blobmodel 1.2.2__tar.gz → 2.1.0__tar.gz

{blobmodel-1.2.2 → blobmodel-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blobmodel
-Version: 1.2.2
+Version: 2.1.0
 Summary: Two dimensional model of propagating blobs
 Author-email: gregordecristoforo <gregor.decristoforo@gmail.com>
 License: MIT License
@@ -25,7 +25,7 @@ License: MIT License
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
-Requires-Python: >=3
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
@@ -34,11 +34,14 @@ Requires-Dist: tqdm
 Requires-Dist: nptyping
 Requires-Dist: matplotlib
 Requires-Dist: netcdf4
-Requires-Dist: pytest-cov
-Requires-Dist: black
-Requires-Dist: mypy
-Requires-Dist: sphinx
-Requires-Dist: sphinx-rtd-theme
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
 Dynamic: license-file
 
 # blobmodel  <img align="left" src="https://github.com/uit-cosmo/blobmodel/blob/main/readme_files/logo.png" width="120px" >
@@ -97,9 +100,11 @@ python -m pip install -e .
 Create a grid on which the blobs are discretized using the `Model` class. The `make_realization()` method computes the output as an xarray dataset which can also be written out as a `netcdf` file if the argument `file_name` is specified. A simple example is shown below:
 
 ```Python
-from blobmodel import Model, show_model
+from blobmodel import Geometry, Model, show_model
 
-bm = Model(Nx=200, Ny=100, Lx=10, Ly=10, dt=0.1, T=20, num_blobs=100)
+bm = Model(
+    geometry=Geometry(Nx=200, Ny=100, Lx=10, Ly=10, dt=0.1, T=20), num_blobs=100
+)
 
 ds = bm.make_realization(file_name="example.nc")
 ```
@@ -110,26 +115,24 @@ show_model(ds)
 You can specify the blob parameters with a BlobFactory class. The DefaultBlobFactory class has some of the most common distribution functions implemented. An example would look like this:
 
 ```Python
-from blobmodel import DefaultBlobFactory, DistributionEnum, Model
+from blobmodel import DefaultBlobFactory, DistributionEnum, Geometry, Model
 
 # use DefaultBlobFactory to define distribution functions of random variables
-my_blob_factory = DefaultBlobFactory(A_dist=DistributionEnum.normal, A_parameter=5)
+my_blob_factory = DefaultBlobFactory(t_drain=100).set_sampler(
+    "amplitude", DistributionEnum.normal, free_parameter=5
+)
 
 # pass on my_blob_factory when creating the Model
 bm = Model(
-        Nx=100,
-        Ny=100,
-        Lx=10,
-        Ly=10,
-        dt=0.1,
-        T=20,
+        geometry=Geometry(Nx=100, Ny=100, Lx=10, Ly=10, dt=0.1, T=20),
         blob_factory=my_blob_factory,
-        t_drain=100,
         num_blobs=100,
     )
 ```
 Alternatively, you can specify all blob parameters exactly as you want by writing your own class which inherits from BlobFactory. See `examples/custom_blobfactory.py` as an example or take a look at the [blobmodel documentation](https://blobmodel.readthedocs.io/en/latest/?badge=latest).
 
+Blobs can decay exponentially from their initial time with a drainage time `t_drain`, and/or be given a finite pulse lifetime `t_lifetime`, a Gaussian envelope symmetric about the blob's `t_init` so that the blob grows, peaks and decays. Both are arguments of `DefaultBlobFactory` and are applied to every sampled blob; see the [drainage time](https://blobmodel.readthedocs.io/en/latest/drainage_time.html) and [pulse lifetime](https://blobmodel.readthedocs.io/en/latest/pulse_lifetime.html) sections of the documentation.
+
 ## Contributing
 
 Feel free to raise issues about anything. Contributions through pull requests are also very welcome. Please take a look at our [Contributor guide](https://blobmodel.readthedocs.io/en/latest/contributor_guide.html) for further details.

{blobmodel-1.2.2 → blobmodel-2.1.0}/README.md

@@ -54,9 +54,11 @@ python -m pip install -e .
 Create a grid on which the blobs are discretized using the `Model` class. The `make_realization()` method computes the output as an xarray dataset which can also be written out as a `netcdf` file if the argument `file_name` is specified. A simple example is shown below:
 
 ```Python
-from blobmodel import Model, show_model
+from blobmodel import Geometry, Model, show_model
 
-bm = Model(Nx=200, Ny=100, Lx=10, Ly=10, dt=0.1, T=20, num_blobs=100)
+bm = Model(
+    geometry=Geometry(Nx=200, Ny=100, Lx=10, Ly=10, dt=0.1, T=20), num_blobs=100
+)
 
 ds = bm.make_realization(file_name="example.nc")
 ```
@@ -67,26 +69,24 @@ show_model(ds)
 You can specify the blob parameters with a BlobFactory class. The DefaultBlobFactory class has some of the most common distribution functions implemented. An example would look like this:
 
 ```Python
-from blobmodel import DefaultBlobFactory, DistributionEnum, Model
+from blobmodel import DefaultBlobFactory, DistributionEnum, Geometry, Model
 
 # use DefaultBlobFactory to define distribution functions of random variables
-my_blob_factory = DefaultBlobFactory(A_dist=DistributionEnum.normal, A_parameter=5)
+my_blob_factory = DefaultBlobFactory(t_drain=100).set_sampler(
+    "amplitude", DistributionEnum.normal, free_parameter=5
+)
 
 # pass on my_blob_factory when creating the Model
 bm = Model(
-        Nx=100,
-        Ny=100,
-        Lx=10,
-        Ly=10,
-        dt=0.1,
-        T=20,
+        geometry=Geometry(Nx=100, Ny=100, Lx=10, Ly=10, dt=0.1, T=20),
         blob_factory=my_blob_factory,
-        t_drain=100,
         num_blobs=100,
     )
 ```
 Alternatively, you can specify all blob parameters exactly as you want by writing your own class which inherits from BlobFactory. See `examples/custom_blobfactory.py` as an example or take a look at the [blobmodel documentation](https://blobmodel.readthedocs.io/en/latest/?badge=latest).
 
+Blobs can decay exponentially from their initial time with a drainage time `t_drain`, and/or be given a finite pulse lifetime `t_lifetime`, a Gaussian envelope symmetric about the blob's `t_init` so that the blob grows, peaks and decays. Both are arguments of `DefaultBlobFactory` and are applied to every sampled blob; see the [drainage time](https://blobmodel.readthedocs.io/en/latest/drainage_time.html) and [pulse lifetime](https://blobmodel.readthedocs.io/en/latest/pulse_lifetime.html) sections of the documentation.
+
 ## Contributing
 
 Feel free to raise issues about anything. Contributions through pull requests are also very welcome. Please take a look at our [Contributor guide](https://blobmodel.readthedocs.io/en/latest/contributor_guide.html) for further details.

{blobmodel-1.2.2 → blobmodel-2.1.0}/blobmodel/__init__.py

@@ -1,7 +1,13 @@
-from .model import Model
+from .model import Model, to_imaging_dataset
 from .blobs import Blob
 from .plotting import show_model
-from .stochasticality import BlobFactory, DefaultBlobFactory
+from .stochasticality import (
+    BlobFactory,
+    BlobListFactory,
+    CallableBlobFactory,
+    DefaultBlobFactory,
+    ParameterSampler,
+)
 from .geometry import Geometry
 from .blob_shape import AbstractBlobShape, BlobShapeImpl, BlobShapeEnum
 from .distributions import DistributionEnum

{blobmodel-1.2.2 → blobmodel-2.1.0}/blobmodel/blob_shape.py

@@ -78,6 +78,19 @@ def _get_lorentz_shape(theta: np.ndarray, **kwargs) -> np.ndarray:
 def _get_double_exponential_shape(theta: np.ndarray, **kwargs) -> np.ndarray:
     """Compute the double-exponential pulse shape.
 
+    The shape is ``exp(-theta / lam)`` for ``theta >= 0`` and
+    ``exp(theta / (1 - lam))`` for ``theta < 0``, i.e. ``lam`` is the
+    e-folding fraction of the leading (``theta >= 0``) side of the pulse.
+    For a blob propagating with ``v_x > 0`` observed at a fixed position,
+    ``lam`` is therefore the temporal *rise* fraction of the measured pulse,
+    matching the asymmetry-parameter convention of the FPP literature.
+
+    .. versionchanged:: 2.0.0
+        The convention was flipped: ``lam`` previously weighted the trailing
+        (``theta < 0``) side, so ``lam`` was the temporal *fall* fraction.
+        Code written against older versions that passed ``1 - lam`` to
+        compensate should now pass ``lam`` directly.
+
     Parameters
     ----------
     theta : np.ndarray
@@ -85,18 +98,29 @@ def _get_double_exponential_shape(theta: np.ndarray, **kwargs) -> np.ndarray:
     kwargs
         Additional keyword arguments.
         lam : float
-            Asymmetry parameter controlling the shape.
+            Asymmetry parameter controlling the shape, in the interval [0, 1].
+            The limits are the one-sided shapes: lam = 0 is nonzero only for
+            theta < 0 (a pure temporal decay for v_x > 0), lam = 1 is nonzero
+            only for theta >= 0 (a pure temporal rise for v_x > 0).
 
     Returns
     -------
     np.ndarray
         Array representing the double-exponential pulse shape.
+
+    Raises
+    ------
+    ValueError
+        If lam lies outside the interval [0, 1].
     """
     lam = kwargs["lam"]
-    assert (lam > 0.0) & (lam < 1.0)
+    if not 0.0 <= lam <= 1.0:
+        raise ValueError(f"lam must be in the interval [0, 1], got lam = {lam}.")
     kern = np.zeros(shape=np.shape(theta))
-    kern[theta < 0] = np.exp(theta[theta < 0] / lam)
-    kern[theta >= 0] = np.exp(-theta[theta >= 0] / (1 - lam))
+    if lam < 1.0:
+        kern[theta < 0] = np.exp(theta[theta < 0] / (1 - lam))
+    if lam > 0.0:
+        kern[theta >= 0] = np.exp(-theta[theta >= 0] / lam)
     return kern
 
 
@@ -171,43 +195,73 @@ def _get_dipole_shape(theta: np.ndarray, **kwargs) -> np.ndarray:
 
 
 class BlobShapeImpl(AbstractBlobShape):
-    """Implementation of the AbstractPulseShape class."""
+    """Implementation of the AbstractBlobShape class."""
 
     def __init__(
         self,
-        pulse_shape_p=BlobShapeEnum.gaussian,
-        pulse_shape_s=BlobShapeEnum.gaussian,
+        pulse_shape_p: BlobShapeEnum = BlobShapeEnum.gaussian,
+        pulse_shape_s: BlobShapeEnum = BlobShapeEnum.gaussian,
     ):
         """Initialize the BlobShapeImpl object.
 
-        Attributes
+        Parameters
         ----------
-        pulse_shape_p : str, optional
-            Type of pulse shape in the principal direction, by default "gauss".
-        pulse_shape_s : str, optional
-            Type of pulse shape in the secondary direction, by default "gauss".
+        pulse_shape_p : BlobShapeEnum, optional
+            Type of pulse shape in the principal direction,
+            by default BlobShapeEnum.gaussian.
+        pulse_shape_s : BlobShapeEnum, optional
+            Type of pulse shape in the secondary direction,
+            by default BlobShapeEnum.gaussian.
+
+        Raises
+        ------
+        NotImplementedError
+            If a pulse shape is not a member of BlobShapeEnum with an
+            implemented shape function.
         """
         if (
-            pulse_shape_p not in BlobShapeImpl.__GENERATORS.keys()
-            or pulse_shape_s not in BlobShapeImpl.__GENERATORS.keys()
+            pulse_shape_p not in BlobShapeImpl.__GENERATORS
+            or pulse_shape_s not in BlobShapeImpl.__GENERATORS
         ):
             raise NotImplementedError(
                 f"{self.__class__.__name__}.blob_shape not implemented"
             )
-        self.get_blob_shape_p = BlobShapeImpl.__GENERATORS.get(pulse_shape_p)
-        self.get_blob_shape_s = BlobShapeImpl.__GENERATORS.get(pulse_shape_s)
+        self._shape_p = BlobShapeImpl.__GENERATORS[pulse_shape_p]
+        self._shape_s = BlobShapeImpl.__GENERATORS[pulse_shape_s]
 
     def get_blob_shape_p(self, theta: np.ndarray, **kwargs) -> np.ndarray:
+        """Compute the pulse shape in the principal direction.
+
+        Parameters
+        ----------
+        theta : np.ndarray
+            Array of theta values.
+        kwargs
+            Additional keyword arguments passed to the shape function.
+
+        Returns
+        -------
+        np.ndarray
+            Array representing the pulse shape in the principal direction.
         """
-        Compute the pulse shape in the principal direction.
-        """
-        raise NotImplementedError
+        return self._shape_p(theta, **kwargs)
 
     def get_blob_shape_s(self, theta: np.ndarray, **kwargs) -> np.ndarray:
+        """Compute the pulse shape in the secondary direction.
+
+        Parameters
+        ----------
+        theta : np.ndarray
+            Array of theta values.
+        kwargs
+            Additional keyword arguments passed to the shape function.
+
+        Returns
+        -------
+        np.ndarray
+            Array representing the pulse shape in the secondary direction.
         """
-        Compute the pulse shape in the secondary direction.
-        """
-        raise NotImplementedError
+        return self._shape_s(theta, **kwargs)
 
     __GENERATORS = {
         BlobShapeEnum.exp: _get_exponential_shape,