landlab

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

Landlab’s regular, raster grids are implemented by the class RasterModelGrid, which inherits from ModelGrid. This text lists grid methods available for the class:

Getting Information about a Grid

The following attributes, properties, and methods provide data about a RasterModelGrid, 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.
cell_grid_shape Get the shape of the cellular grid (grid with only cells).
cell_vector_to_raster(u[, flip_vertically]) Unravel a 1D array.
cells_at_corners_of_grid Get array of cells in cellular grid (grid with only cells) corners.
dx Get node spacing in the column direction.
dy Get node spacing in the row direction.
extent Extent of the grid in the y and x-dimensions.
from_dict(params) Create a RasterModelGrid from a dictionary.
grid_xdimension Length of the grid in the x-dimension.
grid_ydimension Length of the grid in the y-dimension.
imshow(group, var_name, \*\*kwds) Plot a data field.
is_point_on_grid(xcoord, ycoord) Check if a point is on the grid.
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.
node_vector_to_raster(u[, flip_vertically]) Unravel an array of node values.
nodes_at_corners_of_grid Get array of the nodes in grid corners.
number_of_cell_columns Number of cell columns.
number_of_cell_rows Number of cell rows.
number_of_elements(name) Number of instances of an element.
number_of_node_columns Number of node columns.
number_of_node_rows Number of node rows.
save(path[, names, format, at]) Save a grid and fields.
shape Get the shape of the grid.
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).
find_nearest_node(coords[, mode]) Node nearest a point.
fixed_gradient_boundary_nodes Get array of fixed gradient boundary nodes.
fixed_value_boundary_nodes Get array of fixed value boundary nodes.
grid_coords_to_node_id(\*args, \*\*kwds) Convert node indices to node ID.
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_has_boundary_neighbor(ids[, method]) Check if nodes have neighbors that are boundary nodes.
node_is_boundary(ids[, boundary_flag]) Check if nodes are boundary nodes.
node_is_core([ids]) Check if a node is a core node.
node_vector_to_raster(u[, flip_vertically]) Unravel an array of node values.
node_x Get array of the x-coordinates of nodes.
node_y Get array of the y-coordinates of nodes.
nodes Get a shaped array of nodes.
nodes_are_all_core(ids) Check if nodes are all core.
nodes_around_point(xcoord, ycoord) Get the nodes surrounding a point.
nodes_at_bottom_edge Get nodes along the bottom edge of a grid.
nodes_at_corners_of_grid Get array of the nodes in grid corners.
nodes_at_edge(edge) Get edge nodes by edge name.
nodes_at_left_edge Get nodes along the left edge of a grid.
nodes_at_patch Get array of nodes of a patch.
nodes_at_right_edge Get nodes along the right edge of a grid.
nodes_at_top_edge Get nodes along the top edge of a grid.
number_of_cell_columns Number of cell columns.
number_of_core_nodes Number of core nodes.
number_of_interior_nodes Number of interior nodes.
number_of_links_at_node Number of links connected to each node.
number_of_node_columns Number of node columns.
number_of_node_rows Number of node rows.
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_at_node Get array of patches attached to nodes.
patches_present_at_node A boolean array, False where a patch has a closed node or is missing.
roll_nodes_ud(data_name, shift[, interior_only]) Roll (shift) specified data on nodes up or down in a raster grid.
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.
shape Get the shape of the grid.
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.
cell_grid_shape Get the shape of the cellular grid (grid with only cells).
cell_vector_to_raster(u[, flip_vertically]) Unravel a 1D array.
cells_at_corners_of_grid Get array of cells in cellular grid (grid with only cells) corners.
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_cell_rows Number of cell rows.
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.
second_ring_looped_neighbors_at_cell Get list of second ring looped neighbor cell IDs (all 16 neighbors).
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

