<img src="https://raw.githubusercontent.com/open-atmos/PySDM/main/docs/logos/pysdm_logo.svg" width=100 height=146 alt="pysdm logo">

PySDM is a package for simulating the dynamics of population of particles. 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 package features a Pythonic high-performance implementation of the Super-Droplet Method (SDM) Monte-Carlo algorithm for representing collisional growth (Shima et al. 2009), hence the name.

PySDM documentation is maintained at: https://open-atmos.github.io/PySDM

There is a growing set of example Jupyter notebooks exemplifying how to perform various types of calculations and simulations using PySDM. Most of the example notebooks reproduce results and plot from literature, see below for a list of examples and links to the notebooks (which can be either executed or viewed "in the cloud").

There are also a growing set of tutorials, also in the form of Jupyter notebooks. These tutorials are intended for teaching purposes and include short explanations of cloud microphysical concepts paired with widgets for running interactive simulations using PySDM. Each tutorial also comes with a set of questions at the end that can be used as homework problems. Like the examples, these tutorials can be executed or viewed "in the cloud" making it an especially easy way for students to get started.

PySDM has two alternative parallel number-crunching backends available: multi-threaded CPU backend based on Numba and GPU-resident backend built on top of ThrustRTC. The Numba backend (aliased CPU) features multi-threaded parallelism for multi-core CPUs, it uses the just-in-time compilation technique based on the LLVM infrastructure. The ThrustRTC backend (aliased GPU) offers GPU-resident operation of PySDM leveraging the SIMT parallelisation model. Using the GPU backend requires nVidia hardware and CUDA driver.

For an overview of PySDM features (and the preferred way to cite PySDM in papers), please refer to our JOSS papers:

• Bartman et al. 2022 (PySDM v1).
• de Jong, Singer et al. 2023 (PySDM v2).

PySDM includes an extension of the SDM scheme to represent collisional breakup described in de Jong, Mackay et al. 2023.
For a list of talks and other materials on PySDM as well as a list of published papers featuring PySDM simulations, see the project wiki.

Dependencies and Installation

PySDM dependencies are: Numpy, Numba, SciPy, Pint, chempy, pyevtk, ThrustRTC and CURandRTC.

To install PySDM using pip, use: pip install PySDM (or pip install git+https://github.com/open-atmos/PySDM.git to get updates beyond the latest release).

Conda users may use pip as well, see the Installing non-conda packages section in the conda docs.

For development purposes, we suggest cloning the repository and installing it using pip -e. Test-time dependencies can be installed with pip -e .[tests].

PySDM examples constitute the PySDM-examples package. The examples have additional dependencies listed in PySDM_examples package setup.py file. Running the example Jupyter notebooks requires the PySDM_examples package to be installed. The suggested install and launch steps are:

git clone https://github.com/open-atmos/PySDM.git
pip