Simulation

Schema for a simulation

class pigreads.schema.simulation.Simulation(**data)

Bases: BaseModel

Definition of a simulation.

The simulation is defined on a three dimensional cuboid with Nz, Ny, and Nx grid points in the z, y, and x directions respectively. The grid points are separated by dz, dy, and dx units in the z, y, and x directions. The simulation is run for Nfr frames with Nt time steps per frame. Each time step is dt units long.

The simulation definion contains a list of pigreads.schema.model.ModelEntry objects (models) which define the reaction terms in the reaction-diffusion equation. See also pigreads.models.Models.

The diffusivity matrix is defined by a pigreads.schema.diffusivity.Diffusivity object.

The inhomogeneity (inhom) of the medium, i.e., which parts of the simulation are active and which model to use where, is defined by a list of pigreads.schema.setter.Setter objects.

The initial state of the simulation is defined by a dictionary of pigreads.schema.setter.Setter objects. The keys of the dictionary are the variable names and the values are lists of setters.

A stimulus protocol is defined by a list of pigreads.schema.stimulus.Stimulus objects.

The flag double_precision can be set to True to use double precision floating point numbers in the simulation.

The required key pigreads is used to identify the simulation file format.

The simulation can be run by calling the run() method.

Example:

pigreads: 1
Nfr: 100
Nt: 200
Nz: 1
Ny: 200
Nx: 200
dt: 0.025
dz: 1
dy: 0.1
dx: 0.1
inhom:
- spherical:
    outside: 0
diffusivity: 0.03
models:
- marcotte2017dynamical:
    diffusivity_u: 1.0
    diffusivity_v: 0.05
init:
    u:
        slices:
            value: 1
            axis: -1
            end: 10
    v:
        slices:
            value: 2
            start: 100
            axis: -2

Read this and run a simulation like this:

from pigreads.schema import Simulation
data = yaml.safe_load(yaml_string)
sim = Simulation(**data)
sim.run(path="result.npy")

Or use the CLI:

$ pigreads run config.yaml result.npy

Parameters:

data (Any)

Nfr: int

Number of frames.

Nt: int

Number of time steps per frame.

Nx: int

Number of grid points in x direction.

Ny: int

Number of grid points in y direction.

Nz: int

Number of grid points in z direction.

diffusivity: DiffusivityFile | DiffusivityParams

Definition of the diffusivity matrix.

See:

pigreads.diffusivity.diffusivity_matrix()

double_precision: bool

Flag to use single or double precision floating point numbers.

dt: float

Time step.

dx: float

Grid spacing in x direction.

dy: float

Grid spacing in y direction.

dz: float

Grid spacing in z direction.

inhom: list[SetterFile | SetterSlices | SetterSpherical]

Definition of the inhomogeneity of the medium.

It defines which parts of the simulation are active and which model to use where.

See:

pigreads.schema.setter.Setter, prepare_inhom(), pigreads.models.Models.weights()

init: dict[str, list[SetterFile | SetterSlices | SetterSpherical]] | SetterFile

Definition of the initial state of the simulation.

The initial state is defined by a dictionary of variable names and lists of setters.

See:

pigreads.schema.setter.Setter, prepare_states()

static is_dict_of_dicts(d, excluded_keys=None)

Check if a value of a dictionary is also a dictionary.

Parameters:

• d (dict[Any, Any]) – Dictionary to check.

• excluded_keys (list[Any] | None) – Ignore values whose key is in excluded_keys. (default: None)

Return type:

bool

Returns:

True if it is a dictionary of dictionaries.

model_config: ClassVar[ConfigDict]

Configuration for pydantic.BaseModel.

models: list[ModelEntry]

Definition of the models to use in the simulation.

The models define the reaction terms in the reaction-diffusion equation.

See:

pigreads.models.Models, prepare_models()

classmethod normalise_diffusivity(diffusivity)

Normalise the diffusivity.

Normally, the diffusivity is given as an instance of pigreads.schema.diffusivity.Diffusivity.

Alternatively, if the diffusivity is given as a string, read the diffusivity matrix from the file. If the diffusivity is given as a float, set the diffusivity matrix to a constant value.

Parameters:

diffusivity (Any) – Any data to try to interpret.

Return type:

Any

Returns:

Normalised data.

classmethod normalise_inhom(inhom)

Normalise the inhomogeneity.

The inhomogeneity is given as lists of pigreads.schema.setter.Setter objects.

The setters are normalised using pigreads.schema.setter.normalise_list_of_setters().

Parameters:

inhom (Any) – Any data to try to interpret.

Return type:

Any

Returns:

Normalised data.

classmethod normalise_init(init)

Normalise the initial state.

The initial state is given as lists of pigreads.schema.setter.Setter objects.

The setters are normalised using pigreads.schema.setter.normalise_list_of_setters().

Parameters:

init (Any) – Any data to try to interpret.

Return type:

Any

Returns:

