pybFoam
Python bindings for OpenFOAM - enabling direct manipulation of OpenFOAM cases, fields, and meshes from Python.
Documentation — tutorials, how-to guides (generated from runnable examples), API reference, and design notes.
Build the docs locally:
uv sync --extra docs
cd docs && uv run make html
# open docs/_build/html/index.html
Features
- Direct Python access to OpenFOAM data structures: Time, fvMesh, fields
- Finite volume operators: fvc (calculus), fvm (matrix operations)
- Turbulence and thermodynamic models: Access to OpenFOAM turbulence and thermo libraries
- Sampling and post-processing: Surface sampling, line sampling, interpolation
- Pydantic configuration models: Type-safe dictionary construction for sampling surfaces
- NumPy integration: Zero-copy access to OpenFOAM field data via buffer protocol
Requirements
- OpenFOAM: v2312 or higher (sourced and installed)
- Python: 3.11 or higher
- CMake: 3.18 or higher
- C++ Compiler: C++17 compatible (GCC 7+, Clang 5+)
- Build tools: nanobind, scikit-build-core
- Build tools: ninja
- Python packages: numpy, pydantic
Installation
Prerequisites
-
Source your OpenFOAM environment:
source /path/to/OpenFOAM/etc/bashrc
-
(Recommended) Create a virtual environment:
python -m venv .venv source .venv/bin/activate
Install from source
CC="$(wmake -show-path-c)" CXX="$(wmake -show-path-cxx)" pip install .
For development:
CC="$(wmake -show-path-c)" CXX="$(wmake -show-path-cxx)" pip install -e .[all]
Generating Type Stubs (Development only)
Type stubs (.pyi files) are generated post-installation using a separate script:
# Install the package first
uv pip install -e .[all]
# Generate and verify stubs
./scripts/generate_stubs.sh
This script:
- Generates stubs using pybind11-stubgen
- Cleans and formats the stubs
- Copies them to the source directory
- Verifies them with mypy
Quick Start
Basic Usage
import pybFoam as pf
# Create OpenFOAM time and mesh
time = pf.Time(".", ".")
mesh = pf.fvMesh(time)
# Access fields
p_rgh = pf.volScalarField.read_field(mesh, "p_rgh")
U = pf.volVectorField.read_field(mesh, "U")
# Compute gradients using finite volume calculus
grad_p = pf.fvc.grad(p_rgh)
div_U = pf.fvc.div(U)
# Convert to NumPy arrays for analysis
import numpy as np
p_array = np.asarray(p_rgh["internalField"])
print(f"Pressure range: {p_array.min():.3f} to {p_array.max():.3f}")
Sampling Surfaces
from pybFoam.sampling import SampledPlaneConfig, sampledSurface, interpolationScalar
from pybFoam import Word
# Create a sampling plane using Pydantic config
plane_config = SampledPlaneConfig(point=[0.5, 0.5, 0.0], normal=[1.0, 0.0, 0.0])
# Create the surface
plane = sampledSurface.New(Word("myPlane"), mesh, plane_config.to_foam_dict())
plane.update()
# Interpolate field onto surface
interp = interpolationScalar.New(Word("cellPoint"), p)
sampled_values = interp.sampleOnFaces(plane)
Read OpenFOAM dictionaries
from pybFoam import Word, dictionary
d = dictionary.read("system/controlDict")
# Typed accessors — a typo in the key raises at the call site
application = d.get[Word]("application")
end_time = d.get[float]("endTime")
max_co = d.getOrDefault[float]("maxCo", 0.5)
# Nested subdictionaries and key enumeration
piso = d.subDict("PISO")
for name in d.toc():
print(name)
Examples
Runnable, self-contained scripts live under examples/. They are
executed at documentation build time and rendered as the tutorials and
how-to guides on the docs site.
- Tutorials (
examples/tutorials/) — end-to-end walkthroughs that build on each other:example_01_getting_started.py— open a case, read a field, NumPy viewexample_02_field_analysis.py— drive a time loop and summarise per-step statisticsexample_03_sampling_workflow.py— sample a plane, export to CSV
- How-to guides (
examples/how-to/) — task-focused recipes:example_read_dictionaries.py— controlDict / typed entriesexample_blockmesh.py—generate_blockmesh+checkMeshexample_fvc_fvm_operators.py— gradient / divergence / Laplacian and implicit matrix termsexample_sample_plane.py,example_sample_line.py
- Case data —
examples/case/andexamples/cavity/are read-only baseline cases consumed by the scripts above. - Solver example —
examples/cavity/icoFoam.py(full PISO loop driven from Python).
More tests with additional API usage live under tests/pybind/.
Testing
Run the test suite:
pytest tests/
Run specific test categories:
pytest tests/pybind/ # C++ binding tests
pytest tests/test_sampling_models.py # Pydantic config tests
Development Setup
- Clone the repository
- Install development dependencies:
pip install -e ".[dev]" # or build with stubs pip install -e .[all] -C cmake.define.ENABLE_PYBFOAM_STUBS=ON -v
- Run tests before committing:
pytest tests/
License
See LICENSE file for details.
Metadata
Release files for pybFoam 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pybfoam-0.6.0.tar.gz | 7.8 MB | Without provenance | Details for pybfoam-0.6.0.tar.gz |
Release files / pybfoam-0.6.0.tar.gz
| Download URL | pybfoam-0.6.0.tar.gz |
|---|---|
| Size | 7.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cb5f6e200100c8caca6d5a6f9ad9ace35c1acae494c1ef1b8605eb6f5ab2bc5a
|
|
BLAKE2b-256 checksum How to use checksums |
b0716638503748e919218309b83bc3ea118f69cdea1c4b1fb26025e2ea393f52
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Security for pybFoam 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.