PySDM 3.0.0rc19__tar.gz → 3.0.0rc20__tar.gz

pysdm-3.0.0rc20/.github/workflows/precommit.yml

@@ -0,0 +1,47 @@
+name: precommit and devops tests
+
+defaults:
+  run:
+    shell: bash
+
+env:
+  # common options for pytest
+  pytest_options: "--durations=10 -v -s -We -p no:unraisableexception"
+
+on:
+  push:
+    branches: [ main ]
+    paths: ['docs/**', '**.md']
+  pull_request:
+    branches: [ main ]
+  schedule:
+    - cron: '0 13 * * 4'
+
+jobs:
+  precommit:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4.1.6
+      - uses: actions/setup-python@v5.0.0
+        with:
+          python-version: "3.10"
+      - run: |
+          pip install pre-commit
+          pre-commit clean
+          pre-commit autoupdate
+          pre-commit run --all-files
+      - if: ${{ failure() }}
+        run: git diff
+
+  devops:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4.1.6
+        with:
+          submodules: recursive
+          fetch-depth: 0  # https://github.com/pypa/setuptools_scm/issues/480
+      - run: pip install -r tests/devops_tests/requirements.txt
+      - env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: pytest  ${{ env.pytest_options }} -k "not test_run_notebooks" tests/devops_tests
+

pysdm-3.0.0rc19/.github/workflows/precommit.yml → pysdm-3.0.0rc20/.github/workflows/urlcheck.yml

@@ -1,51 +1,14 @@
-name: precommit, url-check and devops tests
+name: url-check
 
 defaults:
   run:
     shell: bash
 
-env:
-  # common options for pytest
-  pytest_options: "--durations=10 -v -s -We -p no:unraisableexception"
-
 on:
-  push:
-    branches: [ main ]
-    paths: ['docs/**', '**.md']
-  pull_request:
-    branches: [ main ]
   schedule:
     - cron: '0 13 * * 4'
 
 jobs:
-  precommit:
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v4.1.6
-      - uses: actions/setup-python@v5.0.0
-        with:
-          python-version: "3.10"
-      - run: |
-          pip install pre-commit
-          pre-commit clean
-          pre-commit autoupdate
-          pre-commit run --all-files
-      - if: ${{ failure() }}
-        run: git diff
-
-  devops:
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v4.1.6
-        with:
-          submodules: recursive
-          fetch-depth: 0  # https://github.com/pypa/setuptools_scm/issues/480
-      - run: pip install -r tests/devops_tests/requirements.txt
-      - env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: pytest  ${{ env.pytest_options }} -k "not test_run_notebooks" tests/devops_tests
-
-
   url-check:
     runs-on: ubuntu-24.04
     continue-on-error: true
@@ -67,10 +30,10 @@ jobs:
           verbose: true
 
           # The timeout seconds to provide to requests, defaults to 5 seconds
-          timeout: 7
+          timeout: 15
 
           # How many times to retry a failed request (each is logged, defaults to 1)
-          retry_count: 3
+          retry_count: 5
 
           # A comma separated links to exclude during URL checks
           exclude_urls: https://www.gnu.org/licenses/gpl-3.0.html,https://open-atmos.github.io/PySDM/\2/\3.html

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pysdm
-Version: 3.0.0rc19
+Version: 3.0.0rc20
 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

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/attributes/isotopes/delta.py

@@ -17,7 +17,7 @@ class DeltaImpl(DerivedAttribute):
         else:
             raise NotImplementedError()
 
