landlab

General class methods and attributes of the landlab.grid.base module

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:

Getting Information about a Grid

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

Information about the grid as a whole

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.

Information about nodes

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 nnodes-long 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 (to-node).
node_at_link_tail Get array of the node at each link tail (from-node).
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 x-coordinates of nodes.
node_y Get array of the y-coordinates 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 no-data nodes closed boundaries.
set_nodata_nodes_to_fixed_gradient(...) Make no-data 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 x-component of unit vector sums at each node.
unit_vector_sum_ycomponent_at_node Get array of y-component 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 x-coordinates of nodes.
y_of_node Get array of the y-coordinates of nodes.

Information about cells

area_of_cell Get areas of grid cells.
cell_area_at_node Cell areas in a nnodes-long 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 x-coordinates of nodes at cells.
y_of_cell Get array of the y-coordinates of nodes at cells.

Information about faces

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 x-coordinates of face midpoints.
y_of_face Get array of the y-coordinates of face midpoints.

Information about patches

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.

Information about corners

number_of_corners Total number of corners.

Data Fields in ModelGrid

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.

Create Field Arrays

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.

Add Fields to a ModelGrid

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

Query Fields

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’)

Gradients, fluxes, and divergences on the grid

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 link-based fluxes at cells.
calc_flux_div_at_node(grid, vals, \*args, \*\*kwds) Calculate divergence of link-based 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.

Mappers

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.

Boundary condition control

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 no-data nodes closed boundaries.
set_nodata_nodes_to_fixed_gradient(...) Make no-data 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.

Identifying node subsets

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)

Surface analysis

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.

Notes

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.

Examples

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 pre-defined 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']

Create Field Arrays

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
[]

Add Field Arrays

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
© Copyright 2017, The Landlab Team. Created using Sphinx 1.5.1.