# landlab.ca package¶

## landlab.ca.celllab_cts module¶

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_state : 1d array (x number of nodes in grid)
Node-based grid of node-state codes. This is the grid of cell (sic) states.
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_pair : list (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.
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.
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 link-state 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 link-state transition.

Created GT Sep 2014, starting from link_cap.py.

class CAPlotter(ca, cmap=None, **kwds)[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

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
finalize()[source]

Wrap up plotting.

Wrap up plotting by switching off interactive model and showing the plot.

update_plot()[source]

Plot the current node state grid.

class CellLabCTSModel(model_grid, node_state_dict, transition_list, initial_node_states, prop_data=None, prop_reset_value=None, seed=0)[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.

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 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.

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 node-state 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.

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:

1. Update the states of the two nodes attached to the link
2. Update the link’s state, choose its next transition, and push it on the event queue.
3. 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:

1. Update the states of the two nodes attached to the link
2. Update the link’s state, choose its next transition, and push it on the event queue.
3. 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
16
8
13
3
7
>>> cts.node_state[8]
1
>>> cts.node_state[13]
1
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) 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) 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
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 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.active_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).

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.

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

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

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


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 (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

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, 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?

## landlab.ca.hex_cts module¶

Simple hexagonal Landlab cellular automaton

This file defines the HexCTS class, which is a sub-class of CellLabCTSModel that implements a simple, non-oriented, hex-grid CA. Like its parent class, HexCTS implements a continuous-time, stochastic, pair-based CA. The hex grid has 3 principal directions, rather than 2 for a raster. Hex grids are often used in CA models because of their symmetry.

Created GT Sep 2014

class HexCTS(model_grid, node_state_dict, transition_list, initial_node_states, prop_data=None, prop_reset_value=None)[source]

Class HexCTS implements a non-oriented hex-grid CellLab-CTS model.

HexCTS constructor: sets number of orientations to 1 and calls base-class constructor.

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.

Examples

>>> from landlab import HexModelGrid
>>> from landlab.ca.celllab_cts import Transition
>>> from landlab.ca.hex_cts import HexCTS

>>> mg = HexModelGrid(4, 3, 1.0)
>>> nsd = {0 : 'yes', 1 : 'no'}
>>> xnlist = []
>>> xnlist.append(Transition((0,1,0), (1,1,0), 1.0, 'frogging'))
>>> hcts = HexCTS(mg, nsd, xnlist, nsg)


HexCTS constructor: sets number of orientations to 1 and calls base-class constructor.

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.

## landlab.ca.hex_lattice_tectonicizer module¶

hex_lattice_tectonicizer.py.

Models discrete normal-fault offset on a 2D hex lattice with a rectangular shape and with one orientation of the nodes being vertical.

The intention here is to use a particle (LCA) model to represent the evolution of a 2D hillslope, with the hex_lattice_tectonicizer serving to shift the nodes either upward (simple vertical uplift relative to baselevel), or up and sideways (representing motion on a fault plane).

Created on Mon Nov 17 08:01:49 2014

@author: gtucker

class HexLatticeTectonicizer(grid=None, node_state=None, propid=None, prop_data=None, prop_reset_value=None)[source]

Bases: object

Handles tectonics and baselevel for CellLab-CTS models.

This is the base class from which classes to represent particular baselevel/fault geometries are derived.

Examples

>>> hlt = HexLatticeTectonicizer()
>>> hlt.grid.number_of_nodes
25
>>> hlt.nr
5
>>> hlt.nc
5


Create and initialize a HexLatticeTectonicizer.

Examples

>>> from landlab import HexModelGrid
>>> hg = HexModelGrid(6, 6, shape='rect')
>>> hlt = HexLatticeTectonicizer()
>>> hlt.grid.number_of_nodes
25
>>> hlt.nr
5
>>> hlt.nc
5

class LatticeNormalFault(fault_x_intercept=0.0, grid=None, node_state=None, propid=None, prop_data=None, prop_reset_value=None)[source]

Handles normal-fault displacement in CellLab-CTS models.

Represents a 60 degree, left-dipping normal fault, and handles discrete offsets for a hex grid that has vertical columns and a rectangular shape.

Examples

>>> import numpy as np
>>> from landlab import HexModelGrid
>>> from landlab.ca.boundaries.hex_lattice_tectonicizer import LatticeNormalFault
>>> pid = np.arange(25, dtype=int)
>>> pdata = np.arange(25)
>>> ns = np.arange(25, dtype=int)
>>> grid = HexModelGrid(5, 5, 1.0, orientation='vertical', shape='rect', reorient_links=True)
>>> lnf = LatticeNormalFault(0.0, grid, ns, pid, pdata, 0.0)
>>> lnf.first_fw_col
1
>>> lnf.num_fw_rows
array([0, 1, 3, 4, 5])
>>> lnf.incoming_node
array([1, 3, 4, 6])
>>> lnf.outgoing_node
array([12, 17, 19, 22])

>>> pid = arange(16, dtype=int)
>>> ns = arange(16, dtype=int)
>>> pdata = arange(16)
>>> grid = HexModelGrid(4, 4, 1.0, orientation='vertical', shape='rect', reorient_links=True)
>>> lnf = LatticeNormalFault(0.0, grid, ns, pid, pdata, 0.0)
>>> lnf.num_fw_rows
array([0, 1, 3, 4])
>>> lnf.incoming_node
array([1, 2, 5])
>>> lnf.outgoing_node
array([ 7, 11, 15])
>>> lnf.do_offset(rock_state=16)
>>> ns
array([ 0, 16, 16, 16,  4, 16,  6,  1,  8,  2, 10,  5, 12, 13, 14,  9])
>>> lnf.propid
array([ 0,  7, 11,  3,  4, 15,  6,  1,  8,  2, 10,  5, 12, 13, 14,  9])

>>> pid = arange(20, dtype=int)
>>> ns = arange(20, dtype=int)
>>> pdata = arange(20)
>>> grid = HexModelGrid(4, 5, 1.0, orientation='vertical', shape='rect', reorient_links=True)
>>> lnf = LatticeNormalFault(0.0, grid, ns, pid, pdata, 0.0)
>>> lnf.incoming_node
array([1, 3, 4, 6])
>>> lnf.outgoing_node
array([12, 14, 17, 19])
>>> lnf.do_offset(rock_state=20)
>>> ns
array([ 0, 20, 20, 20, 20,  5, 20, 20,  8,  1, 10,  3,  4, 13,  6, 15, 16,
9, 18, 11])
>>> lnf.propid
array([ 0, 12,  2, 14, 17,  5, 19,  7,  8,  1, 10,  3,  4, 13,  6, 15, 16,
9, 18, 11])


Create and initialize a LatticeNormalFault object.

Examples

>>> import numpy as np
>>> from landlab import HexModelGrid
>>> from landlab.ca.boundaries.hex_lattice_tectonicizer import LatticeNormalFault
>>> pid = np.arange(25, dtype=int)
>>> pdata = np.arange(25)
>>> ns = np.arange(25, dtype=int)
>>> grid = HexModelGrid(5, 5, 1.0, orientation='vertical', shape='rect', reorient_links=True)
>>> lnf = LatticeNormalFault(-0.01, grid, ns, pid, pdata, 0.0)
>>> lnf.first_fw_col
0
>>> lnf.num_fw_rows
array([1, 2, 4, 5, 5])
>>> lnf.incoming_node
array([0, 1, 3, 4, 6])
>>> lnf.outgoing_node
array([12, 17, 19, 22, 24])

>>> pid = np.arange(16, dtype=int)
>>> pdata = np.arange(16)
>>> ns = np.arange(16, dtype=int)
>>> grid = HexModelGrid(4, 4, 1.0, orientation='vertical', shape='rect', reorient_links=True)
>>> lnf = LatticeNormalFault(0.0, grid, ns, pid, pdata, 0.0)
>>> lnf.first_fw_col
1
>>> lnf.num_fw_rows
array([0, 1, 3, 4])
>>> lnf.incoming_node
array([1, 2, 5])
>>> lnf.outgoing_node
array([ 7, 11, 15])

>>> pid = np.arange(45, dtype=int)
>>> pdata = np.arange(45)
>>> ns = np.arange(45, dtype=int)
>>> grid = HexModelGrid(5, 9, 1.0, orientation='vertical', shape='rect', reorient_links=True)
>>> lnf = LatticeNormalFault(0.0, grid, ns, pid, pdata, 0.0)
>>> lnf.first_fw_col
1
>>> lnf.num_fw_rows
array([0, 1, 3, 4, 5, 5, 5, 5, 5])
>>> lnf.incoming_node
array([ 1,  2,  3,  5,  6,  7,  8, 10, 11, 12])
>>> lnf.outgoing_node
array([22, 31, 33, 34, 35, 38, 39, 40, 43, 44])

do_offset(rock_state=1)[source]

Apply 60-degree normal-fault offset.

Offset is applied to a hexagonal grid with vertical node orientation and rectangular arrangement of nodes.

Parameters: rock_state : int State code to apply to new cells introduced along bottom row.

Examples

>>> import numpy as np
>>> from landlab.ca.boundaries.hex_lattice_tectonicizer import LatticeNormalFault
>>> from landlab import HexModelGrid
>>> pid = np.arange(25, dtype=int)
>>> pdata = np.arange(25)
>>> ns = np.arange(25, dtype=int)
>>> grid = HexModelGrid(5, 5, 1.0, orientation='vertical', shape='rect', reorient_links=True)
>>> lnf = LatticeNormalFault(0.0, grid, ns, pid, pdata, 0.0)
>>> lnf.do_offset(rock_state=25)
>>> ns
array([ 0, 25, 25, 25, 25,  5, 25, 25,  8,  1, 10,  3,  4, 13,  6, 15, 16,
9, 18, 11, 20, 21, 14, 23, 24])
>>> lnf.propid
array([ 0, 12,  2, 17, 19,  5, 22,  7,  8,  1, 10,  3,  4, 13,  6, 15, 16,
9, 18, 11, 20, 21, 14, 23, 24])


Set up array with link IDs for shifting link data up and right.

Examples

>>> from landlab.ca.boundaries.hex_lattice_tectonicizer import LatticeNormalFault
>>> from landlab import HexModelGrid
>>> pid = np.arange(25, dtype=int)
>>> pdata = np.arange(25)
>>> ns = np.arange(25, dtype=int)
>>> grid = HexModelGrid(5, 5, 1.0, orientation='vertical', shape='rect', reorient_links=True)
>>> lnf = LatticeNormalFault(-0.01, grid, ns, pid, pdata, 0.0)
array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])

