tud_lbm.config.array_expansion

Array parameter expansion for parallel simulations.

Detects array-valued parameters in configuration and expands them into multiple SimulationConfig objects for parallel execution.

Example usage:

from config.adapter_toml import TomlAdapter
from config.array_expansion import detect_array_fields, expand_config

# Load config (arrays are preserved in raw form)
adapter = TomlAdapter()
raw_config = adapter.load("config_parallel.toml", allow_arrays=True)

# Detect which fields have arrays
array_fields = detect_array_fields(raw_config)

# Expand into multiple configs
configs = expand_config(raw_config)
# Returns: [SimulationConfig(...), SimulationConfig(...), ...]

Attributes

GRID_SHAPE_TUPLE_LEN

Classes

ArrayParameterSet

Metadata about which fields had arrays in the original config.

Functions

detect_array_fields(→ ArrayParameterSet | None)	Detect which fields in a config contain array values.
expand_config(...)	Expand a config dict with array fields into multiple configs.
enumerate_configs(...)	Yield (index, parameters, config) tuples for each expansion.

Module Contents

tud_lbm.config.array_expansion.GRID_SHAPE_TUPLE_LEN = 2

class tud_lbm.config.array_expansion.ArrayParameterSet

Metadata about which fields had arrays in the original config.

field_names

Names of fields that contained arrays.

array_values

Mapping from field name to the array of values.

total_combinations

Total number of config combinations generated.

field_names: frozenset[str]

array_values: dict[str, tuple[Any, Ellipsis]]

total_combinations: int

tud_lbm.config.array_expansion.detect_array_fields(_config: tud_lbm.config.simulation_config.SimulationConfig) → ArrayParameterSet | None

Detect which fields in a config contain array values.

Returns None if no arrays are present.

Parameters:

_config – A SimulationConfig (should only contain scalars after full expansion; this is more for validation/inspection).

Returns:

ArrayParameterSet describing detected arrays, or None if no arrays were found.

tud_lbm.config.array_expansion.expand_config(config_dict: dict[str, Any], *, allow_arrays: bool = True) → tuple[list[tud_lbm.config.simulation_config.SimulationConfig], ArrayParameterSet | None]

Expand a config dict with array fields into multiple configs.

Performs Cartesian product expansion over:

• Top-level ARRAY_ELIGIBLE_FIELDS that carry a list value.

• Sub-keys inside NESTED_SWEEPABLE_FIELDS dicts (gravity_force, electric_force, wetting_config, hysteresis_config) that carry a list value.

Parameters:

• config_dict – Raw configuration dict (typically from TomlAdapter before SimulationConfig instantiation).

• allow_arrays – If False, raise ValueError if arrays are found.

Returns:

• configs: List of SimulationConfig objects (one per combination). If no arrays found, list contains single config.

• metadata: ArrayParameterSet if arrays were detected, else None.

Return type:

(configs, metadata) where

Raises:

• ValueError – If arrays are found but allow_arrays is False.

• TypeError – If array values contain incompatible types.

tud_lbm.config.array_expansion.enumerate_configs(config_dict: dict[str, Any], *, allow_arrays: bool = True) → collections.abc.Iterator[tuple[int, dict[str, Any], tud_lbm.config.simulation_config.SimulationConfig]]

Yield (index, parameters, config) tuples for each expansion.

parameters uses dotted-path keys for nested fields (e.g. "gravity_force.inclination_angle_deg").

Parameters:

• config_dict – Raw configuration dict.

• allow_arrays – If False, raise ValueError if arrays are found.

Yields:

(index, parameters, config) tuples where –

• index: 0-based position in the expansion.

• parameters: Dict of parameter names and values for this combo.

• config: The SimulationConfig.