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

pysdm_examples-3.0.0rc2/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: pysdm-examples
+Version: 3.0.0rc2
+Summary: PySDM usage examples reproducing results from literature and depicting how to use PySDM from Python Jupyter notebooks
+Home-page: https://github.com/open-atmos/PySDM
+Author: https://github.com/open-atmos/PySDM/graphs/contributors
+Author-email: sylwester.arabas@agh.edu.pl
+License: GPL-3.0
+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: Pillow
+Requires-Dist: joblib
+Requires-Dist: ipywidgets
+Requires-Dist: seaborn
+Requires-Dist: numdifftools
+Requires-Dist: vtk
+Requires-Dist: pyvinecopulib>=0.7.3
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: nbconvert; extra == "tests"
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
+
+# 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:
+- <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Arabas_et_al_2015.html">Arabas_et_al_2015</a>
+  - in-notebook GUI for setting up, running and interactively visualising the 2D kinematic simulations (with an option to export raw data to <mark>VTK</mark> and <mark>netCDF</mark> 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 <mark>Paraview</mark>
+- <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Arabas_et_al_2025.html">Arabas_et_al_2025</a>: 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:
+- <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Shipway_and_Hill_2012.html">Shipway_and_Hill_2012</a>: reproducing figures from the <a href="https://doi.org/10.1002/qj.1913">Shipway & Hill 2012</a> paper;
+- <a href="https://open-atmos.github.io/PySDM/PySDM_examples/deJong_Mackay_et_al_2023.html">deJong_Mackay_et_al_2023</a>: 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).
+
+## 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).
+
+<a href="https://open-atmos.github.io/PySDM/PySDM_examples/Rozanski_and_Sonntag_1982.html">Rozanski_and_Sonntag_1982</a>: bulk microphysics example (i.e. single super droplet) with
+deuterium and heavy-oxygen <mark>water isotopologues</mark> 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
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Arabas_and_Shima_2017.html">Arabas_and_Shima_2017</a>: monodisperse particle spectrum, activation/deactivation cycle
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Yang_et_al_2018.html">Yang_et_al_2018</a>: polydisperse particle spectrum, activation/deactivation cycles
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Abdul_Razzak_Ghan_2000.html">Abdul_Razzak_Ghan_2000</a>: polydisperse activation, comparison against <mark>GCM parameterisation</mark>
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Pyrcel.html">Pyrcel</a>: polydisperse activation, mimicking example test case from <mark>Pyrcel</mark> documentation
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Lowe_et_al_2019.html">Lowe_et_al_2019</a>: externally mixed polydisperse size spectrum with <mark>surface-active organics</mark> case
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Grabowski_and_Pawlowska_2023.html">Grabowski_and_Pawlowska_2023</a>: polydisperse activation, focus on <mark>ripening</mark>
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Jensen_and_Nugent_2017.html">Jensen_and_Nugent_2017</a>: polydisperse activation featuring <mark>giant CCN</mark>
+- condensation and aqueous-chemistry
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Kreidenweis_et_al_2003.html">Kreidenweis_et_al_2003</a>: <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)
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Jaruga_and_Pawlowska_2018.html">Jaruga_and_Pawlowska_2018</a>: exploration of numerical convergence using the above Hoppel-gap simulation setup
+- freezing
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Spichtinger_et_al_2023.html">Spichtinger_et_al_2023</a>: <mark>homogeneous freezing</mark> and ice growth (<mark>Wegener-Bergeron-Findeisen process</mark>)
+
+The parcel environment is also featured in the <a href="https://open-atmos.github.io/PySDM/PySDM.html#tutorials">PySDM tutorials</a>.
+
+## 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:
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Shima_et_al_2009.html">Shima_et_al_2009</a>: using <mark>Golovin additive kernel</mark> for comparison against analytic solution, featuring interactive in-notebook interface for selecting simulation parameters
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Berry_1967.html">Berry_1967</a>: examples using geometric, hydrodynamic and electric-field collision kernels
+- coalescence and breakup:
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Bieli_et_al_2022.html">Bieli_et_al_2022</a>: evolution of moments under collisional growth and breakage
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/deJong_Mackay_et_al_2023.html">deJong_Mackay_et_al_2023</a>: 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:
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Alpert_and_Knopf_2016.html">Alpert_and_Knopf_2016</a>: stochastic immersion freezing with monodisperse vs. lognormal immersed surface areas
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Arabas_et_al_2025.html">Arabas_et_al_2025</a>: 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:
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Lamb_et_al_2017.html">Lamb_et_al_2017</a>
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Bolot_et_al_2013.html">Bolot_et_al_2013</a>
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Merlivat_and_Nief_1967.html">Merlivat_and_Nief_1967</a>
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Van_Hook_1968.html">Van_Hook_1968</a>
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Graf_et_al_2019.html">Graf_et_al_2019</a>
+- <mark>Rayleigh fractionation</mark>:
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Pierchala_et_al_2022.html">Pierchala_et_al_2022</a>: reproducing model plots for a <mark>triple-isotope</mark> lab study, including <mark>kinetic fractionation</mark>
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Gonfiantini_1986.html">Gonfiantini_1986</a>: flat-surface evaporation at different humidities for D and <sup>18</sup>O
+- isotopic relaxation timescale:
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Miyake_et_al_1968.html">Miyake_et_al_1968</a>: incl. comparison of different <mark>ventilation</mark> parameterisations
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Bolin_1958.html">Bolin_1958</a>
+- below-cloud <mark>kinetic fractionation</mark>:
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Gedzelman_and_Arnold_1994.html">Gedzelman_and_Arnold_1994</a>
+
+## examples depicting extraterrestrial clouds (formulae-only, no simulations yet)
+- Titan (methane clouds):
+  - <a href="https://open-atmos.github.io/PySDM/PySDM_examples/Toon_et_al_1980.html">Toon_et_al_1980</a>

