lgca.lgca_3dmoore.NoVE_IBLGCA_Moore

class lgca.lgca_3dmoore.NoVE_IBLGCA_Moore(nodes=None, dims=None, density=0.1, restchannels=1, bc='periodic', seed=None, propagation=True, **kwargs)

Bases: NoVE_IBLGCA_Cubic, LGCA_3dMoore

Identity-based 3D Moore LGCA without volume exclusion.

add_family(ancestor_fam)

Create a new family and register it in the family tree.

Parameters:

ancestor_fam (int) – Family that the new one descends from.

Warning

Please do not call this unless you are writing an interaction function that deals with mutations.

It accesses self.maxfamily and self.family_props which do not exist if self.init_families() has not been called in the LGCA initialization.

animate_config(nodes_t=None, **kwargs)

Animate the configuration of the NoVE_IBLGCA_Cubic model.

animate_density(density_t=None, **kwargs)

Animate the density of the NoVE_IBLGCA_Cubic model.

animate_flux(nodes_t=None, **kwargs)

Animate the flux of the NoVE_IBLGCA_Cubic model.

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.

c = array([[-1., -1., -1., -1., -1., -1., -1., -1., -1.,  0.,  0.,  0.,  0.,          0.,  0.,  0.,  0.,  1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.],        [-1., -1., -1.,  0.,  0.,  0.,  1.,  1.,  1., -1., -1., -1.,  0.,          0.,  1.,  1.,  1., -1., -1., -1.,  0.,  0.,  0.,  1.,  1.,  1.],        [-1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1., -1.,          1., -1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1.]])

calc_entropy(base=None)

Calculate entropy of the lattice. :type base: :param base: base of the logarithm, defaults to 2 :return: entropy according to information theory as scalar

calc_family_generations()

Calculate which generation each family belongs to, i.e. how many mutations have occurred. The list is returned and stored in self.family_props['generation'].

Returns:

Family generations indexed by family ID, helper root family = generation 0, families at the beginning of the simulation = generation 1.

calc_family_pop_alive()

Calculate how many cells of each family are alive. :returns: np.ndarray fam_pop_array - array of family population counts indexed by family ID

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_generation_pop()

Calculate the current population per family generation.

Returns:

Cell numbers per generation, indexed by generation (helper root family is generation 0, families present at initialization are generation 1).

calc_generation_pop_t(cutoff_abs=None, cutoff_rel=None)

Calculate the population per family generation at each simulation step. Requires a previous self.timeevo() with recordfampop=True.

Parameters:

• cutoff_abs (int) – Exclude families that never exceeded this population size in absolute numbers. cutoff_rel takes precedence over cutoff_abs.

• cutoff_rel (float) – Exclude families that never exceeded this population size, expressed as a fraction of the total population. cutoff_rel takes precedence over cutoff_abs.

Returns:

Cell numbers per generation at each timestep (helper root family is generation 0, families present at initialization are generation 1). Dimensions: (timesteps+1, generations+1).

calc_init_families_pop()

Calculate the current population per family that was initialised in the beginning of the simulation (“initial ancestor”) and its descendants.

Returns:

• init_families_pop (numpy.ndarray) – Population per initial family.

• init_ancestor_IDs (numpy.ndarray) – Initial family ID corresponding to each position in init_families_pop.

calc_init_families_pop_t(cutoff_abs=None, cutoff_rel=None)

Calculate the current population per family that was initialised in the beginning of the simulation (“initial ancestor”) and its descendants at each simulation step. Requires a previous self.timeevo() with recordfampop=True.

Parameters:

• cutoff_abs (int) – Exclude families that never exceeded this population size in absolute numbers. cutoff_rel takes precedence over cutoff_abs.

• cutoff_rel (float) – Exclude families that never exceeded this population size, expressed as a fraction of the total population. cutoff_rel takes precedence over cutoff_abs.

Returns:

• init_families_pop (numpy.ndarray) – Population per initial family at each timestep, dimensions: (timesteps+1, num_init_families+1).

• init_ancestor_IDs (numpy.ndarray) – Family ID corresponding to each position on the family dimension in init_families_pop.

calc_mean_alignment()

Calculate the mean alignment measure. The mean alignment is a measure for local alignment of particle orientation in the lattice. It is calculated as the agreement in direction between the flux of a lattice site and the flux of the director field summed up and normalized over all lattice sites. .. note:: This is buggy! :return: Local alignment parameter: ranging from -1 (antiparallel alignment) through 0 (no alignment) to 1 (parallel alignment)

