PySDM 3.0.0rc12__tar.gz → 3.0.0rc16__tar.gz

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/.github/actions/env-setup/action.yml

@@ -43,6 +43,10 @@ runs:
             exit(0)
         EOF
       shell: bash
+    
+    - name: set NUMBA_THREADING_LAYER
+      run: echo NUMBA_THREADING_LAYER=workqueue >> $GITHUB_ENV
+      shell: bash
 
     - uses: actions/cache/save@v4
       if: steps.cache.outputs.cache-hit != 'true'

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/.github/workflows/pdoc.yml

@@ -28,7 +28,7 @@ jobs:
           python-version: "3.12"
 
       - name: exclude pvpython scripts
-        run: rm examples/PySDM_examples/utils/pvanim.py
+        run: grep -rl '^#!/usr/bin/env pvpython' examples/PySDM_examples | xargs rm -f
 
       - run: pip install pdoc nbformat gitpython
       - run: pip install -e .

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/.github/workflows/precommit.yml

@@ -24,7 +24,7 @@ jobs:
       - uses: actions/checkout@v4.1.6
       - uses: actions/setup-python@v5.0.0
         with:
-          python-version: 3.9
+          python-version: "3.10"
       - run: |
           pip install pre-commit
           pre-commit clean

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/.github/workflows/pypi.yml

@@ -58,10 +58,7 @@ jobs:
     strategy:
       matrix:
         platform: [ ubuntu-latest, macos-latest, windows-latest ]
-        python-version: [ "3.9", "3.12" ]
-        exclude:
-          - platform: macos-14
-            python-version: "3.9"
+        python-version: [ "3.10", "3.12" ]
     runs-on: ${{ matrix.platform }}
     needs: [ package ]
     steps:

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/.github/workflows/readme_snippets.yml

@@ -23,9 +23,8 @@ jobs:
       - uses: actions/setup-python@v5.0.0
         with:
           python-version: "3.10"
-      - run: python -m pip install $PIP_INSTALL_ARGS -e .
+      - run: python -m pip install $PIP_INSTALL_ARGS -e .[CI_version_pins]
       - run: python -m pip install $PIP_INSTALL_ARGS pytest-codeblocks pytest
-      - run: python -m pip install $PIP_INSTALL_ARGS "pillow<11.3.0"  # matplotlib triggers deprecation warnings in 11.3.0
       - run: |
           python -c "import os,pytest_codeblocks; code=pytest_codeblocks.extract_from_file('docs/markdown/pysdm_landing.md'); f=open('readme.py', 'w', encoding='utf-8'); f.write('# coding: utf-8'+os.linesep); f.writelines(block.code for block in code if block.syntax=='Python'); f.close()"
       - run: cat -n readme.py
@@ -49,7 +48,7 @@ jobs:
       - uses: actions/setup-python@v5.0.0
         with:
           python-version: "3.10"
-      - run: pip install -e .
+      - run: pip install -e .[CI_version_pins]
       - run: pip install pytest-codeblocks pytest
       - run: python -c "import pytest_codeblocks; code=pytest_codeblocks.extract_from_file('docs/markdown/pysdm_landing.md'); f=open('readme.jl', 'w'); f.writelines(block.code for block in code if block.syntax=='Julia'); f.close()"
       - uses: julia-actions/setup-julia@v2
@@ -65,14 +64,17 @@ jobs:
       - uses: actions/checkout@v4.1.6
       - uses: actions/setup-python@v5.0.0
         with:
-          python-version: 3.9
-      - run: pip install -e .
+          python-version: "3.12"
+
+      - run: echo NUMBA_THREADING_LAYER=workqueue >> $GITHUB_ENV
+
+      - run: pip install -e .[CI_version_pins]
       - run: pip install pytest-codeblocks pytest
       - run: python -c "import pytest_codeblocks; code=pytest_codeblocks.extract_from_file('docs/markdown/pysdm_landing.md'); f=open('readme.m', 'w'); f.writelines(block.code for block in code if block.syntax=='Matlab'); f.close()"
       - run: cat -n readme.m
       - uses: matlab-actions/setup-matlab@v2.1.0
         with:
-          release: R2022a
+          release: R2024b
           cache: true
       - uses: matlab-actions/run-command@v2.1.0
         with:

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/.github/workflows/tests.yml

