Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
1b8434a
Refactored the operator structure to reduce the unrequired additional…
szkud Oct 27, 2026
79af8ec
Refactored the feature->addon and contribution->hooks
szkud Oct 27, 2026
3aa9660
Refactored the protocols
szkud Nov 2, 2026
f5ab305
Cleaned up the simulation config.
szkud Nov 2, 2026
715b1ce
Finalising refactor
szkud Nov 2, 2026
5584cfd
Implementation of 3D
szkud Nov 3, 2026
a43ef0d
symmertry bc fix
szkud Nov 3, 2026
bb8e0c2
Changed the wetting density preset.
szkud Nov 4, 2026
d1d1635
Final pre PR clean up.
szkud Nov 4, 2026
a366413
Refactored the literal strings
szkud Nov 5, 2026
eecd13c
Refactored the literal strings
szkud Nov 5, 2026
4fb096e
Added nan-check to surface tension calibration
szkud Nov 5, 2026
b815748
Refactored init file naming.
szkud Nov 5, 2026
203f694
Small refactors.
szkud Nov 5, 2026
fc0b844
Implemented the maxwell construction logic in the codebase.
szkud Nov 6, 2026
6baa61c
Removed analysis plot and added We analysis to comparison.
szkud Nov 6, 2026
6909482
Pre and post step now depend on the initial location of the dispersed…
szkud Nov 11, 2026
f19f8af
Added Oh^2 for the regime plots
szkud Nov 11, 2026
be05ffb
Added Oh^2 for the regime plots
szkud Nov 11, 2026
e43aec8
moved plans to correct place.
szkud Nov 12, 2026
1447518
Merge pull request #119 from szkuds/feature/maxwell_construction
szkuds Nov 12, 2026
647ac8e
Merge branch 'fix/bubble_simulation' of github.com:szkuds/TUD_LBM int…
szkud Nov 12, 2026
af3d608
Implemented the maxwell construction
szkud Nov 12, 2026
bacd233
added extra infor for the EoD[
szkud Nov 12, 2026
668aad4
Small fix for surface tension calibration.
szkud Nov 12, 2026
7cfc7ba
surface tension cache updated
szkud Nov 12, 2026
17593f7
Changed the indexing of the boundaries since it had several component…
szkud Nov 13, 2026
9214559
Adapted the hysteresis window which had an early onset in the acceler…
szkud Nov 16, 2026
ae4fc4b
Refactor parellel runs
szkud Nov 17, 2026
f3de70c
Refactor of the test to enable pycharm debugging.
szkud Nov 17, 2026
8882ac9
Refactored the naming convention.
szkud Nov 17, 2026
b65bfe5
electric force fix
szkud Nov 18, 2026
065e3c1
Fixed a wetting clamp bug with CS EoS.
szkud Nov 18, 2026
4253b7f
Attempt to remove overlapping frames when plotting.
szkud Nov 18, 2026
ee5e3f3
Surface tension update
szkud Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
24 changes: 19 additions & 5 deletions .idea/pyLspTools.xml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
[![cffconvert](https://github.com/szkuds/tud_lbm/actions/workflows/cffconvert.yml/badge.svg)](https://github.com/szkuds/tud_lbm/actions/workflows/cffconvert.yml)
[![sonarcloud](https://github.com/szkuds/tud_lbm/actions/workflows/sonarcloud.yml/badge.svg)](https://github.com/szkuds/tud_lbm/actions/workflows/sonarcloud.yml)

A JAX-accelerated lattice Boltzmann method framework developed at Delft University of Technology. TUD-LBM supports single-phase, multiphase, wetting, hysteresis, and chemical-step simulations through a configuration-driven workflow.
A JAX-accelerated lattice Boltzmann method framework developed at Delft University of Technology. TUD-LBM supports single-phase and multiphase (well-balanced LBM, WB-LBM) simulations, wetting boundary conditions with or without contact angle hysteresis, and chemical steps, through a configuration-driven workflow. The terms are defined in the *Terminology* section of [`docs/quickstart.rst`](docs/quickstart.rst).

## Installation

Expand Down Expand Up @@ -79,10 +79,10 @@ tud-lbm run

### Parameter sweeps and post-processing

List-valued sweepable fields in a TOML configuration expand into a parameter sweep. Use `--max-workers` to control parallel execution and `--compare` to create cross-run comparison plots.
A run is one config. A parameter sweep is staged as one completed TOML per combination; run each file with `tud-lbm run`, or pass the directory to `scripts/db_pipeline.sh`.

```console
tud-lbm run examples/config_parallel.toml --max-workers 4 --compare
tud-lbm sweep stage examples/config_simple.toml --set 'tau=[0.6, 0.7, 0.8]' --out configs/var_tau/
```

Saved runs can be plotted or animated, and a directory of runs can be analysed:
Expand All @@ -93,7 +93,7 @@ tud-lbm animate /path/to/run-directory
tud-lbm compare /path/to/sweep-results --no-prompt
```

See the [examples](examples/) for single-phase, multiphase, parallel, and von Karman configurations.
See the [examples](examples/) for single-phase, multiphase, and von Karman configurations.

## Reporting bugs and vulnerabilities

Expand Down
160 changes: 95 additions & 65 deletions docs/adapters.rst
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,22 @@ Configuration input
-------------------

All input adapters subclass
:class:`~src.config.adapter_base.ConfigAdapter` and implement two methods:
:class:`~src.protocols.ConfigAdapter` and implement two methods:

``load_raw(source) -> dict``
Parse the source into a flat kwargs dict, without instantiating anything.
Read the source into the nested section layout and hand it to
:func:`~src.config.sections.load_sections`, which upgrades an old-layout
config and flattens the sections onto field names.

``save(config, path) -> None``
Serialise a config back out.
Serialise a config back out, from :func:`~src.config.sections.build_sections`.

The shared ``load()`` on the base class handles the rest: normalising
``grid_shape`` to a tuple, splitting known fields from unknown ones, and
constructing the frozen ``SimulationConfig`` (which validates itself).
The shared ``load()`` on the base class handles the rest
(:func:`~src.config.sections.config_from_flat`): normalising ``grid_shape``
to a tuple, keeping unknown keys in ``extra``, rejecting the old flat field
names, and constructing the frozen ``SimulationConfig`` (which validates
itself). The layout is config knowledge, so it lives in
:mod:`src.config.sections`, not on the adapter base class.

.. code-block:: python

Expand Down Expand Up @@ -56,11 +61,13 @@ way, so a run is always reproducible from its own output.
Accepts two shapes. **Flat**, using ``SimulationConfig`` field names
directly::

{"sim_type": "multiphase", "kappa": 0.04, ...}
{"multiphase": {"eos": "double-well", "kappa": 0.04, ...},
"forces": {"gravity_force": {"force_g": 1e-6}}}

or **nested**, mirroring the TOML section structure::

{"simulation_type": {"type": "multiphase", ...}, "multiphase": {...}}
{"simulation_type": {"nt": 1000, ...}, "multiphase": {...},
"gravity_force": {"force_g": 1e-6}}

The nested form is detected by the presence of a ``simulation_type`` dict.
``DictAdapter.save()`` raises ``NotImplementedError`` — use ``TomlAdapter``
Expand All @@ -69,98 +76,121 @@ to write.
Section mapping
~~~~~~~~~~~~~~~

``_merge_sections`` flattens the nested representation onto config fields.
:func:`~src.config.sections.merge_sections` flattens the nested representation onto config fields.
The mapping is:

========================= ===============================================
TOML section ``SimulationConfig`` destination
========================= ===============================================
``[simulation_type]`` top-level fields; ``type`` → ``sim_type``
``[multiphase]`` merged into top level, multiphase types only
``[boundary_conditions]`` ``bc_config``
``[simulation_type]`` top-level fields (``nt``, ``tau``, ``grid_shape``, …)
``[multiphase]`` ``multiphase``; its presence makes the run multiphase
``[boundary_conditions]`` ``boundary_conditions``
``[initialisation]`` ``initialisation``
``[wetting]`` ``wetting_config``
``[hysteresis]`` ``hysteresis_config``
``[chemical_step]`` ``chemical_step_config``
``[obstacle]`` ``obstacle_config``
``[<name>_force]`` the matching ``<name>_force`` field
``[wetting]`` ``wetting``
``[hysteresis]`` ``hysteresis``
``[chemical_step]`` ``chemical_step``
``[obstacle]`` ``obstacle``
``[<name>_force]`` ``forces["<name>_force"]``
``[output]`` ``results_dir``, ``save_fields``, ``plot_fields``,
``animate_fields``, ``output_format``, …
========================= ===============================================

Rules worth knowing:

* ``[simulation_type]`` is required; its absence raises ``ValueError``.
* ``type`` is validated against the five known simulation types before any
other parsing happens.
* ``[multiphase]`` is only merged when ``type`` contains ``"multiphase"`` —
a stray section on a single-phase run is ignored, not an error.
* A ``[*_force]`` section whose name does not match a force field raises
* Each section is stored whole on the field of the same name, so the section
names *are* the field names, and ``--override multiphase.kappa=0.02`` needs
no alias table.
* A ``[*_force]`` section with no schema in ``config/forces.py`` raises
``KeyError``; one that is not a table raises ``TypeError``.
* A flat old field name (``sim_type``, ``kappa``, ``wetting_config``, …)
passed to ``config_from_flat`` raises ``ValueError`` instead of landing in
``extra``, which would silently have made the run single-phase.
* ``results_dir`` is passed through ``Path.expanduser()``, so ``~`` works.
* Keys that match no field are collected into ``config.extra`` rather than
rejected. This is how calibration results such as ``surface_tension`` are
carried alongside a run.

The reverse direction is driven by the same metadata. Every field carries a
``CONFIG_SECTION`` entry, and ``build_sections()`` buckets fields back into
``CONFIG_SECTION`` entry, and :func:`~src.config.sections.build_sections` buckets fields back into
sections so that a saved config round-trips to the shape it was loaded from.

Defaults applied on construction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``SimulationConfig.__post_init__`` fills in several things, so the object you
get back is not always what you wrote:
Every default lives once, in :mod:`src.config.defaults`.
``SimulationConfig.__post_init__`` fills them in, so the object you get back —
and the ``config.toml`` written to the run directory — is not always what you
wrote, but always what the run used:

* ``grid_shape`` is promoted to 3-D — ``(64, 64)`` becomes ``(64, 64, 1)``.
* ``save_interval`` defaults to ``nt // 10`` when left at ``0``.
* ``bc_config`` defaults to periodic on all six faces; any face you omit from
an explicit ``[boundary_conditions]`` is filled in as ``periodic``.
* A ``[hysteresis]`` section without a ``[wetting]`` section gets neutral
wetting parameters (``phi = 1.0``, ``d_rho = 0.0``).
* every edge of the lattice gets a boundary condition, ``periodic`` when
omitted (four edges on a 2D lattice, six on a 3D one), and an edge whose
condition takes parameters gets them (``u0 = 0.05`` for a
``velocity-inlet``).
* a ``[multiphase]`` section whose EOS has a coexistence solver
(Carnahan–Starling) gets any omitted ``rho_l``/``rho_v`` from the Maxwell
construction of its own parameters, rounded to six significant figures; a
configured density is kept.
* ``equilibrium`` defaults by phase: ``standard_equilibrium`` single-phase,
``wb`` multiphase; the source term is the one it registered as its pair.
* with ``equilibrium = "wb_hydro_inc"`` an omitted
``[multiphase] equilibrium_reference_density`` is the vapour density at
coexistence (the Maxwell one for Carnahan–Starling, else ``rho_v``). The key
is rejected for any other equilibrium.
* the ``[hysteresis]``, ``[chemical_step]`` and ``[*_force]`` sections get
their optimiser, step and force defaults, and a ``[hysteresis]`` section
without ``[wetting]`` gets neutral wetting parameters (``phi = 1.0``,
``d_rho = 0.0``).
* an MRT ``k_diag`` has its shear entries rewritten to ``1/tau``.
* ``output_format`` is lower-cased, and a list collapses to its first entry.

Validation covers grid shape, lattice type, ``tau > 0.5``, ``nt > 0``,
collision scheme (with ``k_diag`` required for MRT), ``init_dir`` when
``init_type = "init_from_file"``, ``save_fields`` membership, obstacle
geometry, and — for multiphase — the presence of ``eos``, ``kappa``,
``rho_l``, ``rho_v``, ``interface_width``, that ``rho_l > rho_v``, and the
four Carnahan–Starling parameters when that EOS is selected. Specifying both
``gravity_force`` and ``gravity_masked_force`` is rejected.
collision scheme (with ``k_diag`` required for MRT), the equilibrium,
``init_type`` against the registry and ``init_dir`` for ``init_from_file``,
``save_fields`` membership, every boundary-condition name and parameter key,
obstacle geometry, each force against its schema, the wetting, hysteresis
and chemical-step sections, and — for multiphase — the common keys, that
``rho_l > rho_v`` (both required for a double-well EOS), and the further
parameters of the selected EOS (the four Carnahan–Starling ones). Only one
gravity force may be configured. A 3D
lattice refuses what is still two-dimensional: wetting, hysteresis, chemical
step, the electric force, MRT and an obstacle.

Old-layout configs
~~~~~~~~~~~~~~~~~~

:mod:`src.config.legacy` upgrades a config written before the section
layout — ``[simulation_type] type = ...``, flat multiphase keys, per-force
fields, the ``*_config`` names. ``TomlAdapter`` rewrites a run directory's
``config.toml`` in the new layout on its first load, through its own
``save``; any other file is upgraded in memory and left as it is. The upgrade
is idempotent, and nothing outside ``legacy.py`` and its one call knows the
old layout.

Parameter sweeps
----------------

Fields declared with ``array_field()`` are sweep-eligible: giving one a list
value expands the configuration into the Cartesian product of all such
lists.
A configuration is always one run. A sweep is staged as files by
``tud-lbm sweep stage`` (``src/cli/sweep_staging.py``): for each combination of
the ``--set`` axes it applies the values to the flat raw dict with the
``--override`` path rules, builds the :class:`SimulationConfig`, and writes it
with :meth:`TomlAdapter.save`, the writer of a run directory's own
``config.toml``. So every staged file is validated and shows the defaults and
derived values (Maxwell ``rho_l``/``rho_v``, MRT shear rates) of its own
combination.

.. code-block:: python

from src.config.array_expansion import expand_config

configs, params = expand_config(raw_dict)
len(configs) # one per combination
params.field_names # frozenset of the fields that were swept

``expand_config`` takes the *raw dict* — the output of ``load_raw()``, before
``SimulationConfig`` instantiation — and returns
``(list[SimulationConfig], ArrayParameterSet | None)``. The metadata is
``None`` when no arrays were found. Pass ``allow_arrays=False`` to make list
values an error instead, which is what single-run code paths do.

Expansion applies at two levels: top-level sweep-eligible fields, and
sub-keys inside the *nested sweepable* dicts ``wetting_config``,
``hysteresis_config``, ``chemical_step_config``, and the force sections.
That is what makes this work:

.. code-block:: toml
.. code-block:: console

[simulation_type]
tau = [0.6, 0.7]
tud-lbm sweep stage cfg.toml --set 'tau=[0.6, 0.7]' \
--set 'hysteresis.ca_advancing=[110.0, 120.0]' \
--set 'gravity_masked_force.force_g=[1e-6, 2e-6]' # 2 × 2 × 2 = 8 files

[hysteresis]
ca_advancing = [110.0, 120.0] # 2 × 2 = 4 runs
A list where a sweep used to read its axis — ``tau``, ``nt``,
``collision_scheme``, a list of ``grid_shape``\ s, any key of ``[multiphase]``,
``[wetting]``, ``[hysteresis]``, ``[chemical_step]`` or a ``[*_force]`` table —
raises ``ValueError`` and names the command.

Simulation output
-----------------
Expand Down Expand Up @@ -246,8 +276,8 @@ Two further details matter for correctness:
differ on resumed runs, ``skip_interval`` runs, and pruned snapshots, where
a fixed-interval difference over-reports contact-line speeds by the ratio
of the gaps.
* ``MetricScales`` carries both ``sigma_measured`` (from
``config.extra["surface_tension"]``) and ``sigma_analytical``
* ``MetricScales`` carries both ``sigma_measured`` (from the calibration
cache, through ``cached_surface_tension(config)``) and ``sigma_analytical``
(``(2/3)(κ/W)·Δρ²``). ``sigma_primary`` prefers the measured value,
because the closed form is not valid for ``carnahan-starling``. The CSV
exports ``sigma_lg``, ``sigma_lg_source``, and ``Ca_analytical`` so both
Expand All @@ -257,7 +287,7 @@ Adding a format
---------------

**Input**: subclass ``ConfigAdapter``, implement ``load_raw`` and ``save``,
and register the extension in ``_ADAPTER_MAP``. Reuse ``_merge_sections``
and register the extension in ``_ADAPTER_MAP``. Reuse :func:`~src.config.sections.merge_sections`
if your format has the same section structure.

**Output**: add a module to ``src/simulation_io/output_data/`` with an
Expand Down
Loading
Loading