laurel.scenario_builders package

Submodules

laurel.scenario_builders.batt_dual_pow module

class laurel.scenario_builders.batt_dual_pow.BatteryDualPowerScenarioBuilder(scen_params, all_params, catalog)[source]

Bases: ScenarioBuilder

Create scenarios which scan across battery sizes and charging powers.

partition_level_names = ('run_name', 'batt_kwh', 'depot_kw', 'tstop_kw', 'task_id')

class laurel.scenario_builders.batt_dual_pow.BatteryDualPowerScenarioReader(dirs=None)[source]

Bases: ScenarioReader

Read scenarios which scan across battery sizes and management strategies.

builder: alias of BatteryDualPowerScenarioBuilder

extract_metadata(path)[source]

Parse scenario-identifying metadata from a partition path.

Return values must correspond in order with metadata_level_names.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: tuple
Returns:: Tuple of metadata values (strings or scalars) in the same order as metadata_level_names.

metadata_level_names: tuple[str] = ('batt_kwh', 'depot_kw', 'tstop_kw')

name_scenario(path)[source]

Convert a partition path to a human-readable scenario label.

The helper concat_name_components() is typically useful for formatting the label from path components.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: str
Returns:: Human-readable scenario name string added to the combined DataFrame under the scenario_name column.

laurel.scenario_builders.batt_man module

class laurel.scenario_builders.batt_man.BatteryManageScenarioBuilder(scen_params, all_params, catalog)[source]

Bases: ScenarioBuilder

Create scenarios which scan across battery sizes and management strategies.

partition_level_names = ('run_name', 'batt_kwh', 'charge_management', 'task_id')

class laurel.scenario_builders.batt_man.BatteryManageScenarioReader(dirs=None)[source]

Bases: ScenarioReader

Read scenarios which scan across battery sizes and management strategies.

builder: alias of BatteryManageScenarioBuilder

extract_metadata(path)[source]

Parse scenario-identifying metadata from a partition path.

Return values must correspond in order with metadata_level_names.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: tuple
Returns:: Tuple of metadata values (strings or scalars) in the same order as metadata_level_names.

metadata_level_names: tuple[str] = ('batt_kwh', 'charge_management')

name_scenario(path)[source]

Convert a partition path to a human-readable scenario label.

The helper concat_name_components() is typically useful for formatting the label from path components.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: str
Returns:: Human-readable scenario name string added to the combined DataFrame under the scenario_name column.

laurel.scenario_builders.batt_pow module

class laurel.scenario_builders.batt_pow.BatteryPowerScenarioBuilder(scen_params, all_params, catalog)[source]

Bases: ScenarioBuilder

Create scenarios which scan across battery sizes and charging powers.

partition_level_names = ('run_name', 'batt_kwh', 'depot_kw', 'is_mandate_active', 'task_id')

class laurel.scenario_builders.batt_pow.BatteryPowerScenarioReader(dirs=None)[source]

Bases: ScenarioReader

Read scenarios which scan across battery sizes and management strategies.

builder: alias of BatteryPowerScenarioBuilder

extract_metadata(path)[source]

Parse scenario-identifying metadata from a partition path.

Return values must correspond in order with metadata_level_names.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: tuple
Returns:: Tuple of metadata values (strings or scalars) in the same order as metadata_level_names.

metadata_level_names: tuple[str] = ('batt_kwh', 'depot_kw', 'is_mandate_active')

name_scenario(path)[source]

Convert a partition path to a human-readable scenario label.

The helper concat_name_components() is typically useful for formatting the label from path components.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: str
Returns:: Human-readable scenario name string added to the combined DataFrame under the scenario_name column.

laurel.scenario_builders.ca_eight module

class laurel.scenario_builders.ca_eight.CalifClass8ScenarioBuilder(scen_params, all_params, catalog)[source]

Bases: ScenarioBuilder

Build scenarios for the California Class 8 truck model.

partition_level_names = ('run_name', 'range_mi', 'depot_kw', 'enroute_kw', 'charge_management', 'task_id')

class laurel.scenario_builders.ca_eight.CalifClass8ScenarioReader(dirs=None)[source]

Bases: ScenarioReader

Read scenarios for the California Class 8 truck model.

builder: alias of CalifClass8ScenarioBuilder

extract_metadata(path)[source]

Parse scenario-identifying metadata from a partition path.

Return values must correspond in order with metadata_level_names.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: tuple
Returns:: Tuple of metadata values (strings or scalars) in the same order as metadata_level_names.

