tud_lbm.config.array_expansion
==============================

.. py:module:: tud_lbm.config.array_expansion

.. autoapi-nested-parse::

   Array parameter expansion for parallel simulations.

   Detects array-valued parameters in configuration and expands them into
   multiple :class:`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
----------

.. autoapisummary::

   tud_lbm.config.array_expansion.GRID_SHAPE_TUPLE_LEN


Classes
-------

.. autoapisummary::

   tud_lbm.config.array_expansion.ArrayParameterSet


Functions
---------

.. autoapisummary::

   tud_lbm.config.array_expansion.detect_array_fields
   tud_lbm.config.array_expansion.expand_config
   tud_lbm.config.array_expansion.enumerate_configs


Module Contents
---------------

.. py:data:: GRID_SHAPE_TUPLE_LEN
   :value: 2


.. py:class:: ArrayParameterSet

   Metadata about which fields had arrays in the original config.

   .. attribute:: field_names

      Names of fields that contained arrays.

   .. attribute:: array_values

      Mapping from field name to the array of values.

   .. attribute:: total_combinations

      Total number of config combinations generated.


   .. py:attribute:: field_names
      :type:  frozenset[str]


   .. py:attribute:: array_values
      :type:  dict[str, tuple[Any, Ellipsis]]


   .. py:attribute:: total_combinations
      :type:  int


.. py:function:: 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.

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

   :returns: :class:`ArrayParameterSet` describing detected arrays, or None
             if no arrays were found.


.. py:function:: 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.

   :param config_dict: Raw configuration dict (typically from TomlAdapter
                       before SimulationConfig instantiation).
   :param allow_arrays: If False, raise ValueError if arrays are found.

   :returns:

             - *configs*: List of :class:`SimulationConfig` objects (one per
               combination). If no arrays found, list contains single config.
             - *metadata*: :class:`ArrayParameterSet` if arrays were detected,
               else None.
   :rtype: ``(configs, metadata)`` where

   :raises ValueError: If arrays are found but *allow_arrays* is False.
   :raises TypeError: If array values contain incompatible types.


.. py:function:: 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"``).

   :param config_dict: Raw configuration dict.
   :param 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 :class:`SimulationConfig`.