lgca.base.LGCA_base¶

class lgca.base.LGCA_base(nodes=None, dims=None, restchannels=0, density=0.1, bc='periodic', seed=None, propagation=True, **kwargs)¶

Bases: ABC

Abstract base class for classical LGCA with volume exclusion.

It holds all methods and attributes that are common for all geometries. Cannot simulate on its own. If you want to use it, instantiate one of the geometry-specific derived classes.

Parameters:

bc ({'absorbing', 'reflecting', 'periodic', 'inflow'}, default='periodic') – Boundary conditions. Not all bc are supported in all geometries (yet).

Attributes:

apply_boundariescallable: Function implementing the boundary conditions.
c: (Class attribute.) Array of the velocity channel vectors. Dimensions: (dims, lgca.velocitychannels),
cell_densitynumpy.ndarray: Number of particles at each lattice node in the current LGCA state. Computed field. Dimensions: lgca.dims.
cijnumpy.ndarray: Nematic tensor. Element-wise multiplication of neighborhood vectors with themselves. Computed from the geometry. Dimensions: (lgca.c.shape[1], lgca.c.shape[0], lgca.c.shape[0}). First dimension: neighborhood vector, second and third dimension: combination of x and y components of the vector as [[cix*cix, cix*ciy], [ciy*cix, ciy*ciy]].
concentration: Internal variable for the chemotaxis interaction.
dens_tnumpy.ndarray: Number of particles at each lattice node for all timesteps in the previous simulation. Only available after a simulation performed with timeevo(recorddens=True). Dimensions: (timesteps,) + lgca.dims.
dimstuple: Lattice dimensions/size of the lattice as (xdim,) (1D LGCA) or (xdim, ydim) (2D LGCA), excluding shadow nodes on the border.
guiding_tensor: Internal variable for the contact_guidance interaction.
interactioncallable: Interaction rule assigned to the LGCA.
interactions: (Class attribute.) List of interaction functions suitable for this type of LGCA.
jlist of numpy.ndarray: Flux for each possible channel configuration. Dimensions: (lgca.K + 1, len(lgca.c)).
Kint: Number of channels per node. Equal to lgca.velocitychannels + lgca.restchannels.
n_crit: Internal variable for the wetting interaction.
n_tnumpy.ndarray: Sum of particles in the lattice for all timesteps in the previous simulation. Only available after a simulation performed with timeevo(recordN=True). Dimensions: (timesteps,).
nodesnumpy.ndarray: State of the lattice, configuration of all channels. Dimensions: (lgca.l + 2*lgca.r_int, lgca.K) (in 1D LGCA) or (lgca.lx + 2*lgca.r_int, lgca.ly + 2*lgca.r_int, lgca.K). Includes shadow nodes on all borders for implementing boundary conditions.
nodes_tnumpy.ndarray: Full lattice configuration of non-border nodes for all timesteps in the previous simulation. Only available after a simulation performed with timeevo(record=True). Dimensions: (timesteps,) + lgca.dims + (K,).
nonbordertuple of numpy.ndarray: Indices of non-border nodes in the lgca.nodes array as (x-indices,) (in 1D LGCA) or (x-indices, y-indices) (in 2D LGCA), i.e. all nodes excluding shadow nodes for boundary conditions. Both arrays x-indices and y-indices have the dimensions lgca.dims.
permutationslist of numpy.ndarray: All possible configurations for a lattice site with lgca.K channels. Dimensions: (lgca.K + 1, n, lgca.K). n is the number of possible permutations for the node if x channels are occupied, where x is given by the first dimension.
r_intint, default=1: Interaction radius. Must be at least 1 to handle propagation.
restchannelsint: Number of resting channels.
silist of numpy.ndarray: Nematic tensor for all possible node configurations, obtained from lgca.permutations and py.cij. Dimensions: (lgca.K + 1, n, len(lgca.c), len(lgca.c)). n is the number of possible permutations for the node if x channels are occupied, where x is given by the first dimension.
velcells_t, restcells_tnumpy.ndarray: Sum of particles in velocity/rest channels, respectively, for all timesteps in the previous simulation. Only available after a simulation performed with timeevo(recordpertype=True). Dimensions: (timesteps,) + lgca.dims.
velocitychannels: (Class attribute.) Number of velocity channels.

See also

