pysdm-examples 3.0.0rc1

PySDM usage examples reproducing results from literature and depicting how to use PySDM from Python Jupyter notebooks

Introduction

PySDM examples are engineered as Jupyter Python notebooks supported by auxiliary Python commons that constitute a separate PySDM-examples Python package which is also available at PyPI. 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 pip-installed. For installation instructions see project docs homepage. Note that the Jupyter notebooks themselves are not included in the package wheels, but are included in the source .tar.gz file on PyPI, and are conveninently browsable on GitHub. All notebooks feature header cells with badges enabling single-click execution on Google Colab and on mybinder.org. The examples package is also used in the PySDM test suite.

Example gallery

The examples are named referring to the journal paper they aim to reproduce simulations from (or sometimes just where the inspiration originated from). The list below groups all examples by the dimensionality and type of the employed modelling framework ("environment" in PySDM nomenclature, which can be: box, parcel, single-column, 2D prescribed flow), and by the set of physical processes simulated (condensation, collisional coagulation and breakup, drop freezing, isotopic fractionation, aqueous chemistry, seeding, ...).

2D kinematic environment (prescribed-flow) mimicking Sc deck

The 2D prescribed-flow framework used here can be traced back to the work of Kessler 1969 (section 3C). The setup employed in PySDM-examples, which mimics a stratiform cloud deck and features periodic horizontal boundary condition and vanishing flow at vertical boundaries, was introduced in Morrison and Grabowski (2007) and later adopted for particle-based simulations in Arabas et al. (2015). It uses a non-devergent single-eddy flow field resulting in an updraft-downdraft pair in the domain. The flow field advects two scalar fields in an Eulerian way: water vapour mixing ratio and dry-air potential temperature. In PySDM-examples, the Eulerian advection is handled using the PyMPDATA Numba-based implementation of the MPDATA numerical scheme of Smolarkiewicz (e.g., 2006). An animation depicting PySDM simulation capturing aerosol collisional processing by warm rain is shown below (see the Paraview hello-world HOWTO Jupyter notbook for code generating the simulation and visualisation):

Example notebooks:

• Arabas_et_al_2015
  • in-notebook GUI for setting up, running and interactively visualising the 2D kinematic simulations (with an option to export raw data to VTK and netCDF files, as well as to save plots to SVG or PDF):
  • "hello world" notebook depicting how to automate using Python the process of loading data and creating animations in Paraview
• Arabas_et_al_2025: adaptation of the 2D kinematic setup for studying glaciation of the cloud deck by immersion freezing

1D kinematic environment (prescribed-flow, single-column)

The single-column PySDM environment is a reimplementation of the Met Office KiD framework introduced in Shipway & Hill 2012. The framework features a single Eulerian-transported field of water vapour mixing ratio (vertical profile of potential temperature is fixed). As in the 2D kinematic framework above, the Eulerian advection is handled by PyMPDATA.

Example notebooks:

• Shipway_and_Hill_2012: reproducing figures from the Shipway & Hill 2012 paper;
• deJong_Mackay_et_al_2023: reproducing figures from the de Jong et al. 2023 paper where the single-column framework was used to exemplify operation of the Monte-Carlo collisional breakup scheme in PySDM (scheme introduced in that paper).

OD/1D iterative parcel/column environment mimicking removal of precipitation

This framework uses a parcel model with removal of precipitation for analysis, iterative equilibration, the isotopic composition of the water vapour and rain water in a column of air (no Eulerian transport, only iterative passage of a parcel through the column).

Rozanski_and_Sonntag_1982: bulk microphysics example (i.e. single super droplet) with deuterium and heavy-oxygen water isotopologues featured.

0D parcel environment

The parcel framework implemented in PySDM uses a hydrostatic profile and adiabatic mass and energy conservation to drive evolution of thermodynamic state and microphysical properties of particles.

Example notebooks include:

• condensation only
  • Arabas_and_Shima_2017: monodisperse particle spectrum, activation/deactivation cycle
  • Yang_et_al_2018: polydisperse particle spectrum, activation/deactivation cycles
  • Abdul_Razzak_Ghan_2000: polydisperse activation, comparison against GCM parameterisation
  • Pyrcel: polydisperse activation, mimicking example test case from Pyrcel documentation
  • Lowe_et_al_2019: externally mixed polydisperse size spectrum with surface-active organics case
  • Grabowski_and_Pawlowska_2023: polydisperse activation, focus on ripening
  • Jensen_and_Nugent_2017: polydisperse activation featuring giant CCN
• condensation and aqueous-chemistry
  • Kreidenweis_et_al_2003: Hoppel gap simulation setup (i.e. depiction of evolution of aerosol mass spectrum from a monomodal to bimodal due to aqueous‐phase SO2 oxidation)
  • Jaruga_and_Pawlowska_2018: exploration of numerical convergence using the above Hoppel-gap simulation setup
• freezing
  • Spichtinger_et_al_2023: homogeneous freezing and ice growth (Wegener-Bergeron-Findeisen process)

The parcel environment is also featured in the PySDM tutorials.

0D box environment

The box environment is void of any spatial or thermodynamic context, it constitutes the most basic framework.

Example notebooks include:

• coalescence only:
  • Shima_et_al_2009: using Golovin additive kernel for comparison against analytic solution, featuring interactive in-notebook interface for selecting simulation parameters
  • Berry_1967: examples using geometric, hydrodynamic and electric-field collision kernels
• coalescence and breakup:
  • Bieli_et_al_2022: evolution of moments under collisional growth and breakage
  • deJong_Mackay_et_al_2023: validation of the breakup scheme against analytical solutions from Srivastava 1982
• immersion freezing only:
  • Alpert_and_Knopf_2016: stochastic immersion freezing with monodisperse vs. lognormal immersed surface areas
  • Arabas_et_al_2025: comparison of time-dependent and singular immersion freezing schemes

The box environment is also featured in the PySDM tutorials.

examples depicting isotope-related formulae (without any simulation context)

• equilibrium isotopic fractionation formulae:
  • Lamb_et_al_2017
  • Bolot_et_al_2013
  • Merlivat_and_Nief_1967
  • Van_Hook_1968
  • Graf_et_al_2019
• Rayleigh fractionation:
  • Pierchala_et_al_2022: reproducing model plots for a triple-isotope lab study, including kinetic fractionation
  • Gonfiantini_1986: flat-surface evaporation at different humidities for D and ¹⁸O
• isotopic relaxation timescale:
  • Miyake_et_al_1968: incl. comparison of different ventilation parameterisations
  • Bolin_1958
• below-cloud kinetic fractionation:
  • Gedzelman_and_Arnold_1994

examples depicting extraterrestrial clouds (formulae-only, no simulations yet)

• Titan (methane clouds):
  • Toon_et_al_1980