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:

Bibliography with code cross-references

The list below summarises all literature references included in PyMPDATA codebase and includes links to both the referenced papers, as well as to the referring PyMPDATA source files.

  1. Arabas & Farhat 2020 (J. Comput. Appl. Math. 373): "Derivative pricing as a transport problem: MPDATA solutions to Black–Scholes-type equations"
  2. Arabas et al. 2014 (Sci. Prog. 22): "Formula Translation in Blitz++, NumPy and Modern Fortran: A Case Study of the Language Choice Tradeoffs"
  3. Bartman et al. 2022 (J. Open Source Soft. 7): "PyMPDATA v1: Numba-accelerated implementation of MPDATA with examples in Python, Julia and Matlab"
  4. Beason & Margolin 1988 (Nuclear explosives code developer's conference, Boulder, CO, USA): "DPDC (double-pass donor cell): A second-order monotone scheme for advection"
  5. Jarecka et al. 2015 (J. Comp. Phys. 289): "A spreading drop of shallow water"
  6. Jaruga et al. 2015 (Geosci. Model Dev. 8): "libmpdata++ 1.0: a library of parallel MPDATA solvers for systems of generalised transport equations "
  7. Lam et al. 2015: "Numba: a LLVM-based Python JIT compiler"
  8. Margolin & Shashkov 2006 (Int. J. Numer. Methods Fluids 50): "MPDATA: gauge transformations, limiters and monotonicity"
  9. Margolin & Smolarkiewicz 1998 (SIAM J. Sci. Comput. 20): "Antidiffusive Velocities for Multipass Donor Cell Advection"
  10. Molenkamp 1968 (J. Appl. Meteorol. Climatol. 7): "Accuracy of Finite-Difference Methods Applied to the Advection Equation"
  11. Olesik et al. 2022 (Geosci. Model Dev. 15): "On numerical broadening of particle-size spectra: a condensational growth study using PyMPDATA 1.0"
  12. Ranocha et al. 2022: "Adaptive numerical simulations with Trixi.jl: A case study of Julia for scientific computing"
  13. Shipway & Hill 2012 (Q. J. R. Meteorol. Soc. 138): "Diagnosis of systematic differences between multiple parametrizations of warm rain microphysics using a kinematic framework"
  14. Smolarkiewicz & Clark 1986 (J. Comp. Phys. 67): "The multidimensional positive definite advection transport algorithm: Further development and applications"
  15. Smolarkiewicz & Grabowski 1990 (J. Comp. Phys. 86): "The multidimensional positive definite advection transport algorithm: nonoscillatory option"
  16. Smolarkiewicz & Margolin 1998 (J. Comp. Phys. 140): "MPDATA: A Finite-Difference Solver for Geophysical Flows"
  17. Smolarkiewicz 2006 (Int. J. Numer. Methods Fluids 50): " Multidimensional positive definite advection transport algorithm: an overview "
  18. Smolarkiewicz 2006 (J. Comp. Phys. 54): "A fully multidimensional positive definite advection transport algorithm with small implicit diffusion"
  19. Williamson & Rasch 1989 (Mon. Weather Rev. 117): "Two-Dimensional Semi-Lagrangian Transport with Shape-Preserving Interpolation"

EOF