@@ -26,7 +26,7 @@ jobs:
     strategy:
       matrix:
         platform: [ ubuntu-24.04, macos-15-intel, macos-14, windows-latest ]
-        python-version: [ "3.9", "3.12" ]
+        python-version: [ "3.10", "3.12" ]
     runs-on: ${{ matrix.platform }}
     steps:
       - uses: actions/checkout@v4.1.6
@@ -45,7 +45,7 @@ jobs:
         python-version: ["3.12"]
         include: # for pylint
           - platform: ubuntu-24.04
-            python-version: "3.9"
+            python-version: "3.10"
     runs-on: ${{ matrix.platform }}
     steps:
       - uses: actions/checkout@v4.1.6
@@ -62,7 +62,7 @@ jobs:
     strategy:
       matrix:
         platform: [ubuntu-24.04]
-        python-version: ["3.9"]
+        python-version: ["3.10"]
     runs-on: ${{ matrix.platform }}
     steps:
     - uses: actions/checkout@v4.1.6
@@ -84,14 +84,14 @@ jobs:
         pylint --max-module-lines=550 --unsafe-load-any-extension=y --disable=fixme,too-many-function-args,unsubscriptable-object,consider-using-with,protected-access,too-many-statements,too-many-public-methods,too-many-branches,duplicate-code,invalid-name,missing-function-docstring,missing-module-docstring,missing-class-docstring,too-many-locals,too-many-instance-attributes,too-few-public-methods,too-many-arguments,c-extension-no-member $(git ls-files '*.py' | grep ^examples)
     - run: |
         # TODO #682
-        nbqa pylint --unsafe-load-any-extension=y --disable=fixme,duplicate-code,invalid-name,trailing-whitespace,line-too-long,missing-function-docstring,wrong-import-position,missing-module-docstring,wrong-import-order,ungrouped-imports,no-member,too-many-locals,unnecessary-lambda-assignment $(git ls-files '*.ipynb')
+        nbqa pylint --unsafe-load-any-extension=y --disable=fixme,duplicate-code,invalid-name,trailing-whitespace,line-too-long,missing-function-docstring,wrong-import-position,missing-module-docstring,wrong-import-order,ungrouped-imports,no-member,too-many-locals,unnecessary-lambda-assignment,multiple-imports $(git ls-files '*.ipynb')
 
   unit-tests-without-jit-plus-codecov:
     needs: env-unit-tests-setup
     strategy:
       matrix:
         platform: [ ubuntu-24.04, macos-15-intel, macos-14, windows-latest ]
-        python-version: [ "3.9", "3.12" ]
+        python-version: [ "3.10", "3.12" ]
     runs-on: ${{ matrix.platform }}
     env:
       NUMBA_DISABLE_JIT: 1
@@ -109,7 +109,7 @@ jobs:
       run: |
         python -m pip install pytest-cov
         python -m pytest ${{ env.pytest_options }} tests/unit_tests --cov-report=xml --cov=PySDM
-    - uses: codecov/codecov-action@v4.5.0
+    - uses: codecov/codecov-action@v5.5.2
       with:
         fail_ci_if_error: true
         verbose: true
@@ -138,8 +138,6 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           setup-name: unit-tests-${{ matrix.platform }}-${{ matrix.python-version }}
-      - if: startsWith(matrix.platform, 'ubuntu-')
-        run: echo NUMBA_THREADING_LAYER=omp >> $GITHUB_ENV
       - name: Run pytest
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -199,9 +197,6 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           setup-name: nonunit-tests-${{ matrix.platform }}-${{ matrix.python-version }}
-
-      - if: startsWith(matrix.platform, 'ubuntu-')
-        run: echo NUMBA_THREADING_LAYER=omp >> $GITHUB_ENV
       - name: Run pytest
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -231,7 +226,10 @@ jobs:
         include:
           - platform: "macos-14"
             python-version: "3.12"
-            test-suite: "multi-process_a,multi-process_b,multi-process_d,multi-process_e"
+            test-suite: "multi-process_a,multi-process_b"
+          - platform: "macos-14"
+            python-version: "3.12"
+            test-suite: "multi-process_d,multi-process_e"
         exclude:
           - platform: "macos-14"
             test-suite: "multi-process_a"
