How mabau/lbmpy works
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: lbstep.py Simulation step · creationfunctions.py Method & kernel creation · updatekernels.py LBM update kernels · abstractlbmethod.py Abstract LBM method
Components 19
Symbolic LBM Model
Mathematical definitions used to specify an update rule.
- Stencils, equilibria & forcing · Defines lattice geometry, equilibrium populations, transforms, and forces.
src/lbmpy/stencils.py
Method Semantics
Collision formulations and relaxation behavior.
- Abstract LBM method · Defines shared collision-model semantics and conserved quantities.
src/lbmpy/methods/abstractlbmethod.py - Moment-based methods · Implements raw-moment and central-moment formulations.
src/lbmpy/methods/momentbased/momentbasedmethod.py - Cumulant methods · Implements cumulant-based collision schemes.
src/lbmpy/methods/cumulantbased/cumulantbasedmethod.py
Kernel Execution
Generated update kernels and simulation stepping.
- Method & kernel creation · Bridges symbolic model configuration to generated executable rules.
src/lbmpy/creationfunctions.py - LBM update kernels · Composes collision, streaming, and optional split-loop updates.
src/lbmpy/updatekernels.py - Field access · Maps population fields to streaming and update operations.
src/lbmpy/fieldaccess.py - Simulation step · High-level time-step orchestration for generated kernels.
src/lbmpy/lbstep.py
Streaming & Boundaries
Access patterns, communication, and boundary orchestration.
- Streaming indexing · Separates streaming access-pattern and indexing logic.
src/lbmpy/advanced_streaming/indexing.py - Halo communication · Supports periodic and distributed-style population exchange.
src/lbmpy/advanced_streaming/communication.py - Boundary handling · Applies boundary conditions around simulation updates.
src/lbmpy/boundaries/boundaryhandling.py - In-kernel boundaries · 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 · Extends the core pipeline with phase-field simulation steps.
src/lbmpy/phasefield/phasefieldstep.py - Allen–Cahn equations · Provides phase-field Allen–Cahn kernel equations.
src/lbmpy/phasefield_allen_cahn/kernel_equations.py - Sparse update rule · Adapts updates for sparse simulation domains.
src/lbmpy/sparse/update_rule_sparse.py - Macroscopic values · Extracts simulation observables from population fields.
src/lbmpy/macroscopic_value_kernels.py - Chapman–Enskog analysis · Connects discrete LBM schemes to continuum behavior.
src/lbmpy/chapman_enskog/chapman_enskog.py - Simplex projection · C/Cython phase-field projection implementation.
src/lbmpy/phasefield/simplex_projection.pyx
Other components
- lbmpy package
src/lbmpy/__init__.py
Connections 21
- 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