This describes Landlab’s implementation of ModelGrid, a base class used to create and manage grids for 2D numerical models in Python using Landlab. This text lists grid methods available for the class:
The following attributes, properties, and methods provide data about the grid, its geometry, and the connectivity among the various elements. Each grid element has an ID number, which is also its position in an array that contains information about that type of element. For example, the x coordinate of node 5 would be found at grid.node_x[5].
The naming of gridelement arrays is attribute*`_at_`*element, where attribute is the name of the data in question, and element is the element to which the attribute applies. For example, the property node_at_cell contains the ID of the node associated with each cell. For example, node_at_cell[3] contains the node ID of the node associated with cell 3. The attribute is singular if there is only one value per element; for example, there is only one node associated with each cell. It is plural when there are multiple values per element; for example, the faces_at_cell array contains multiple faces for each cell. Exceptions to these general rules are functions that return indices of a subset of all elements of a particular type. For example, you can obtain an array with IDs of only the core nodes using core_nodes, while active_links provides an array of IDs of active links (only). Finally, attributes that represent a measurement of something, such as the length of a link or the surface area of a cell, are described using _of_, as in the example area_of_cell.
axis_name 
Get the name of each coordinate axis. 
axis_units 
Get units for each axis. 
move_origin (origin) 
Changes the x, y values of all nodes. 
ndim 
Number of spatial dimensions of the grid. 
node_axis_coordinates (*args, **kwds) 
Get the coordinates of nodes along a particular axis. 
number_of_elements (name) 
Number of instances of an element. 
size (group) 
Size of the arrays stored in a group. 
active_link_dirs_at_node 
Link flux directions at each node: 1=incoming flux, 1=outgoing flux, 0=no flux. 
active_neighbors_at_node 
Get list of neighbor node IDs. 
all_node_azimuths_map 
Get azimuths from every node to every other node. 
all_node_distances_map 
Get distances from every node to every other node. 
boundary_nodes 
Get array of boundary nodes. 
calc_distances_of_nodes_to_point (coord[, ...]) 
Get distances for nodes to a given point. 
cell_area_at_node 
Cell areas in a nnodeslong array. 
cell_at_node 
Node ID associated with grid cells. 
closed_boundary_nodes 
Get array of closed boundary nodes. 
core_nodes 
Get array of core nodes. 
downwind_links_at_node (values[, bad_index]) 
Return an (nnodes, X) shape array of link IDs of which links are downwind of each node, according to values (array or field). 
fixed_gradient_boundary_nodes 
Get array of fixed gradient boundary nodes. 
fixed_value_boundary_nodes 
Get array of fixed value boundary nodes. 
link_at_node_is_downwind (values[, out]) 
Return a boolean the same shape as links_at_node() which flags links which are downwind of the node as True. 
link_at_node_is_upwind (values[, out]) 
Return a boolean the same shape as links_at_node() which flags links which are upwind of the node as True. 
link_dirs_at_node 
Link directions at each node: 1=incoming, 1=outgoing, 0=none. 
links_at_node 
Get links of nodes. 
neighbors_at_node 
Get neighboring nodes. 
node_at_cell 
Node ID associated with grid cells. 
node_at_core_cell 
Get array of nodes associated with core cells. 
node_at_link_head 
Get array of the node at each link head (tonode). 
node_at_link_tail 
Get array of the node at each link tail (fromnode). 
node_axis_coordinates (*args, **kwds) 
Get the coordinates of nodes along a particular axis. 
node_is_boundary (ids[, boundary_flag]) 
Check if nodes are boundary nodes. 
node_x 
Get array of the xcoordinates of nodes. 
node_y 
Get array of the ycoordinates of nodes. 
nodes 
Get node ids for the grid. 
number_of_core_nodes 
Number of core nodes. 
number_of_links_at_node 
Number of links connected to each node. 
number_of_nodes 
Total number of nodes. 
number_of_patches_present_at_node 
Return the number of patches at a node without a closed node. 
open_boundary_nodes 
Get array of open boundary nodes. 
patches_present_at_node 
A boolean array, False where a patch has a closed node or is missing. 
set_nodata_nodes_to_closed (node_data, ...) 
Make nodata nodes closed boundaries. 
set_nodata_nodes_to_fixed_gradient (...) 
Make nodata nodes fixed gradient boundaries. 
status_at_node 
Get array of the boundary status for each node. 
unit_vector_sum_xcomponent_at_node 
Get array of xcomponent of unit vector sums at each node. 
unit_vector_sum_ycomponent_at_node 
Get array of ycomponent of unit vector sums at each node. 
upwind_links_at_node (values[, bad_index]) 
Return an (nnodes, X) shape array of link IDs of which links are upwind of each node, according to values (field or array). 
x_of_node 
Get array of the xcoordinates of nodes. 
y_of_node 
Get array of the ycoordinates of nodes. 
active_link_dirs_at_node 
Link flux directions at each node: 1=incoming flux, 1=outgoing flux, 0=no flux. 
active_links 
Get array of active links. 
angle_of_link 
Find and return the angle of a link about the node at the link tail. 
angle_of_link_about_head 
Find and return the angle of a link about the node at the link head. 
downwind_links_at_node (values[, bad_index]) 
Return an (nnodes, X) shape array of link IDs of which links are downwind of each node, according to values (array or field). 
face_at_link 
Get array of faces associated with links. 
fixed_links 
Get array of fixed links. 
length_of_link 
Get lengths of links. 
link_at_face 
Get links associated with faces. 
link_at_node_is_downwind (values[, out]) 
Return a boolean the same shape as links_at_node() which flags links which are downwind of the node as True. 
link_at_node_is_upwind (values[, out]) 
Return a boolean the same shape as links_at_node() which flags links which are upwind of the node as True. 
link_dirs_at_node 
Link directions at each node: 1=incoming, 1=outgoing, 0=none. 
links_at_node 
Get links of nodes. 
node_at_link_head 
Get array of the node at each link head (tonode). 
node_at_link_tail 
Get array of the node at each link tail (fromnode). 
number_of_active_links 
Number of active links. 
number_of_fixed_links 
Number of fixed links. 
number_of_links 
Total number of links. 
number_of_links_at_node 
Number of links connected to each node. 
number_of_patches_present_at_link 
Return the number of patches at a link without a closed node. 
patches_present_at_link 
A boolean array, False where a patch has a closed node or is missing. 
resolve_values_on_active_links (*args, **kwargs) 
Resolve the xycomponents of active links. 
resolve_values_on_links (link_values[, out]) 
Resolve the xycomponents of links. 
status_at_link 
Get array of the status of all links. 
unit_vector_xcomponent_at_link 
Get array of xcomponent of unit vector for links. 
unit_vector_ycomponent_at_link 
Get array of ycomponent of unit vector for links. 
upwind_links_at_node (values[, bad_index]) 
Return an (nnodes, X) shape array of link IDs of which links are upwind of each node, according to values (field or array). 
x_of_link 
Get array of the xcoordinates of link midpoints. 
y_of_link 
Get array of the ycoordinates of link midpoints. 
area_of_cell 
Get areas of grid cells. 
cell_area_at_node 
Cell areas in a nnodeslong array. 
cell_at_node 
Node ID associated with grid cells. 
core_cells 
Get array of core cells. 
faces_at_cell 
Return array containing face IDs at each cell. 
node_at_cell 
Node ID associated with grid cells. 
node_at_core_cell 
Get array of nodes associated with core cells. 
number_of_cells 
Total number of cells. 
number_of_core_cells 
Number of core cells. 
number_of_faces_at_cell () 
Number of faces attached to each cell. 
x_of_cell 
Get array of the xcoordinates of nodes at cells. 
y_of_cell 
Get array of the ycoordinates of nodes at cells. 
active_faces 
Get array of active faces. 
face_at_link 
Get array of faces associated with links. 
faces_at_cell 
Return array containing face IDs at each cell. 
link_at_face 
Get links associated with faces. 
number_of_active_faces 
Total number of active faces. 
number_of_faces 
Total number of faces. 
number_of_faces_at_cell () 
Number of faces attached to each cell. 
width_of_face 
Width of grid faces. 
x_of_face 
Get array of the xcoordinates of face midpoints. 
y_of_face 
Get array of the ycoordinates of face midpoints. 
number_of_patches_present_at_link 
Return the number of patches at a link without a closed node. 
number_of_patches_present_at_node 
Return the number of patches at a node without a closed node. 
patches_present_at_link 
A boolean array, False where a patch has a closed node or is missing. 
patches_present_at_node 
A boolean array, False where a patch has a closed node or is missing. 
number_of_corners 
Total number of corners. 
ModelGrid
inherits from the ModelDataFields
class. This
provides ~.ModelGrid, and its subclasses, with the ability to, optionally,
store data values that are associated with the different types grid elements
(nodes, cells, etc.). In particular, as part of ModelGrid.__init__()
,
data field groups are added to the ModelGrid that provide containers to
put data fields into. There is one group for each of the eight grid elements
(node, cell, link, face, core_node, core_cell, active_link, and active_face).
There is an additional group at_grid that can store arrays of length one
intended as a place to store variables global to the grid.
To access these groups, use the same methods as accessing groups with
~.ModelDataFields. ModelGrid.__init__()
adds the following attributes to
itself that provide access to the values groups:
at_node 

