PySDM-examples 2.130__tar.gz → 3.0.0__tar.gz

pysdm_examples-3.0.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: pysdm-examples
+Version: 3.0.0
+Summary: PySDM usage examples reproducing results from literature and depicting how to use PySDM from Python Jupyter notebooks
+Author-email: "https://github.com/open-atmos/PySDM/graphs/contributors" <sylwester.arabas@agh.edu.pl>
+License-Expression: GPL-3.0-only
+Project-URL: Tracker, https://github.com/open-atmos/PySDM/issues
+Project-URL: Documentation, https://open-atmos.github.io/PySDM/PySDM_examples
+Project-URL: Source, https://github.com/open-atmos/PySDM/tree/main/examples
+Description-Content-Type: text/markdown
+Requires-Dist: PySDM
+Requires-Dist: PyMPDATA
+Requires-Dist: open-atmos-jupyter-utils
+Requires-Dist: pystrict
+Requires-Dist: matplotlib
+Requires-Dist: joblib
+Requires-Dist: ipywidgets
+Requires-Dist: seaborn
+Requires-Dist: numdifftools
+Requires-Dist: vtk
+Requires-Dist: pyrcel
+Requires-Dist: pyvinecopulib
+Requires-Dist: networkx
+Requires-Dist: PyVista
+Requires-Dist: cmcrameri
+Requires-Dist: cmap
+Provides-Extra: ci-version-pins
+Requires-Dist: PySDM[CI_version_pins]; extra == "ci-version-pins"
+Requires-Dist: PyMPDATA==1.7.3; extra == "ci-version-pins"
+Requires-Dist: open-atmos-jupyter-utils==1.5.0; extra == "ci-version-pins"
+Requires-Dist: pystrict==1.3; extra == "ci-version-pins"
+Requires-Dist: matplotlib!=3.9.1; extra == "ci-version-pins"
+Requires-Dist: joblib==1.6.0; extra == "ci-version-pins"
+Requires-Dist: ipywidgets==8.1; extra == "ci-version-pins"
+Requires-Dist: seaborn==0.13.2; extra == "ci-version-pins"
+Requires-Dist: numdifftools==0.11.1; extra == "ci-version-pins"
+Requires-Dist: vtk==9.7; extra == "ci-version-pins"
+Requires-Dist: pyrcel==2.0.0; extra == "ci-version-pins"
+Requires-Dist: pyvinecopulib==1.0.0; extra == "ci-version-pins"
+Requires-Dist: cmcrameri==1.10; extra == "ci-version-pins"
+Requires-Dist: cmap==0.7.2; extra == "ci-version-pins"
+Dynamic: description
+Dynamic: description-content-type
+
+# Introduction
+
+<img align="left" src="https://raw.githubusercontent.com/open-atmos/PySDM/main/docs/logos/pysdm_logo.svg" width=150 height=219 alt="pysdm logo" style="padding-right:1em">
+
+PySDM examples are engineered as Jupyter Python notebooks supported by auxiliary Python commons
+  that constitute a separate <mark>PySDM-examples</mark> Python package which is also
+  <a href="https://pypi.org/p/PySDM-examples">available at PyPI</a>.
+The examples have additional dependencies listed in
+  <a href="https://github.com/open-atmos/PySDM/blob/main/examples/setup.py">PySDM-examples package setup.py file</a>.
+Running the example Jupyter notebooks requires the <mark>PySDM-examples</mark> package to be pip-installed.
+For installation instructions see [project docs homepage](https://open-atmos.github.io/PySDM).
+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
+  <a href="https://colab.research.google.com/">Google Colab</a> and on
+  <a href="https://mybinder.org/">mybinder.org</a>.
+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: <mark>box</mark>, <mark>parcel</mark>,
+<mark>single-column</mark>, <mark>2D prescribed flow</mark>), and by the set of physical processes simulated
+(<mark>condensation</mark>, collisional <mark>coagulation</mark> and <mark>breakup</mark>,
+<mark>drop freezing</mark>, <mark>isotopic fractionation</mark>, <mark>aqueous chemistry</mark>,
+<mark>seeding</mark>, ...).
+
+## 2D kinematic environment (prescribed-flow) mimicking Sc deck
+
+The 2D prescribed-flow framework used here can be traced back to the work of
+  <a href="https://doi.org/10.1007/978-1-935704-36-2_1">Kessler 1969 (section 3C)</a>.
+  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 <a href="https://doi.org/10.1175/JAS3980">Morrison and Grabowski (2007)</a>
+    and later adopted for particle-based simulations in <a href="https://doi.org/10.5194/gmd-8-1677-2015">Arabas et al. (2015)</a>.
+  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 <a href="https://doi.org/10.21105/joss.03896">PyMPDATA</a> Numba-based
+    implementation of the <a href="https://doi.org/10.1002/fld.1071">MPDATA numerical scheme of Smolarkiewicz (e.g., 2006)</a>.
+  An animation depicting PySDM simulation capturing <mark>aerosol collisional processing</mark> by warm rain is shown below
+  (<a href="https://github.com/open-atmos/PySDM/blob/main/examples/PySDM_examples/_HOWTOs/paraview_hello_world.ipynb">see
+  the Paraview hello-world HOWTO Jupyter notbook for code generating the simulation and visualisation</a>):
+<center>
+  <img src="https://github.com/open-atmos/PySDM/releases/download/tip/docs_intro_animation_ubuntu-24.04.gif" style="width:80%" />
+</center>
+
+Example notebooks:
+- `PySDM_examples.featured.Arabas_et_al_2025`: adaptation of the 2D kinematic setup for studying <mark>glaciation</mark> of the cloud deck by <mark>immersion freezing</mark>
+
+## 1D kinematic environment (prescribed-flow, single-column)
+
+The single-column PySDM environment is a reimplementation of the <mark>Met Office KiD framework</mark>
+  introduced in <a href="https://doi.org/10.1002/qj.1913">Shipway & Hill 2012</a>.
+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
+  <a href="https://open-atmos.github.io/PyMPDATA/">PyMPDATA</a>.
+
+Example notebooks:
+- `PySDM_examples.featured.Shipway_and_Hill_2012`: reproducing figures from the <a href="https://doi.org/10.1002/qj.1913">Shipway & Hill 2012</a> paper;
+- `PySDM_examples.featured.deJong_Mackay_et_al_2023`: reproducing figures from the <a href="https://doi.org/10.5194/gmd-16-4193-2023">de Jong et al. 2023</a> paper where the single-column
+   framework was used to exemplify operation of the <mark>Monte-Carlo collisional breakup scheme</mark> in PySDM (scheme introduced in that paper).
+
+## 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
+  - `PySDM_examples.featured.Arabas_and_Shima_2017`: monodisperse particle spectrum, activation/deactivation cycle
+  - `PySDM_examples.featured.Yang_et_al_2018`: polydisperse particle spectrum, activation/deactivation cycles
+  - `PySDM_examples.featured.Abdul_Razzak_Ghan_2000`: polydisperse activation, comparison against <mark>GCM parameterisation</mark>
+  - `PySDM_examples.featured.pyrcel_docs_testcase`: polydisperse activation, mimicking example test case from <mark>Pyrcel</mark> documentation
+  - `PySDM_examples.featured.Lowe_et_al_2019`: externally mixed polydisperse size spectrum with <mark>surface-active organics</mark> case
+  - `PySDM_examples.featured.Grabowski_and_Pawlowska_2023`: polydisperse activation, focus on <mark>ripening</mark>
+  - `PySDM_examples.featured.Jensen_and_Nugent_2017`: polydisperse activation featuring <mark>giant CCN</mark>
+- condensation and aqueous-chemistry
+  - `PySDM_examples.featured.Kreidenweis_et_al_2003`: <mark>Hoppel gap</mark> simulation setup (i.e. depiction of evolution of aerosol mass spectrum from a monomodal to bimodal due to aqueous‐phase SO2 oxidation)
+  - `PySDM_examples.featured.Jaruga_and_Pawlowska_2018`: exploration of numerical convergence using the above Hoppel-gap simulation setup
+- freezing
+
+The parcel environment is also featured in the <a href="https://open-atmos.github.io/PySDM/PySDM.html#tutorials">PySDM tutorials</a>.
+
+<center>
+  <img src="https://github.com/open-atmos/PySDM/releases/download/tip/parcel_animation_ubuntu-24.04.gif" style="width:80%" />
+</center>
+
+## 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:
+  - `PySDM_examples.featured.Shima_et_al_2009`: using <mark>Golovin additive kernel</mark> for comparison against analytic solution, featuring interactive in-notebook interface for selecting simulation parameters
+  - `PySDM_examples.featured.Berry_1967`: examples using geometric, hydrodynamic and electric-field collision kernels
+- coalescence and breakup:
+  - `PySDM_examples.featured.Bieli_et_al_2022`: evolution of moments under collisional growth and breakage
+  - `PySDM_examples.featured.deJong_Mackay_et_al_2023`: validation of the breakup scheme against analytical solutions from <a href="https://doi.org/10.1175/1520-0469(1982)039%3C1317:ASMOPC%3E2.0.CO;2">Srivastava 1982</a>
+- immersion freezing only:
+  - `PySDM_examples.featured.Alpert_and_Knopf_2016`: stochastic immersion freezing with monodisperse vs. lognormal immersed surface areas
+  - `PySDM_examples.featured.Arabas_et_al_2025`: comparison of time-dependent and singular immersion freezing schemes
+
+The box environment is also featured in the <a href="https://open-atmos.github.io/PySDM/PySDM.html#tutorials">PySDM tutorials</a>.
+
+## examples depicting isotope-related formulae (without any simulation context)
+- <mark>equilibrium isotopic fractionation</mark> formulae:
+  - `PySDM_examples.misc.Lamb_et_al_2017`
+  - `PySDM_examples.misc.Bolot_et_al_2013`
+  - `PySDM_examples.misc.Merlivat_and_Nief_1967`
+  - `PySDM_examples.misc.Van_Hook_1968`
+- <mark>Rayleigh fractionation</mark>:
+  - `PySDM_examples.featured.Pierchala_et_al_2022`: reproducing model plots for a <mark>triple-isotope</mark> lab study, including <mark>kinetic fractionation</mark>
+  - `PySDM_examples.misc.Gonfiantini_1986`: flat-surface evaporation at different humidities for D and <sup>18</sup>O
+- isotopic relaxation timescale:
+  - `PySDM_examples.misc.Miyake_et_al_1968`: incl. comparison of different <mark>ventilation</mark> parameterisations
+  - `PySDM_examples.misc.Bolin_1958`
+- below-cloud <mark>kinetic fractionation</mark>:
+  - `PySDM_examples.misc.Gedzelman_and_Arnold_1994`
+
+## examples depicting extraterrestrial clouds (formulae-only, no simulations yet)
+- Titan (methane clouds):
+  - `PySDM_examples.misc.Toon_et_al_1980`

{pysdm_examples-2.130 → pysdm_examples-3.0.0}/PySDM_examples/__init__.py

@@ -3,9 +3,12 @@
 """
 
 from importlib.metadata import PackageNotFoundError, version
+import PySDM
 
 try:
     __version__ = version(__name__)
 except PackageNotFoundError:
     # package is not installed
     pass
+
+assert PySDM.__version__ == __version__

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Abdul_Razzak_Ghan_2000/run_ARG_parcel.py

@@ -1,14 +1,17 @@
 from collections import namedtuple
 
 import numpy as np
-from PySDM_examples.Abdul_Razzak_Ghan_2000.aerosol import CONSTANTS_ARG, AerosolARG
+from PySDM_examples.featured.Abdul_Razzak_Ghan_2000.aerosol import (
+    CONSTANTS_ARG,
+    AerosolARG,
+)
 
-from PySDM import Builder, Formulae
+from PySDM import Particulator, Formulae
 from PySDM import products as PySDM_products
 from PySDM.backends import CPU
 from PySDM.dynamics import AmbientThermodynamics, Condensation
 from PySDM.environments import Parcel
-from PySDM.initialisation import equilibrate_wet_radii
+from PySDM.initialisation.hygroscopic_equilibrium import equilibrate_wet_radii
 from PySDM.initialisation.sampling.spectral_sampling import ConstantMultiplicity
 from PySDM.physics import si
 
@@ -19,6 +22,7 @@ def run_parcel(
     N2,
     rad2,
     n_sd_per_mode,
+    *,
     RH0=1.0,
     T0=294 * si.K,
     p0=1e5 * si.Pa,
@@ -44,6 +48,7 @@ def run_parcel(
         initial_water_vapour_mixing_ratio=const.eps * pv0 / (p0 - pv0),
         w=w,
         T0=T0,
+        backend=CPU(formulae),
     )
 
     aerosol = AerosolARG(
@@ -51,22 +56,19 @@ def run_parcel(
     )
     n_sd = n_sd_per_mode * len(aerosol.modes)
 
-    builder = Builder(backend=CPU(formulae), n_sd=n_sd, environment=env)
-    builder.add_dynamic(AmbientThermodynamics())
-    builder.add_dynamic(Condensation())
-    builder.request_attribute("critical saturation")
-
     attributes = {
         k: np.empty(0) for k in ("dry volume", "kappa times dry volume", "multiplicity")
     }
     for i, mode in enumerate(aerosol.modes):
         kappa, spectrum = mode["kappa"]["CompressedFilmOvadnevaite"], mode["spectrum"]
-        r_dry, concentration = ConstantMultiplicity(spectrum).sample(n_sd_per_mode)
-        v_dry = builder.formulae.trivia.volume(radius=r_dry)
-        specific_concentration = concentration / builder.formulae.constants.rho_STP
+        r_dry, concentration = ConstantMultiplicity(spectrum).sample_deterministic(
+            n_sd_per_mode
+        )
+        v_dry = formulae.trivia.volume(radius=r_dry)
+        specific_concentration = concentration / env.backend.formulae.constants.rho_STP
         attributes["multiplicity"] = np.append(
             attributes["multiplicity"],
-            specific_concentration * builder.particulator.environment.mass_of_dry_air,
+            specific_concentration * env.mass_of_dry_air,
         )
         attributes["dry volume"] = np.append(attributes["dry volume"], v_dry)
         attributes["kappa times dry volume"] = np.append(
@@ -74,13 +76,20 @@ def run_parcel(
         )
 
     r_wet = equilibrate_wet_radii(
-        r_dry=builder.formulae.trivia.radius(volume=attributes["dry volume"]),
-        environment=builder.particulator.environment,
+        r_dry=formulae.trivia.radius(volume=attributes["dry volume"]),
+        environment=env,
         kappa_times_dry_volume=attributes["kappa times dry volume"],
     )
-    attributes["volume"] = builder.formulae.trivia.volume(radius=r_wet)
+    attributes["volume"] = env.backend.formulae.trivia.volume(radius=r_wet)
 
-    particulator = builder.build(attributes, products=products)
+    particulator = Particulator(
+        n_sd=n_sd,
+        environment=env,
+        dynamics=[AmbientThermodynamics(), Condensation()],
+        requested_attributes=("critical saturation",),
+        attributes=attributes,
+        products=products,
+    )
 
     output = {product.name: [] for product in particulator.products.values()}
     output_attributes = {
@@ -91,7 +100,7 @@ def run_parcel(
     }
 
     for _ in range(n_steps):
-        particulator.run(steps=1)
+        particulator.advance(n_steps=1)
         for product in particulator.products.values():
             value = product.get()
             output[product.name].append(value[0])

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Alpert_and_Knopf_2016/simulation.py

@@ -5,7 +5,7 @@ import numpy as np
 from matplotlib import pyplot
 from packaging import version
 
-from PySDM import Builder, Formulae
+from PySDM import Particulator, Formulae
 from PySDM.backends import CPU
 from PySDM.dynamics import Freezing
 from PySDM.environments import Box
@@ -52,7 +52,7 @@ class Simulation:
             else:
                 total_time = (
                     np.diff(np.asarray(self.temperature_range)) / case["cooling_rate"]
-                )
+                ).item()
 
             constants = None
             if "J_het" not in case:
@@ -214,20 +214,15 @@ def simulation(
         constants=constants,
         particle_shape_and_density="MixedPhaseSpheres",
     )
-    builder = Builder(
-        n_sd=n_sd,
-        backend=CPU(formulae=formulae),
-        environment=Box(dt=time_step, dv=volume),
-    )
-    builder.add_dynamic(Freezing(singular=False))
-    builder.request_attribute("volume")
 
     if hasattr(spectrum, "s_geom") and spectrum.s_geom == 1:
         _isa, _conc = np.full(n_sd, spectrum.m_mode), np.full(
             n_sd, multiplicity / volume
         )
     else:
-        _isa, _conc = spectral_sampling.ConstantMultiplicity(spectrum).sample(n_sd)
+        _isa, _conc = spectral_sampling.ConstantMultiplicity(
+            spectrum
+        ).sample_deterministic(n_sd)
     attributes = {
         "multiplicity": discretise_multiplicities(_conc * volume),
         "immersed surface area": _isa,
@@ -238,12 +233,20 @@ def simulation(
         IceWaterContent(name="qi"),
         TotalUnfrozenImmersedSurfaceArea(name="A_tot"),
     )
-    particulator = builder.build(attributes=attributes, products=products)
-    env = particulator.environment
-
+    env = Box(dt=time_step, dv=volume, backend=CPU(formulae=formulae))
     env["T"] = initial_temperature
     env["a_w_ice"] = np.nan
     env["RH"] = 1 + np.finfo(float).eps
+
+    particulator = Particulator(
+        n_sd=n_sd,
+        environment=env,
+        attributes=attributes,
+        products=products,
+        dynamics=[Freezing(immersion_freezing="time-dependent")],
+        requested_attributes=("volume",),
+    )
+
     svp = particulator.formulae.saturation_vapour_pressure
 
     cell_id = 0
@@ -253,7 +256,7 @@ def simulation(
         if cooling_rate != 0:
             env["T"] -= np.full((1,), cooling_rate * time_step / 2)
             env["a_w_ice"] = svp.pvs_ice(env["T"][0]) / svp.pvs_water(env["T"][0])
-        particulator.run(0 if i == 0 else 1)
+        particulator.advance(0 if i == 0 else 1)
         if cooling_rate != 0:
             env["T"] -= np.full((1,), cooling_rate * time_step / 2)
 

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Alpert_and_Knopf_2016/table_1.py

@@ -1,4 +1,4 @@
-from PySDM_examples.Alpert_and_Knopf_2016.table import Table
+from PySDM_examples.featured.Alpert_and_Knopf_2016.table import Table
 
 from PySDM.initialisation.spectra import Lognormal, TopHat
 from PySDM.physics import si

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Alpert_and_Knopf_2016/table_2.py

@@ -1,4 +1,4 @@
-from PySDM_examples.Alpert_and_Knopf_2016.table import Table
+from PySDM_examples.featured.Alpert_and_Knopf_2016.table import Table
 
 from PySDM.initialisation.spectra import Lognormal
 from PySDM.physics import si

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Arabas_and_Shima_2017/__init__.py

@@ -6,4 +6,7 @@ fig_5.ipynb:
 .. include:: ./fig_5.ipynb.badges.md
 """
 
