The project is hosted on Don’t look for a fork button because it does not exist. To contribute, the first step is to open an issue on our bug tracker so that we give you the needed rights on the repo.

Installation for development#

After installing PDM (for example with something like pipx install pdm, but check the other recommended install methods), the following commands should install and activate the virtual environment:

hg clone
cd fluidsimfoam
pdm sync

Version control#

We use Mercurial and the development is hosted on See

Testing and coverage#

We use pytest and ipdb (which are installed automatically by pdm). The command make test run the tests of the project. Here are some examples of other useful commands:

pytest tests -x
alias pytest-ipdb=pytest --pdb --pdbcls=IPython.terminal.debugger:TerminalPdb
pytest-ipdb -vv tests/

To study the test coverage, one can run make cov or something like:

pytest tests doc/examples --cov --cov-report term --cov-report html
firefox htmlcov/index.html


ipdb is quite convenient. Export the environment variable PYTHONBREAKPOINT (for example add export PYTHONBREAKPOINT=ipdb.set_trace in your .bashrc) and add breakpoint() somewhere in the code.


We use Black and isort to format the Python code. One can run make format and make test before committing.

Documentation and tutorials#

The documentation is produced with Sphinx and MyST. The source is in the doc directory and in the docstrings. The website is built (for each push in the default branch) and hosted on ReadTheDocs.

To build the documentation locally:

cd doc

The tutorials are written in files and executed during the build. .ipynb files are never version controlled in the repository.


OpenFOAM (v1912) is installed on ReadTheDocs servers with the official Ubuntu apt package. With this package no compilation for OpenFOAM simulation is possible, so no codeStream. Fortunatelly, one can already do a lot of things with Fluidsimfoam without compilation!

To write tutorials, one can modify the files with your favorite editor or open these files with JupyterLab: run jupyter-lab and then click right on the icon representing the file and click on Open With > Notebook. JupyterLab will save the input of the notebook in the file.

The source of the documentation should be formatted with mdformat. Running make format from the doc directory should format all files.


For now, we push on PyPI manually:

hg pull
hg up default
hg tag 0.0.7
hg push
rm -rf dist
python -m build
twine upload dist/*