Revise README.md

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
+```

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
 
@@ -154,3 +161,17 @@ case.run()
 ## 📘 Documentation
 
 For more information, 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
+
+<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/benchmark.py

@@ -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/requirements.txt

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

benchmark/ruff.toml

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