{pysdm_examples-3.0.0/PySDM_examples/sandbox → pysdm_examples-3.0.0rc2/PySDM_examples}/Abade_and_Albuquerque_2024/settings.py

@@ -1,6 +1,6 @@
 from pystrict import strict
 
-from PySDM.backends import CPU
+from PySDM import Formulae
 from PySDM.physics import si
 from PySDM.initialisation.spectra import Lognormal
 
@@ -10,42 +10,48 @@ class Settings:
     def __init__(
         self,
         *,
-        backend: CPU,
         n_sd: int,
         timestep: float,
-        # default values correspond to paper settings
-        singular: bool = True,
         enable_immersion_freezing: bool = True,
         enable_vapour_deposition_on_ice: bool = True,
         inp_frac: float = 0.1,
-        kappa: float = 0.6,
-        updraft: float = 0.5 * si.m / si.s,
     ):
-        self.backend = backend
         self.n_sd = n_sd
         self.timestep = timestep
         self.enable_immersion_freezing = enable_immersion_freezing
         self.enable_vapour_deposition_on_ice = enable_vapour_deposition_on_ice
-        self.singular = singular
+
         self.initial_total_pressure = 1000 * si.hPa  # note: not given in the paper
 
+        # parameters from the paper
+        self.formulae = Formulae(
+            constants={
+                "bulk_phase_partitioning_exponent": 0.1,
+                "NIEMAND_A": -0.517,
+                "NIEMAND_B": 8.934,
+            },
+            bulk_phase_partitioning="KaulEtAl2015",
+            particle_shape_and_density="MixedPhaseSpheres",
+            diffusion_coordinate="WaterMassLogarithm",
+            freezing_temperature_spectrum="Niemand_et_al_2012",
+        )
         self.initial_water_vapour_mixing_ratio = 1.5 * si.g / si.kg
         self.parcel_linear_extent = 100 * si.m
