# mabau/lbmpy architecture

> Architecture diagram of the GitHub repository mabau/lbmpy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mabau/lbmpy
- Repository: https://github.com/mabau/lbmpy

## Overview

#### Purpose and entry points
`lbmpy` is a Python library for constructing and executing lattice Boltzmann method (LBM) simulations, including hydrodynamics, thermal/multiphase models, boundaries, and analysis. The package entry point is `src/lbmpy/__init__.py`; high-level method/kernel construction is centered on `src/lbmpy/creationfunctions.py` and `src/lbmpy/lbstep.py`. The README only redirects to the successor GitHub repository.

#### Method-definition layer
LBM formulations are represented as method objects, with alternatives for raw-moment, central-moment, cumulant, and entropic schemes. This layer owns collision-model semantics, conserved quantities, equilibrium definitions, and relaxation behavior.
- `src/lbmpy/methods/abstractlbmethod.py`
- `src/lbmpy/methods/momentbased/momentbasedmethod.py`
- `src/lbmpy/methods/cumulantbased/cumulantbasedmethod.py`

#### Symbolic model construction
Stencils, moments, equilibria, transforms, forcing, and relaxation rates provide the mathematical inputs used to construct an LBM update rule. Method construction crosses from these symbolic definitions into executable kernel generation through the creation APIs.
- `src/lbmpy/stencils.py`
- `src/lbmpy/equilibrium/generic_discrete_equilibrium.py`
- `src/lbmpy/moment_transforms/abstractmomenttransform.py`
- `src/lbmpy/forcemodels.py`

#### Kernel and time-step execution
The execution path composes collision, streaming, field access, macro-value extraction, and optional split-loop optimizations into update kernels. `LBMConfig`-style construction is likely exposed through creation functions, while `lbstep` provides a higher-level simulation-step abstraction. Kernel logic is designed for CPU/GPU equivalence and different streaming/access patterns.
- `src/lbmpy/creationfunctions.py`
- `src/lbmpy/updatekernels.py`
- `src/lbmpy/lbstep.py`
- `src/lbmpy/fieldaccess.py`

#### Streaming, communication, and boundaries
Advanced streaming separates indexing/access-pattern concerns from communication, supporting periodic and distributed-style halo exchange patterns. Boundary handling is a distinct integration boundary: boundary conditions can be incorporated into generated kernels or managed through boundary-handling orchestration.
- `src/lbmpy/advanced_streaming/indexing.py`
- `src/lbmpy/advanced_streaming/communication.py`
- `src/lbmpy/boundaries/boundaryhandling.py`
- `src/lbmpy/boundaries/boundaries_in_kernel.py`

#### Specialized physics extensions
The core LBM pipeline is extended for phase-field and Allen–Cahn models, non-Newtonian/viscoelastic flows, turbulence, fluctuations, partially saturated cells, and sparse domains. These modules reuse the method/kernel boundary rather than forming separate applications.
- `src/lbmpy/phasefield/phasefieldstep.py`
- `src/lbmpy/phasefield_allen_cahn/kernel_equations.py`
- `src/lbmpy/oldroydb.py`
- `src/lbmpy/sparse/update_rule_sparse.py`

#### Analysis, runtime, and native integration
The runtime is primarily Python, with generated numerical kernels and a native C/Cython simplex-projection implementation for phase-field work. Analytical Chapman–Enskog tools connect discrete schemes to continuum behavior; postprocessing and macroscopic-value kernels expose simulation outputs. No hosted infrastructure or external service integration is evident from the repository tree.
- `src/lbmpy/chapman_enskog/chapman_enskog.py`
- `src/lbmpy/macroscopic_value_kernels.py`
- `src/lbmpy/phasefield/simplex_projection.c`
- `src/lbmpy/phasefield/simplex_projection.pyx`

Main entry points: [`src/lbmpy/lbstep.py`](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/lbstep.py) (Simulation step), [`src/lbmpy/creationfunctions.py`](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/creationfunctions.py) (Method & kernel creation), [`src/lbmpy/updatekernels.py`](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/updatekernels.py) (LBM update kernels), [`src/lbmpy/methods/abstractlbmethod.py`](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/methods/abstractlbmethod.py) (Abstract LBM method)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_symbolic["Symbolic LBM Model"]
  node_symbolic_inputs["Stencils, equilibria &amp; forcing<br/>symbolic definitions<br/>[stencils.py]"]
end

subgraph group_methods["Method Semantics"]
  node_abstract_method["Abstract LBM method<br/>method interface"]
  node_moment_method["Moment-based methods<br/>method implementation"]
  node_cumulant_method["Cumulant methods<br/>method implementation"]
end