@@ -243,7 +241,7 @@ jobs:
             test-suite: "multi-process_e"
       fail-fast: true
     runs-on: ${{ matrix.platform }}
-    timeout-minutes: ${{ startsWith(matrix.platform, 'windows-') && 28 || 30 }}
+    timeout-minutes: 30
     steps:
       - name: Debug contexts
         run: |
@@ -261,8 +259,6 @@ jobs:
           python-version: ${{ matrix.python-version }}
           setup-name: nonunit-tests-${{ matrix.platform }}-${{ matrix.python-version }}
           # https://github.com/numba/numba/issues/6350#issuecomment-728174860
-      - if: startsWith(matrix.platform, 'ubuntu-')
-        run: echo NUMBA_THREADING_LAYER=omp >> $GITHUB_ENV
 
       - if: startsWith(matrix.platform, 'ubuntu-') && (contains(matrix.test-suite, 'multi-process_a') || contains(matrix.test-suite, 'multi-process_b'))
         run: |
@@ -300,8 +296,10 @@ jobs:
           rm /tmp/pytest/test_run_notebooks_*current
           ls /tmp/pytest/test_run_notebooks_*/
           ls /tmp/pytest/test_run_notebooks_*/output/
-          ffmpeg -i /tmp/pytest/test_run_notebooks_*/output/docs_intro_animation.ogv -loop 0 -vf "fps=10,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" $HOME/work/_temp/_github_home/figures/docs_intro_animation_${{ matrix.platform }}.gif
           mv /tmp/pytest/test_run_notebooks_*/output/last_animation_frame.pdf $HOME/work/_temp/_github_home/figures/last_animation_frame_${{ matrix.platform }}.pdf
+          for anim_name in docs_intro_animation parcel_animation; do
+              ffmpeg -i /tmp/pytest/test_run_notebooks_*/output/${anim_name}.ogv -loop 0 -vf "fps=10,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" $HOME/work/_temp/_github_home/figures/${anim_name}_${{ matrix.platform }}.gif
+          done
           ls $HOME/work/_temp/_github_home/figures
 
       - name: animation movie upload

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/.pre-commit-config.yaml

@@ -28,3 +28,9 @@ repos:
     - id: detect-missing-init
       args: ['--create', "--track", "--python-folders", "tests,PySDM,examples/PySDM_examples"]
 
+  - repo: https://github.com/open-atmos/devops_tests
+    rev: v0.0.2
+    hooks:
+      - id: check-badges
+        name: check badges
+        args: [--fix-header, --repo-name=PySDM]

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pysdm
-Version: 3.0.0rc12
+Version: 3.0.0rc16
 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
 Author-email: "https://github.com/open-atmos/PySDM/graphs/contributors" <sylwester.arabas@agh.edu.pl>
 License-Expression: GPL-3.0-only
@@ -33,7 +33,6 @@ Provides-Extra: unit-tests
 Requires-Dist: pytest; extra == "unit-tests"
 Requires-Dist: pytest-timeout; extra == "unit-tests"
 Requires-Dist: matplotlib!=3.9.1; extra == "unit-tests"
-Requires-Dist: Pillow<11.3.0; extra == "unit-tests"
 Provides-Extra: nonunit-tests
 Requires-Dist: pytest; extra == "nonunit-tests"
 Requires-Dist: PySDM-examples; extra == "nonunit-tests"

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/PySDM/attributes/isotopes/moles.py

@@ -18,7 +18,7 @@ derived attributes providing amounts of light isotopes in water (1H and 16O)
         ) / (2 * molar_mass_1H + molar_mass_16O)
 
         moles_1H = 2 * (moles_H2O + moles_17O + moles_18O) + moles_2H + moles_3H
