Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/open-atmos/pympdata
Numba-accelerated Pythonic implementation of MPDATA with examples in Python, Julia and Matlab
https://github.com/open-atmos/pympdata
advection advection-diffusion atmospheric-modelling numba numerical-integration pde-solver pypi-package python research simulation
Last synced: 4 days ago
JSON representation
Numba-accelerated Pythonic implementation of MPDATA with examples in Python, Julia and Matlab
- Host: GitHub
- URL: https://github.com/open-atmos/pympdata
- Owner: open-atmos
- License: gpl-3.0
- Created: 2019-12-03T12:08:09.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2024-10-25T14:37:53.000Z (3 months ago)
- Last Synced: 2024-10-25T16:09:57.766Z (3 months ago)
- Topics: advection, advection-diffusion, atmospheric-modelling, numba, numerical-integration, pde-solver, pypi-package, python, research, simulation
- Language: Python
- Homepage: https://open-atmos.github.io/PyMPDATA/
- Size: 28 MB
- Stars: 24
- Watchers: 2
- Forks: 17
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 
# PyMPDATA
[](https://www.python.org/)
[](https://www.numba.org)
[](https://en.wikipedia.org/wiki/Linux)
[](https://en.wikipedia.org/wiki/macOS)
[](https://en.wikipedia.org/wiki/Windows)
[](https://jupyter.org/)
[](https://github.com/open-atmos/PyMPDATA/graphs/commit-activity)
[](https://www.openhub.net/p/atmos-cloud-sim-uj-PyMPDATA)
[](https://joss.theoj.org/papers/10e7361e43785dbb1b3d659c5b01757a)
[](https://zenodo.org/badge/latestdoi/225610671)
[](https://www.fnp.org.pl/en/)
[](https://www.ncn.gov.pl/?language=en)
[](https://www.gnu.org/licenses/gpl-3.0.html)
[](https://github.com/open-atmos/PyMPDATA/actions)
[](https://ci.appveyor.com/project/slayoo/pympdata/branch/main)
[](https://app.codecov.io/gh/open-atmos/PyMPDATA)
[](https://pypi.org/project/PyMPDATA)
[](https://open-atmos.github.io/PyMPDATA/index.html)
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](https://doi.org/10.1006/jcph.1998.5901), sec. 3.5, par. 4).
PyMPDATA [documentation](https://open-atmos.github.io/PyMPDATA/index.html) is generated via [``pdoc``](https://pdoc.dev/).
A separate project called [``PyMPDATA-MPI``](https://github.com/open-atmos/PyMPDATA-MPI)
depicts how [``numba-mpi``](https://pypi.org/project/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``](https://pypi.org/p/PyMPDATA-examples) Python package which is also available at PyPI.
The examples have additional dependencies listed in [``PyMPDATA_examples`` package ``setup.py``](https://github.com/open-atmos/PyMPDATA/blob/main/examples/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``](https://open-atmos.github.io/PyMPDATA/PyMPDATA/options.html) 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``](https://open-atmos.github.io/PyMPDATA/PyMPDATA/scalar_field.html)
and [``VectorField``](https://open-atmos.github.io/PyMPDATA/PyMPDATA/vector_field.html) classes implement the
[Arakawa-C staggered grid](https://en.wikipedia.org/wiki/Arakawa_grids#Arakawa_C-grid) logic.
#### Boundary conditions
Boundary conditions are implemented as classes defined in
[``BoundaryCondition``](https://open-atmos.github.io/PyMPDATA/PyMPDATA/boundary_conditions.html).
#### Stepper
The logic of the MPDATA iterative solver is represented
in PyMPDATA by the [``Stepper``](https://open-atmos.github.io/PyMPDATA/PyMPDATA/stepper.html) class.
#### Solver
Instances of the [``Solver``](https://open-atmos.github.io/PyMPDATA/PyMPDATA/solver.html) 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](https://github.com/open-atmos/PyMPDATA/pulls)
(or the [PyMPDATA-examples PR site](https://github.com/open-atmos/PyMPDATA-examples/pulls) 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](https://www.python.org/dev/peps/pep-0020/) and
the [KISS principle](https://en.wikipedia.org/wiki/KISS_principle).
The codebase has greatly benefited from [PyCharm code inspections](https://www.jetbrains.com/help/pycharm/code-inspection.html)
and [Pylint](https://pylint.org) 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](https://github.com/open-atmos/PyMPDATA/issues/new).
Feature requests are recorded in the "Ideas..." [PyMPDATA wiki page](https://github.com/open-atmos/PyMPDATA/wiki/Ideas-for-new-features-and-examples).
We encourage to use the [GitHub Discussions](https://github.com/open-atmos/PyMPDATA/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](http://fnp.org.pl) (POIR.04.04.00-00-5E1C/18)
and by the [Polish National Science Centre](https://ncn.gov.pl/en) (grant no. 2020/39/D/ST10/01220)
copyright: Jagiellonian University (2019-2023) & AGH University of Krakow (2023 onwards)
licence: GPL v3