Built-in interactions

Interactions define the local update applied before propagation. Built-in interactions are selected with the interaction keyword when constructing a simulator with lgca.get_lgca(). The valid names depend on the selected model family.

Supported names by family

Model family	Interaction names
Classical LGCA with volume exclusion	go_and_grow, go_or_grow, alignment, aggregation, random_walk, persistent_motion, birthdeath, excitable_medium (2D/3D), nematic (2D/3D), chemotaxis (2D/3D), contact_guidance (2D), only_propagation
Identity-based LGCA with volume exclusion	go_or_grow, go_and_grow, random_walk, birth, birthdeath, birthdeath_discrete, go_and_grow_mutations (most geometries), only_propagation
Classical LGCA without volume exclusion	dd_alignment, di_alignment, go_or_grow, go_or_rest
Identity-based LGCA without volume exclusion	go_or_grow, go_or_grow_kappa, go_or_grow_glioblastoma, birth, birthdeath, birthdeath_cancerdfe, random_walk, randomwalk, steric_evolution
Multi-species LGCA	Classical interaction names plus excitable_medium_ms for volume-exclusion multi-species models

Use lgca.print_interactions() on an initialized simulator to inspect the exact list for that class.

Classical LGCA

Interaction functions and helper functions for classical LGCA with volume exclusion.

lgca.interactions.aggregation(lgca)

Bias movement towards higher cell density.

Parameters:

• lgca (LGCA) – Lattice gas cellular automaton instance.

• beta (float) – Strength of the bias toward higher density regions.

Returns:

Notes

The lgca object is modified in place.

lgca.interactions.alignment(lgca)

Align moving cells with their neighbours.

Parameters:

• lgca (LGCA) – Lattice gas cellular automaton instance.

• beta (float) – Alignment strength with neighbouring velocities.

Returns:

Notes

The lgca object is modified in place.

lgca.interactions.birth(lgca)

Perform a simple birth step followed by a random walk.

Parameters:

• lgca (LGCA) – Lattice gas cellular automaton instance.

• r_b (float) – Birth probability per empty channel; effective probability is r_b * n / lgca.K for local density n.

Returns:

Notes

The lgca object is modified in place.

lgca.interactions.birthdeath(lgca)

Perform a birth–death step followed by a random walk.

Parameters:

• lgca (LGCA) – Lattice gas cellular automaton instance.

• r_b (float) – Birth probability per empty channel.

• r_d (float) – Death probability per occupied channel.

Returns:

Notes

The lgca object is modified in place.

lgca.interactions.chemotaxis(lgca)

Rearrange nodes in response to an external gradient.

Parameters:

• lgca (LGCA) – Lattice gas cellular automaton instance.

• beta (float) – Strength of the bias toward the gradient.

• gradient_field (numpy.ndarray) – External gradient field influencing motion.

Returns:

Notes

The lgca object is modified in place.

lgca.interactions.contact_guidance(lgca)

Align cells with a predefined guiding axis.

Parameters:

• lgca (LGCA) – Lattice gas cellular automaton instance.

• beta (float) – Alignment strength toward the guiding axis.

Returns:

Notes

The lgca object is modified in place.

lgca.interactions.disarrange(a, axis=-1)

Shuffle a in-place along the given axis.

Apply numpy.random.shuffle to the given axis of a. Each one-dimensional slice is shuffled independently.

THIS IS A LEGACY FUNCTION, USE THE RANDOM WALK FUNCTION INSTEAD FOR A MORE EFFICIENT IMPLEMENTATION!

Parameters:

• a (ndarray) – The array to shuffle

• axis (int, optional, default: -1) – Along which axis to shuffle a. The default is -1, which implies the last axis.

lgca.interactions.excitable_medium(lgca)

Simulate an excitable medium following Barkley’s model.

Parameters:

• lgca (LGCA) – Lattice gas cellular automaton instance.

• alpha (float) – Controls the excitability of the medium.

• beta (float) – Interaction coefficient between species.

• N (int) – Number of sub-steps performed in each interaction.

Returns:

Notes

The lgca object is modified in place.

lgca.interactions.go_or_grow(lgca)

Perform the go-or-grow switching interaction.

Parameters:

• lgca (LGCA) – Lattice gas cellular automaton instance.