+from .simulation import Simulation
+from .settings import Settings
+
 # pylint: disable=invalid-name

pysdm_examples-3.0.0/PySDM_examples/featured/Arabas_and_Shima_2017/example.py

@@ -0,0 +1,11 @@
+from PySDM_examples.featured.Arabas_and_Shima_2017.settings import setups
+from PySDM_examples.featured.Arabas_and_Shima_2017.simulation import Simulation
+
+
+def main():
+    for settings in setups:
+        Simulation(settings).run()
+
+
+if __name__ == "__main__":
+    main()

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Arabas_and_Shima_2017/simulation.py

@@ -1,16 +1,16 @@
 import numpy as np
 
 import PySDM.products as PySDM_products
-from PySDM.backends import CPU
-from PySDM.builder import Builder
+from PySDM import Particulator
+from PySDM.backends import Numba
 from PySDM.dynamics import AmbientThermodynamics, Condensation
 from PySDM.environments import Parcel
-from PySDM.initialisation import equilibrate_wet_radii
+from PySDM.initialisation.hygroscopic_equilibrium import equilibrate_wet_radii
 from PySDM.physics import constants as const
 
 
 class Simulation:
-    def __init__(self, settings, backend=CPU):
+    def __init__(self, settings, backend=Numba):
         t_half = settings.z_half / settings.w_avg
 
         dt_output = (2 * t_half) / settings.n_output