subgraph group_execution["Kernel Execution"]
  node_creation_api{{"Method &amp; kernel creation<br/>construction API"}}
  node_update_kernels["LBM update kernels<br/>kernel generator<br/>[updatekernels.py]"]
  node_field_access["Field access<br/>access abstraction<br/>[fieldaccess.py]"]
  node_lbm_step["Simulation step<br/>runtime abstraction<br/>[lbstep.py]"]
end

subgraph group_distribution["Streaming &amp; Boundaries"]
  node_streaming_indexing["Streaming indexing<br/>[indexing.py]"]
  node_communication["Halo communication<br/>[communication.py]"]
  node_boundary_handling["Boundary handling<br/>orchestrator"]
  node_kernel_boundaries["In-kernel boundaries<br/>kernel integration"]
end

subgraph group_extensions["Extensions &amp; Analysis"]
  node_phasefield["Phase-field step<br/>physics extension<br/>[phasefieldstep.py]"]
  node_allen_cahn["Allen–Cahn equations<br/>physics extension"]
  node_sparse_update["Sparse update rule<br/>physics extension"]
  node_macroscopic_output["Macroscopic values<br/>output kernels"]
  node_chapman_enskog["Chapman–Enskog analysis<br/>[chapman_enskog.py]"]
  node_simplex_native["Simplex projection<br/>native extension"]
end

node_package["lbmpy package<br/>Python package<br/>[__init__.py]"]

node_package -->|"exports construction"| node_creation_api
node_package -->|"exposes runtime"| node_lbm_step
node_symbolic_inputs -->|"model inputs"| node_creation_api
node_abstract_method -->|"base class"| node_moment_method
node_abstract_method -->|"base class"| node_cumulant_method
node_moment_method -->|"selected formulation"| node_creation_api
node_cumulant_method -->|"selected formulation"| node_creation_api
node_creation_api -->|"builds"| node_update_kernels
node_creation_api -->|"configures"| node_lbm_step
node_field_access -->|"field mappings"| node_update_kernels
node_streaming_indexing -->|"access pattern"| node_field_access
node_update_kernels -->|"executes per step"| node_lbm_step
node_communication -.->|"halo exchange"| node_lbm_step
node_boundary_handling -->|"applies boundaries"| node_lbm_step
node_kernel_boundaries -->|"embeds conditions"| node_update_kernels
node_phasefield -->|"extends stepping"| node_lbm_step
node_allen_cahn -->|"equations"| node_phasefield
node_simplex_native -->|"projection support"| node_phasefield
node_sparse_update -->|"alternative update path"| node_update_kernels
node_lbm_step -->|"produces fields"| node_macroscopic_output
node_abstract_method -.->|"analyzed by"| node_chapman_enskog