class LatticeUplifter(grid=None, node_state=None, propid=None, prop_data=None, prop_reset_value=None, opt_block_layer=False, block_ID=9, block_layer_dip_angle=0.0, block_layer_thickness=1.0, layer_left_x=0.0, y0_top=0.0)[source]

Handles vertical uplift of interior (not edges) for a hexagonal lattice with vertical node orientation and rectangular node arrangement.

Create and initialize a LatticeUplifter

Examples

>>> lu = LatticeUplifter()
>>> lu.inner_base_row_nodes
array([1, 3, 4])

>>> hg = HexModelGrid(5, 6, 1.0, orientation='vertical', shape='rect', reorient_links=True)
>>> lu = LatticeUplifter(grid=hg)
>>> lu.inner_base_row_nodes
array([1, 2, 3, 4])


Applies uplift to links and transitions.

For each link that lies above the y = 1.5 cells line, assign the properties of the link one row down.

Examples

>>> from landlab import HexModelGrid
>>> from landlab.ca.oriented_hex_cts import OrientedHexCTS
>>> from landlab.ca.celllab_cts import Transition
>>> import numpy as np

>>> mg = HexModelGrid(4, 3, 1.0, orientation='vertical', shape='rect')
>>> nsd = {0 : 'yes', 1 : 'no'}
>>> xnlist = []
>>> xnlist.append(Transition((0,0,0), (1,1,0), 1.0, 'frogging'))
>>> xnlist.append(Transition((0,0,1), (1,1,1), 1.0, 'frogging'))
>>> xnlist.append(Transition((0,0,2), (1,1,2), 1.0, 'frogging'))
>>> ohcts = OrientedHexCTS(mg, nsd, xnlist, nsg)
array([0, 4, 8, 8, 4, 0, 4, 8, 8, 4, 0])
array([0, 1, 2, 2, 1, 0, 1, 2, 2, 1, 0])
>>> lu = LatticeUplifter(grid=mg)
>>> nu = ohcts.next_update
array([ 0.8 ,  1.26,  0.92,  0.79,  0.55,  1.04,  0.58,  2.22,  3.31,
0.48,  1.57])
>>> pq = ohcts.priority_queue
>>> pq._queue[0][2]  # link for first event = 20, not shifted
20
>>> round(pq._queue[0][0], 2)  # transition scheduled for t = 0.48
0.48
>>> pq._queue[2][2]  # this event scheduled for link 15...
15
>>> round(pq._queue[2][0], 2)  # ...transition scheduled for t = 0.58
0.58
array([ 0.75,  0.84,  2.6 ,  0.07,  0.09,  0.8 ,  0.02,  1.79,  1.51,
2.04,  3.85])
>>> pq._queue[0][2]  # new soonest event
15
>>> pq._queue[9][2]  # was previously 7, now shifted up...
14
>>> round(pq._queue[9][0], 2)  # ...but still scheduled for t = 0.80
0.8

