antupy.Parametric#

class antupy.Parametric(base_case: Simulation | Plant, params_in: Mapping[str, Array | Iterable[str | int | float]], params_out: list[str] = [], save_results_detailed: bool = False, dir_output: Path | str | None = None, path_results: Path | str | None = None, include_gitignore: bool = False, isolation_mode: str = 'reuse', verbose: bool = True)[source]#

Enhanced parametric analysis manager with full unit tracking. This class handles the setup, execution, and management of parametric studies where multiple input parameters are varied systematically to explore their effects on simulation outputs. Results are stored in a Frame.

Parameters:

  • base_case (Simulation or Plant) – Base simulation or plant object to use as template for all parametric runs. This object will be deep-copied for each simulation case.

  • params_in (dict[str, Array or Iterable]) – Dictionary mapping parameter names to their value ranges. Keys are parameter names (support dot notation for nested attributes). Values can be Array objects with units or iterables of values.

  • params_out (list[str], optional) – List of output parameter names to extract from simulation results. If empty list (default), all available outputs will be extracted.

  • save_results_detailed (bool, optional) – Whether to save detailed simulation objects as pickle files. Default is False to save disk space.

  • dir_output (Path, str, or None, optional) – Directory path to save detailed simulation results. Created automatically if it doesn’t exist. Default is None.

  • path_results (Path, str, or None, optional) – File path for saving summary results CSV after each simulation. Enables incremental saving for long-running studies. Default is None.

  • include_gitignore (bool, optional) – Whether to create a .gitignore file in dir_output to ignore .plk files. Default is False. Only applies when dir_output is specified.

  • isolation_mode (str, optional) – Simulation isolation mode. Options: - ‘reuse’ (default): Reuses the same base_case instance across simulations. - ‘deepcopy’: Each simulation uses a deep copy of base_case. Guarantees complete isolation but slower performance. Use if run_simulation() has side effects or modifies internal state.

  • verbose (bool, optional) – Whether to print progress information during analysis. Default is True.

base_case#

The base simulation template object.

Type:

Simulation or Plant

params_in#

Input parameters dictionary as provided during initialization.

Type:

dict[str, Array or Iterable]

params_out#

Output parameters to extract from simulation results.

Type:

list[str]

save_results_detailed#

Flag indicating whether to save detailed simulation objects.

Type:

bool

dir_output#

Directory for saving detailed simulation results.

Type:

Path or None

path_results#

File path for saving incremental CSV results.

Type:

Path or None

verbose#

Flag for progress information printing.

Type:

bool

cases#

Frame containing all input parameter combinations to analyze. Created by setup_cases() method with units preserved.

Type:

Frame or None

results#

Complete results Frame with input parameters and output metrics. Available after successful run_analysis() execution with units.

Type:

Frame or None

Examples

Basic parametric study with units preserved:

>>> from antupy.analyser.par import Parametric
>>> from antupy.array import Array
>>>
>>> # Define parameter ranges with units
>>> params_in = {
...     'temperature': Array([20, 25, 30], '°C'),
...     'flow_rate': Array([0.1, 0.2, 0.3], 'm3/s')
... }
>>>
>>> # Create and run analysis
>>> study = Parametric(
...     base_case=my_simulation,
...     params_in=params_in,
...     params_out=['efficiency', 'cost']
... )
>>> results = study.run_analysis()  # Returns ap.Frame with units
>>>
>>> # Access results with units
>>> efficiency_array = results.get_values('efficiency')  # Array with units
>>> all_outputs = results.get_values(['efficiency', 'cost'])  # Dict of Arrays
__init__(base_case: Simulation | Plant, params_in: Mapping[str, Array | Iterable[str | int | float]], params_out: list[str] = [], save_results_detailed: bool = False, dir_output: Path | str | None = None, path_results: Path | str | None = None, include_gitignore: bool = False, isolation_mode: str = 'reuse', verbose: bool = True)[source]#
Parameters:

Methods

__init__(base_case, params_in[, params_out, ...])

get_output_arrays(...)

Get analysis results as Array objects with units preserved.

get_summary()

Generate summary of parametric analysis results.

run_analysis()

Execute parametric analysis with configured input parameters.

setup_cases(params_in)

Create parametric run matrix from input parameters as ap.Frame.