-        moles_16O =  .5 * (moles_2H + moles_3H) + moles_H2O
+        moles_16O = moles_2H + moles_3H + moles_H2O
 """
 
 from PySDM.attributes.impl import DerivedAttribute, register_attribute
@@ -45,24 +45,15 @@ class Helper(DerivedAttribute):
 class MolesLightWater(Helper):
     def __init__(self, builder):
         const = builder.formulae.constants
-        M_H2O = 2 * const.M_1H + const.M_16O
         super().__init__(
             builder=builder,
             name="moles light water",
             attrs_to_multiplier={
-                builder.get_attribute("moles_2H"): -(
-                    const.M_1H * const.M_2H + const.M_16O
-                )
-                / M_H2O,
-                builder.get_attribute("moles_3H"): -(
-                    const.M_1H * const.M_3H + const.M_16O
-                )
-                / M_H2O,
-                builder.get_attribute("moles_17O"): -(2 * const.M_1H + const.M_17O)
-                / M_H2O,
-                builder.get_attribute("moles_18O"): -(2 * const.M_1H + const.M_18O)
-                / M_H2O,
-                builder.get_attribute("signed water mass"): 1 / M_H2O,
+                builder.get_attribute("moles_2H"): -const.M_2H_1H_16O / const.M_1H2_16O,
+                builder.get_attribute("moles_3H"): -const.M_3H_1H_16O / const.M_1H2_16O,
+                builder.get_attribute("moles_17O"): -const.M_1H2_17O / const.M_1H2_16O,
+                builder.get_attribute("moles_18O"): -const.M_1H2_18O / const.M_1H2_16O,
+                builder.get_attribute("signed water mass"): 1 / const.M_1H2_16O,
             },
         )
 
@@ -90,8 +81,8 @@ class Moles16O(Helper):
             builder=builder,
             name="moles_16O",
             attrs_to_multiplier={
-                builder.get_attribute("moles_2H"): 0.5,
-                builder.get_attribute("moles_3H"): 0.5,
+                builder.get_attribute("moles_2H"): 1.0,
+                builder.get_attribute("moles_3H"): 1.0,
                 builder.get_attribute("moles light water"): 1.0,
             },
         )

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/PySDM/dynamics/isotopic_fractionation.py

@@ -1,6 +1,8 @@
 """