uplift_interior_nodes(ca, current_time, rock_state=1)[source]

Simulate ‘vertical’ displacement by shifting contents of node_state

Examples

>>> from landlab import HexModelGrid
>>> from landlab.ca.hex_cts import HexCTS
>>> from landlab.ca.celllab_cts import Transition
>>> mg = HexModelGrid(5, 5, 1.0, orientation='vertical', shape='rect')
>>> nsd = {}
>>> for i in range(26):
...     nsd[i] = i
>>> xnlist = []
>>> xnlist.append(Transition((0,0,0), (1,1,0), 1.0, 'frogging', True))
>>> ca = HexCTS(mg, nsd, xnlist, nsg)
>>> lu = LatticeUplifter(propid=ca.propid, prop_data=pd)
>>> lu.node_state[:] = arange(len(lu.node_state))
>>> lu.uplift_interior_nodes(ca, rock_state=25, current_time=0.0)
>>> lu.node_state
array([ 0, 25,  2, 25, 25,
5,  1,  7,  3,  4,
10,  6, 12,  8,  9,
15, 11, 17, 13, 14,
20, 16, 22, 18, 19])
>>> lu.propid
array([ 0, 21,  2, 23, 24,
5,  1,  7,  3,  4,
10,  6, 12,  8,  9,
15, 11, 17, 13, 14,
20, 16, 22, 18, 19])

