PySDM logo

Documentation

What is PySDM?

PySDM is a package for simulating the dynamics of population of particles undergoing diffusional and collisional growth (and breakage). The package features a Pythonic high-performance (multi-threaded CPU & CUDA GPU) implementation of the Super-Droplet Method (SDM) Monte-Carlo algorithm for representing collisional growth (Shima et al. 2009), hence the name. It is intended to serve as a building block for simulation systems modelling fluid flows involving a dispersed phase, with PySDM being responsible for representation of the dispersed phase. Currently, the development is focused on atmospheric cloud physics applications, in particular on modelling the dynamics of particles immersed in moist air using the particle-based (a.k.a. super-droplet) approach to represent aerosol/cloud/rain microphysics. The key goal of PySDM is to enable rapid development and independent reproducibility of simulations in cloud microphysics while being free from the two-language barrier commonly separating prototype and high-performance research code.

What is the difference between PySDM and PySDM-examples?

PySDM is a Python package that provides the implementation of SDM that can be used in your own projects.

PySDM-examples is a Python package that provides examples of how to use PySDM. The package contains common code used in PySDM examples Jupyter notebooks, as well as in PySDM test suite.

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

Important links

PySDM PySDM-examples

Installation

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

pip install PySDM

Note: the way above will not install test-time dependencies, to install them and run the tests, likely the most convenient way is:

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

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

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

pip install PySDM-examples

Note: this will also install PySDM if needed, but the examples package wheels do not include the Jupyter notebooks - only common code used from the notebooks. All PySDM 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/PySDM.git
pip install -e PySDM -e PySDM/examples
jupyter-notebook PySDM/examples

Dependencies

PySDM depends on NumPy, Numba, ThrustRTC, SciPy, Pint, chempy, pyevtk and CURandRTC

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

Contributing, reporting issues, 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 PySDM or PySDM-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 PySDM code.

Licensing, credits, acknowledgements

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

Development of PySDM was started by Piotr Bartman[-Szwarc], Sylwester Arabas and collaborators at the Jagiellonian University in Kraków and at the CliMA team at Caltech. For an overview of features of the initial release, see the 2022 PySDM v1 JOSS paper.

The v2 release of PySDM is summarised in the 2023 de Jong, Singer, et al. JOSS paper. Current development (towards v3) and maintenance is led by the Environmental Physics Group at the AGH University of Krakow. See list of code committers for a complete list of contributors.

Development of PySDM was supported by: