PySDM 2.71__tar.gz → 2.73__tar.gz

{PySDM-2.71 → PySDM-2.73}/.github/workflows/tests+artifacts+pypi.yml

@@ -69,11 +69,10 @@ jobs:
         with:
           python-version: 3.9
       - run: |
-          pip install pdoc3
+          pip install pdoc
           pip install -e .
           pip install -e examples
-          python -We -m pdoc --html PySDM examples/PySDM_examples
-          python -We .github/workflows/pdoc_index_workaround.py
+          PDOC_ALLOW_EXEC=1 python -We -m pdoc -o html PySDM examples/PySDM_examples -t pdoc_templates
       - if: ${{ github.ref == 'refs/heads/main' && matrix.platform == 'ubuntu-latest' }}
         uses: JamesIves/github-pages-deploy-action@4.1.1
         with:

{PySDM-2.71 → PySDM-2.73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PySDM
-Version: 2.71
+Version: 2.73
 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
@@ -32,7 +32,7 @@ Description: # PySDM
         [![Appveyor Build status](http://ci.appveyor.com/api/projects/status/github/open-atmos/PySDM?branch=main&svg=true)](https://ci.appveyor.com/project/slayoo/pysdm/branch/main)
         [![Coverage Status](https://codecov.io/gh/open-atmos/PySDM/branch/main/graph/badge.svg)](https://app.codecov.io/gh/open-atmos/PySDM)    
         [![PyPI version](https://badge.fury.io/py/PySDM.svg)](https://pypi.org/project/PySDM)
-        [![API docs](https://img.shields.io/badge/API_docs-pdoc3-blue.svg)](https://open-atmos.github.io/PySDM/)
+        [![API docs](https://shields.mitmproxy.org/badge/docs-pdoc.dev-brightgreen.svg)](https://open-atmos.github.io/PySDM/)
         
         PySDM is a package for simulating the dynamics of population of particles. 
         It is intended to serve as a building block for simulation systems modelling
@@ -62,9 +62,9 @@ Description: # PySDM
         PySDM has two alternative parallel number-crunching backends 
           available: multi-threaded CPU backend based on [Numba](http://numba.pydata.org/) 
           and GPU-resident backend built on top of [ThrustRTC](https://pypi.org/project/ThrustRTC/).
-        The [`Numba`](https://open-atmos.github.io/PySDM/PySDM/backends/numba/numba.html) backend (aliased ``CPU``) features multi-threaded parallelism for 
+        The [`Numba`](https://open-atmos.github.io/PySDM/PySDM/backends/numba.html) backend (aliased ``CPU``) features multi-threaded parallelism for 
           multi-core CPUs, it uses the just-in-time compilation technique based on the LLVM infrastructure.
-        The [`ThrustRTC`](https://open-atmos.github.io/PySDM/PySDM/backends/thrustRTC/thrustRTC.html) backend (aliased ``GPU``) offers GPU-resident operation of PySDM
+        The [`ThrustRTC`](https://open-atmos.github.io/PySDM/PySDM/backends/thrust_rtc.html) backend (aliased ``GPU``) offers GPU-resident operation of PySDM
           leveraging the [SIMT](https://en.wikipedia.org/wiki/Single_instruction,_multiple_threads) 
           parallelisation model. 
         Using the ``GPU`` backend requires nVidia hardware and [CUDA driver](https://developer.nvidia.com/cuda-downloads).
@@ -76,7 +76,7 @@ Description: # PySDM
         PySDM includes an extension of the SDM scheme to represent collisional breakup described in [de Jong, Mackay et al. 2023](10.5194/gmd-16-4193-2023).   
         For a list of talks and other materials on PySDM as well as a list of published papers featuring PySDM simulations, see the [project wiki](https://github.com/open-atmos/PySDM/wiki).
         
-        A [pdoc-generated](https://pdoc3.github.io/pdoc) documentation of PySDM public API is maintained at: [https://open-atmos.github.io/PySDM](https://open-atmos.github.io/PySDM) 
+        A [pdoc-generated](https://pdoc.dev/) documentation of PySDM public API is maintained at: [https://open-atmos.github.io/PySDM](https://open-atmos.github.io/PySDM) 
         
         ## Example Jupyter notebooks (reproducing results from literature):
         
@@ -186,8 +186,8 @@ Description: # PySDM
           listings provide sample code roughly reproducing the 
           Figure 2 from [Shima et al. 2009 paper](http://doi.org/10.1002/qj.441)
           using PySDM from Python, Julia and Matlab.
-        It is a [`Coalescence`](https://open-atmos.github.io/PySDM/PySDM/dynamics/coalescence.html)-only set-up in which the initial particle size 
-          spectrum is [`Exponential`](https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra.html#PySDM.initialisation.spectra.Exponential) and is deterministically sampled to match
+        It is a [`Coalescence`](https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/sollision.html#Coalescence)-only set-up in which the initial particle size 
+          spectrum is [`Exponential`](https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra/exponential.html#Exponential) and is deterministically sampled to match
           the condition of each super-droplet having equal initial multiplicity:
         <details>
         <summary>Julia (click to expand)</summary>
@@ -241,9 +241,9 @@ Description: # PySDM
         ```
         </details>
         
-        The key element of the PySDM interface is the [``Particulator``](https://open-atmos.github.io/PySDM/PySDM/particulator.html) 
+        The key element of the PySDM interface is the [``Particulator``](https://open-atmos.github.io/PySDM/PySDM/particulator.html#Particulator) 
           class instances of which are used to manage the system state and control the simulation.
-        Instantiation of the [``Particulator``](https://open-atmos.github.io/PySDM/PySDM/particulator.html) class is handled by the [``Builder``](https://open-atmos.github.io/PySDM/PySDM/builder.html)
+        Instantiation of the [``Particulator``](https://open-atmos.github.io/PySDM/PySDM/particulator.html#Particulator) class is handled by the [``Builder``](https://open-atmos.github.io/PySDM/PySDM/builder.html#Builder)
           as exemplified below:
         <details>
         <summary>Julia (click to expand)</summary>
@@ -313,18 +313,18 @@ Description: # PySDM
         The ``backend`` argument may be set to ``CPU`` or ``GPU``
           what translates to choosing the multi-threaded backend or the 
           GPU-resident computation mode, respectively.
-        The employed [`Box`](https://open-atmos.github.io/PySDM/PySDM/environments/box.html) environment corresponds to a zero-dimensional framework
+        The employed [`Box`](https://open-atmos.github.io/PySDM/PySDM/environments/box.html#Box) environment corresponds to a zero-dimensional framework
           (particle positions are not considered).
         The vectors of particle multiplicities ``n`` and particle volumes ``v`` are
           used to initialise super-droplet attributes.
-        The [`Coalescence`](https://open-atmos.github.io/PySDM/PySDM/dynamics/coalescence.html)
+        The [`Coalescence`](https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision.html#Coalescence)
           Monte-Carlo algorithm (Super Droplet Method) is registered as the only
           dynamic in the system.
-        Finally, the [`build()`](https://open-atmos.github.io/PySDM/PySDM/builder.html#PySDM.builder.Builder.build) method is used to obtain an instance
-          of [`Particulator`](https://open-atmos.github.io/PySDM/PySDM/particulator.html#PySDM.particulator.Particulator) which can then be used to control time-stepping and
+        Finally, the [`build()`](https://open-atmos.github.io/PySDM/PySDM/builder.html#Builder.build) method is used to obtain an instance
+          of [`Particulator`](https://open-atmos.github.io/PySDM/PySDM/particulator.html#Particulator) which can then be used to control time-stepping and
           access simulation state.
         
-        The [`run(nt)`](https://open-atmos.github.io/PySDM/PySDM/particulator.html#PySDM.particuparticulatorr.Particulator.run) method advances the simulation by ``nt`` timesteps.
+        The [`run(nt)`](https://open-atmos.github.io/PySDM/PySDM/particulator.html#Particulator.run) method advances the simulation by ``nt`` timesteps.
         In the listing below, its usage is interleaved with plotting logic
           which displays a histogram of particle mass distribution 
           at selected timesteps:
@@ -441,16 +441,16 @@ Description: # PySDM
             SPECTRUM_INIT["ParticleVolumeVersusRadiusLogarithmSpectrum.__init__()"] -->|instantiates| SPECTRUM
             SPECTRUM[":ParticleVolumeVersusRadiusLogarithmSpectrum"] -->|added as element of| PRODUCTS
         
-            click COAL "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision.html"
+            click COAL "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision.html#Coalescence"
             click BUILDER_INSTANCE "https://open-atmos.github.io/PySDM/PySDM/builder.html"
             click BUILDER_INIT "https://open-atmos.github.io/PySDM/PySDM/builder.html"
             click BUILDER_ADD_DYN "https://open-atmos.github.io/PySDM/PySDM/builder.html"
-            click ENV_INIT "https://open-atmos.github.io/PySDM/PySDM/environments/index.html"
-            click ENV "https://open-atmos.github.io/PySDM/PySDM/environments/index.html"
-            click KERNEL_INIT "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision_kernels/index.html"
-            click KERNEL "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision_kernels/index.html"
-            click EXP_INIT "https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra/index.html"
-            click IS "https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra/index.html"
+            click ENV_INIT "https://open-atmos.github.io/PySDM/PySDM/environments.html"
+            click ENV "https://open-atmos.github.io/PySDM/PySDM/environments.html"
+            click KERNEL_INIT "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision_kernels.html"
+            click KERNEL "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision_kernels.html"
+            click EXP_INIT "https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra.html"
+            click IS "https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra.html"
             click CM_INIT "https://open-atmos.github.io/PySDM/PySDM/initialisation/sampling/spectral_sampling.html"
             click CM_INSTANCE "https://open-atmos.github.io/PySDM/PySDM/initialisation/sampling/spectral_sampling.html"
             click SAMPLE "https://open-atmos.github.io/PySDM/PySDM/initialisation/sampling/spectral_sampling.html"
@@ -466,7 +466,7 @@ Description: # PySDM
         
         In the following example, a condensation-only setup is used with the adiabatic 
         [`Parcel`](https://open-atmos.github.io/PySDM/PySDM/environments/parcel.html) environment.
-        An initial [`Lognormal`](https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra.html#PySDM.initialisation.spectra.Lognormal)
+        An initial [`Lognormal`](https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra/lognormal.html#Lognormal)
         spectrum of dry aerosol particles is first initialised to equilibrium wet size for the given
         initial humidity. 
         Subsequent particle growth due to [`Condensation`](https://open-atmos.github.io/PySDM/PySDM/dynamics/condensation.html) of water vapour (coupled with the release of latent heat)
@@ -476,7 +476,7 @@ Description: # PySDM
         and depict the evolution of 
         [`PeakSupersaturation`](https://open-atmos.github.io/PySDM/PySDM/products/condensation/peak_supersaturation.html), 
         [`EffectiveRadius`](https://open-atmos.github.io/PySDM/PySDM/products/size_spectral/effective_radius.html), 
-        [`ParticleConcentration`](https://open-atmos.github.io/PySDM/PySDM/products/size_spectral/particle_concentration.html#PySDM.products.particles_concentration.ParticleConcentration) 
+        [`ParticleConcentration`](https://open-atmos.github.io/PySDM/PySDM/products/size_spectral/particle_concentration.html#ParticleConcentration) 
         and the 
         [`WaterMixingRatio `](https://open-atmos.github.io/PySDM/PySDM/products/size_spectral/water_mixing_ratio.html).
         
@@ -521,7 +521,7 @@ Description: # PySDM
         
         r_dry, specific_concentration = spectral_sampling.Logarithmic(spectrum).sample(n_sd)
         v_dry = formulae.trivia.volume(radius=r_dry)
-        r_wet = equilibrate_wet_radii(r_dry=r_dry, environment=env, kappa_times_dry_volume=kappa * v_dry)
+        r_wet = equilibrate_wet_radii(r_dry=r_dry, environment=builder.particulator.environment, kappa_times_dry_volume=kappa * v_dry)
         
         attributes = Dict()
         attributes["multiplicity"] = discretise_multiplicities(specific_concentration * env.mass_of_dry_air)
@@ -606,7 +606,7 @@ Description: # PySDM
         specific_concentration = tmp{2};
         r_wet = equilibrate_wet_radii(pyargs(...
             'r_dry', r_dry, ...
-            'environment', env, ...
+            'environment', builder.particulator.environment, ...
             'kappa_times_dry_volume', kappa * v_dry...
         ));
         
@@ -702,7 +702,7 @@ Description: # PySDM
         
         r_dry, specific_concentration = spectral_sampling.Logarithmic(spectrum).sample(n_sd)
         v_dry = formulae.trivia.volume(radius=r_dry)
-        r_wet = equilibrate_wet_radii(r_dry=r_dry, environment=env, kappa_times_dry_volume=kappa * v_dry)
+        r_wet = equilibrate_wet_radii(r_dry=r_dry, environment=builder.particulator.environment, kappa_times_dry_volume=kappa * v_dry)
         
         attributes = {
           'multiplicity': discretise_multiplicities(specific_concentration * env.mass_of_dry_air),

{PySDM-2.71 → PySDM-2.73}/PySDM/builder.py

@@ -49,8 +49,7 @@ class Builder:
     def _set_environment(self, environment):
         if self.particulator.environment is not None:
             raise AssertionError("environment has already been set")
-        self.particulator.environment = environment
-        self.particulator.environment.register(self)
+        self.particulator.environment = environment.instantiate(builder=self)
 
     def add_dynamic(self, dynamic):
         assert self.particulator.environment is not None

{PySDM-2.71 → PySDM-2.73}/PySDM/environments/box.py

@@ -5,8 +5,10 @@ Bare zero-dimensional framework
 import numpy as np
 
 from PySDM.impl.mesh import Mesh
+from PySDM.environments.impl import register_environment
 
 
+@register_environment()
 class Box:
     def __init__(self, dt, dv):
         self.dt = dt

PySDM-2.73/PySDM/environments/impl/__init__.py

@@ -0,0 +1,3 @@
+""" common internals not intended to be imported from user code """
+
+from PySDM.environments.impl.register_environment import register_environment

PySDM-2.73/PySDM/environments/impl/register_environment.py

@@ -0,0 +1,24 @@
+""" decorator for environment classes
+ensuring that their instances can be re-used with multiple builders """
+
+from copy import deepcopy
+
+
+def _instantiate(self, *, builder):
+    copy = deepcopy(self)
+    copy.register(builder=builder)
+    return copy
+
+
+def register_environment():
+    def decorator(cls):
+        if hasattr(cls, "instantiate"):
+            if cls.instantiate is not _instantiate:
+                raise AttributeError(
+                    "decorated class has a different instantiate method"
+                )
+        else:
+            setattr(cls, "instantiate", _instantiate)
+        return cls
+
+    return decorator

{PySDM-2.71 → PySDM-2.73}/PySDM/environments/kinematic_1d.py

@@ -7,10 +7,12 @@ import numpy as np
 
 from PySDM.environments.impl.moist import Moist
 
-from ..impl import arakawa_c
-from ..initialisation.equilibrate_wet_radii import equilibrate_wet_radii
+from PySDM.impl import arakawa_c
+from PySDM.initialisation.equilibrate_wet_radii import equilibrate_wet_radii
+from PySDM.environments.impl import register_environment
 
 
+@register_environment()
 class Kinematic1D(Moist):
     def __init__(self, *, dt, mesh, thd_of_z, rhod_of_z, z0=0):
         super().__init__(dt, mesh, [])

{PySDM-2.71 → PySDM-2.73}/PySDM/environments/kinematic_2d.py

@@ -12,10 +12,11 @@ from PySDM.initialisation.equilibrate_wet_radii import (
     equilibrate_wet_radii,
 )
 from PySDM.initialisation.sampling.spectral_sampling import ConstantMultiplicity
-
-from ..impl import arakawa_c
+from PySDM.impl import arakawa_c
+from PySDM.environments.impl import register_environment
 
 
+@register_environment()
 class Kinematic2D(Moist):
     def __init__(self, *, dt, grid, size, rhod_of, mixed_phase=False):
         super().__init__(dt, Mesh(grid, size), [], mixed_phase=mixed_phase)

{PySDM-2.71 → PySDM-2.73}/PySDM/environments/parcel.py

@@ -12,8 +12,10 @@ from PySDM.initialisation.equilibrate_wet_radii import (
     default_rtol,
     equilibrate_wet_radii,
 )
+from PySDM.environments.impl import register_environment
 
 
+@register_environment()
 class Parcel(Moist):  # pylint: disable=too-many-instance-attributes
     def __init__(
         self,

{PySDM-2.71 → PySDM-2.73}/PySDM.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PySDM
-Version: 2.71
+Version: 2.73
 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
@@ -32,7 +32,7 @@ Description: # PySDM
         [![Appveyor Build status](http://ci.appveyor.com/api/projects/status/github/open-atmos/PySDM?branch=main&svg=true)](https://ci.appveyor.com/project/slayoo/pysdm/branch/main)
         [![Coverage Status](https://codecov.io/gh/open-atmos/PySDM/branch/main/graph/badge.svg)](https://app.codecov.io/gh/open-atmos/PySDM)    
         [![PyPI version](https://badge.fury.io/py/PySDM.svg)](https://pypi.org/project/PySDM)
-        [![API docs](https://img.shields.io/badge/API_docs-pdoc3-blue.svg)](https://open-atmos.github.io/PySDM/)
+        [![API docs](https://shields.mitmproxy.org/badge/docs-pdoc.dev-brightgreen.svg)](https://open-atmos.github.io/PySDM/)
         
         PySDM is a package for simulating the dynamics of population of particles. 
         It is intended to serve as a building block for simulation systems modelling
@@ -62,9 +62,9 @@ Description: # PySDM
         PySDM has two alternative parallel number-crunching backends 
           available: multi-threaded CPU backend based on [Numba](http://numba.pydata.org/) 
           and GPU-resident backend built on top of [ThrustRTC](https://pypi.org/project/ThrustRTC/).
-        The [`Numba`](https://open-atmos.github.io/PySDM/PySDM/backends/numba/numba.html) backend (aliased ``CPU``) features multi-threaded parallelism for 
+        The [`Numba`](https://open-atmos.github.io/PySDM/PySDM/backends/numba.html) backend (aliased ``CPU``) features multi-threaded parallelism for 
           multi-core CPUs, it uses the just-in-time compilation technique based on the LLVM infrastructure.
-        The [`ThrustRTC`](https://open-atmos.github.io/PySDM/PySDM/backends/thrustRTC/thrustRTC.html) backend (aliased ``GPU``) offers GPU-resident operation of PySDM
+        The [`ThrustRTC`](https://open-atmos.github.io/PySDM/PySDM/backends/thrust_rtc.html) backend (aliased ``GPU``) offers GPU-resident operation of PySDM
           leveraging the [SIMT](https://en.wikipedia.org/wiki/Single_instruction,_multiple_threads) 
           parallelisation model. 
         Using the ``GPU`` backend requires nVidia hardware and [CUDA driver](https://developer.nvidia.com/cuda-downloads).
@@ -76,7 +76,7 @@ Description: # PySDM
         PySDM includes an extension of the SDM scheme to represent collisional breakup described in [de Jong, Mackay et al. 2023](10.5194/gmd-16-4193-2023).   
         For a list of talks and other materials on PySDM as well as a list of published papers featuring PySDM simulations, see the [project wiki](https://github.com/open-atmos/PySDM/wiki).
         
-        A [pdoc-generated](https://pdoc3.github.io/pdoc) documentation of PySDM public API is maintained at: [https://open-atmos.github.io/PySDM](https://open-atmos.github.io/PySDM) 
+        A [pdoc-generated](https://pdoc.dev/) documentation of PySDM public API is maintained at: [https://open-atmos.github.io/PySDM](https://open-atmos.github.io/PySDM) 
         
         ## Example Jupyter notebooks (reproducing results from literature):
         
@@ -186,8 +186,8 @@ Description: # PySDM
           listings provide sample code roughly reproducing the 
           Figure 2 from [Shima et al. 2009 paper](http://doi.org/10.1002/qj.441)
           using PySDM from Python, Julia and Matlab.
-        It is a [`Coalescence`](https://open-atmos.github.io/PySDM/PySDM/dynamics/coalescence.html)-only set-up in which the initial particle size 
-          spectrum is [`Exponential`](https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra.html#PySDM.initialisation.spectra.Exponential) and is deterministically sampled to match
+        It is a [`Coalescence`](https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/sollision.html#Coalescence)-only set-up in which the initial particle size 
+          spectrum is [`Exponential`](https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra/exponential.html#Exponential) and is deterministically sampled to match
           the condition of each super-droplet having equal initial multiplicity:
         <details>
         <summary>Julia (click to expand)</summary>
@@ -241,9 +241,9 @@ Description: # PySDM
         ```
         </details>
         
-        The key element of the PySDM interface is the [``Particulator``](https://open-atmos.github.io/PySDM/PySDM/particulator.html) 
+        The key element of the PySDM interface is the [``Particulator``](https://open-atmos.github.io/PySDM/PySDM/particulator.html#Particulator) 
           class instances of which are used to manage the system state and control the simulation.
-        Instantiation of the [``Particulator``](https://open-atmos.github.io/PySDM/PySDM/particulator.html) class is handled by the [``Builder``](https://open-atmos.github.io/PySDM/PySDM/builder.html)
+        Instantiation of the [``Particulator``](https://open-atmos.github.io/PySDM/PySDM/particulator.html#Particulator) class is handled by the [``Builder``](https://open-atmos.github.io/PySDM/PySDM/builder.html#Builder)
           as exemplified below:
         <details>
         <summary>Julia (click to expand)</summary>
@@ -313,18 +313,18 @@ Description: # PySDM
         The ``backend`` argument may be set to ``CPU`` or ``GPU``
           what translates to choosing the multi-threaded backend or the 
           GPU-resident computation mode, respectively.
-        The employed [`Box`](https://open-atmos.github.io/PySDM/PySDM/environments/box.html) environment corresponds to a zero-dimensional framework
+        The employed [`Box`](https://open-atmos.github.io/PySDM/PySDM/environments/box.html#Box) environment corresponds to a zero-dimensional framework
           (particle positions are not considered).
         The vectors of particle multiplicities ``n`` and particle volumes ``v`` are
           used to initialise super-droplet attributes.
-        The [`Coalescence`](https://open-atmos.github.io/PySDM/PySDM/dynamics/coalescence.html)
+        The [`Coalescence`](https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision.html#Coalescence)
           Monte-Carlo algorithm (Super Droplet Method) is registered as the only
           dynamic in the system.
-        Finally, the [`build()`](https://open-atmos.github.io/PySDM/PySDM/builder.html#PySDM.builder.Builder.build) method is used to obtain an instance
-          of [`Particulator`](https://open-atmos.github.io/PySDM/PySDM/particulator.html#PySDM.particulator.Particulator) which can then be used to control time-stepping and
+        Finally, the [`build()`](https://open-atmos.github.io/PySDM/PySDM/builder.html#Builder.build) method is used to obtain an instance
+          of [`Particulator`](https://open-atmos.github.io/PySDM/PySDM/particulator.html#Particulator) which can then be used to control time-stepping and
           access simulation state.
         
-        The [`run(nt)`](https://open-atmos.github.io/PySDM/PySDM/particulator.html#PySDM.particuparticulatorr.Particulator.run) method advances the simulation by ``nt`` timesteps.
+        The [`run(nt)`](https://open-atmos.github.io/PySDM/PySDM/particulator.html#Particulator.run) method advances the simulation by ``nt`` timesteps.
         In the listing below, its usage is interleaved with plotting logic
           which displays a histogram of particle mass distribution 
           at selected timesteps:
@@ -441,16 +441,16 @@ Description: # PySDM
             SPECTRUM_INIT["ParticleVolumeVersusRadiusLogarithmSpectrum.__init__()"] -->|instantiates| SPECTRUM
             SPECTRUM[":ParticleVolumeVersusRadiusLogarithmSpectrum"] -->|added as element of| PRODUCTS
         
-            click COAL "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision.html"
+            click COAL "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision.html#Coalescence"
             click BUILDER_INSTANCE "https://open-atmos.github.io/PySDM/PySDM/builder.html"
             click BUILDER_INIT "https://open-atmos.github.io/PySDM/PySDM/builder.html"
             click BUILDER_ADD_DYN "https://open-atmos.github.io/PySDM/PySDM/builder.html"
-            click ENV_INIT "https://open-atmos.github.io/PySDM/PySDM/environments/index.html"
-            click ENV "https://open-atmos.github.io/PySDM/PySDM/environments/index.html"
-            click KERNEL_INIT "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision_kernels/index.html"
-            click KERNEL "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision_kernels/index.html"
-            click EXP_INIT "https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra/index.html"
-            click IS "https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra/index.html"
+            click ENV_INIT "https://open-atmos.github.io/PySDM/PySDM/environments.html"
+            click ENV "https://open-atmos.github.io/PySDM/PySDM/environments.html"
+            click KERNEL_INIT "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision_kernels.html"
+            click KERNEL "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision_kernels.html"
+            click EXP_INIT "https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra.html"
+            click IS "https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra.html"
             click CM_INIT "https://open-atmos.github.io/PySDM/PySDM/initialisation/sampling/spectral_sampling.html"
             click CM_INSTANCE "https://open-atmos.github.io/PySDM/PySDM/initialisation/sampling/spectral_sampling.html"
             click SAMPLE "https://open-atmos.github.io/PySDM/PySDM/initialisation/sampling/spectral_sampling.html"
@@ -466,7 +466,7 @@ Description: # PySDM
         
         In the following example, a condensation-only setup is used with the adiabatic 
         [`Parcel`](https://open-atmos.github.io/PySDM/PySDM/environments/parcel.html) environment.
-        An initial [`Lognormal`](https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra.html#PySDM.initialisation.spectra.Lognormal)
+        An initial [`Lognormal`](https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra/lognormal.html#Lognormal)
         spectrum of dry aerosol particles is first initialised to equilibrium wet size for the given
         initial humidity. 
         Subsequent particle growth due to [`Condensation`](https://open-atmos.github.io/PySDM/PySDM/dynamics/condensation.html) of water vapour (coupled with the release of latent heat)
@@ -476,7 +476,7 @@ Description: # PySDM
         and depict the evolution of 
         [`PeakSupersaturation`](https://open-atmos.github.io/PySDM/PySDM/products/condensation/peak_supersaturation.html), 
         [`EffectiveRadius`](https://open-atmos.github.io/PySDM/PySDM/products/size_spectral/effective_radius.html), 
-        [`ParticleConcentration`](https://open-atmos.github.io/PySDM/PySDM/products/size_spectral/particle_concentration.html#PySDM.products.particles_concentration.ParticleConcentration) 
+        [`ParticleConcentration`](https://open-atmos.github.io/PySDM/PySDM/products/size_spectral/particle_concentration.html#ParticleConcentration) 
         and the 
         [`WaterMixingRatio `](https://open-atmos.github.io/PySDM/PySDM/products/size_spectral/water_mixing_ratio.html).
         
@@ -521,7 +521,7 @@ Description: # PySDM
         
         r_dry, specific_concentration = spectral_sampling.Logarithmic(spectrum).sample(n_sd)
         v_dry = formulae.trivia.volume(radius=r_dry)
-        r_wet = equilibrate_wet_radii(r_dry=r_dry, environment=env, kappa_times_dry_volume=kappa * v_dry)
+        r_wet = equilibrate_wet_radii(r_dry=r_dry, environment=builder.particulator.environment, kappa_times_dry_volume=kappa * v_dry)
         
         attributes = Dict()
         attributes["multiplicity"] = discretise_multiplicities(specific_concentration * env.mass_of_dry_air)
@@ -606,7 +606,7 @@ Description: # PySDM
         specific_concentration = tmp{2};
         r_wet = equilibrate_wet_radii(pyargs(...
             'r_dry', r_dry, ...
-            'environment', env, ...
+            'environment', builder.particulator.environment, ...
             'kappa_times_dry_volume', kappa * v_dry...
         ));
         
@@ -702,7 +702,7 @@ Description: # PySDM
         
         r_dry, specific_concentration = spectral_sampling.Logarithmic(spectrum).sample(n_sd)
         v_dry = formulae.trivia.volume(radius=r_dry)
-        r_wet = equilibrate_wet_radii(r_dry=r_dry, environment=env, kappa_times_dry_volume=kappa * v_dry)
+        r_wet = equilibrate_wet_radii(r_dry=r_dry, environment=builder.particulator.environment, kappa_times_dry_volume=kappa * v_dry)
         
         attributes = {
           'multiplicity': discretise_multiplicities(specific_concentration * env.mass_of_dry_air),

{PySDM-2.71 → PySDM-2.73}/PySDM.egg-info/SOURCES.txt

@@ -15,7 +15,6 @@ setup.py
 .github/workflows/cancel.yml
 .github/workflows/joss.yml
 .github/workflows/joss_paper.yml
-.github/workflows/pdoc_index_workaround.py
 .github/workflows/readme_snippets.yml
 .github/workflows/stale.yml
 .github/workflows/tests+artifacts+pypi.yml
@@ -189,6 +188,7 @@ PySDM/environments/kinematic_2d.py
 PySDM/environments/parcel.py
 PySDM/environments/impl/__init__.py
 PySDM/environments/impl/moist.py
+PySDM/environments/impl/register_environment.py
 PySDM/exporters/__init__.py
 PySDM/exporters/netcdf_exporter.py
 PySDM/exporters/netcdf_exporter_1d.py
@@ -633,6 +633,7 @@ paper/paper.md
 paper/paperv1.md
 paper/readme.pdf
 paper/test.pdf
+pdoc_templates/index.html.jinja2
 tests/__init__.py
 tests/examples_tests/__init__.py
 tests/examples_tests/conftest.py
@@ -799,6 +800,8 @@ tests/unit_tests/dynamics/displacement/displacement_settings.py
 tests/unit_tests/dynamics/displacement/test_advection.py
 tests/unit_tests/dynamics/displacement/test_courant_product.py
 tests/unit_tests/dynamics/displacement/test_sedimentation.py
+tests/unit_tests/environments/__init__.py
+tests/unit_tests/environments/test_impl.py
 tests/unit_tests/impl/__init__.py
 tests/unit_tests/impl/test_camel_case.py
 tests/unit_tests/impl/test_mesh.py

{PySDM-2.71 → PySDM-2.73}/README.md

@@ -21,7 +21,7 @@
 [![Appveyor Build status](http://ci.appveyor.com/api/projects/status/github/open-atmos/PySDM?branch=main&svg=true)](https://ci.appveyor.com/project/slayoo/pysdm/branch/main)
 [![Coverage Status](https://codecov.io/gh/open-atmos/PySDM/branch/main/graph/badge.svg)](https://app.codecov.io/gh/open-atmos/PySDM)    
 [![PyPI version](https://badge.fury.io/py/PySDM.svg)](https://pypi.org/project/PySDM)
-[![API docs](https://img.shields.io/badge/API_docs-pdoc3-blue.svg)](https://open-atmos.github.io/PySDM/)
+[![API docs](https://shields.mitmproxy.org/badge/docs-pdoc.dev-brightgreen.svg)](https://open-atmos.github.io/PySDM/)
 
 PySDM is a package for simulating the dynamics of population of particles. 
 It is intended to serve as a building block for simulation systems modelling
@@ -51,9 +51,9 @@ Like the examples, these tutorials can be executed or viewed "in the cloud" maki
 PySDM has two alternative parallel number-crunching backends 
   available: multi-threaded CPU backend based on [Numba](http://numba.pydata.org/) 
   and GPU-resident backend built on top of [ThrustRTC](https://pypi.org/project/ThrustRTC/).
-The [`Numba`](https://open-atmos.github.io/PySDM/PySDM/backends/numba/numba.html) backend (aliased ``CPU``) features multi-threaded parallelism for 
+The [`Numba`](https://open-atmos.github.io/PySDM/PySDM/backends/numba.html) backend (aliased ``CPU``) features multi-threaded parallelism for 
   multi-core CPUs, it uses the just-in-time compilation technique based on the LLVM infrastructure.
-The [`ThrustRTC`](https://open-atmos.github.io/PySDM/PySDM/backends/thrustRTC/thrustRTC.html) backend (aliased ``GPU``) offers GPU-resident operation of PySDM
+The [`ThrustRTC`](https://open-atmos.github.io/PySDM/PySDM/backends/thrust_rtc.html) backend (aliased ``GPU``) offers GPU-resident operation of PySDM
   leveraging the [SIMT](https://en.wikipedia.org/wiki/Single_instruction,_multiple_threads) 
   parallelisation model. 
 Using the ``GPU`` backend requires nVidia hardware and [CUDA driver](https://developer.nvidia.com/cuda-downloads).
@@ -65,7 +65,7 @@ For an overview of PySDM features (and the preferred way to cite PySDM in papers
 PySDM includes an extension of the SDM scheme to represent collisional breakup described in [de Jong, Mackay et al. 2023](10.5194/gmd-16-4193-2023).   
 For a list of talks and other materials on PySDM as well as a list of published papers featuring PySDM simulations, see the [project wiki](https://github.com/open-atmos/PySDM/wiki).
 
-A [pdoc-generated](https://pdoc3.github.io/pdoc) documentation of PySDM public API is maintained at: [https://open-atmos.github.io/PySDM](https://open-atmos.github.io/PySDM) 
+A [pdoc-generated](https://pdoc.dev/) documentation of PySDM public API is maintained at: [https://open-atmos.github.io/PySDM](https://open-atmos.github.io/PySDM) 
 
 ## Example Jupyter notebooks (reproducing results from literature):
 
@@ -175,8 +175,8 @@ In order to depict the PySDM API with a practical example, the following
   listings provide sample code roughly reproducing the 
   Figure 2 from [Shima et al. 2009 paper](http://doi.org/10.1002/qj.441)
   using PySDM from Python, Julia and Matlab.
-It is a [`Coalescence`](https://open-atmos.github.io/PySDM/PySDM/dynamics/coalescence.html)-only set-up in which the initial particle size 
-  spectrum is [`Exponential`](https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra.html#PySDM.initialisation.spectra.Exponential) and is deterministically sampled to match
+It is a [`Coalescence`](https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/sollision.html#Coalescence)-only set-up in which the initial particle size 
+  spectrum is [`Exponential`](https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra/exponential.html#Exponential) and is deterministically sampled to match
   the condition of each super-droplet having equal initial multiplicity:
 <details>
 <summary>Julia (click to expand)</summary>
@@ -230,9 +230,9 @@ attributes['volume'], attributes['multiplicity'] = ConstantMultiplicity(initial_
 ```
 </details>
 
-The key element of the PySDM interface is the [``Particulator``](https://open-atmos.github.io/PySDM/PySDM/particulator.html) 
+The key element of the PySDM interface is the [``Particulator``](https://open-atmos.github.io/PySDM/PySDM/particulator.html#Particulator) 
   class instances of which are used to manage the system state and control the simulation.
-Instantiation of the [``Particulator``](https://open-atmos.github.io/PySDM/PySDM/particulator.html) class is handled by the [``Builder``](https://open-atmos.github.io/PySDM/PySDM/builder.html)
+Instantiation of the [``Particulator``](https://open-atmos.github.io/PySDM/PySDM/particulator.html#Particulator) class is handled by the [``Builder``](https://open-atmos.github.io/PySDM/PySDM/builder.html#Builder)
   as exemplified below:
 <details>
 <summary>Julia (click to expand)</summary>
@@ -302,18 +302,18 @@ particulator = builder.build(attributes, products)
 The ``backend`` argument may be set to ``CPU`` or ``GPU``
   what translates to choosing the multi-threaded backend or the 
   GPU-resident computation mode, respectively.
-The employed [`Box`](https://open-atmos.github.io/PySDM/PySDM/environments/box.html) environment corresponds to a zero-dimensional framework
+The employed [`Box`](https://open-atmos.github.io/PySDM/PySDM/environments/box.html#Box) environment corresponds to a zero-dimensional framework
   (particle positions are not considered).
 The vectors of particle multiplicities ``n`` and particle volumes ``v`` are
   used to initialise super-droplet attributes.
-The [`Coalescence`](https://open-atmos.github.io/PySDM/PySDM/dynamics/coalescence.html)
+The [`Coalescence`](https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision.html#Coalescence)
   Monte-Carlo algorithm (Super Droplet Method) is registered as the only
   dynamic in the system.
-Finally, the [`build()`](https://open-atmos.github.io/PySDM/PySDM/builder.html#PySDM.builder.Builder.build) method is used to obtain an instance
-  of [`Particulator`](https://open-atmos.github.io/PySDM/PySDM/particulator.html#PySDM.particulator.Particulator) which can then be used to control time-stepping and
+Finally, the [`build()`](https://open-atmos.github.io/PySDM/PySDM/builder.html#Builder.build) method is used to obtain an instance
+  of [`Particulator`](https://open-atmos.github.io/PySDM/PySDM/particulator.html#Particulator) which can then be used to control time-stepping and
   access simulation state.
 
-The [`run(nt)`](https://open-atmos.github.io/PySDM/PySDM/particulator.html#PySDM.particuparticulatorr.Particulator.run) method advances the simulation by ``nt`` timesteps.
+The [`run(nt)`](https://open-atmos.github.io/PySDM/PySDM/particulator.html#Particulator.run) method advances the simulation by ``nt`` timesteps.
 In the listing below, its usage is interleaved with plotting logic
   which displays a histogram of particle mass distribution 
   at selected timesteps:
@@ -430,16 +430,16 @@ The component submodules used to create this simulation are visualized below:
     SPECTRUM_INIT["ParticleVolumeVersusRadiusLogarithmSpectrum.__init__()"] -->|instantiates| SPECTRUM
     SPECTRUM[":ParticleVolumeVersusRadiusLogarithmSpectrum"] -->|added as element of| PRODUCTS
 
-    click COAL "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision.html"
+    click COAL "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision.html#Coalescence"
     click BUILDER_INSTANCE "https://open-atmos.github.io/PySDM/PySDM/builder.html"
     click BUILDER_INIT "https://open-atmos.github.io/PySDM/PySDM/builder.html"
     click BUILDER_ADD_DYN "https://open-atmos.github.io/PySDM/PySDM/builder.html"
-    click ENV_INIT "https://open-atmos.github.io/PySDM/PySDM/environments/index.html"
-    click ENV "https://open-atmos.github.io/PySDM/PySDM/environments/index.html"
-    click KERNEL_INIT "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision_kernels/index.html"
-    click KERNEL "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision_kernels/index.html"
-    click EXP_INIT "https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra/index.html"
-    click IS "https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra/index.html"
+    click ENV_INIT "https://open-atmos.github.io/PySDM/PySDM/environments.html"
+    click ENV "https://open-atmos.github.io/PySDM/PySDM/environments.html"
+    click KERNEL_INIT "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision_kernels.html"
+    click KERNEL "https://open-atmos.github.io/PySDM/PySDM/dynamics/collisions/collision_kernels.html"
+    click EXP_INIT "https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra.html"
+    click IS "https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra.html"
     click CM_INIT "https://open-atmos.github.io/PySDM/PySDM/initialisation/sampling/spectral_sampling.html"
     click CM_INSTANCE "https://open-atmos.github.io/PySDM/PySDM/initialisation/sampling/spectral_sampling.html"
     click SAMPLE "https://open-atmos.github.io/PySDM/PySDM/initialisation/sampling/spectral_sampling.html"
@@ -455,7 +455,7 @@ The component submodules used to create this simulation are visualized below:
 
 In the following example, a condensation-only setup is used with the adiabatic 
 [`Parcel`](https://open-atmos.github.io/PySDM/PySDM/environments/parcel.html) environment.
-An initial [`Lognormal`](https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra.html#PySDM.initialisation.spectra.Lognormal)
+An initial [`Lognormal`](https://open-atmos.github.io/PySDM/PySDM/initialisation/spectra/lognormal.html#Lognormal)
 spectrum of dry aerosol particles is first initialised to equilibrium wet size for the given
 initial humidity. 
 Subsequent particle growth due to [`Condensation`](https://open-atmos.github.io/PySDM/PySDM/dynamics/condensation.html) of water vapour (coupled with the release of latent heat)
@@ -465,7 +465,7 @@ Results of the simulation are plotted against vertical
 and depict the evolution of 
 [`PeakSupersaturation`](https://open-atmos.github.io/PySDM/PySDM/products/condensation/peak_supersaturation.html), 
 [`EffectiveRadius`](https://open-atmos.github.io/PySDM/PySDM/products/size_spectral/effective_radius.html), 
-[`ParticleConcentration`](https://open-atmos.github.io/PySDM/PySDM/products/size_spectral/particle_concentration.html#PySDM.products.particles_concentration.ParticleConcentration) 
+[`ParticleConcentration`](https://open-atmos.github.io/PySDM/PySDM/products/size_spectral/particle_concentration.html#ParticleConcentration) 
 and the 
 [`WaterMixingRatio `](https://open-atmos.github.io/PySDM/PySDM/products/size_spectral/water_mixing_ratio.html).
 
@@ -510,7 +510,7 @@ builder.add_dynamic(Condensation())
 
 r_dry, specific_concentration = spectral_sampling.Logarithmic(spectrum).sample(n_sd)
 v_dry = formulae.trivia.volume(radius=r_dry)
-r_wet = equilibrate_wet_radii(r_dry=r_dry, environment=env, kappa_times_dry_volume=kappa * v_dry)
+r_wet = equilibrate_wet_radii(r_dry=r_dry, environment=builder.particulator.environment, kappa_times_dry_volume=kappa * v_dry)
 
 attributes = Dict()
 attributes["multiplicity"] = discretise_multiplicities(specific_concentration * env.mass_of_dry_air)
@@ -595,7 +595,7 @@ v_dry = formulae.trivia.volume(pyargs('radius', r_dry));
 specific_concentration = tmp{2};
 r_wet = equilibrate_wet_radii(pyargs(...
     'r_dry', r_dry, ...
-    'environment', env, ...
+    'environment', builder.particulator.environment, ...
     'kappa_times_dry_volume', kappa * v_dry...
 ));
 
@@ -691,7 +691,7 @@ builder.add_dynamic(Condensation())
 
 r_dry, specific_concentration = spectral_sampling.Logarithmic(spectrum).sample(n_sd)
 v_dry = formulae.trivia.volume(radius=r_dry)
-r_wet = equilibrate_wet_radii(r_dry=r_dry, environment=env, kappa_times_dry_volume=kappa * v_dry)
+r_wet = equilibrate_wet_radii(r_dry=r_dry, environment=builder.particulator.environment, kappa_times_dry_volume=kappa * v_dry)
 
 attributes = {
   'multiplicity': discretise_multiplicities(specific_concentration * env.mass_of_dry_air),