Metadata-Version: 2.4
Name: crawlbm
Version: 0.1.0
Summary: A simple 2D Lattice Boltzmann Method (LBM) fluid solver
Author: Brendan Boyd
License-Expression: MIT
Project-URL: Homepage, https://github.com/biboyd/crawLBM
Project-URL: Source, https://github.com/biboyd/crawLBM
Project-URL: Issues, https://github.com/biboyd/crawLBM/issues
Keywords: lattice boltzmann,fluid dynamics,CFD,LBM
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Dynamic: license-file

# crawLBM

A bare-bones 2D Lattice Boltzmann Method (LBM) fluid solver written in Python.
The logic is simply: crawl before walking or running.

## Features

* BGK (single-relaxation-time) collision operator
* D2Q9 lattice structure
* Periodic and halfway bounce-back boundary conditions (including moving walls)
* Taylor-Green Vortex and Couette Flow test problems
* Physical unit conversion (SI inputs → lattice units)

## Installation

### From PyPI

```bash
pip install crawLBM
```

### From source

```bash
git clone https://github.com/biboyd/crawLBM.git
cd crawLBM
pip install .
```

For development (editable install):

```bash
pip install -e .
```

## Usage

After installation, run the solver from the command line:

```bash
# Taylor-Green Vortex (default)
crawlbm --init TG-vortex --domain_resolution 64 --max_step 1000 --plot_dir ./output

# Couette Flow
crawlbm --init Couette --domain_resolution 32 --tau 0.8 --max_step 2000 --plot_dir ./output
```

### Key options

| Flag | Default | Description |
|------|---------|-------------|
| `--init` | `TG-vortex` | Initialization type: `TG-vortex` or `Couette` |
| `--domain_size Lx Ly` | `1 1` | Physical domain size in SI units |
| `--domain_resolution` | `64` | Grid points along the longest dimension |
| `--tau` | `0.8` | Relaxation time (must be > 0.5) |
| `--nu` | `1e-6` | Physical kinematic viscosity (m²/s) |
| `--U_ref` | `0.01` | Reference velocity scale (m/s) |
| `--max_step` | `1000` | Number of time steps |
| `--plot_int` | `100` | Save a plotfile every N steps |
| `--plot_dir` | `./` | Output directory for plotfiles |

### Python API

```python
from crawlbm import Grid, advance_sim
from crawlbm._cli import init_TG_vortex

grid = Grid(nx=64, ny=64)
init_TG_vortex(grid, Lx=1.0, Ly=1.0, U_0=0.01)
advance_sim(grid, tau=0.8, max_step=500, plot_int=100, plot_dir='./output')
```

## Running tests

```bash
pip install pytest
pytest unit_tests/ -v
```

## Dependencies

* Python >= 3.8
* NumPy

Matplotlib is an optional dependency used by the plotting scripts in `plotfiles/` and `test_problems/`. Install it with:

```bash
pip install crawlbm[plot]
```

## LLM Acknowledgement
Core functions and functionality were written by Brendan Boyd. Unit tests, convergence tests, and cleaning up the codebase to work as a python package was implemented via Claude Code.

Additionally, some bug fixes were found via Claude Code.