metadata_level_names: tuple[str] = ('range_mi', 'depot_kw', 'enroute_kw', 'charge_management')

name_scenario(path)[source]

Convert a partition path to a human-readable scenario label.

The helper concat_name_components() is typically useful for formatting the label from path components.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: str
Returns:: Human-readable scenario name string added to the combined DataFrame under the scenario_name column.

laurel.scenario_builders.ca_eight.multiply_dict_leaves(d, scalar)[source]: Multiply all leaf values in a dictionary by a scalar.

laurel.scenario_builders.ca_eight_adopt module

class laurel.scenario_builders.ca_eight_adopt.CalifClass8AdoptionScenarioBuilder(scen_params, all_params, catalog)[source]

Bases: ScenarioBuilder

Build scenarios for the California Class 8 truck model.

partition_level_names = ('run_name', 'adopt_pct', 'range_mi', 'depot_kw', 'enroute_kw', 'charge_management', 'task_id')

class laurel.scenario_builders.ca_eight_adopt.CalifClass8AdoptionScenarioReader(dirs=None)[source]

Bases: ScenarioReader

Read scenarios for the California Class 8 truck model.

builder: alias of CalifClass8AdoptionScenarioBuilder

extract_metadata(path)[source]

Parse scenario-identifying metadata from a partition path.

Return values must correspond in order with metadata_level_names.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: tuple
Returns:: Tuple of metadata values (strings or scalars) in the same order as metadata_level_names.

metadata_level_names: tuple[str] = ('adopt_pct', 'range_mi', 'depot_kw', 'enroute_kw', 'charge_management')

name_scenario(path)[source]

Convert a partition path to a human-readable scenario label.

The helper concat_name_components() is typically useful for formatting the label from path components.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: str
Returns:: Human-readable scenario name string added to the combined DataFrame under the scenario_name column.

laurel.scenario_builders.ca_eight_adopt.multiply_dict_leaves(d, scalar)[source]: Multiply all leaf values in a dictionary by a scalar.

laurel.scenario_builders.ranger module

class laurel.scenario_builders.ranger.RangeScenarioBuilder(scen_params, all_params, catalog)[source]

Bases: ScenarioBuilder

Create scenarios which scan across battery sizes and charging powers.

partition_level_names = ('run_name', 'range_mi', 'task_id')

class laurel.scenario_builders.ranger.RangeScenarioReader(dirs=None)[source]

Bases: ScenarioReader

Read scenarios which scan across battery sizes and management strategies.

builder: alias of RangeScenarioBuilder

extract_metadata(path)[source]

Parse scenario-identifying metadata from a partition path.

Return values must correspond in order with metadata_level_names.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: tuple
Returns:: Tuple of metadata values (strings or scalars) in the same order as metadata_level_names.

metadata_level_names: tuple[str] = ('range_mi',)

name_scenario(path)[source]

Convert a partition path to a human-readable scenario label.

The helper concat_name_components() is typically useful for formatting the label from path components.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: str
Returns:: Human-readable scenario name string added to the combined DataFrame under the scenario_name column.

laurel.scenario_builders.scale_test module

class laurel.scenario_builders.scale_test.ScaleTestScenarioBuilder(scen_params, all_params, catalog)[source]

Bases: ScenarioBuilder

Build scenarios for the scaling test truck model.

partition_level_names = ('run_name', 'sample_source', 'task_id')

class laurel.scenario_builders.scale_test.ScaleTestScenarioReader(dirs=None)[source]

Bases: ScenarioReader

Read scenarios for the scaling test truck model.

builder: alias of ScaleTestScenarioBuilder

extract_metadata(path)[source]

Parse scenario-identifying metadata from a partition path.

Return values must correspond in order with metadata_level_names.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: tuple
Returns:: Tuple of metadata values (strings or scalars) in the same order as metadata_level_names.

metadata_level_names: tuple[str] = ('sample_source',)

name_scenario(path)[source]

Convert a partition path to a human-readable scenario label.

The helper concat_name_components() is typically useful for formatting the label from path components.

Parameters:: path (Path) – Path object for a completed partition file.
Return type:: str
Returns:: Human-readable scenario name string added to the combined DataFrame under the scenario_name column.

laurel.scenario_builders.sense module

Scenario builder and reader for sensitivity analyses with mixed variable types.

Supports sensitivity designs that combine categorical variables (enumerated discrete choices, e.g. charging-manager strategy) with continuous variables sampled via a Sobol’ quasi-random sequence (e.g. adoption rates, energy consumption rates). The full scenario space is the Cartesian product of all categorical combinations and all Sobol samples, giving n_categ_combos × sample_size total scenarios.

