blobmodel package

Submodules

blobmodel.blob_shape module

This module defines classes for blob pulse shapes used in two-dimensional simulations.

class blobmodel.blob_shape.AbstractBlobShape

Bases: ABC

Abstract class containing the blob pulse shapes. Two-dimensional blob pulse shapes are written in the form:

phi(theta_x, theta_y) = phi_x(theta_x) * phi_y(theta_y)

abstract get_blob_shape_perp(theta: ndarray, **kwargs) → ndarray
abstract get_blob_shape_prop(theta: ndarray, **kwargs) → ndarray
class blobmodel.blob_shape.BlobShapeEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class representing blob shapes.

dipole = 7
double_exp = 3
exp = 1
gaussian = 4
lorentz = 2
rect = 5
secant = 6
class blobmodel.blob_shape.BlobShapeImpl(pulse_shape_prop=BlobShapeEnum.gaussian, pulse_shape_perp=BlobShapeEnum.gaussian)

Bases: AbstractBlobShape

Implementation of the AbstractPulseShape class.

get_blob_shape_perp(theta: ndarray, **kwargs) → ndarray

Compute the pulse shape perpendicular to the propagation direction.

Parameters:

  • theta (np.ndarray) – Array of theta values.

  • kwargs – Additional keyword arguments.

Returns:

Array representing the pulse shape perpendicular to the propagation direction.

Return type:

np.ndarray

get_blob_shape_prop(theta: ndarray, **kwargs) → ndarray

Compute the pulse shape in the propagation direction.

Parameters:

  • theta (np.ndarray) – Array of theta values.

  • kwargs – Additional keyword arguments.

Returns:

Array representing the pulse shape in the propagation direction.

Return type:

np.ndarray

blobmodel.blobs module

This module defines a Blob class and related functions for discretizing and manipulating blobs.

class blobmodel.blobs.Blob(blob_id: int, blob_shape: AbstractBlobShape, amplitude: float, width_prop: float, width_perp: float, v_x: float, v_y: float, pos_x: float, pos_y: float, t_init: float, t_drain: float | NDArray[Any, Any], prop_shape_parameters: dict | None = None, perp_shape_parameters: dict | None = None, blob_alignment: bool = True, theta: float = 0)

Bases: object

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:

\[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:

  • \(a\) is the blob amplitude, amplitude.

  • \(\ell_x\) is the blob width in the propagation direction, width_prop.

  • \(\ell_y\) is the blob width in the perpendicular direction, width_perp.

  • \(v\) is the horizontal blob velocity.

  • \(w\) is the vertical blob velocity.

  • \(t_k\) is the blob arriving time at the position x=0, t_init.

  • \(\tau_\shortparallel\) is the drainage time, t_drain.

  • \(\varphi\) is the blob pulse shape, blob_shape.

Additionally, a tilt angle can be provided through theta.

discretize_blob(x: NDArray[Any, Any], y: NDArray[Any, Any], t: NDArray[Any, Any], Ly: float, periodic_y: bool = False, one_dimensional: bool = False) → NDArray[Any, Any]

Discretize blob on grid. If one_dimensional the perpendicular pulse shape is ignored.

Parameters:

  • x (NDArray) – Grid coordinates in the x-direction.

  • y (NDArray) – Grid coordinates in the y-direction.

  • t (NDArray) – Time coordinates.

  • Ly (float) – Length of domain in the y-direction.

  • periodic_y (bool, optional) – Flag indicating periodicity in the y-direction (default: False).

  • 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 – Discretized blob on a 3D array with dimensions (x, y, t).

Return type:

NDArray

blobmodel.geometry module

This module defines the Geometry class for creating a grid for the Model.

class blobmodel.geometry.Geometry(Nx: int, Ny: int, Lx: float, Ly: float, dt: float, T: float, t_init: float, periodic_y: bool)

Bases: object

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.

blobmodel.model module

This module defines a 2D model of propagating blobs.

class blobmodel.model.Model(Nx: int = 100, Ny: int = 100, Lx: float = 10, Ly: float = 10, dt: float = 0.1, T: float = 10, periodic_y: bool = False, blob_shape: ~blobmodel.blob_shape.AbstractBlobShape = <blobmodel.blob_shape.BlobShapeImpl object>, num_blobs: int = 1000, t_drain: float | ~nptyping.ndarray.NDArray[~typing.Any, ~typing.Any] | int = 10, blob_factory: ~blobmodel.stochasticality.BlobFactory = <blobmodel.stochasticality.DefaultBlobFactory object>, t_init: float = 0, labels: str = 'off', label_border: float = 0.75, one_dimensional: bool = False, verbose: bool = True)

Bases: object

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.

get_blobs() → List[Blob]

Return the list of blobs.

Returns:

List of Blob objects.

Return type:

List[Blob]

Notes

  • Note that if Model.sample_blobs has not been called, the list will be empty

make_realization(file_name: str | None = None, speed_up: bool = False, error: float = 1e-10) → Dataset

Integrate the Model over time and write out data as an xarray dataset.

Parameters:

  • file_name (str, optional) – File name for the .nc file containing data as an xarray dataset.

  • speed_up (bool, optional) – Flag for speeding up the code by discretizing each single blob at smaller time window when blob values fall under given error value the blob gets discarded

  • error (float, optional) – Numerical error at x = Lx when the blob gets truncated.

Returns:

xarray dataset with the data resulting from a realization of the process described by the model and evaluated in a three-dimensional grid with dimensions: - x: Horizontal coordinate - y: Vertical coordinate - t: Time coordinate The resulting blob density, evaluated in the grid, is given by the DataArray, n. In case that the model is one-dimensional, the vertical coordinate y will be of length 1.

Return type:

xr.Dataset

Notes

  • speed_up is only a good approximation for blob_shape=”exp”

blobmodel.plotting module

This module provides functions to create and display animations of model output.

blobmodel.plotting.show_model(dataset: Dataset, variable: str = 'n', interval: int = 100, gif_name: str | None = None, fps: int = 10) → None

Creates an animation that shows the evolution of a specific variable over time.

Parameters:

  • dataset (xr.Dataset) – Model data.

  • variable (str, optional) – Variable to be animated (default: “n”).

  • interval (int, optional) – Time interval between frames in milliseconds (default: 100).

  • gif_name (str, optional) – If not None, save the animation as a GIF and name it acoridingly.

  • fps (int, optional) – Set the frames per second for the saved GIF (default: 10).

Return type:

None

Notes

  • This function chooses between a 1D and 2D visualizations based on the dimensionality of the dataset.

blobmodel.stochasticality module

This module defines a class for generating blob parameters.

class blobmodel.stochasticality.BlobFactory

Bases: ABC

Abstract class used by 2d propagating blob model to specify blob parameters.

abstract is_one_dimensional() → bool

returns True if the BlobFactory is compatible with a one_dimensional model.

abstract sample_blobs(Ly: float, T: float, num_blobs: int, blob_shape: AbstractBlobShape, t_drain: float | NDArray[Any, Any]) → List[Blob]

Creates a list of Blobs used in Model.

class blobmodel.stochasticality.DefaultBlobFactory(A_dist: DistributionEnum = DistributionEnum.exp, wx_dist: DistributionEnum = DistributionEnum.deg, wy_dist: DistributionEnum = DistributionEnum.deg, vx_dist: DistributionEnum = DistributionEnum.deg, vy_dist: DistributionEnum = DistributionEnum.deg, spx_dist: DistributionEnum = DistributionEnum.deg, spy_dist: DistributionEnum = DistributionEnum.deg, A_parameter: float = 1.0, wx_parameter: float = 1.0, wy_parameter: float = 1.0, vx_parameter: float = 1.0, vy_parameter: float = 1.0, shape_param_x_parameter: float = 0.5, shape_param_y_parameter: float = 0.5, blob_alignment: bool = True)

Bases: BlobFactory

Default implementation of BlobFactory.

Generates blob parameters for different possible random distributions. All random variables are independent from each other

is_one_dimensional() → bool

Returns True if the BlobFactory is compatible with a one-dimensional model.

Returns:

True if the BlobFactory is compatible with a one-dimensional model, False otherwise.

Return type:

bool

Notes

  • Perpendicular width parameters are irrelevant since perp shape should be ignored by the Bolb class.

sample_blobs(Ly: float, T: float, num_blobs: int, blob_shape: AbstractBlobShape, t_drain: float | NDArray[Any, Any]) → List[Blob]

Creates a list of Blobs used in the Model.

Parameters:

  • Ly (float) – Size of the domain in the y-direction.

  • T (float) – Total time duration.

  • num_blobs (int) – Number of blobs to generate.

  • blob_shape (AbstractBlobShape) – Object representing the shape of the blobs.

  • t_drain (float) – Time at which the blobs start draining.

Returns:

List of Blob objects generated for the Model.

Return type:

List[Blob]

set_theta_setter(theta_setter)

Set a lambda function to set the value of theta (blob tilting) for each blob. Important: the blob angle is measured with respect to the x axis, not with respect to the velocity vector.

Module contents