Main data structures¶
 node_state : 1d array (x number of nodes in grid)
 Nodebased grid of nodestate codes. This is the grid of cell (sic) states.
 link_state_dict : dictionary
 Keys are 3element tuples that represent the cellstate pairs and orientation code for each possible link type; values are the corresponding linkstate codes. Allows you to look up the linkstate code corresponding to a particular pair of adjacent nodes with a particular orientation.
 node_pair : list (x number of possible link states)
 List of 3element tuples representing all the various link states. Allows you to look up the node states and orientation corresponding to a particular linkstate ID.
 event_queue : heap of Event objects
 Queue containing all future transition events, sorted by time of occurrence (from soonest to latest).
 next_update : 1d array (x number of active 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 in each Event object 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_orientation : 1d array of ints (x number of active links)
 Orientation code for each link.
 link_state : 1d array of ints (x number of active links)
 State code for each link.
 n_xn : 1d array of ints (x number of possible link states)
 Number of transitions (“xn” stands for “transition”) from a given link state.
 xn_to : 2d array of ints (# possible link states x max. # transitions)
 Stores the linkstate code(s) to which a particular link state can transition. “max. # transitions” means the maximum number of transitions from a single state. For example, if each link state is associated with one and only one transition, then the maximum is 1, but if there is at least one link state that can have either of two different transitions, then the maximum would be two.
 xn_rate : 2d array of floats (# possible link states x max. # transitions)
 Rate associated with each linkstate transition.
Created GT Sep 2014, starting from link_cap.py.

class
CAPlotter
(ca, cmap=None, **kwds)[source]¶ Bases:
object
Handle display of a CellLabCTS 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
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

class
CellLabCTSModel
(model_grid, node_state_dict, transition_list, initial_node_states, prop_data=None, prop_reset_value=None, seed=0)[source]¶ Bases:
object
Linktype (or doublettype) cellular automaton model.
A CellLabCTSModel implements a linktype (or doublettype) 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 nodestate 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 nodestate 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 nodestate 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 nodestate 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.

assign_link_states_from_node_types
()[source]¶ Assign linkstate 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 3element 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 linkstate to nodestate.
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 3element 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.

current_link_state
(link_id)[source]¶ Get the current state of a link.
Used to determine whether the link state at link link_id has changed due to an independent change in the nodestate grid. Returns the current state of the link based on the states of its two end nodes; this can be compared to the entry in self.link_state to determine whether the state has changed.
Parameters: link_id : int
ID of the active link to test
Returns: int
New link state code
Notes
Vectorizing this might yield some speed.

do_transition
(event, current_time, plot_each_transition=False, plotter=None)[source]¶ Transition state.
Implements a state transition.
Parameters: event : Event object
Event object containing the data for the current transition event
current_time : float
Current time in simulation
plot_each_transition : bool (optional)
True if caller wants to show a plot of the grid after this transition
plotter : CAPlotter object
Sent if caller wants a plot after this transition
Notes
First checks that the transition is still valid by comparing the link’s next_update time with the corresponding update time in the event object.
If the transition is valid, we:
 Update the states of the two nodes attached to the link
 Update the link’s state, choose its next transition, and push it on the event queue.
 Update the states of the other links attached to the two nodes, choose their next transitions, and push them on the event queue.

do_transition_new
(event_link, event_time, current_time, plot_each_transition=False, plotter=None)[source]¶ Transition state.
Implements a state transition.
Parameters: event : Event object
Event object containing the data for the current transition event
current_time : float
Current time in simulation
plot_each_transition : bool (optional)
True if caller wants to show a plot of the grid after this transition
plotter : CAPlotter object
Sent if caller wants a plot after this transition
Notes
First checks that the transition is still valid by comparing the link’s next_update time with the corresponding update time in the event object.
If the transition is valid, we:
 Update the states of the two nodes attached to the link
 Update the link’s state, choose its next transition, and push it on the event queue.
 Update the states of the other links attached to the two nodes, choose their next transitions, and push them on the event queue.
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) >>> (tm, idx, link) = cts.priority_queue.pop() >>> np.round(100 * tm) 12.0 >>> idx 6 >>> link 16 >>> cts.grid.node_at_link_tail[link] 8 >>> cts.grid.node_at_link_head[link] 13 >>> cts.next_trn_id[link] 3 >>> cts.trn_to[cts.next_trn_id[link]] 7 >>> cts.do_transition_new(link, tm, 0.0) >>> cts.node_state[8] 1 >>> cts.node_state[13] 1 >>> cts.link_state[16] 7 >>> cts.next_update[16] == _NEVER True >>> cts.next_trn_id[16] 1

get_next_event
(link, current_state, current_time)[source]¶ Get the next event for a link.
Returns the next event for link with ID “link”, which is in state “current state”.
Parameters: link : int
ID of the link
current_state : int
Current state code for the link
current_time : float
Current time in simulation (i.e., time of event just processed)
Returns: Event object
The returned Event object contains the time, link ID, and type of the next transition event at this link.
Notes
If there is only one potential transition out of the current state, a time for the transition is selected at random from an exponential distribution with rate parameter appropriate for this transition.
If there are more than one potential transitions, a transition time is chosen for each, and the smallest of these applied.
Assumes that there is at least one potential transition from the current state.

get_next_event_new
(link, current_state, current_time)[source]¶ Get the next event for a link.
Returns the next event for link with ID “link”, which is in state “current state”.
Parameters: link : int
ID of the link
current_state : int
Current state code for the link
current_time : float
Current time in simulation (i.e., time of event just processed)
Returns: Event object
The returned Event object contains the time, link ID, and type of the next transition event at this link.
Notes
If there is only one potential transition out of the current state, a time for the transition is selected at random from an exponential distribution with rate parameter appropriate for this transition.
If there are more than one potential transitions, a transition time is chosen for each, and the smallest of these applied.
Assumes that there is at least one potential transition from the current state.

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)

push_transitions_to_event_queue_new
()[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)

run_new
(run_to, plot_each_transition=False, plotter=None)[source]¶ Test of new approach using priority queue.

set_node_state_grid
(node_states)[source]¶ Set the grid of nodestate codes to node_states.
Sets the grid of nodestate 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 nodestate array
Parameters: node_states : 1D array of ints (x number of nodes in grid) Notes
The nodestate 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.active_link_orientation
: 1D numpy array
Notes
The setup varies depending on the type of LCA. The default is nonoriented, 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).

