PyMPDATA

PyMPDATA is a high-performance Numba-accelerated Pythonic implementation of the MPDATA algorithm of Smolarkiewicz et al. used in geophysical fluid dynamics and beyond for numerically solving generalised convection-diffusion PDEs in 1D, 2D and 3D structured meshes with coordinate transformations.

In short, PyMPDATA numerically solves the following equation:

$$ \partial_t (G \psi) + \nabla \cdot (Gu \psi) + \mu \Delta (G \psi) = 0 $$

where scalar field $\psi$ is referred to as the advectee, vector field u is referred to as advector, and the G factor corresponds to optional coordinate transformation. The inclusion of the Fickian diffusion term is optional and is realised through modification of the advective velocity field with MPDATA handling both the advection and diffusion (for discussion see, e.g. Smolarkiewicz and Margolin 1998, sec. 3.5, par. 4).

PyMPDATA documentation is generated via pdoc.

A separate project called PyMPDATA-MPI depicts how numba-mpi can be used to enable distributed memory parallelism in PyMPDATA.applications, and provide a validation of the implementation and its performance.

Dependencies and installation

To install PyMPDATA, one may use: pip install PyMPDATA (or pip install git+https://github.com/open-atmos/PyMPDATA.git to get updates beyond the latest release). PyMPDATA depends on NumPy and Numba.

Running the tests shipped with the package requires additional packages that are installed if pip is invoked with: pip install PyMPDATA[tests].

Examples (Jupyter notebooks reproducing results from literature):

PyMPDATA examples are bundled with PyMPDATA and located in the examples subfolder. They constitute a separate PyMPDATA_examples Python package which is also available at PyPI. The examples have additional dependencies listed in PyMPDATA_examples package setup.py file. Running the examples requires the PyMPDATA_examples package to be installed. Since the examples package includes Jupyter notebooks (and their execution requires write access), the suggested install and launch steps are:

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

Alternatively, one can also install the examples package from pypi.org by using pip install PyMPDATA-examples.

Package structure and API:

The key classes constituting the PyMPDATA interface are summarised below.

Options class

The Options class groups both algorithm variant options as well as some implementation-related flags.

Arakawa-C grid layer

In PyMPDATA, the solution domain is assumed to extend from the first cell's boundary to the last cell's boundary (thus the first scalar field value is at $[\Delta x/2, \Delta y/2]$. The ScalarField and VectorField classes implement the Arakawa-C staggered grid logic.

Boundary conditions

Boundary conditions are implemented as classes defined in BoundaryCondition.

Stepper

The logic of the MPDATA iterative solver is represented in PyMPDATA by the Stepper class.

Solver

Instances of the Solver class are used to control the integration and access solution data. During instantiation, additional memory required by the solver is allocated according to the options provided.

Contributing, reporting issues, seeking support

Submitting new code to the project, please preferably use GitHub pull requests (or the PyMPDATA-examples PR site if working on examples) - it helps to keep record of code authorship, track and archive the code review workflow and allows to benefit from the continuous integration setup which automates execution of tests with the newly added code.

As of now, the copyright to the entire PyMPDATA codebase is with the Jagiellonian University (2019-2023) and AGH University of Krakow (2023 onwards) - work places of the main maintainer. Code contributions are assumed to imply transfer of copyright. Should there be a need to make an exception, please indicate it when creating a pull request or contributing code in any other way. In any case, the license of the contributed code must be compatible with GPL v3.

Developing the code, we follow The Way of Python and the KISS principle. The codebase has greatly benefited from PyCharm code inspections and Pylint code analysis (Pylint checks are part of the CI workflows).

Issues regarding any incorrect, unintuitive or undocumented bahaviour of PyMPDATA are best to be reported on the GitHub issue tracker. Feature requests are recorded in the "Ideas..." PyMPDATA wiki page.

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

Please use the PyMPDATA issue-tracking and dicsussion infrastructure for PyMPDATA-examples as well. We look forward to your contributions and feedback.

Credits:

Development of PyMPDATA was supported by the EU through a grant of the Foundation for Polish Science (POIR.04.04.00-00-5E1C/18) and by the Polish National Science Centre (grant no. 2020/39/D/ST10/01220)

copyright: Jagiellonian University (2019-2023) & AGH University of Krakow (2023 onwards)
licence: GPL v3