lattics package

Subpackages

• lattics.tests package
  • Submodules
  • lattics.tests.conftest module
  • lattics.tests.test_agent_functions module
    • test_default_instantiation()
    • test_status_flag_initialization_get_set_bool()
    • test_status_flag_initialization_get_set_str()
  • lattics.tests.test_cell_function_models module
  • lattics.tests.test_simulation_fundamentals module
    • test_agent_addition_no_space()
    • test_agent_addition_no_space_gives_warning()
    • test_agent_removal_no_space()
    • test_default_instantiation()
    • test_simulation_run_elapsed_time()
  • Module contents

Submodules

lattics.agent module

Basic unit of the LattiCS framework representing a single biological cell.

class lattics.agent.Agent(simulation: simulation.Simulation = None)

Bases: object

add_model(model: cellfunction.CellFunctionModel) → None

Adds the provided model instance to the agent’s collection of cell function models and invokes the model’s initialization method.

Parameters:

modelCellFunctionModel

A subclass of the CellFunctionModel abstract base class.

clone() → Agent

Returns a deep copy instance of the agent.

Returns:

Agent

The cloned agent instance

get_attribute(name: str) → Any

Returns the value of the specified attribute.

Parameters:

namestr

The identifier of the attribute

Returns:

any type

The current value of the attribute

Raises:

ValueError

If the specified attribute does not exist

Examples

>>> a.initialize_attribute('my_attribute', 0)
>>> print(a.get_attribute(''my_attribute''))
0

has_attribute(name: str) → bool

Returns whether the agent instance has a specific attribute initialized.

Parameters:

namestr

The identifier of the attribute

Returns:

bool

True if the agent has the attribute, otherwise false

Examples

>>> a.initialize_attribute('my_attribute')
>>> a.has_attribute('my_attribute')
True
>>> a.has_attribute('nonexisting_attribute')
False

initialize_attribute(name: str, value: Any = None) → None

Initialize a new attribute for the agent instance with the specified name.

Parameters:

namestr

The identifier of the status flag

valueAny, optional

The initial value to be set, by default None

Examples

>>> a = Agent()
>>> a.initialize_attribute('my_attribute_1')
>>> a.initialize_attribute('my_attribute_2', 0)
>>> a.initialize_attribute('my_attribute_3', 'foo')

set_attribute(name: str, value: Any) → None

Set the value of the specified attribute.

Parameters:

namestr

The identifier of the attribute

valueAny

The new value to be set

Raises:

ValueError

If the specified attribute does not exist

Examples

>>> a.initialize_attribute('my_attribute')
>>> a.set_attribute('my_attribute', True)

property simulation: simulation.Simulation

Get the simulation instance associated with the agent.

Returns:

Simulation

An instance representing the simulation

update_models(dt: int) → None

Sequentially updates all models associated with the agent. If multiple sub-models exist within the same category, they are updated in the order they appear in their respective collection.

Parameters:

dtint

The time elapsed since the last update, in milliseconds

lattics.cellfunctions module

class lattics.cellfunctions.CellFunctionModel(agent: Agent, update_interval: int)

Bases: object

Acts as a base class for all cellular function models, such as metabolism, cell cycle regulation, and other regulatory processes.

initialize_agent_attributes() → None

Initializes the attributes required for the model.

set_agent(agent: Agent) → None

Sets the model’s reference to the Agent to which it is attached.

Parameters:

agentAgent

The containing agent

set_update_interval(update_interval: int) → None

Sets the time interval that passes between two update steps.

Parameters:

update_intervalint

Time between two update steps, in milliseconds

update(dt: int) → None

Determines whether an update step is needed based on the time elapsed since the last update. If the elapsed time meets or exceeds the update_interval parameter, the update is performed.

Parameters:

dtint

The time elapsed since the last update call, in milliseconds

class lattics.cellfunctions.FixedIncrementalCellCycle(agent: Agent, update_interval: int, length: int, initial_time: int = 0, random_initial: bool = False)

Bases: CellFunctionModel

