Batch¶

Core Concept¶

A Batch is responsible for executing a collection of simulation runs.

Each run is identified by an integer index:

Run 0 \ Run 1 \ ...
Run N

For each run, the Batch determines:

• what command should be executed
• what preparation is required before execution
• what processing is required after execution

Execution Lifecycle¶

A Batch progresses through several phases for each run:

1. Preparation — setup work before execution (create directories, write inputs)
2. Execution — run the command
3. Validation — verify simulation outputs exist and are valid
4. Post-Processing — collect results, compute metrics, generate reports

Core Components¶

BatchExecCmdIter¶

The BatchExecCmdIter class manages batch execution and coordinates the full lifecycle.

See API BatchExecCmdIter

InputsBuilder¶

Prepares simulation inputs for each case before execution.

Example:

from studpy.batch import OneFileInputsBuilder

inputs_builder = OneFileInputsBuilder(
    template_path="inputs/template.txt",
    output_dir="runs",
)

See API OneFileInputsBuilder

Execution Modes¶

Sequential Execution¶

Run simulations one at a time:

batch.execute_sequential()

Useful for: - Single-core systems - Debugging - I/O constrained problems

Parallel Execution¶

Run multiple simulations concurrently:

batch.execute_parallel(max_workers=4)

Useful for: - Multi-core systems - Independent simulations - Reducing total execution time

Configuration¶

Progress Reporting¶

Monitor execution progress in real-time:

batch.execute_sequential(
    show_progress=True,
    progress_interval=10,  # Update every 10 runs
)

Error Handling¶

Control behavior when simulations fail:

batch.execute_sequential(
    stop_on_error=False,  # Continue after failures
    log_errors=True,
)

Output Validation¶

Verify simulation outputs before collection:

batch.validate_outputs(
    required_files=["output.txt", "results.json"],
    check_file_size=True,
)

Best Practices¶

Start with sequential execution¶

Debug inputs and command configuration before parallelizing.

Validate early¶

Test your InputsBuilder on a small subset before full batch execution.

Use consistent naming¶

Structure output directories consistently across all runs:

runs/
├── run_0/
│   ├── inputs.txt
│   └── output.txt
├── run_1/
│   ├── inputs.txt
│   └── output.txt

Monitor resource usage¶

Adjust max_workers based on available system memory and CPU.

Collect intermediate results¶

Enable result collection at regular intervals to avoid data loss on failure.

Typical Workflow¶

1. Build CaseBuilder with parameter definitions
2. Generate cases dataset
3. Create InputsBuilder for case preparation
4. Initialize BatchExecCmdIter with execution command
5. Execute batch (sequential or parallel)
6. Validate outputs
7. Aggregate results