lgca.lgca_1d.LGCA_1D: Classical LGCA in a 1D geometry.
lgca.lgca_square.LGCA_Square: Classical LGCA in a 2D square geometry.
lgca.lgca_hex.LGCA_Hex: Classical LGCA in a 2D hexagonal geometry.

apply_abc()¶

Apply absorbing boundary conditions.

Update self.nodes, using the shadow border nodes and respecting the geometry.

apply_inflowbc()¶

Apply inflow boundary conditions.

Update self.nodes, using the shadow border nodes and respecting the geometry.

apply_pbc()¶

Apply periodic boundary conditions.

Update self.nodes, using the shadow border nodes and respecting the geometry.

apply_rbc()¶

Apply reflecting boundary conditions.

Update self.nodes, using the shadow border nodes and respecting the geometry.

abstract property c: ndarray¶: (Class attribute.) Array of the velocity channel vectors. Dimensions: (dims, lgca.velocitychannels), where dims is 1 or 2 depending on the geometry.

calc_flux(nodes)¶

Calculate the flux vector for all lattice sites in nodes.

The elements of the flux vectors are computed as the dot product between the LGCA’s neighborhood vectors and the velocity channel configuration in nodes.

Parameters:: nodes (numpy.ndarray) – Lattice configuration to compute the flux for. Must have more than or the same number of dimensions as self.nodes and nodes.shape[-1] >= self.velocitychannels. Is typically self.nodes.
Returns:: Array of flux vectors at each lattice site. Dimensions: nodes.shape[:-1] + (len(self.c),).

calc_permutations()¶: Initialize lazy computation structures for permutations. Only compute permutations when actually needed.

get_flux_permutations(n_particles)¶: Get flux permutations for n_particles.

get_permutations(n_particles)¶

Get permutations for n_particles.

Parameters:: n_particles (int) – Number of occupied channels.
Returns:: Array of permutations for n_particles.

abstractmethod gradient(qty)¶

Compute the gradient of qty along all axes.

Parameters:: qty (numpy.ndarray) – Quantity to take the gradient of. Needs to have the same number of dimensions as self.nodes. If qty.shape == self.nodes.shape[:-1] the result can be indexed with the LGCA coordinates (see example).
Returns:: Computed gradient. Dimensions: qty.shape + (len(self.c),). If self and qty are 2D arrays, gradient(qty)[...,0] is the gradient in x direction and gradient(qty)[...,1] the gradient in y direction.

Notes

The gradient is calculated using numpy.gradient() with stepwidth h=0.5 (s.t. no normalization takes place). It is computed as the central finite difference with equidistant support points and supports one-sided differences at the boundaries.

In most cases this yields the simple difference between the two closest array elements in the given direction. For example, the gradient at position 1 of np.array([1, 2, 4]) would be (4 - 1)/(2 * 0.5) = 3.

Examples

If the input quantity has the same x (and y) dimensions as the LGCA’s nodes, the gradient at each node position can be accessed the same way as the node itself.

>>> from lgca import get_lgca
>>> import numpy as np
>>> # define a square LGCA to illustrate dimensions
>>> lgca = get_lgca(geometry='square', dims=(2,3))
>>> lgca.nodes.shape  # (xdim, ydim, number of channels)
(4, 5, 4)
>>> my_qty = np.array([[0,0,0,0,0],
>>>                    [1,1,1,1,1],
>>>                    [2,2,2,3,2],
>>>                    [3,3,3,3,3]])
>>> my_qty.shape  # (xdim, ydim)
(4, 5)
>>> grad = lgca.gradient(my_qty)
>>> grad.shape  # (xdim, ydim, number of dimensions)
(4, 5, 2)
>>> # address like internal LGCA fields: first dimension is x (printed vertically),
>>> # second dimension is y (printed horizontally), this can be a bit confusing
>>> for coord in lgca.coord_pairs:
>>>     if np.any(grad[coord]>2):
>>>         print("Gradient at index", coord, "is ", grad[coord])
>>>         print("Configuration at index ", coord, " is ", lgca.nodes[coord],
>>>               ", with cell density ", lgca.cell_density[coord])
Gradient at index (1, 3) is  [3. 0.]
Configuration at index  (1, 3)  is  [False False False  True] , with cell density  1

The first element of the gradient holds the gradient in x direction, the second element the gradient in y direction. Note that (1, 3) is the index corresponding to a logical non-border coordinate (0, 2) if the interaction radius is 1. This is relevant for defining a custom field qty: Only the field values at non-border indices will be “felt” by the particles in the LGCA if the interaction is defined accordingly, but border nodes can be used to specify the field’s boundary conditions.