at_cell 

at_link 

at_face 

at_patch 

at_corner 

landlab.grid.base.ModelGrid.at_grid 
Each of these attributes returns a dict
like object whose keys are value
names as strings and values are numpy arrays that gives quantities at
grid elements.
ModelGrid
inherits several useful methods for creating new data
fields and adding new data fields to a ModelGrid instance. Methods to add or
create a new data array follow the numpy
syntax for creating arrays. The
folowing methods create and, optionally, initialize new arrays. These arrays
are of the correct size but a new field will not be added to the field:
empty 
Uninitialized array whose size is that of the field. 
ones 
Array, initialized to 1, whose size is that of the field. 
zeros 
Array, initialized to 0, whose size is that of the field. 
Unlike with the equivalent numpy functions, these do not take a size argument as the size of the returned arrays is determined from the size of the ModelGrid. However, the keyword arguments are the same as those of the numpy equivalents.
The following methods will create a new array and add a reference to that array to the ModelGrid:
add_empty 
Create and add an uninitialized array of values to the field. 
add_field 
Add an array of values to the field. 
add_ones 
Create and add an array of values, initialized to 1, to the field. 
add_zeros 
Create and add an array of values, initialized to 0, to the field. 
delete_field 
Erases an existing field. 
set_units 
Set the units for a field of values. 
These methods operate in the same way as the previous set except that, in
addition to creating a new array, the newlycreated array is added to the
ModelGrid. The calling signature is the same but with the addition of an
argument that gives the name of the new field as a string. The additional
method, add_field()
, adds a previously allocation
array to the ModelGrid. If the array is of the incorrect size it will raise
ValueError
.
Use the following methods/attributes get information about the stored data fields:
size 
Size of the arrays stored in a group. 
keys 
List of field names in a group. 
has_group 
Check if a group exists. 
has_field 
Check if a field is in a group. 
field_units 
Get units for a field. 
field_values 
Get values of a field. 
groups 
List of group names. 
i.e., call, e.g. mg.has_field(‘node’, ‘my_field_name’)
Landlab is designed to easily calculate gradients in quantities across the grid, and to construct fluxes and flux divergences from them. Because these calculations tend to be a little more involved than property lookups, the methods tend to start with calc_.
calc_diff_at_link (grid, vals, *args, **kwds) 
Calculate differences of node values over links. 
calc_flux_div_at_cell (grid, vals, *args, **kwds) 
Calculate divergence of linkbased fluxes at cells. 
calc_flux_div_at_node (grid, vals, *args, **kwds) 
Calculate divergence of linkbased fluxes at nodes. 
calc_grad_at_link (grid, vals, *args, **kwds) 
Calculate gradients of node values at links. 
calc_grad_at_patch (grid[, elevs, ...]) 
Calculate the components of the gradient at each patch. 
calc_net_flux_at_node (grid, vals, *args, **kwds) 
Calculate net link fluxes at nodes. 
calc_slope_at_node (grid[, elevs, method, ...]) 
Array of slopes at nodes, averaged over neighboring patches. 
calc_slope_at_patch (grid[, elevs, ...]) 
Calculate the slope (positive magnitude of gradient) at patches. 
calc_unit_normal_at_patch (grid[, elevs]) 
Calculate and return the unit normal vector <a, b, c> to a patch. 
These methods allow mapping of values defined on one grid element type onto a second, e.g., mapping upwind node values onto links, or mean link values onto nodes.
map_downwind_node_link_max_to_node (grid, ...) 
Map the largest magnitude of the links carrying flux from the node to the node. 
map_downwind_node_link_mean_to_node (grid, ...) 
Map the mean magnitude of the links carrying flux out of the node to the node. 
map_link_head_node_to_link (grid, var_name[, out]) 
Map values from a link head nodes to links. 
map_link_tail_node_to_link (grid, var_name[, out]) 
Map values from a link tail nodes to links. 
map_link_vector_sum_to_patch (grid, var_name) 
Map the vector sum of links around a patch to the patch. 
map_link_vector_to_nodes (q) 
Map data defined on links to nodes. 
map_max_of_link_nodes_to_link (grid, var_name) 
Map the maximum of a link’s nodes to the link. 
map_max_of_node_links_to_node (grid, var_name) 
Map the maximum value of a nodes’ links to the node. 
map_max_of_patch_nodes_to_patch (grid, var_name) 
Map the maximum value of nodes around a patch to the patch. 
map_mean_of_link_nodes_to_link (grid, var_name) 
Map the mean of a link’s nodes to the link. 
map_mean_of_patch_nodes_to_patch (grid, var_name) 
Map the mean value of nodes around a patch to the patch. 
map_min_of_link_nodes_to_link (grid, var_name) 
Map the minimum of a link’s nodes to the link. 
map_min_of_node_links_to_node (grid, var_name) 
Map the minimum value of a nodes’ links to the node. 
map_min_of_patch_nodes_to_patch (grid, var_name) 
Map the minimum value of nodes around a patch to the patch. 
map_node_to_cell (grid, var_name[, out]) 
Map values for nodes to cells. 
map_upwind_node_link_max_to_node (grid, var_name) 
Map the largest magnitude of the links bringing flux into the node to the node. 
map_upwind_node_link_mean_to_node (grid, var_name) 
Map the mean magnitude of the links bringing flux into the node to the node. 
map_value_at_downwind_node_link_max_to_node (...) 
Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 
map_value_at_max_node_to_link (grid, ...[, out]) 
Map the the value found in one node array to a link, based on the maximum value found in a second node field or array. 
map_value_at_min_node_to_link (grid, ...[, out]) 
Map the the value found in one node array to a link, based on the minimum value found in a second node field or array. 
map_value_at_upwind_node_link_max_to_node (...) 
Map the the value found in one link array to a node, based on the largest magnitude value of links bringing fluxes into the node, found in a second node array or field. 
These are the primary properties for getting and setting the grid boundary
conditions. Changes made to status_at_node()
and
status_at_node()
will automatically update the conditions
defined at other grid elements automatically.
active_faces 
Get array of active faces. 
active_links 
Get array of active links. 
active_neighbors_at_node 
Get list of neighbor node IDs. 
boundary_nodes 
Get array of boundary nodes. 
closed_boundary_nodes 
Get array of closed boundary nodes. 
core_cells 
Get array of core cells. 
core_nodes 
Get array of core nodes. 
fixed_gradient_boundary_nodes 
Get array of fixed gradient boundary nodes. 
fixed_links 
Get array of fixed links. 
fixed_value_boundary_nodes 
Get array of fixed value boundary nodes. 
node_at_core_cell 
Get array of nodes associated with core cells. 
node_is_boundary (ids[, boundary_flag]) 
Check if nodes are boundary nodes. 
number_of_active_faces 
Total number of active faces. 
number_of_active_links 
Number of active links. 
number_of_core_cells 
Number of core cells. 
number_of_core_nodes 
Number of core nodes. 
number_of_fixed_links 
Number of fixed links. 
number_of_patches_present_at_link 
Return the number of patches at a link without a closed node. 
number_of_patches_present_at_node 
Return the number of patches at a node without a closed node. 
open_boundary_nodes 
Get array of open boundary nodes. 
set_nodata_nodes_to_closed (node_data, ...) 
Make nodata nodes closed boundaries. 
set_nodata_nodes_to_fixed_gradient (...) 
Make nodata nodes fixed gradient boundaries. 
status_at_link 
Get array of the status of all links. 
status_at_node 
Get array of the boundary status for each node. 
These methods are useful in identifying subsets of nodes, e.g., closest node to a point; nodes at edges.
(None are available for this grid type)
These methods permit the kinds of surface analysis that you might expect to find in GIS software.
calc_aspect_at_node (grid[, ...]) 
Get array of aspect of a surface. 
calc_hillshade_at_node ([alt, az, slp, asp, ...]) 
Get array of hillshade. 
calc_slope_at_node (grid[, elevs, method, ...]) 
Array of slopes at nodes, averaged over neighboring patches. 
It is important that when creating a new grid class that inherits from
ModelGrid
, to call ModelGrid.__init__()
in the new grid’s
__init__()
. For example, the new class’s __init__ should contain the
following code,
class NewGrid(ModelGrid):
def __init__(self, *args, **kwds):
ModelGrid.__init__(self, **kwds)
# Code that initializes the NewGrid
Without this, the new grid class will not have the at_*
attributes.
Although the following examples use a RasterModelGrid
, they apply
equally to any grid that inherits from ModelGrid
. The new grid
comes with a set of predefined value groups. One group for each grid element.
Use the groups attribute to see the group names.
>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 3))
>>> groups = list(grid.groups)
>>> groups.sort()
>>> groups
['cell', 'corner', 'face', 'grid', 'link', 'node', 'patch']
If you just want to create an array but not add it to the grid, you can use
the ones()
method.
>>> grid.ones(at='node')
array([ 1., 1., 1., 1., 1., 1., 1., 1., 1.])
>>> list(grid.at_node.keys()) # Nothing has been added to the grid
[]
Use the add_*
methods to add value arrays attached to grid elements. Each
of these methods accepts two arguments. The first is name of the grid element
where values are associated and the second the name of the quantity. The
quantity name must be unique within a group but the same quantity can appear
in multiple goups.
>>> list(grid.at_node.keys()) # There a no values defined at grid nodes
[]
>>> z = grid.add_ones('node', 'topographic__elevation')
We now see that the array has been added to the grid as a reference to the
array returned by add_ones
.
>>> list(grid.at_node.keys())
['topographic__elevation']
>>> grid.at_node['topographic__elevation']
array([ 1., 1., 1., 1., 1., 1., 1., 1., 1.])
>>> z is grid.at_node['topographic__elevation']
True
To add a previously created array to the grid, use the
add_field()
method but be aware that it must be of the
correct size (if it’s not a ValueError
will be raised).
>>> grid.has_field('node', 'air__temperature')
False
>>> import numpy as np
>>> t = np.zeros(9)
>>> t is grid.add_field('node', 'air__temperature', t)
True
>>> grid.has_field('node', 'air__temperature')
True
>>> grid.has_field('cell', 'air__temperature')
False
>>> t is grid.at_node['air__temperature']
True