Simulation (Package) - singa-bio/singa GitHub Wiki

The Simulation package implements a strategy to model and simulate natural processes with spatial and temporal resolution. Based on the neighbourhood relations in graphs graphs and complex interactions in cellular automata, the strategy uses reccurence relations to simulate models of cellular scale. Natural phenomena such as diffusion, chemical reactions and membrane transport are encapsulated into modules that apply updates to the system. This bottom-up approach aims to entangle mechanistic models of basic phenomena to produce emergent behaviour observable on a higher scale.

Introduction to Cellular Graph Automata

The basis of Cellular Graph Automata (CGA) are classical cellular automata (CA). In CA the simulation space is subdivided into cells, by a static regular tiling and each of the cells is assigned a state. Depending on the definition of the neighbourhood, a state transition function is applied in each time step. Depending on the states of the adjacent cells, the new state of a cell devised.

images/ca_state_transition.png

The first step to get from cellular automata to graph automata is to replace the tiling based neighbourhood relation with a graph based one.

images/ca_to_graph_neighbourhood.png

Now the neighbourhood is defined by the edges between nodes and the tiling can be delineated by Voronoi cells. This definition allows for a flexible definition of neighbourhood. Further the voronoi cells can be used to calculate the area of simulation space each node is responsible for.

The next addition to CA, in order to arrive at CGA is to add a set of continuous values to each node, that represent the concentration of chemical entities in the voronoi region of the node. Further, set of value transition functions is defined, that describe the change in concentration in between time steps. The sum of changes is then applied and the new concentration is set. In this implementation of CGA the value transition functions represent natural phenomena or cellular processes. Each phenomenon is encapsulated into a module that is responsible for the calculation of the delta for every node and chemical entity.

Spatial and temporal step width

The spatial and temporal step widths are critical for the accuracy, robustness and speed of the simulation. The spatial step width is a result of the number of nodes and the arrangement of nodes in the system. Using a larger number of nodes for the same simulation area will allow for more accurate and robust simulations, while increasing computational complexity of the system.

The temporal step width is determined during simulation. For each epoch (one application of value transition function) the time step will be adjusted to ensure numerical stability. The numerical error for each time step is determined by comparing results of different temporal step widths (namely using the midpoint method). If the error is too large, the step width is decreased until the error is below a specified threshold (epsilon). Naturally,epsilons approaching 0 result in very small time steps and therefore long simulation times, at default epsilon is at 0.01.

Parametrization

Each module encapsulates a mechanistic model of the phenomenon. In mechanistic models the basic elements have a direct correspondence to the underlying mechanisms of the phenomenon they describe. Further, mechanistic models use parameters that are attributes of the underlying chemical entities. Therefore, it is possible to calculate or simply retrieve those parameters from databases. SiNGA provides access to databases and regression methods and allows for the automatic retrieval of some of the specified parameters. See the module pages for illustration of this principle.

Setup and Simulation

Each simulation requires a AutomatonGraph, a set of Modules and a set of ChemicalEntitys. Additionally AssignmentRules can be used to assign concentrations to chemical entities based on rules (functions). The class SimulationExamples provides a set of examples where Simulations are being set up. Principally the following steps should be taken:

// initialize simulation
Simulation simulation = new Simulation();
// initialize a graph
AutomatonGraph graph = AutomatonGraphs.useStructureFrom(Graphs.buildGridGraph(10, 10, defaultBoundingBox));
// add to simulation
simulation.setGraph(graph);
// initialize chemical entities
ChemicalEntity fructosePhosphate = ChEBIParserService.parse("CHEBI:18105");
// initialize their concentrations in the graph
graph.initializeSpeciesWithConcentration(fructosePhosphate, 0.1);
// add to simulation
simulation.getChemicalEntities().add(fructosePhosphate);
// set environmental simulation parameters (e.g. system diameter, temperature, viscosity)
EnvironmentalParameters.getInstance().setNodeSpacingToDiameter(Quantities.getQuantity(2500.0, NANO(METRE)), 10);
// add diffusion module (free diffusion will be simulated)
simulation.getModules().add(new FreeDiffusion(simulation));

Afterwards the simulation can be performed stepwise by calling the nextEpoch method. For each epoch the size of the time step will be adjusted with the TimeStepHarmonizer, to ensure numerical stability up to a given epsilon. The time step will be optimized for each epoch, resulting in many epochs for critical simulation regimes and large ones for stable regions. Changes in simulations can be observed by tagging AutomatonNodes of the AutomatonGraph. By setting AutomatonNode.setObserved(boolean) to true the simulation emits NodeUpdatedEvent for every observed node and every time step to every registered UpdateEventListener. As a standard implementation the EpochUpdateWriter is provided and can be added to the simulation that will write log files to the specified file locations.