The gradient in x direction is 3 = (3 - 0)/1. In y direction it is 0 = (1 - 1)/1.

abstractmethod init_coords()¶

Initialize LGCA coordinates. These are used to index the lattice nodes. In the implementation, set self.nonborder, self.xcoords, self.ycoords, and self.coord_pairs to meaningful and consistent values.

Must match what is done in set_dims() and init_nodes(). For the attribute types see lgca.base.LGCA_base.

abstractmethod init_nodes(density, nodes=None, **kwargs)¶

Initialize LGCA lattice configuration. Create the lattice and then assign particles to channels in the nodes. In the implementation, set self.nodes.

Must match what is done in set_dims() and init_coords(). For arguments and attribute types see lgca.base.LGCA_base.

abstract property interactions: list¶: (Class attribute.) List of interaction functions suitable for this type of LGCA.

print_interactions()¶: Print the list of pre-implemented interactions for this LGCA type.

print_nodes()¶: Print the full lattice configuration as integers.

abstractmethod propagation()¶

Perform the transport step of the LGCA: Move particles through the lattice according to their velocity.

Propagate the particles by updating self.nodes, respecting the geometry. Boundary conditions are enforced later by apply_boundaries().

random_reset(density)¶

Randomly fill channels so that each node has on average density particles.

Each channel is independently occupied with probability density / self.K.

Parameters:: density (float) – Desired average number of particles per node. density = total_number_of_particles / number_of_nodes.

set_bc(bc)¶

Set the boundary conditions.

Selects a method which is called every timestep to enforce boundary conditions. The methods to select from are implemented in the derived classes. The chosen one is assigned to self.apply_boundaries().

Parameters:: bc ({'absorbing', 'reflecting', 'periodic', 'inflow'}) – Boundary conditions. Not all bc are supported in all geometries (yet).

abstractmethod set_dims(dims=None, nodes=None, restchannels=0)¶

Set LGCA dimensions. In the implementation, set self.K, self.restchannels and self.dims to meaningful and consistent values.

Must match what is done in init_coords() and init_nodes(). For arguments and attribute types see lgca.base.LGCA_base.

set_interaction(**kwargs)¶

Set the interaction rule and respective needed parameters.

Set self.interaction and possibly add entries in self.interaction_params. Do not use this to specify a custom interaction. In order to do this (as of now), self.interaction and self.interaction_params must be manipulated directly from an external script.

Parameters:

kwargs['interaction'] (str, default='random_walk') – Name of the predefined interaction in lgca.interactions.
**kwargs – Interaction parameters.

set_r_int(r)¶

Change the interaction radius. Update shadow border nodes accordingly.

This has effects on self.nodes, the coordinates and the computed fields.

Parameters:: r (int) – New interaction radius.

timeevo(timesteps=100, record=False, recordN=False, recorddens=True, showprogress=True, recordpertype=False)¶

Perform a simulation of the LGCA for timesteps timesteps.

Different quantities can be recorded during the simulation, e.g. the total number of particles at each timestep. They are stored in LGCA attributes.

Parameters:

timesteps (int, default=100) – How long the simulation should be performed.
record (bool, default=False) – Record the full lattice configuration for each timestep in self.nodes_t.
recorddens (bool, default=True) – Record the number of particles at each lattice site for each timestep in self.dens_t.
recordN (bool, default=False) – Record the total number of particles in the lattice for each timestep in self.n_t.
recordpertype (bool, default=False) – Record the number of particles in velocity channels/resting channels at each lattice site for each timestep in self.velcells_t and self.restcells_t, respectively.
showprogress (bool, default=True) – Show a simple progress bar with a percentage of performed timesteps in the standard output.

timestep()¶: Update the state of the LGCA from time k to k+1. Includes the interaction and propagation steps.

total_population()¶

Calculate the amount of particles in the lattice.

Returns:: Total population size.

update_dynamic_fields()¶

Update “fields” from the current LGCA state that store important variables to compute other dynamic steps.

Computes self.cell_density, number of particles at each lattice node.

abstract property velocitychannels: int¶: (Class attribute.) Number of velocity channels.

biolgca

Navigation

Related Topics

lgca.base.LGCA_base¶