Normalised data.

classmethod normalise_models(models)

Normalise the models.

Normally, the models are given as a list of pigreads.schema.model.ModelEntry.

Alternatively, if the models are given as a string, it is converted to a list with a single model entry. If the models are given as a dictionary, it is converted to a list of model entries. If the models are given as a list of strings, they are converted to a list of model entries with empty parameter sets.

Parameters:

models (Any) – Any data to try to interpret.

Return type:

Any

Returns:

Normalised data.

pigreads: Literal[1]

Identifier for the simulation file format.

prepare_inhom()

Get the inhomogeneity array.

The inhomogeneity array is created by applying the setters in the inhom list to an array of ones with the shape of the grid.

The inhomogeneity array is used to define the active parts of the simulation and which model to use where.

Return type:

ndarray[Any, Any]

Returns:

Inhomogeneity array.

prepare_models()

Create a models object from the model entries.

The model entries are used to create the models object which is used to run the simulation.

Return type:

Models

Returns:

Models object.

prepare_space()

Get arrays with the coordinates of the grid points.

The arrays are returned as a tuple of three arrays with the z, y, and x coordinates of the grid points.

Return type:

tuple[ndarray[Any, Any], ndarray[Any, Any], ndarray[Any, Any]]

Returns:

Arrays for the spatial coordinates z, y, and x.

See:

numpy.meshgrid()

prepare_states(models, varidx, inhom, path=None)

Prepare the state array.

The state array is created as a five dimensional array with the shape (Nfr, Nz, Ny, Nx, Nv) where Nv is the number of variables in the model, see also pigreads.models.Models.Nv().

This array is created in three steps:

1. Create a new array with the correct shape and dtype using pigreads.helper.prepare_array().

2. Set the first frame of the array to the resting state of the model, see pigreads.models.Models.resting_states().

3. Apply the initial state setters to the first frame of the array.

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

Parameters:

• models (Models) – Models object.

• varidx (dict[str, int]) – Mapping of variable names to indices in the state array, see Simulation.varidx().

• inhom (ndarray[Any, Any]) – Inhomogeneity array.

• path (Path | str | None) – Path to memory map the state array to. (default: None)

Return type:

ndarray[Any, Any]

Returns:

State array.

prepare_stim(varidx)

Prepare the stimulus signal and shape.

The stimulus signal is created as a three dimensional array with the shape ((Nfr - 1)*Nt, Ns, Nv) where Ns is the number of stimuli in the simulation and Nv is the number of variables in the model, see also pigreads.models.Models.Nv(). This array is first set to zero and then modified by the signal steps in the stimulus objects, see pigreads.schema.stimulus.SignalStep and pigreads.schema.stimulus.Stimulus.

The stimulus shape is created as a four dimensional array with the shape (Ns, Nz, Ny, Nx) where Ns is the number of stimuli in the simulation. This array is first set to zero and then modified by the shape setters in the stimulus objects, see pigreads.schema.setter.Setter and pigreads.schema.stimulus.Stimulus.

The stimulus signal and shape are returned as a tuple.

Parameters:

varidx (dict[str, int]) – Mapping of variable names to indices in the state array see Simulation.varidx().

Return type:

tuple[ndarray[Any, Any], ndarray[Any, Any]]

Returns:

Stimulus signal and shape.

run(path=None, start_frame=0, progress=<function Simulation.<lambda>>, callback=None, infinite=False)

Run the simulation.

Parameters:

• start_frame (int) – The frame to start the simulation at, default is 0. (default: 0)

• path (Path | str | None) – The path to save the state array to, default is None, see pigreads.helper.prepare_array(). (default: None)

• progress (Callable[[Any], Any]) – A function to show progress, default is no progress updates. (default: <function Simulation.<lambda> at 0x7af38dd90880>)

• callback (Callable[[ndarray[Any, Any], int], bool] | None) – A function to call after each frame, default is no callback. If it returns False, stop iteration early. (default: None)

• infinite (bool) – Whether to run the simulation in an infinite loop, default is False. (default: False)

Return type:

ndarray[Any, Any]

Returns:

The results in the state array with the shape (Nfr, Nz, Ny, Nx, Nv).

The simulation calls the following methods to prepare the simulation:

• prepare_inhom()

• prepare_models()

• prepare_states()

• prepare_stim()

• pigreads.models.Models.weights()

The simulation is then run frame by frame using the pigreads.models.Models.run() function. The results are saved to the state array and returned.

stim: list[Stimulus]

Definition of the stimulus protocol.

The stimulus protocol is defined by a list of pigreads.schema.stimulus.Stimulus objects.

See:

pigreads.schema.stimulus.Stimulus, prepare_stim()

static varidx(models)

Create a dictionary mapping variable names to indices.

The indices are used to access the variables in the state array.

Parameters:

models (Models) – Models object.

Return type:

dict[str, int]

Returns:

Mapping of variable names to indices.