links_at_patch Get array of links defining each patch.
nodes_at_patch Get array of nodes of a patch.
number_of_patches Number of 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_at_link Get array of patches adjoined to each link.
patches_at_node Get array of patches attached to nodes.
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).

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

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_across_cell_corners(grid, vals, ...) Get gradients to diagonally opposite nodes.
calc_grad_across_cell_faces(grid, vals, ...) Get gradients across the faces of a cell.
calc_grad_along_node_links(grid, vals, ...) Get gradients along links touching a node.
calc_grad_at_active_link(grid, vals, \*args, ...) Calculate gradients over active links.
calc_grad_at_link(grid, vals, \*args, \*\*kwds) Calculate gradients in node_values at links.
calc_grad_at_patch(grid[, elevs, ...]) Calculate the components of the gradient of each raster patch.
calc_net_flux_at_node(grid, vals, \*args, \*\*kwds) Calculate net link fluxes at nodes.
calc_slope_at_cell_subtriangles(grid[, ...]) Calculate the slope (positive magnitude of gradient) at each of the eight cell subtriangles.
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 raster patches.
calc_unit_normal_at_patch([elevs]) Calculate and return the unit normal vector <a, b, c> to a patch.
calc_unit_normals_at_cell_subtriangles(grid) Calculate unit normals on a cell.
calc_unit_normals_at_patch_subtriangles(grid) Calculate unit normals on 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_inlinks_to_node(grid, var_name[, out]) Map the maximum of links entering a node to the node.
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_outlinks_to_node(grid, var_name) Map the max of links leaving a node 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_horizontal_active_links_to_node(...) Map the mean of active links in the x direction touching node to the node.
map_mean_of_horizontal_links_to_node(grid, ...) Map the mean of links in the x direction touching a node to the node.
map_mean_of_inlinks_to_node(grid, var_name) Map the mean of links entering a node to the node.
map_mean_of_link_nodes_to_link(grid, var_name) Map the mean of a link’s nodes to the link.
map_mean_of_links_to_node(grid, var_name[, out]) Map the mean of links touching a node to the node.
map_mean_of_outlinks_to_node(grid, var_name) Map the mean of links leaving a node to the node.
map_mean_of_patch_nodes_to_patch(grid, var_name) Map the mean value of nodes around a patch to the patch.
map_mean_of_vertical_active_links_to_node(...) Map the mean of active links in the y direction touching node to the node.
map_mean_of_vertical_links_to_node(grid, ...) Map the mean of links in the y direction touching a node to the node.
map_min_of_inlinks_to_node(grid, var_name[, out]) Map the minimum of links entering a node to the node.
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_outlinks_to_node(grid, var_name) Map the min of links leaving a node 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_sum_of_inlinks_to_node(grid, var_name[, out]) Map the sum of links entering a node to the node.
map_sum_of_outlinks_to_node(grid, var_name) Map the sum of links leaving a node to the node.
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_has_boundary_neighbor(ids[, method]) Check if nodes have neighbors that are boundary nodes.
node_is_boundary(ids[, boundary_flag]) Check if nodes are boundary nodes.
node_is_core([ids]) Check if a node is a core node.
nodes_are_all_core(ids) Check if nodes are all core.
nodes_at_bottom_edge Get nodes along the bottom edge of a grid.
nodes_at_edge(edge) Get edge nodes by edge name.
nodes_at_left_edge Get nodes along the left edge of a grid.
nodes_at_right_edge Get nodes along the right edge of a grid.
nodes_at_top_edge Get nodes along the top edge of a grid.
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.
second_ring_looped_neighbors_at_cell Get list of second ring looped neighbor cell IDs (all 16 neighbors).
set_closed_boundaries_at_grid_edges(...) Set boundary not to be closed.
set_fixed_link_boundaries_at_grid_edges(...) Create fixed link boundaries at the grid edges.
set_fixed_value_boundaries_at_grid_edges(...) Create fixed values boundaries.
set_looped_boundaries(top_bottom_are_looped, ...) Create wrap-around boundaries.
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.
set_open_nodes_disconnected_from_watershed_to_closed(...) Identifys all non-closed nodes that are disconnected from the node given in outlet_id and sets them as closed.
set_status_at_node_on_edges(grid[, right, ...]) Set node status on grid edges.
set_watershed_boundary_condition(node_data) Finds the node adjacent to a boundary node with the smallest value.
set_watershed_boundary_condition_outlet_coords(...) Set the boundary conditions for a watershed.
set_watershed_boundary_condition_outlet_id(...) Set the boundary conditions for a watershed.
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.

cells_at_corners_of_grid Get array of cells in cellular grid (grid with only cells) corners.
find_nearest_node(coords[, mode]) Node nearest a point.
grid_coords_to_node_id(\*args, \*\*kwds) Convert node indices to node ID.
is_point_on_grid(xcoord, ycoord) Check if a point is on the grid.
nodes_around_point(xcoord, ycoord) Get the nodes surrounding a point.
nodes_at_bottom_edge Get nodes along the bottom edge of a grid.
nodes_at_corners_of_grid Get array of the nodes in grid corners.
nodes_at_edge(edge) Get edge nodes by edge name.
nodes_at_left_edge Get nodes along the left edge of a grid.
nodes_at_right_edge Get nodes along the right edge of a grid.
nodes_at_top_edge Get nodes along the top edge of a grid.
set_closed_boundaries_at_grid_edges(...) Set boundary not to be closed.
set_fixed_link_boundaries_at_grid_edges(...) Create fixed link boundaries at the grid edges.
set_fixed_value_boundaries_at_grid_edges(...) Create fixed values boundaries.
set_looped_boundaries(top_bottom_are_looped, ...) Create wrap-around boundaries.

Surface analysis

These methods permit the kinds of surface analysis that you might expect to find in GIS software.

calc_aspect_at_cell_subtriangles(grid[, ...]) Get tuple of arrays of aspect of each of the eight cell subtriangles.
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.

© Copyright 2017, The Landlab Team. Created using Sphinx 1.5.1.