uplift_property_ids()[source]

Shift property IDs upward by one row

## landlab.ca.little_ca_test module¶

Test the creation and execution of a CellLab-CTS model.

Tests the creation and execution of a CellLab-CTS model, by creating a simple two-state CA on a small grid.

Created by Greg Tucker, May 2015

main()[source]
setup_transition_list()[source]

Creates and returns a list of Transition() objects to represent state transitions for a biased random walk, in which the rate of downward motion is greater than the rate in the other three directions.

Returns: xn_list : list of Transition objects List of objects that encode information about the link-state transitions.

Notes

This doesn’t represent any particular process, but rather is simply used to test the CA code. The transition rules have 0-0 pairs transitioning to 0-1 or 1-0 pairs (50/50 chance) and thence to 1-1 pairs, at which point there are no further transitions.

The states and transitions are as follows:

Pair state      Transition to       Process             Rate (cells/s)
==========      =============       =======             ==============
0 (0-0)         1 (0-1)                                 0.5
2 (1-0)                                 0.5
1 (0-1)         3 (1-1)                                 1.0
2 (1-0)         3 (1-1)                                 1.0
3 (1-1)         (none)                                  -


## landlab.ca.oriented_hex_cts module¶

Simple hexagonal Landlab cellular automaton

This file defines the OrientedHexCTS class, which is a sub-class of CellLabCTSModel that implements a simple, non-oriented, hex-grid CA. Like its parent class, OrientedHexCTS implements a continuous-time, stochastic, pair-based CA. The hex grid has 3 principal directions, rather than 2 for a raster. Hex grids are often used in CA models because of their symmetry.

Created GT Sep 2014

class OrientedHexCTS(model_grid, node_state_dict, transition_list, initial_node_states, prop_data=None, prop_reset_value=None)[source]

Oriented hex-grid CellLab-CTS model.

