Case Builder¶

Overview¶

Parameters¶

Commons¶

Each simulation variable is represented by a Param.

A parameter associates:

• a target identifier
• an optional display name
• a generation strategy configuration

Example:

from studpy.cases import Param
from studpy.cases.configs import LinearConfig

temperature = Param(
    target="temperature",
    name="Temperature",
    config=LinearConfig(
        low=300,
        high=1200,
        size=10,
    ),
)

Available Configuration Types¶

Linear Sampling¶

Generate evenly spaced values between two bounds.

LinearConfig(
    low=0.0,
    high=1.0,
    size=5,
)

Equivalent generated values:

0.00, 0.25, 0.50, 0.75, 1.00

List Sampling¶

Use explicit values.

ListConfig(
    values=[10, 20, 50, 100],
)

Random Integer Sampling¶

Generate random integer values.

RandomIntConfig(
    low=1,
    high=10,
    size=20,
)

Gaussian Sampling¶

Define normally distributed parameters.

GaussianConfig(
    mean=0.0,
    std=1.0,
    size=100,
)

Optional truncation bounds can also be specified.

Latin Hypercube Sampling (LHS)¶

LHS parameters are grouped using a shared reference.

All parameters sharing the same reference are sampled together.

Example:

from studpy.cases.configs import LHSConfig

Param(
    target="pressure",
    config=LHSConfig(
        reference="main_lhs",
        low=1.0,
        high=10.0,
    ),
)

Case Builder¶

Building¶

CaseBuilder combines all parameters and sampling definitions.

Example:

from studpy.cases import CaseBuilder
from studpy.cases.latin_hypercube_sampling import LatinHypercubeSampling

specs = CaseBuilder(
    parameters=parameters,
    lhs={
        "main_lhs": LatinHypercubeSampling(
            n_samples=50,
            random_seed=42,
        )
    },
)

Case Dataset Generation¶

Simulation cases are generated using:

cases = specs.build_cases()

Saving

The result is a pandas.DataFrame where each row represents one simulation case.

Considerations¶

Cartesian Product Expansion¶

Non-LHS parameters are combined using Cartesian products.

For example:

Temperature: 3 values
Pressure:    4 values

produces:

3 × 4 = 12 cases

Reproducibility¶

Sampling reproducibility can be controlled using random seeds.

Example:

LatinHypercubeSampling(
    n_samples=100,
    random_seed=42,
)

Best Practices¶

Use explicit parameter names¶

Prefer:

name="Temperature"

instead of relying on automatic column naming.

Group correlated LHS variables¶

Parameters sampled together should share the same reference.

Limit Cartesian explosion¶

Cartesian combinations can grow very quickly.

Use: - LHS - random sampling - reduced parameter sets

when exploring large parameter spaces.