setup_transition_data
(xn_list)[source]¶ Create transition data arrays.
PREVIOUS METHOD:
Using the transition list and the number of link states, creates three arrays that collectively contain data on state transitions:
n_xn
: for each link state, contains the number of transitions out of that state.xn_to
: 2D array that records, for each link state and each transition, the new state into which the link transitions.xn_rate
: 2D array that records, for each link state and each transition, the rate (1/time) of the transition.xn_propswap
: 2D array that indicates, for each link state and each transition, whether that transition is accompanied by a “property” swap, in which the two cells exchange properties (in order to represent a particle moving)
NEW METHOD:
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, 4)) >>> 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(12) % 2 >>> cts = OrientedRasterCTS(grid, nsd, trn_list, ins) >>> cts.n_trn array([0, 1, 1, 0, 0, 2, 0, 0]) >>> cts.trn_id array([[0, 0], [0, 0], [1, 0], [0, 0], [0, 0], [2, 3], [0, 0], [0, 0]]) >>> cts.trn_to array([2, 1, 6, 7]) >>> cts.trn_rate array([ 1., 2., 3., 4.])

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.

update_link_state
(link, new_link_state, current_time)[source]¶ Implements a link transition by updating the current state of the link and (if appropriate) choosing the next transition event and pushing it on to the event queue.
Parameters: link : int
ID of the link to update
new_link_state : int
Code for the new state
current_time : float
Current time in simulation

update_link_state_new
(link, new_link_state, current_time)[source]¶ Implements a link transition by updating the current state of the link and (if appropriate) choosing the next transition event and pushing it on to the event queue.
Parameters: link : int
ID of the link to update
new_link_state : int
Code for the new state
current_time : float
Current time in simulation

update_link_states_and_transitions
(current_time)[source]¶ Following an “external” change to the node state grid, updates link states where necessary and creates any needed events.
Notes
Algorithm:
FOR each active link: if the actual node pair is different from the link's code: change the link state to be correct schedule an event

update_link_states_and_transitions_new
(current_time)[source]¶ Following an “external” change to the node state grid, updates link states where necessary and creates any needed events.
Notes
Algorithm:
FOR each active link: if the actual node pair is different from the link's code: change the link state to be correct schedule an event

update_node_states
(tail_node, head_node, new_link_state)[source]¶ Update the states of the two nodes in the given link.
Parameters: tail_node : int
ID of the tail node of the link (cell pair) in question
head_node : int
ID of the head node of the link (cell pair) in question
new_link_state : int
Link state code for the new cell pair
Returns: (bool, bool)
Flags indicating whether the tail node and head node, respectively, have changed state


class
Event
(time, link, xn_to, propswap=False, prop_update_fn=None)[source]¶ Bases:
object
Transition event at a link.
Represents a transition event at a link. The transition occurs at a given link and a given time, and it involves a transition into the state xn_to (an integer code representing the new link state; “xn” is shorthand for “transition”).
The class overrides the __lt__ (less than operator) method so that when Event() objects are placed in a PriorityQueue, the earliest event is given the highest priority (i.e., placed at the top of the queue).
Event() constructor sets 3 required properties and one optional property.
Parameters: time : float
Time at which the event is scheduled to occur
link : int
ID of the link at which event occurs
xn_to : int
New state to which this cell pair (link) will transition
propswap : bool (optional)
Flag: does this event involve an exchange of properties between the two cells?
Examples
>>> from landlab.ca.celllab_cts import Event >>> e1 = Event( 10.0, 1, 2) >>> e2 = Event( 2.0, 3, 1) >>> e1 < e2 False >>> e2 < e1 True
Event() constructor sets 3 required properties and one optional property.
Parameters: time : float
Time at which the event is scheduled to occur
link : int
ID of the link at which event occurs
xn_to : int
New state to which this cell pair (link) will transition
propswap : bool (optional)
Flag: does this event involve an exchange of properties between the two cells?

class
Transition
(from_state, to_state, rate, name=None, swap_properties=False, prop_update_fn=None)[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, LR; 1: vertical, bottomtop. 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?