Metadata-Version: 2.4
Name: latticebmjax
Version: 1.0.0
Summary: Hardware-accelerated Lattice Boltzmann Method using JAX
Author-email: Fernanda Vera <fernanda.vera-carrion@rwth-aachen.de>
License: MIT License
        
        Copyright (c) 2026 veracfernanda
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: homepage, https://github.com/veracfernanda/latticebmjax
Keywords: lattice boltzmann,cfd,jax,fluid simulation
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jax[cpu]>=0.4.30
Requires-Dist: jaxlib>=0.4.30
Requires-Dist: numpy>=1.26
Requires-Dist: matplotlib>=3.9.2
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Dynamic: license-file

# latticebmjax

## About

'latticebmjax' is a Python package designed for hardware-accelerated simulation of fluid flows using the Lattice Boltzmann Method (LBM) with JAX as the computational backend.
It is capable of:

- Solving 2D incompressible flows using the D2Q9 BGK-LBM scheme
- Applying Zou-He and bounce-back boundary conditions
- Running on CPU with JIT compilation via JAX
- Validating results against the Ghia et al. (1982) benchmark data
- Plotting velocity fields, streamlines and centreline profiles

## Features

- D2Q9 lattice with BGK single-relaxation-time collision operator
- Zou-He velocity boundary condition for the moving lid
- Bounce-back no-slip boundary conditions for stationary walls
- JIT-compiled time loop via `jax.jit` for high performance
- Lid-driven cavity solver validated against Ghia et al. (1982)
- Centreline velocity profiles compared to benchmark data (Re=100, 400, 1000)

## Installation

### Dependencies

Ensure you have the required dependencies installed, which are listed in `requirements.txt`. You can install them using:

```bash
pip install -r requirements.txt
```

### User installation

To install the library, you can use the 'pip' command:

```bash
pip install latticebmjax
```


### Folder structure

```bash
latticebmjax
├─── README.md
├─── LICENSE
├─── pyproject.toml
├─── requirements.txt
├─── benchmarks
│   ├─── convergence.py
│   └─── ghia_data.py
├─── examples
│   ├─── poiseuille.py
│   └─── lid_cavity.py
├─── latticebmjax
│   ├─── __init__.py
│   ├─── collision.py
│   ├─── equilibrium.py
│   ├─── lattice.py
│   └─── streaming.py
├─── solvers
│   ├─── __init__.py
│   ├─── base_solver.py
│   ├─── boundary.py
│   ├─── lid_cavity.py
│   └─── poiseuille.py
├─── testcase_data
│   ├─── ghia_re100.csv
│   ├─── ghia_re400.csv
│   └─── ghia_re1000.csv
└─── tests
    ├─── test_collision.py
    ├─── test_lid_cavity.py
    └─── test_streaming.py
```

### Examples

Some usage examples of the library can be found in the [examples folder](https://github.com/veracfernanda/latticebmjax/tree/dev/examples)

### License

This software is distributed under the MIT License and further information about the license can be found in the [LICENSE file](https://github.com/veracfernanda/latticebmjax/blob/dev/LICENSE)

### Third-party libraries

The library currently uses the following third-party libraries:

- [jax](https://jax.readthedocs.io) — JIT compilation and GPU acceleration
- [numpy](https://numpy.org) — array utilities and CSV loading
- [matplotlib](https://matplotlib.org) — velocity field and centreline plots
- [pandas](https://pandas.pydata.org) — benchmark data loading
- [pytest](https://pytest.org) — unit and integration testing

## Contributing

The project is in the early development phase. Upon completion and delivery, contributions will be welcome! Please fork the repository and submit a pull request for any improvements or bug fixes.
