sdom.ParametricStudy#

class sdom.ParametricStudy(base_data: dict, solver_config: dict, n_hours: int = 8760, output_dir: str | None = None, n_cores: int | None = None)[source]#

Run a multi-dimensional parametric sensitivity study in parallel.

Accepts scalar, storage-factor, and time-series sweep definitions, constructs the full Cartesian product of all sweep dimensions, and dispatches each combination to a separate worker process via concurrent.futures.ProcessPoolExecutor.

Parameters:

  • base_data (dict) – SDOM data dictionary returned by sdom.load_data(). This object is never modified; each worker process receives its own deep copy before applying mutations.

  • solver_config (dict) – Solver configuration dict from sdom.get_default_solver_config_dict().

  • n_hours (int, optional) – Number of simulation hours. Defaults to 8760.

  • output_dir (str or None, optional) – Directory where per-case sub-directories and the summary CSV will be written. Pass None to skip all disk output.

  • n_cores (int or None, optional) – Number of worker processes. Capped internally at max(1, os.cpu_count() - 1). Pass None to use the maximum safe count.

Examples

>>> study = ParametricStudy(base_data=data, solver_config=solver_cfg)
>>> study.add_scalar_sweep("scalars", "GenMix_Target", [0.8, 0.9, 1.0])
>>> study.add_ts_sweep("load_data", [0.95, 1.05])
>>> results = study.run()  # 3 × 2 = 6 cases
__init__(base_data: dict, solver_config: dict, n_hours: int = 8760, output_dir: str | None = None, n_cores: int | None = None) → None[source]#

Methods

__init__(base_data, solver_config[, ...])

add_scalar_sweep(data_key, param_name, values)

Register a scalar parameter sweep.

add_storage_factor_sweep(param_name, factors)

Register a multiplicative storage-parameter sweep.

add_ts_sweep(ts_key, factors)

Register a time-series multiplicative sweep.

run()

Execute all parametric combinations in parallel.

Attributes

case_metadata

Per-case metadata populated after run() is called.

output_dir

The root output directory passed to the constructor (may be None).
__init__(base_data: dict, solver_config: dict, n_hours: int = 8760, output_dir: str | None = None, n_cores: int | None = None) → None[source]#
property output_dir: str | None#

The root output directory passed to the constructor (may be None).

property case_metadata: List[dict]#

Per-case metadata populated after run() is called.

Returns a list of dicts, one per case in Cartesian-product order (matching the order of the list returned by run()). Each dict contains:

  • "case_name" — filesystem-safe case identifier

  • "case_index" — zero-based position in the Cartesian product

  • One additional key per registered sweep dimension, using the param_name (scalar / storage-factor sweeps) or ts_key (time-series sweeps) as the key, and the swept value as the value.

Returns an empty list before run() is called.

add_scalar_sweep(data_key: str, param_name: str, values: list) → None[source]#

Register a scalar parameter sweep.

Each value in values replaces data[data_key].loc[param_name, "Value"] for one case dimension.

Parameters:

  • data_key (str) – Key in the SDOM data dict (e.g. "scalars").

  • param_name (str) – Row label of the parameter (e.g. "GenMix_Target").

  • values (list of float) – Discrete values to sweep over.

add_storage_factor_sweep(param_name: str, factors: list) → None[source]#

Register a multiplicative storage-parameter sweep.

Each factor scales the entire data["storage_data"].loc[param_name] row (all storage technologies) uniformly.

Parameters:

  • param_name (str) – Row label in data["storage_data"] (e.g. "P_Capex").

  • factors (list of float) – Multiplicative factors to apply.

add_ts_sweep(ts_key: str, factors: list) → None[source]#

Register a time-series multiplicative sweep.

Each factor scales the numeric column of data[ts_key]. The column name is resolved automatically from sdom.parametric.mutations.TS_KEY_TO_COLUMN.

Parameters:

  • ts_key (str) – Key in the SDOM data dict (e.g. "load_data").

  • factors (list of float) – Multiplicative scaling factors.

run() → List[OptimizationResults][source]#

Execute all parametric combinations in parallel.

Constructs the Cartesian product of all registered sweeps, submits every case to a ProcessPoolExecutor, reports progress as jobs complete, exports per-case CSVs (if output_dir was specified), and writes a summary CSV.

Returns:

One entry per combination, in Cartesian-product order (matching the order cases were submitted). Cases that failed have is_optimal == False and a descriptive termination_condition.

Return type:

list of OptimizationResults