landlab.ca.celllab_cts¶
Landlab’s Continuous-Time Stochastic (CTS) cellular automata modeling package.
Overview¶
A CellLab CTS model implements a particular type of cellular automaton (CA): a continuous-time stochastic CA. The approach is based on that of Narteau et al. (2002, 2009) and Rozier and Narteau (2014). Like a normal CA, the domain consists of a lattice of cells, each of which has a discrete state. Unlike a conventional CA, the updating process is stochastic, and takes place in continuous rather than discrete time. Any given pair (or “doublet”) of adjacent cell states has a certain specified probability of transition to a different pair of states. The transition probability is given in the form of an average transition rate, \(\lambda\) (with dimensions of 1/T); the actual time of transition is a random variable drawn from an exponential probability distribution with mean \(1/\lambda\).
Subclasses¶
Landlab provides for several different lattice and connection types:
RasterCTS: regular raster grid with transitions between horizontal and vertical cell pairs
OrientedRasterCTS: like a RasterLCA, but different transition rates can be assigned to vertical and horizontal pairs. This property of orientation can be used, for example, to implement rules representing gravitational attraction, or flow of a fluid with a particular direction.
RasterD8CTS: like a RasterLCA, but includes diagonal as well as vertical and horizontal cell pairs.
OrientedRasterD8CTS: as above but orientation also matters.
HexCTS: hexagonal grid
OrientedHexCTS: hexagonal grid, with transition rates allowed to vary according to orientation.
Encoding of “states”¶
As in any traditional cellular automaton model, a LandlabCellularAutomaton contains a grid of cells (“nodes” in Landlab parlance), each of which is has a discrete state. States are represented by integers (0, 1, … N).
In addition, every active link has an orientation code and a link state code. The orientation code represents the orientation of the link in space: is it “vertical” (aligned with the y axis), “horizontal” (aligned with x), or in some other orientation? The number of possible orientations depends on the subclass. The base class has only one orientation code (0) (meaning “orientation doesn’t matter), but this is overridden in some of the subclasses. For example, the OrientedRasterLCA has two orientation codes (0 and 1, for vertical and horizontal), while the OrientedHexLCA has three (representing the three axes in a hex-cell / triagonal grid).
Each active link also has a link state code. The state of a link refers to its particular combination of nodes and its orientation. For example, link state 1 refers to a link in which the tail-node has state 0, the head-node has state 1, and the orientation code is 0. The number of possible link states is equal to R N^2, where R is the number of orientations (1 to 3, depending on the subclass) and N is the number of possible node states. The simplest possible Landlab CA model would have just one orientation code and two possible cell states, so that there are four unique link states. These would be represented by the tuples of (tail-node state, head-node state, orientation) as follows:
link state 0 = (0, 0, 0)
link state 1 = (0, 1, 0)
link state 2 = (1, 0, 0)
link state 3 = (1, 1, 0)
Main data structures¶
- node_state1d array of int (x number of nodes in grid)
Node-based grid of node-state codes. This is the grid of cell (sic) states.
- link_state_dictdictionary
Keys are 3-element tuples that represent the cell-state pairs and orientation code for each possible link type; values are the corresponding link-state codes. Allows you to look up the link-state code corresponding to a particular pair of adjacent nodes with a particular orientation.
- node_pairlist (x number of possible link states)
List of 3-element tuples representing all the various link states. Allows you to look up the node states and orientation corresponding to a particular link-state ID.
- priority_queuePriorityQueue object containing event records
Queue containing all future transition events, sorted by time of occurrence (from soonest to latest).
- next_update1d array (x number of links)
Time (in the future) at which the link will undergo its next transition. You might notice that the update time for every scheduled transition is also stored with each event in the event queue. Why store it twice? Because a scheduled event might be invalidated after the event has been scheduled (because another transition has changed one of a link’s two nodes, for example). The way to tell whether a scheduled event is still valid is to compare its time with the corresponding transition time in the next_update array. If they are different, the event is discarded.
- link_orientation1d array of int8 (x number of links)
Orientation code for each link.
- link_state1d array of int (x number of links)
State code for each link.
- n_trn1d array of int (x number of possible link states)
Number of transitions (“trn” stands for “transition”) from a given link state.
- trn_to1d array of ints (x # transitions)
Stores the link-state code(s) to which a particular transition ID can transition.
- trn_rate1d array of floats (# transitions)
Rate associated with each link-state transition.
Created GT Sep 2014, starting from link_cap.py.
- class CAPlotter[source]¶
Bases:
object
Handle display of a CellLab-CTS grid.
CAPlotter() constructor keeps a reference to the CA model, and optionally a colormap to be used with plots.
- Parameters:
ca (LandlabCellularAutomaton object) – Reference to a CA model
cmap (Matplotlib colormap, optional) – Colormap to be used in plotting
Examples
>>> from landlab import RasterModelGrid, HexModelGrid >>> from landlab.ca.celllab_cts import Transition >>> from landlab.ca.raster_cts import RasterCTS >>> import numpy as np >>> grid = RasterModelGrid((3, 5)) >>> nsd = {0: "zero", 1: "one"} >>> trn_list = [] >>> trn_list.append(Transition((0, 1, 0), (1, 1, 0), 1.0)) >>> ins = np.arange(15) % 2 >>> ca = RasterCTS(grid, nsd, trn_list, ins) >>> cap = CAPlotter(ca) >>> cap.gridtype 'rast' >>> cap._cmap.name 'jet'
>>> from landlab.ca.hex_cts import HexCTS >>> import matplotlib >>> grid = HexModelGrid((3, 3)) >>> ins = np.zeros(grid.number_of_nodes, dtype=int) >>> ca = HexCTS(grid, nsd, trn_list, ins) >>> cap = CAPlotter(ca, cmap=matplotlib.cm.pink) >>> cap.gridtype 'hex' >>> cap._cmap.name 'pink'
CAPlotter() constructor keeps a reference to the CA model, and optionally a colormap to be used with plots.
- Parameters:
ca (LandlabCellularAutomaton object) – Reference to a CA model
cmap (Matplotlib colormap, optional) – Colormap to be used in plotting
- __init__(ca, cmap=None, **kwds)[source]¶
CAPlotter() constructor keeps a reference to the CA model, and optionally a colormap to be used with plots.
- Parameters:
ca (LandlabCellularAutomaton object) – Reference to a CA model
cmap (Matplotlib colormap, optional) – Colormap to be used in plotting
- __new__(**kwargs)¶
- class CellLabCTSModel[source]¶
Bases:
object
Link-type (or doublet-type) cellular automaton model.
A CellLabCTSModel implements a link-type (or doublet-type) cellular automaton model. A link connects a pair of cells. Each cell has a state (represented by an integer code), and each link also has a state that is determined by the states of the cell pair.
- Parameters:
model_grid (Landlab ModelGrid object) – Reference to the model’s grid
node_state_dict (dict) – Keys are node-state codes, values are the names associated with these codes
transition_list (list of Transition objects) – List of all possible transitions in the model
initial_node_states (array of ints (x number of nodes in grid)) – Starting values for node-state grid
prop_data (array (x number of nodes in grid), optional) – Array of properties associated with each node/cell
prop_reset_value (number or object, optional) – Default or initial value for a node/cell property (e.g., 0.0). Must be same type as prop_data.
Initialize the CA model.
- Parameters:
model_grid (Landlab ModelGrid object) – Reference to the model’s grid
node_state_dict (dict) – Keys are node-state codes, values are the names associated with these codes
transition_list (list of Transition objects) – List of all possible transitions in the model
initial_node_states (array of ints (x number of nodes in grid)) – Starting values for node-state grid
prop_data (array (x number of nodes in grid), optional) – Array of properties associated with each node/cell
prop_reset_value (number or object, optional) – Default or initial value for a node/cell property (e.g., 0.0). Must be same type as prop_data.
seed (int, optional) – Seed for random number generation.
- __init__(model_grid, node_state_dict, transition_list, initial_node_states, prop_data=None, prop_reset_value=None, seed=0)[source]¶
Initialize the CA model.
- Parameters:
model_grid (Landlab ModelGrid object) – Reference to the model’s grid
node_state_dict (dict) – Keys are node-state codes, values are the names associated with these codes
transition_list (list of Transition objects) – List of all possible transitions in the model
initial_node_states (array of ints (x number of nodes in grid)) – Starting values for node-state grid
prop_data (array (x number of nodes in grid), optional) – Array of properties associated with each node/cell
prop_reset_value (number or object, optional) – Default or initial value for a node/cell property (e.g., 0.0). Must be same type as prop_data.
seed (int, optional) – Seed for random number generation.
- __new__(**kwargs)¶
- assign_link_states_from_node_types()[source]¶
Assign link-state code for each link.
Takes lists/arrays of “tail” and “head” node IDs for each link, and a dictionary that associates pairs of node states (represented as a 3-element tuple, comprising the TAIL state, FROM state, and orientation) to link states.
creates:
self.link_state
: 1D numpy array
- create_link_state_dict_and_pair_list()[source]¶
Create a dict of link-state to node-state.
Creates a dictionary that can be used as a lookup table to find out which link state corresponds to a particular pair of node states. The dictionary keys are 3-element tuples, each of which represents the state of the TAIL node, the HEAD node, and the orientation of the link. The values are integer codes representing the link state numbers.
Notes
Performance note: making self.node_pair a tuple does not appear to change time to lookup values in update_node_states. Changing it to a 2D array of int actually slows it down.
- push_transitions_to_event_queue()[source]¶
Initializes the event queue by creating transition events for each cell pair that has one or more potential transitions and pushing these onto the queue. Also records scheduled transition times in the self.next_update array.
Examples
>>> from landlab import RasterModelGrid >>> from landlab.ca.celllab_cts import Transition >>> from landlab.ca.oriented_raster_cts import OrientedRasterCTS >>> import numpy as np >>> grid = RasterModelGrid((3, 5)) >>> nsd = {0: "zero", 1: "one"} >>> trn_list = [] >>> trn_list.append(Transition((0, 1, 0), (1, 0, 0), 1.0)) >>> trn_list.append(Transition((1, 0, 0), (0, 1, 0), 2.0)) >>> trn_list.append(Transition((0, 1, 1), (1, 0, 1), 3.0)) >>> trn_list.append(Transition((0, 1, 1), (1, 1, 1), 4.0)) >>> ins = np.arange(15) % 2 >>> cts = OrientedRasterCTS(grid, nsd, trn_list, ins) >>> ev0 = cts.priority_queue._queue[0] >>> np.round(100 * ev0[0]) 12.0 >>> ev0[2] # this is the link ID 16 >>> ev6 = cts.priority_queue._queue[6] >>> np.round(100 * ev6[0]) 27.0 >>> ev6[2] # this is the link ID 6 >>> cts.next_trn_id[ev0[2]] # ID of the transition to occur at this link 3 >>> cts.next_trn_id[cts.grid.active_links] array([-1, 2, -1, 1, 0, 1, 0, 2, -1, 3])
- run(run_to, node_state_grid=None, plot_each_transition=False, plotter=None)[source]¶
Run the model forward for a specified period of time.
- Parameters:
run_to (float) – Time to run to, starting from self.current_time
node_state_grid (1D array of ints (x number of nodes) (optional)) – Node states (if given, replaces model’s current node state grid)
plot_each_transition (bool (optional)) – Option to display the grid after each transition
plotter (CAPlotter object (optional)) – Needed if caller wants to plot after every transition
Examples
>>> from landlab import RasterModelGrid >>> from landlab.ca.celllab_cts import Transition >>> from landlab.ca.oriented_raster_cts import OrientedRasterCTS >>> import numpy as np >>> grid = RasterModelGrid((3, 5)) >>> nsd = {0: "zero", 1: "one"} >>> trn_list = [] >>> trn_list.append(Transition((0, 1, 0), (1, 0, 0), 1.0)) >>> trn_list.append(Transition((1, 0, 0), (0, 1, 0), 2.0)) >>> trn_list.append(Transition((0, 1, 1), (1, 0, 1), 3.0)) >>> trn_list.append(Transition((0, 1, 1), (1, 1, 1), 4.0)) >>> ins = np.arange(15) % 2 >>> cts = OrientedRasterCTS(grid, nsd, trn_list, ins)
- set_node_state_grid(node_states)[source]¶
Set the grid of node-state codes to node_states.
Sets the grid of node-state codes to node_states. Also checks to make sure node_states is in the proper format, which is to say, it’s a Numpy array of the same length as the number of nodes in the grid.
Creates:
self.node_state : 1D array of ints (x number of nodes in grid) The node-state array
- Parameters:
node_states (1D array of ints (x number of nodes in grid))
Notes
The node-state array is attached to the grid as a field with the name ‘node_state’.
- setup_array_of_orientation_codes()[source]¶
Create array of active link orientation codes.
Creates and configures an array that contain the orientation code for each active link (and corresponding cell pair).
creates:
self.link_orientation
: 1D numpy array
Notes
The setup varies depending on the type of LCA. The default is non-oriented, in which case we just have an array of zeros. Subclasses will override this method to handle lattices in which orientation matters (for example, vertical vs. horizontal in an OrientedRasterLCA).
- update_component_data(new_node_state_array)[source]¶
Update all component data.
Call this method to update all data held by the component, if, for example, another component or boundary conditions modify the node statuses outside the component between run steps.
This method updates all necessary properties, including both node and link states.
new_node_state_array is the updated list of node states, which must still all be compatible with the state list originally supplied to this component.
Examples
>>> from landlab import RasterModelGrid >>> from landlab.ca.celllab_cts import Transition >>> from landlab.ca.raster_cts import RasterCTS >>> import numpy as np >>> grid = RasterModelGrid((3, 5)) >>> nsd = {0: "zero", 1: "one"} >>> trn_list = [] >>> trn_list.append(Transition((0, 1, 0), (1, 1, 0), 1.0)) >>> ins = np.zeros(15, dtype=int) >>> ca = RasterCTS(grid, nsd, trn_list, ins) >>> list(ca.node_state[6:9]) [0, 0, 0] >>> list(ca.link_state[9:13]) [0, 0, 0, 0] >>> len(ca.priority_queue._queue) # there are no transitions 0 >>> nns = np.arange(15) % 2 # make a new node-state grid... >>> ca.update_component_data(nns) # ...and assign it >>> list(ca.node_state[6:9]) [0, 1, 0] >>> list(ca.link_state[9:13]) [2, 1, 2, 1] >>> len(ca.priority_queue._queue) # now there are 5 transitions 5
- class Transition[source]¶
Bases:
object
A transition from one state to another.
Represents a transition from one state (“from_state”) to another (“to_state”) at a link. The transition probability is represented by a rate parameter “rate”, with dimensions of 1/T. The probability distribution of time until the transition event occurs is exponentional with mean 1/rate. The optional name parameter allows the caller to assign a name to any given transition.
Note that from_state and to_state can now be either integer IDs for the standardised ordering of the link states (as before), or tuples explicitly describing the node state at each end, and the orientation. Orientation is 0: horizontal, L-R; 1: vertical, bottom-top. For such a tuple, order is (left/bottom, right/top, orientation).
Transition() constructor sets 3 required properties and 2 optional properties for a transition from one cell pair to another.
- Parameters:
from_state (int) – Code for the starting state of the cell pair (link)
to_state (int) – Code for the new state of the cell pair (link)
rate (float) – Average rate at which this transition occurs (dimension of 1/time)
name (string (optional)) – Name for this transition
swap_properties (bool (optional)) – Flag: should properties be exchanged between the two cells?
Transition() constructor sets 3 required properties and 2 optional properties for a transition from one cell pair to another.
- Parameters:
from_state (int) – Code for the starting state of the cell pair (link)
to_state (int) – Code for the new state of the cell pair (link)
rate (float) – Average rate at which this transition occurs (dimension of 1/time)
name (string (optional)) – Name for this transition
swap_properties (bool (optional)) – Flag: should properties be exchanged between the two cells?
- __init__(from_state, to_state, rate, name=None, swap_properties=False, prop_update_fn=None)[source]¶
Transition() constructor sets 3 required properties and 2 optional properties for a transition from one cell pair to another.
- Parameters:
from_state (int) – Code for the starting state of the cell pair (link)
to_state (int) – Code for the new state of the cell pair (link)
rate (float) – Average rate at which this transition occurs (dimension of 1/time)
name (string (optional)) – Name for this transition
swap_properties (bool (optional)) – Flag: should properties be exchanged between the two cells?
- __new__(**kwargs)¶