Merge pull request #117 from uit-cosmo/docstrings

Add docstrings

Author: Sosnowsky

blobmodel/blob_shape.py

@@ -6,6 +6,10 @@
 
 
 class BlobShapeEnum(Enum):
+    """
+    Enum class representing blob shapes.
+    """
+
     exp = 1
     lorentz = 2
     double_exp = 3

blobmodel/blobs.py

@@ -9,7 +9,25 @@
 
 
 class Blob:
-    """Define a single blob."""
+    """
+    Class representing a single blob. It stores all blob parameters and discretizes the blob on a grid through
+    the function `discretize_blob`. The contribution of a single blob to a grid defined by `x`, `y` and `t` is given by:
+
+    .. math::
+        a e^{-(t-t_k)/\tau_\shortparallel}\varphi\left( \frac{x-v(t-t_k)}{\ell_x}, \frac{(y-y_k)-w(t-t_k)}{\ell_y} \right)
+
+    Where:
+        - :math:`a` is the blob amplitude, `amplitude`.
+        - :math:`\ell_x` is the blob width in the propagation direction, `width_prop`.
+        - :math:`\ell_y` is the blob width in the perpendicular direction, `width_perp`.
+        - :math:`v` is the horizontal blob velocity.
+        - :math:`w` is the vertical blob velocity.
+        - :math:`t_k` is the blob arriving time at the position x=0, `t_init`.
+        - :math:`\tau_\shortparallel` is the drainage time, `t_drain`.
+        - :math:`\varphi` is the blob pulse shape, `blob_shape`.
+
+    Additionally, a tilt angle can be provided through `theta`.
+    """
 
     def __init__(
         self,
@@ -124,6 +142,11 @@ def discretize_blob(
         one_dimensional : bool, optional
             Flag indicating a one-dimensional blob (default: False).
 
+        Notes
+        -----
+        The periodicity in the y direction is implemented by first substracting the number of full domain Ly
+        propagations made by the blob and by summing mirror blobs at vertical positions +-Ly.
+
         Returns
         -------
         discretized_blob : NDArray

blobmodel/geometry.py

@@ -7,7 +7,10 @@
 
 
 class Geometry:
-    """Define grid for Model."""
+    """
+    Represents the space and time grid used by the Model class to discretize the blob evolution.
+    It builds a meshgrid based on the desired resolution and length in each coordinate.
+    """
 
     def __init__(
         self,

blobmodel/model.py

@@ -13,7 +13,13 @@
 
 
 class Model:
-    """2D Model of propagating blobs."""
+    """
+    Class storing all parameters relevant for the realization of a random process of a superposition of
+    uncorrelated pulses propagating in two dimensions. The realization is performed by calling `make_realization` which:
+        - uses a `BlobFactory` to make a list of blobs following the specified blob parameter distribution functions,
+        - each 'Blob' is discretized by calling its `discretize_blob` function and
+        - the discretization is performed on a grid given by the `Geometry`.
+    """
 
     def __init__(
         self,

blobmodel/stochasticality.py

@@ -8,8 +8,10 @@
 
 
 class BlobFactory(ABC):
-    """Abstract class used by 2d propagating blob model to specify blob
-    parameters."""
+    """
+    Abstract class used by 2d propagating blob model to specify blob
+    parameters.
+    """
 
     @abstractmethod
     def sample_blobs(
@@ -20,7 +22,9 @@ def sample_blobs(
         blob_shape: AbstractBlobShape,
         t_drain: Union[float, NDArray],
     ) -> List[Blob]:
-        """creates list of Blobs used in Model."""
+        """
+        Creates a list of Blobs used in Model.
+        """
         raise NotImplementedError
 
     @abstractmethod