click node_package "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/__init__.py"
click node_symbolic_inputs "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/stencils.py"
click node_abstract_method "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/methods/abstractlbmethod.py"
click node_moment_method "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/methods/momentbased/momentbasedmethod.py"
click node_cumulant_method "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/methods/cumulantbased/cumulantbasedmethod.py"
click node_creation_api "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/creationfunctions.py"
click node_update_kernels "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/updatekernels.py"
click node_field_access "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/fieldaccess.py"
click node_lbm_step "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/lbstep.py"
click node_streaming_indexing "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/advanced_streaming/indexing.py"
click node_communication "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/advanced_streaming/communication.py"
click node_boundary_handling "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/boundaries/boundaryhandling.py"
click node_kernel_boundaries "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/boundaries/boundaries_in_kernel.py"
click node_phasefield "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/phasefield/phasefieldstep.py"
click node_allen_cahn "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/phasefield_allen_cahn/kernel_equations.py"
click node_sparse_update "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/sparse/update_rule_sparse.py"
click node_macroscopic_output "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/macroscopic_value_kernels.py"
click node_chapman_enskog "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/chapman_enskog/chapman_enskog.py"
click node_simplex_native "https://github.com/mabau/lbmpy/blob/master/src/lbmpy/phasefield/simplex_projection.pyx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_symbolic_inputs toneBlue
class node_abstract_method,node_moment_method,node_cumulant_method toneAmber
class node_creation_api,node_update_kernels,node_field_access,node_lbm_step toneMint
class node_streaming_indexing,node_communication,node_boundary_handling,node_kernel_boundaries toneRose
class node_phasefield,node_allen_cahn,node_sparse_update,node_macroscopic_output,node_chapman_enskog,node_simplex_native toneIndigo
class node_package toneNeutral
```

## Components

### Symbolic LBM Model

Mathematical definitions used to specify an update rule.

- [Stencils, equilibria & forcing](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/stencils.py): symbolic definitions · Defines lattice geometry, equilibrium populations, transforms, and forces. · `src/lbmpy/stencils.py`

### Method Semantics

Collision formulations and relaxation behavior.

- [Abstract LBM method](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/methods/abstractlbmethod.py): method interface · Defines shared collision-model semantics and conserved quantities. · `src/lbmpy/methods/abstractlbmethod.py`
- [Moment-based methods](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/methods/momentbased/momentbasedmethod.py): method implementation · Implements raw-moment and central-moment formulations. · `src/lbmpy/methods/momentbased/momentbasedmethod.py`
- [Cumulant methods](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/methods/cumulantbased/cumulantbasedmethod.py): method implementation · Implements cumulant-based collision schemes. · `src/lbmpy/methods/cumulantbased/cumulantbasedmethod.py`

### Kernel Execution

Generated update kernels and simulation stepping.

- [Method & kernel creation](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/creationfunctions.py): construction API · Bridges symbolic model configuration to generated executable rules. · `src/lbmpy/creationfunctions.py`
- [LBM update kernels](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/updatekernels.py): kernel generator · Composes collision, streaming, and optional split-loop updates. · `src/lbmpy/updatekernels.py`
- [Field access](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/fieldaccess.py): access abstraction · Maps population fields to streaming and update operations. · `src/lbmpy/fieldaccess.py`
- [Simulation step](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/lbstep.py): runtime abstraction · High-level time-step orchestration for generated kernels. · `src/lbmpy/lbstep.py`

### Streaming & Boundaries

Access patterns, communication, and boundary orchestration.

- [Streaming indexing](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/advanced_streaming/indexing.py): indexing · Separates streaming access-pattern and indexing logic. · `src/lbmpy/advanced_streaming/indexing.py`
- [Halo communication](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/advanced_streaming/communication.py): communication · Supports periodic and distributed-style population exchange. · `src/lbmpy/advanced_streaming/communication.py`
- [Boundary handling](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/boundaries/boundaryhandling.py): orchestrator · Applies boundary conditions around simulation updates. · `src/lbmpy/boundaries/boundaryhandling.py`
- [In-kernel boundaries](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/boundaries/boundaries_in_kernel.py): kernel integration · Incorporates boundary conditions directly into generated kernels. · `src/lbmpy/boundaries/boundaries_in_kernel.py`

### Extensions & Analysis

Specialized physics, native support, and output analysis.

- [Phase-field step](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/phasefield/phasefieldstep.py): physics extension · Extends the core pipeline with phase-field simulation steps. · `src/lbmpy/phasefield/phasefieldstep.py`
- [Allen–Cahn equations](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/phasefield_allen_cahn/kernel_equations.py): physics extension · Provides phase-field Allen–Cahn kernel equations. · `src/lbmpy/phasefield_allen_cahn/kernel_equations.py`
- [Sparse update rule](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/sparse/update_rule_sparse.py): physics extension · Adapts updates for sparse simulation domains. · `src/lbmpy/sparse/update_rule_sparse.py`
- [Macroscopic values](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/macroscopic_value_kernels.py): output kernels · Extracts simulation observables from population fields. · `src/lbmpy/macroscopic_value_kernels.py`
- [Chapman–Enskog analysis](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/chapman_enskog/chapman_enskog.py): analysis · Connects discrete LBM schemes to continuum behavior. · `src/lbmpy/chapman_enskog/chapman_enskog.py`
- [Simplex projection](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/phasefield/simplex_projection.pyx): native extension · C/Cython phase-field projection implementation. · `src/lbmpy/phasefield/simplex_projection.pyx`

### Other components

- [lbmpy package](https://github.com/mabau/lbmpy/blob/master/src/lbmpy/__init__.py): Python package · `src/lbmpy/__init__.py`

## Connections

- lbmpy package → Method & kernel creation: exports construction
- lbmpy package → Simulation step: exposes runtime
- Stencils, equilibria & forcing → Method & kernel creation: model inputs
- Abstract LBM method → Moment-based methods: base class
- Abstract LBM method → Cumulant methods: base class
- Moment-based methods → Method & kernel creation: selected formulation
- Cumulant methods → Method & kernel creation: selected formulation
- Method & kernel creation → LBM update kernels: builds
- Method & kernel creation → Simulation step: configures
- Field access → LBM update kernels: field mappings
- Streaming indexing → Field access: access pattern
- LBM update kernels → Simulation step: executes per step
- Halo communication → Simulation step: halo exchange
- Boundary handling → Simulation step: applies boundaries
- In-kernel boundaries → LBM update kernels: embeds conditions
- Phase-field step → Simulation step: extends stepping
- Allen–Cahn equations → Phase-field step: equations
- Simplex projection → Phase-field step: projection support
- Sparse update rule → LBM update kernels: alternative update path
- Simulation step → Macroscopic values: produces fields
- Abstract LBM method → Chapman–Enskog analysis: analyzed by