@@ -18,40 +18,20 @@ class Simulation:
         while dt_output / self.n_substeps >= settings.dt_max:  # TODO #334 dt_max
             self.n_substeps += 1
 
-        builder = Builder(
-            backend=backend(
-                formulae=settings.formulae,
-                **(
-                    {"override_jit_flags": {"parallel": False}}
-                    if backend == CPU
-                    else {}
-                ),
-            ),
-            n_sd=1,
-            environment=Parcel(
-                dt=dt_output / self.n_substeps,
-                mass_of_dry_air=settings.mass_of_dry_air,
-                p0=settings.p0,
-                initial_water_vapour_mixing_ratio=settings.initial_water_vapour_mixing_ratio,
-                T0=settings.T0,
-                w=settings.w,
-            ),
-        )
-
-        builder.add_dynamic(AmbientThermodynamics())
-        builder.add_dynamic(
-            Condensation(
-                rtol_x=settings.rtol_x,
-                rtol_thd=settings.rtol_thd,
-                dt_cond_range=settings.dt_cond_range,
-            )
-        )
         attributes = {}
         r_dry = np.array([settings.r_dry])
         attributes["dry volume"] = settings.formulae.trivia.volume(radius=r_dry)
         attributes["kappa times dry volume"] = attributes["dry volume"] * settings.kappa
         attributes["multiplicity"] = np.array([settings.n_in_dv], dtype=np.int64)
