tud_lbm.config.simulation_config
================================

.. py:module:: tud_lbm.config.simulation_config

.. autoapi-nested-parse::

   Validated, serialisable simulation configuration for TUD-LBM.

   :class:`SimulationConfig` is a **frozen** Python dataclass used for
   parsing, validation, and serialisation. It never enters a JIT boundary.

   Usage::

       from config.simulation_config import SimulationConfig

       cfg = SimulationConfig(
           grid_shape=(128, 128, 1),
           tau=0.8,
           nt=5000,
           collision_scheme="bgk",
       )



Attributes
----------

.. autoapisummary::

   tud_lbm.config.simulation_config.CONFIG_SECTION
   tud_lbm.config.simulation_config.ARRAY_ELIGIBLE
   tud_lbm.config.simulation_config.NESTED_SWEEPABLE
   tud_lbm.config.simulation_config.MIN_GRID_DIMENSIONS
   tud_lbm.config.simulation_config.MIN_TAU_VALUE


Classes
-------

.. autoapisummary::

   tud_lbm.config.simulation_config.SimulationConfig


Functions
---------

.. autoapisummary::

   tud_lbm.config.simulation_config.array_field
   tud_lbm.config.simulation_config.get_array_eligible_fields
   tud_lbm.config.simulation_config.get_nested_sweepable_fields
   tud_lbm.config.simulation_config.get_fields_for_section


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

.. py:data:: CONFIG_SECTION
   :type:  str
   :value: 'config_section'


.. py:data:: ARRAY_ELIGIBLE
   :type:  str
   :value: 'array_eligible'


.. py:data:: NESTED_SWEEPABLE
   :type:  str
   :value: 'nested_sweepable'


.. py:data:: MIN_GRID_DIMENSIONS
   :type:  int
   :value: 2


.. py:data:: MIN_TAU_VALUE
   :type:  float
   :value: 0.5


.. py:function:: array_field(*, default: object = dataclasses.MISSING, default_factory: object = dataclasses.MISSING, section: str | None = None, nested_sweepable: bool = False, **kwargs: object) -> dataclasses.field

   Field factory for array-eligible SimulationConfig fields.

   :param default: Default value for the field.
   :param default_factory: Default factory function for the field.
   :param section: Config section name for serialisation routing.
   :param nested_sweepable: If ``True``, sub-keys inside this dict field
                            will also be inspected for list values during Cartesian-product
                            expansion (e.g. ``gravity_force``, ``wetting_config``).
   :param \*\*kwargs: Additional keyword arguments passed to the field factory.

   :returns: A dataclass field with array-eligible metadata.


.. py:class:: SimulationConfig

   Validated, serialisable simulation configuration for TUD-LBM.

   This frozen dataclass is used for parsing, validation, and serialisation.
   It never enters a JIT boundary and serves as the configuration container
   for all simulation parameters including grid, collision, boundary conditions,
   and output settings.


   .. py:attribute:: sim_type
      :type:  Literal['single_phase', 'multiphase', 'multiphase_wetting', 'multiphase_hysteresis', 'multiphase_hysteresis_chemical_step']
      :value: 'single_phase'



   .. py:attribute:: simulation_name
      :type:  str | None
      :value: None



   .. py:attribute:: lattice_type
      :type:  str
      :value: 'D2Q9'



   .. py:attribute:: grid_shape
      :type:  tuple[int, Ellipsis]


   .. py:attribute:: nt
      :type:  int


   .. py:attribute:: tau
      :type:  float


   .. py:attribute:: collision_scheme
      :type:  str


   .. py:attribute:: k_diag
      :type:  tuple[float, Ellipsis] | None


   .. py:attribute:: bc_config
      :type:  dict[str, Any] | None
      :value: None



   .. py:attribute:: wetting_config
      :type:  dict[str, Any] | None


   .. py:attribute:: hysteresis_config
      :type:  dict[str, Any] | None


   .. py:attribute:: chemical_step_config
      :type:  dict[str, Any] | None


   .. py:attribute:: gravity_force
      :type:  dict[str, Any] | None


   .. py:attribute:: electric_force
      :type:  dict[str, Any] | None


   .. py:attribute:: gravity_masked_force
      :type:  dict[str, Any] | None


   .. py:attribute:: init_type
      :type:  str
      :value: 'standard'



   .. py:attribute:: init_dir
      :type:  str | None
      :value: None



   .. py:attribute:: initialisation
      :type:  dict[str, Any]


   .. py:attribute:: results_dir
      :type:  str
      :value: ''



   .. py:attribute:: save_interval
      :type:  int
      :value: 0



   .. py:attribute:: skip_interval
      :type:  int
      :value: 0



   .. py:attribute:: save_fields
      :type:  list[str] | None
      :value: None



   .. py:attribute:: plot_fields
      :type:  list[str] | None
      :value: None



   .. py:attribute:: animate_fields
      :type:  list[str] | None
      :value: None



   .. py:attribute:: output_format
      :type:  str | list[str] | None
      :value: 'numpy'



   .. py:attribute:: output_dir
      :type:  str | None
      :value: None



   .. py:attribute:: eos
      :type:  str | None


   .. py:attribute:: kappa
      :type:  float | None


   .. py:attribute:: rho_l
      :type:  float | None


   .. py:attribute:: rho_v
      :type:  float | None


   .. py:attribute:: interface_width
      :type:  int | None


   .. py:attribute:: g
      :type:  float | None


   .. py:attribute:: extra
      :type:  dict[str, Any]


   .. py:method:: __post_init__() -> None

      Validate and normalize configuration after initialization.



   .. py:property:: is_single_phase
      :type: bool


      Check if simulation is single-phase.


   .. py:property:: is_multiphase
      :type: bool


      Check if simulation is multiphase.


   .. py:property:: force_enabled
      :type: bool


      Check if any force field is populated.


   .. py:method:: to_dict() -> dict[str, Any]

      Convert configuration to dictionary format.



   .. py:method:: __repr__() -> str

      Return string representation of SimulationConfig.



.. py:function:: get_array_eligible_fields() -> frozenset[str]

   Get names of fields eligible for array expansion in configuration sweeps.


.. py:function:: get_nested_sweepable_fields() -> frozenset[str]

   Return field names whose dict sub-keys may carry list sweep values.


.. py:function:: get_fields_for_section(section: str) -> frozenset[str]

   Get field names belonging to a specific configuration section.