foamlib 0.8.7__tar.gz → 0.8.9__tar.gz

{foamlib-0.8.7 → foamlib-0.8.9}/.github/workflows/ci.yml

@@ -28,14 +28,14 @@ jobs:
     - name: Checkout
       uses: actions/checkout@v4
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
         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
@@ -74,7 +74,7 @@ jobs:
       with:
         openfoam-version: ${{ matrix.openfoam-version }}
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
@@ -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
@@ -103,7 +103,7 @@ jobs:
     - name: Checkout
       uses: actions/checkout@v4
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
     - name: Check package build
       run: |
         uv build

{foamlib-0.8.7 → foamlib-0.8.9}/.github/workflows/pypi-publish.yml

@@ -17,7 +17,7 @@ jobs:
     - name: Checkout
       uses: actions/checkout@v4
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
     - name: Build
       run: uv build
     - name: Publish to PyPI

foamlib-0.8.9/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
+```

{foamlib-0.8.7 → foamlib-0.8.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foamlib
-Version: 0.8.7
+Version: 0.8.9
 Summary: A Python interface for interacting with OpenFOAM
 Project-URL: Homepage, https://github.com/gerlero/foamlib
 Project-URL: Repository, https://github.com/gerlero/foamlib
@@ -27,32 +27,38 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.7
 Requires-Dist: aioshutil<2,>=1
 Requires-Dist: numpy<3,>=1
-Requires-Dist: numpy<3,>=1.25.0; python_version >= '3.10'
 Requires-Dist: pyparsing<4,>=3.1.2
-Requires-Dist: rich<14,>=13
+Requires-Dist: rich<15,>=13
 Requires-Dist: typing-extensions<5,>=4; python_version < '3.11'
 Provides-Extra: dev
 Requires-Dist: mypy<2,>=1; extra == 'dev'
-Requires-Dist: pytest-asyncio<0.26,>=0.21; extra == 'dev'
+Requires-Dist: pytest-asyncio<0.27,>=0.21; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest<9,>=7; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: scipy-stubs; (python_version >= '3.10') and extra == 'dev'
+Requires-Dist: scipy<2,>=1; extra == 'dev'
 Requires-Dist: sphinx-rtd-theme; extra == 'dev'
 Requires-Dist: sphinx<9,>=5; extra == 'dev'
 Provides-Extra: docs
+Requires-Dist: ruff; extra == 'docs'
 Requires-Dist: sphinx-rtd-theme; extra == 'docs'
 Requires-Dist: sphinx<9,>=5; extra == 'docs'
 Provides-Extra: lint
 Requires-Dist: ruff; extra == 'lint'
 Provides-Extra: test
-Requires-Dist: pytest-asyncio<0.26,>=0.21; extra == 'test'
+Requires-Dist: mypy<2,>=1; extra == 'test'
+Requires-Dist: pytest-asyncio<0.27,>=0.21; extra == 'test'
 Requires-Dist: pytest-cov; extra == 'test'
 Requires-Dist: pytest<9,>=7; extra == 'test'
+Requires-Dist: scipy<2,>=1; extra == 'test'
 Provides-Extra: typing
 Requires-Dist: mypy<2,>=1; extra == 'typing'
-Requires-Dist: pytest-asyncio<0.26,>=0.21; extra == 'typing'
+Requires-Dist: pytest-asyncio<0.27,>=0.21; extra == 'typing'
 Requires-Dist: pytest-cov; extra == 'typing'
 Requires-Dist: pytest<9,>=7; extra == 'typing'
+Requires-Dist: scipy-stubs; (python_version >= '3.10') and extra == 'typing'
+Requires-Dist: scipy<2,>=1; extra == 'typing'
 Description-Content-Type: text/markdown
 
 [<img alt="foamlib" src="https://github.com/gerlero/foamlib/raw/main/logo.png" height="65">](https://github.com/gerlero/foamlib)
@@ -73,11 +79,18 @@ Description-Content-Type: text/markdown
 
 **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
 
@@ -208,6 +221,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).