Classes

SenseScenarioBuilder: Constructs scenario parameter dicts for HPC batch execution.
SenseScenarioReader: Parses scenario paths back into metadata for cross-scenario aggregation.

Key design decisions

Categorical × continuous product: Crossing every categorical combination with every Sobol draw ensures that the full continuous parameter space is explored independently for each discrete configuration — important when categorical choices interact with continuous parameters (e.g. charging strategy interacts with charging speed).
Graceful empty-set handling: If params_sampl is empty (all variables are categorical), samples_list = [{}] keeps the loop structure uniform and avoids passing a zero-dimension distribution to OpenTURNS. If params_categ is empty (all variables are continuous), product(*[]) yields one empty tuple, so categ_combos = [{}] and the full Sobol sample is iterated without modification.
Path-based parameter override: Each variable definition includes a path key — a list of dict keys that locates the variable inside the Kedro parameter hierarchy. SenseScenarioBuilder._set_param() navigates this path to mutate a deep-copied base parameter dict, ensuring no two scenarios share mutable state.
Copula structure: Correlations among continuous variables (e.g. adoption rates that are jointly drawn from a Gaussian copula fit to NLR scenarios) are specified as a separate copulas block in the scenario config. Independent variables are assigned an IndependentCopula automatically, and all copulas are combined into a BlockIndependentCopula.

References

Passow, F., & Rajagopal, R. (2026). Identifying indicators to inform proactive substation upgrades for charging electric heavy-duty trucks. Applied Energy.

class laurel.scenario_builders.sense.SenseScenarioBuilder(scen_params, all_params, catalog)[source]

Bases: ScenarioBuilder

Build scenario parameter dicts for sensitivity analyses with mixed variable types.

Partitions the variables defined in scenario_params["variables"] into categorical variables (enumerated via itertools.product()) and continuous variables (sampled via a Sobol’ low-discrepancy sequence). The full scenario space is the Cartesian product of the two sets.

static build_input_dist(vars, copulas)[source]

Build the joint input distribution for continuous sensitivity variables.

Constructs an JointDistribution from marginal distributions and an optional block-independent copula structure:

For each variable in vars, instantiate the named OpenTURNS distribution (e.g. ot.Beta, ot.Uniform) using the params values in order of their definition, and label it with the variable name.
If copulas is provided, build one copula per entry (currently NormalCopula and StudentCopula are supported). Each copula entry specifies a correlation sub-dict parsed by correl_dict_to_matrix(). Variables not assigned to any copula block are collected into an IndependentCopula. All copulas are combined into a BlockIndependentCopula.
If no copulas are provided, the marginals are assembled with no dependence structure (independent joint distribution).

Parameters:

vars (dict) –
Ordered dict mapping variable names to distribution specifications. Each value must have:
- dist (str): OpenTURNS distribution class name.
- params (dict): Keyword-argument values passed positionally to the distribution constructor; order matters.
copulas (list[dict] | None) – List of copula specification dicts, each with a single key naming the copula type ("NormalCopula" or "StudentCopula") and a value containing a correlation sub-dict. Pass None for independent marginals.

Return type:

JointDistribution

Returns:

JointDistribution combining the specified marginals and copula structure.

Raises:

ValueError – If a copula entry is not a dict, or if copula variable names are not a subset of the marginal variable names.
NotImplementedError – If a copula type other than NormalCopula or StudentCopula is requested.

partition_level_names = ('run_name', 'task_id')

class laurel.scenario_builders.sense.SenseScenarioReader(dirs=None)[source]

Bases: ScenarioReader

Read and index scenarios produced by SenseScenarioBuilder.

Parses the integer task ID from each scenario’s path metadata, which is used downstream to order scenarios and join cross-scenario aggregations.

builder: alias of SenseScenarioBuilder

extract_metadata(path)[source]

Extract the numeric task ID from a scenario path.

Parameters:: path (Path) – Scenario path as returned by the builder.
Return type:: tuple
Returns:: One-tuple (task_id,) where task_id is the integer parsed from the task_<N> segment of the path metadata.

metadata_level_names: tuple[str] = ('task_id',)

name_scenario(path)[source]

Return the integer task ID as the canonical scenario name.

Parameters:: path (Path) – Scenario path as returned by the builder.
Return type:: str
Returns:: Integer task ID parsed from the path metadata.

Module contents

Concrete ScenarioBuilder subclasses for LAUREL scenario generation.

Importing this package registers all bundled builders in _registry, making them available to generate_scenario_configs() without any further configuration.