pympdata logo

Documentation

What is PyMPDATA?

PyMPDATA is a Numba-accelerated multi-threaded Pythonic implementation of the MPDATA algorithm of Smolarkiewicz et al. used in geophysical fluid dynamics and beyond for numerically solving generalised convection-diffusion PDEs. PyMPDATA supports integration in 1D, 2D and 3D structured meshes with optional coordinate transformations. The animation shown depicts a "hello-world" 2D advection-only simulation with dotted lines indicating domain decomposition across three threads.

A separate project called PyMPDATA-MPI depicts how numba-mpi can be used to enable distributed memory parallelism in PyMPDATA.

What is the difference between PyMPDATA and PyMPDATA-examples?

PyMPDATA is a Python package that provides the MPDATA algorithm implementation. It is a library that can be used in your own projects.

PyMPDATA-examples is a Python package that provides examples of how to use PyMPDATA. It includes common Python modules used in PyMPDATA smoke tests and in example Jupyter notebooks (but the package wheels do not include the notebooks, only .py files imported from the notebooks and PyMPDATA tests).

The two projects exist separately on PyPI, but their development and issue tracking is hosted at the same GitHub repository.

Important links

PyMPDATA PyMPDATA-examples PyMPDATA-MPI

Installation

PyMPDATA is available on PyPI and can be installed using pip: 

pip install PyMPDATA

Note: the way above will not install PyMPDATA-examples, to install them, and run the tests, likely the most convenient way is:

git clone https://github.com/open-atmos/PyMPDATA.git
pip install -e PyMPDATA[tests] -e PyMPDATA/examples[tests]
pytest PyMPDATA

(the above should be a viable way to set up development environment for PyMPDATA, see also our Python dev hints Wiki for further information)

PyMPDATA-examples is available on PyPI and can be installed using pip: 

pip install PyMPDATA-examples

Note: this will also install PyMPDATA if needed, but the examples package wheels do not include the Jupyter notebooks - only common code used from the notebooks. All PyMPDATA example notebooks can be viewed on GitHub and feature header cells with badges enabling single-click execution on either Google Colab or mybinder.org platforms. To try the notebooks out locally, use: 

git clone https://github.com/open-atmos/PyMPDATA.git
pip install -e PyMPDATA -e PyMPDATA/examples
jupyter-notebook PyMPDATA/examples

Dependencies

PyMPDATA depends on NumPy, Numba and pystrict.

PyMPDATA-examples requires additional packages listed in install_requires in setup.py. Amongst them is PyMPDATA.

Contributing, reporting issues and seeking support

Submitting new code to both packages is done through the same GitHub repository via Pull requests.

Issues regarding any incorrect, unintuitive or undocumented behaviour of PyMPDATA or PyMPDATA-examples are best to be reported on the GitHub issue tracker.

We encourage to use the GitHub Discussions feature (rather than the issue tracker) for seeking support in understanding, using and extending PyMPDATA code.

Licensing, credits, acknowledgements

PyMPDATA and PyMPDATA-examples are free/libre open-source software packages released under the GNU GPL v3 license.

Development of PyMPDATA was started by Piotr Bartman[-Szwarc], Sylwester Arabas and collaborators at the Jagiellonian University in Kraków. For an overview of features of the initial release, see the 2022 PyMPDATA v1 JOSS paper. See list of code committers for a complete list of contributors.

Development of PyMPDATA was supported by: