Models¶

Classes to manage models¶

class pigreads.models.Models(tuples_key_kwargs=None, double_precision=False)¶

Bases: object

This class stores the models to be used in a Pigreads simulation. The models are defined by OpenCL code. The class variable available is a dictionary of all available models.

Models are added to an instance of this class using the add() method, or as a list of tuples in the constructor. The order of the models is the order in which they are used in the simulation. models[0] is used at inhom values of 1, models[1] at 2, etc.

Parameters:

tuples_key_kwargs (list[tuple[str, dict[str, float]]] | str | None) – A list of tuples with the model key and keyword arguments encoding parameter names and values to be passed to the add() method. If a string is given, it is treated the name of the first model to be added with no keyword arguments. If None, no models are added. (default: None)
double_precision (bool) – If True, use double precision for calculations. (default: False)

Variables:

double_precision (bool) – If True, use double precision for calculations.

property Nv: int¶: Maximum number of state variables in the models.

__getitem__(imodel)¶

Get the model entry with the given index linked to the core implementation to read and change model parameters.

Parameters:: imodel (int) – Index of the model.
Return type:: ModelEntry
Returns:: Model entry with a pigreads.helper.ModelParameters view.

__iter__()¶

Get an iterator of model entries linked to the core implementation to read and change model parameters.

Return type:: Iterator[ModelEntry]
Returns:: Iterator of model entries.

__len__()¶

The number of models added to the list of models.

Return type:: int

add(key, **parameters)¶

Select and enable a model with given parameters.

Parameters:

key (str) – The key of the model to be added.
parameters (Any) – Parameter names and their values to be passed to the model.

Return type:

None

available: ClassVar[dict[str, ModelDefinition]]¶: Dictionary of all available models.

property block_size: tuple[int, int, int]¶

Local work size for running OpenCL kernels.

The block_size parameter corresponds to OpenCL’s localWorkSize and defines the size of a small block of the domain that is processed together by the OpenCL platform (typically the GPU).

If chosen too small, the performance will be suboptimal. If chosen too large, the OpenCL kernel will not run. The default value is (1, 8, 8), i.e., a block of unit width in z, and 8x8 in the y and x dimensions. This is a good compromise for most applications.

Tweaking this value can lead to significant performance improvements.

code(key, model_id)¶

OpenCL kernel source code defining a model.

Parameters:

key (str) – The key of the model.
model_id (int) – An integer identifying the model.

Return type:

str

property core: Models¶: Get the link to the core implementation of this class.

property dtype: type¶: Data type to use for calculations, i.e., single or double precision floating point numbers.

get_definition(imodel)¶

Get the definition of the model with the given index.

Parameters:: imodel (int) – Index of the model.
Return type:: ModelDefinition

get_entry(imodel)¶

Get the model entry with the given index linked to the core implementation to read and change model parameters.

Parameters:: imodel (int) – Index of the model.
Return type:: ModelEntry
Returns:: Model entry with a pigreads.helper.ModelParameters view.

get_key(imodel)¶

Get the key of the model with the given index.

Parameters:: imodel (int) – Index of the model.
Return type:: str

get_parameter(imodel, iparam)¶

Get the parameter with the given indices.

Parameters:

imodel (int) – Index of the model.
iparam (int) – Index of the parameter.

Return type:

float

Returns:

Parameter value.

resting_states(inhom, Nframes=1, dtype=None)¶

Create an array of states and fill the first frame with the resting values of the models depending on the inhom values.

Parameters:

inhom (ndarray[Any, Any]) – A 3D array with integer values, encoding which model to use at each point. Its value is zero for points outside the medium and one or more for points inside. Values larger than zero are used to select one of multiple models: 1 for models[0], 2 for models[1], etc.
Nframes (int) – The number of frames in time. (default: 1)
dtype (type | None) – Data type of the arrays, i.e., single or double precision floating point numbers. (default: None)

Return type:

ndarray[Any, Any]

Returns:

A 5D array of shape (Nframes, Nz, Ny, Nx, Nv).

run(inhom, weights, states, stim_signal=None, stim_shape=None, Nt=1, dt=0.001)¶

Run a Pigreads simulation.

Parameters:

inhom (ndarray[Any, Any]) – A 3D array with integer values, encoding which model to use at each point. Its value is zero for points outside the medium and one or more for points inside. Values larger than zero are used to select one of multiple models: 1 for models[0], 2 for models[1], etc.
weights (ndarray[Any, Any]) – The weights for the diffusion term, see weights().
states (ndarray[Any, Any]) – The initial states of the simulation, a 4D array of shape (Nz, Ny, Nx, Nv), see Models.resting_states().
stim_signal (ndarray[Any, Any] | None) – A 3D array with the stimulus signal at each time point for all variables, with shape (Nt, Ns, Nv). If None, no stimulus is applied. (default: None)
stim_shape (ndarray[Any, Any] | None) – A 4D array specifying the shape of the stimulus, with shape (Ns, Nz, Ny, Nx). If None, no stimulus is applied (default: None)
Nt (int) – The number of time steps to run the simulation for. (default: 1)
dt (float) – The time step size. (default: 0.001)

Return type:

ndarray[Any, Any]

Returns:

The final states of the simulation, a 4D array of shape (Nz, Ny, Nx, Nv).

set_parameter(imodel, iparam, value)¶

Set the parameter with the given indices.

Parameters:

imodel (int) – Index of the model.
iparam (int) – Index of the parameter.
value (float) – New parameter value.

Return type:

None

weights(dz=1.0, dy=1.0, dx=1.0, inhom=None, diffusivity=1.0)¶

Calculate the weights for the diffusion term in the reaction-diffusion equation.

Parameters:

dz (float) – The distance between points in the z-dimension, see pigreads.helper.deltas(). (default: 1.0)
dy (float) – The distance between points in the y-dimension. (default: 1.0)
dx (float) – The distance between points in the x-dimension. (default: 1.0)
inhom (ndarray[Any, Any] | None) – A 3D array with integer values, encoding which model to use at each point. Its value is zero for points outside the medium and one or more for points inside. If None, all points are considered inside the medium. (default: None)
diffusivity (ndarray[Any, Any] | float) – The diffusivity matrix, see pigreads.diffusivity.diffusivity_matrix(). If a scalar is given, the matrix is isotropic with the same value in all directions. (default: 1.0)

Return type:

ndarray[Any, Any]

Returns:

Weight matrix for the diffusion term, A 5D array of shape (1, Nz, Ny, Nx, 19).