calc_normalized_entropy(base=None)

Calculate entropy of the lattice normalized to maximal possible entropy. :type base: :param base: base of the logarithm, defaults to 2 :return: normalized entropy as scalar

calc_permutations()

Initialize lazy computation structures for permutations. Only compute permutations when actually needed.

calc_polar_alignment_parameter()

Calculate the polar alignment parameter. The polar alignment parameter is a measure for global agreement of particle orientation in the lattice. It is calculated as the magnitude of the sum of the velocities of all particles normalized by the number of particles. :return: Polar alignment parameter of the lattice from 0 (no alignment) to 1 (complete alignment)

calc_prop_mean(nodes=None, props=None, propname=None)

Calculate the mean value of a property “propname” on every node, given the node configuration “nodes” and the properties “props”

calc_prop_mean_spatiotemp(nodes_t=None, props=None)

Given the lgca states nodes_t, calculate the mean of individual cell properties at each node for each time point. :type nodes_t: :param nodes_t: Recorded node states. If omitted, use recorded state of latest timeevo. :type props: :param props: dictionary of individual cell properties. If omitted, props dictionary of current instance is used :return:

channel_weight(qty)

Compute neighbour weights for interaction fields.

cix = array([-1., -1., -1., -1., -1., -1., -1., -1., -1.,  0.,  0.,  0.,  0.,         0.,  0.,  0.,  0.,  1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.])

ciy = array([-1., -1., -1.,  0.,  0.,  0.,  1.,  1.,  1., -1., -1., -1.,  0.,         0.,  1.,  1.,  1., -1., -1., -1.,  0.,  0.,  0.,  1.,  1.,  1.])

ciz = array([-1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1., -1.,         1., -1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1.])

static convert_bool_to_ib(conf)

Convert the booleans in the lattice configuration of a classical LGCA with volume exclusion into unique particle identifiers.

Parameters:

conf (numpy.ndarray) – Lattice configuration for a classical LGCA with volume exclusion.

Returns:

Node configuration of conf converted to an identity-based LGCA. Dimensions: conf.shape.

convert_int_to_ib(occ)

Convert an array of integers representing the occupation numbers of an lgca to an array consisting of lists of individual cell labels, starting at 0. The length of each list corresponds to the entry in ‘occ’. :type occ: :param occ: array of occupation numbers. must match the lgca dimensions :return: array, where each entry is a list of individual cell labels.

filter_family_population_t(fam_pop_t=None, cutoff_abs=None, cutoff_rel=None)

Mask out families from fam_pop_t that never exceeded the given population threshold.

Parameters:

• cutoff_abs (int) – Exclude families that never exceeded this population size in absolute numbers. cutoff_rel takes precedence over cutoff_abs.

• cutoff_rel (float) – Exclude families that never exceeded this population size, expressed as a fraction of the total population. cutoff_rel takes precedence over cutoff_abs.

• fam_pop_t (numpy.ndarray, default=``self.fam_pop_t``) – Each family’s population size over time, dimensions: (timesteps + 1, num_families + 1).

Returns:

fam_pop_t with all population values for too small families set to 0, dimensions: (timesteps + 1, num_families + 1). Original fam_pop_t if both cutoff parameters are None.

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.

get_prop(nodes=None, props=None, propname=None)

Return array of property “propname” on every node, given the lattice configuration “nodes” and the property dictionary “props”.

gradient(qty)

Return the spatial gradient of qty.

init_coords()

Initialize LGCA coordinates for a 3D cubic lattice.

init_families(type='homogeneous', mutation=True)

Initialize structures to track inheritance between cells and/or cell families.

Initializes the 'family' property in self.props and, if needed, the counter self.maxfamily and the dictionary self.family_props. The 'ancestor' and 'descendants' properties in the latter can be used to reconstruct a family tree.

Parameters:

• mutation (bool, default=True) – If true, mutation can occur so that offspring can have different properties and found its own family. The additional dictionary self.family_props and the counter self.maxfamily keep track of this. If false, the number of families is not supposed to increase during the simulation so that self.family_props and self.maxfamily are not needed.

• type ({'homogeneous', 'heterogeneous'}, default='homogeneous') – Family composition for the initial population. If homogeneous, all initial cells belong to the same family and have the same properties. If heterogeneous, each initial cell founds its own family and can have individual properties that it passes on to its offspring.

See also

add_family

Add a family to the family tree after a mutation has occurred.

muller_plot

Draw a Muller plot for a simulation timecourse.

