TmpInputsBuilder Example¶

Purpose¶

This example demonstrates how to use TmpInputsBuilder to generate simulation cases from an existing template directory.

This workflow is common for Fortran-based simulators where:

• the simulation input is part of a larger folder structure;
• a template directory already exists;
• only a few values inside an input file need to be modified for each run.

Instead of generating a new file from scratch, TmpInputsBuilder:

1. Copies the entire template directory.
2. Creates a dedicated run folder.
3. Modifies configured values inside a target .tmp file.

Initial Template¶

Suppose the simulation expects the following structure:

template/
├── INI/
│   └── init_mod.tmp
├── POST/
├── ...
└── OUT/

with an input file containing values followed by labels:

68.7      Pression interne initiale (bar abs.)
15.0      Vitesse du vent (m/s)

The labels remain unchanged while the numeric values are replaced.

Create the Inputs Builder¶

from pathlib import Path

from studpy.inputs import (
    TmpInputsBuilder,
    ParameterConfig,
)

inputs_builder = TmpInputsBuilder(
    output_folder=Path("Runs"),
    template_dir=Path("template"),

    ini_subdir="INI",
    ini_filename="init_mod.tmp",

    parameters=[
        ParameterConfig(
            name="pressure",
            low=10.0,
            high=100.0,
            ini_label="Pression interne initiale (bar abs.)",
        ),
        ParameterConfig(
            name="wind_speed",
            low=1.0,
            high=20.0,
            ini_label="Vitesse du vent (m/s)",
        ),
    ],
)

Define the Cases¶

In this example, two parameters are sampled using Latin Hypercube Sampling.

from studpy.cases import (
    Param,
    LHSConfig,
    CaseBuilder,
    LatinHypercubeSampling,
)

LHS_REF = "main"

parameters = [
    Param(
        input_path="pressure",
        name="pressure",
        config=LHSConfig(
            low=10.0,
            high=100.0,
            reference=LHS_REF,
        ),
    ),
    Param(
        input_path="wind_speed",
        name="wind_speed",
        config=LHSConfig(
            low=1.0,
            high=20.0,
            reference=LHS_REF,
        ),
    ),
]

lhs = LatinHypercubeSampling(
    n_samples=5,
    random_seed=42,
)

case_builder = CaseBuilder(
    parameters=parameters,
    lhs={
        LHS_REF: lhs,
    },
)

Create the Study¶

from studpy.study import Study

study = Study(
    case_builder=case_builder,
    inputs_builder=inputs_builder,
)

Generate Inputs¶

for i in range(study.cases_count()):
    study.case_build_inputs(i)

Generated Structure¶

After generation:

Runs/
├── run_001/
│   ├── INI/
│   │   └── init_mod.tmp
│   ├── POST/
│   └── OUT/
│
├── run_002/
│   ├── INI/
│   │   └── init_mod.tmp
│   ├── POST/
│   └── OUT/
│
└── ...

Each run contains a complete copy of the original template.

Patched Input Example¶

Original:

68.7      Pression interne initiale (bar abs.)
15.0      Vitesse du vent (m/s)

Generated run:

82.3      Pression interne initiale (bar abs.)
7.4       Vitesse du vent (m/s)

Only the numeric values are modified.

The labels remain unchanged.

Linked Parameters¶

Some simulation codes require the same value to appear in multiple locations.

ini_linked allows a parameter to update several labels simultaneously.

ParameterConfig(
    name="flowrate",
    low=10.0,
    high=100.0,
    ini_label="Débit 1 (initial) (m3(n)/s)",
    ini_linked=[
        "Débit 2 (intermédiaire) (m3(n)/s)",
        "Débit 3 (final) (m3(n)/s)",
    ],
)

When flowrate changes, all three labels receive the same value.

Typical Use Cases¶

TmpInputsBuilder is intended for simulations that already rely on a directory-based input structure:

• Fortran solvers
• CFD codes
• Combustion models
• Risk assessment tools
• Legacy engineering software
• RAYOT-style workflows

Whenever a simulation requires:

template/
├── INI/
├── POST/
├── OUT/
└── ...

and only a few values inside an existing file must be modified, TmpInputsBuilder is usually the simplest solution.