PyMPDATA

pure-Python, open-source implementation of the MPDATA algorithm

PyMPDATA is a high-performance Numba-accelerated Python package implementing the MPDATA algorithm by Smolarkiewicz et al. aimed at solving generalised advection-diffusion PDEs in geophysical fluid dynamics and beyond. It numerically solves equations of form:

$$ \partial_t (G\psi) + \nabla \cdot (G\vec{u}\psi) + \mu \Delta (G\psi) = 0 $$ where \(\psi\) is the advectee, \(u\) is the advector and the \(G\) factor describes the coordinate transformation. The last term is related to Fickian diffusion and is optional. The crux of the method lies in iterative application of the upwind scheme. The first iteration employs the advective velocity \(\vec{u}\), while each subsequent iteration employs a so-called antidiffusive velocity which corrects solution from prior iteration reducing the numerical diffusion. The antidiffusive velocities are formulated through modified equation analysis of the upwind scheme and feature cross-dimensional dependencies (i.e., applying MPDATA in multiple dimensions is not equivalent to application of one-dimensional MPDATA in all dimensions), the scheme is thus not dimensionally split, hence “M” in the algorithm name. Since each iteration of the scheme constitutes a forward-in-time upwind pass, the scheme inherits characteristics of the upwind scheme: CFL stability criterion, conservativeness, embarrassingly parallel domain decomposition, and sign-preservation. For non-negative fields \(\psi\), sign-preservation translates to positive definiteness, hence the “PD” in the algorithm name. Application of the corrective iterations improves scheme convergence rate compared with first-order upwind.

The package depends on NumPy, Numba and Numba-MPI. This allows for taking advantage of Just-In-Time (JIT) compilation provided by Numba, and in case of computational clusters, distributed memory parallelism with PyMPDATA-MPI. PyMPDATA has an example gallery available as a separate Python package, showing how it can be used to solve equations such as the Black-Scholes equation, Burgers equation and shallow-water equations. The project can be found on PyPI, with its source code hosted on GitHub, along with the documentation and example gallery.

Selected papers on the MPDATA algorithm (features implemented in PyMPDATA)

• Smolarkiewicz 1983 (Mon. Weather Rev. 111): “A Simple Positive Definite Advection Scheme with Small Implicit Diffusion”
• Smolarkiewicz 1984 (J. Comp. Phys. 54): “A fully multidimensional positive definite advection transport algorithm with small implicit diffusion”
• Smolarkiewicz & Grabowski 1990: “The multidimensional positive definite advection transport algorithm: nonoscillatory option”
• Smolarkiewicz & Margolin 1998 (J. Comp. Phys. 140): “MPDATA: A Finite-Difference Solver for Geophysical Flows”
• Smolarkiewicz 2006 (Int. J. Numer. Methods Fluids 50): “Multidimensional positive definite advection transport algorithm: an overview”
• Margolin & Shashkov 2006 (Int. J. Numer. Methods Fluids 50): “MPDATA: gauge transformations, limiters and monotonicity†”
• Jaruga et al. 2015 (GMD 8): “libmpdata++ 1.0: a library of parallel MPDATA solvers for systems of generalised transport equations”

Papers on or using PyMPDATA

• Bartman et al. 2022 (JOSS 7): “ PyMPDATA v1: Numba-accelerated implementation of MPDATA with examples in Python, Julia and Matlab”
• Olesik et al. 2022 (GMD 15): “On numerical broadening of particle-size spectra: a condensational growth study using PyMPDATA 1.0”
• Derlatka et al. 2024 (SoftwareX 28): “Numba-MPI v1.0: Enabling MPI communication within Numba/LLVM JIT-compiled Python code”
• Magnuszewski et al. 2025 (arXiv): “ Path-dependent option pricing with two-dimensional PDE using MPDATA”

🎓 Student project opportunities

• traffic flow dynamics with PyMPDATA
• immersed boundary method with PyMPDATA
• fully third-order MPDATA variant for PyMPDATA
• coupling PyMPDATA’s Boussinesq solver with PySDM to simulate convective cloud
• shallow-water equations on a sphere using PyMPDATA
• stacked shallow-water system (isopycnic ocean model)

Contributors from our team

Piotr Bartman-Szwarc

Completed MSc project in 2020 (major: Computer Science, Jagiellonian Univ.)

Michael Olesik

Completed MSc project in 2020 (major: Physics, Jagiellonian Univ.)

Michał Wroński

Ongoing BEng project (major: Micro- and Nanotechnologies in Biophysics, AGH)

Michał Kowalczyk

Completed BEng project in 2025 (major: Technical Physics, AGH)

Paweł Magnuszewski

Completed MSc project in 2025 (major: Computer Science & Intelligent Systems, AGH)

Kacper Derlatka

Completed MSc project in 2023 (major: Computer Science, Jagiellonian Univ.)

Sylwester Arabas

Team lead (PhD, Physics, U. Warsaw, 2013)