tud_lbm
=======

.. py:module:: tud_lbm

.. autoapi-nested-parse::

   TUD LBM — Physics-first Lattice Boltzmann Method simulation framework.

   A JAX-accelerated LBM package for PhD students and researchers, emphasizing
   readability and extensibility.

   Quick Start
   -----------

   The main workflow: Config → Setup → State → Run::

       from tud_lbm import SimulationConfig, build_setup, run, init_state

       # 1. Create configuration with sensible defaults
       config = SimulationConfig(grid_shape=(64, 64), tau=0.8, nt=5000)

       # 2. Build simulation setup from config
       setup = build_setup(config)

       # 3. Initialize state (single-phase or multiphase)
       state = init_state(setup)

       # 4. Run simulation
       final_state, trajectory = run(setup, state, nt=config.nt)

   Key Classes & Functions
   -----------------------

   **Configuration & Setup:**
   - SimulationConfig     : Immutable configuration container (sensible defaults)
   - build_lattice()      : Create velocity model (D2Q9, D3Q19, etc.)
   - build_setup()        : Build complete simulation setup
   - State                : Single-phase simulation state (rho, u, f)
   - WettingState         : Multiphase state with contact angle and interface tracking

   **Execution:**
   - init_state()         : Initialize state from setup
   - run()                : Execute simulation, returns (final_state, trajectory)

   **Input/Output:**
   - readers              : Config loaders (DictAdapter, TomlAdapter)
   - plotting             : Visualization (FigureBuilder, PlotOperator, visualise)
   - io                   : Output writers (NumPy, VTK) and managers (SimulationIO)

   Full API Reference
   -------------------

   See https://github.com/tudelft-ceg/tud-lbm for documentation.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/tud_lbm/cli/index
   /autoapi/tud_lbm/config/index
   /autoapi/tud_lbm/io/index
   /autoapi/tud_lbm/lattice/index
   /autoapi/tud_lbm/operators/index
   /autoapi/tud_lbm/pipeline/index
   /autoapi/tud_lbm/plotting/index
   /autoapi/tud_lbm/readers/index
   /autoapi/tud_lbm/registry/index


Attributes
----------

.. autoapisummary::

   tud_lbm.__version__


Functions
---------

.. autoapisummary::

   tud_lbm.__getattr__
   tud_lbm.__dir__


Package Contents
----------------

.. py:data:: __version__
   :value: '0.3.0'


.. py:function:: __getattr__(name)

   Lazy load main API to avoid circular imports.

   Exports:
   --------
   SimulationConfig : Immutable frozen dataclass with physics & grid parameters
   Lattice          : Velocity model (D2Q9, D3Q19, etc.)
   build_lattice()  : Factory to create lattice from config
   build_setup()    : Factory to create complete Setup from config
   init_state()     : Initialize State or WettingState from setup
   run()            : Execute simulation for N timesteps
   State            : Single-phase simulation state (rho, u, f, t)
   WettingState     : Multiphase state for contact angle tracking


.. py:function:: __dir__()

   Expose public API for IDE autocompletion and help().