A cell function model that implements a simple fixed-length cell cycle. When the internal time counter reaches the specified length, the agent is marked as division_pending. If the simulation environment handles the division and sets the agent’s status to division_completed, the internal time counter resets, and the cell cycle begins again.

property current_time: int

Get the current internal time of the model, which represents the elapsed time since the last division.

Returns:

int

Current internal time, in milliseconds

initialize_agent_attributes() → None

Initializes the attributes required for the model. The model uses two attributes: division_pending and division_completed. For a detailed description, refer to the FixedIncrementalCellCycle documentation.

lattics.domains module

class lattics.domains.SimulationDomain(simulation: Simulation)

Bases: object

Base class for different simulation domains.

add_agent(agent: Agent, **kwargs) → None

Adds the specified agent to the structure representing the internal storage of the domain.

Parameters:

agentAgent

The agent to be added

initialize() → None

Initializes the domain.

remove_agent(agent: Agent) → None

Removes the specified agent from the internal storage of the domain.

Parameters:

agentAgent

The agent to be removed

update(dt: int) → None

Updates the domain according to the specified time duration.

Parameters:

dtint

The time elapsed since the last update call, in milliseconds

class lattics.domains.Structured2DSimulationDomain(simulation: Simulation, dimensions: tuple[int, int])

Bases: SimulationDomain

add_agent(agent: Agent, position: tuple[int, int], motility: int = 0, binding_affinity: int = 0, displacement_limit: int = 1) → None

Adds the specified agent to the specified index of the internal array of the agents.

Parameters:

agentAgent

The agent to be added

positiontuple[int, int]

The column and row index describing the agent’s position

motilityint, optional

Characteristic velocity of the agent, expressed in micrometers per millisecond, by default 0

binding_affinityint, optional

Scale factor that determines the binding strength between the agent and other agents, by default 0

Raises:

ValueError

If the position of the agent is out of the bounds of the domain

initialize() → None

Initializes the domain.

initialize_agent_attributes(agent) → None

Initializes the attributes used by the domain. The domain uses the following attributes: division_pending, division_completed, motility, binding_affinity, and displacement_limit. Agents are displaced to adjacent grid points based on their motility and binding_affinity values. Agents labeled as division_pending are duplicated depending on the number of available grid points and the displacement_limit, which specifies how far an agent can push others to create space for a daughter cell. Once division has occurred, the division_completed attribute is set to True.

is_empty_position(position: tuple[int, int]) → bool

Indicates whether the specified lattice point is unoccupied (i.e., not containing any agent instance).

Parameters:

positiontuple[int, int]

The column and row index describing the position

Returns:

bool

True if the lattice point is empty, False otherwise

is_valid_position(position: tuple[int, int]) → bool

Indicates whether the given position lies within the bounds of the domain.

Parameters:

positiontuple[int, int]

The column and row index describing the position

Returns:

bool

True if the position exists within the domain, False otherwise

remove_agent(agent: Agent) → None

Removes the specified agent from the internal list of the agents.

Parameters:

agentAgent

The agent to be removed

update(dt: int) → None

Updates the domain according to the specified time duration.

Parameters:

dtint

The time elapsed since the last update call, in milliseconds

class lattics.domains.UnstructuredSimulationDomain(simulation: Simulation, capacity: int = None)

Bases: SimulationDomain

Represents a perfectly mixed simulation domain with no spatial structure or localized interactions, where each agent has an equal probability of interacting with any other agent in the population. Agents are stored in a list.

add_agent(agent: Agent, **kwargs) → None

Adds the specified agent to the internal list of the agents.

Parameters:

agentAgent

The agent to be added

initialize() → None

Initializes the domain.

initialize_agent_attributes(agent) → None

Initializes the attributes used by the domain. The domain tracks two attributes: division_pending and division_completed. The division_pending attribute can be set by cell-level functions to indicate that an agent is ready to divide and that the domain should handle the division event. Once division has occurred, the division_completed attribute is set to True.

remove_agent(agent: Agent) → None

