v2606: Plugins

This release introduces Python bindings for OpenFOAM, called pybFoam, developed by Henning Scheufler. Many thanks for this contribution!

Python has gained increasing relevance for scientific computing, data analysis, machine learning, and as general-purpose glue for workflows. Many of the methods becoming increasingly relevant to CFD are developed in this ecosystem, including data-driven turbulence closures, surrogate and reduced-order models, and physics-informed neural networks. The pybFoam project makes these methods more accessible and can serve as an entry point into the Python ecosystem. By including these bindings, we hope to encourage their use and provide a well-coordinated Python/OpenFOAM interface.

pybFoam is built on top of nanobind and exposes the OpenFOAM classes within Python. The following features are currently bound:

• Core types – Time, fvMesh, dictionary, and the volField and surfaceField families, with field data exposed directly to NumPy.
• Field operations – arithmetic and mathematical operations on fields, including cos, sin, and other element-wise functions.
• Finite-volume operators – fvc and fvm operators (grad, div, laplacian, ddt, and others) bound to the OpenFOAM implementation.
• Sampling – surface and line sampling with interpolation.
• Models – turbulence and thermophysical model bindings.
• Meshing – blockMesh, snappyHexMesh, and checkMesh.
• Embedded solver – an interpreter that can be embedded in a solver or library.

Below is an example of how to load the pressure field, compute its gradient, and create a NumPy view of the resulting field:

import pybFoam as pyb
import numpy as np

runTime = pyb.Time(".", ".")
mesh = pyb.fvMesh(runTime)
p = pyb.volScalarField.read_field(mesh, "p")

grad_p = pyb.fvc.grad(p)
np_p = np.asarray(p["internalField"])

Further documentation is provided on the external repository.

• Repository – https://github.com/HenningScheufler/pybFoam
• Documentation – https://henningscheufler.github.io/pybFoam/index.html

pyOFTools, also developed by Henning Scheufler, builds on the infrastructure provided by pybFoam and offers a base set of Python methods for interacting with OpenFOAM.

By using Python at both ends of a run – the pre-processing that prepares initial fields and the post-processing that extracts results – workflows become easier to express and extend.

The library is also intended to demonstrate the following:

• how to embed the Python interpreter in OpenFOAM and use it with pybFoam
• how to extend a library with custom bindings
• how a Python library on top of pybFoam can be packaged in the Python ecosystem

pyOFTools runs its post-processing within an OpenFOAM solver via a function object:

functions
{
    pyPostProcessing
    {
        libs            (embeddingPython);
        type            pyPostProcessing;
        writeControl    timeStep;
        writeInterval   1;
        pyFileName      postProcess;   // postProcess.py (no extension)
        pyClassName     postProcess;   // module-level PostProcessorBase instance
    }
}

This will load a user-defined Python file postProcess.py and call the class postProcess:

from pyOFTools.postprocessor import PostProcessorBase
from pyOFTools.builders import field
from pyOFTools.aggregators import VolIntegrate

postProcess = PostProcessorBase()

@postProcess.Table("water_volume.csv")
def water_volume(mesh):
    return field(mesh, "alpha.water") | VolIntegrate()

The decorator @postProcess.Table("water_volume.csv") defines the output format and file name. The function body loads a field from the registry using field(mesh, "alpha.water") and applies operations to it. In this case, | VolIntegrate() integrates alpha.water over the domain volume.

Additional Features

• surface datasets - plane(mesh, point, normal) or iso_surface(mesh, "alpha.water", 0.5), then pipe into area() or sample(mesh, field) and an aggregator, e.g. iso_surface(mesh, "alpha.water", 0.5) | area() | Sum().
• point datasets - line(mesh, name, start, end, n_points, field) samples a field along a line, e.g. line(mesh, "centreline", (0,0,0), (1,0,0), 100, "p") | Mean().
• Composable pipeline - spatial selectors (Box, Sphere, combined with & / | / ~), binners (Directional), and aggregators (Sum, Mean, VolIntegrate, SurfIntegrate) chain with the | operator and compose across dataset types.
• setFields in Python - prepare initial 0/ fields with the same geometric selectors used for post-processing, instead of setFieldsDict.
• Command-line interface - a pyoftools CLI: pyoftools setFields <spec> runs a .py or .json field spec against a case, plus pyoftools version.
• Sampling - surface and line/set sampling with interpolation, reusing the same selectors and aggregators as volume data.

More details can be found in the documentation.

• Repository - https://github.com/HenningScheufler/pyOFTools
• Documentation - https://henningscheufler.github.io/pyOFTools/index.html

This OpenFOAM release includes the first support for exporting OpenFOAM data to the new VTK-HDF data format.

This native VTK data format, properly supported by ParaView 6.1 and later, is based on HDF5 (Hierarchical Data Format). It eliminates the parsing overhead and data duplication associated with previous VTK formats, whether legacy or XML-based. The format provides true binary file capabilities that accelerate reading and enable greater flexibility for supporting the newest VTK data models and data compositions.

One of the longer-term benefits will be the reuse of static mesh geometries – something already possible with the Ensight formats but without requiring a separate parser. The format also opens up the possibility of adding data compression and other enhancements in future releases.

The initial bindings address the heaviest and most frequent data producers: volume geometry and fields.

Output does not yet support data compression during generation, but the HDF5 h5repack command can be used to apply compression afterwards.

The vtkhdfWrite function object

The new vtkhdfWrite function object is designed as a drop-in replacement for the existing vtkWrite function object, supporting all of the same keywords. The legacy and format keywords are accepted but silently ignored as they are not applicable to this format.

The relevant keywords for the vtkhdfWrite function object are:

{
   type    vtkhdfWrite;
   libs    (foam-vtkhdfWrite);
   ...
}

If sufficient interest emerges from this initial offering, further support for different OpenFOAM data generators, time-series data, and static geometries will be considered for a future release.

The foamToVTKHDF utility

As the name suggests, the foamToVTKHDF utility is the VTK-HDF counterpart to the foamToVTK utility. Its base functionality is largely identical, but currently only handles volume geometry and fields. Finite-area, Lagrangian, and special-purpose diagnostic dumps are not yet supported.

No associated tutorial examples are included, as both tools should work as drop-in replacements for their existing counterparts.