Merge branch 'main' into joss

Author: gerlero

.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
         python-version-file: pyproject.toml
     - name: Check types with mypy
       run: |
-        uv run --extra typing mypy
+        uv run mypy
 
   test:
     runs-on: ubuntu-22.04
@@ -49,11 +49,11 @@ jobs:
         options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3
     strategy:
       matrix:
-        openfoam-version: [2406, 2006, 12, 9]
+        openfoam-version: [2412, 2006, 12, 9]
         python-version: ['3.7', '3.8', '3.9', '3.10', '3.11', '3.12', '3.13']
         slurm: [false]
         include:
-          - openfoam-version: 2406
+          - openfoam-version: 2412
             python-version: '3.13'
             slurm: true
           - openfoam-version: 12
@@ -84,7 +84,7 @@ jobs:
       uses: koesterlab/setup-slurm-action@v1
     - name: Install test dependencies
       run: |
-        uv sync --extra test
+        uv sync
     - name: Test with pytest
       run: |
         uv run pytest --cov=foamlib --cov-report xml

.github/workflows/docker.yml

@@ -80,7 +80,7 @@ jobs:
       packages: write
     strategy:
       matrix:
-        openfoam-version: [2406, 2312, 12, 11]
+        openfoam-version: [2412, 2406, 12, 11]
       fail-fast: false
     steps:
       - name: Set up QEMU

CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing
+
+## Setup
+
+1. [Fork the repository on GitHub](https://github.com/gerlero/foamlib/fork)
+
+1. Clone your fork locally
+
+```bash
+git clone https://github.com/<your_username>/foamlib.git
+```
+
+2. Install the project in editable mode in a virtual environment
+
+```bash
+cd foamlib
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+```
+
+## Contributing changes via a pull request
+
+1. Create a new branch for your changes
+
+```bash
+git checkout -b my-new-feature
+```
+
+2. Make your changes
+
+3. Test your changes (see below for instructions)
+
+4. Commit your changes
+
+```bash
+git add .
+git commit -m "Add some feature"
+```
+
+5. Push your changes to your fork
+
+```bash
+git push origin my-new-feature
+```
+
+6. [Open a pull request on GitHub](https://github.com/gerlero/foamlib/compare)
+
+
+## Checks
+
+The following checks will be run by the CI pipeline, so it is recommended to run them locally before opening a pull request.
+
+### Testing
+
+Run the tests with:
+
+```bash
+pytest
+```
+
+### Type checking
+
+Type check the code with:
+
+```bash
+mypy
+```
+
+### Linting
+
+Lint the code with:
+
+```bash
+ruff check
+```
+
+### Formatting
+
+Format the code with:
+
+```bash
+ruff format
+```
+
+### Documentation
+
+Generate the documentation locally with:
+
+```bash
+cd docs
+make html
+```

Dockerfile

@@ -1,7 +1,7 @@
 
 ARG BASE=python:3.12-slim
 
-ARG OPENFOAM_VERSION=2406
+ARG OPENFOAM_VERSION=2412
 FROM microfluidica/openfoam:${OPENFOAM_VERSION} AS openfoam
 
 ARG VIRTUAL_ENV=/opt/venv

README.md

@@ -16,11 +16,18 @@
 
 **foamlib** provides a simple, modern, ergonomic and fast Python interface for interacting with [OpenFOAM](https://www.openfoam.com).
 
-<p align="center">
-    <img alt="benchmark" src="https://github.com/gerlero/foamlib/raw/main/benchmark.png" height="250">
-    <br>
-  <i>Parsing a </i>volVectorField<i> with 200k cells.</i>
-</p>
+<div align="center">
+<img alt="benchmark" src="https://github.com/gerlero/foamlib/raw/main/benchmark/benchmark.png" height="250">
+
+Parsing a volVectorField with 200k cells.<sup>[1](#benchmark)</sup>
+</div>
+
+
+## 🚀 Introduction
+
+**foamlib** is a Python package designed to simplify the manipulation of OpenFOAM cases and files. Its standalone parser makes it easy to work with OpenFOAM’s input/output files from Python, while its case-handling capabilities facilitate various execution workflows—reducing boilerplate code and enabling efficient Python-based pre- and post-processing, as well as simulation management.
+
+Compared to [PyFoam](https://openfoamwiki.net/index.php/Contrib/PyFoam) and other similar tools like [fluidfoam](https://github.com/fluiddyn/fluidfoam), [fluidsimfoam](https://foss.heptapod.net/fluiddyn/fluidsimfoam), and [Ofpp](https://github.com/xu-xianghua/ofpp), **foamlib** offers advantages such as modern Python compatibility, support for binary-formatted fields, a fully type-hinted API, and asynchronous operations; making OpenFOAM workflows more accessible and streamlined.
 
 ## 👋 Basics
 
@@ -151,6 +158,159 @@ case = FoamCase(Path(__file__).parent)
 case.run()
 ```
 
-## 📘 Documentation
+## ▶️ A complete example
+
+The following is a fully self-contained example that demonstrates how to create an OpenFOAM case from scratch, run it, and analyze the results.
+
+<details>
+
+<summary>Example</summary>
+
+```python
+#!/usr/bin/env python3
+"""Check the diffusion of a scalar field in a scalarTransportFoam case."""
+
+import shutil
+from pathlib import Path
+
+import numpy as np
+from scipy.special import erfc
+from foamlib import FoamCase
+
+path = Path(__file__).parent / "diffusionCheck"
+shutil.rmtree(path, ignore_errors=True)
+path.mkdir(parents=True)
+(path / "system").mkdir()
+(path / "constant").mkdir()
+(path / "0").mkdir()
+
+case = FoamCase(path)
+
+with case.control_dict as f:
+    f["application"] = "scalarTransportFoam"
+    f["startFrom"] = "latestTime"
+    f["stopAt"] = "endTime"
+    f["endTime"] = 5
+    f["deltaT"] = 1e-3
+    f["writeControl"] = "adjustableRunTime"
+    f["writeInterval"] = 1
+    f["purgeWrite"] = 0
+    f["writeFormat"] = "ascii"
+    f["writePrecision"] = 6
+    f["writeCompression"] = False
+    f["timeFormat"] = "general"
+    f["timePrecision"] = 6
+    f["adjustTimeStep"] = False
+    f["runTimeModifiable"] = False
+
+with case.fv_schemes as f:
+    f["ddtSchemes"] = {"default": "Euler"}
+    f["gradSchemes"] = {"default": "Gauss linear"}
+    f["divSchemes"] = {"default": "none", "div(phi,U)": "Gauss linear", "div(phi,T)": "Gauss linear"}
+    f["laplacianSchemes"] = {"default": "Gauss linear corrected"}
+
+with case.fv_solution as f:
+    f["solvers"] = {"T": {"solver": "PBiCG", "preconditioner": "DILU", "tolerance": 1e-6, "relTol": 0}}
+
+with case.block_mesh_dict as f:
+    f["scale"] = 1
+    f["vertices"] = [
+        [0, 0, 0],
+        [1, 0, 0],
+        [1, 0.5, 0],
+        [1, 1, 0],
+        [0, 1, 0],
+        [0, 0.5, 0],
+        [0, 0, 0.1],
+        [1, 0, 0.1],
+        [1, 0.5, 0.1],
+        [1, 1, 0.1],
+        [0, 1, 0.1],
+        [0, 0.5, 0.1],
+    ]
+    f["blocks"] = [
+        "hex", [0, 1, 2, 5, 6, 7, 8, 11], [400, 20, 1], "simpleGrading", [1, 1, 1],
+        "hex", [5, 2, 3, 4, 11, 8, 9, 10], [400, 20, 1], "simpleGrading", [1, 1, 1],
+    ]
+    f["edges"] = []
+    f["boundary"] = [
+        ("inletUp", {"type": "patch", "faces": [[5, 4, 10, 11]]}),
+        ("inletDown", {"type": "patch", "faces": [[0, 5, 11, 6]]}),
+        ("outletUp", {"type": "patch", "faces": [[2, 3, 9, 8]]}),
+        ("outletDown", {"type": "patch", "faces": [[1, 2, 8, 7]]}),
+        ("walls", {"type": "wall", "faces": [[4, 3, 9, 10], [0, 1, 7, 6]]}),
+        ("frontAndBack", {"type": "empty", "faces": [[0, 1, 2, 5], [5, 2, 3, 4], [6, 7, 8, 11], [11, 8, 9, 10]]}),
+    ]
+    f["mergePatchPairs"] = []
+
+with case.transport_properties as f:
+    f["DT"] = f.Dimensioned(1e-3, f.DimensionSet(length=2, time=-1), "DT")
+
+with case[0]["U"] as f:
+    f.dimensions = f.DimensionSet(length=1, time=-1)
+    f.internal_field = [1, 0, 0]
+    f.boundary_field = {
+        "inletUp": {"type": "fixedValue", "value": [1, 0, 0]},
+        "inletDown": {"type": "fixedValue", "value": [1, 0, 0]},
+        "outletUp": {"type": "zeroGradient"},
+        "outletDown": {"type": "zeroGradient"},
+        "walls": {"type": "zeroGradient"},
+        "frontAndBack": {"type": "empty"},
+    }
+
+with case[0]["T"] as f:
+    f.dimensions = f.DimensionSet(temperature=1)
+    f.internal_field = 0
+    f.boundary_field = {
+        "inletUp": {"type": "fixedValue", "value": 0},
+        "inletDown": {"type": "fixedValue", "value": 1},
+        "outletUp": {"type": "zeroGradient"},
+        "outletDown": {"type": "zeroGradient"},
+        "walls": {"type": "zeroGradient"},
+        "frontAndBack": {"type": "empty"},
+    }
+
+case.run()
+
+x, y, z = case[0].cell_centers().internal_field.T
+
+end = x == x.max()
+x = x[end]
+y = y[end]
+z = z[end]
+
+DT = case.transport_properties["DT"].value
+U = case[0]["U"].internal_field[0]
+
+for time in case[1:]:
+    if U*time.time < 2*x.max():
+        continue
+
+    T = time["T"].internal_field[end]
+    analytical = 0.5 * erfc((y - 0.5) / np.sqrt(4 * DT * x/U))
+    if np.allclose(T, analytical, atol=0.1):
+        print(f"Time {time.time}: OK")
+    else:
+        raise RuntimeError(f"Time {time.time}: {T} != {analytical}")
+```
+
+</details>
+
+
+## 📘 API documentation
+
+For more information on how to use **foamlibs**'s classes and methods, check out the [documentation](https://foamlib.readthedocs.io/).
+
+## 🙋 Support
+
+If you have any questions or need help, feel free to open a [discussion](https://github.com/gerlero/foamlib/discussions).
+
+If you believe you have found a bug in **foamlib**, please open an [issue](https://github.com/gerlero/foamlib/issues).
+
+## 🧑‍💻 Contributing
+
+You're welcome to contribute to **foamlib**! Check out the [contributing guidelines](CONTRIBUTING.md) for more information.
+
+## Footnotes
 
-For more information, check out the [documentation](https://foamlib.readthedocs.io/).
+<a id="benchmark">[1]</a> foamlib 0.8.1 vs PyFoam 2023.7 on a MacBook Air (2020, M1) with 8 GB of RAM. [Benchmark script](benchmark/benchmark.py).

benchmark.png benchmark/benchmark.pngbenchmark.png renamed to benchmark/benchmark.png

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+
+"""Benchmark foamlib against PyFoam."""
+
+import timeit
+
+from foamlib import FoamFieldFile
+from PyFoam.RunDictionary.ParsedParameterFile import ParsedParameterFile
+
+FoamFieldFile("U").internal_field = [[0.0, 0.0, 0.0]] * 200_000
+
+print(
+    f"foamlib: {min(timeit.repeat(lambda: FoamFieldFile('U').internal_field, number=1))} s"
+)
+print(
+    f"PyFoam: {min(timeit.repeat(lambda: ParsedParameterFile('U')['internalField'], number=1))} s"
+)

benchmark/benchmark.py

@@ -0,0 +1,2 @@
+foamlib==0.8.1
+PyFoam==2023.7

benchmark/requirements.txt

@@ -0,0 +1,4 @@
+extend = "../pyproject.toml"
+
+[lint]
+extend-ignore = ["T201"]

benchmark/ruff.toml

@@ -1,6 +1,6 @@
 """A Python interface for interacting with OpenFOAM."""
 
-__version__ = "0.8.4"
+__version__ = "0.8.8"
 
 from ._cases import (
     AsyncFoamCase,