add "threshold" homogeneous freezing & refactor immersion/homogenesous freezing setting flags + new thaw logic + GPU support for homogeneous freezing + removal of paper .md files in anticipation of 3.0-preX releasing scheme + update in copula examples to match changes in pyvinecopulib API (#1665)

Co-authored-by: Sylwester Arabas <[email protected]>

Author: tluettm

.github/workflows/joss.yml

@@ -16,7 +16,7 @@ jobs:
   pdoc:
     strategy:
       matrix:
-        platform: [ ubuntu-latest, macos-13, windows-latest ]
+        platform: [ ubuntu-latest, macos-latest, windows-latest ]
     runs-on: ${{ matrix.platform }}
     steps:
       - uses: actions/[email protected]

.github/workflows/joss_paper.yml

@@ -57,7 +57,7 @@ jobs:
   pkg_install_check:
     strategy:
       matrix:
-        platform: [ ubuntu-latest, macos-13, macos-14, windows-latest ]
+        platform: [ ubuntu-latest, macos-latest, windows-latest ]
         python-version: [ "3.9", "3.12" ]
         exclude:
           - platform: macos-14

.github/workflows/pdoc.yml

@@ -243,7 +243,7 @@ jobs:
 
       # TODO #1207
       - if: startsWith(matrix.platform, 'macos-13')
-        run: python -m pytest --basetemp=/tmp/pytest ${{ env.pytest_options }} tests/examples_tests/test_run* -k "not Rozanski_and_Sonntag_1982" --suite ${{ matrix.test-suite }}
+        run: python -m pytest --basetemp=/tmp/pytest ${{ env.pytest_options }} tests/examples_tests/test_run* -k "not (Rozanski_and_Sonntag_1982 or copula_hello)" --suite ${{ matrix.test-suite }}
 
       - if: ( ! startsWith(matrix.platform, 'macos-13') )
         run: python -m pytest ${{ env.pytest_options }} --basetemp=/tmp/pytest --timeout_method=thread --timeout=${{ startsWith(matrix.platform, 'windows-') && 1000 || 900 }} tests/examples_tests/test_run* --suite ${{ matrix.test-suite }}

.github/workflows/pypi.yml

@@ -20,7 +20,9 @@ class TemperatureOfLastFreezing(DerivedAttribute):
 
     def __init__(self, builder):
         assert "Freezing" in builder.particulator.dynamics
-        assert not builder.particulator.dynamics["Freezing"].singular
+        assert (
+            builder.particulator.dynamics["Freezing"].immersion_freezing != "singular"
+        )
         self.signed_water_mass = builder.get_attribute("signed water mass")
         self.cell_id = builder.get_attribute("cell id")
         super().__init__(

.github/workflows/tests.yml

@@ -1,5 +1,6 @@
 """
-groups of attributes used in either singular or time-dependent immersion freezing regimes
+groups of attributes used in either singular or time-dependent immersion freezing regimes,
+in threshold or time-dependent homogeneous freezing and for thaw routines
 """
 
 from collections import namedtuple
@@ -36,3 +37,14 @@ class TimeDependentHomogeneousAttributes(
     """groups attributes required in time-dependent regime for homogeneous freezing"""
 
     __slots__ = ()
+
+
+class ThresholdHomogeneousAndThawAttributes(
+    namedtuple(
+        typename="ThresholdHomogeneousAttributes",
+        field_names=("signed_water_mass"),
+    )
+):
+    """groups attributes required in time-dependent regime for homogeneous freezing"""
+
+    __slots__ = ()

PySDM/attributes/ice/freezing_temperature.py

@@ -14,6 +14,7 @@
     SingularAttributes,
     TimeDependentAttributes,
     TimeDependentHomogeneousAttributes,
+    ThresholdHomogeneousAndThawAttributes,
 )
 
 
@@ -37,25 +38,40 @@ def body(signed_water_mass, i):
         return body
 
     @cached_property
-    def _freeze_singular_body(self):
+    def _thaw_instantaneous_body(self):
         _thaw = self._thaw
-        _freeze = self._freeze
         frozen_and_above_freezing_point = (
             self.formulae.trivia.frozen_and_above_freezing_point
         )
+
+        @numba.njit(**self.default_jit_flags)
+        def body(attributes, cell, temperature):
+            n_sd = len(attributes.signed_water_mass)
+            for i in numba.prange(n_sd):  # pylint: disable=not-an-iterable
+                if frozen_and_above_freezing_point(
+                    attributes.signed_water_mass[i], temperature[cell[i]]
+                ):
+                    _thaw(attributes.signed_water_mass, i)
+
+        return body
+
+    @cached_property
+    def _immersion_freezing_singular_body(self):
+        _freeze = self._freeze
         unfrozen_and_saturated = self.formulae.trivia.unfrozen_and_saturated
 
         @numba.njit(**self.default_jit_flags)
-        def body(attributes, temperature, relative_humidity, cell, thaw):
+        def body(
+            attributes,
+            temperature,
+            relative_humidity,
+            cell,
+        ):
             n_sd = len(attributes.freezing_temperature)
             for i in numba.prange(n_sd):  # pylint: disable=not-an-iterable
                 if attributes.freezing_temperature[i] == 0:
                     continue
-                if thaw and frozen_and_above_freezing_point(
-                    attributes.signed_water_mass[i], temperature[cell[i]]
-                ):
-                    _thaw(attributes.signed_water_mass, i)
-                elif (
+                if (
                     unfrozen_and_saturated(
                         attributes.signed_water_mass[i], relative_humidity[cell[i]]
                     )
@@ -66,12 +82,8 @@ def body(attributes, temperature, relative_humidity, cell, thaw):
         return body
 
     @cached_property
-    def _freeze_time_dependent_body(self):
-        _thaw = self._thaw
+    def _immersion_freezing_time_dependent_body(self):
         _freeze = self._freeze
-        frozen_and_above_freezing_point = (
-            self.formulae.trivia.frozen_and_above_freezing_point
-        )
         unfrozen_and_saturated = self.formulae.trivia.unfrozen_and_saturated
         j_het = self.formulae.heterogeneous_ice_nucleation_rate.j_het
         prob_zero_events = self.formulae.trivia.poissonian_avoidance_function
@@ -83,20 +95,14 @@ def body(  # pylint: disable=too-many-arguments
             timestep,
             cell,
             a_w_ice,
-            temperature,
             relative_humidity,
-            thaw,
         ):
             n_sd = len(attributes.signed_water_mass)
             for i in numba.prange(n_sd):  # pylint: disable=not-an-iterable
                 if attributes.immersed_surface_area[i] == 0:
                     continue
                 cell_id = cell[i]
-                if thaw and frozen_and_above_freezing_point(
-                    attributes.signed_water_mass[i], temperature[cell_id]
-                ):
-                    _thaw(attributes.signed_water_mass, i)
-                elif unfrozen_and_saturated(
+                if unfrozen_and_saturated(
                     attributes.signed_water_mass[i], relative_humidity[cell_id]
                 ):
                     rate_assuming_constant_temperature_within_dt = (
@@ -111,12 +117,8 @@ def body(  # pylint: disable=too-many-arguments
         return body
 
     @cached_property
-    def _freeze_time_dependent_homogeneous_body(self):
-        _thaw = self._thaw
+    def _homogeneous_freezing_time_dependent_body(self):
         _freeze = self._freeze
-        frozen_and_above_freezing_point = (
-            self.formulae.trivia.frozen_and_above_freezing_point
-        )
         unfrozen_and_ice_saturated = self.formulae.trivia.unfrozen_and_ice_saturated
         j_hom = self.formulae.homogeneous_ice_nucleation_rate.j_hom
         prob_zero_events = self.formulae.trivia.poissonian_avoidance_function
@@ -136,17 +138,12 @@ def body(  # pylint: disable=unused-argument,too-many-arguments
             a_w_ice,
             temperature,
             relative_humidity_ice,
-            thaw,
         ):
 
             n_sd = len(attributes.signed_water_mass)
             for i in numba.prange(n_sd):  # pylint: disable=not-an-iterable
                 cell_id = cell[i]
-                if thaw and frozen_and_above_freezing_point(
-                    attributes.signed_water_mass[i], temperature[cell_id]
-                ):
-                    _thaw(attributes.signed_water_mass, i)
-                elif unfrozen_and_ice_saturated(
+                if unfrozen_and_ice_saturated(
                     attributes.signed_water_mass[i], relative_humidity_ice[cell_id]
                 ):
                     d_a_w_ice = (relative_humidity_ice[cell_id] - 1.0) * a_w_ice[
@@ -167,33 +164,64 @@ def body(  # pylint: disable=unused-argument,too-many-arguments
 
         return body
 
-    def freeze_singular(
-        self, *, attributes, temperature, relative_humidity, cell, thaw: bool
+    @cached_property
+    def _homogeneous_freezing_threshold_body(self):
+        _freeze = self._freeze
+        unfrozen_and_ice_saturated = self.formulae.trivia.unfrozen_and_ice_saturated
+        const = self.formulae.constants
+
+        @numba.njit(**self.default_jit_flags)
+        def body(attributes, cell, temperature, relative_humidity_ice):
+            n_sd = len(attributes.signed_water_mass)
+            for i in numba.prange(n_sd):  # pylint: disable=not-an-iterable
+                cell_id = cell[i]
+                if unfrozen_and_ice_saturated(
+                    attributes.signed_water_mass[i], relative_humidity_ice[cell_id]
+                ):
+                    if temperature[cell_id] <= const.HOMOGENEOUS_FREEZING_THRESHOLD:
+                        _freeze(attributes.signed_water_mass, i)
+
+        return body
+
+    def thaw_instantaneous(
+        self,
+        *,
+        attributes,
+        cell,
+        temperature,
+    ):
+        self._thaw_instantaneous_body(
+            ThresholdHomogeneousAndThawAttributes(
+                signed_water_mass=attributes.signed_water_mass.data,
+            ),
+            cell.data,
+            temperature.data,
+        )
+
+    def immersion_freezing_singular(
+        self, *, attributes, temperature, relative_humidity, cell
     ):
-        self._freeze_singular_body(
+        self._immersion_freezing_singular_body(
             SingularAttributes(
                 freezing_temperature=attributes.freezing_temperature.data,
                 signed_water_mass=attributes.signed_water_mass.data,
             ),
             temperature.data,
             relative_humidity.data,
             cell.data,
-            thaw=thaw,
         )
 
-    def freeze_time_dependent(
+    def immersion_freezing_time_dependent(
         self,
         *,
         rand,
         attributes,
         timestep,
         cell,
         a_w_ice,
-        temperature,
         relative_humidity,
-        thaw: bool,
     ):
-        self._freeze_time_dependent_body(
+        self._immersion_freezing_time_dependent_body(
             rand.data,
             TimeDependentAttributes(
                 immersed_surface_area=attributes.immersed_surface_area.data,
@@ -202,12 +230,27 @@ def freeze_time_dependent(
             timestep,
             cell.data,
             a_w_ice.data,
-            temperature.data,
             relative_humidity.data,
-            thaw=thaw,
         )
 
-    def freeze_time_dependent_homogeneous(
+    def homogeneous_freezing_threshold(
+        self,
+        *,
+        attributes,
+        cell,
+        temperature,
+        relative_humidity_ice,
+    ):
+        self._homogeneous_freezing_threshold_body(
+            ThresholdHomogeneousAndThawAttributes(
+                signed_water_mass=attributes.signed_water_mass.data,
+            ),
+            cell.data,
+            temperature.data,
+            relative_humidity_ice.data,
+        )
+
+    def homogeneous_freezing_time_dependent(
         self,
         *,
         rand,
@@ -217,9 +260,8 @@ def freeze_time_dependent_homogeneous(
         a_w_ice,
         temperature,
         relative_humidity_ice,
-        thaw: bool,
     ):
-        self._freeze_time_dependent_homogeneous_body(
+        self._homogeneous_freezing_time_dependent_body(
             rand.data,
             TimeDependentHomogeneousAttributes(
                 volume=attributes.volume.data,
@@ -230,7 +272,6 @@ def freeze_time_dependent_homogeneous(
             a_w_ice.data,
             temperature.data,
             relative_humidity_ice.data,
-            thaw=thaw,
         )
 
     @cached_property