PySDM 2.74__tar.gz → 2.76__tar.gz

{PySDM-2.74 → PySDM-2.76}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PySDM
-Version: 2.74
+Version: 2.76
 Summary: Pythonic particle-based (super-droplet) warm-rain/aqueous-chemistry cloud microphysics package with box, parcel & 1D/2D prescribed-flow examples in Python, Julia and Matlab
 Home-page: https://github.com/open-atmos/PySDM
 Author: https://github.com/open-atmos/PySDM/graphs/contributors

{PySDM-2.74 → PySDM-2.76}/PySDM/backends/impl_numba/methods/__init__.py

@@ -12,3 +12,4 @@ from .moments_methods import MomentsMethods
 from .pair_methods import PairMethods
 from .physics_methods import PhysicsMethods
 from .terminal_velocity_methods import TerminalVelocityMethods
+from .seeding_methods import SeedingMethods

{PySDM-2.74 → PySDM-2.76}/PySDM/backends/impl_numba/methods/condensation_methods.py

@@ -445,7 +445,7 @@ class CondensationMethods(BackendMethods):
                 v_drop = formulae.particle_shape_and_density__mass_to_volume(
                     attributes.water_mass[drop]
                 )
-                if v_drop < 0:
+                if v_drop <= 0:
                     continue
                 x_old = formulae.condensation_coordinate__x(v_drop)
                 r_old = formulae.trivia__radius(v_drop)

PySDM-2.76/PySDM/backends/impl_numba/methods/seeding_methods.py

@@ -0,0 +1,68 @@
+""" CPU implementation of backend methods for particle injections """
+
+from functools import cached_property
+
+import numba
+
+from PySDM.backends.impl_common.backend_methods import BackendMethods
+
+
+class SeedingMethods(BackendMethods):  # pylint: disable=too-few-public-methods
+    @cached_property
+    def _seeding(self):
+        @numba.njit(**{**self.default_jit_flags, "parallel": False})
+        def body(  # pylint: disable=too-many-arguments
+            idx,
+            multiplicity,
+            extensive_attributes,
+            seeded_particle_index,
+            seeded_particle_multiplicity,
+            seeded_particle_extensive_attributes,
+            number_of_super_particles_to_inject: int,
+        ):
+            number_of_super_particles_already_injected = 0
+            # TODO #1387 start enumerating from the end of valid particle set
+            for i, mult in enumerate(multiplicity):
+                if (
+                    number_of_super_particles_to_inject
+                    == number_of_super_particles_already_injected
+                ):
+                    break
+                if mult == 0:
+                    idx[i] = -1
+                    s = seeded_particle_index[
+                        number_of_super_particles_already_injected
+                    ]
+                    number_of_super_particles_already_injected += 1
+                    multiplicity[i] = seeded_particle_multiplicity[s]
+                    for a in range(len(extensive_attributes)):
+                        extensive_attributes[a, i] = (
+                            seeded_particle_extensive_attributes[a, s]
+                        )
+            assert (
+                number_of_super_particles_to_inject
+                == number_of_super_particles_already_injected
+            )
+
+        return body
+
+    def seeding(
+        self,
+        *,
+        idx,
+        multiplicity,
+        extensive_attributes,
+        seeded_particle_index,
+        seeded_particle_multiplicity,
+        seeded_particle_extensive_attributes,
+        number_of_super_particles_to_inject: int,
+    ):
+        self._seeding(
+            idx=idx.data,
+            multiplicity=multiplicity.data,
+            extensive_attributes=extensive_attributes.data,
+            seeded_particle_index=seeded_particle_index.data,
+            seeded_particle_multiplicity=seeded_particle_multiplicity.data,
+            seeded_particle_extensive_attributes=seeded_particle_extensive_attributes.data,
+            number_of_super_particles_to_inject=number_of_super_particles_to_inject,
+        )

{PySDM-2.74 → PySDM-2.76}/PySDM/backends/numba.py

@@ -28,6 +28,7 @@ class Numba(  # pylint: disable=too-many-ancestors,duplicate-code
     methods.DisplacementMethods,
     methods.TerminalVelocityMethods,
     methods.IsotopeMethods,
+    methods.SeedingMethods,
 ):
     Storage = ImportedStorage
     Random = ImportedRandom
@@ -75,3 +76,4 @@ class Numba(  # pylint: disable=too-many-ancestors,duplicate-code
         methods.DisplacementMethods.__init__(self)
         methods.TerminalVelocityMethods.__init__(self)
         methods.IsotopeMethods.__init__(self)
+        methods.SeedingMethods.__init__(self)

{PySDM-2.74 → PySDM-2.76}/PySDM/builder.py

@@ -150,4 +150,8 @@ class Builder:
         for key in self.particulator.dynamics:
             self.particulator.timers[key] = WallTimer()
 
+        if (attributes["multiplicity"] == 0).any():
+            self.particulator.attributes.healthy = False
+            self.particulator.attributes.sanitize()
+
         return self.particulator

{PySDM-2.74 → PySDM-2.76}/PySDM/dynamics/__init__.py

@@ -15,3 +15,4 @@ from PySDM.dynamics.displacement import Displacement
 from PySDM.dynamics.eulerian_advection import EulerianAdvection
 from PySDM.dynamics.freezing import Freezing
 from PySDM.dynamics.relaxed_velocity import RelaxedVelocity
+from PySDM.dynamics.seeding import Seeding

PySDM-2.76/PySDM/dynamics/seeding.py

@@ -0,0 +1,94 @@
+""" particle injection handling, requires initalising a simulation with
+enough particles flagged with NaN multiplicity (translated to zeros
+at multiplicity discretisation """
+
+from collections.abc import Sized
+
+import numpy as np
+
+from PySDM.dynamics.impl import register_dynamic
+from PySDM.initialisation import discretise_multiplicities
+
+
+@register_dynamic()
+class Seeding:
+    def __init__(
+        self,
+        *,
+        super_droplet_injection_rate: callable,
+        seeded_particle_extensive_attributes: dict,
+        seeded_particle_multiplicity: Sized,
+    ):
+        for attr in seeded_particle_extensive_attributes.values():
+            assert len(seeded_particle_multiplicity) == len(attr)
+        self.particulator = None
+        self.super_droplet_injection_rate = super_droplet_injection_rate
+        self.seeded_particle_extensive_attributes = seeded_particle_extensive_attributes
+        self.seeded_particle_multiplicity = seeded_particle_multiplicity
+        self.rnd = None
+        self.u01 = None
+        self.index = None
+
+    def register(self, builder):
+        self.particulator = builder.particulator
+
+    def post_register_setup_when_attributes_are_known(self):
+        if tuple(self.particulator.attributes.get_extensive_attribute_keys()) != tuple(
+            self.seeded_particle_extensive_attributes.keys()
+        ):
+            raise ValueError(
+                f"extensive attributes ({self.seeded_particle_extensive_attributes.keys()})"
+                " do not match those used in particulator"
+                f" ({self.particulator.attributes.get_extensive_attribute_keys()})"
+            )
+
+        self.index = self.particulator.Index.identity_index(
+            len(self.seeded_particle_multiplicity)
+        )
+        if len(self.seeded_particle_multiplicity) > 1:
+            self.rnd = self.particulator.Random(
+                len(self.seeded_particle_multiplicity), self.particulator.formulae.seed
+            )
+            self.u01 = self.particulator.Storage.empty(
+                len(self.seeded_particle_multiplicity), dtype=float
+            )
+        self.seeded_particle_multiplicity = (
+            self.particulator.IndexedStorage.from_ndarray(
+                self.index,
+                discretise_multiplicities(
+                    np.asarray(self.seeded_particle_multiplicity)
+                ),
+            )
+        )
+        self.seeded_particle_extensive_attributes = (
+            self.particulator.IndexedStorage.from_ndarray(
+                self.index,
+                np.asarray(list(self.seeded_particle_extensive_attributes.values())),
+            )
+        )
+
+    def __call__(self):
+        if self.particulator.n_steps == 0:
+            self.post_register_setup_when_attributes_are_known()
+
+        time = self.particulator.n_steps * self.particulator.dt
+        number_of_super_particles_to_inject = self.super_droplet_injection_rate(time)
+
+        if number_of_super_particles_to_inject > 0:
+            assert number_of_super_particles_to_inject <= len(
+                self.seeded_particle_multiplicity
+            )
+
+            if self.rnd is not None:
+                self.u01.urand(self.rnd)
+                # TODO #1387 make shuffle smarter
+                # e.g. don't need to shuffle if only one type of seed particle
+                # or if the number of super particles to inject
+                # is equal to the number of possible seeds
+                self.index.shuffle(self.u01)
+            self.particulator.seeding(
+                seeded_particle_index=self.index,
+                number_of_super_particles_to_inject=number_of_super_particles_to_inject,
+                seeded_particle_multiplicity=self.seeded_particle_multiplicity,
+                seeded_particle_extensive_attributes=self.seeded_particle_extensive_attributes,
+            )

{PySDM-2.74 → PySDM-2.76}/PySDM/impl/particle_attributes.py

@@ -118,3 +118,8 @@ class ParticleAttributes:  # pylint: disable=too-many-instance-attributes
 
     def has_attribute(self, attr):
         return attr in self.__attributes
+
+    def reset_idx(self):
+        self.__valid_n_sd = self.__idx.shape[0]
+        self.__idx.reset_index()
+        self.healthy = False

{PySDM-2.74 → PySDM-2.76}/PySDM/initialisation/discretise_multiplicities.py

@@ -6,11 +6,22 @@ import numpy as np
 
 
 def discretise_multiplicities(values_arg):
-    values_int = values_arg.round().astype(np.int64)
+    """any NaN values in the input array are ignored and flagged
+    with zero multiplicities in the output array"""
+
+    values_int = np.where(np.isnan(values_arg), 0, values_arg).round().astype(np.int64)
 
     if np.issubdtype(values_arg.dtype, np.floating):
+        if np.isnan(values_arg).all():
+            return values_int
+
+        if not np.logical_or(values_int > 0, np.isnan(values_arg)).all():
+            raise ValueError(
+                f"int-casting resulted in multiplicity of zero (min(y_float)={min(values_arg)})"
+            )
+
         percent_diff = 100 * abs(
-            1 - np.sum(values_arg) / np.sum(values_int.astype(float))
+            1 - np.nansum(values_arg) / np.sum(values_int.astype(float))
         )
         if percent_diff > 1:
             raise ValueError(
@@ -18,9 +29,4 @@ def discretise_multiplicities(values_arg):
                 f" due to casting multiplicities to ints"
             )
 
-        if not (values_int > 0).all():
-            raise ValueError(
-                f"int-casting resulted in multiplicity of zero (min(y_float)={min(values_arg)})"
-            )
-
     return values_int

{PySDM-2.74 → PySDM-2.76}/PySDM/initialisation/init_fall_momenta.py

@@ -5,7 +5,6 @@ of droplets
 
 import numpy as np
 
-from PySDM.backends import CPU
 from PySDM.dynamics.terminal_velocity import GunnKinzer1949
 from PySDM.formulae import Formulae
 from PySDM.particulator import Particulator
@@ -31,6 +30,8 @@ def init_fall_momenta(
     if zero:
         return np.zeros_like(water_mass)
 
+    from PySDM.backends import CPU  # pylint: disable=import-outside-toplevel
+
     particulator = Particulator(0, CPU(Formulae()))  # TODO #1155
 
     approximation = terminal_velocity_approx(particulator=particulator)

{PySDM-2.74 → PySDM-2.76}/PySDM/particulator.py

@@ -13,7 +13,7 @@ from PySDM.impl.particle_attributes import ParticleAttributes
 
 
 class Particulator:  # pylint: disable=too-many-public-methods,too-many-instance-attributes
-    def __init__(self, n_sd, backend: BackendMethods):
+    def __init__(self, n_sd, backend):
         assert isinstance(backend, BackendMethods)
         self.__n_sd = n_sd
 
@@ -438,3 +438,44 @@ class Particulator:  # pylint: disable=too-many-public-methods,too-many-instance
         self.backend.isotopic_fractionation()
         for isotope in heavy_isotopes:
             self.attributes.mark_updated(f"moles_{isotope}")
+
+    def seeding(
+        self,
+        *,
+        seeded_particle_index,
+        seeded_particle_multiplicity,
+        seeded_particle_extensive_attributes,
+        number_of_super_particles_to_inject,
+    ):
+        n_null = self.n_sd - self.attributes.super_droplet_count
+        if n_null == 0:
+            raise ValueError(
+                "No available seeds to inject. Please provide particles with nan filled attributes."
+            )
+
+        if number_of_super_particles_to_inject > n_null:
+            raise ValueError(
+                "Trying to inject more super particles than space available."
+            )
+
+        if number_of_super_particles_to_inject > len(seeded_particle_multiplicity):
+            raise ValueError(
+                "Trying to inject multiple super particles with the same attributes. \
+                Instead increase multiplicity of injected particles."
+            )
+
+        self.backend.seeding(
+            idx=self.attributes._ParticleAttributes__idx,
+            multiplicity=self.attributes["multiplicity"],
+            extensive_attributes=self.attributes.get_extensive_attribute_storage(),
+            seeded_particle_index=seeded_particle_index,
+            seeded_particle_multiplicity=seeded_particle_multiplicity,
+            seeded_particle_extensive_attributes=seeded_particle_extensive_attributes,
+            number_of_super_particles_to_inject=number_of_super_particles_to_inject,
+        )
+        self.attributes.reset_idx()
+        self.attributes.sanitize()
+
+        self.attributes.mark_updated("multiplicity")
+        for key in self.attributes.get_extensive_attribute_keys():
+            self.attributes.mark_updated(key)

{PySDM-2.74 → PySDM-2.76}/PySDM.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PySDM
-Version: 2.74
+Version: 2.76
 Summary: Pythonic particle-based (super-droplet) warm-rain/aqueous-chemistry cloud microphysics package with box, parcel & 1D/2D prescribed-flow examples in Python, Julia and Matlab
 Home-page: https://github.com/open-atmos/PySDM
 Author: https://github.com/open-atmos/PySDM/graphs/contributors

{PySDM-2.74 → PySDM-2.76}/PySDM.egg-info/SOURCES.txt

@@ -105,6 +105,7 @@ PySDM/backends/impl_numba/methods/isotope_methods.py
 PySDM/backends/impl_numba/methods/moments_methods.py
 PySDM/backends/impl_numba/methods/pair_methods.py
 PySDM/backends/impl_numba/methods/physics_methods.py
+PySDM/backends/impl_numba/methods/seeding_methods.py
 PySDM/backends/impl_numba/methods/terminal_velocity_methods.py
 PySDM/backends/impl_numba/test_helpers/__init__.py
 PySDM/backends/impl_numba/test_helpers/scipy_ode_condensation_solver.py
@@ -139,6 +140,7 @@ PySDM/dynamics/eulerian_advection.py
 PySDM/dynamics/freezing.py
 PySDM/dynamics/isotopic_fractionation.py
 PySDM/dynamics/relaxed_velocity.py
+PySDM/dynamics/seeding.py
 PySDM/dynamics/collisions/__init__.py
 PySDM/dynamics/collisions/collision.py
 PySDM/dynamics/collisions/breakup_efficiencies/__init__.py
@@ -620,6 +622,11 @@ examples/PySDM_examples/deJong_Mackay_et_al_2023/simulation1D.py
 examples/PySDM_examples/deJong_Mackay_et_al_2023/simulation_0D.py
 examples/PySDM_examples/deJong_Mackay_et_al_2023/simulation_ss.py
 examples/PySDM_examples/deJong_Mackay_et_al_2023/data/straub_fig10.csv
+examples/PySDM_examples/seeding/__init__.py
+examples/PySDM_examples/seeding/hello_world.ipynb
+examples/PySDM_examples/seeding/seeding_no_collisions.ipynb
+examples/PySDM_examples/seeding/settings.py
+examples/PySDM_examples/seeding/simulation.py
 examples/PySDM_examples/utils/__init__.py
 examples/PySDM_examples/utils/basic_simulation.py
 examples/PySDM_examples/utils/dummy_controller.py
@@ -704,6 +711,9 @@ tests/smoke_tests/parcel_a/pyrcel/__init__.py
 tests/smoke_tests/parcel_a/pyrcel/test_parcel_example.py
 tests/smoke_tests/parcel_a/rozanski_and_sonntag_1982/__init__.py
 tests/smoke_tests/parcel_a/rozanski_and_sonntag_1982/test_figs_4_5_6.py
+tests/smoke_tests/parcel_a/seeding/__init__.py
+tests/smoke_tests/parcel_a/seeding/test_hello_world.py
+tests/smoke_tests/parcel_a/seeding/test_seeding_no_collisions.py
 tests/smoke_tests/parcel_b/arabas_and_shima_2017/__init__.py
 tests/smoke_tests/parcel_b/arabas_and_shima_2017/test_conservation.py
 tests/smoke_tests/parcel_b/arabas_and_shima_2017/test_displacement.py
@@ -773,6 +783,7 @@ tests/unit_tests/backends/test_moments_methods.py
 tests/unit_tests/backends/test_oxidation.py
 tests/unit_tests/backends/test_pair_methods.py
 tests/unit_tests/backends/test_physics_methods.py
+tests/unit_tests/backends/test_seeding_methods.py
 tests/unit_tests/backends/test_toms748.py
 tests/unit_tests/backends/storage/__init__.py
 tests/unit_tests/backends/storage/test_basic_ops.py
@@ -783,6 +794,7 @@ tests/unit_tests/dynamics/test_eulerian_advection.py
 tests/unit_tests/dynamics/test_impl_register_dynamic.py
 tests/unit_tests/dynamics/test_isotopic_fractionation.py
 tests/unit_tests/dynamics/test_relaxed_velocity.py
+tests/unit_tests/dynamics/test_seeding.py
 tests/unit_tests/dynamics/test_terminal_velocity.py
 tests/unit_tests/dynamics/collisions/__init__.py
 tests/unit_tests/dynamics/collisions/conftest.py
@@ -811,6 +823,7 @@ tests/unit_tests/impl/test_moments.py
 tests/unit_tests/impl/test_particle_attributes.py
 tests/unit_tests/initialisation/__init__.py
 tests/unit_tests/initialisation/test_aerosol_init.py
+tests/unit_tests/initialisation/test_discretise_multiplicities.py
 tests/unit_tests/initialisation/test_equilibrate_wet_radii.py
 tests/unit_tests/initialisation/test_init_fall_momenta.py
 tests/unit_tests/initialisation/test_spatial_discretisation.py

PySDM-2.76/examples/PySDM_examples/seeding/__init__.py

@@ -0,0 +1,2 @@
+from .settings import Settings
+from .simulation import Simulation