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:

Bibliography with code cross-references

The list below summarises all literature references included in PySDM codebase and includes links to both the referenced papers, as well as to the referring PySDM source files.

  1. Abade & Albuquerque 2024 (Q. J. R. Meteorol. Soc. 150): "Persistent mixed-phase states in adiabatic cloud parcels under idealised conditions"
  2. Abdul-Razzak & Ghan 2000 (J. Geophys. Res. Atmos. 105): "A parameterization of aerosol activation: 2. Multiple aerosol types"
  3. Alpert & Knopf 16 (Atmos. Chem. Phys. 16): "Analysis of isothermal and cooling-rate-dependent immersion freezing by a unifying stochastic ice nucleation model"
  4. Arabas & Shima 2017 (Nonlin. Proc. Geophys. 24): "On the CCN (de)activation nonlinearities"
  5. Arabas et al. 2015 (Geosci. Model Dev. 2015): "libcloudph++ 1.0: a single-moment bulk, double-moment bulk, and particle-based warm-rain microphysics library in C++"
  6. Arabas et al. 2023 (arXiv:2308.05015): "Immersion freezing in particle-based aerosol-cloud microphysics: a probabilistic perspective on singular and time-dependent models"
  7. August 1828 (Ann. Phys. Chem. 89): "Ueber die Berechnung der Expansivkraft des Wasserdunstes"
  8. Barkan & Luz 2005 (Rapid Commun. Mass Spectrom. 19): "High precision measurements of 17O/16O and 18O/16O ratios in H2O"
  9. Barkan & Luz 2007 (Rapid Commun. Mass Spectrom. 21): "Diffusivity fractionations of H216O/H217O and H216O/H218O in air and their implications for isotope hydrology"
  10. Bartman et al. 2022 (J. Open Source Soft. 7): "PyMPDATA v1: Numba-accelerated implementation of MPDATA with examples in Python, Julia and Matlab"
  11. Bartman et al. 2022 (J. Open Source Soft. 7): "PySDM v1: particle-based cloud modeling package for warm-rain microphysics and aqueous chemistry"
  12. Berry 1967 (J. Atmos. Sci. 24): "Cloud Droplet Growth by Collection"
  13. Bieli et al. 2022 (J. Adv. Model. Earth Sys. 14): "An Efficient Bayesian Approach to Learning Droplet Collision Kernels: Proof of Concept Using “Cloudy,” a New n-Moment Bulk Microphysics Scheme"
  14. Bigg 1953 (Proc. Phys. Soc. B 66): "The Supercooling of Water"
  15. Bohren 1987 (Am. J. Phys. 55): "Multiple scattering of light and some of its observable consequences"
  16. Bolin 1958 (Proc. 2nd UN Intl Conf. Peaceful Uses of Atomic Energy): "On the Use of Tritium as a Tracer for Water in Nature"
  17. Bolot et al. 2013 (Atmos. Chem. Phys. 13): "Modelling and interpreting the isotopic composition of water vapour in convective updrafts "
  18. Bolton 1980 (Mon. Weather Rev. 108): "The Computation of Equivalent Potential Temperature"
  19. Cappa et al. 2003 (J. Geophys. Res. Atmos. 108): "Isotopic fractionation of water during evaporation"
  20. Cotton et al. 2011 (International Geophysics 99): "Fundamental Equations Governing Cloud Processes"
  21. Craig 1961 (Science 133): "Isotopic Variations in Meteoric Waters"
  22. Dansgaard 1964 (Tellus A 16): "Stable isotopes in precipitation"
  23. de Jong et al. 2023 (Geosci. Model Dev. 16): "Breakups are complicated: an efficient representation of collisional breakup in the superdroplet method"
  24. de Jong et al. 2023 (J. Open Source Soft. 8): "New developments in PySDM and PySDM-examples v2: collisional breakup, immersion freezing, dry aerosol initialization, and adaptive time-stepping"
  25. Ellehoj et al. 2013 (Rapid Commun. Mass Spectrom. 27): "Ice-vapor equilibrium fractionation factor of hydrogen and oxygen isotopes: Experimental investigations and implications for stable water isotope studies"
  26. Ervens & Feingold 2012 (Atmos. Chem. Phys. 12): "On the representation of immersion and condensation freezing in cloud models using different nucleation schemes "
  27. Feingold et al. 1999 (J. Atmos. Sci. 56): "The Impact of Giant Cloud Condensation Nuclei on Drizzle Formation in Stratocumulus: Implications for Cloud Radiative Properties"
  28. Flatau et al. 1992 (J. Appl. Meteorol. Climatol. 31): "Polynomial Fits to Saturation Vapor Pressure"
  29. Friedman et al. 1962 (J. Geophys. Res. 67): "Water-vapor exchange between a water droplet and its environment"
  30. Gat 2010: "Isotope Hydrology: A Study of the Water Cycle"
  31. Gedzelman & Arnold 1994 (J. Geophys. Res. Atmos. 99): "Modeling the isotopic composition of precipitation"
  32. Golovin 1963 (Dokl. Akad. Nauk SSSR 148): "К вопросу о решении уравнения коагуляции дождевых капель с учетом конденсации (On solving the equation of rain drop coagulation with allowance for condensation)"
  33. Grabowski & Pawlowska 2023 (Geophys. Res. Lett. 50): "Adiabatic Evolution of Cloud Droplet Spectral Width: A New Look at an Old Problem"
  34. Grabowski et al. 2011 (Atmos. Res. 99): "Droplet growth in a bin warm-rain scheme with Twomey CCN activation"
  35. Graf et al. 2019 (Atmos. Chem. Phys. 19): "A new interpretative framework for below-cloud effects on stable water isotopes in vapour and rain"
  36. Gunn & Kinzer 1949 (J. Atmos. Sci. 6): "The Terminal Velocity of Fall for Water Droplets in Stagnant Air"
  37. Hall & Pruppacher 1976 (J. Atmos. Sci. 33): "The Survival of Ice Particles Falling from Cirrus Clouds in Subsaturated Air"
  38. Hellmann & Harvey 2020 (Geophys. Res. Lett. 47): "First-Principles Diffusivity Ratios for Kinetic Isotope Fractionation of Water in Air"
  39. Horita & Wesolowski 1994 (Geochim. Cosmochim. Acta 58): "Liquid-vapor fractionation of oxygen and hydrogen isotopes of water from the freezing to the critical temperature"
  40. Horita et al. 2008 (Isot. Environ. Healt. S. 44): "Isotope effects in the evaporation of water: a status report of the Craig–Gordon model"
  41. Hoyle et al. 2016 (Atmos. Chem. Phys. 16): "Aqueous phase oxidation of sulphur dioxide by ozone in cloud droplets"
  42. Jaruga & Pawlowska 2018 (Geosci. Model Dev. 11): "libcloudph++ 2.0: aqueous-phase chemistry extension of the particle-based cloud microphysics scheme"
  43. Jensen & Nugent 2017 (J. Atmos. Sci. 74): "Condensational Growth of Drops Formed on Giant Sea-Salt Aerosol Particles"
  44. Jokulsdottir & Archer 2016 (Geosci. Model Dev. 9): "A stochastic, Lagrangian model of sinking biogenic aggregates in the ocean (SLAMS 1.0): model formulation, validation and sensitivity"
  45. Jouzel 1986 (The Terrestrial Environment, B): "Isotopes in cloud physics: Multiphase and multistage condensation process"
  46. Kaul et al. 2015 (Mon. Weather Rev. 143): "Sensitivities in Large-Eddy Simulations of Mixed-Phase Arctic Stratocumulus Clouds Using a Simple Microphysics Approach"
  47. Kessler 1969 (Meteorol. Monogr. 10): "On the Distribution and Continuity of Water Substance in Atmospheric Circulations"
  48. Knopf & Alpert 2013 (Faraday Discuss. 165): "A water activity based model of heterogeneous ice nucleation kinetics for freezing of water and aqueous solution droplets"
  49. Kreidenweis et al. 2003 (J. Geophys. Res. 108): "Modification of aerosol mass and size distribution due to aqueous-phase SO2 oxidation in clouds: Comparisons of several models"
  50. Laaksonen et al. 2005 (Atmos. Chem. Phys. 5): "Commentary on cloud modelling and the mass accommodation coefficient of water"
  51. Lamb et al. 2017 (PNAS 114): "Laboratory measurements of HDO/H2O isotopic fractionation during ice deposition in simulated cirrus clouds"
  52. Lind et al. 1987 (J. Geophys. Res. Atmos. 92): "Aqueous phase oxidation of sulfur(IV) by hydrogen peroxide, methylhydroperoxide, and peroxyacetic acid"
  53. Low & List 1982 (J. Atmos. Sci. 39): "Collision, Coalescence and Breakup of Raindrops. Part II: Parameterization of Fragment Size Distributions"
  54. Lowe 1977 (J. Appl. Meteorol. Climatol. 16): "An Approximating Polynomial for the Computation of Saturation Vapor Pressure"
  55. Lowe et al. 2019 (Nature Comm. 10): "Key drivers of cloud response to surface-active organics"
  56. Majoube 1970 (Nature 226): "Fractionation Factor of 18O between Water Vapour and Ice"
  57. Majoube 1971 ( J. Chim. Phys. 68): "Fractionnement en 180 entre la glace et la vapeur d’eau"
  58. Majoube 1971 (J. Chim. Phys. 68): "Fractionnement en oxygène 18 et en deutérium entre l’eau et sa vapeur"
  59. Mason 1951 (Proc. Phys. Soc. B 64): "Spontaneous Condensation of Water Vapour in Expansion Chamber Experiments"
  60. Mason 1971 (Clarendon Press, Oxford): "The Physics of Clouds"
  61. Merlivat & Jouzel 1979 (J. Geophys. Res. Oceans 84): "Global climatic interpretation of the deuterium-oxygen 18 relationship for precipitation"
  62. Merlivat & Nief 1967 (Tellus A 19): "Fractionnement isotopique lors des changements d’état solide-vapeur et liquide-vapeur de l’eau à des températures inférieures à 0°C"
  63. Merlivat 1978 (J. Chem. Phys. 69): "Molecular diffusivities of H216O, HD16O and H218O in gases"
  64. Miyake et al. 1968 (Pap. Meteorol. Geophys. 19): "An Isotopic Study on Meteoric Precipitation"
  65. Morrison & Grabowski 2007 (J. Atmos. Sci. 64): "Comparison of Bulk and Bin Warm-Rain Microphysics Models Using a Kinematic Framework"
  66. Murphy & Koop 2005 (Q. J. R. Meteorol. Soc. 131): "Review of the vapour pressures of ice and supercooled water for atmospheric applications"
  67. Niedermeier et al. 2014 (Geophys. Res. Lett. 41): "A computationally efficient description of heterogeneous freezing: A simplified version of the Soccer ball model"
  68. Niedermeier et al. 2014 (J. Atmos. Sci. 69): "A computationally efficient description of heterogeneous freezing: A simplified version of the Soccer ball model"
  69. Okuyama & Zung 1967 (J. Chem. Phys. 1967): "Evaporation—Condensation Coefficient for Small Droplets"
  70. Ovadnevaite et al. 2017 (Nature 546): "Surface tension prevails over solute effect in organic-influenced cloud droplet activation"
  71. Petters & Kreidenweis 2007 (Atmos. Chem. Phys. 7): "A single parameter representation of hygroscopic growth and cloud condensation nucleus activity"
  72. Picciotto et al. 1960 (Nature 187): "Isotopic Composition and Temperature of Formation of Antarctic Snows"
  73. Pierchala et al. 2022 (Geochim. Cosmochim. Acta 322): "Quantification the diffusion-induced fractionation of 1H217O isotopologue in air accompanying the process of water evaporation"
  74. Pounder 1965 (Pergamon Press): "The Physics of Ice"
  75. Pruppacher & Klett 2010 (Springer Dordrecht): "Microphysics of Clouds and Precipitation"
  76. Pruppacher & Rasmussen 1979 (J. Atmos. Sci. 36): "A Wind Tunnel Investigation of the Rate of Evaporation of Large Water Drops Falling at Terminal Velocity in Air"
  77. Rogers & Yau 1989 (Pergamon Press): "A short course in clouds physics"
  78. Rozanski & Sonntag 1982 (Tellus A 34): "Vertical distribution of deuterium in atmospheric water vapour"
  79. Ruehl et al. 2016 (Science 351): "An interfacial mechanism for cloud droplet formation on organic aerosols"
  80. Seinfeld & Pandis 2006 (Wiley): "Microphysics of Clouds and Precipitation"
  81. Shima et al. 2009 (Q. J. R. Meteorol. Soc. 135): "The super-droplet method for the numerical simulation of clouds and precipitation: a particle-based and probabilistic microphysics model coupled with a non-hydrostatic model"
  82. Shima et al. 2020 (Geosci. Model Dev. 13): "Predicting the morphology of ice particles in deep convection using the super-droplet method: development and evaluation of SCALE-SDM 0.2.5-2.2.0, -2.2.1, and -2.2.2"
  83. Shipway & Hill 2012 (Q. J. R. Meteorol. Soc. 138): "Diagnosis of systematic differences between multiple parametrizations of warm rain microphysics using a kinematic framework"
  84. Smolarkiewicz 2006 (Int. J. Numer. Methods Fluids 50): "Multidimensional positive definite advection transport algorithm: an overview"
  85. Squires 1952 (Aust. J. Chem. (Aust. J. Sci. Res. 5): "The Growth of Cloud Drops by Condensation. I. General Characteristics"
  86. Srivastava 1982 (J. Atmos. Sci. 39): "A Simple Model of Particle Coalescence and Breakup"
  87. Steinke et al. 2011 (Atmos. Chem. Phys. 11): "Ice nucleation properties of fine ash particles from the Eyjafjallajökull eruption in April 2010 "
  88. Stephens 1978 (J. Atmos. Sci. 35): "Radiation Profiles in Extended Water Clouds. II: Parameterization Schemes"
  89. Stewart 1975 (J. Geophys. Res. Oceans 80): "Stable isotope fractionation due to evaporation and isotopic exchange of falling waterdrops: Applications to atmospheric processes and evaporation of lakes"
  90. Straub et al. 2010 (J. Atmos. Sci. 67): "Numerical Investigation of Collision-Induced Breakup of Raindrops. Part II: Parameterizations of Coalescence Efficiencies and Fragment Size Distributions"
  91. Szumowski et al. 1998 (Atmos. Res. 45): "Simple two-dimensional kinematic framework designed to test warm rain microphysical models"
  92. Van Hook 1968 (J. Phys. Chem. 72): "Vapor pressures of the isotopic waters and ices"
  93. Vedder 1987 (Am. J. Phys. 55): "Simple approximations for the error function and its inverse"
  94. Wexler 1976 (J. Res. NBS A Phys. Ch. 80A): "Vapor Pressure Formulation for Water in Range 0 to 100 °C. A Revision"
  95. Yang et al. 2018 (Atmos. Chem. Phys. 18): "Cloud droplet size distribution broadening during diffusional growth: ripening amplified by deactivation and reactivation"
  96. Zografos et al. 1987 (Comput. Method. Appl. M. 61): "Equations of properties as a function of temperature for seven fluids"

EOF