-        self.heavy_isotope = builder.get_attribute("moles_" + heavy_isotope)
+        self.heavy_isotope = builder.get_attribute(f"moles_{heavy_isotope}")
         self.light_isotope = builder.get_attribute(f"moles_{light_isotope}")
         super().__init__(
             builder,

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/backends/impl_numba/methods/condensation_methods.py

@@ -1,6 +1,7 @@
 """
 CPU implementation of backend methods for water condensation/evaporation
-"""
+with adaptive timestepping as in [Bartman 2020 (MSc thesis, Section 3.3)](https://www.ap.uj.edu.pl/diplomas/attachments/file/download/125485)
+"""  # pylint: disable=line-too-long
 
 from collections import namedtuple
 import math

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/dynamics/collisions/coalescence_efficiencies/berry1967.py

@@ -1,5 +1,5 @@
 """
-E.X. Berry 1967
+[Berry 1967](https://doi.org/10.1175/1520-0469(1967)024%3C0688:CDGBC%3E2.0.CO;2)
 Cloud Droplet Growth by Collection
 """
 

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/dynamics/collisions/coalescence_efficiencies/lowlist1982.py

@@ -1,5 +1,5 @@
 """
-See Low & List 1982
+See [Low & List 1982](https://doi.org/10.1175/1520-0469(1982)039%3C1607:CCABOR%3E2.0.CO;2)
 """
 
 import numpy as np

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/dynamics/collisions/coalescence_efficiencies/straub2010.py

@@ -1,4 +1,5 @@
 """
+[Straub et al. 2010](https://doi.org/10.1175/2009JAS3175.1)
 TODO #744
 """
 

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/dynamics/condensation.py

@@ -1,7 +1,8 @@
 """
 bespoke condensational growth solver
 with implicit-in-particle-size integration and adaptive timestepping
-"""
+as in [Bartman 2020 (MSc thesis, Section 3.3)](https://www.ap.uj.edu.pl/diplomas/attachments/file/download/125485)
+"""  # pylint: disable=line-too-long
 
 from collections import namedtuple
 

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/dynamics/seeding.py

@@ -1,4 +1,4 @@
-"""particle injection handling, requires initalising a simulation with
+"""particle injection handling, requires initialising a simulation with
 enough particles flagged with NaN multiplicity (translated to zeros
 at multiplicity discretisation"""
 

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/dynamics/terminal_velocity/gunn_and_kinzer.py

@@ -1,7 +1,7 @@
 """
 [Gunn & Kinzer 1949](https://doi.org/10.1175/1520-0469(1949)006%3C0243:TTVOFF%3E2.0.CO;2)
- terminal velocities used for things like coalescence kernel evaluation, particle displacement,
- ventilation factor, etc
+terminal velocities used for things like coalescence kernel evaluation, particle
+displacement, ventilation factor, etc
 """
 
 import numba
@@ -17,7 +17,8 @@ class GunnKinzer1949:  # pylint: disable=too-few-public-methods
         self.particulator = particulator
 
         """
-        Gunn & Kinzer 1949, Table 2
+        Table 2 in
+        [Gunn & Kinzer 1949](https://doi.org/10.1175/1520-0469(1949)006%3C0243:TTVOFF%3E2.0.CO;2)
         """
         ir = (
             np.array(

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/dynamics/terminal_velocity/power_series.py

@@ -1,7 +1,8 @@
 """
 Power series expression - a simple and mutable power-law (where the coefficients are specified
 by the user), which is a form used in many more complex terminal velocity parameterizations
-such as Rogers & Yau. This formulation emerges from balancing drag and gravitational forces on
+such as [Rogers & Yau 1989](https://archive.org/details/shortcourseinclo0000roge_m3k2).
+This formulation emerges from balancing drag and gravitational forces on
 a spherical object, and the power depends on the drag coefficient (and thus the Reynolds number
 and flow regime). Rogers and Yau distinguishes different power law parameters for three regimes,
 whereas this much simpler formulation applies across the full range of particle sizes.

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/dynamics/terminal_velocity/rogers_and_yau.py

@@ -1,5 +1,6 @@
 """
-Rogers & Yau, equations: (8.5), (8.6), (8.8)
+[Rogers & Yau](https://archive.org/details/shortcourseinclo0000roge_m3k2),
+equations: (8.5), (8.6), (8.8)
 """
 
 

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/initialisation/aerosol_composition/__init__.py

@@ -1,5 +1,5 @@
 """
-classes defining structure for specifying interal and external mixtures of aerosols
+classes defining structure for specifying internal and external mixtures of aerosols
 and functions for computing bulk properties of the aerosol like kappa
 """
 

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/physics/constants.py

@@ -64,7 +64,9 @@ PER_MEG = PPM
 
 T0 = sci.zero_Celsius * si.kelvin
 
-# there are so few water ions instead of K we have K [H2O] (see Seinfeld & Pandis p 345)
+# there are so few water ions instead of K we have K [H2O], see [Seinfeld & Pandis, p. 345](
+# https://archive.org/details/0237-pdf-atmospheric-chemistry-and-physics-2nd-ed-j.-seinfeld-s.-pandis-wiley-2006-ww
+# )
 M = si.mole / si.litre
 K_H2O = 1e-14 * M * M
 

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/physics/diffusion_ice_capacity/__init__.py

@@ -1,5 +1,5 @@
 """
-Formulae for capacity in diffusional growh/evaporation of ice
+Formulae for capacity in diffusional growth/evaporation of ice
 """
 
 from .spherical import Spherical

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/physics/diffusion_ice_kinetics/__init__.py

@@ -1,5 +1,5 @@
 """
-Formulae for handling transition-régime corrections in diffusional growh/evaporation of ice
+Formulae for handling transition-régime corrections in diffusional growth/evaporation of ice
 """
 
 from .neglect import Neglect

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/physics/diffusion_kinetics/lowe_et_al_2019.py

@@ -1,6 +1,6 @@
 """
 as in [Lowe et al. 2019](https://doi.org/10.1038/s41467-019-12982-0)
-uses eq. 13-14 in Pruppacher & Klett 2005 with Delta v = 0
+uses eq. 13-14 in [Pruppacher & Klett](https://doi.org/10.1007/978-0-306-48100-0) with Delta v = 0
 and no corrections for thermal conductivity
 """
 

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/physics/drop_growth/fick.py

@@ -27,7 +27,8 @@ class Fick:
         Parameters
         ----------
         Fk
-            Thermodynamic term associated with heat conduction from Rogers & Yau 1989.
+            Thermodynamic term associated with heat conduction from
+            [Rogers & Yau 1989](https://archive.org/details/shortcourseinclo0000roge_m3k2
         Fd
             Term associated with vapour diffusion.
         """

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/physics/drop_growth/howell_1949.py

@@ -34,7 +34,8 @@ class Howell1949(Fick):  # pylint: disable=too-few-public-methods
         Parameters
         ----------
         Fk
-            Thermodynamic term associated with heat conduction from Rogers & Yau 1989.
+            Thermodynamic term associated with heat conduction from
+            [Rogers & Yau 1989](https://archive.org/details/shortcourseinclo0000roge_m3k2).
         Fd
             Term associated with vapour diffusion.
         """

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/physics/particle_shape_and_density/columnar_ice.py

@@ -11,7 +11,7 @@ class ColumnarIce(PorousSpheroid):
 
     @staticmethod
     def polar_radius_empirical_parametrisation(const, mass):
-        """Sec. 3.1.2 in [Spichtinger & Gierens 2009].
+        """Sec. 3.1.2 in [Spichtinger & Gierens 2009](https://doi.org/10.5194/acp-9-685-2009).
         Note that the notation in the paper is incorrect.
         """
         return np.where(
@@ -26,7 +26,7 @@ class ColumnarIce(PorousSpheroid):
 
     @staticmethod
     def aspect_ratio_empirical_parametrisation(const, mass):
-        """Eq. 17 in [Spichtinger & Gierens 2009]"""
+        """Eq. 17 in [Spichtinger & Gierens 2009](https://doi.org/10.5194/acp-9-685-2009)"""
         return np.where(
             mass < const.columnar_ice_mass_transition,
             1,

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/PySDM/products/condensation/condensation_timestep.py

@@ -1,6 +1,10 @@
 """
-minimum and maximum condensation timestep (fetching a value resets the counter)
-"""
+minimum and maximum condensation timestep in between product get() calls
+(fetching a value resets the counter)
+The time step is variable when adaptive timestepping is enabled
+(see Fig. 5 and Fig. 8 in [Bartman 2020 (MSc thesis, Section 3.3)](https://www.ap.uj.edu.pl/diplomas/attachments/file/download/125485)
+for sample plots of this product)
+"""  # pylint: disable=line-too-long
 
 import numpy as np
 

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/docs/bibliography.json

@@ -169,7 +169,8 @@
   "https://doi.org/10.5194/acp-7-1961-2007": {
     "usages": [
       "PySDM/physics/hygroscopicity/kappa_koehler.py",
-      "PySDM/physics/constants_defaults.py"
+      "PySDM/physics/constants_defaults.py",
+      "examples/PySDM_examples/Jensen_and_Nugent_2017/settings.py"
     ],
     "label": "Petters & Kreidenweis 2007 (Atmos. Chem. Phys. 7)",
     "title": "A single parameter representation of hygroscopic growth and cloud condensation nucleus activity"
@@ -210,7 +211,8 @@
   },
   "https://doi.org/10.1175/1520-0469(1982)039%3C1607:CCABOR%3E2.0.CO;2": {
     "usages": [
-      "PySDM/dynamics/collisions/breakup_fragmentations/lowlist82.py"
+      "PySDM/dynamics/collisions/breakup_fragmentations/lowlist82.py",
+      "PySDM/dynamics/collisions/coalescence_efficiencies/lowlist1982.py"
     ],
     "label": "Low & List 1982 (J. Atmos. Sci. 39)",
     "title": "Collision, Coalescence and Breakup of Raindrops. Part II: Parameterization of Fragment Size Distributions"
@@ -291,6 +293,7 @@
     "usages": [
       "examples/PySDM_examples/deJong_Mackay_et_al_2023/fig_9.ipynb",
       "PySDM/dynamics/collisions/breakup_fragmentations/straub2010.py",
+      "PySDM/dynamics/collisions/coalescence_efficiencies/straub2010.py",
       "PySDM/physics/constants_defaults.py"
     ],
     "label": "Straub et al. 2010 (J. Atmos. Sci. 67)",
@@ -525,7 +528,8 @@
       "examples/PySDM_examples/Berry_1967/figs_5_8_10.ipynb",
       "examples/PySDM_examples/Berry_1967/__init__.py",
       "PySDM/dynamics/collisions/collision_kernels/electric.py",
-      "PySDM/dynamics/collisions/collision_kernels/hydrodynamic.py"
+      "PySDM/dynamics/collisions/collision_kernels/hydrodynamic.py",
+      "PySDM/dynamics/collisions/coalescence_efficiencies/berry1967.py"
     ],
     "label": "Berry 1967 (J. Atmos. Sci. 24)",
     "title": "Cloud Droplet Growth by Collection"
@@ -742,7 +746,9 @@
       "PySDM/physics/terminal_velocity/rogers_yau.py",
       "PySDM/physics/drop_growth/fick.py",
       "PySDM/physics/drop_growth/howell_1949.py",
-      "PySDM/physics/drop_growth/mason_1971.py"
+      "PySDM/physics/drop_growth/mason_1971.py",
+      "PySDM/dynamics/terminal_velocity/rogers_and_yau.py",
+      "PySDM/dynamics/terminal_velocity/power_series.py"
     ],
     "title": "A short course in clouds physics",
     "label": "Rogers & Yau 1989 (Pergamon Press)"
@@ -781,12 +787,18 @@
     "label": "Cotton et al. 2011 (International Geophysics 99)"
   },
   "https://doi.org/10.1007/978-0-306-48100-0": {
-    "usages": ["PySDM/physics/constants_defaults.py"],
+    "usages": [
+      "PySDM/physics/constants_defaults.py",
+      "PySDM/physics/diffusion_kinetics/lowe_et_al_2019.py"
+    ],
     "title": "Microphysics of Clouds and Precipitation",
     "label": "Pruppacher & Klett 2010 (Springer Dordrecht)"
   },
   "https://archive.org/details/0237-pdf-atmospheric-chemistry-and-physics-2nd-ed-j.-seinfeld-s.-pandis-wiley-2006-ww": {
-    "usages": ["PySDM/physics/constants_defaults.py"],
+    "usages": [
+      "PySDM/physics/constants_defaults.py",
+      "PySDM/physics/constants.py"
+    ],
     "title": "Microphysics of Clouds and Precipitation",
     "label": "Seinfeld & Pandis 2006 (Wiley)"
   },
@@ -983,5 +995,14 @@
     ],
     "label": "Barthazy and Schefold 2006 (Atmos. Res. 82)",
     "title": "Fall velocity of snowflakes of different riming degree and crystal types"
+  },
+  "https://www.ap.uj.edu.pl/diplomas/attachments/file/download/125485": {
+    "usages": [
+      "PySDM/backends/impl_numba/methods/condensation_methods.py",
+      "PySDM/dynamics/condensation.py",
+      "PySDM/products/condensation/condensation_timestep.py"
+    ],
+    "label": "Bartman 2020 (MSc thesis)",
+    "title": "PySDM v1.0: Pythonic particle-based cloud microphysics package"
   }
 }

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/docs/generate_html.py

@@ -67,8 +67,9 @@ def check_urls(urls_from_json):
                 r"\b(https://doi\.org/10[.][0-9]{4,}(?:[.][0-9]+)*/(?:(?![\"&\'<>^\\])\S)+)\b",
                 r"\b(https://digitallibrary\.un\.org/record/(?:[0-9])+)\b",
                 r"\b(http://mi\.mathnet\.ru/dan(?:[0-9])+)\b",
-                r"\b(https://archive.org/details/(?:[0-9a-z_\.-])+)\b",
-                r"\b(https://web.archive.org/web/(?:[0-9])+/https://(?:[0-9a-zA-Z_\.-/])+)\b",
+                r"\b(https://archive\.org/details/(?:[0-9a-z_\.-])+)\b",
+                r"\b(https://web\.archive\.org/web/(?:[0-9])+/https://(?:[0-9a-zA-Z_\.-/])+)\b",
+                r"\b(https://www\.ap\.uj\.edu\.pl/diplomas/attachments/file/download/(?:[0-9])+)\b",
             ):
                 urls = re.findall(pattern, text)
                 if urls:
@@ -80,7 +81,9 @@ def check_urls(urls_from_json):
     for url in unique_urls_found:
         assert url in unique_urls_read, f"{url} not found in the json file"
     for url in unique_urls_read:
-        assert url in unique_urls_found, f"{url} not referenced in the code"
+        assert (
+            url in unique_urls_found
+        ), f"{url} not referenced in the code (or not recognized url pattern)"
 
     url_usages_found = {
         url: sorted({path for path, d in found_urls if d == url})
@@ -120,7 +123,7 @@ def create_references_html(urls_from_json, code_path):
 
 
 def run_pdoc(code_path, out_path):
-    """generates docs in HTML formay by executing pdoc"""
+    """generates docs in HTML format by executing pdoc"""
     subprocess.run(
         [
             sys.executable,

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/docs/markdown/pysdm_landing.md

@@ -71,7 +71,7 @@ In these cases, non-SI units should be always indicated in variable names,
   - `pressure_hPa` to use hectopascals.
 
 However, such conversions are best to be done
-  on-the-fly avoiding storage of non-SI values in variables (e.g., `plot(pressure / si.hPa)`.
+  on-the-fly avoiding storage of non-SI values in variables (e.g., `plot(pressure / si.hPa)`).
 
 ### Dimensional Analysis
 By default, the `si` object contains bare multipliers corresponding to SI prefixes.

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/examples/PySDM_examples/Jensen_and_Nugent_2017/settings.py

@@ -21,7 +21,8 @@ class Settings:
         self.t_end_of_ascent = 1500 * si.s if cloud_type == "Sc" else None
         self.dt = dt or 1 * si.s  # TODO #1266: not found in the paper yet
 
-        self.kappa = 1.28  # Table 1 from Petters & Kreidenweis 2007
+        # Table 1 from [Petters & Kreidenweis 2007](https://doi.org/10.5194/acp-7-1961-2007)
+        self.kappa = 1.28
 
         self.formulae = Formulae(
             saturation_vapour_pressure="FlatauWalkoCotton",  # TODO #1266: Bolton

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/pysdm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pysdm
-Version: 3.0.0rc19
+Version: 3.0.0rc20
 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

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/pysdm.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ setup.py
 .github/workflows/readme_snippets.yml
 .github/workflows/stale.yml
 .github/workflows/tests.yml
+.github/workflows/urlcheck.yml
 PySDM/__init__.py
 PySDM/builder.py
 PySDM/formulae.py

{pysdm-3.0.0rc19 → pysdm-3.0.0rc20}/tests/unit_tests/test_particulator.py

@@ -140,7 +140,7 @@ class TestParticulator:
         assert particulator.attributes.sane
 
     @staticmethod
-    def test_seeding_fails_if_no_null_super_droplets_availale(backend_class):
+    def test_seeding_fails_if_no_null_super_droplets_available(backend_class):
         # arrange
         a_number = 44