Removes the specified agent from the internal list of the agents.

Parameters:

agentAgent

The agent to be removed

update(dt: int) → None

Updates the domain according to the specified time duration. Agents labeled as division_pending are duplicated based on the available space in the domain, constrained by capacity.

Parameters:

dtint

The time elapsed since the last update call, in milliseconds

lattics.numba_functions module

lattics.numba_functions.apply_neumann_bc_2d(array)

lattics.numba_functions.bresenham_2d(x1, y1, x2, y2)

lattics.numba_functions.diffusion_solver_ftcs_2d(C, D, d, dt, dx)

lattics.numba_functions.diffusion_solver_lod_2d(C, D, d, dt, h)

lattics.numba_functions.diffusion_solver_lod_3d(C, D, d, dt, h)

lattics.numba_functions.displace_agent_2d(positions, idx, new_position, agent_idx_array)

lattics.numba_functions.displacement_trial_2d(idx, positions, binding_affs, agent_idx_array, change_flags)

Performs a displacement trial with a given agent assuming 2D coordinates.

Args:

idx (int): positions (array of ints): 2D array of the positions of all agents binding_affs (array of float): the binding affinities of all agents agent_idx_array (2D array of ints): identifiers (indexes) of the agents

based on their positions

change_flags (array of bools): indicating whether an agent was

relocated during the trial

lattics.numba_functions.get_neighborhood_2d(type)

lattics.numba_functions.get_neighborhood_3d(type)

lattics.numba_functions.pairwise_interaction_energy_2d(position_one, bindig_aff_one, position_two, binding_aff_two)

Computes pairwise interaction energies of two agents.

Args:

position_one (array of ints): the coordinates of agent one bindig_aff_one (float): the binding affinity of agent one position_two (array of ints): the coordinates of agent two binding_aff_two (float): the binding affinity of agent two

Returns:

float: the interaction energy

lattics.numba_functions.total_interaction_energy_2d(idx, agent_pos, bind_affs, agent_idx_array)

Computes the sum of pairwise interaction energies of a given agent.

Args:

idx (int): identifier (index) of the selected agent agent_pos (array of ints): the position of the selected agent bind_affs (array of floats): 1D array of agent binding affinities agent_idx_array (array of ints): 2D array containing identifiers (indexes)

of the agents based on their positions

Returns:

float: the total interaction energy of the agent

lattics.numba_functions.tridiag_solver(sub, diag, sup, const)

lattics.simulation module

The main component of the LattiCS framework containing functionalities to set up and execute a simulation.

class lattics.simulation.Simulation(id=None)

Bases: object

Represents a simulation instance. This object manages the participating agents (Agent), the environment (SimulationDomain), and the various chemical substances (Substrate) present within it. The class provides high-level access to configure and execute a simulation.

add_agent(agent: Agent, **kwargs) → None

Adds the specified agent to the simulation. The agent will be added to the collection of all agents and, if a simulation domain is defined, will also be placed within the simulation domain.

Parameters:

agentAgent

The agent to be added

add_simulation_domain(domain: domains.SimulationDomain) → None

Sets the simulation domain to the instance passed as a parameter.

Parameters:

domainSimulationDomain

The simulation domain instance to be used

property agents: list[Agent]

Get the collection of agents currently present in the simulation. The order of agents in this collection is maintained throughout the simulation, with new agent instances always being added at the end.

Returns:

list[Agent]

Collection of the agents

remove_agent(agent: Agent) → None

Removes the specified agent from the simulation. The agent will be removed from the collection of all agents and, if applicable, will also be removed from the simulation domain.

Parameters:

agentAgent

The agent to be removed

run(time, dt) → None

Runs the simulation from the current state for the specified duration using the given time step.

Parameters:

timeint

The duration to be simulated, in milliseconds

dt_type_

Time step, in milliseconds

property time: int

Get the current internal time of the simulation, representing the elapsed time since the simulation started.

Returns:

int

Internal time of the simulation, in milliseconds.

Module contents