init_nodes(density=0.1, nodes=None)

Initialize the lattice nodes for NoVE_IBLGCA.

list_families_alive()

Calculate which families are alive. :returns: np.ndarray - array of family IDs in ascending order

live_animate_density(**kwargs)

Live plot a 3D density surface based on a specified threshold using Mayavi.

Parameters:

• threshold (float, default=0.5) – Density threshold for surface plotting.

• colormap (str, default='viridis') – Colormap for the surface.

• opacity (float, default=0.5) – Opacity of the surface.

• **kwargs – Additional arguments passed to mlab.contour3d.

Returns:

live_animate_flux(scale_factor=1.0, opacity=0.5, cbar=False, **kwargs)

Live plot the flux vectors in the 3D lattice using Mayavi.

This method updates the plot in real-time as the simulation progresses.

Parameters:

• scale_factor (float, default=1.0) – Scaling factor for the arrows.

• opacity (float, default=0.6) – Opacity of the flux vectors.

• **kwargs – Additional arguments passed to mlab.quiver3d.

Returns:

Mayavi quiver3d object.

muller_plot(t_start_index=None, t_slice=slice(None, None, None), prop=None, cutoff_abs=None, cutoff_rel=None, **kwargs)

Draw a Muller plot from the LGCA simulation data (runtime, family tree, recorded family populations).

Parameters:

• cutoff_abs (int) – Exclude families that never exceeded this population size in absolute numbers. cutoff_rel takes precedence over cutoff_abs.

• cutoff_rel (float) – Exclude families that never exceeded this population size, expressed as a fraction of the total population. cutoff_rel takes precedence over cutoff_abs.

• prop (hashable type, key of the dictionary self.family_props) – Colour the area for each family according to this family property. If None, colour area according to family identity.

• t_slice (slice) – Which parts of the simulation time to consider for the plot.

• t_start_index (int) – First number to appear on the x axis (time).

• **kwargs – Keyword arguments to further style the plot drawn by lgca.plots.muller_plot().

Returns:

• fig (matplotlib.figure.Figure) – Matplotlib figure handle.

• ax (matplotlib.axes.Axes) – Muller plot axis handle.

• (ret) – Handle of legend, handle of colourbar or None. The separate colourbar axis handle can be retrieved as ret.ax.

nb_sum(qty)

Sum values of qty in the 26-neighbourhood of each node.

num_families_alive()

Calculate how many families are alive.

Returns:

Number of families alive.

num_families_alive_t(cutoff_abs=None, cutoff_rel=None)

Calculate how many families have been alive at each simulation step. Requires a previous self.timeevo() with recordfampop=True.

Parameters:

• cutoff_abs (int) – Exclude families that never exceeded this population size in absolute numbers. cutoff_rel takes precedence over cutoff_abs.

• cutoff_rel (float) – Exclude families that never exceeded this population size, expressed as a fraction of the total population. cutoff_rel takes precedence over cutoff_abs.

Returns:

Number of families at each timestep, dimensions: timesteps+1.

num_families_total()

Calculate how many families there are in total, including extinct ones.

Returns:

Number of families.

num_families_total_t(cutoff_abs=None, cutoff_rel=None)

Calculate how many families there are in total at each timestep, including extinct ones.

Parameters:

• cutoff_abs (int) – Exclude families that never exceeded this population size in absolute numbers. cutoff_rel takes precedence over cutoff_abs.

• cutoff_rel (float) – Exclude families that never exceeded this population size, expressed as a fraction of the total population. cutoff_rel takes precedence over cutoff_abs.

Returns:

Number of families at each timestep, dimensions: timesteps+1.

plot_config(nodes=None, **kwargs)

Plot the configuration of the NoVE_IBLGCA_Cubic model.

plot_density(density=None, **kwargs)

Plot the density of the NoVE_IBLGCA_Cubic model.

plot_density_cubes(density=None, colormap='viridis', opacity=0.5, cbar=True, **kwargs)

Plot a 3D surface based on the local density using a specified threshold using Mayavi.

Parameters:

• threshold (float, default=0.5) – Density threshold for surface plotting.

• colormap (str, default='viridis') – Colormap for the surface.

• opacity (float, default=0.5) – Opacity of the surface.

• **kwargs – Additional arguments passed to mlab.contour3d.

Returns:

Mayavi contour3d object.

plot_flux(nodes=None, **kwargs)

Plot the flux of the NoVE_IBLGCA_Cubic model.

plot_prop_2dhist(nodes=None, props=None, propnames=None, figindex=None, figsize=None, **kwargs)

