tud_lbm.config.adapter_toml
===========================

.. py:module:: tud_lbm.config.adapter_toml

.. autoapi-nested-parse::

   TOML configuration file adapter.

   Reads and writes ``.toml`` config files.

   Requires Python ≥ 3.11 (``tomllib`` in stdlib) **or** the ``tomli``
   back-port on Python 3.10::

       pip install tomli

   Example usage::

       from config.adapter_toml import TomlAdapter

       adapter = TomlAdapter()
       config = adapter.load("example_for_test/config_simple.toml")
       adapter.save(config, "output/config.toml")



Attributes
----------

.. autoapisummary::

   tud_lbm.config.adapter_toml.tomli_w


Classes
-------

.. autoapisummary::

   tud_lbm.config.adapter_toml.TomlAdapter


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

.. py:data:: tomli_w
   :value: None


.. py:class:: TomlAdapter

   Bases: :py:obj:`tud_lbm.config.adapter_base.ConfigAdapter`


   Adapter that reads and writes TOML configuration files.

   Supported top-level tables
   --------------------------
   ``[simulation_type]``
       Required. Contains the simulation type (``type``), grid shape,
       physics parameters, and runner/IO fields.

   ``[multiphase]``
       Optional. Extra physics parameters when ``type = "multiphase"``.

   ``[gravity_force]`` / ``[electric_force]`` / ...
       Optional. One top-level table per force model.

   ``[boundary_conditions]``
       Optional. Boundary condition configuration (including nested
       ``wetting_params`` and ``hysteresis_params``).

   ``[output]``
       Optional. Output/saving overrides (``results_dir``, ``fields``).


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

      Parse *path* and return raw configuration dict.

      Unlike :meth:`load`, this returns the raw config dict without
      instantiating :class:`SimulationConfig`.  Useful for detecting
      array fields before expansion.

      :param path: Filesystem path to a ``.toml`` file.

      :returns: Raw config dictionary (may contain array values for physics
                parameters, plus output overrides from ``[output]``).

      :raises FileNotFoundError: If *path* does not exist.
      :raises ValueError: If required sections/keys are missing.



   .. py:method:: load(path: str) -> tud_lbm.config.simulation_config.SimulationConfig

      Parse *path* and return a :class:`SimulationConfig`.

      Supports both scalar and array-valued parameters. For array
      parameters, use :meth:`load_raw` followed by
      :func:`~config.array_expansion.expand_config` to generate
      multiple configs.

      :param path: Filesystem path to a ``.toml`` file.

      :returns: A validated :class:`SimulationConfig`.

      :raises FileNotFoundError: If *path* does not exist.
      :raises ValueError: If required sections/keys are missing or invalid.



   .. py:method:: save(config: tud_lbm.config.simulation_config.SimulationConfig, path: str) -> None

      Serialise *config* to a ``.toml`` file at *path*.

      Delegates the field → section bucketing to
      :meth:`~ConfigAdapter.build_sections` (shared by all adapters)
      and writes the result with ``tomli_w``.

      :param config: A validated :class:`SimulationConfig`.
      :param path: Destination file path.

      :raises OSError: If the file cannot be written.
      :raises ImportError: If tomli_w is not installed.