-        self.updraft = updraft
+        self.updraft = 0.5 * si.m / si.s
         self.freezing_inp_frac = inp_frac
         self.freezing_inp_dry_radius = 0.5 * si.um
 
-        thd_0 = backend.formulae.state_variable_triplet.th_dry(
+        thd_0 = self.formulae.state_variable_triplet.th_dry(
             th_std=269 * si.K,
             water_vapour_mixing_ratio=self.initial_water_vapour_mixing_ratio,
         )
-        rhod_0 = backend.formulae.state_variable_triplet.rho_d(
+        rhod_0 = self.formulae.state_variable_triplet.rho_d(
             p=self.initial_total_pressure,
             water_vapour_mixing_ratio=self.initial_water_vapour_mixing_ratio,
             theta_std=thd_0,
         )
 
-        self.mass_of_dry_air = rhod_0 * backend.formulae.trivia.volume(
+        self.mass_of_dry_air = rhod_0 * self.formulae.trivia.volume(
             radius=self.parcel_linear_extent
         )
         self.soluble_aerosol = Lognormal(
@@ -55,7 +61,7 @@ class Settings:
             m_mode=75 * si.nm,
             s_geom=1.6,
         )
-        self.kappa = kappa
-        self.initial_temperature = backend.formulae.state_variable_triplet.T(
+        self.kappa = 0.6
+        self.initial_temperature = self.formulae.state_variable_triplet.T(
             rhod=rhod_0, thd=thd_0
         )

pysdm_examples-3.0.0rc2/PySDM_examples/Abade_and_Albuquerque_2024/simulation.py

@@ -0,0 +1,94 @@
+import numpy as np
+
+from PySDM_examples.utils import BasicSimulation
+
+from PySDM import Builder
+from PySDM.backends import CPU
+from PySDM.dynamics import (
+    Condensation,
+    AmbientThermodynamics,
+    VapourDepositionOnIce,
+    Freezing,
+)
+from PySDM.initialisation.sampling.spectral_sampling import ConstantMultiplicity
+from PySDM.products import (
+    AmbientTemperature,
+    AmbientWaterVapourMixingRatio,
+    ParcelDisplacement,
+    WaterMixingRatio,
+    SpecificIceWaterContent,
+)
+from PySDM.environments import Parcel
+
+
+class Simulation(BasicSimulation):
+    def __init__(self, settings):
+        builder = Builder(
+            backend=CPU(settings.formulae, override_jit_flags={"parallel": False}),
+            n_sd=settings.n_sd,
+            environment=Parcel(
+                dt=settings.timestep,
+                mass_of_dry_air=settings.mass_of_dry_air,
+                p0=settings.initial_total_pressure,
+                initial_water_vapour_mixing_ratio=settings.initial_water_vapour_mixing_ratio,
+                T0=settings.initial_temperature,
+                w=settings.updraft,
+                mixed_phase=True,
+            ),
+        )
+        builder.add_dynamic(AmbientThermodynamics())
+        builder.add_dynamic(Condensation())
+
+        if settings.enable_immersion_freezing:
+            builder.add_dynamic(Freezing(immersion_freezing="singular"))
+        if settings.enable_vapour_deposition_on_ice:
+            builder.add_dynamic(VapourDepositionOnIce())
+
+        r_dry, n_in_dv = ConstantMultiplicity(settings.soluble_aerosol).sample(
+            n_sd=settings.n_sd
+        )
+        attributes = builder.particulator.environment.init_attributes(
+            n_in_dv=n_in_dv, kappa=settings.kappa, r_dry=r_dry
+        )
+        attributes["signed water mass"] = (
+            builder.particulator.formulae.particle_shape_and_density.volume_to_mass(
+                attributes["volume"]
+            )
+        )
+        del attributes["volume"]
+
+        if settings.enable_immersion_freezing:
+            trivia = builder.particulator.formulae.trivia
+            n_inp = int(settings.n_sd * settings.freezing_inp_frac)
+
+            rng = np.random.default_rng(seed=builder.particulator.formulae.seed)
+
+            attributes["freezing temperature"] = rng.permutation(
+                np.pad(
+                    builder.particulator.formulae.freezing_temperature_spectrum.invcdf(
+                        cdf=rng.uniform(low=0, high=1, size=n_inp),
+                        A_insol=trivia.sphere_surface(
+                            diameter=2 * settings.freezing_inp_dry_radius
+                        ),
+                    ),
+                    (0, settings.n_sd - n_inp),
+                    mode="constant",
+                    constant_values=(trivia.C2K(-38)),
+                )
+            )
+
+        self.products = (
+            WaterMixingRatio(name="water", radius_range=(0, np.inf)),
+            SpecificIceWaterContent(name="ice"),
+            ParcelDisplacement(name="height"),
+            AmbientTemperature(name="T"),
+            AmbientWaterVapourMixingRatio(
+                name="vapour", var="water_vapour_mixing_ratio"
+            ),
+        )
+        super().__init__(
+            particulator=builder.build(attributes=attributes, products=self.products)
+        )
+
+    def run(self, *, nt, steps_per_output_interval):
+        return self._run(nt=nt, steps_per_output_interval=steps_per_output_interval)

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

@@ -1,12 +1,9 @@
 from collections import namedtuple
 
 import numpy as np
-from PySDM_examples.featured.Abdul_Razzak_Ghan_2000.aerosol import (
-    CONSTANTS_ARG,
-    AerosolARG,
-)
+from PySDM_examples.Abdul_Razzak_Ghan_2000.aerosol import CONSTANTS_ARG, AerosolARG
 
-from PySDM import Particulator, Formulae
+from PySDM import Builder, Formulae
 from PySDM import products as PySDM_products
 from PySDM.backends import CPU
 from PySDM.dynamics import AmbientThermodynamics, Condensation
@@ -22,7 +19,6 @@ def run_parcel(
     N2,
     rad2,
     n_sd_per_mode,
-    *,
     RH0=1.0,
     T0=294 * si.K,
     p0=1e5 * si.Pa,
@@ -48,7 +44,6 @@ def run_parcel(
         initial_water_vapour_mixing_ratio=const.eps * pv0 / (p0 - pv0),
         w=w,
         T0=T0,
-        backend=CPU(formulae),
     )
 
     aerosol = AerosolARG(
@@ -56,19 +51,22 @@ 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_deterministic(
-            n_sd_per_mode
-        )
-        v_dry = formulae.trivia.volume(radius=r_dry)
-        specific_concentration = concentration / env.backend.formulae.constants.rho_STP
+        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
         attributes["multiplicity"] = np.append(
             attributes["multiplicity"],
-            specific_concentration * env.mass_of_dry_air,
+            specific_concentration * builder.particulator.environment.mass_of_dry_air,
         )
         attributes["dry volume"] = np.append(attributes["dry volume"], v_dry)
         attributes["kappa times dry volume"] = np.append(
@@ -76,20 +74,13 @@ def run_parcel(
         )
 
     r_wet = equilibrate_wet_radii(
-        r_dry=formulae.trivia.radius(volume=attributes["dry volume"]),
-        environment=env,
+        r_dry=builder.formulae.trivia.radius(volume=attributes["dry volume"]),
+        environment=builder.particulator.environment,
         kappa_times_dry_volume=attributes["kappa times dry volume"],
     )
-    attributes["volume"] = env.backend.formulae.trivia.volume(radius=r_wet)
+    attributes["volume"] = builder.formulae.trivia.volume(radius=r_wet)
 
-    particulator = Particulator(
-        n_sd=n_sd,
-        environment=env,
-        dynamics=[AmbientThermodynamics(), Condensation()],
-        requested_attributes=("critical saturation",),
-        attributes=attributes,
-        products=products,
-    )
+    particulator = builder.build(attributes, products=products)
 
     output = {product.name: [] for product in particulator.products.values()}
     output_attributes = {
@@ -100,7 +91,7 @@ def run_parcel(
     }
 
     for _ in range(n_steps):
-        particulator.advance(n_steps=1)
+        particulator.run(steps=1)
         for product in particulator.products.values():
             value = product.get()
             output[product.name].append(value[0])

{pysdm_examples-3.0.0/PySDM_examples/featured → pysdm_examples-3.0.0rc2/PySDM_examples}/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 Particulator, Formulae
+from PySDM import Builder, 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,15 +214,20 @@ 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(immersion_freezing="time-dependent"))
+    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_deterministic(n_sd)
+        _isa, _conc = spectral_sampling.ConstantMultiplicity(spectrum).sample(n_sd)
     attributes = {
         "multiplicity": discretise_multiplicities(_conc * volume),
         "immersed surface area": _isa,
@@ -233,20 +238,12 @@ def simulation(
         IceWaterContent(name="qi"),
         TotalUnfrozenImmersedSurfaceArea(name="A_tot"),
     )
-    env = Box(dt=time_step, dv=volume, backend=CPU(formulae=formulae))
+    particulator = builder.build(attributes=attributes, products=products)
+    env = particulator.environment
+
     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
@@ -256,7 +253,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.advance(0 if i == 0 else 1)
+        particulator.run(0 if i == 0 else 1)
         if cooling_rate != 0:
             env["T"] -= np.full((1,), cooling_rate * time_step / 2)
 

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

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

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

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

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

@@ -6,7 +6,4 @@ 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.0rc2/PySDM_examples/Arabas_and_Shima_2017/example.py

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

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

@@ -1,8 +1,8 @@
 import numpy as np
 
 import PySDM.products as PySDM_products
-from PySDM import Particulator
-from PySDM.backends import Numba
+from PySDM.backends import CPU
+from PySDM.builder import Builder
 from PySDM.dynamics import AmbientThermodynamics, Condensation
 from PySDM.environments import Parcel
 from PySDM.initialisation.hygroscopic_equilibrium import equilibrate_wet_radii
@@ -10,7 +10,7 @@ from PySDM.physics import constants as const
 
 
 class Simulation:
-    def __init__(self, settings, backend=Numba):
+    def __init__(self, settings, backend=CPU):
         t_half = settings.z_half / settings.w_avg
 
         dt_output = (2 * t_half) / settings.n_output
@@ -18,20 +18,40 @@ 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 = 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),
-        )
+        environment = builder.particulator.environment
         r_wet = equilibrate_wet_radii(
             r_dry=r_dry,
             environment=environment,
@@ -52,20 +72,7 @@ class Simulation:
             PySDM_products.RipeningRate(unit="s^-1 mg^-1", name="ripening_rate"),
         ]
 
-        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.particulator = builder.build(attributes, products)
 
         self.n_output = settings.n_output
 
@@ -100,7 +107,7 @@ class Simulation:
 
         self.save(output)
         for _ in range(self.n_output):
-            self.particulator.advance(self.n_substeps)
+            self.particulator.run(self.n_substeps)
             self.save(output)
 
         return output

pysdm_examples-3.0.0rc2/PySDM_examples/Arabas_et_al_2015/__init__.py

@@ -0,0 +1,10 @@
+# pylint: disable=invalid-name
+"""
+2D prescribed-flow case extended with Paraview visualisation with spin-up logic from
+[Arabas et al. 2015](http://doi.org/10.5194/gmd-8-1677-2015)
+
+gui.ipynb:
+.. include:: ./gui.ipynb.badges.md
+"""
+from .settings import Settings
+from .spin_up import SpinUp