pybFoam 0.2.0

python bindings for OpenFOAM

pybFoam

Python bindings for OpenFOAM - enabling direct manipulation of OpenFOAM cases, fields, and meshes from Python.

Currently in the pre-alpha release state.

---

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.9 or higher
• CMake: 3.18 or higher
• C++ Compiler: C++17 compatible (TBD)
• Build tools: pybind11, scikit-build-core
• Python packages: numpy, pydantic

---

Installation

Prerequisites

1. Source your OpenFOAM environment:

   source /path/to/OpenFOAM/etc/bashrc
   

2. (Recommended) Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate
   

Install from source

pip install .

For development:

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:

1. Generates stubs using pybind11-stubgen
2. Cleans and formats the stubs
3. Copies them to the source directory
4. 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)

Dictionary I/O with Pydantic

from pybFoam.io import IOModelBase
from pydantic import Field

class TransportProperties(IOModelBase):
    nu: float = Field(..., description="Kinematic viscosity")

    class Config:
        foam_file_name = "transportProperties"

# Read from OpenFOAM dictionary
props = TransportProperties.from_file("constant/transportProperties")
print(f"Viscosity: {props.nu}")

# Modify and write back
props.nu = 1e-5
props.to_file("constant/transportProperties")

---

Examples

See the tests/ directory for more examples:

• Basic field operations: tests/pybind/test_primitives.py
• Finite volume operators: tests/pybind/test_fvc.py, tests/pybind/test_fvm.py
• Surface sampling: tests/pybind/test_surface_sampling.py
• Line sampling: tests/pybind/test_set_sampling.py
• Solver example: tests/cavity/icoFoam.py

---

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

---

Documentation (outdated)

Full documentation is available at: https://henningscheufler.github.io/pybFoam/

---

Development Setup

1. Clone the repository
2. Install development dependencies:

   pip install -e ".[dev]"
   # or build with stubs
   pip install -e .[all] -C cmake.define.ENABLE_PYBFOAM_STUBS=ON -v
   

3. Run tests before committing:

   pytest tests/
   

---

License

See LICENSE file for details.

---