https://github.com/haimingz/vivsim
Accelerated vortex-induced vibration (VIV) simulation using immersed boundary lattice Boltzmann method (IB-LBM) powered by JAX.
https://github.com/haimingz/vivsim
cfd jax lbm
Last synced: about 1 month ago
JSON representation
Accelerated vortex-induced vibration (VIV) simulation using immersed boundary lattice Boltzmann method (IB-LBM) powered by JAX.
- Host: GitHub
- URL: https://github.com/haimingz/vivsim
- Owner: haimingz
- License: mit
- Created: 2024-04-03T15:51:22.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-12-26T07:05:34.000Z (3 months ago)
- Last Synced: 2025-12-27T18:49:23.425Z (2 months ago)
- Topics: cfd, jax, lbm
- Language: Python
- Homepage:
- Size: 6.86 MB
- Stars: 28
- Watchers: 2
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-jax - vivsim - Fluid-structure interaction simulations using Immersed Boundary-Lattice Boltzmann Method. <img src="https://img.shields.io/github/stars/haimingz/vivsim?style=social" align="center"> (Libraries / New Libraries)
README
## VIVSIM
[](https://github.com/MShawon/github-clone-count-badge) [](https://github.com/MShawon/github-clone-count-badge)
VIVSIM is a Python library for accelerated fluid-structure interaction (FSI) simulations based on the immersed boundary -lattice Boltzmann method (IB-LBM). It was originated from a research project requiring efficient simulation codes for studying vortex-induced vibration (VIV) of underwater structures.
Inspired by projects like [JAX-CFD](https://github.com/google/jax-cfd) and [XLB](https://github.com/Autodesk/XLB), VIVSIM utilizes [JAX](https://github.com/jax-ml/jax) as the backend to harness the power of hardware accelerators, achieving massive parallelism on GPU/GPUs.
## Recent Updates
**Version 1.1.0** (October 2024)
- **Modular LBM Architecture**: Reorganized all LBM-related code into a structured `lbm` module with submodules for `boundary`, `collision`, and `forcing`, enabling easier maintenance and future extensions with new methods.
- **Enhanced Boundary Conditions**: Implemented more boundary condition methods including Non-Equilibrium Extrapolation (NEE), Non-Equilibrium Bounce Back (NEBB), and equilibrium boundary conditions. Support predescribed velocity, density, and forces.
- **Improved LBM Collision Operators**: Implemented Karlin-Bösch-Chikatamarla (KBC) collision operator that is super stable for high Re numbers.
- **New Forcing Scheme**: Implemented the modified Exact Difference Method (EDM) which requires no correction to the collision operator when there are forces..
- **Code Quality**: Improved code readability, fixed typos in docstrings, and enhanced documentation throughout the codebase using AI with my supervision.
## Usage
VIVSIM provides a collection of **pure functions** for IB-LBM computations. Users can construct custom simulation models for different tasks. Start with the included demo examples to see how easy that is!
Below is a minimum workable example for lid-driven cavity simulation:
```python
import jax
import jax.numpy as jnp
from vivsim import lbm
# define constants
U0 = 0.5 # velocity of lid
NU = 0.1 # kinematic viscosity
OMEGA = lbm.get_omega(NU) # relaxation parameter
# define fluid properties
rho = jnp.ones((NX, NY), dtype=jnp.float32) # density
u = jnp.zeros((2, NX, NY), dtype=jnp.float32) # velocity
# initialize distribution function
f = lbm.get_equilibrium(rho, u)
# define compute routine
@jax.jit
def update(f):
# Collision
rho, u = lbm.get_macroscopic(f)
feq = lbm.get_equilibrium(rho, u)
f = lbm.collision_bgk(f, feq, OMEGA)
# Streaming
f = lbm.streaming(f)
# Boundary conditions
f = lbm.boundary_nee(f, loc='left')
f = lbm.boundary_nee(f, loc='right')
f = lbm.boundary_nee(f, loc='bottom')
f = lbm.boundary_nee(f, loc='top', ux_wall=U0)
return f, rho, u
# start simulation
for t in range(TM):
f, rho, u = update(f)
# export data & visualization ...
```
## Examples
_Lid-driven cavity at Re = 2e4 on a 1000x1000 lattice grid_
_Flow passes some texts on a 1000x1000 lattice grid_
_VIV of a cylinder with U_r = 5 and Re = 1e2_
_VIV of a cylinder with U_r = 5 and Re = 1e4_
## Capabilities
Lattice Models
- D2Q9
Collision Models
- Bhatnagar-Gross-Krook (BGK) collision operator
- Multiple Relaxation Time (MRT) collision operator
- Karlin–Bösch–Chikatamarla (KBC) collision operator
Boundary Conditions:
- Predescribed velocity, density, and forces at boundaies using:
- Non-Equilibrium Bounce Back (NEBB) method
- Non-Equilibrium Extrapolation (NEE) method
- Equilibrium boundary
- Predescribed velocity boundary using
- Bounce-Back method (no-slip)
- Specular Reflection (slip)
- Periodic boundary
Forcing Schemes:
- Guo's Forcing sheme
- Modified Exact Difference Method (EDM)
Fluid-Structure Interaction
- Multi-Direct-Forcing (MDF) Immersed Boundary method.
Acceleration techniques
- Multi-GPU simulation (using JAX)
- Gird refinement (shown below)
- Dynamic IB region (shown below)
## Todos
- Standardized simulation routines.
- 3D simulation capability.
## Getting Started
To locally install VIVSIM for development:
```bash
git clone https://github.com/haimingz/vivsim.git
pip install -e vivsim
```
This package is based on JAX, whose installation may depend on the OS and hardware. If the above command does not work well, please refer to the [JAX Documentation](https://jax.readthedocs.io/en/latest/installation.html) for the latest installation guidance.
More detailed instructions can be found in our [Documentation](https://github.com/haimingz/vivsim/wiki/Installation).
## Cite VIVSIM
If you find this repo useful, please cite [our paper](https://asmedigitalcollection.asme.org/OMAE/proceedings-abstract/OMAE2024/87844/1202724):
```
@article{zhu2025gpu,
title={{GPU} Accelerated Vortex-Induced Vibration Simulation Using {JAX}: Efficiency and Accuracy Strategies},
author={Zhu, Haiming and Yang, Yuan and Du, Zunfeng and Yu, Jianxing},
journal={Computers \& Fluids},
pages={106913},
year={2025},
publisher={Elsevier}
}
```