Helper functions¶

Various functions¶

class pigreads.helper.ModelParameters(models, imodel)¶

Bases: MutableMapping[str, float]

A view into the core implementation of the models allowing reading and modifying the parameters of a model.

Parameters:

models (Models) – Instance of the models class to link to the core.
imodel (int) – Index of the model.

Variables:

models (pigreads.models.Models) – Instance of the models class to link to the core.
imodel (int) – Index of the model.

__delitem__(key)¶

Delete the parameter with the given key.

Note: This operation is not supported in this class.

Parameters:: key (str) – Key of the parameter.
Return type:: None

__getitem__(key)¶

Get the parameter with the given key.

Parameters:: key (str) – Key of the parameter.
Return type:: float
Returns:: Parameter value.

__iter__()¶

Get an iterator of the keys of the parameters.

Return type:: Iterator[str]
Returns:: Iterator of the keys of the parameters.

__len__()¶

Get the number of parameters.

Return type:: int
Returns:: Number of parameters.

__repr__()¶

Get the string representation of the parameters.

Return type:: str
Returns:: String representation of the parameters.

__setitem__(key, value)¶

Set the parameter with the given key.

Parameters:

key (str) – Key of the parameter.
value (float) – New value of the parameter.

Return type:

None

__str__()¶

Get the string representation of the parameters.

Return type:: str
Returns:: String representation of the parameters.

_key_to_index(key)¶

Get the index of the parameter with the given key.

Parameters:: key (str) – Key of the parameter.
Return type:: int
Returns:: Index of the parameter.

to_dict()¶

Convert the parameters to a dictionary.

Return type:: dict[str, float]
Returns:: Dictionary of the parameters.

pigreads.helper.delta(x, ax=-1)¶

Extract grid spacing from a 3D array.

Parameters:

x (ndarray[Any, Any]) – A 3D array.
ax (int) – The axis along which to calculate the distance. (default: -1)

Return type:

float

Returns:

The distance between the first two points.

For example, consider this code:

z, y, x = np.mgrid[0, 0:4:0.2, 0:1:5j]
dx = pig.delta(z, ax=-1)
dy = pig.delta(z, ax=-2)
dz = pig.delta(z, ax=-3)

pigreads.helper.deltas(*x)¶

Extract grid spacing from a 3D meshgrid.

For example, consider this code:

z, y, x = np.mgrid[0, 0:4:0.2, 0:1:5j]
dz, dy, dx = pig.deltas(z, y, x)

Parameters:: x (ndarray[Any, Any]) – A 3D array.
Return type:: list[float]
Returns:: A list with the distances between the points.

pigreads.helper.get_upper_triangle(matrix)¶

Convert a 3x3 matrix to a 6D vector, with the diagonal and upper triangle of the matrix as elements in the order xx, yy, zz, yz, xz, xy. Additional dimensions are supported, but the last two dimensions must each have size 3.

Parameters:: matrix (ndarray[Any, Any]) – A 3x3 matrix.
Return type:: ndarray[Any, Any]
Returns:: A 6D vector.

pigreads.helper.normalise_vector(f, dtype=<class 'numpy.float32'>)¶

Normalise a 3D vector to unit length.

Parameters:

f (ndarray[Any, Any] | list[int] | tuple[int, int, int]) – A 3D vector over space with shape (Nz, Ny, Nx, 3).
dtype (type) – Data type of the arrays, i.e., single or double precision floating point numbers. (default: <class 'numpy.float32'>)

Return type:

ndarray[Any, Any]

Returns:

A 5D vector with shape (Nz, Ny, Nx, 3, 1).

pigreads.helper.prepare_array(shape, path=None, dtype=<class 'numpy.float32'>)¶

Prepare an array in a given shape.

Either create a new array or load an existing array from the file with the given path as a memory map.

The shape and dtype of the array are given as arguments. If the path is None, a new array is created. If the path is a file, the array is loaded from the file. If the array is not of the correct shape or dtype or the file does not exist, a new array is created.

The array is returned as a memory map if a path is given, otherwise as a normal numpy array.

Parameters:

shape (tuple[int, ...]) – Shape of the array.
path (Path | str | None) – Path to the file to load the array from. (default: None)
dtype (type) – Data type of the arrays, i.e., single or double precision floating point numbers. (default: <class 'numpy.float32'>)

Return type:

ndarray[Any, Any]

Returns:

Resulting array.

See:

numpy.lib.format.open_memmap()

pigreads.helper.to_ithildin(framedur, dt, dz, dy, dx, models, states, inhom=None)¶

Convert the output of a Pigreads simulation to an Ithildin SimData object.

While originally designed for a different reaction-diffusion solver, the Python module for Ithildin is useful to analyse Pigreads simulations.

Parameters:

framedur (float) – The duration between subsequent frames, usually in milliseconds.
dt (float) – The time step size used in pigreads.models.Models.run(), usually in milliseconds.
dz (float) – The distance between points in the z-dimension, see pigreads.helper.deltas().
dy (float) – The distance between points in the y-dimension.
dx (float) – The distance between points in the x-dimension.
models (Models) – The models used in the simulation, see pigreads.models.Models.
states (ndarray[Any, Any]) – The states of the simulation, a 5D array of shape (Nt, Nz, Ny, Nx, Nv), see pigreads.models.Models.resting_states() and pigreads.models.Models.run().
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)

Return type:

tuple[dict[str, Any], dict[str, ndarray[Any, Any]]]

Returns:

Tuple of an Ithildin log file as a string and a dictionary of the variables by variable name.

Usage:

import ithildin as ith
log, variables = pig.to_ithildin(Nt * dt, dt, dz, dy, dx, models, states, inhom)
sd = ith.SimData(log=ith.Log(data=log))
sd.vars = variables