-        environment = builder.particulator.environment
+        environment = Parcel(
+            dt=dt_output / self.n_substeps,
+            mass_of_dry_air=settings.mass_of_dry_air,
+            p0=settings.p0,
+            initial_water_vapour_mixing_ratio=settings.initial_water_vapour_mixing_ratio,
+            T0=settings.T0,
+            w=settings.w,
+            backend=backend(formulae=settings.formulae),
+        )
         r_wet = equilibrate_wet_radii(
             r_dry=r_dry,
             environment=environment,
@@ -72,7 +52,20 @@ class Simulation:
             PySDM_products.RipeningRate(unit="s^-1 mg^-1", name="ripening_rate"),
         ]
 
-        self.particulator = builder.build(attributes, products)
+        self.particulator = Particulator(
+            n_sd=1,
+            dynamics=[
+                AmbientThermodynamics(),
+                Condensation(
+                    rtol_x=settings.rtol_x,
+                    rtol_thd=settings.rtol_thd,
+                    dt_cond_range=settings.dt_cond_range,
+                ),
+            ],
+            attributes=attributes,
+            products=products,
+            environment=environment,
+        )
 
         self.n_output = settings.n_output
 
@@ -107,7 +100,7 @@ class Simulation:
 
         self.save(output)
         for _ in range(self.n_output):