Plot a 2d-histogram of two cell properties given by ‘propnames’ of all cells in ‘nodes’. By default, the current lgca state is used and the first two properties are shown. :type nodes: :param nodes: :type props: :param props: :type propnames: :param propnames: :type figindex: :param figindex: :type figsize: :param figsize: :type kwargs: :param kwargs: :return:

plot_prop_hist(nodes=None, props=None, propname=None, figindex=None, figsize=None, **kwargs)

Plot histogram of cell property ‘propname’ of cells in ‘nodes’. Per default, the current lgca state and the first property is shown. :type nodes: :param nodes: :type props: :param props: :type propname: :param propname: :type figindex: :param figindex: :type figsize: :param figsize: :type kwargs: :param kwargs: :return:

plot_prop_timecourse(nodes_t=None, props=None, propname=None, figindex=None, figsize=None, **kwargs)

Plot the time evolution of the cell property ‘propname’ :type nodes_t: :param nodes_t: :type props: :param props: :type propname: :param propname: :type figindex: :param figindex: :type figsize: :param figsize: :type kwargs: :param kwargs: keyword arguments for the matplotlib.plot command :return:

plot_scalarfield(field, mask=None, colormap='viridis', opacity=0.5, cbar=True, cbarlabel='Scalar field', vmin=None, vmax=None, **kwargs)

Plot a 3D scalar field using Mayavi. Parameters ———- field mask colormap opacity cbar kwargs

Returns:

print_interactions()

Print the list of pre-implemented interactions for this LGCA type.

print_nodes()

Print the full lattice configuration as integers.

propagate_ancestor_to_descendants()

Traverse family tree to find the families that were initialised in the beginning of the simulation (“initial ancestors”) and which families descend from them, including the 2nd, 3rd, … generations.

Returns:

Initial ancestors indexed by family ID. The helper root family and initial ancestors have 0, all others their ancestor’s family ID.

propagate_family_prop_to_cells(prop)

Propagate a family property down to all cells that belong to the family. Uses contents of self.family_props[prop] to create a new cell property self.props[prop]

Parameters:

prop (str) – Key of the family property in self.family_props[prop].

static propagate_pop_to_parents(pop_t, ancestor)

Propagate family population in pop_t to all ancestors recorded in ancestor.

Parameters:

• pop_t (numpy.ndarray) – Population of each family for all timesteps, dimensions: (timesteps, num_families).

• ancestor (list) – Record of each family’s parent (initially existing families have 0), length: num_families + 1.

Returns:

Family populations over time summed up to all ancestors recursively, cum_pop_t[:, 0] holds total population over time.

See also

muller_plot

Draw a Muller plot for a simulation timecourse.

propagation()

Move object-list particles through all 26 Moore velocity channels.

random_reset(density)

Populate the lattice from a Poisson distribution with mean density per node.

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).

set_dims(dims=None, nodes=None, restchannels=0, capacity=None)

Set LGCA dimensions.

Initializes self.K, self.restchannels, self.dims, self.lx, self.ly, and self.lz.

Parameters:

• dims (tuple of int, default=(10, 10, 10)) – Lattice dimensions. Must match with specified geometry.

• nodes (numpy.ndarray) – Custom initial lattice configuration.

• restchannels (int, default=0) – Number of resting channels.

See also

init_nodes

Initialize LGCA lattice configuration.

init_coords

Initialize LGCA coordinates.

set_interaction(**kwargs)

Set the interaction rule and respective needed parameters.

Set self.interaction and possibly add entries in self.interaction_params and self.props. If inheritance is involved, initialize self.family_props and self.maxfamily. 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, recordchanneldens=False, showprogress=True, recordfampop=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.

• recordfampop (bool, default=False) – Record the population of all families for each timestep in self.fam_pop_t.

• recordN (bool, default=False) – Record the total number of particles in the lattice for each timestep in self.n_t.

• 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.

total_population_t(cutoff_abs=None, cutoff_rel=None)

Calculate the total population of cells at each simulation step. Requires a previous self.timeevo() with recordfampop=True due to the filtering option.

Parameters:

• cutoff_abs (int) – Exclude families that never exceeded this population size in absolute numbers. cutoff_rel takes precedence over cutoff_abs.

• cutoff_rel (float) – Exclude families that never exceeded this population size, expressed as a fraction of the total population. cutoff_rel takes precedence over cutoff_abs.

Returns:

Number of cells at each timestep, dimensions: timesteps+1.

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.