New developments in PySDM and PySDM-examples v2: collisional breakup, immersion freezing, dry aerosol initialization, and adaptive time-stepping

PySDM and the accompanying PySDM-examples packages are open-source modeling tools for computational studies of atmospheric clouds, aerosols, and precipitation. The project hinges on the particle-based microphysics modeling approach and Pythonic code design. The eponymous SDM refers to the Super Droplet Method – a Monte-Carlo algorithm introduced in Shima et al. (2009) to represent the coagulation of particles in modeling frameworks such as Large-Eddy Simulations (LES) of atmospheric flows. Recent efforts have culminated in the “v2” release line, which includes representation of a variety of new processes for both liquid and ice-phase particles, performance enhancements such as adaptive time-stepping, as well as a broadened suite of examples which demonstrate, test, and motivate the use of the SDM for cloud modeling research.


Background and Statement of Need
The key motivation behind development of PySDM has been to offer the community an approachable, readily reusable software for users and developers who wish to contribute to the scientific progress of particle-based methods for simulating atmospheric clouds. To this end, we strive to maintain modularity of the PySDM building blocks, separation of functionality and examples, and extensive unit test coverage in the project. A user of the package can select top-level options such as the simulation environment, particle processes, and output attributes without a detailed grasp of the CPU and GPU backend code.
PySDM "v1" featured representation of the following processes: condensational growth/evaporation, collisional growth, aqueous sulfur chemistry, and coupling of particle transport and vapor/heat budget with grid-discretized fluid flow. This paper outlines subsequent developments in the "v2" releases of PySDM including representation of three new processes (collisional breakup, immersion freezing, and surface-partitioning of organic aerosol components), initialization framework for aerosol size and composition, enhanced support for adaptive time-stepping, and additional illustrative examples.
literature. The examples package serves multiple roles in the project. First, it guides users and developers through the package features. Second, PySDM-examples has been used as educational material, offering interactive Jupyter notebooks suitable for hands-on demonstrations of basic cloud-physics simulations. Third, inclusion of simulation scripts/notebooks pertaining to new research papers can streamline assessment of the results by reviewers. Running simulations described in a paper can be done independently on a cloud-computing platform such as Google Colab or mybinder.org. Finally, we require new examples introduced into PySDM-examples to be accompanied by a set of "smoke tests" in PySDM, which assert results against reference data to ensure that published results remain reproducible with future developments of PySDM.

Summary of new features and examples in v2
For an example of running basic zero-dimensional simulations with PySDM, we refer to the project README.md file and Bartman, Bulenok, et al. (2022). The key building blocks of the PySDM API and class hierarchy are: "attributes", "backends", "dynamics", "environments", "products" and physics "formulae". The following code snippets demonstrate new elements of PySDM API, which can be added or substituted into the "v1" API description to run simulations using the new features. Execution of code snippets from both the present "v2" and the previous "v1" papers is included in the PySDM continuous integration workflow.

Collisional Breakup
The collisional breakup process represents the splitting of two colliding superdroplets into multiple fragments. It can be specified as an individual Breakup "dynamic" or used within a unified Collision "dynamic", in which the probability of breakup versus coalescence is sampled. The additional PySDM components used in the example below can be imported via: from PySDM.dynamics.collisions import Collision from PySDM.dynamics.collisions.collision_kernels import Golovin from PySDM.dynamics.collisions.coalescence_efficiencies import ConstEc from PySDM.dynamics.collisions.breakup_efficiencies import ConstEb from PySDM.dynamics.collisions.breakup_fragmentations import ExponFrag The rate of superdroplet collisions are specified by a collision kernel, and the breakup process requires three additional specifications: coalescence_efficiencies (probability of coalescence occurring), breakup_efficiencies (probability of breakup occurring if not coalescence), and breakup_fragmentations (the number of fragments formed in the case of a breakup event).

