https://github.com/darothen/pysdm
Pythonic particle-based (super-droplet) warm-rain/aqueous-chemistry cloud microphysics package with box, parcel & 1D/2D prescribed-flow examples
Science Score: 23.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
○CITATION.cff file
-
○codemeta.json file
-
○.zenodo.json file
-
✓DOI references
Found 20 DOI reference(s) in README -
✓Academic publication links
Links to: arxiv.org, wiley.com -
○Academic email domains
-
○Institutional organization owner
-
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (7.0%) to scientific vocabulary
Last synced: 10 months ago
·
JSON representation
Repository
Pythonic particle-based (super-droplet) warm-rain/aqueous-chemistry cloud microphysics package with box, parcel & 1D/2D prescribed-flow examples
Basic Info
Statistics
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
- Releases: 0
Fork of open-atmos/PySDM
Created about 5 years ago
· Last pushed about 5 years ago
https://github.com/darothen/PySDM/blob/master/
[](https://www.python.org/)
[](https://numba.pydata.org)
[](https://pypi.org/project/ThrustRTC/)
[](https://en.wikipedia.org/wiki/Linux)
[](https://en.wikipedia.org/wiki/macOS)
[](https://en.wikipedia.org/wiki/Windows)
[](https://jupyter.org/)
[](https://travis-ci.com/atmos-cloud-sim-uj/PySDM)
[](https://github.com/atmos-cloud-sim-uj/PySDM/actions)
[](https://ci.appveyor.com/project/slayoo/pysdm/branch/master)
[](https://github.com/atmos-cloud-sim-uj/PySDM/network/dependencies)
[](https://codecov.io/github/atmos-cloud-sim-uj/PySDM?branch=master)
[](https://GitHub.com/atmos-cloud-sim-uj/PySDM/graphs/commit-activity)
[](https://github.com/atmos-cloud-sim-uj/PySDM/issues?q=)
[](https://github.com/atmos-cloud-sim-uj/PySDM/issues?q=is:closed)
[](https://github.com/atmos-cloud-sim-uj/PySDM/pulls?q=)
[](https://github.com/atmos-cloud-sim-uj/PySDM/pulls?q=is:closed)
[](https://www.openhub.net/p/atmos-cloud-sim-uj-PySDM)
[](https://www.fnp.org.pl/en/)
[](https://en.uj.edu.pl/)
[](https://www.gnu.org/licenses/gpl-3.0.html)
# PySDM
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 core is a Pythonic high-performance implementation of the
Super-Droplet Method (SDM) Monte-Carlo algorithm for representing collisional growth
([Shima et al. 2009](https://rmets.onlinelibrary.wiley.com/doi/abs/10.1002/qj.441)), hence the name.
PySDM has two alternative parallel number-crunching backends
available: multi-threaded CPU backend based on [Numba](http://numba.pydata.org/)
and GPU-resident backend built on top of [ThrustRTC](https://pypi.org/project/ThrustRTC/).
The **Numba backend** named ``CPU`` is the default, and features multi-threaded parallelism for
multi-core CPUs.
It uses the just-in-time compilation technique based on the LLVM infrastructure.
The **ThrustRTC** backend named ``GPU`` offers GPU-resident operation of PySDM
leveraging the [SIMT](https://en.wikipedia.org/wiki/Single_instruction,_multiple_threads)
parallelisation model.
Using the ``GPU`` backend requires nVidia hardware and [CUDA driver](https://developer.nvidia.com/cuda-downloads).
For an overview paper on PySDM v1 (and the preferred item to cite if using PySDM), see [Bartman et al. 2021 arXiv e-print](https://arxiv.org/abs/2103.17238) (submitted to JOSS).
For a list of talks and other materials on PySDM, see the [project wiki](https://github.com/atmos-cloud-sim-uj/PySDM/wiki).
## Dependencies and Installation
PySDM dependencies are: [Numpy](https://numpy.org/), [Numba](http://numba.pydata.org/), [SciPy](https://scipy.org/),
[Pint](https://pint.readthedocs.io/), [chempy](https://pypi.org/project/chempy/),
[ThrustRTC](https://fynv.github.io/ThrustRTC/) and [CURandRTC](https://github.com/fynv/CURandRTC).
To install PySDM using ``pip``, one may use: ``pip install git+https://github.com/atmos-cloud-sim-uj/PySDM.git``.
For development purposes, we suggest cloning the repository and installing it using ``pip -e``.
Test-time dependencies are listed in the ``requirements.txt`` file.
Besides the PySDM repository (where this README file is hosted), there are three related repositories:
- [``PySDM_examples``](https://github.com/atmos-cloud-sim-uj/PySDM-examples) with a suite of Python/Jupyter examples depicting PySDM features and listed below,
- [``PySDM_examples.jl``](https://github.com/atmos-cloud-sim-uj/PySDM-examples.jl) with examples depicting how to use PySDM from Julia using [PyCall.jl](https://github.com/JuliaPy/PyCall.jl),
- [``PySDM_examples.m``](https://github.com/atmos-cloud-sim-uj/PySDM-examples.m) with examples depicting how to use PySDM from Matlab using the [Matlab-Python interface](https://www.mathworks.com/help/matlab/call-python-libraries.html).
The examples have additional dependencies listed in [``PySDM_examples`` package ``setup.py``](https://github.com/atmos-cloud-sim-uj/PySDM-examples/blob/main/setup.py) file.
Running the examples requires the the ``PySDM_examples`` package to be installed (or within ``PYTHONPATH``).
Since the examples package includes Jupyter notebooks, the suggested install and launch steps are:
```
git clone https://github.com/atmos-cloud-sim-uj/PySDM-examples.git
cd PySDM-examples
pip install -e .
jupyter-notebook
```
## PySDM examples (Jupyter notebooks reproducing results from literature):
#### 0D box-model coalescence-only examples (work with both CPU and GPU backends):
- [Shima et al. 2009](http://doi.org/10.1002/qj.441) Fig. 2
[](https://mybinder.org/v2/gh/atmos-cloud-sim-uj/PySDM-examples.git/main?urlpath=lab/tree/PySDM_examples/Shima_et_al_2009/fig_2.ipynb)
[](https://colab.research.google.com/github/atmos-cloud-sim-uj/PySDM-examples/blob/main/PySDM_examples/Shima_et_al_2009/fig_2.ipynb)
(Box model, coalescence only, test case employing Golovin analytical solution)
- [Berry 1967](https://doi.org/10.1175/1520-0469(1967)024<0688:CDGBC>2.0.CO;2) Figs. 5, 8 & 10
[](https://mybinder.org/v2/gh/atmos-cloud-sim-uj/PySDM-examples.git/main?urlpath=lab/tree/PySDM_examples/Berry_1967/figs_5_8_10.ipynb)
[](https://colab.research.google.com/github/atmos-cloud-sim-uj/PySDM-examples/blob/main/PySDM_examples/Berry_1967/figs_5_8_10.ipynb)
(Box model, coalescence only, test cases for realistic kernels)
#### 0D parcel-model condensation only examples (CPU backend only, stay tuned...)
- [Arabas & Shima 2017](http://dx.doi.org/10.5194/npg-24-535-2017) Fig. 5
[](https://mybinder.org/v2/gh/atmos-cloud-sim-uj/PySDM-examples.git/main?urlpath=lab/tree/PySDM_examples/Arabas_and_Shima_2017/fig_5.ipynb)
[](https://colab.research.google.com/github/atmos-cloud-sim-uj/PySDM-examples/blob/main/PySDM_examples/Arabas_and_Shima_2017/fig_5.ipynb)
(Adiabatic parcel, monodisperse size spectrum activation/deactivation test case)
- [Yang et al. 2018](https://doi.org/10.5194/acp-18-7313-2018) Fig. 2:
[](https://mybinder.org/v2/gh/atmos-cloud-sim-uj/PySDM-examples.git/main?urlpath=lab/tree/PySDM_examples/Yang_et_al_2018/fig_2.ipynb)
[](https://colab.research.google.com/github/atmos-cloud-sim-uj/PySDM-examples/blob/main/PySDM_examples/Yang_et_al_2018/fig_2.ipynb)
(Adiabatic parcel, polydisperse size spectrum activation/deactivation test case)
#### 0D parcel-model condensation/aqueous-chemistry example (CPU backend only, stay tuned...)
- [Kreidenweis et al. 2003](https://doi.org/10.1029/2002JD002697) Fig 1:
[](https://mybinder.org/v2/gh/atmos-cloud-sim-uj/PySDM-examples.git/main?urlpath=lab/tree/PySDM_examples/Kreidenweis_et_al_2003/demo.ipynb)
[](https://colab.research.google.com/github/atmos-cloud-sim-uj/PySDM-examples/blob/main/PySDM_examples/Kreidenweis_et_al_2003/demo.ipynb)
(Adiabatic parcel, polydisperse size spectrum, aqueousphase SO2 oxidation test case)
- [Jaruga and Pawlowska 2018](https://doi.org/10.5194/gmd-11-3623-2018):
[](https://mybinder.org/v2/gh/atmos-cloud-sim-uj/PySDM-examples.git/main?urlpath=lab/tree/PySDM_examples/Jaruga_and_Pawlowska_2018/figs_1_2_3.ipynb)
[](https://colab.research.google.com/github/atmos-cloud-sim-uj/PySDM-examples/blob/main/PySDM_examples/Jaruga_and_Pawlowska_2018/figs_1_2_3.ipynb)
(same test case as above, different numerical settings)
#### 1D kinematic (prescribed-flow, single-column)
- [Shipway & Hill 2012](https://doi.org/10.1002/qj.1913)
[](https://mybinder.org/v2/gh/atmos-cloud-sim-uj/PySDM-examples.git/main?urlpath=lab/tree/PySDM_examples/Shipway_and_Hill_2012/fig_1.ipynb)
[](https://colab.research.google.com/github/atmos-cloud-sim-uj/PySDM-examples/blob/main/PySDM_examples/Shipway_and_Hill_2012/fig_1.ipynb)
(Fig. 1 with thermodynamics & condensation only - no particle displacement)
#### 2D kinematic (prescribed-flow) Sc-mimicking aerosol collisional processing (warm-rain) examples (CPU backend only, stay tuned...)
- [Arabas et al. 2015](https://doi.org/10.5194/gmd-8-1677-2015) Figs. 8 & 9:
[](https://mybinder.org/v2/gh/atmos-cloud-sim-uj/PySDM-examples.git/main?urlpath=lab/tree/PySDM_examples/Arabas_et_al_2015/figs_8_9.ipynb)
[](https://colab.research.google.com/github/atmos-cloud-sim-uj/PySDM-examples/blob/main/PySDM_examples/Arabas_et_al_2015/figs_8_9.ipynb)
(interactive web-GUI with product selection, parameter sliders and netCDF/plot export buttons)
- Bartman et al. 2021 (in preparation):
[](https://mybinder.org/v2/gh/atmos-cloud-sim-uj/PySDM-examples.git/main?filepath=lab/tree/PySDM_examples/Bartman_et_al_2021/demo.ipynb)
[](https://colab.research.google.com/github/atmos-cloud-sim-uj/PySDM-examples/blob/main/PySDM_examples/Bartman_et_al_2021/demo.ipynb)
(default-settings based script generating a netCDF file and loading it subsequently to create the animation below)
## Hello-world example
In order to depict the PySDM API with a practical example, the following
listings provide a sample code roughly reproducing the
Figure 2 from [Shima et al. 2009 paper](http://doi.org/10.1002/qj.441).
It is a coalescence-only set-up in which the initial particle size
spectrum is exponential and is deterministically sampled to match
the condition of each super-droplet having equal initial multiplicity:
```Python
from PySDM.physics import si
from PySDM.initialisation.spectral_sampling import ConstantMultiplicity
from PySDM.initialisation.spectra import Exponential
n_sd = 2**15
initial_spectrum = Exponential(norm_factor=8.39e12, scale=1.19e5 * si.um**3)
attributes = {}
attributes['volume'], attributes['n'] = ConstantMultiplicity(spectrum=initial_spectrum).sample(n_sd)
```
The key element of the PySDM interface is the [``Core``](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/core.py)
class which instances are used to manage the system state and control the simulation.
Instantiation of the ``Core`` class is handled by the ``Builder``
as exemplified below:
```Python
from PySDM import Builder
from PySDM.environments import Box
from PySDM.dynamics import Coalescence
from PySDM.dynamics.coalescence.kernels import Golovin
from PySDM.backends import CPU
from PySDM.products.state import ParticlesVolumeSpectrum
builder = Builder(n_sd=n_sd, backend=CPU)
builder.set_environment(Box(dt=1 * si.s, dv=1e6 * si.m**3))
builder.add_dynamic(Coalescence(kernel=Golovin(b=1.5e3 / si.s)))
products = [ParticlesVolumeSpectrum()]
particles = builder.build(attributes, products)
```
The ``backend`` argument may be set to ``CPU`` or ``GPU``
what translates to choosing the multi-threaded backend or the
GPU-resident computation mode, respectively.
The employed ``Box`` environment corresponds to a zero-dimensional framework
(particle positions are not considered).
The vectors of particle multiplicities ``n`` and particle volumes ``v`` are
used to initialise super-droplet attributes.
The ``Coalescence`` Monte-Carlo algorithm (Super Droplet Method) is registered as the only
dynamic in the system (other available dynamics representing
condensational growth and particle displacement).
Finally, the ``build()`` method is used to obtain an instance
of ``Core`` which can then be used to control time-stepping and
access simulation state.
The ``run(nt)`` method advances the simulation by ``nt`` timesteps.
In the listing below, its usage is interleaved with plotting logic
which displays a histogram of particle mass distribution
at selected timesteps:
```Python
from PySDM.physics.constants import rho_w
from matplotlib import pyplot
import numpy as np
radius_bins_edges = np.logspace(np.log10(10 * si.um), np.log10(5e3 * si.um), num=32)
for step in [0, 1200, 2400, 3600]:
particles.run(step - particles.n_steps)
pyplot.step(x=radius_bins_edges[:-1] / si.um,
y=particles.products['dv/dlnr'].get(radius_bins_edges) * rho_w / si.g,
where='post', label=f"t = {step}s")
pyplot.xscale('log')
pyplot.xlabel('particle radius [m]')
pyplot.ylabel("dm/dlnr [g/m$^3$/(unit dr/r)]")
pyplot.legend()
pyplot.savefig('readme.svg')
```
The resultant plot looks as follows:
## Package structure and API
- [backends](https://github.com/atmos-cloud-sim-uj/PySDM/tree/master/PySDM/backends):
- [CPU=Numba](https://github.com/piotrbartman/PySDM/tree/master/PySDM/backends/numba):
multi-threaded CPU backend using LLVM-powered just-in-time compilation
- [GPU=ThrustRTC](https://github.com/piotrbartman/PySDM/tree/master/PySDM/backends/thrustRTC):
GPU-resident backend using NVRTC runtime compilation library for CUDA
- [initialisation](https://github.com/atmos-cloud-sim-uj/PySDM/tree/master/PySDM/initialisation):
- [multiplicities](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/initialisation/multiplicities.py):
integer-valued discretisation with sanity checks for errors due to type casting
- [r_wet_init](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/initialisation/r_wet_init.py):
kappa-Keohler-based equilibrium in unsaturated conditions (RH=1 used in root-finding above saturation)
- [spatial_sampling](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/initialisation/spatial_sampling.py):
pseudorandom sampling using NumPy's default RNG
- [spectra](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/initialisation/spectra.py):
Exponential and Lognormal classes
- [spectral_sampling](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/initialisation/spectral_sampling.py):
linear, logarithmic and constant_multiplicity classes
- [physics](https://github.com/atmos-cloud-sim-uj/PySDM/tree/master/PySDM/physics):
- [constants](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/physics/constants.py):
physical constants partly imported from [SciPy](https://www.scipy.org/) and [chempy](https://pypi.org/project/chempy/) packages
- [dimensional_analysis](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/physics/dimensional_analysis.py):
tool for enabling dimensional analysis of the code for unit tests (based on [pint](https://pint.readthedocs.io/))
- [formulae](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/physics/formulae.py):
physical formulae partly imported from the Numba backend (e.g., for initialisation)
- [environments](https://github.com/atmos-cloud-sim-uj/PySDM/tree/master/PySDM/environments):
- [Box](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/environments/box.py):
bare zero-dimensional framework
- [Parcel](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/environments/parcel.py):
zero-dimensional adiabatic parcel framework
- [Kinematic1D](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/environments/kinematic_1d.py):
single-column time-varying-updraft framework with moisture advection handled by [PyMPDATA](http://github.com/atmos-cloud-sim-uj/PyMPDATA/)
- [Kinematic2D](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/environments/kinematic_2d.py):
two-dimensional prescribed-flow-coupled framework with Eulerian advection handled by [PyMPDATA](http://github.com/atmos-cloud-sim-uj/PyMPDATA/)
- [dynamics](https://github.com/atmos-cloud-sim-uj/PySDM/tree/master/PySDM/dynamics):
- [Coalescence](https://github.com/atmos-cloud-sim-uj/PySDM/tree/master/PySDM/dynamics/coalescence)
- [coalescence.kernels (selected)](https://github.com/atmos-cloud-sim-uj/PySDM/tree/master/PySDM/dynamics/coalescence/kernels)
- [Golovin](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/dynamics/coalescence/kernels/golovin.py)
- [Geometric](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/dynamics/coalescence/kernels/geometric.py)
- [Hydrodynamic](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/dynamics/coalescence/kernels/hydrodynamic.py)
- ...
- [Condensation](https://github.com/atmos-cloud-sim-uj/PySDM/tree/master/PySDM/dynamics/condensation.py)
- solvers (working in arbitrary spectral coordinate specified through external class, defaults to logarithm of volume):
- [default](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/backends/numba/impl/condensation_methods.py):
bespoke solver with implicit-in-particle-size integration and adaptive timestepping (Numba only as of now, soon on all backends)
- [BDF](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/backends/numba/bdf.py):
black-box SciPy-based solver for benchmarking (Numba backend only)
- [AqueousChemistry](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/dynamics/aqueous_chemistry/aqueous_chemistry.py):
aqueous-phase chemistry (incl. SO2 oxidation)
- [Displacement](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/dynamics/displacement.py):
includes advection with the flow & sedimentation)
- [EulerianAdvection](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/dynamics/eulerian_advection)
- Attributes (selected):
- [numerics](https://github.com/atmos-cloud-sim-uj/PySDM/tree/master/PySDM/attributes/numerics):
- [position_in_cell](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/attributes/numerics/position_in_cell.py)
- [cell_id](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/attributes/numerics/cell_id.py)
- ...
- [physics](https://github.com/atmos-cloud-sim-uj/PySDM/tree/master/PySDM/attributes/physics):
- [volume](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/attributes/physics/volume.py)
- [multiplicities](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/attributes/physics/multiplicities.py)
- [critical_volume](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/attributes/physics/critical_volume.py)
- ...
- [chemistry](https://github.com/atmos-cloud-sim-uj/PySDM/tree/master/PySDM/attributes/chemistry):
- [pH](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/attributes/chemistry/pH.py)
- [concentration](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/attributes/chemistry/concentration.py)
- ...
- Products (selected):
- [SuperDropletCount](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/products/state/super_droplet_count.py)
- [ParticlesVolumeSpectrum](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/products/state/particles_volume_spectrum.py)
- [WaterMixingRatio](https://github.com/atmos-cloud-sim-uj/PySDM/blob/master/PySDM/products/state/water_mixing_ratio.py)
- ...
## Credits:
Development of PySDM is supported by the EU through a grant of the Foundation for Polish Science (POIR.04.04.00-00-5E1C/18).
copyright: Jagiellonian University
licence: GPL v3
## Related resources and open-source projects
### SDM patents (some expired, some withdrawn):
- https://patents.google.com/patent/US7756693B2
- https://patents.google.com/patent/EP1847939A3
- https://patents.google.com/patent/JP4742387B2
- https://patents.google.com/patent/CN101059821B
### Other SDM implementations:
- SCALE-SDM (Fortran):
https://github.com/Shima-Lab/SCALE-SDM_BOMEX_Sato2018/blob/master/contrib/SDM/sdm_coalescence.f90
- Pencil Code (Fortran):
https://github.com/pencil-code/pencil-code/blob/master/src/particles_coagulation.f90
- PALM LES (Fortran):
https://palm.muk.uni-hannover.de/trac/browser/palm/trunk/SOURCE/lagrangian_particle_model_mod.f90
- libcloudph++ (C++):
https://github.com/igfuw/libcloudphxx/blob/master/src/impl/particles_impl_coal.ipp
- LCM1D (Python)
https://github.com/SimonUnterstrasser/ColumnModel
- superdroplet (Cython/Numba/C++11/Fortran 2008/Julia)
https://github.com/darothen/superdroplet
- NTLP (FORTRAN)
https://github.com/Folca/NTLP/blob/SuperDroplet/les.F
### non-SDM probabilistic particle-based coagulation solvers
- PartMC (Fortran):
https://github.com/compdyn/partmc
### Python models with discrete-particle (moving-sectional) representation of particle size spectrum
- pyrcel: https://github.com/darothen/pyrcel
- PyBox: https://github.com/loftytopping/PyBox
- py-cloud-parcel-model: https://github.com/emmasimp/py-cloud-parcel-model
Owner
- Name: Daniel Rothenberg
- Login: darothen
- Kind: user
- Location: Frederick, CO
- Company: Waymo
- Website: http://www.danielrothenberg.com
- Twitter: danrothenberg
- Repositories: 72
- Profile: https://github.com/darothen
Tech Lead @ Waymo | Weather/Climate Scientist | Pythonista | ex-Chief Scientist @ ClimaCell/Tomorrow.io | Formerly Postdoc Associate @ MIT EAPS/IDSS/CGCS