Pure Python CFD Solver with PyTorch GPU Acceleration
An open-source Python reimplementation of OpenFOAM 13 (Foundation)
pyOpenFOAM is an open-source Python reimplementation of OpenFOAM 13 (Foundation), the widely-used C++ computational fluid dynamics (CFD) toolbox. Our goal is to bring OpenFOAM's capabilities to the Python ecosystem while leveraging PyTorch for GPU acceleration and automatic differentiation.
- 64 OpenFOAM Solvers — Incompressible, compressible, multiphase, thermal, and more
- GPU Acceleration — All field operations use PyTorch tensors on CUDA/MPS
- Differentiable CFD —
torch.autogradsupport through custom autograd functions - OpenFOAM Compatible — Read/write existing OpenFOAM cases natively
- 408+ Boundary Conditions — Velocity, pressure, turbulence, VOF, thermal
- Full Turbulence Library — RANS (k-epsilon, k-omega SST, S-A, v2f), LES (Smagorinsky, WALE), DES
- Mesh Tools — blockMesh, snappyHexMesh, gmsh/fluent/VTK converters
- MPI Parallel — Domain decomposition, halo exchange, parallel I/O
- Lagrangian Particle Tracking — Injection, collision, breakup, evaporation models
- Multiphase VOF/MULES — Interface compression, cavitation models, interfacial forces
- Structural Mechanics — Displacement solver, elastic models
- Rigid Body Dynamics — Joints, restraints, motion solvers
- Wave Models — Airy, Stokes, Cnoidal wave theories
- Comprehensive Tools — checkMesh, setFields, renumberMesh, foamToVTK, and more
OpenFOAM reference simulation data and Docker image are available on HuggingFace:
AlanZee/pyOpenFOAM-reference-data
| File | Size | Description |
|---|---|---|
openfoam-reference-data.tar.gz |
2.42 GB | 257 OpenFOAM reference cases (96% of v13 tutorials) |
pyopenfoam-simulation-results.tar.gz |
47 KB | pyOpenFOAM validation results (34 JSON files) |
| Docker image | 622 MB | OpenFOAM-13 compiled environment (122 libs, 9 binaries) |
from huggingface_hub import hf_hub_download
import tarfile
path = hf_hub_download(
repo_id="AlanZee/pyOpenFOAM-reference-data",
filename="openfoam-reference-data.tar.gz",
repo_type="dataset"
)
with tarfile.open(path, "r:gz") as tar:
tar.extractall("validation/reference/openfoam/")- Python ≥ 3.10
- PyTorch ≥ 2.0
- NumPy ≥ 1.24
- SciPy ≥ 1.10
git clone https://github.com/alanZee/pyOpenFOAM.git
cd pyOpenFOAM
pip install -r requirements.txt
pip install -e .# CUDA 12.1
pip install torch --index-url https://download.pytorch.org/whl/cu121
# Apple Silicon (MPS)
pip install torch # MPS support built-infrom pyfoam.applications import SimpleFoam
solver = SimpleFoam("tutorials/incompressible/simpleFoam/pitzDaily")
solver.run()from pyfoam.core import device_context
with device_context("cuda"):
mesh = FvMesh.from_poly_mesh(poly_mesh)
solver = SIMPLESolver(mesh, config)
U, p, phi, info = solver.solve(U, p, phi)from pyfoam.differentiable import DifferentiableLaplacian, DifferentiableLinearSolve
# Differentiable Laplacian (supports torch.autograd)
lap = DifferentiableLaplacian.apply(phi, mesh)
# Differentiable linear solve (implicit differentiation)
x = DifferentiableLinearSolve.apply(A, b, tol, max_iter)pyfoam/
├── core/ # Device management, LDU/FvMatrix, sparse ops, multi-GPU
├── io/ # OpenFOAM file format I/O (ASCII + binary), VTK/Gmsh/Fluent
├── mesh/ # PolyMesh, FvMesh, mesh generation (blockMesh, snappyHexMesh)
├── fields/ # volScalarField, volVectorField, surfaceScalarField
├── boundary/ # 408+ BC types (velocity, pressure, turbulence, VOF, thermal)
├── discretisation/ # fvm/fvc operators, interpolation schemes
├── solvers/ # PCG, PBiCGSTAB, GAMG, SIMPLE/SIMPLEC/PISO/PIMPLE
├── turbulence/ # RANS, LES, DES models + wall functions (100+ variants)
├── thermophysical/ # Perfect gas, Sutherland, JANAF, psi/rho-based thermo
├── multiphase/ # VOF + MULES, interFoam, Euler-Euler, cavitation
├── parallel/ # MPI decomposition, halo exchange, parallel I/O
├── applications/ # 130+ solvers (incompressible, compressible, multiphase, thermal)
├── tools/ # checkMesh, setFields, renumberMesh, foamToVTK, etc.
├── postprocessing/ # FunctionObject framework, forces, y+, VTK output
├── differentiable/ # Differentiable operators, linear solver, SIMPLE
├── lagrangian/ # Particle tracking, injection, collision, breakup, evaporation
├── waves/ # Airy, Stokes, Cnoidal wave models
├── fv/ # fvModels (sources) + fvConstraints
├── ode/ # ODE solvers (Euler, RK4, RKF45, Rosenbrock)
├── rigid_body/ # Rigid body dynamics, joints, restraints
├── structural/ # Structural mechanics (displacement solver, elastic models)
├── models/ # Physical models (radiation)
└── utils/ # Shared utilities
| Category | Solvers |
|---|---|
| Incompressible | simpleFoam, icoFoam, pisoFoam, pimpleFoam, SRFSimpleFoam, porousSimpleFoam, boundaryFoam |
| Compressible | rhoSimpleFoam, rhoPimpleFoam, sonicFoam, rhoCentralFoam |
| Buoyancy | buoyantSimpleFoam, buoyantPimpleFoam, buoyantBoussinesqSimpleFoam |
| Thermal | laplacianFoam, chtMultiRegionFoam |
| Multiphase | interFoam, multiphaseInterFoam, compressibleInterFoam, twoPhaseEulerFoam, multiphaseEulerFoam, cavitatingFoam |
| Other | potentialFoam, scalarTransportFoam, reactingFoam, solidDisplacementFoam |
| Optimization | adjointFoam, adjointShapeOptimizationFoam, adjointTurbulenceFoam |
| Acoustics | acousticFoam |
13 benchmark cases defined against analytical solutions and published experimental/numerical data:
| Case | Solver | Accuracy | Reference |
|---|---|---|---|
| Couette Flow | icoFoam | 0.001% (internal) | Couette analytical solution |
| Poiseuille Flow | icoFoam | 0.02% (internal) | Hagen-Poiseuille analytical solution |
| Lid-Driven Cavity (Re=100) | icoFoam | 0.9% (20x20) / 1.0% (32x32) | Ghia et al. 1982 |
| Taylor-Green Vortex | icoFoam | — | Taylor & Green 1937 |
| Backward Facing Step | simpleFoam | — | Driver & Seegmiller 1985 |
| Sod Shock Tube | rhoCentralFoam | — | Sod 1978 |
| Natural Convection (Ra=10^5) | buoyantBoussinesqSimpleFoam | — | de Vahl Davis 1983 |
| Dam Break | interFoam | — | Martin & Moyce 1952 |
| Turbulent Channel (Re_tau=180) | simpleFoam + kOmegaSST | — | Moser, Kim & Mansour 1999 |
| Compressible Nozzle | rhoCentralFoam | — | Isentropic nozzle theory |
| Laminar Cylinder (Re=20) | icoFoam | — | Dennis & Chang 1970 |
| Cylinder Flow (Re=100) | pisoFoam | — | Williamson 1996 |
| Turbulent Duct (Re=10000) | simpleFoam + kOmegaSST | — | Petukhov 1970 |
python validation/run_all.py# Run all tests
pytest tests/unit/ -q --tb=no
# Specific module
pytest tests/unit/solvers/ -qResults: 17,130 passed, 2 xfailed (~410 seconds)
| Document | Description |
|---|---|
| API Index | 24 modules overview, class counts, usage examples, RTS pattern |
| Module API Reference | Detailed API for all public classes and functions |
| Getting Started (en) | Installation, quick start, GPU guide |
| Getting Started (zh) | Installation, quick start, GPU guide (Chinese) |
| Migration Guide | OpenFOAM to pyOpenFOAM mapping (Chinese) |
| Migration Guide (en) | OpenFOAM to pyOpenFOAM mapping (English) |
| Architecture | Top-level architecture and design decisions |
| GPU Guide | GPU acceleration and multi-GPU usage |
| PROPOSAL.md | Requirements, goals, benchmarks, solver list |
| DESIGN.md | Top-level architecture and design decisions |
| ROADMAP.md | Future plans and remaining work |
| Validation Report | Comprehensive 257-case validation with 8 figures |
| Per-Case Data | JSON data for all 257 reference cases |
We welcome contributions! Priority areas:
- Validation — Help us validate against OpenFOAM
- Differentiability — Extend autograd support
- Performance — Optimize GPU memory and computation
- Documentation — Improve tutorials and examples
pyOpenFOAM is licensed under the GNU General Public License v3.0.
Built for the CFD and Python communities