Immersion Freezing
This release of PySDM introduces representation of immersion freezing, i.e. liquid-solid phase change contingent on the presence of insoluble ice nuclei immersed in supercooled water droplets. There are two alternative models implemented: the singular approach presented in Shima et al. (2020), and the time-dependent approach of Alpert & Knopf (2016). For the time-dependent model, the water Activity Based Immersion Freezing Model (ABIFM) of Knopf & Alpert (2013) is used. The Freezing "dynamic" is introduced by specifying whether a singular model is used, and additional particle attributes (either freezing temperature or immersed surface area) must be initialized accordingly.
from PySDM.dynamics import Freezing builder.add_dynamic(Freezing(singular=False)) For validation of the the newly introduced immersion freezing models, a set of notebooks reproducing box-model simulations from Alpert & Knopf (2016) was introduced to the PySDM-examples package. A comparison of the time-dependent and singular models using a two-dimensional kinematic prescribed-flow framework was the focus of Arabas et al. (2023).

Initialization of multi-component internally or externally mixed aerosol
The new aerosol initialization framework introduced in PySDM "v2" allows flexible specification of multi-modal, multi-component aerosol. The DryAerosolMixture class takes a tuple of compounds and dictionaries specifying their molar masses, densities, solubilities, and ionic dissociation numbers. The user specifies the aerosol modes which are comprised of a kappa hygroscopicity value, calculated from the molecular components and their associated mass_fractions, and a dry aerosol size spectrum. For example, a single-mode aerosol class (SimpleAerosol) can be defined as follows.

Surface-partitioning of organics to modify surface tension of droplets
PySDM "v2" includes a new example demonstrating the available models for droplet surface tension. The four surface tension options included in PySDM, which define the droplet surface tension as a function of dry aerosol composition and wet radius, are: 'Constant', 'CompressedFilmOvadnevaite' (Ovadnevaite et al. (2017)), 'CompressedFilmRuehl' (Ruehl et al. (2016)), and 'SzyszkowskiLangmuir' following the Szyszkowski-Langmuir equation. Parameters for the three surface-partitioning models must be specified as shown below. A full comparison of the four surface tension models can be found in the Singer_Ward example.

Adaptive time-stepping
In PySDM "v2", the Condensation, Collision, and Displacement "dynamics" all support adaptive time-stepping logic, which involves sub-stepping within the user-specified time step used for coupling with the "environment". Adaptivity is enabled by default and can be disabled by passing False as the value of optional adaptive keyword to the given dynamic. This adaptive time-stepping applies separately in each grid box of a multidimensional environment, and includes a load-balancing logic as described in Bartman & Arabas (2023). In the case of collisions, the time-step adaptivity is aimed at eliminating errors associated with multiple coalescence events within a timestep. In the case of condensation, the time-step adaptivity is aimed at reducing computational load by coupling the time-step length choice with ambient supersaturation leading to using longer time-steps in cloud-free regions and shorter time-steps in regions where droplet [de]activation or rain evaporation occurs. In the case of displacement, the time-step adaptivity is aimed at obeying a given tolerance in integration of the super-particle trajectories, and the error measure is constructed by comparing implicit-and explicit-Euler solutions.

Relevant recent open-source developments
PySDM supports a PyMPDATA-based (Bartman, Banaśkiewicz, et al., 2022) reimplementation of the 1D kinematically-driven test framework in a recently-published intercomparison of microphysics methods (Hill et al., 2023). The authors are unaware of recent SDM algorithm implementations in open-source packages beyond those mentioned in (Bartman, Bulenok, et al., 2022) and the related list of links in the PySDM README file. Furthermore, none of these implementations include superdroplet-count-conserving collisional breakup, organic surface partitioning or adaptive time-stepping for coagulation. The aerosol initialization method described in PySDM v2 is similar to that of pyrcel (Rothenberg & Wang, 2017). Leveraging the availability of PyPartMC -a new Python interface to the PartMC particle-resolved Monte-Carlo aerosol simulation code (D'Aquino et al., 2023), PySDM test suite has been extended with automated checks against PartMC.

Author contributions
EdJ led the formulation and implementation of the collisional breakup scheme with contributions from JBM. CES added the aerosol initialization framework. CES contributed the new surface tension models and relevant examples, in consultation with RXW. SAz contributed to extensions and enhancement of the one-dimensional kinematic framework environment. PB led the formulation and worked with SAr on implementation of the adaptive time-stepping schemes. KD contributed to setting up continuous integration workflows for the GPU backend. OB implemented breakup handling within the GPU backend and contributed code refactors and new tests for both CPU and GPU backends. ID, CES, and AJ contributed to the aerosol activation examples. The immersion freezing representation code was developed by SAr. Maintenance of the project have been carried out by SAr, CES, and EdJ.