• r_b (float # This parameter is not used in the provided snippet for go_or_grow, but kept for consistency if it)

• intended. (was) – Birth probability for resting cells.

• r_d (float # This parameter is not used in the provided snippet for go_or_grow) – Death probability for both states.

• beta (float # Renamed from kappa in some contexts, this is the sensitivity for switching) – Steepness of the switching function / sensitivity to entropy change.

• theta (float # This parameter is not used here, tanh_switch is not directly called for entropy part) – Threshold density for switching.

Notes

The lgca object is modified in place. This version attempts to use the entropy-based switching logic. Assumes lgca.velocitychannels and lgca.restchannels are defined. Uses a placeholder _s_binom_entropy_like for the undefined s_binom.

lgca.interactions.go_or_rest(lgca)

Switch cells between moving and resting states based on local density. Uses tanh_switch function. Assumes lgca.nodes is (K, dims…). No birth or death in this version.

lgca.interactions.nematic(lgca)

Implement nematic alignment of neighbouring cells.

Parameters:

• lgca (LGCA) – Lattice gas cellular automaton instance.

• beta (float) – Strength of nematic alignment.

Returns:

Notes

The lgca object is modified in place.

lgca.interactions.only_propagation(lgca)

Placeholder interaction that performs no rearrangement.

Parameters:

lgca (LGCA) – Lattice gas cellular automaton instance.

Returns:

Notes

The lgca object is modified in place but remains unchanged. This interaction does not use lgca.interaction_params.

lgca.interactions.persistent_walk(lgca)

Rearrange nodes to implement persistent motion. Vectorized implementation. See also: alignment. This is a special case of alignment where the interaction radius is 0.

Parameters:

• lgca (LGCA) – Lattice gas cellular automaton instance.

• beta (float) – Strength of alignment with the previous velocity direction.

Returns:

Notes

The lgca object is modified in place.

lgca.interactions.random_walk(lgca)

Apply a random walk to all nodes.

Parameters:

lgca (LGCA) – Lattice gas cellular automaton instance.

Returns:

Notes

The lgca object is modified in place. This interaction does not use lgca.interaction_params.

lgca.interactions.wetting(lgca)

Model wetting dynamics on an adhesive surface.

Parameters:

• lgca (LGCA) – Lattice gas cellular automaton instance.

• r_b (float) – Birth probability used inside the spheroid region.

• rho_0 (float) – Homeostatic density determining the pressure gradient.

• alpha (float) – ECM degradation rate.

• beta (float) – Adhesion strength weighting flux alignment.

• gamma (float) – Strength of the pressure gradient term.

Returns:

Notes

The lgca object is modified in place.

Identity-based LGCA

Interaction functions and helper functions for identity-based LGCA with volume exclusion.

lgca.ib_interactions.birth(lgca)

Create daughter cells according to individual proliferation rates.

Parameters:

lgca (BaseLGCA) – LGCA object to update.

Notes

lgca.nodes and lgca.props['r_b'] are changed in place. The proliferation rate of each daughter cell is drawn from trunc_gauss() with limits 0 and interaction_params['a_max'] and width interaction_params['std'].

lgca.ib_interactions.birthdeath(lgca)

Birth-death dynamics with mutating proliferation rates.

Cells die with probability interaction_params['r_d']. Surviving cells proliferate according to their individual r_b. The proliferation rate of newborns is drawn from trunc_gauss(). If interaction_params['track_inheritance'] is True the family index of the mother cell is copied to the daughter.

Parameters:

lgca (BaseLGCA) – LGCA object being modified.

Notes

lgca and its property lists are altered in place.

lgca.ib_interactions.birthdeath_discrete(lgca)

Birth-death process with discrete proliferation-rate mutations.

Offspring may mutate their r_b by pm interaction_params['drb'] with probability interaction_params['pmut'] while values are capped by interaction_params['a_max'].

Parameters:

lgca (BaseLGCA) – LGCA object being updated.

Notes

Operates in place on lgca.

lgca.ib_interactions.go_and_grow_mutations(lgca)

Birth-death dynamics with explicit family tracking and mutations.

Cells die with probability interaction_params['r_d']. Proliferation rates are either constant or family dependent depending on interaction_params['effect'] ('passenger_mutation' or 'driver_mutation'). With probability interaction_params['r_m'] a dividing cell founds a new family. In the driver case the new family’s r_b is multiplied by interaction_params['fitness_increase'].

Parameters:

lgca (BaseLGCA) – LGCA instance that will be updated.

Notes

The LGCA object and its property lists are modified in place.

lgca.ib_interactions.go_or_grow(lgca)

Implement the go-or-grow interaction scheme.

Cells stochastically switch between moving and resting states based on the local density and their parameters kappa and theta. Resting cells can proliferate with probability interaction_params['r_b']. The parameters kappa_std and theta_std determine the variance of these traits inherited by daughter cells.

Parameters:

lgca (BaseLGCA) – LGCA object to operate on.

Notes

The LGCA is updated in place.

lgca.ib_interactions.random_walk(lgca)

Shuffle particles between channels to mimic diffusion.

Parameters:

lgca (BaseLGCA) – LGCA object whose nodes array will be permuted.

Notes

lgca is modified in place.

lgca.ib_interactions.trunc_gauss(lower, upper, mu, sigma=0.1, size=1, rng=None)

Draw samples from a truncated normal distribution.

Parameters:

• lower (float) – Lower truncation limit.

• upper (float) – Upper truncation limit.

• mu (float) – Mean of the underlying distribution.

• sigma (float, default=0.1) – Standard deviation of the distribution.

• size (int, default=1) – Number of samples to draw.

Returns:

float if size equals 1 or an array of samples otherwise.

LGCA without volume exclusion

Interaction functions and helper functions for LGCA without volume exclusion.

lgca.nove_interactions.dd_alignment(lgca)

Density dependent alignment of particle directions.

The local director field is obtained from the flux of all neighboring nodes (including the central node if nb_include_center is set). Particles in each occupied node are then reoriented according to exp(beta * dot(g, c_i)) where g is the director field and c_i are the velocity vectors.

Parameters:

lgca (LGCA_1D, LGCA_Square, LGCA_Hex, or LGCA_Cubic) – LGCA instance that the interaction is applied to. The lattice may be one-, two-, or three-dimensional. Requires the beta and nb_include_center entries in lgca.interaction_params.

Notes

lgca.nodes is replaced by the sampled configuration.

lgca.nove_interactions.di_alignment(lgca)

Density independent alignment of particle directions.

Similar to dd_alignment(), but the director field is normalized by the number of neighbors so that the reorientation does not depend on local density.

Parameters:

lgca (LGCA_1D, LGCA_Square, LGCA_Hex, or LGCA_Cubic) – LGCA instance that the interaction is applied to. The lattice may be one-, two-, or three-dimensional. Requires the beta and nb_include_center entries in lgca.interaction_params.

Notes

lgca.nodes is replaced by the sampled configuration.

lgca.nove_interactions.go_or_grow(lgca)

Interaction step of the go-or-grow model without volume exclusion.

Cells switch between moving and resting states depending on the local density. Resting cells may proliferate and both phenotypes can die. After the switch and birth/death events, moving cells are reoriented uniformly among the velocity channels.

Parameters:

lgca (LGCA_1D, LGCA_Square, LGCA_Hex, or LGCA_Cubic) – LGCA instance that the interaction is applied to. The lattice may be one-, two-, or three-dimensional. The following keys in lgca.interaction_params are used: kappa, theta, r_b and r_d.

Notes

lgca.nodes is overwritten with the updated node configuration.

lgca.nove_interactions.go_or_rest(lgca)

Simplified go-or-grow interaction without birth and death.

Only the switching between moving and resting states and the reorientation of moving cells are performed.

Parameters:

lgca (LGCA_1D, LGCA_Square, LGCA_Hex, or LGCA_Cubic) – LGCA instance that the interaction is applied to. The lattice may be one-, two-, or three-dimensional. Uses the kappa and theta values from lgca.interaction_params.

Notes

lgca.nodes is overwritten with the updated node configuration.

lgca.nove_interactions.random_walk(lgca)

Perform a random walk rearrangement on the lattice.

All particles of every occupied lattice site are redistributed uniformly over the velocity channels.

Parameters:

lgca (LGCA_1D, LGCA_Square, LGCA_Hex, or LGCA_Cubic) – LGCA instance that the interaction is applied to. The lattice may be one-, two-, or three-dimensional.

Notes

lgca.nodes is overwritten with the new lattice configuration. No other attributes are updated.

Identity-based LGCA without volume exclusion

Interaction functions and helper functions for identity-based LGCA without volume exclusion.

lgca.nove_ib_interactions.birth(lgca)

Logistic birth process with inheritable proliferation rates.

Each cell divides with probability r_b scaled by the available capacity. The proliferation rate of each daughter cell is drawn from a truncated Gaussian distribution centred at the mother’s rate.

Parameters:

lgca (object) – Lattice-gas cellular automaton that will be modified in-place.

Returns:

lgca.nove_ib_interactions.birthdeath(lgca)

Birth and death step with heterogenous proliferation rates.

Cells divide according to their individual birth rate and the available capacity, while every cell dies with probability r_d. The proliferation rate of each daughter cell is drawn from a truncated Gaussian distribution around the mother’s rate.

Parameters:

lgca (object) – Lattice-gas cellular automaton that will be modified in-place.

Returns:

lgca.nove_ib_interactions.birthdeath_cancerdfe(lgca)

Birth–death step with driver and passenger mutations.

Proliferation follows a logistic law and death occurs with probability r_d. Daughter cells inherit the mother’s birth rate plus a deviation drawn from exponential distributions representing driver (beneficial) or passenger (deleterious) mutations.

Parameters:

lgca (object) – Lattice-gas cellular automaton that will be modified in-place.

Returns:

lgca.nove_ib_interactions.evo_steric(lgca)

Birth–death dynamics with mutations and steric movement.

Cells proliferate with their individual birth rates following a logistic growth law limited by capacity and die with probability r_d. During proliferation mutations may occur which modify the proliferation rate. After the birth–death step cells redistribute among velocity channels according to steric interactions controlled by alpha and gamma.

Parameters:

lgca (object) – Lattice-gas cellular automaton that will be modified in-place.

Returns:

lgca.nove_ib_interactions.go_or_grow(lgca)

Evolutionary go-or-grow interaction.

Cells stochastically switch between a migratory and a resting phenotype according to a sigmoidal function of the local density (tanh_switch) with individual parameters kappa and theta. Resting cells proliferate with a constant rate r_b and all cells die with rate r_d. Offspring inherit the mother’s switching parameters with Gaussian noise.

Parameters:

lgca (object) – Lattice-gas cellular automaton that will be modified in-place.

Returns:

lgca.nove_ib_interactions.go_or_grow_glioblastoma(lgca)

Clone-level go-or-grow dynamics for glioblastoma evolution.

Cells switch between migratory and resting phenotypes according to the local neighbourhood density. Resting cells proliferate with a birth rate stored on their family, and driver mutations found new families with increased birth rate and inherited switch sensitivity.

Parameters:

lgca (object) – Lattice-gas cellular automaton that will be modified in-place.

Returns:

lgca.nove_ib_interactions.go_or_grow_kappa(lgca)

Go-or-grow interaction using neighbourhood density.

Phenotype switching is determined by the average density in the Moore neighbourhood rather than only the local density. Only the slope parameter kappa evolves, whereas the threshold theta is fixed globally.

Parameters:

lgca (object) – Lattice-gas cellular automaton that will be modified in-place.

Returns:

lgca.nove_ib_interactions.go_or_grow_kappa_chemo(lgca)

Go-or-grow interaction with chemotactic movement.

Switching dynamics are identical to go_or_grow_kappa(), but migrating cells move preferentially along the density gradient according to a Boltzmann weight with parameter beta.

Parameters:

lgca (object) – Lattice-gas cellular automaton that will be modified in-place.

Returns:

lgca.nove_ib_interactions.random_walk(lgca)

Move cells by uniformly redistributing them among velocity channels.

Parameters:

lgca (object) – Lattice-gas cellular automaton that is modified in-place.

Returns:

lgca.nove_ib_interactions.tanh_switch(rho, kappa=5.0, theta=0.8)

Sigmoidal switching function.

Parameters:

• rho (float or numpy.ndarray) – Local (or neighbourhood) density.

• kappa (float, optional) – Steepness of the transition. Default is 5.0.

• theta (float, optional) – Density threshold at which the switch probability is 0.5. Default is 0.8.

Returns:

Switching probability with the same shape as rho.

lgca.nove_ib_interactions.trunc_gauss(lower, upper, mu, sigma=0.1, size=1, rng=None)

Draw samples from a truncated normal distribution.

Parameters:

• lower (float) – Lower bound of the distribution.

• upper (float) – Upper bound of the distribution.

• mu (float) – Mean of the underlying normal distribution.

• sigma (float, optional) – Standard deviation of the underlying normal distribution. 0.1 by default.

• size (int, optional) – Number of samples to draw. 1 by default.

Returns:

If size equals 1 a single float is returned, otherwise an array of shape (size,) with the drawn samples.

Multi-species LGCA

Interaction rules for classical multi-species LGCA.

lgca.ms_interactions.excitable_medium_ms(lgca)

Excitable medium for two species.

Species 0 remains in its rest channels while species 1 undergoes a birth–death reaction followed by a random walk.

Custom interactions

Placeholder. Interaction callables receive the LGCA instance and mutate lgca.nodes or related state. Detailed guidance for custom interaction registration, parameter validation and dynamic-field updates is still planned.