OrientedHexCTS constructor: sets number of orientations to 3 and calls base-class constructor.

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.

Examples

>>> from landlab import HexModelGrid
>>> from landlab.ca.oriented_hex_cts import OrientedHexCTS
>>> from landlab.ca.celllab_cts import Transition

>>> mg = HexModelGrid(4, 3, 1.0)
>>> nsd = {0 : 'yes', 1 : 'no'}
>>> xnlist = []
>>> xnlist.append(Transition((0,1,0), (1,1,0), 1.0, 'frogging'))
>>> ohcts = OrientedHexCTS(mg, nsd, xnlist, nsg)


Initialize a OrientedHexCTS.

OrientedHexCTS constructor: sets number of orientations to 3 and calls base-class constructor.

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.
setup_array_of_orientation_codes()[source]

Creates and configures an array that contain the orientation code for each active link (and corresponding cell pair).

Notes

Creates:

• self.active_link_orientation: 1D numpy array

This overrides the method of the same name in celllab_cts.py. If the hex grid is oriented such that one of the 3 axes is vertical (a ‘vertical’ grid), then the three orientations are:

• 0 = vertical (0 degrees clockwise from vertical)
• 1 = right and up (60 degrees clockwise from vertical)
• 2 = right and down (120 degrees clockwise from vertical)

If the grid is oriented with one principal axis horizontal (‘horizontal’ grid), then the orientations are:

• 0 = up and left (30 degrees counter-clockwise from vertical)
• 1 = up and right (30 degrees clockwise from vertical)
• 2 = horizontal (90 degrees clockwise from vertical)

## landlab.ca.oriented_raster_cts module¶

Simple raster Landlab cellular automaton.

Simple raster Landlab cellular automaton, with cell-pair transitions that depend on orientation (vertical or horizontal)

This file defines the OrientedRasterCTS class, which is a sub-class of CellLabCTSModel that implements a simple, oriented, raster-grid CA. Like its parent class, OrientedRasterCTS implements a continuous-time, stochastic, pair-based CA.

Created GT Sep 2014

class OrientedRasterCTS(model_grid, node_state_dict, transition_list, initial_node_states, prop_data=None, prop_reset_value=None)[source]

Oriented raster CellLab-CTS model.

RasterCTS constructor: sets number of orientations to 2 and calls base-class constructor.

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.

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.ca.celllab_cts import Transition
>>> from landlab.ca.oriented_raster_cts import OrientedRasterCTS

>>> mg = RasterModelGrid(3, 4, 1.0)
>>> nsd = {0 : 'yes', 1 : 'no'}
>>> xnlist = []
>>> xnlist.append(Transition((0,1,0), (1,1,0), 1.0, 'frogging'))
>>> orcts = OrientedRasterCTS(mg, nsd, xnlist, nsg)


RasterCTS constructor: sets number of orientations to 2 and calls base-class constructor.

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.
setup_array_of_orientation_codes()[source]

Creates and configures an array that contain the orientation code for each active link (and corresponding cell pair).

Notes

Creates:

• self.active_link_orientation: 1D numpy array of ints Array of orientation codes for each cell pair (link)

This overrides the method of the same name in landlab_ca.py.

## landlab.ca.raster_cts module¶

raster_cts.py: simple raster continuous-time stochastic cellular automaton

This file defines the RasterCTS class, which is a sub-class of CellLabCTSModel that implements a simple, non-oriented, raster-grid CA. Like its parent class, RasterCTS implements a continuous-time, stochastic, pair-based CA.

Created GT Sep 2014, starting from link_ca.py.

class RasterCTS(model_grid, node_state_dict, transition_list, initial_node_states, prop_data=None, prop_reset_value=None)[source]

Class RasterLCA implements a non-oriented raster CellLab-CTS model.

RasterLCA constructor: sets number of orientations to 1 and calls base-class constructor.

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.

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.ca.celllab_cts import Transition
>>> from landlab.ca.raster_cts import RasterCTS

>>> mg = RasterModelGrid(3, 4, 1.0)
>>> nsd = {0 : 'yes', 1 : 'no'}
>>> xnlist = []
>>> xnlist.append(Transition((0,1,0), (1,1,0), 1.0, 'frogging'))