-            self.particulator.run(self.n_substeps)
+            self.particulator.advance(self.n_substeps)
             self.save(output)
 
         return output

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Arabas_et_al_2025/__init__.py

@@ -2,26 +2,21 @@
 box-model and 2D prescribed-flow immersion-freezing examples based on
 [Arabas et al. 2025](https://doi.org/10.1029/2024MS004770)
 
-aida.ipynb:
-.. include:: ./aida.ipynb.badges.md
-
-copula_hello.ipynb:
-.. include:: ./copula_hello.ipynb.badges.md
-
 fig_2.ipynb:
 .. include:: ./fig_2.ipynb.badges.md
 
-figs_10_and_11_and_animations.ipynb:
-.. include:: ./figs_10_and_11_and_animations.ipynb.badges.md
-
 fig_A2.ipynb:
 .. include:: ./fig_A2.ipynb.badges.md
 
+
 figs_3_and_7_and_8.ipynb:
 .. include:: ./figs_3_and_7_and_8.ipynb.badges.md
 
 figs_5_and_6.ipynb:
 .. include:: ./figs_5_and_6.ipynb.badges.md
+
+figs_10_and_11_and_animations.ipynb:
+.. include:: ./figs_10_and_11_and_animations.ipynb.badges.md
 """
 
 from .make_particulator import make_particulator

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Arabas_et_al_2025/commons.py

@@ -5,6 +5,7 @@ from PySDM.physics import si
 
 FREEZING_CONSTANTS = {
     "dust": {
+        # [Alpert and Knopf (2016, Table 2)](https://doi.org/10.5194/acp-16-2083-2016)
         "NIEMAND_A": -0.517,
         "NIEMAND_B": 8.934,
         "ABIFM_M": 22.62,

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Arabas_et_al_2025/make_particulator.py

@@ -1,6 +1,6 @@
 import numpy as np
 
-from PySDM import Builder, Formulae
+from PySDM import Particulator, Formulae
 from PySDM import products as PySDM_products
 from PySDM.backends import CPU
 from PySDM.dynamics import Freezing
@@ -35,7 +35,7 @@ def make_particulator(
         "particle_shape_and_density": "MixedPhaseSpheres",
     }
     formulae = Formulae(**formulae_ctor_args)
-    backend = CPU(formulae, override_jit_flags={"parallel": False})
+    backend = CPU(formulae)
 
     attributes = {
         "signed water mass": np.ones(n_sd) * droplet_volume * formulae.constants.rho_w
@@ -51,26 +51,31 @@ def make_particulator(
             _,
             attributes["multiplicity"],
         ) = sampling.sample(backend=backend, n_sd=n_sd)
+        immersion_freezing_flag = "singular"
     else:
         (
             _,
             attributes["immersed surface area"],
             attributes["multiplicity"],
         ) = sampling.sample(backend=backend, n_sd=n_sd)
+        immersion_freezing_flag = "time-dependent"
+    if thaw:
+        thaw_flag = "instantaneous"
+    else:
+        thaw_flag = None
     attributes["multiplicity"] *= total_particle_number
 
-    builder = Builder(n_sd=n_sd, backend=backend, environment=Box(dt, volume))
-
-    env = builder.particulator.environment
+    env = Box(dt, volume, backend=backend)
     env["T"] = initial_temperature
     env["RH"] = A_VALUE_LARGER_THAN_ONE
     env["rhod"] = 1.0
 
-    builder.add_dynamic(Freezing(singular=singular, thaw=thaw))
-    builder.request_attribute("volume")
-
-    return builder.build(
+    return Particulator(
+        n_sd=n_sd,
+        environment=env,
+        dynamics=[Freezing(immersion_freezing=immersion_freezing_flag, thaw=thaw_flag)],
         attributes=attributes,
+        requested_attributes=("volume",),
         products=(
             PySDM_products.Time(name="t"),
             PySDM_products.AmbientTemperature(name="T"),

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Arabas_et_al_2025/plots.py

@@ -1,8 +1,8 @@
 import matplotlib
 import numpy as np
 from matplotlib import pyplot
-from PySDM_examples.Arabas_et_al_2025.curved_text import CurvedText
-from PySDM_examples.Arabas_et_al_2025.frozen_fraction import FrozenFraction
+from PySDM_examples.featured.Arabas_et_al_2025.curved_text import CurvedText
+from PySDM_examples.featured.Arabas_et_al_2025.frozen_fraction import FrozenFraction
 
 from PySDM.physics import si
 

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Arabas_et_al_2025/run_simulation.py

@@ -1,10 +1,8 @@
 import numpy as np
 
 
-def update_thermo(particulator, T):
-    env = particulator.environment
-    svp = particulator.formulae.saturation_vapour_pressure
-
+def update_thermo(env, T):
+    svp = env.backend.formulae.saturation_vapour_pressure
     env["T"] = T
     env["a_w_ice"] = svp.pvs_ice(T) / svp.pvs_water(T)
 
@@ -17,10 +15,13 @@ def run_simulation(particulator, temperature_profile, n_steps):
     for step in range(n_steps + 1):
         if step != 0:
             update_thermo(
-                particulator, T=temperature_profile((step - 0.5) * particulator.dt)
+                particulator.environment,
+                T=temperature_profile((step - 0.5) * particulator.dt),
+            )
+            particulator.advance(step - particulator.n_steps)
+            update_thermo(
+                particulator.environment, T=temperature_profile(step * particulator.dt)
             )
-            particulator.run(step - particulator.n_steps)
-            update_thermo(particulator, T=temperature_profile(step * particulator.dt))
             output["frozen"].append(particulator.attributes["volume"].to_ndarray() < 0)
         else:
             output["spectrum"] = {}

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Berry_1967/example.py

@@ -1,9 +1,9 @@
 import os
 
 import numpy as np
-from PySDM_examples.Berry_1967.settings import Settings
-from PySDM_examples.Berry_1967.spectrum_plotter import SpectrumPlotter
-from PySDM_examples.Shima_et_al_2009.example import run
+from PySDM_examples.featured.Berry_1967.settings import Settings
+from PySDM_examples.featured.Berry_1967.spectrum_plotter import SpectrumPlotter
+from PySDM_examples.featured.Shima_et_al_2009.example import run
 
 from PySDM.dynamics.collisions.collision_kernels import (
     Electric,

{pysdm_examples-2.130/PySDM_examples → pysdm_examples-3.0.0/PySDM_examples/featured}/Berry_1967/spectrum_plotter.py

@@ -1,6 +1,6 @@
 from matplotlib import pyplot
 from open_atmos_jupyter_utils import show_plot
-from PySDM_examples.Shima_et_al_2009.spectrum_plotter import (
+from PySDM_examples.featured.Shima_et_al_2009.spectrum_plotter import (
     SpectrumPlotter as SuperSpectrumPlotter,
 )