-resolves fractionation of water molecules across different isotopologues
-requires condensation dynamic to be registered (and run beforehand)
+Resolves fractionation of water molecules across different isotopologues.
+
+Requires condensation dynamic to be registered (and run beforehand).
+Considers only single-substituted molecules (i.e. no D2O, etc.)
 """
 
 from PySDM.dynamics.condensation import Condensation

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/PySDM/environments/kinematic_1d.py

@@ -60,12 +60,12 @@ class Kinematic1D(Moist):
             ) = self.mesh.cellular_attributes(positions)
 
             if collisions_only:
-                v_wet, n_per_kg = spectral_discretisation.sample(
+                v_wet, n_per_kg = spectral_discretisation.sample_deterministic(
                     backend=self.particulator.backend, n_sd=self.particulator.n_sd
                 )
                 attributes["volume"] = v_wet
             else:
-                r_dry, n_per_kg = spectral_discretisation.sample(
+                r_dry, n_per_kg = spectral_discretisation.sample_deterministic(
                     backend=self.particulator.backend, n_sd=self.particulator.n_sd
                 )
                 attributes["dry volume"] = self.formulae.trivia.volume(radius=r_dry)

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/PySDM/environments/kinematic_2d.py

@@ -60,9 +60,9 @@ class Kinematic2D(Moist):
                 attributes["position in cell"],
             ) = self.mesh.cellular_attributes(positions)
 
-            r_dry, n_per_kg = spectral_sampling(spectrum=dry_radius_spectrum).sample(
-                n_sd=n_sd, backend=self.particulator.backend
-            )
+            r_dry, n_per_kg = spectral_sampling(
+                spectrum=dry_radius_spectrum
+            ).sample_deterministic(n_sd=n_sd, backend=self.particulator.backend)
 
             attributes["dry volume"] = self.formulae.trivia.volume(radius=r_dry)
             attributes["kappa times dry volume"] = kappa * attributes["dry volume"]

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/PySDM/exporters/__init__.py

@@ -6,3 +6,4 @@ from .netcdf_exporter import NetCDFExporter
 from .netcdf_exporter_1d import NetCDFExporter_1d, readNetCDF_1d
 from .vtk_exporter import VTKExporter
 from .vtk_exporter_1d import VTKExporter_1d
+from .vtk_exporter_parcel import VTKExporterParcel

pysdm-3.0.0rc16/PySDM/exporters/vtk_exporter_parcel.py

@@ -0,0 +1,151 @@
+"""
+VTK Exporter for parcel PySDM simulations.
+
+This module defines `VTKExporterParcel`, a subclass of `PySDM.exporters.VTKExporter`,
+that writes simulation outputs to VTK format using `pyevtk`. It exports product
+profiles (e.g., relative humidity) as unstructured grids and particle attributes
+as point clouds, along with `.pvd` collection files for time-series visualization
+in ParaView.
+"""
+
+from pyevtk.hl import unstructuredGridToVTK, pointsToVTK
+from pyevtk.vtk import VtkHexahedron, VtkGroup
+import numpy as np
+
+from PySDM.exporters.vtk_exporter import VTKExporter
+
+
+# pylint: disable=too-many-instance-attributes
+class VTKExporterParcel(VTKExporter):
+    """
+    Custom VTK exporter for parcel PySDM, exporting products as grids
+    and attributes as point clouds for ParaView visualization.
+    """
+
+    def __init__(self, n_sd, output, mass_of_dry_air):
+        super().__init__()
+        self.output = output
+        self.coords = {
+            "x": np.random.random(n_sd),
+            "y": np.random.random(n_sd),
+            "z": np.random.random(n_sd),
+        }
+        self.half_diagonal = []
+        self.n_levels = len(self.output["products"]["z"])
+
+        volume = mass_of_dry_air / output["products"]["rhod"][0]
+        delta_z = output["products"]["z"][1] - output["products"]["z"][0]
+        for level in range(self.n_levels):
+            if level > 0:
+                prev_to_curr_density_ratio = (
+                    output["products"]["rhod"][level - 1]
+                    / output["products"]["rhod"][level]
+                )
+                volume *= prev_to_curr_density_ratio
+                delta_z = (
+                    output["products"]["z"][level] - output["products"]["z"][level - 1]
+                )
+            area = volume / delta_z
+            self.half_diagonal.append((2 * area) ** 0.5)
+
+    def write_pvd(self):
+        pvd_attributes = VtkGroup(self.attributes_file_path)
+        for key, value in self.exported_times["attributes"].items():
+            pvd_attributes.addFile(key + ".vtu", sim_time=value)
+        pvd_attributes.save()
+
+        pvd_products = VtkGroup(self.products_file_path)
+        for key, value in self.exported_times["products"].items():
+            pvd_products.addFile(key + ".vtu", sim_time=value)
+        pvd_products.save()
+
+    def export_products(
+        self, step, simulation
+    ):  # pylint: disable=arguments-differ, too-many-locals
+        path = self.products_file_path + "_num" + self.add_leading_zeros(step)
+        self.exported_times["products"][path] = step * simulation.particulator.dt
+
+        n_vertices = 4 * self.n_levels
+        x_vertices = np.zeros(n_vertices)
+        y_vertices = np.zeros(n_vertices)
+        z_vertices = np.zeros(n_vertices)
+        connectivity = [0, 1, 2, 3]
+        cell_type = np.zeros(self.n_levels - 1)
+        cell_type[:] = VtkHexahedron.tid
+
+        for level in range(self.n_levels):
+            half_diag = self.half_diagonal[level]
+            current_z = self.output["products"]["z"][level]
+            idx = level * 4
+            x_vertices[idx], y_vertices[idx], z_vertices[idx] = (
+                -half_diag,
+                -half_diag,
+                current_z,
+            )
+            idx += 1
+            x_vertices[idx], y_vertices[idx], z_vertices[idx] = (
+                -half_diag,
+                half_diag,
+                current_z,
+            )
+            idx += 1
+            x_vertices[idx], y_vertices[idx], z_vertices[idx] = (
+                half_diag,
+                half_diag,
+                current_z,
+            )
+            idx += 1
+            x_vertices[idx], y_vertices[idx], z_vertices[idx] = (
+                half_diag,
+                -half_diag,
+                current_z,
+            )
+            connectivity += [*range(4 * (level + 1), 4 * (level + 2))] * 2
+        connectivity = np.asarray(connectivity[:-4])
+        offset = np.asarray(range(8, 8 * self.n_levels, 8))
+
+        _ = {"test_pd": np.array([44] * n_vertices)}
+
+        relative_humidity = self.output["products"]["S_max_percent"]
+        cell_data = {
+            "RH": np.full(shape=(len(relative_humidity) - 1,), fill_value=np.nan)
+        }
+        cell_data["RH"][:step] = (
+            np.array(relative_humidity[:-1] + np.diff(relative_humidity) / 2)
+        )[:step]
+        unstructuredGridToVTK(
+            path,
+            x_vertices,
+            y_vertices,
+            z_vertices,
+            connectivity=connectivity,
+            offsets=offset,
+            cell_types=cell_type,
+            cellData=cell_data,
+        )
+
+    def export_attributes(self, step, simulation):  # pylint: disable=arguments-differ
+        path = self.attributes_file_path + "_num" + self.add_leading_zeros(step)
+        self.exported_times["attributes"][path] = step * simulation.particulator.dt
+
+        payload = {}
+
+        for key in self.output["attributes"].keys():
+            payload[key] = np.asarray(self.output["attributes"][key])[:, step].copy()
+        if step != 0:
+            delta_z = (
+                self.output["products"]["z"][step]
+                - self.output["products"]["z"][step - 1]
+            )
+            if step == 1:
+                self.coords["z"] *= delta_z
+            else:
+                self.coords["z"] += delta_z
+
+        pointsToVTK(
+            path,
+            2 * (self.coords["x"] - 0.5) * self.half_diagonal[step],
+            2 * (self.coords["y"] - 0.5) * self.half_diagonal[step],
+            self.coords["z"],
+            data=payload,
+        )

pysdm-3.0.0rc16/PySDM/initialisation/sampling/spectral_sampling.py

@@ -0,0 +1,153 @@
+"""
+spectral discretisation logic incl. linear, logarithmic, and constant-multiplicity
+ layouts with deterministic, pseudorandom and quasirandom sampling
+"""
+
+import abc
+from typing import Optional, Tuple
+
+import numpy as np
+from scipy.interpolate import interp1d
+
+default_cdf_range = (0.00001, 0.99999)
+
+
+class SpectralSampling:
+    def __init__(
+        self,
+        spectrum,
+        *,
+        size_range: Optional[Tuple[float, float]] = None,
+        error_threshold: Optional[float] = None,
+    ):
+        self.spectrum = spectrum
+        self.error_threshold = error_threshold or 0.01
+
+        if size_range is None:
+            self.cdf_range = default_cdf_range
+            self.size_range = spectrum.percentiles(self.cdf_range)
+        else:
+            assert len(size_range) == 2
+            assert size_range[0] > 0
+            assert size_range[1] > size_range[0]
+            self.size_range = size_range
+            self.cdf_range = (
+                spectrum.cdf(size_range[0]),
+                spectrum.cdf(size_range[1]),
+            )
+
+    @abc.abstractmethod
+    def _sample(self, frac_values):
+        pass
+
+    def _sample_with_grid(self, grid):
+        x = grid[1:-1:2]
+        cdf = self.spectrum.cumulative(grid[0::2])
+        y_float = cdf[1:] - cdf[0:-1]
+
+        diff = abs(1 - np.sum(y_float) / self.spectrum.norm_factor)
+        if diff > self.error_threshold:
+            raise ValueError(
+                f"{diff * 100:.3g}% error in total real-droplet number due to sampling "
+                f"({len(x)} samples)"
+            )
+
+        return x, y_float
+
+    def sample_deterministic(
+        self, n_sd, *, backend=None
+    ):  # pylint: disable=unused-argument
+        return self._sample(
+            frac_values=np.linspace(
+                self.cdf_range[0], self.cdf_range[1], num=2 * n_sd + 1
+            )
+        )
+
+    def sample_quasirandom(self, n_sd, *, backend):
+        num_elements = n_sd
+        storage = backend.Storage.empty(num_elements, dtype=float)
+        backend.Random(seed=backend.formulae.seed, size=num_elements)(storage)
+        u01 = storage.to_ndarray()
+
+        frac_values = np.linspace(
+            self.cdf_range[0], self.cdf_range[1], num=2 * n_sd + 1
+        )
+
+        for i in range(1, len(frac_values) - 1, 2):
+            frac_values[i] = frac_values[i - 1] + u01[i // 2] * (
+                frac_values[i + 1] - frac_values[i - 1]
+            )
+
+        return self._sample(frac_values=frac_values)
+
+    def sample_pseudorandom(self, n_sd, *, backend):
+        num_elements = 2 * n_sd + 1
+        storage = backend.Storage.empty(num_elements, dtype=float)
+        backend.Random(seed=backend.formulae.seed, size=num_elements)(storage)
+        u01 = storage.to_ndarray()
+
+        frac_values = np.sort(
+            self.cdf_range[0] + u01 * (self.cdf_range[1] - self.cdf_range[0])
+        )
+        return self._sample(frac_values=frac_values)
+
+
+class Logarithmic(SpectralSampling):
+    def _sample(self, frac_values):
+        grid = np.exp(
+            (np.log(self.size_range[1]) - np.log(self.size_range[0])) * frac_values
+            + np.log(self.size_range[0])
+        )
+        return self._sample_with_grid(grid)
+
+
+class Linear(SpectralSampling):
+    def _sample(self, frac_values):
+        grid = self.size_range[0] + frac_values * (
+            self.size_range[1] - self.size_range[0]
+        )
+        return self._sample_with_grid(grid)
+
+
+class ConstantMultiplicity(SpectralSampling):
+    def _sample(self, frac_values):
+        grid = self.spectrum.percentiles(frac_values)
+        assert np.isfinite(grid).all()
+        return self._sample_with_grid(grid)
+
+
+class AlphaSampling(SpectralSampling):
+    """as in [Matsushima et al. 2023](https://doi.org/10.5194/gmd-16-6211-2023)"""
+
+    def __init__(
+        self,
+        spectrum,
+        *,
+        alpha,
+        dist_1_inv,
+        interp_points,
+        size_range=None,
+        error_threshold: Optional[float] = None,
+    ):
+        super().__init__(
+            spectrum, size_range=size_range, error_threshold=error_threshold
+        )
+        self.alpha = alpha
+        self.dist_0_cdf = self.spectrum.cdf
+        self.dist_1_inv = dist_1_inv
+        self.x_prime = np.linspace(
+            self.size_range[0], self.size_range[1], num=interp_points
+        )
+
+    def _sample(self, frac_values):
+        if self.alpha == 0:
+            frac_values = self.spectrum.percentiles(frac_values)
+        elif self.alpha == 1:
+            frac_values = self.dist_1_inv(frac_values, self.size_range)
+        else:
+            sd_cdf = self.dist_0_cdf(self.x_prime)
+            x_sd_cdf = (1 - self.alpha) * self.x_prime + self.alpha * self.dist_1_inv(
+                sd_cdf, self.size_range
+            )
+            frac_values = interp1d(sd_cdf, x_sd_cdf)(frac_values)
+        return self._sample_with_grid(frac_values)

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/PySDM/initialisation/spectra/sum.py

@@ -20,7 +20,7 @@ class Sum:
         cdf_arg = np.zeros(len(interpolation_grid) * len(self.spectra) + 1)
         cdf_arg[1:] = np.concatenate(percentiles)
         cdf = self.cumulative(cdf_arg) / self.norm_factor
-        self.inverse_cdf = interp1d(cdf, cdf_arg)
+        self.inverse_cdf = interp1d(cdf, cdf_arg, bounds_error=False)
 
     def size_distribution(self, arg):
         result = 0.0
@@ -36,3 +36,9 @@ class Sum:
 
     def percentiles(self, cdf_values):
         return self.inverse_cdf(cdf_values)
+
+    def pdf(self, arg):
+        return self.size_distribution(arg) / self.norm_factor
+
+    def cdf(self, arg):
+        return self.cumulative(arg) / self.norm_factor

{pysdm-3.0.0rc12 → pysdm-3.0.0rc16}/docs/bibliography.json

@@ -951,6 +951,15 @@
     "title": "A physically constrained classical description of the homogeneous nucleation of ice in water",
     "label": "Koop and Murray 2016 (J. Chem. Phys. 145)"
   },
+  "https://doi.org/10.5194/gmd-16-6211-2023": {
+    "title": "Overcoming computational challenges to realize meter- to submeter-scale resolution in cloud simulations using the super-droplet method",
+    "label": "Matsushima et al. 2023 (Geosci. Model Dev. 16)",
+    "usages": [
+      "PySDM/initialisation/sampling/spectral_sampling.py",
+      "examples/PySDM_examples/Matsushima_et_al_2023/figure_1.ipynb",
+      "examples/PySDM_examples/Matsushima_et_al_2023/__init__.py"
+    ]
+  },
   "https://doi.org/10.48550/arXiv.2509.05536": {
     "usages": [
       "examples/PySDM_examples/Ware_et_al_2025/__init__.py",