landlab

The Landlab.

Package name:

TheLandlab

Release date:

2018-09-18

Authors:

Greg Tucker, Nicole Gasparini, Erkan Istanbulluoglu, Daniel Hobley, Sai Nudurupati, Jordan Adams, Eric Hutton, Katherine Barnhart, Margaux Mouchene, Nathon Lyons

URL:

https://landlab.readthedocs.io/en/release/

License:

MIT

class Component(*args, **kwds)

Base component class from which Landlab components inherit.

cite_as = ''

property coords

Return the coordinates of nodes on grid attached to the component.

property current_time

Current time.

Some components may keep track of the current time. In this case, the current_time attribute is incremented. Otherwise it is set to None.

Return type:

current_time

definitions = ()

classmethod from_path(grid, path)

Create a component from an input file.

Parameters:

• grid (ModelGrid) – A landlab grid.

• path (str or file_like) – Path to a parameter file, contents of a parameter file, or a file-like object.

Returns:

A newly-created component.

Return type:

Component

property grid

Return the grid attached to the component.

initialize_optional_output_fields()

Create fields for a component based on its optional field outputs, if declared in _optional_var_names.

This method will create new fields (without overwrite) for any fields output by the component as optional. New fields are initialized to zero. New fields are created as arrays of floats, unless the component also contains the specifying property _var_type.

initialize_output_fields(values_per_element=None)

Create fields for a component based on its input and output var names.

This method will create new fields (without overwrite) for any fields output by, but not supplied to, the component. New fields are initialized to zero. Ignores optional fields. New fields are created as arrays of floats, unless the component specifies the variable type.

Parameters:

values_per_element (int (optional)) – On occasion, it is necessary to create a field that is of size (n_grid_elements, values_per_element) instead of the default size (n_grid_elements,). Use this keyword argument to acomplish this task.

input_var_names = ()

name = None

optional_var_names = ()

output_var_names = ()

property shape

Return the grid shape attached to the component, if defined.

unit_agnostic = None

units = ()

classmethod var_definition(name)

Get a description of a particular field.

Parameters:

name (str) – A field name.

Returns:

A description of each field.

Return type:

tuple of (name, *description*)

classmethod var_help(name)

Print a help message for a particular field.

Parameters:

name (str) – A field name.

classmethod var_loc(name)

Location where a particular variable is defined.

Parameters:

name (str) – A field name.

Returns:

The location (‘node’, ‘link’, etc.) where a variable is defined.

Return type:

str

var_mapping = ()

classmethod var_type(name)

Returns the dtype of a field (float, int, bool, str…).

Parameters:

name (str) – A field name.

Returns:

The dtype of the field.

Return type:

dtype

classmethod var_units(name)

Get the units of a particular field.

Parameters:

name (str) – A field name.

Returns:

Units for the given field.

Return type:

str

class ExampleData(example, case='')

property base

fetch()

Fetch landlab example data files.

Examples

>>> data = ExampleData("io/shapefile")
>>> sorted(data)
['methow', 'redb', 'soque']

>>> import os
>>> data.fetch()  
>>> sorted(os.listdir())  
['methow', 'redb', 'soque']

exception FieldError(field)

Raise this error for a missing field name.

class FramedVoronoiGrid(shape, xy_spacing=(1.0, 1.0), xy_of_lower_left=(0.0, 0.0), xy_min_spacing=(0.5, 0.5), seed=200, xy_of_reference=(0.0, 0.0), xy_axis_name=('x', 'y'), xy_axis_units='-')

A grid of Voronoi Delaunay cells with a structured perimeter layout.

This inherited class implements a irregular 2D grid with Voronoi Delaunay cells and irregular patches. It is a special type of VoronoiDelaunayGrid grid in which the initial set of points is arranged in a fixed lattice (e.g. like a RasterModelGrid), named here “layout”, and the core points are then moved a random distance from their initial positions, bounded by a user-supplied threshold.

Examples

Create a grid with 3 rows and 2 columns of nodes.

>>> from landlab import FramedVoronoiGrid
>>> grid = FramedVoronoiGrid((3, 2), xy_spacing=1.0)
>>> grid.number_of_nodes
6

>>> grid = FramedVoronoiGrid(
...     (4, 3), xy_spacing=(10.0, 10.0), xy_min_spacing=(5.0, 5.0), seed=200
... )
>>> grid.status_at_node.reshape(grid.shape)
array([[1, 1, 1],
       [1, 0, 1],
       [1, 0, 1],
       [1, 1, 1]], dtype=uint8)
>>> grid.x_of_node[3]
0.0
>>> grid.x_of_node[5]
20.0
>>> grid.y_of_node[0::3]
array([  0.   ,   7.499,  17.499,  30.   ])

>>> grid = FramedVoronoiGrid(
...     (3, 5), xy_spacing=(10.0, 10.0), xy_min_spacing=5.0, seed=None
... )
>>> grid.boundary_nodes
array([ 0,  1,  2,  3,  4,  5,  9, 10, 11, 12, 13, 14])

Create a grid of voronoi cells with a structured perimeter.

Create an irregular 2D grid with voronoi cells and triangular patches. It is a special type of VoronoiDelaunayGrid in which the initial set of points is arranged in a regular lattice determined by the parameters shape, and xy_spacing. The coordinates of the core points are then randomly moved while the perimeter points remaining fixed, in a way determined by the parameters xy_min_spacing, and seed.

Parameters:

• shape (tuple of int) – Number of rows and columns of nodes.

• xy_spacing (float or tuple of float, optional) – Node spacing along x and y coordinates. If float, same spacing at x and y.

• xy_of_lower_left (tuple, optional) – Minimum x-of-node and y-of-node values. Depending on the grid, there may not be a node at this coordinate.

• xy_min_spacing (float or tuple of float, optional) – Final minimal spacing between nodes. Random moves of the core nodes from their initial positions cannot be above this threshold: (xy_spacing - xy_min_spacing) / 2 If float, same minimal spacing for x and y.

• seed (int, optional) – Seed used to generate the random x and y moves. When set, controls the pseudo-randomness of moves to ensure reproducibility. When None, the seed is random and the moves of coordinates are completely random.

• xy_of_reference (tuple, optional) – Coordinate value in projected space of the reference point, xy_of_lower_left.

• xy_axis_name (tuple of str, optional) – x and y axis names.

• xy_axis_units (str, optional) – x and y axis units.

Returns:

A newly-created grid.

Return type:

FramedVoronoiGrid

Examples

Create a grid with 3 rows and 2 columns of nodes.

>>> from landlab import FramedVoronoiGrid
>>> grid = FramedVoronoiGrid((3, 2), xy_spacing=1.0)
>>> grid.number_of_nodes
6

__init__(shape, xy_spacing=(1.0, 1.0), xy_of_lower_left=(0.0, 0.0), xy_min_spacing=(0.5, 0.5), seed=200, xy_of_reference=(0.0, 0.0), xy_axis_name=('x', 'y'), xy_axis_units='-')

Create a grid of voronoi cells with a structured perimeter.

Create an irregular 2D grid with voronoi cells and triangular patches. It is a special type of VoronoiDelaunayGrid in which the initial set of points is arranged in a regular lattice determined by the parameters shape, and xy_spacing. The coordinates of the core points are then randomly moved while the perimeter points remaining fixed, in a way determined by the parameters xy_min_spacing, and seed.

Parameters:

• shape (tuple of int) – Number of rows and columns of nodes.

• xy_spacing (float or tuple of float, optional) – Node spacing along x and y coordinates. If float, same spacing at x and y.

• xy_of_lower_left (tuple, optional) – Minimum x-of-node and y-of-node values. Depending on the grid, there may not be a node at this coordinate.

• xy_min_spacing (float or tuple of float, optional) – Final minimal spacing between nodes. Random moves of the core nodes from their initial positions cannot be above this threshold: (xy_spacing - xy_min_spacing) / 2 If float, same minimal spacing for x and y.

• seed (int, optional) – Seed used to generate the random x and y moves. When set, controls the pseudo-randomness of moves to ensure reproducibility. When None, the seed is random and the moves of coordinates are completely random.

• xy_of_reference (tuple, optional) – Coordinate value in projected space of the reference point, xy_of_lower_left.

• xy_axis_name (tuple of str, optional) – x and y axis names.

• xy_axis_units (str, optional) – x and y axis units.

Returns:

A newly-created grid.

Return type:

FramedVoronoiGrid

Examples

Create a grid with 3 rows and 2 columns of nodes.

>>> from landlab import FramedVoronoiGrid
>>> grid = FramedVoronoiGrid((3, 2), xy_spacing=1.0)
>>> grid.number_of_nodes
6

property active_adjacent_corners_at_corner

Adjacent corners for each grid corner.

See also

active_adjacent_nodes_at_node

property active_face_dirs_at_corner

Return face directions into each corner.

See also

active_link_dirs_at_node

property all_corner_azimuths_map

Get azimuths from every corner to every other corner.

See also

all_node_azimuths_map

property all_corner_distances_map

Get distances from every corner to every other corner.

See also

all_node_distances_map

property angle_of_face_about_head

Find and return the angle of a face about the corner at the face head.

See also

angle_of_link_about_head

property boundary_corners

Get array of boundary corners.

See also

boundary_nodes

property cells_present_at_corner

A boolean array, False where a cell has a closed corner or is

See also

patches_present_at_node

property cells_present_at_face

A boolean array, False where a cell has a closed corner or is

See also

patches_present_at_link

property closed_boundary_corners

Get array of closed boundary corners.

See also

closed_boundary_nodes

property core_corners

Get array of core corners.

See also

core_nodes

property core_patches

Get array of core patches.

See also

core_cells

property corner_at_core_patch

Get array of corners associated with core patches.

See also

node_at_core_cell

property face_status_at_corner

property fixed_faces

Get array of fixed faces.

See also

fixed_links

property fixed_gradient_boundary_corner_anchor_corner

Returns the corner at the other end of the fixed face for a fixed

See also

fixed_gradient_boundary_node_anchor_node

property fixed_gradient_boundary_corner_fixed_face

An array of the fixed_faces connected to fixed gradient boundary

See also

fixed_gradient_boundary_node_fixed_link

property fixed_gradient_boundary_corners

Get array of fixed gradient boundary corners.

See also

fixed_gradient_boundary_nodes

property fixed_value_boundary_corners

Get array of fixed value boundary corners.

See also

fixed_value_boundary_nodes

classmethod from_dict(kwds)

Create grid from dictionary.

Parameters:

params (dictionary) – Dictionary of required parameters to create a model grid.

Examples

>>> from landlab import RasterModelGrid
>>> params = {"shape": (3, 4), "xy_spacing": 2}
>>> grid = RasterModelGrid.from_dict(params)
>>> grid.x_of_node
array([ 0.,  2.,  4.,  6.,  0.,  2.,  4.,  6.,  0.,  2.,  4.,  6.])
>>> grid.y_of_node
array([ 0.,  0.,  0.,  0.,  2.,  2.,  2.,  2.,  4.,  4.,  4.,  4.])

property number_of_cells_present_at_corner

Return the number of cells at a corner without a closed corner.

See also

number_of_patches_present_at_node

property number_of_cells_present_at_face

Return the number of cells at a face without a closed corner.

See also

number_of_patches_present_at_link

property number_of_core_corners

Number of core corners.

See also

number_of_core_nodes

property number_of_core_patches

Number of core patches.

See also

number_of_core_cells

property number_of_fixed_faces

Number of fixed faces.

See also

number_of_fixed_links

property open_boundary_corners

Get array of open boundary corners.

See also

open_boundary_nodes

property patch_area_at_corner

Cell areas in a ncorners-long array.

See also

cell_area_at_node

property status_at_corner

Get array of the boundary status for each corner.

See also

status_at_node

property status_at_face

Get array of the status of all faces.

See also

status_at_link

property unit_vector_sum_xcomponent_at_corner

Get array of x-component of unit vector sums at each corner.

See also

unit_vector_sum_xcomponent_at_node

property unit_vector_sum_ycomponent_at_corner

Get array of y-component of unit vector sums at each corner.

See also

unit_vector_sum_ycomponent_at_node

class HexModelGrid(shape, spacing=1.0, xy_of_lower_left=(0.0, 0.0), orientation='horizontal', node_layout='hex', reorient_links=True, xy_of_reference=(0.0, 0.0), xy_axis_name=('x', 'y'), xy_axis_units='-')

A grid of hexagonal cells.

This inherited class implements a regular 2D grid with hexagonal cells and triangular patches. It is a special type of VoronoiDelaunay grid in which the initial set of points is arranged in a triangular/hexagonal lattice.

Examples

Create a hex grid with 2 rows of nodes. The first and third rows will have 2 nodes, and the second nodes.

>>> from landlab import HexModelGrid
>>> grid = HexModelGrid((3, 2), spacing=1.0)
>>> grid.number_of_nodes
7

>>> grid = HexModelGrid((3, 3), node_layout="rect", spacing=2.0)
>>> grid.status_at_node
array([1, 1, 1, 1, 0, 1, 1, 1, 1], dtype=uint8)
>>> grid = HexModelGrid((3, 3), node_layout="rect", orientation="vertical")
>>> grid.status_at_node
array([1, 1, 1, 1, 1, 0, 1, 1, 1], dtype=uint8)
>>> grid = HexModelGrid((4, 4), node_layout="rect", orientation="vertical")
>>> grid.status_at_node
array([1, 1, 1, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 1, 1, 1], dtype=uint8)
>>> grid.boundary_nodes
array([ 0,  1,  2,  3,  4,  7,  8, 11, 12, 13, 14, 15])
>>> grid = HexModelGrid((3, 4), node_layout="rect")
>>> grid.status_at_node
array([1, 1, 1, 1, 1, 0, 0, 1, 1, 1, 1, 1], dtype=uint8)

Create a grid of hexagonal cells.

Create a regular 2D grid with hexagonal cells and triangular patches. It is a special type of VoronoiModelGrid in which the initial set of points is arranged in a triangular/hexagonal lattice.

Parameters:

• shape (tuple of int) – Number of rows and columns of nodes.

• spacing (float, optional) – Node spacing.

• xy_of_lower_left (tuple of float, optional) – Minimum x-of-node and y-of-node values. Depending on the grid no node may be present at this coordinate. Default is (0., 0.).

• xy_of_reference (tuple of float, optional) – Coordinate value in projected space of the reference point, xy_of_lower_left. Default is (0., 0.)

• orientation (str, optional) – One of the 3 cardinal directions in the grid, either ‘horizontal’ (default) or ‘vertical’

• node_layout ({"hex", "rect"}) – The grid layout of nodes.

• reorient_links (bool, optional) – Whether or not to re-orient all links to point between -45 deg and +135 deg clockwise from “north” (i.e., along y axis). default is True.

Returns:

A newly-created grid.

Return type:

HexModelGrid

Examples

Create a hex grid with 2 rows of nodes. The first and third rows will have 2 nodes, and the second nodes.

>>> from landlab import HexModelGrid
>>> hmg = HexModelGrid((3, 2), spacing=1.0)
>>> hmg.number_of_nodes
7

__init__(shape, spacing=1.0, xy_of_lower_left=(0.0, 0.0), orientation='horizontal', node_layout='hex', reorient_links=True, xy_of_reference=(0.0, 0.0), xy_axis_name=('x', 'y'), xy_axis_units='-')

Create a grid of hexagonal cells.

Create a regular 2D grid with hexagonal cells and triangular patches. It is a special type of VoronoiModelGrid in which the initial set of points is arranged in a triangular/hexagonal lattice.

Parameters:

• shape (tuple of int) – Number of rows and columns of nodes.

• spacing (float, optional) – Node spacing.

• xy_of_lower_left (tuple of float, optional) – Minimum x-of-node and y-of-node values. Depending on the grid no node may be present at this coordinate. Default is (0., 0.).

• xy_of_reference (tuple of float, optional) – Coordinate value in projected space of the reference point, xy_of_lower_left. Default is (0., 0.)

• orientation (str, optional) – One of the 3 cardinal directions in the grid, either ‘horizontal’ (default) or ‘vertical’

• node_layout ({"hex", "rect"}) – The grid layout of nodes.

• reorient_links (bool, optional) – Whether or not to re-orient all links to point between -45 deg and +135 deg clockwise from “north” (i.e., along y axis). default is True.

Returns:

A newly-created grid.

Return type:

HexModelGrid

Examples

Create a hex grid with 2 rows of nodes. The first and third rows will have 2 nodes, and the second nodes.

>>> from landlab import HexModelGrid
>>> hmg = HexModelGrid((3, 2), spacing=1.0)
>>> hmg.number_of_nodes
7

property active_adjacent_corners_at_corner

Adjacent corners for each grid corner.

See also

active_adjacent_nodes_at_node

property active_face_dirs_at_corner

Return face directions into each corner.

See also

active_link_dirs_at_node

property all_corner_azimuths_map

Get azimuths from every corner to every other corner.

See also

all_node_azimuths_map

property all_corner_distances_map

Get distances from every corner to every other corner.

See also

all_node_distances_map

property angle_of_face_about_head

Find and return the angle of a face about the corner at the face head.

See also

angle_of_link_about_head

as_dataset(include='*', exclude=None, time=None)

Create an xarray Dataset representation of a grid.

This method creates a new xarray Dataset object that contains the grid’s data fields. A particular grid type (e.g. a RasterModelGrid) should define its own as_dataset method to represent that particular grid type as a Dataset and then call this method to add the data fields.

Parameters:

• include (str or iterable or str) – Glob-style patterns of fields to include in the dataset.

• exclude (str or iterable or str) – Glob-style patterns of fields to exclude from the dataset.

Returns:

An xarray Dataset representation of a ModelGrid.

Return type:

Dataset

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))

Add some fields to the grid. Notice that we have defined a field named “elevation” at both nodes and links.

>>> _ = grid.add_full("elevation", 3.0, at="node")
>>> _ = grid.add_full("elevation", 4.0, at="link")
>>> _ = grid.add_full("temperature", 5.0, at="node")

>>> ds = grid.as_dataset()
>>> sorted(ds.dims.items())
[('dim', 2), ('link', 17), ('node', 12)]
>>> sorted([var for var in ds.data_vars if var.startswith("at_")])
['at_link:elevation', 'at_node:elevation', 'at_node:temperature']

>>> grid.event_layers.add(1.0, rho=0.5)

>>> ds = grid.as_dataset()
>>> sorted(ds.dims.items())
[('cell', 2), ('dim', 2), ('layer', 1), ('link', 17), ('node', 12)]
>>> sorted([var for var in ds.data_vars if var.startswith("at_")])
['at_layer_cell:rho', 'at_layer_cell:thickness', 'at_link:elevation',
 'at_node:elevation', 'at_node:temperature']

property boundary_corners

Get array of boundary corners.

See also

boundary_nodes

property cells_present_at_corner

A boolean array, False where a cell has a closed corner or is

See also

patches_present_at_node

property cells_present_at_face

A boolean array, False where a cell has a closed corner or is

See also

patches_present_at_link

property closed_boundary_corners

Get array of closed boundary corners.

See also

closed_boundary_nodes

property core_corners

Get array of core corners.

See also

core_nodes

property core_patches

Get array of core patches.

See also

core_cells

property corner_at_core_patch

Get array of corners associated with core patches.

See also

node_at_core_cell

property face_status_at_corner

property fixed_faces

Get array of fixed faces.

See also

fixed_links

property fixed_gradient_boundary_corner_anchor_corner

Returns the corner at the other end of the fixed face for a fixed

See also

fixed_gradient_boundary_node_anchor_node

property fixed_gradient_boundary_corner_fixed_face

An array of the fixed_faces connected to fixed gradient boundary

See also

fixed_gradient_boundary_node_fixed_link

property fixed_gradient_boundary_corners

Get array of fixed gradient boundary corners.

See also

fixed_gradient_boundary_nodes

property fixed_value_boundary_corners

Get array of fixed value boundary corners.

See also

fixed_value_boundary_nodes

classmethod from_dataset(dataset)

classmethod from_dict(kwds)

Create grid from dictionary.

Parameters:

params (dictionary) – Dictionary of required parameters to create a model grid.

Examples

>>> from landlab import RasterModelGrid
>>> params = {"shape": (3, 4), "xy_spacing": 2}
>>> grid = RasterModelGrid.from_dict(params)
>>> grid.x_of_node
array([ 0.,  2.,  4.,  6.,  0.,  2.,  4.,  6.,  0.,  2.,  4.,  6.])
>>> grid.y_of_node
array([ 0.,  0.,  0.,  0.,  2.,  2.,  2.,  2.,  4.,  4.,  4.,  4.])

hexplot(data, data_label=None, color_map=None)

Create a plot of the grid elements.

Creates a plot of the grid and one node-data field, showing hexagonal cells colored by values in the field.

Parameters:

• data (str or (n_nodes,) ndarray) – Data field to be colored.

• data_label (str, optional) – Label for colorbar.

• color_map (matplotlib colormap object, None) – Color map to apply (defaults to “jet”)

See also

imshow_grid

Another Landlab function capable of producing hexplots, with a fuller-featured set of options.

node_row_and_column(node_id)

Row and column from node ID, FOR VERT RECT CONFIGURATION ONLY.

Examples

>>> from landlab import HexModelGrid
>>> grid = HexModelGrid((3, 4), node_layout="rect", orientation="vertical")
>>> grid.node_row_and_column(5)
(1, 2)
>>> grid = HexModelGrid((3, 5), node_layout="rect", orientation="vertical")
>>> grid.node_row_and_column(13)
(2, 1)

property number_of_cells_present_at_corner

Return the number of cells at a corner without a closed corner.

See also

number_of_patches_present_at_node

property number_of_cells_present_at_face

Return the number of cells at a face without a closed corner.

See also

number_of_patches_present_at_link

property number_of_core_corners

Number of core corners.

See also

number_of_core_nodes

property number_of_core_patches

Number of core patches.

See also

number_of_core_cells

property number_of_corner_columns

Number of corner columns hex grid.

See also

number_of_node_columns

property number_of_corner_rows

Number of corner rows in a rectangular-shaped and/or horizontally

See also

number_of_node_rows

property number_of_fixed_faces

Number of fixed faces.

See also

number_of_fixed_links

property number_of_node_columns

Number of node columns hex grid.

Number of node columns in a rectangular-shaped and/or vertically oriented hex grid.

Returns the number of columns, including boundaries.

Notes

Will generate an error if called with a hex-shaped, horizontally aligned grid.

Examples

>>> from landlab import HexModelGrid
>>> grid = HexModelGrid((5, 5), node_layout="rect")
>>> grid.number_of_node_columns
5

property number_of_node_rows

Number of node rows in a rectangular-shaped and/or horizontally oriented hex grid.

Returns the number of rows, including boundaries.

Notes

Will generate an error if called with a hex-shaped, vertically aligned grid.

Examples

>>> from landlab import HexModelGrid
>>> grid = HexModelGrid((5, 5), node_layout="rect")
>>> grid.number_of_node_rows
5

property open_boundary_corners

Get array of open boundary corners.

See also

open_boundary_nodes

property patch_area_at_corner

Cell areas in a ncorners-long array.

See also

cell_area_at_node

set_watershed_boundary_condition(node_data, nodata_value=-9999.0, return_outlet_id=False)

Find the node adjacent to a boundary node with the smallest value.

This node is set as the outlet. The outlet node must have a data value. Can return the outlet id as a one element numpy array if return_outlet_id is set to True.

All nodes with nodata_value are set to CLOSED (grid.status_at_node == 4). All nodes with data values are set to CORE (grid.status_at_node == 0), with the exception that the outlet node is set to a FIXED_VALUE (grid.status_at_node == 1).

Note that the outer ring (perimeter) of the grid is set to CLOSED, even if there are nodes that have values. The only exception to this would be if the outlet node is on the perimeter, which is acceptable.

This routine assumes that all of the nodata_value are on the outside of the data values. In other words, there are no islands of nodata_value surrounded by nodes with data.

This also assumes that the grid has a single watershed (that is a single outlet node).

Parameters:

• node_data (str or (n_nodes,) ndarray) – At-node field name or at-node data values to use for identifying watershed location.

• nodata_value (float, optional) – Value that indicates an invalid value.

• return_outlet_id (bool, optional) – Indicates whether or not to return the id of the found outlet

Examples

The example will use a HexModelGrid with node data values as illustrated:

      1. ,  2. ,  3. ,  4. ,
  0.5,  1.5,  2.5,  3.5,  4.5,
0. ,  1. ,  2. ,  3. ,  4. ,  5.,
  0.5,  1.5,  2.5,  3.5,  4.5,
      1. ,  2. ,  3. ,  4.

>>> from landlab import HexModelGrid
>>> hmg = HexModelGrid((5, 4))
>>> z = hmg.add_zeros("topographic__elevation", at="node")
>>> z += hmg.x_of_node + 1.0
>>> out_id = hmg.set_watershed_boundary_condition(z, -9999.0, True)
>>> out_id
array([9])
>>> hmg.status_at_node
array([4, 4, 4, 4, 4, 0, 0, 0, 4, 1, 0, 0, 0, 0, 4, 4, 0, 0, 0, 4, 4, 4, 4,
   4], dtype=uint8)

set_watershed_boundary_condition_outlet_id(outlet_id, node_data, nodata_value=-9999.0)

Set the boundary conditions for a watershed.

All nodes with nodata_value are set to CLOSED. All nodes with data values are set to CORE, with the exception that the outlet node is set to a FIXED_VALUE.

Note that the outer ring of the HexModelGrid is set to CLOSED, even if there are nodes that have values. The only exception to this would be if the outlet node is on the boundary, which is acceptable.

Assumes that the id of the outlet is already known.

This assumes that the grid has a single watershed. If this is not the case this will not work.

Parameters:

• outlet_id (int) – id of the outlet node

• node_data (str or (n_nodes,) ndarray) – At-node field name or at-node data values to use for identifying watershed location.

• nodata_value (float, optional) – Value that indicates an invalid value.

Examples

The example will use a HexModelGrid with node data values as illustrated:

      1. ,  2. ,  3. ,  4. ,
  0.5,  1.5,  2.5,  3.5,  4.5,
0. ,  1. ,  2. ,  3. ,  4. ,  5.,
  0.5,  1.5,  2.5,  3.5,  4.5,
      1. ,  2. ,  3. ,  4.

>>> from landlab import HexModelGrid
>>> hmg = HexModelGrid((5, 4))
>>> z = hmg.add_zeros("topographic__elevation", at="node")
>>> z += hmg.x_of_node + 1.0

>>> hmg.status_at_node
array([1, 1, 1, 1, 1, 0, 0, 0, 1, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 1, 1, 1, 1,
   1], dtype=uint8)

>>> outlet = hmg.set_watershed_boundary_condition_outlet_id(9, z, -9999.0)
>>> hmg.status_at_node
array([4, 4, 4, 4, 4, 0, 0, 0, 4, 1, 0, 0, 0, 0, 4, 4, 0, 0, 0, 4, 4, 4, 4,
   4], dtype=uint8)

property status_at_corner

Get array of the boundary status for each corner.

See also

status_at_node

property status_at_face

Get array of the status of all faces.

See also

status_at_link

property unit_vector_sum_xcomponent_at_corner

Get array of x-component of unit vector sums at each corner.

See also

unit_vector_sum_xcomponent_at_node

property unit_vector_sum_ycomponent_at_corner

Get array of y-component of unit vector sums at each corner.

See also

unit_vector_sum_ycomponent_at_node

property xy_of_lower_left

Return (x, y) of the reference point.

class LinkStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Define the link types

ACTIVE = 0

Indicate a link is active, and can carry flux

FIXED = 2

Indicate a link has a fixed (gradient) value, & behaves as a boundary

INACTIVE = 4

Indicate a link is inactive, and cannot carry flux

exception MissingKeyError(key)

Error to indicate a missing parameter key.

Raise this error if the parameter dictionary file does not contain a requested key.

class ModelGrid(**kwds)

Base class for 2D structured or unstructured grids for numerical models.

The idea is to have at least two inherited classes, RasterModelGrid and DelaunayModelGrid, that can create and manage grids. To this might be added a GenericModelGrid, which would be an unstructured polygonal grid that doesn’t necessarily obey or understand the Delaunay triangulation, but rather simply accepts an input grid from the user. Also a HexModelGrid for hexagonal.

Parameters:

• axis_name (tuple, optional) – Name of axes

• axis_units (tuple, optional) – Units of coordinates

Create a new collection of field groups.

BAD_INDEX = -1

Indicates a node is bad index.

BC_LINK_IS_ACTIVE = 0

Indicates a link is active, and can carry flux

BC_LINK_IS_FIXED = 2

Indicates a link has a fixed gradient value, and behaves as a boundary

BC_LINK_IS_INACTIVE = 4

Indicates a link is inactive, and cannot carry flux

BC_NODE_IS_CLOSED = 4

Indicates a boundary node is closed

BC_NODE_IS_CORE = 0

Indicates a node is core.

BC_NODE_IS_FIXED_GRADIENT = 2

Indicates a boundary node has a fixed gradient.

BC_NODE_IS_FIXED_VALUE = 1

Indicates a boundary node has a fixed value.

BC_NODE_IS_LOOPED = 3

Indicates a boundary node is wrap-around.

VALID_LOCATIONS = ('node', 'link', 'patch', 'corner', 'face', 'cell', 'grid')

Grid elements on which fields can be placed.

property active_adjacent_nodes_at_node

Adjacent nodes for each grid node.

For each grid node, get the adjacent nodes ordered counterclockwise starting from the positive x axis.

Examples

>>> from landlab import RasterModelGrid, HexModelGrid
>>> grid = RasterModelGrid((4, 5))

>>> grid.active_adjacent_nodes_at_node[(-1, 6, 2),]
array([[-1, -1, -1, -1],
       [ 7, 11,  5,  1],
       [-1,  7, -1, -1]])

Setting a node to closed causes all links touching it to be inactive.

>>> grid.status_at_node[6] = grid.BC_NODE_IS_CLOSED
>>> grid.active_adjacent_nodes_at_node[(-1, 6, 2),]
array([[-1, -1, -1, -1],
       [-1, -1, -1, -1],
       [-1,  7, -1, -1]])

>>> grid.active_adjacent_nodes_at_node[7]
array([ 8, 12, -1,  2])
>>> grid.active_adjacent_nodes_at_node[2]
array([-1,  7, -1, -1])

>>> grid = HexModelGrid((3, 2))
>>> grid.status_at_node[0] = grid.BC_NODE_IS_CLOSED
>>> grid.active_adjacent_nodes_at_node
array([[-1, -1, -1, -1, -1, -1],
       [-1,  3, -1, -1, -1, -1],
       [ 3, -1, -1, -1, -1, -1],
       [ 4,  6,  5,  2, -1,  1],
       [-1,  3, -1, -1, -1, -1],
       [-1, -1,  3, -1, -1, -1],
       [-1,  3, -1, -1, -1, -1]])

property active_faces

Get array of active faces.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> grid.active_faces
array([0, 1, 2, 3, 4, 5, 6])

>>> grid.status_at_node[6] = grid.BC_NODE_IS_CLOSED
>>> grid.active_faces
array([0, 2, 5])

property active_link_dirs_at_node

Return link directions into each node.

A value of 1 indicates a link points toward a given node, while a value of -1 indicates a link points away from a node. Note that inactive links have a value of 0, but active and fixed links are both reported normally.

Returns:

Link directions relative to the nodes of a grid. The shape of the matrix will be number of nodes by the maximum number of links per node. A zero indicates no link at this position.

Return type:

(n_nodes, max_links_per_node) ndarray of int

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))

.--->.--->.--->.
^    ^    ^    ^
|    |    |    |
.--->5--->.--->.
^    ^    ^    ^
|    |    |    |
.--->.--->.--->.

>>> grid.active_link_dirs_at_node[5]
array([-1, -1,  1,  1], dtype=int8)

If we set the nodes along the left edge to be closed, the links attached to those nodes become inactive and so their directions are reported as 0.

>>> grid.status_at_node[grid.nodes_at_left_edge] = grid.BC_NODE_IS_CLOSED
>>> grid.active_link_dirs_at_node
array([[ 0,  0,  0,  0], [ 0, -1,  0,  0], [ 0, -1,  0,  0], [ 0,  0,  0,  0],
       [ 0,  0,  0,  0], [-1, -1,  0,  1], [-1, -1,  1,  1], [ 0,  0,  1,  0],
       [ 0,  0,  0,  0], [ 0,  0,  0,  1], [ 0,  0,  0,  1], [ 0,  0,  0,  0]],
       dtype=int8)

property active_links

Get array of active links.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> grid.active_links
array([ 4,  5,  7,  8,  9, 11, 12])

property all_node_azimuths_map

Get azimuths from every node to every other node.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> angles = grid.all_node_azimuths_map

The shape of the array is number_of_nodes by number_of_nodes and azimuth from a node to itself is zero.

>>> angles.shape == (grid.number_of_nodes, grid.number_of_nodes)
True
>>> angles.diagonal()
array([ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.])

Angles are measured in radians and increase clockwise starting at north.

>>> angles *= 180.0 / np.pi
>>> angles[0, :4]
array([  0.,  90.,  90.,  90.])
>>> angles[0, ::4]
array([ 0.,  0.,  0.])
>>> angles[0, ::5]
array([  0.,  45.,  45.])

property all_node_distances_map

Get distances from every node to every other node.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> distances = grid.all_node_distances_map

The shape of the array is number_of_nodes by number_of_nodes and distance from a node to itself is zero.

>>> distances.shape == (grid.number_of_nodes, grid.number_of_nodes)
True
>>> distances.diagonal()
array([ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.])

The distances from the first node to all nodes in its row and all the nodes in its column.

>>> distances[0, :4]
array([ 0.,  1.,  2.,  3.])
>>> distances[0, ::4]
array([ 0.,  1.,  2.])

property angle_of_link_about_head

Find and return the angle of a link about the node at the link head.

Because links have direction, their angle can be specified as an angle about either the node at the link head, or the node at the link tail. The default behaviour of angle_of_link is to return the angle about the link tail, but this method gives the angle about the link head.

Examples

>>> from landlab import HexModelGrid
>>> import numpy as np

>>> grid = HexModelGrid((3, 2), node_layout="hex")
>>> np.round(grid.angle_of_link[:3] / np.pi * 3.0)
array([ 0., 2.,  1.])
>>> np.round(grid.angle_of_link_about_head[:3] / np.pi * 3.0)  # 60 deg segments
array([ 3.,  5.,  4.])

as_dataarray(name, at=None, time=None)

Create an xarray DataArray representation of a grid field.

Parameters:

• name (str) – Name of a field. This can either be a canonical field name (of the form “at_<element>:<field_name>”, or just the field name. In the latter case, use the at keyword to specify where the field is defined.

• at (str, optional) – The grid elements on which the field is defined. Use this only if name is not a canonical field name that already contains the grid element.

Returns:

The field represented as a newly-created xarray DataArray.

Return type:

DataArray

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> _ = grid.add_full("elevation", 3.0, at="node")

>>> grid.as_dataarray("at_node:elevation")
<xarray.DataArray 'at_node:elevation' (node: 12)>
array([ 3.,  3.,  3.,  3.,  3.,  3.,  3.,  3.,  3.,  3.,  3.,  3.])
Dimensions without coordinates: node

>>> all(
...     grid.as_dataarray("at_node:elevation")
...     == grid.as_dataarray("elevation", at="node")
... )
True

as_dataset(include='*', exclude=None, time=None)

Create an xarray Dataset representation of a grid.

This method creates a new xarray Dataset object that contains the grid’s data fields. A particular grid type (e.g. a RasterModelGrid) should define its own as_dataset method to represent that particular grid type as a Dataset and then call this method to add the data fields.

Parameters:

• include (str or iterable or str) – Glob-style patterns of fields to include in the dataset.

• exclude (str or iterable or str) – Glob-style patterns of fields to exclude from the dataset.

Returns:

An xarray Dataset representation of a ModelGrid.

Return type:

Dataset

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))

Add some fields to the grid. Notice that we have defined a field named “elevation” at both nodes and links.

>>> _ = grid.add_full("elevation", 3.0, at="node")
>>> _ = grid.add_full("elevation", 4.0, at="link")
>>> _ = grid.add_full("temperature", 5.0, at="node")

>>> ds = grid.as_dataset()
>>> sorted(ds.dims.items())
[('dim', 2), ('link', 17), ('node', 12)]
>>> sorted([var for var in ds.data_vars if var.startswith("at_")])
['at_link:elevation', 'at_node:elevation', 'at_node:temperature']

>>> grid.event_layers.add(1.0, rho=0.5)

>>> ds = grid.as_dataset()
>>> sorted(ds.dims.items())
[('cell', 2), ('dim', 2), ('layer', 1), ('link', 17), ('node', 12)]
>>> sorted([var for var in ds.data_vars if var.startswith("at_")])
['at_layer_cell:rho', 'at_layer_cell:thickness', 'at_link:elevation',
 'at_node:elevation', 'at_node:temperature']

at_cell = {}

at_corner = {}

at_face = {}

at_grid = {}

at_link = {}

at_node = {}

at_patch = {}

property axis_name

Get the name of each coordinate axis.

Returns:

The names of each axis.

Return type:

tuple of str

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.axis_name
('x', 'y')
>>> grid.axis_name = ("lon", "lat")
>>> grid.axis_name
('lon', 'lat')

property axis_units

Get units for each axis.

Returns:

The units (as a string) for each of a grid’s coordinates.

Return type:

tuple of str

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5), xy_spacing=(3.0, 2.0))
>>> mg.axis_units
('-', '-')
>>> mg.axis_units = ("degrees_north", "degrees_east")
>>> mg.axis_units
('degrees_north', 'degrees_east')
>>> mg.axis_units = "m"
>>> mg.axis_units
('m', 'm')

property boundary_nodes

Get array of boundary nodes.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> mg.boundary_nodes
array([ 0,  1,  2,  3,  4,  5,  9, 10, 14, 15, 16, 17, 18, 19])

calc_aspect_at_node(slope_component_tuple=None, elevs='topographic__elevation', unit='degrees', ignore_closed_nodes=True)

Get array of aspect of a surface.

Calculates at returns the aspect of a surface. Aspect is returned as radians clockwise of north, unless input parameter units is set to ‘degrees’.

If slope_component_tuple is provided, i.e., (slope_x, slope_y), the aspect will be calculated from these data.

If it is not, it will be derived from elevation data at the nodes, which can either be a string referring to a grid field (default: ‘topographic__elevation’), or an nnodes-long numpy array of the values themselves.

If ignore_closed_nodes is False, all proximal elevation values will be used in the calculation. If True, only unclosed nodes are used.

Parameters:

• slope_component_tuple ((slope_x_array, slope_y_array) (optional)) – Tuple of components of slope in the x and y directions, defined on nodes, if already known. If not, provide elevs.

• elevs (str or array (optional)) – Node field name or node array of elevations. If slope_component_tuple is not provided, must be set, but unused otherwise.

• unit ({'degrees', 'radians'}) – Controls the unit that the aspect is returned as.

• ignore_closed_nodes (bool) – If True, do not incorporate values at closed nodes into the calc.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 4))
>>> z = mg.node_x**2 + mg.node_y**2
>>> mg.calc_aspect_at_node(elevs=z)
array([ 225.        ,  240.16585039,  255.2796318 ,  258.69006753,
        209.83414961,  225.        ,  243.54632481,  248.77808974,
        194.7203682 ,  206.45367519,  225.        ,  231.94498651,
        191.30993247,  201.22191026,  218.05501349,  225.        ])
>>> z = z.max() - z
>>> mg.calc_aspect_at_node(elevs=z)
array([ 45.        ,  60.16585039,  75.2796318 ,  78.69006753,
        29.83414961,  45.        ,  63.54632481,  68.77808974,
        14.7203682 ,  26.45367519,  45.        ,  51.94498651,
        11.30993247,  21.22191026,  38.05501349,  45.        ])

>>> mg = RasterModelGrid((4, 4), xy_spacing=(3.0, 2.0))
>>> z = mg.node_x**2 + mg.node_y**2
>>> mg.calc_aspect_at_node(elevs=z)
array([ 236.30993247,  247.52001262,  259.97326008,  262.40535663,
        220.75264634,  234.41577266,  251.13402374,  255.29210302,
        201.54258265,  215.47930877,  235.73541937,  242.24162456,
        196.69924423,  209.43534223,  229.19345757,  236.30993247])

Note that a small amount of asymmetry arises at the grid edges due to the “missing” nodes beyond the edge of the grid.

calc_diff_at_link(node_values, out=None)

Calculate differences of node values over links.

Calculates the difference in quantity node_values at each link in the grid.

Parameters:

• node_values (ndarray or field name) – Values at grid nodes.

• out (ndarray, optional) – Buffer to hold the result.

Returns:

Differences across links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((3, 3))
>>> z = np.zeros(9)
>>> z[4] = 1.0
>>> rmg.calc_diff_at_link(z)
array([ 0.,  0.,  0.,  1.,  0.,  1., -1.,  0., -1.,  0.,  0.,  0.])

calc_distances_of_nodes_to_point(coord, get_az=None, node_subset=None, out_distance=None, out_azimuth=None)

Get distances for nodes to a given point.

Returns an array of distances for each node to a provided point. If “get_az” is set to ‘angles’, returns both the distance array and an array of azimuths from up/north. If it is set to ‘displacements’, it returns the azimuths as a 2xnnodes array of x and y displacements. If it is not set, returns just the distance array.

If “node_subset” is set as an ID, or list/array/etc of IDs method returns just the distance (and optionally azimuth) for that node. Point is provided as a tuple (x,y).

If out_distance (& out_azimuth) are provided, these arrays are used to store the outputs. This is recommended for memory management reasons if you are working with node subsets.

Note

Angles are returned in radians but measured clockwise from north.

Parameters:

• coord (tuple of float) – Coodinates of point as (x, y).

• get_az ({None, 'angles', 'displacements'}, optional) – Optionally calculate azimuths as either angles or displacements. The calculated values will be returned along with the distances as the second item of a tuple.

• node_subset (array_like, optional) – Calculate distances on a subset of grid nodes. The default is to calculate distances from the provided points to all nodes.

• out_distance (array_like, optional) – If provided, put the calculated distances here. Otherwise, create a new array.

• out_azimuth (array_like, optional) – If provided, put the calculated distances here. Otherwise, create a new array.

Returns:

If get_az is None return the array of distances. Otherwise, return a tuple of distances and azimuths.

Return type:

ndarray or tuple of ndarray

Notes

Once you start working with node subsets in Landlab, which can change size between loops, it’s quite possible for Python’s internal memory management to crap out after large numbers of loops (~>10k). This is to do with the way it block allocates memory for arrays of differing lengths, then cannot free this memory effectively. The solution - as implemented here - is to pre-allocate all arrays as nnodes long, then only work with the first [len_subset] entries by slicing (in a pseudo-C-style). Care has to be taken not to “accidentally” allow Python to allocate a new array you don’t have control over. Then, to maintain efficient memory allocation, we create some “dummy” nnode-long arrays to store intermediate parts of the solution in.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))

Calculate distances from point at (2., 1.) to a subset of nodes on the grid.

>>> grid.calc_distances_of_nodes_to_point((2, 1), node_subset=(2, 6, 7, 8, 12))
array([ 1.,  1.,  0.,  1.,  1.])

Calculate distances from a point to all nodes on the grid.

>>> dist = grid.calc_distances_of_nodes_to_point((2, 1))
>>> dist.shape == (grid.number_of_nodes,)
True
>>> dist.take((2, 6, 7, 8, 12))
array([ 1.,  1.,  0.,  1.,  1.])

Put the distances into a buffer.

>>> out = np.empty(grid.number_of_nodes, dtype=float)
>>> dist = grid.calc_distances_of_nodes_to_point((2, 1), out_distance=out)
>>> out is dist
True
>>> out.take((2, 6, 7, 8, 12))
array([ 1.,  1.,  0.,  1.,  1.])

Calculate azimuths along with distances. The azimuths are calculated in radians but measured clockwise from north.

>>> (_, azim) = grid.calc_distances_of_nodes_to_point((2, 1), get_az="angles")
>>> azim.take((2, 6, 7, 8, 12)) * 180.0 / np.pi
array([ 180.,  270.,    0.,   90.,    0.])
>>> (_, azim) = grid.calc_distances_of_nodes_to_point(
...     (2, 1), get_az="angles", node_subset=(1, 3, 11, 13)
... )
>>> azim * 180.0 / np.pi
array([ 225.,  135.,  315.,   45.])

When calculating displacements, the first row contains displacements in x and the second displacements in y.

>>> (_, azim) = grid.calc_distances_of_nodes_to_point(
...     (2, 1), get_az="displacements", node_subset=(2, 6, 7, 8, 12)
... )
>>> azim
array([[ 0., -1.,  0.,  1.,  0.],
       [-1.,  0.,  0.,  0.,  1.]])

calc_flux_div_at_cell(unit_flux, out=None)

Calculate divergence of link-based fluxes at cells.

This function is very similar to the function calc_flux_div_at_node.

Given a flux per unit width across each cell face in the grid, calculate the net outflux (or influx, if negative) divided by cell area, at each cell.

Parameters:

unit_flux_at_links_across_faces (ndarray or field name) – Flux per unit width along links at faces (x number of faces) or link field.

Returns:

Flux divergence at cells.

Return type:

ndarray (x number of cells)

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.grid.divergence import calc_flux_div_at_cell
>>> rg = RasterModelGrid((3, 4), xy_spacing=10.0)
>>> import numpy as np
>>> z = rg.add_zeros("topographic__elevation", at="node")
>>> z[5] = 50.0
>>> z[6] = 36.0
>>> lg = rg.calc_grad_at_link(z)  # there are 17 links
>>> lg
array([ 0. ,  0. ,  0. ,  0. ,  5. ,  3.6,  0. ,  5. , -1.4, -3.6,  0. ,
       -5. , -3.6,  0. ,  0. ,  0. ,  0. ])
>>> fg = lg[rg.link_at_face]  # there are 7 faces
>>> fg
array([ 5. ,  3.6,  5. , -1.4, -3.6, -5. , -3.6])
>>> calc_flux_div_at_cell(rg, -fg)
array([ 1.64,  0.94])
>>> rg.set_status_at_node_on_edges(right=rg.BC_NODE_IS_CLOSED)
>>> rg.set_status_at_node_on_edges(top=rg.BC_NODE_IS_CLOSED)
>>> unit_flux_at_faces = np.zeros(rg.number_of_faces)
>>> unit_flux_at_faces[rg.active_faces] = -fg[rg.active_faces]
>>> calc_flux_div_at_cell(rg, unit_flux_at_faces)
array([ 1.14,  0.22])
>>> _ = rg.add_field("neg_grad_at_link", -lg, at="link")
>>> calc_flux_div_at_cell(rg, "neg_grad_at_link")
array([ 1.64,  0.94])

Notes

Performs a numerical flux divergence operation at cells.

calc_flux_div_at_node(unit_flux, out=None)

Calculate divergence of link-based fluxes at nodes.

Given a flux per unit width across each face in the grid, calculate the net outflux (or influx, if negative) divided by cell area, at each node (zero or “out” value for nodes without cells).

Parameters:

unit_flux (ndarray or field name) – Flux per unit width along links (x number of links).

Returns:

Flux divergence at nodes.

Return type:

ndarray (x number of nodes)

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.grid.divergence import calc_flux_div_at_node
>>> rg = RasterModelGrid((3, 4), xy_spacing=10.0)
>>> z = rg.add_zeros("topographic__elevation", at="node")
>>> z[5] = 50.0
>>> z[6] = 36.0
>>> lg = rg.calc_grad_at_link(z)  # there are 17 links
>>> lg
array([ 0. ,  0. ,  0. ,  0. ,  5. ,  3.6,  0. ,  5. , -1.4, -3.6,  0. ,
       -5. , -3.6,  0. ,  0. ,  0. ,  0. ])
>>> calc_flux_div_at_node(rg, -lg)
array([ 0.  ,  0.  ,  0.  ,  0.  ,  0.  ,  1.64,  0.94,  0.  ,  0.  ,
        0.  ,  0.  ,  0.  ])
>>> rg.set_status_at_node_on_edges(right=rg.BC_NODE_IS_CLOSED)
>>> rg.set_status_at_node_on_edges(top=rg.BC_NODE_IS_CLOSED)
>>> unit_flux_at_links = np.zeros(rg.number_of_links)
>>> unit_flux_at_links[rg.active_links] = -lg[rg.active_links]
>>> calc_flux_div_at_node(rg, unit_flux_at_links)
array([ 0.  ,  0.  ,  0.  ,  0.  ,  0.  ,  1.14,  0.22,  0.  ,  0.  ,
        0.  ,  0.  ,  0.  ])
>>> _ = rg.add_field("neg_grad_at_link", -lg, at="link")
>>> calc_flux_div_at_node(rg, "neg_grad_at_link")
array([ 0.  ,  0.  ,  0.  ,  0.  ,  0.  ,  1.64,  0.94,  0.  ,  0.  ,
        0.  ,  0.  ,  0.  ])

Notes

Performs a numerical flux divergence operation on nodes.

calc_grad_at_link(node_values, out=None)

Calculate gradients of node values at links.

Calculates the gradient in node_values at each link in the grid, returning an array of length number_of_links.

Parameters:

• node_values (ndarray or field name (x number of nodes)) – Values at grid nodes.

• out (ndarray, optional (x number of links)) – Buffer to hold the result.

Returns:

Gradients across active links.

Return type:

ndarray

Examples

>>> from landlab import RasterModelGrid
>>> rg = RasterModelGrid((3, 4), xy_spacing=10.0)
>>> z = rg.add_zeros("topographic__elevation", at="node")
>>> z[5] = 50.0
>>> z[6] = 36.0
>>> calc_grad_at_link(rg, z)  # there are 17 links
array([ 0. ,  0. ,  0. ,  0. ,  5. ,  3.6,  0. ,  5. , -1.4, -3.6,  0. ,
       -5. , -3.6,  0. ,  0. ,  0. ,  0. ])

>>> from landlab import HexModelGrid
>>> hg = HexModelGrid((3, 3), spacing=10.0)
>>> z = hg.add_zeros("topographic__elevation", at="node", clobber=True)
>>> z[4] = 50.0
>>> z[5] = 36.0
>>> calc_grad_at_link(hg, z)  # there are 11 faces
array([ 0. ,  0. ,  0. ,  5. ,  5. ,  3.6,  3.6,  0. ,  5. , -1.4, -3.6,
        0. , -5. , -5. , -3.6, -3.6,  0. ,  0. ,  0. ])

calc_grad_at_patch(elevs='topographic__elevation', ignore_closed_nodes=True, unit_normal=None, slope_magnitude=None)

Calculate the components of the gradient at each patch.

If ignore_closed_nodes is True, closed nodes do not affect gradient calculations. If a closed node is present in a patch, the patch gradient is set to zero in both x and y directions.

Parameters:

• elevs (str or ndarray, optional) – Field name or array of node values.

• ignore_closed_nodes (bool) – If True, do not incorporate values at closed nodes into the calc.

• unit_normal (array with shape (num_patches, 3) (optional)) – The unit normal vector to each patch, if already known.

• slope_magnitude (array with size num_patches (optional)) – The slope of each patch, if already known.

Returns:

gradient_tuple – Len-2 tuple of arrays giving components of gradient in the x and y directions, in the units of units.

Return type:

(x_component_at_patch, y_component_at_patch)

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> z = mg.node_y
>>> (x_grad, y_grad) = mg.calc_grad_at_patch(elevs=z)
>>> np.allclose(y_grad, np.pi / 4.0)
True
>>> np.allclose(x_grad, 0.0)
True

calc_hillshade_at_node(alt=45.0, az=315.0, slp=None, asp=None, unit='degrees', elevs='topographic__elevation')

Get array of hillshade.

Code author: Katy Barnhart <katherine.barnhart@colorado.edu>

Parameters:

• alt (float) – Sun altitude (from horizon) - defaults to 45 degrees

• az (float) – Sun azimuth (CW from north) - defaults to 315 degrees

• slp (float) – slope of cells at surface - optional

• asp (float) – aspect of cells at surface (from north) - optional (with slp)

• unit (string) –

  ‘degrees’ (default) or ‘radians’ - only needed if slp and asp

  are not provided

• specified (If slp and asp are both not) –

• as ('elevs' must be provided) –

• an (a grid field name (defaults to 'topographic__elevation') or) –

• case (nnodes-long array of elevation values. In this) –

• will (the method) –

• hillshade (calculate local slopes and aspects internally as part of the) –

• production. –

Returns:

Hillshade at each cell.

Return type:

ndarray of float

Notes

code taken from GeospatialPython.com example from December 14th, 2014 DEJH found what looked like minor sign problems, and adjusted to follow the ArcGIS algorithm <http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#/How_Hillshade_works/009z000000z2000000/>.

Remember when plotting that bright areas have high values. cmap=’Greys’ will give an apparently inverted color scheme. cmap=’gray’ has white associated with the high values, so is recommended for plotting.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid

>>> mg = RasterModelGrid((5, 5), xy_spacing=1.0)
>>> z = mg.x_of_node * np.tan(60.0 * np.pi / 180.0)
>>> mg.calc_hillshade_at_node(elevs=z, alt=30.0, az=210.0)
array([ 0.625,  0.625,  0.625,  0.625,  0.625,  0.625,  0.625,  0.625,
        0.625,  0.625,  0.625,  0.625,  0.625,  0.625,  0.625,  0.625,
        0.625,  0.625,  0.625,  0.625,  0.625,  0.625,  0.625,  0.625,
        0.625])

calc_net_flux_at_node(unit_flux_at_links, out=None)

Calculate net link fluxes at nodes.

Given a flux per unit width along each link in the grid, calculate the net outflux (or influx, if negative) at each node. Fluxes are treated as zero for links that have no faces, and net fluxes are treated as zero for nodes that have no cell.

Parameters:

• unit_flux_at_links (ndarray or field name) – Flux per unit width associated with links.

• out (ndarray, optional) – Buffer to hold the result.

Returns:

Net flux at nodes.

Return type:

ndarray (x number of cells)

Examples

>>> from landlab import RasterModelGrid
>>> rg = RasterModelGrid((3, 4), xy_spacing=10.0)
>>> z = rg.add_zeros("topographic__elevation", at="node")
>>> z[5] = 50.0
>>> z[6] = 36.0
>>> lg = rg.calc_grad_at_link(z)  # there are 17 links
>>> lg
array([ 0. ,  0. ,  0. ,  0. ,  5. ,  3.6,  0. ,  5. , -1.4, -3.6,  0. ,
       -5. , -3.6,  0. ,  0. ,  0. ,  0. ])
>>> calc_net_flux_at_node(rg, -lg)
array([   0.,    0.,    0.,    0.,    0.,  164.,   94.,    0.,    0.,
          0.,    0.,    0.])
>>> rg.set_status_at_node_on_edges(right=rg.BC_NODE_IS_CLOSED)
>>> rg.set_status_at_node_on_edges(top=rg.BC_NODE_IS_CLOSED)
>>> unit_flux_at_links = np.zeros(rg.number_of_links)
>>> unit_flux_at_links[rg.active_links] = -lg[rg.active_links]
>>> nlfn = calc_net_flux_at_node(rg, unit_flux_at_links)
>>> np.round(nlfn)
array([   0.,    0.,    0.,    0.,    0.,  114.,   22.,    0.,    0.,
          0.,    0.,    0.])

>>> from landlab import HexModelGrid
>>> hg = HexModelGrid((3, 3), spacing=10.0)
>>> z = hg.add_zeros("topographic__elevation", at="node", clobber=True)
>>> z[4] = 50.0
>>> z[5] = 36.0
>>> lg = hg.calc_grad_at_link(z)  # there are ? links
>>> lg
array([ 0. ,  0. ,  0. ,  5. ,  5. ,  3.6,  3.6,  0. ,  5. , -1.4, -3.6,
        0. , -5. , -5. , -3.6, -3.6,  0. ,  0. ,  0. ])
>>> nlfn = calc_net_flux_at_node(hg, -lg)
>>> np.round(nlfn)
array([   0.,    0.,    0.,    0.,  152.,   96.,    0.,    0.,    0.,    0.])

Notes

This is essentially a line integral for the fluxes along the boundaries of each cell. Hence, the resulting output has dimensions of total flux (so, if the unit flux happens to be mass per time per face width, the output will be in mass per unit time). Because a line integral is undefined where there are no cells (i.e., perimeter nodes), the result is given as zeros for these nodes. The current algorithm uses fancy indexing (calling _calc_net_face_flux_at_cells) and could probably be made faster.

calc_slope_at_node(elevs='topographic__elevation', method='patch_mean', ignore_closed_nodes=True, return_components=False, **kwds)

Array of slopes at nodes, averaged over neighboring patches.

Produces a value for node slope (i.e., mean gradient magnitude) at each node in a manner analogous to a GIS-style slope map. It averages the gradient on each of the patches surrounding the node, creating a value for node slope that better incorporates nonlocal elevation information. Directional information can still be returned through use of the return_components keyword.

Note that under these definitions, it is not always true that:

mag, cmp = mg.calc_slope_at_node(z)
mag**2 == cmp[0] ** 2 + cmp[1] ** 2  # not always true

If ignore_closed_nodes is False, all proximal elevation values will be used in the calculation. If True, only unclosed nodes are used.

Parameters:

• elevs (str or ndarray, optional) – Field name or array of node values.

• method ({'patch_mean', 'Horn'}) – By equivalence to the raster version, 'patch_mean' returns a scalar mean on the patches; 'Horn' returns a vector mean on the patches.

• ignore_closed_nodes (bool) – If True, do not incorporate values at closed nodes into the calculation.

• return_components (bool) – If True, return a tuple, (array_of_magnitude, (array_of_slope_x_radians, array_of_slope_y_radians)). If False, return an array of floats of the slope magnitude.

Returns:

If return_components, returns (array_of_magnitude, (array_of_slope_x_radians, array_of_slope_y_radians)). If not return_components, returns an array of slope magnitudes.

Return type:

float array or length-2 tuple of float arrays

Examples

>>> import numpy as np
>>> from landlab import RadialModelGrid, RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> z = mg.node_x
>>> slopes = mg.calc_slope_at_node(elevs=z)
>>> np.allclose(slopes, 45.0 / 180.0 * np.pi)
True

>>> mg = RasterModelGrid((4, 5))
>>> z = -mg.node_y
>>> slope_mag, cmp = mg.calc_slope_at_node(elevs=z, return_components=True)
>>> np.allclose(slope_mag, np.pi / 4.0)
True
>>> np.allclose(cmp[0], 0.0)
True
>>> np.allclose(cmp[1], -np.pi / 4.0)
True

>>> mg = RadialModelGrid(n_rings=3)
>>> z = mg.radius_at_node
>>> slope_at_node = np.round(mg.calc_slope_at_node(elevs=z), decimals=5)

>>> nodes_at_ring = [
...     np.where(np.isclose(mg.radius_at_node, radius)) for radius in range(3)
... ]
>>> slope_at_node[nodes_at_ring[0]]
array([ 0.85707])
>>> slope_at_node[nodes_at_ring[1]]
array([ 0.79417,  0.79417,  0.79417,  0.79417,  0.79417,  0.79417])
>>> slope_at_node[nodes_at_ring[2]]
array([ 0.77542,  0.78453,  0.78453,  0.77542,  0.77542,  0.78453,
        0.78453,  0.77542,  0.77542,  0.78453,  0.78453,  0.77542])

calc_slope_at_patch(elevs='topographic__elevation', ignore_closed_nodes=True, unit_normal=None)

Calculate the slope (positive magnitude of gradient) at patches.

If ignore_closed_nodes is True, closed nodes do not affect slope calculations. If a closed node is present in a patch, the patch slope is set to zero.

Parameters:

• elevs (str or ndarray, optional) – Field name or array of node values.

• ignore_closed_nodes (bool) – If True, do not incorporate values at closed nodes into the calc.

• unit_normal (array with shape (num_patches, 3) (optional)) – The unit normal vector to each patch, if already known.

Returns:

slopes_at_patch – The slope (positive gradient magnitude) of each patch.

Return type:

n_patches-long array

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> z = mg.node_x
>>> S = mg.calc_slope_at_patch(elevs=z)
>>> S.size == mg.number_of_patches
True
>>> np.allclose(S, np.pi / 4.0)
True

calc_unit_normal_at_patch(elevs='topographic__elevation')

Calculate and return the unit normal vector <a, b, c> to a patch.

Parameters:

elevs (str or ndarray, optional) – Field name or array of node values.

Returns:

nhat – The unit normal vector <a, b, c> to each patch.

Return type:

num-patches x length-3 array

Examples

>>> from landlab import HexModelGrid
>>> mg = HexModelGrid((3, 3))
>>> z = mg.node_x * 3.0 / 4.0
>>> mg.calc_unit_normal_at_patch(z)
array([[-0.6,  0. ,  0.8],
       [-0.6,  0. ,  0.8],
       [-0.6,  0. ,  0.8],
       [-0.6,  0. ,  0.8],
       [-0.6,  0. ,  0.8],
       [-0.6,  0. ,  0.8],
       [-0.6,  0. ,  0.8],
       [-0.6,  0. ,  0.8],
       [-0.6,  0. ,  0.8],
       [-0.6,  0. ,  0.8]])

property cell_area_at_node

Cell areas in a nnodes-long array.

Zeros are entered at all perimeter nodes, which lack cells.

Returns:

Cell areas as an n_nodes-long array.

Return type:

ndarray

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5), xy_spacing=(3, 4))
>>> grid.status_at_node[7] = grid.BC_NODE_IS_CLOSED
>>> grid.cell_area_at_node
array([  0.,   0.,   0.,   0.,   0.,
         0.,  12.,  12.,  12.,   0.,
         0.,  12.,  12.,  12.,   0.,
         0.,   0.,   0.,   0.,   0.])

property closed_boundary_nodes

Get array of closed boundary nodes.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> mg.status_at_node[mg.nodes_at_top_edge] = mg.BC_NODE_IS_CLOSED
>>> mg.closed_boundary_nodes
array([15, 16, 17, 18, 19])

property core_cells

Get array of core cells.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))

Initially all of the cells are “core”.

>>> grid.core_cells
array([0, 1, 2,
       3, 4, 5])

Setting a node to closed causes its cell to no longer be core.

>>> grid.status_at_node[8] = grid.BC_NODE_IS_CLOSED
>>> grid.core_cells
array([0, 1, 3, 4, 5])

property core_nodes

Get array of core nodes.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> mg.core_nodes
array([ 6,  7,  8, 11, 12, 13])

downwind_links_at_node(values, bad_index=-1)

Return an (nnodes, X) shape array of link IDs of which links are downwind of each node, according to values (array or field).

X is the maximum downwind links at any node. Nodes with fewer downwind links than this have additional slots filled with bad_index. Links are ordered anticlockwise from east.

Parameters:

• values (str or array) – Name of variable field defined at links, or array of values at links.

• bad_index (int) – Index to place in array indicating no link.

Returns:

Array of upwind link IDs

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -5.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> rmg.downwind_links_at_node("grad", bad_index=rmg.BAD_INDEX)
array([[ 0,  3],
       [ 1,  4],
       [ 2,  5],
       [ 6, -1],
       [ 7, 10],
       [ 8, 11],
       [ 9, 12],
       [13, -1],
       [14, -1],
       [15, -1],
       [16, -1],
       [-1, -1]])

fields(include='*', exclude=None)

List of fields held by the grid.

The returned field names are returned as their canonical names. That is, as a string of the for "at_<location>:<name>". This allows for fields with the same name to be defined at different grid locations. You could have, for example, a variable “elevation” defined at both nodes and links.

Both the include and exclude patterns are glob-style expressions, not regular expressions. If either include or exclude are lists, then the patterns are matched using an “or”.

The include filters are applied before the exclude filters.

Parameters:

• include (str, or iterable of str, optional) – Glob-style pattern for field names to include.

• exclude (str, or iterable of str, optional) – Glob-style pattern for field names to exclude.

Returns:

Filtered set of canonical field names held by the grid

Return type:

set

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))

Add some fields to the grid. Notice that we have defined a field named “elevation” at both nodes and links.

>>> _ = grid.add_full("elevation", 3.0, at="node")
>>> _ = grid.add_full("elevation", 4.0, at="link")
>>> _ = grid.add_full("temperature", 5.0, at="node")

>>> sorted(grid.fields())
['at_link:elevation', 'at_node:elevation', 'at_node:temperature']
>>> sorted(grid.fields(include="at_node*"))
['at_node:elevation', 'at_node:temperature']
>>> sorted(grid.fields(include="at_node*", exclude="*temp*"))
['at_node:elevation']

Fields can also be defined at layers. In the following example we’ve filtered the results to just return the layer fields.

>>> grid.event_layers.add(1.0, rho=0.5)
>>> sorted(grid.fields(include="at_layer*"))
['at_layer:rho']

If a list, the fields are matched with an “or”.

>>> sorted(grid.fields(include=["at_node*", "*elevation*"]))
['at_link:elevation', 'at_node:elevation', 'at_node:temperature']

property fixed_gradient_boundary_node_anchor_node

Returns the node at the other end of the fixed link for a fixed gradient boundary node.

Degenerate NodeStatus.FIXED_GRADIENT nodes (e.g., corners) are handled as in fixed_gradient_boundary_node_fixed_link, by pointing to a neighboring NodeStatus.FIXED_GRADIENT node.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> leftedge = grid.nodes_at_left_edge
>>> grid.status_at_node[leftedge] = grid.BC_NODE_IS_FIXED_GRADIENT
>>> grid.fixed_gradient_boundary_nodes
array([0, 4, 8])
>>> grid.fixed_gradient_boundary_node_fixed_link
array([ 3,  7, 10])
>>> grid.fixed_gradient_boundary_node_anchor_node
array([4, 5, 4])

property fixed_gradient_boundary_node_fixed_link

An array of the fixed_links connected to fixed gradient boundary nodes.

Note that on a raster, some nodes (notably the corners) can be NodeStatus.FIXED_GRADIENT, but not have a true LinkStatus.FIXED neighboring link. In such cases, the link returned will be a closed link joining the corner node to a neighboring NodeStatus.FIXED_GRADIENT node (see example).

An AssertionError will be raised if for some reason a NodeStatus.FIXED_GRADIENT node exists which has neither a NodeStatus.FIXED_GRADIENT neighbor, or a LinkStatus.FIXED.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> leftedge = grid.nodes_at_left_edge
>>> grid.status_at_node[leftedge] = grid.BC_NODE_IS_FIXED_GRADIENT
>>> grid.fixed_gradient_boundary_nodes
array([0, 4, 8])
>>> grid.fixed_gradient_boundary_node_fixed_link
array([ 3,  7, 10])

property fixed_gradient_boundary_nodes

Get array of fixed gradient boundary nodes.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> mg.status_at_node[mg.nodes_at_top_edge] = mg.BC_NODE_IS_FIXED_GRADIENT
>>> mg.fixed_gradient_boundary_nodes
array([15, 16, 17, 18, 19])

property fixed_links

Get array of fixed links.

Examples

>>> from landlab import NodeStatus, RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> grid.status_at_node.reshape(grid.shape)
array([[1, 1, 1, 1],
       [1, 0, 0, 1],
       [1, 1, 1, 1]], dtype=uint8)
>>> grid.fixed_links.size
0

>>> grid.status_at_node[:4] = NodeStatus.FIXED_GRADIENT
>>> grid.status_at_node.reshape(grid.shape)
array([[2, 2, 2, 2],
       [1, 0, 0, 1],
       [1, 1, 1, 1]], dtype=uint8)
>>> grid.fixed_links
array([4, 5])

property fixed_value_boundary_nodes

Get array of fixed value boundary nodes.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))

Initially all the perimeter nodes are fixed value boundary.

>>> grid.fixed_value_boundary_nodes
array([ 0,  1,  2,  3,  4, 5,  9, 10, 14, 15, 16, 17, 18, 19])

Set left, right, and bottom edges to closed.

>>> for edge in (
...     grid.nodes_at_left_edge,
...     grid.nodes_at_right_edge,
...     grid.nodes_at_bottom_edge,
... ):
...     grid.status_at_node[edge] = grid.BC_NODE_IS_CLOSED

Now nodes on just the top edge are fixed.

>>> grid.fixed_value_boundary_nodes
array([16, 17, 18])

classmethod from_dict(params)

Create grid from dictionary.

Parameters:

params (dictionary) – Dictionary of required parameters to create a model grid.

Examples

>>> from landlab import RasterModelGrid
>>> params = {"shape": (3, 4), "xy_spacing": 2}
>>> grid = RasterModelGrid.from_dict(params)
>>> grid.x_of_node
array([ 0.,  2.,  4.,  6.,  0.,  2.,  4.,  6.,  0.,  2.,  4.,  6.])
>>> grid.y_of_node
array([ 0.,  0.,  0.,  0.,  2.,  2.,  2.,  2.,  4.,  4.,  4.,  4.])

classmethod from_file(file_like)

Create grid from a file-like object.

File to load either as a file-like object, path to an existing file, or the contents of a file as a string.

Parameters:

file_like – File-like object, filepath, or string.

Examples

>>> from io import StringIO
>>> from landlab import RasterModelGrid
>>> filelike = StringIO(
...     '''
... shape:
...     - 3
...     - 4
... xy_spacing: 2
... '''
... )
>>> grid = RasterModelGrid.from_file(filelike)
>>> grid.x_of_node
array([ 0.,  2.,  4.,  6.,  0.,  2.,  4.,  6.,  0.,  2.,  4.,  6.])
>>> grid.y_of_node
array([ 0.,  0.,  0.,  0.,  2.,  2.,  2.,  2.,  4.,  4.,  4.,  4.])

link_at_node_is_downwind(values, out=None)

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_downwind iterates across the grid and identifies the link values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links carrying flux out of the node. It then return a boolean array the same shape as links_at_node flagging these links. e.g., for a raster, the returned array will be shape (nnodes, 4).

Parameters:

• values (str or array) – Name of variable field defined at links, or array of values at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array. Must be correct shape and boolean dtype.

Returns:

Boolean of which links are downwind at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -5.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> rmg.link_at_node_is_downwind("grad")
array([[ True,  True, False, False],
       [ True,  True, False, False],
       [ True,  True, False, False],
       [False,  True, False, False],
       [ True,  True, False, False],
       [ True,  True, False, False],
       [ True,  True, False, False],
       [False,  True, False, False],
       [ True, False, False, False],
       [ True, False, False, False],
       [ True, False, False, False],
       [False, False, False, False]], dtype=bool)

link_at_node_is_upwind(values, out=None)

Return a boolean the same shape as links_at_node which flags links which are upwind of the node as True.

link_at_node_is_upwind iterates across the grid and identifies the link values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links bringing flux into the node. It then return a boolean array the same shape as links_at_node flagging these links. e.g., for a raster, the returned array will be shape (nnodes, 4).

Parameters:

• values (str or array) – Name of variable field defined at links, or array of values at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array. Must be correct shape and boolean dtype.

Returns:

Boolean of which links are upwind at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))

>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -5.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> rmg.link_at_node_is_upwind("grad")
array([[False, False, False, False],
       [False, False,  True, False],
       [False, False,  True, False],
       [False, False,  True, False],
       [False, False, False,  True],
       [False, False,  True,  True],
       [False, False,  True,  True],
       [False, False,  True,  True],
       [False, False, False,  True],
       [False, False,  True,  True],
       [False, False,  True,  True],
       [False, False,  True,  True]], dtype=bool)

property link_status_at_node

link_with_angle(angle, in_degrees=False)

Return array of IDs of links with given angle.

Examples

>>> from landlab import HexModelGrid
>>> grid = HexModelGrid((3, 3))
>>> grid.link_with_angle(0.0)
array([  0,  1,  8,  9, 10, 17, 18])
>>> grid.link_with_angle(60.0, in_degrees=True)
array([  3,  5,  7, 11, 13, 15])
>>> grid.link_with_angle(2.0944)  # 120 degrees
array([  2,  4,  6, 12, 14, 16])
>>> len(grid.link_with_angle(0.5236))  # no links at 30 deg
0
>>> grid = HexModelGrid((3, 3), orientation="vertical")
>>> grid.link_with_angle(30.0, in_degrees=True)
array([  1,  3,  8, 10, 15, 17])
>>> grid.link_with_angle(1.5708)  # 90 degrees
array([ 2,  5,  6,  9, 12, 13, 16])
>>> grid.link_with_angle(330.0, in_degrees=True)
array([ 0,  4,  7, 11, 14, 18])
>>> len(grid.link_with_angle(60.0, in_degrees=True))  # none at 60 deg
0

link_with_node_status(status_at_tail=None, status_at_head=None)

Links with a given node status.

Parameters:

• status_at_tail (NodeStatus, optional) – Status of the link tail node.

• status_at_head (NodeStatus, optional) – Status of the link head node.

Returns:

Links with the given tail and head node statuses.

Return type:

array of int

Examples

>>> from landlab import RasterModelGrid, NodeStatus
>>> grid = RasterModelGrid((4, 5))

>>> grid.status_at_node[13] = NodeStatus.FIXED_VALUE
>>> grid.status_at_node[2] = NodeStatus.CLOSED
>>> grid.link_with_node_status(
...     status_at_tail=NodeStatus.CORE, status_at_head=NodeStatus.CORE
... )
array([10, 11, 14, 15, 19])
>>> grid.link_with_node_status(
...     status_at_tail=NodeStatus.CORE, status_at_head=NodeStatus.FIXED_VALUE
... )
array([12, 16, 20, 23, 24])
>>> grid.link_with_node_status(
...     status_at_tail=NodeStatus.FIXED_VALUE, status_at_head=NodeStatus.CORE
... )
array([ 5,  7,  9, 18])

>>> grid.link_with_node_status(status_at_head=NodeStatus.CORE)
array([ 5,  6,  7,  9, 10, 11, 14, 15, 18, 19])
>>> grid.link_with_node_status(status_at_tail=NodeStatus.CORE)
array([10, 11, 12, 14, 15, 16, 19, 20, 23, 24])
>>> grid.link_with_node_status()
array([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15, 16,
       17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30])

map_downwind_node_link_max_to_node(var_name, out=None)

Map the largest magnitude of the links carrying flux from the node to the node.

map_downwind_node_link_max_to_node iterates across the grid and identifies the link values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links carrying flux out of the node, then maps the maximum magnitude of ‘var_name’ found on these links onto the node. If no downwind link is found, the value will be recorded as zero.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_downwind_node_link_max_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     0.0,
...     0.0,
...     0.0,
...     0.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     0.0,
...     0.0,
...     0.0,
...     0.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> map_downwind_node_link_max_to_node(rmg, "grad")
array([ 1.,  2.,  1.,  0.,
        1.,  2.,  1.,  0.,
        1.,  2.,  1.,  0.])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_downwind_node_link_max_to_node(rmg, "grad", out=values_at_nodes)
>>> values_at_nodes
array([ 1.,  2.,  1.,  0.,
        1.,  2.,  1.,  0.,
        1.,  2.,  1.,  0.])
>>> rtn is values_at_nodes
True

map_downwind_node_link_mean_to_node(var_name, out=None)

Map the mean magnitude of the links carrying flux out of the node to the node.

map_downwind_node_link_mean_to_node iterates across the grid and identifies the link values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links carrying flux out of the node, then maps the mean magnitude of ‘var_name’ found on these links onto the node. Links with zero values are not included in the means, and zeros are returned if no upwind links are found.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_downwind_node_link_mean_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -5.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> map_downwind_node_link_mean_to_node(rmg, "grad")
array([ 1.5,  2.5,  2.5,  5. ,
        1. ,  2. ,  2. ,  4. ,
        1. ,  2. ,  1. ,  0. ])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_downwind_node_link_mean_to_node(rmg, "grad", out=values_at_nodes)
>>> values_at_nodes
array([ 1.5,  2.5,  2.5,  5. ,
        1. ,  2. ,  2. ,  4. ,
        1. ,  2. ,  1. ,  0. ])
>>> rtn is values_at_nodes
True

map_link_head_node_to_link(var_name, out=None)

Map values from a link head nodes to links.

Iterate over a grid and identify the node at the head. For each link, the value of var_name at the head node is mapped to the corresponding link.

In a RasterModelGrid, each one node has two adjacent “link heads”. This means each node value is mapped to two corresponding links.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_link_head_node_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_node["z"] = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
>>> map_link_head_node_to_link(rmg, "z")
array([  1.,   2.,   3.,   4.,   5.,   6.,   7.,   5.,   6.,   7.,   8.,
      9.,  10.,  11.,   9.,  10.,  11.])

>>> values_at_links = rmg.empty(at="link")
>>> rtn = map_link_head_node_to_link(rmg, "z", out=values_at_links)
>>> values_at_links
array([  1.,   2.,   3.,   4.,   5.,   6.,   7.,   5.,   6.,   7.,   8.,
      9.,  10.,  11.,   9.,  10.,  11.])
>>> rtn is values_at_links
True

map_link_tail_node_to_link(var_name, out=None)

Map values from a link tail nodes to links.

map_link_tail_node_to_link iterates across the grid and identifies the node at the “tail”, or the “from” node for each link. For each link, the value of ‘var_name’ at the “from” node is mapped to the corresponding link.

In a RasterModelGrid, each one node has two adjacent “link tails”. This means each node value is mapped to two corresponding links.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_link_tail_node_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_node["z"] = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
>>> map_link_tail_node_to_link(rmg, "z")
array([  0.,   1.,   2.,   0.,   1.,   2.,   3.,   4.,   5.,   6.,   4.,
         5.,   6.,   7.,   8.,   9.,  10.])

>>> values_at_links = rmg.empty(at="link")
>>> rtn = map_link_tail_node_to_link(rmg, "z", out=values_at_links)
>>> values_at_links
array([  0.,   1.,   2.,   0.,   1.,   2.,   3.,   4.,   5.,   6.,   4.,
         5.,   6.,   7.,   8.,   9.,  10.])
>>> rtn is values_at_links
True

map_link_vector_components_to_node(data_at_link)

Map (x,y) components of link data data_at_link onto nodes.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid, HexModelGrid

>>> grid = RasterModelGrid((3, 4))
>>> link_data = np.arange(grid.number_of_links)

>>> vx, vy = grid.map_link_vector_components_to_node(link_data)
>>> vx[5:7]
array([ 7.5, 8.5])

>>> grid = HexModelGrid((3, 3))
>>> link_data = np.zeros(grid.number_of_links) + 0.5 * 3.0**0.5
>>> link_data[np.isclose(grid.angle_of_link, 0.0)] = 0.0
>>> vx, vy = grid.map_link_vector_components_to_node(link_data)
>>> vy
array([ 0.,  0.,  0.,  0.,  1.,  1.,  0.,  0.,  0.,  0.])

map_link_vector_sum_to_patch(var_name, ignore_inactive_links=True, out=None)

Map the vector sum of links around a patch to the patch.

The resulting vector is returned as a length-2 list, with the two items being arrays of the x component and the y component of the resolved vectors at the patches, respectively.

Parameters:

• var_name (array or field name) – Values defined at links.

• ignore_inactive_links (bool) – If True, do not incorporate inactive links into calc. If all links are inactive at a patch, record zero if out is None or leave the existing value if out.

• out (len-2 list of npatches-long arrays, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

[x_component_of_link_vals_at_patch, y_component_of_link_vals_at_patch].

Return type:

len-2 list of arrays

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_link_vector_sum_to_patch
>>> from landlab import HexModelGrid

>>> mg = HexModelGrid((4, 3))
>>> interior_nodes = mg.status_at_node == mg.BC_NODE_IS_CORE
>>> exterior_nodes = mg.status_at_node != mg.BC_NODE_IS_CORE

Add a ring of closed nodes at the edge:

>>> mg.status_at_node[exterior_nodes] = mg.BC_NODE_IS_CLOSED

This gives us 5 core nodes, 7 active links, and 3 present patches

>>> (mg.number_of_core_nodes == 5 and mg.number_of_active_links == 7)
True
>>> A = mg.add_ones("vals", at="link")
>>> A.fill(9.0)  # any old values on the inactive links
>>> A[mg.active_links] = np.array([1.0, -1.0, 1.0, -1.0, -1.0, -1.0, -1.0])

This setup should give present patch 0 pure east, patch 1 zero (vorticity), and patch 2 westwards and downwards components.

>>> xcomp, ycomp = map_link_vector_sum_to_patch(mg, "vals")
>>> xcomp, ycomp = np.round(xcomp, decimals=5), np.round(ycomp, decimals=5)
>>> np.allclose(xcomp[(6, 9, 10),], [2.0, 0.0, -1.0])
True
>>> np.allclose(ycomp[(6, 9, 10),] / np.sqrt(3.0), [0.0, 0.0, -1.0])
True

These are the patches with LinksStatus.INACTIVE on all three sides:

>>> absent_patches = np.array([0, 1, 2, 4, 8, 11, 12, 15, 16, 17, 18])
>>> np.allclose(xcomp[absent_patches], 0.0)
True
>>> np.allclose(ycomp[absent_patches], 0.0)
True

Now demonstrate the remaining functionality:

>>> A = mg.at_link["vals"].copy()
>>> A.fill(1.0)
>>> _ = map_link_vector_sum_to_patch(
...     mg, A, ignore_inactive_links=False, out=[xcomp, ycomp]
... )
>>> np.allclose(xcomp[absent_patches], 0.0)
False
>>> np.allclose(ycomp[absent_patches], 0.0)
False

map_max_of_link_nodes_to_link(var_name, out=None)

Map the maximum of a link’s nodes to the link.

map_max_of_link_nodes_to_link iterates across the grid and identifies the node values at both the “head” and “tail” of a given link. This function evaluates the value of ‘var_name’ at both the “to” and “from” node. The maximum value of the two node values is then mapped to the link.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_max_of_link_nodes_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field(
...     "z",
...     [
...         [0, 1, 2, 3],
...         [7, 6, 5, 4],
...         [8, 9, 10, 11],
...     ],
...     at="node",
... )
>>> map_max_of_link_nodes_to_link(rmg, "z")
array([  1.,   2.,   3.,   7.,   6.,   5.,   4.,   7.,   6.,   5.,   8.,
         9.,  10.,  11.,   9.,  10.,  11.])

>>> values_at_links = rmg.empty(at="link")
>>> rtn = map_max_of_link_nodes_to_link(rmg, "z", out=values_at_links)
>>> values_at_links
array([  1.,   2.,   3.,   7.,   6.,   5.,   4.,   7.,   6.,   5.,   8.,
         9.,  10.,  11.,   9.,  10.,  11.])
>>> rtn is values_at_links
True

map_max_of_node_links_to_node(var_name, out=None)

Map the maximum value of a nodes’ links to the node.

map_max_of_node_links_to_node iterates across the grid and identifies the link values at each link connected to a node. This function finds the maximum value of ‘var_name’ of each set of links, and then maps this value to the node. Note no attempt is made to honor the directionality of the links.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_max_of_node_links_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = np.arange(rmg.number_of_links)
>>> map_max_of_node_links_to_node(rmg, "grad")
array([  3.,   4.,   5.,   6.,
        10.,  11.,  12.,  13.,
        14.,  15.,  16.,  16.])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_max_of_node_links_to_node(rmg, "grad", out=values_at_nodes)
>>> values_at_nodes
array([  3.,   4.,   5.,   6.,
        10.,  11.,  12.,  13.,
        14.,  15.,  16.,  16.])
>>> rtn is values_at_nodes
True

map_max_of_patch_nodes_to_patch(var_name, ignore_closed_nodes=True, out=None)

Map the maximum value of nodes around a patch to the patch.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• ignore_closed_nodes (bool) – If True, do not incorporate closed nodes into calc. If all nodes are masked at a patch, record zero if out is None or leave the existing value if out.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at patches.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_max_of_patch_nodes_to_patch
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_node["vals"] = [
...     [5.0, 4.0, 3.0, 2.0],
...     [3.0, 4.0, 3.0, 2.0],
...     [3.0, 2.0, 1.0, 0.0],
... ]
>>> map_max_of_patch_nodes_to_patch(rmg, "vals")
array([ 5., 4., 3.,
        4., 4., 3.])

>>> rmg.at_node["vals"] = [
...     [5.0, 4.0, 3.0, 2.0],
...     [3.0, 4.0, 3.0, 2.0],
...     [3.0, 2.0, 1.0, 0.0],
... ]
>>> rmg.status_at_node[rmg.node_x > 1.5] = rmg.BC_NODE_IS_CLOSED
>>> ans = np.zeros(6, dtype=float)
>>> _ = map_max_of_patch_nodes_to_patch(rmg, "vals", out=ans)
>>> ans
array([ 5., 4., 0.,
        4., 4., 0.])

map_mean_of_link_nodes_to_link(var_name, out=None)

Map the mean of a link’s nodes to the link.

map_mean_of_link_nodes_to_link iterates across the grid and identifies the node values at both the “head” and “tail” of a given link. This function takes the sum of the two values of ‘var_name’ at both the “to” and “from” node. The average value of the two node values of ‘var_name’ is then mapped to the link.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_mean_of_link_nodes_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_node["z"] = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
>>> map_mean_of_link_nodes_to_link(rmg, "z")
array([  0.5,   1.5,   2.5,   2. ,   3. ,   4. ,   5. ,   4.5,   5.5,
         6.5,   6. ,   7. ,   8. ,   9. ,   8.5,   9.5,  10.5])

>>> values_at_links = rmg.empty(at="link")
>>> rtn = map_mean_of_link_nodes_to_link(rmg, "z", out=values_at_links)
>>> values_at_links
array([  0.5,   1.5,   2.5,   2. ,   3. ,   4. ,   5. ,   4.5,   5.5,
         6.5,   6. ,   7. ,   8. ,   9. ,   8.5,   9.5,  10.5])
>>> rtn is values_at_links
True

map_mean_of_patch_nodes_to_patch(var_name, ignore_closed_nodes=True, out=None)

Map the mean value of nodes around a patch to the patch.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• ignore_closed_nodes (bool) – If True, do not incorporate closed nodes into calc. If all nodes are masked at a patch, record zero if out is None or leave the existing value if out.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at patches.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_mean_of_patch_nodes_to_patch
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_node["vals"] = [
...     [5.0, 4.0, 3.0, 2.0],
...     [5.0, 4.0, 3.0, 2.0],
...     [3.0, 2.0, 1.0, 0.0],
... ]
>>> map_mean_of_patch_nodes_to_patch(rmg, "vals")
array([ 4.5, 3.5, 2.5,
        3.5, 2.5, 1.5])

>>> rmg.at_node["vals"] = [
...     [5.0, 4.0, 3.0, 2.0],
...     [5.0, 4.0, 3.0, 2.0],
...     [3.0, 2.0, 1.0, 0.0],
... ]
>>> rmg.status_at_node[rmg.node_x > 1.5] = rmg.BC_NODE_IS_CLOSED
>>> ans = np.zeros(6, dtype=float)
>>> _ = map_mean_of_patch_nodes_to_patch(rmg, "vals", out=ans)
>>> ans
array([ 4.5, 4. , 0. ,
        3.5, 3. , 0. ])

map_min_of_link_nodes_to_link(var_name, out=None)

Map the minimum of a link’s nodes to the link.

map_min_of_link_nodes_to_link iterates across the grid and identifies the node values at both the “head” and “tail” of a given link. This function evaluates the value of ‘var_name’ at both the “to” and “from” node. The minimum value of the two node values is then mapped to the link.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_min_of_link_nodes_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field(
...     "z",
...     [
...         [0, 1, 2, 3],
...         [7, 6, 5, 4],
...         [8, 9, 10, 11],
...     ],
...     at="node",
... )
>>> map_min_of_link_nodes_to_link(rmg, "z")
array([  0.,   1.,   2.,   0.,   1.,   2.,   3.,   6.,   5.,   4.,   7.,
         6.,   5.,   4.,   8.,   9.,  10.])

>>> values_at_links = rmg.empty(at="link")
>>> rtn = map_min_of_link_nodes_to_link(rmg, "z", out=values_at_links)
>>> values_at_links
array([  0.,   1.,   2.,   0.,   1.,   2.,   3.,   6.,   5.,   4.,   7.,
         6.,   5.,   4.,   8.,   9.,  10.])
>>> rtn is values_at_links
True

map_min_of_node_links_to_node(var_name, out=None)

Map the minimum value of a nodes’ links to the node.

map_min_of_node_links_to_node iterates across the grid and identifies the link values at each link connected to a node. This function finds the minimum value of ‘var_name’ of each set of links, and then maps this value to the node. Note no attempt is made to honor the directionality of the links.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_min_of_node_links_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = np.arange(rmg.number_of_links)
>>> map_min_of_node_links_to_node(rmg, "grad")
array([  0.,   0.,   1.,   2.,
         3.,   4.,   5.,   6.,
        10.,  11.,  12.,  13.])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_min_of_node_links_to_node(rmg, "grad", out=values_at_nodes)
>>> values_at_nodes
array([  0.,   0.,   1.,   2.,
         3.,   4.,   5.,   6.,
        10.,  11.,  12.,  13.])
>>> rtn is values_at_nodes
True

map_min_of_patch_nodes_to_patch(var_name, ignore_closed_nodes=True, out=None)

Map the minimum value of nodes around a patch to the patch.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• ignore_closed_nodes (bool) – If True, do not incorporate closed nodes into calc. If all nodes are masked at a patch, record zero if out is None or leave the existing value if out.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at patches.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_min_of_patch_nodes_to_patch
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_node["vals"] = [
...     [5.0, 4.0, 3.0, 2.0],
...     [5.0, 4.0, 3.0, 2.0],
...     [3.0, 2.0, 1.0, 0.0],
... ]
>>> map_min_of_patch_nodes_to_patch(rmg, "vals")
array([ 4., 3., 2.,
        2., 1., 0.])

>>> rmg.at_node["vals"] = [
...     [5.0, 4.0, 3.0, 2.0],
...     [5.0, 4.0, 3.0, 2.0],
...     [3.0, 2.0, 1.0, 0.0],
... ]
>>> rmg.status_at_node[rmg.node_x > 1.5] = rmg.BC_NODE_IS_CLOSED
>>> ans = np.zeros(6, dtype=float)
>>> _ = map_min_of_patch_nodes_to_patch(rmg, "vals", out=ans)
>>> ans
array([ 4., 4., 0.,
        2., 2., 0.])

map_node_to_cell(var_name, out=None)

Map values for nodes to cells.

map_node_to_cell iterates across the grid and identifies the all node values of ‘var_name’.

This function takes node values of ‘var_name’ and mapes that value to the corresponding cell area for each node.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at cells.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_node_to_cell
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", np.arange(12.0), at="node")
>>> map_node_to_cell(rmg, "z")
array([ 5.,  6.])

>>> values_at_cells = rmg.empty(at="cell")
>>> rtn = map_node_to_cell(rmg, "z", out=values_at_cells)
>>> values_at_cells
array([ 5.,  6.])
>>> rtn is values_at_cells
True

map_node_to_link_lax_wendroff(v, c, out=None)

Assign values to links using a weighted combination of node values.

Assign to each link a weighted combination of values v at nodes using the Lax-Wendroff method for upwind weighting.

c is a scalar or link vector that gives the link-parallel signed Courant number. Where c is positive, velocity is in the direction of the link; where negative, velocity is in the opposite direction.

As an example, consider 3x5 raster grid with the following values at the nodes in the central row:

0---1---2---3---4

Consider a uniform Courant value c = +0.2 at the horizontal links. The mapped link values should be:

.-0.4-.-1.4-.-2.4-.-3.4-.

Values at links when c = -0.2:

.-0.6-.-1.6-.-2.6-.-3.6-.

Parameters:

• v ((n_nodes,) ndarray) – Values at grid nodes.

• c (float or (n_links,) ndarray) – Courant number to use at links.

• out ((n_links,) ndarray, optional) – If provided, place calculated values in this array. Otherwise, create a new array.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid

>>> grid = RasterModelGrid((3, 5))
>>> grid.at_node["node_value"] = [
...     [0.0, 0.0, 0.0, 0.0, 0.0],
...     [0.0, 1.0, 2.0, 3.0, 4.0],
...     [0.0, 0.0, 0.0, 0.0, 0.0],
... ]
>>> v = grid.at_node["node_value"]

>>> c = grid.add_zeros("courant_number", at="link")
>>> c[grid.horizontal_links] = 0.2

Set values for the middle row of horizontal links.

>>> val_at_link = grid.map_node_to_link_lax_wendroff(v, c)
>>> val_at_link[9:13]
array([ 0.4,  1.4,  2.4,  3.4])
>>> val_at_link = grid.map_node_to_link_lax_wendroff(v, -c)
>>> val_at_link[9:13]
array([ 0.6,  1.6,  2.6,  3.6])

map_node_to_link_linear_upwind(v, u, out=None)

Assign values to links from upstream nodes.

Assign to each link the value v associated with whichever of its two nodes lies upstream, according to link value u.

Consider a link k with tail node t(k) and head node t(h). Nodes have value v(n). We want to assign a value to links, v’(k). The assignment is:

v'(k) = v(t(k)) where u(k) > 0,
v'(k) = v(h(k)) where u(k) <= 0

As an example, consider 3x5 raster grid with the following values at the nodes in the central row:

0---1---2---3---4

Consider a uniform velocity value u = 1 at the horizontal links. The mapped link values should be:

.-0-.-1-.-2-.-3-.

If u < 0, the link values should be:

.-1-.-2-.-3-.-4-.

Parameters:

• v ((n_nodes,), ndarray) – Values at grid nodes.

• u ((n_links,) ndarray) – Values at grid links.

• out ((n_links,) ndarray, optional) – If provided, place calculated values in this array. Otherwise, create a new array.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid

>>> grid = RasterModelGrid((3, 5))
>>> grid.at_node["node_value"] = [
...     [0.0, 0.0, 0.0, 0.0, 0.0],
...     [0.0, 1.0, 2.0, 3.0, 4.0],
...     [0.0, 0.0, 0.0, 0.0, 0.0],
... ]
>>> v = grid.at_node["node_value"]

>>> u = grid.add_zeros("advection_speed", at="link")
>>> u[grid.horizontal_links] = 1.0

Set values for the middle row of horizontal links.

>>> val_at_link = grid.map_node_to_link_linear_upwind(v, u)
>>> val_at_link[9:13]
array([ 0.,  1.,  2.,  3.])
>>> val_at_link = grid.map_node_to_link_linear_upwind(v, -u)
>>> val_at_link[9:13]
array([ 1.,  2.,  3.,  4.])

map_upwind_node_link_max_to_node(var_name, out=None)

Map the largest magnitude of the links bringing flux into the node to the node.

map_upwind_node_link_max_to_node iterates across the grid and identifies the link values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links bringing flux into the node, then maps the maximum magnitude of ‘var_name’ found on these links onto the node. If no upwind link is found, the value will be recorded as zero.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_upwind_node_link_max_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.1,
...     -1.2,
...     -1.3,
...     1.4,
...     1.5,
...     1.6,
...     -1.7,
...     -1.8,
...     -1.9,
...     2.0,
...     2.1,
...     2.2,
...     -2.3,
...     2.4,
...     2.5,
...     2.6,
...     -2.7,
... ]
>>> map_upwind_node_link_max_to_node(rmg, "grad").reshape((3, 4))
array([[ 1.4,  1.5,  1.6,  1.3],
       [ 2.1,  2.2,  2. ,  2.4],
       [ 2.5,  2.6,  2.3,  2.7]])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_upwind_node_link_max_to_node(rmg, "grad", out=values_at_nodes)
>>> values_at_nodes.reshape((3, 4))
array([[ 1.4,  1.5,  1.6,  1.3],
       [ 2.1,  2.2,  2. ,  2.4],
       [ 2.5,  2.6,  2.3,  2.7]])
>>> rtn is values_at_nodes
True

map_upwind_node_link_mean_to_node(var_name, out=None)

Map the mean magnitude of the links bringing flux into the node to the node.

map_upwind_node_link_mean_to_node iterates across the grid and identifies the link values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links bringing flux into the node, then maps the mean magnitude of ‘var_name’ found on these links onto the node. Links with zero values are not included in the means, and zeros are returned if no upwind links are found.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_upwind_node_link_mean_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -5.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> map_upwind_node_link_mean_to_node(rmg, "grad")
array([ 0. ,  1. ,  2. ,  1. ,
        2. ,  2. ,  3. ,  3. ,
        1. ,  1.5,  2.5,  2.5])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_upwind_node_link_mean_to_node(rmg, "grad", out=values_at_nodes)
>>> values_at_nodes
array([ 0. ,  1. ,  2. ,  1. ,
        2. ,  2. ,  3. ,  3. ,
        1. ,  1.5,  2.5,  2.5])
>>> rtn is values_at_nodes
True

map_value_at_downwind_node_link_max_to_node(control_name, value_name, out=None)

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_downwind_node_link_max_to_node iterates across the grid and identifies the link control_values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links carrying flux out of the node, then identifies the link with the maximum magnitude. The value of the second field ‘value_name’ at these links is then mapped onto the node. If no downwind link is found, the value will be recorded as zero.

Parameters:

• control_name (array or field name) – Values defined at nodes that dictate which end of the link to draw values from.

• value_name (array or field name) – Values defined at nodes from which values are drawn, based on control_name.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_value_at_downwind_node_link_max_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     0.0,
...     0.0,
...     0.0,
...     0.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     0.0,
...     0.0,
...     0.0,
...     0.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> rmg.at_link["vals"] = np.arange(rmg.number_of_links, dtype=float)
>>> map_value_at_downwind_node_link_max_to_node(rmg, "grad", "vals")
array([  0.,   1.,   2.,   0.,
         7.,   8.,   9.,   0.,
        14.,  15.,  16.,   0.])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_value_at_downwind_node_link_max_to_node(
...     rmg, "grad", "vals", out=values_at_nodes
... )
>>> values_at_nodes
array([  0.,   1.,   2.,   0.,
         7.,   8.,   9.,   0.,
        14.,  15.,  16.,   0.])
>>> rtn is values_at_nodes
True

map_value_at_max_node_to_link(control_name, value_name, out=None)

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_max_node_to_link iterates across the grid and identifies the node values at both the “head” and “tail” of a given link. This function evaluates the value of ‘control_name’ at both the “to” and “from” node. The value of ‘value_name’ at the node with the maximum value of the two values of ‘control_name’ is then mapped to the link.

Parameters:

• control_name (array or field name) – Name of field defined at nodes or a node array that dictates which end of the link to draw values from.

• value_name (array or field name) – Name of field defined at nodes or node array from which values are drawn, based on control_name.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_value_at_max_node_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field(
...     "z",
...     [
...         [0, 1, 2, 3],
...         [7, 6, 5, 4],
...         [8, 9, 10, 11],
...     ],
...     at="node",
... )
>>> _ = rmg.add_field(
...     "vals_to_map",
...     [
...         [0, 10, 20, 30],
...         [70, 60, 50, 40],
...         [80, 90, 100, 110],
...     ],
...     at="node",
... )
>>> map_value_at_max_node_to_link(rmg, "z", "vals_to_map")
array([  10.,   20.,   30.,   70.,   60.,   50.,   40.,   70.,   60.,
         50.,   80.,   90.,  100.,  110.,   90.,  100.,  110.])

map_value_at_min_node_to_link(control_name, value_name, out=None)

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_min_node_to_link iterates across the grid and identifies the node values at both the “head” and “tail” of a given link. This function evaluates the value of ‘control_name’ at both the “to” and “from” node. The value of ‘value_name’ at the node with the minimum value of the two values of ‘control_name’ is then mapped to the link.

Parameters:

• control_name (array or field name) – Name of field defined at nodes or a node array that dictates which end of the link to draw values from.

• value_name (array or field name) – Name of field defined at nodes or node array from which values are drawn, based on control_name.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_value_at_min_node_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field(
...     "z",
...     [
...         [0, 1, 2, 3],
...         [7, 6, 5, 4],
...         [8, 9, 10, 11],
...     ],
...     at="node",
... )
>>> _ = rmg.add_field(
...     "vals_to_map",
...     [
...         [0, 10, 20, 30],
...         [70, 60, 50, 40],
...         [80, 90, 100, 110],
...     ],
...     at="node",
... )
>>> map_value_at_min_node_to_link(rmg, "z", "vals_to_map")
array([   0.,   10.,   20.,    0.,   10.,   20.,   30.,   60.,   50.,
         40.,   70.,   60.,   50.,   40.,   80.,   90.,  100.])

map_value_at_upwind_node_link_max_to_node(control_name, value_name, out=None)

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.

map_upwind_node_link_max_to_node iterates across the grid and identifies the link control_values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links bringing flux into the node, then identifies the link with the maximum magnitude. The value of the second field ‘value_name’ at these links is then mapped onto the node. If no upwind link is found, the value will be recorded as zero.

Parameters:

• control_name (array or field name) – Values defined at nodes that dictate which end of the link to draw values from.

• value_name (array or field name) – Values defined at nodes from which values are drawn, based on control_name.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_value_at_upwind_node_link_max_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     0.0,
...     0.0,
...     0.0,
...     0.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     0.0,
...     0.0,
...     0.0,
...     0.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> rmg.at_link["vals"] = np.arange(rmg.number_of_links, dtype=float)
>>> map_value_at_upwind_node_link_max_to_node(rmg, "grad", "vals")
array([  0.,   0.,   1.,   2.,
         0.,   7.,   8.,   9.,
         0.,  14.,  15.,  16.])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_value_at_upwind_node_link_max_to_node(
...     rmg, "grad", "vals", out=values_at_nodes
... )
>>> values_at_nodes
array([  0.,   0.,   1.,   2.,
         0.,   7.,   8.,   9.,
         0.,  14.,  15.,  16.])
>>> rtn is values_at_nodes
True

map_vectors_to_links(ux, uy, out=None)

Map magnitude and sign of vectors with components (ux, uy) onto grid links.

Examples

>>> from landlab import HexModelGrid
>>> import numpy
>>> hmg = HexModelGrid((3, 2))
>>> (numpy.round(10 * map_vectors_to_links(hmg, 1.0, 0.0))).astype(int)
array([10, -5,  5, -5,  5, 10, 10,  5, -5,  5, -5, 10])

property ndim

Number of spatial dimensions of the grid.

property node_at_core_cell

Get array of nodes associated with core cells.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))

Initially each cell’s node is core.

>>> grid.node_at_core_cell
array([ 6,  7,  8,
       11, 12, 13])

Setting a node to closed causes means its cell is also “closed”.

>>> grid.status_at_node[8] = grid.BC_NODE_IS_CLOSED
>>> grid.node_at_core_cell
array([ 6,  7, 11, 12, 13])

node_axis_coordinates(axis=0)

Get the coordinates of nodes along a particular axis.

Return node coordinates from a given axis (defaulting to 0). Axis numbering is the same as that for numpy arrays. That is, the zeroth axis is along the rows, and the first along the columns.

Parameters:

axis (int, optional) – Coordinate axis.

Returns:

Coordinates of nodes for a given axis.

Return type:

ndarray

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.node_axis_coordinates(0).reshape(grid.shape)
array([[ 0.,  0.,  0.,  0.,  0.],
       [ 1.,  1.,  1.,  1.,  1.],
       [ 2.,  2.,  2.,  2.,  2.],
       [ 3.,  3.,  3.,  3.,  3.]])
>>> grid.node_axis_coordinates(1).reshape(grid.shape)
array([[ 0.,  1.,  2.,  3.,  4.],
       [ 0.,  1.,  2.,  3.,  4.],
       [ 0.,  1.,  2.,  3.,  4.],
       [ 0.,  1.,  2.,  3.,  4.]])

node_has_boundary_neighbor()

Check if ModelGrid nodes have neighbors that are boundary nodes.

Checks to see if one of the eight neighbor nodes of node(s) with id has a boundary node. Returns True if a node has a boundary node, False if all neighbors are interior.

Parameters:

ids (int, or iterable of int) – ID of node to test.

Returns:

True if node has a neighbor with a boundary ID, False otherwise.

Return type:

boolean

Examples

    0,  1,  2,  3,
  4,  5,  6,  7,  8,
9, 10,  11, 12, 13, 14,
  15, 16, 17, 18, 19,
    20, 21, 22, 23

>>> from landlab import HexModelGrid
>>> grid = HexModelGrid((5, 4))
>>> grid.node_has_boundary_neighbor()
array([ True,  True,  True,  True,  True,  True,  True,  True,  True,
        True,  True, False, False,  True,  True,  True,  True,  True,
        True,  True,  True,  True,  True,  True], dtype=bool)

>>> grid.node_has_boundary_neighbor()[6]
True
>>> grid.node_has_boundary_neighbor()[12]
False
>>> grid.node_has_boundary_neighbor()[((12, 0),)]
array([False,  True], dtype=bool)

node_is_boundary(ids, boundary_flag=None)

Check if nodes are boundary nodes.

Check if nodes at given ids are boundary nodes. Use the boundary_flag to specify a particular boundary type status flag.

Parameters:

• ids (ndarray) – Node IDs to check.

• boundary_flag (int, optional) – A boundary type to check for.

Returns:

Array of booleans indicating if nodes are boundary nodes.

Return type:

ndarray

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> mg.node_is_boundary([0, 6])
array([ True, False], dtype=bool)
>>> mg.node_is_boundary([0, 6], boundary_flag=mg.BC_NODE_IS_CLOSED)
array([False, False], dtype=bool)

property number_of_active_faces

Total number of active faces.

Returns:

Total number of active faces in the grid.

Return type:

int

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> grid.number_of_active_faces
7

The number of active faces is updated when a node status changes.

>>> grid.status_at_node[6] = grid.BC_NODE_IS_CLOSED
>>> grid.number_of_active_faces
3

property number_of_active_links

Number of active links.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> mg.number_of_active_links
17
>>> for edge in (
...     mg.nodes_at_left_edge,
...     mg.nodes_at_right_edge,
...     mg.nodes_at_bottom_edge,
... ):
...     mg.status_at_node[edge] = mg.BC_NODE_IS_CLOSED
>>> mg.number_of_active_links
10

property number_of_core_cells

Number of core cells.

A core cell excludes all boundary cells.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.number_of_core_cells
6

>>> grid.status_at_node[7] = grid.BC_NODE_IS_CLOSED
>>> grid.number_of_core_cells
5

property number_of_core_nodes

Number of core nodes.

The number of core nodes on the grid (i.e., excluding all boundary nodes).

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.number_of_core_nodes
6

>>> grid.status_at_node[7] = grid.BC_NODE_IS_CLOSED
>>> grid.number_of_core_nodes
5

number_of_elements(name)

Number of instances of an element.

Get the number of instances of a grid element in a grid.

Parameters:

name ({'node', 'cell', 'link', 'face', 'core_node', 'core_cell',) – ‘active_link’, ‘active_face’} Name of the grid element.

Returns:

Number of elements in the grid.

Return type:

int

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> mg.number_of_elements("node")
20
>>> mg.number_of_elements("core_cell")
6
>>> mg.number_of_elements("link")
31
>>> mg.number_of_elements("active_link")
17
>>> mg.status_at_node[8] = mg.BC_NODE_IS_CLOSED
>>> mg.number_of_elements("link")
31
>>> mg.number_of_elements("active_link")
13

property number_of_fixed_links

Number of fixed links.

Examples

>>> from landlab import NodeStatus, RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> mg.number_of_fixed_links
0
>>> mg.status_at_node[mg.nodes_at_top_edge] = NodeStatus.FIXED_GRADIENT
>>> mg.number_of_fixed_links
3

property number_of_patches_present_at_link

Return the number of patches at a link without a closed node.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((3, 3))
>>> mg.status_at_node[mg.nodes_at_top_edge] = mg.BC_NODE_IS_CLOSED
>>> mg.patches_present_at_link
array([[False,  True],
       [False,  True],
       [ True, False],
       [ True,  True],
       [False,  True],
       [ True, False],
       [ True, False],
       [False, False],
       [False, False],
       [False, False],
       [False, False],
       [False, False]], dtype=bool)
>>> mg.number_of_patches_present_at_link
array([1, 1, 1, 2, 1, 1, 1, 0, 0, 0, 0, 0])

property number_of_patches_present_at_node

Return the number of patches at a node without a closed node.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((3, 3))
>>> mg.status_at_node[mg.nodes_at_top_edge] = mg.BC_NODE_IS_CLOSED
>>> mg.patches_present_at_node
array([[ True, False, False, False],
       [ True,  True, False, False],
       [False,  True, False, False],
       [False, False, False,  True],
       [False, False,  True,  True],
       [False, False,  True, False],
       [False, False, False, False],
       [False, False, False, False],
       [False, False, False, False]], dtype=bool)
>>> mg.number_of_patches_present_at_node
array([1, 2, 1, 1, 2, 1, 0, 0, 0])

property open_boundary_nodes

Get array of open boundary nodes.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> for edge in (
...     mg.nodes_at_left_edge,
...     mg.nodes_at_right_edge,
...     mg.nodes_at_bottom_edge,
... ):
...     mg.status_at_node[edge] = mg.BC_NODE_IS_CLOSED
>>> mg.open_boundary_nodes
array([16, 17, 18])

property patches_present_at_link

A boolean array, False where a patch has a closed node or is missing.

The array is the same shape as patches_at_link, and is designed to mask it.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((3, 3))
>>> mg.status_at_node[mg.nodes_at_top_edge] = mg.BC_NODE_IS_CLOSED
>>> mg.patches_at_link
array([[-1,  0],
       [-1,  1],
       [ 0, -1],
       [ 1,  0],
       [-1,  1],
       [ 0,  2],
       [ 1,  3],
       [ 2, -1],
       [ 3,  2],
       [-1,  3],
       [ 2, -1],
       [ 3, -1]])
>>> mg.patches_present_at_link
array([[False,  True],
       [False,  True],
       [ True, False],
       [ True,  True],
       [False,  True],
       [ True, False],
       [ True, False],
       [False, False],
       [False, False],
       [False, False],
       [False, False],
       [False, False]], dtype=bool)
>>> 1 in mg.patches_at_link * mg.patches_present_at_link
True
>>> 2 in mg.patches_at_link * mg.patches_present_at_link
False

property patches_present_at_node

A boolean array, False where a patch has a closed node or is missing.

The array is the same shape as patches_at_node, and is designed to mask it.

Note that in cases where patches may have more than 3 nodes (e.g., rasters), a patch is considered still present as long as at least 3 open nodes are present.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((3, 3))
>>> mg.status_at_node[mg.nodes_at_top_edge] = mg.BC_NODE_IS_CLOSED
>>> mg.patches_at_node
array([[ 0, -1, -1, -1],
       [ 1,  0, -1, -1],
       [-1,  1, -1, -1],
       [ 2, -1, -1,  0],
       [ 3,  2,  0,  1],
       [-1,  3,  1, -1],
       [-1, -1, -1,  2],
       [-1, -1,  2,  3],
       [-1, -1,  3, -1]])
>>> mg.patches_present_at_node
array([[ True, False, False, False],
       [ True,  True, False, False],
       [False,  True, False, False],
       [False, False, False,  True],
       [False, False,  True,  True],
       [False, False,  True, False],
       [False, False, False, False],
       [False, False, False, False],
       [False, False, False, False]], dtype=bool)
>>> 1 in mg.patches_at_node * mg.patches_present_at_node
True
>>> 2 in mg.patches_at_node * mg.patches_present_at_node
False

reset_status_at_node()

resolve_values_on_links(link_values, out=None)

Resolve the xy-components of links.

Resolves values provided defined on links into the x and y directions. Returns values_along_x, values_along_y

set_nodata_nodes_to_closed(node_data, nodata_value)

Make no-data nodes closed boundaries.

Sets node status to BC_NODE_IS_CLOSED for all nodes whose value of node_data is equal to the nodata_value.

Any links connected to BC_NODE_IS_CLOSED nodes are automatically set to LinkStatus.INACTIVE boundary.

Parameters:

• node_data (ndarray) – Data values.

• nodata_value (float) – Value that indicates an invalid value.

Examples

The following example uses the following grid:

*--I--->o------>o------>o
^       ^       ^       ^
I       I       |       |
|       |       |       |
*--I--->*--I--->o------>o
^       ^       ^       ^
I       I       I       I
|       |       |       |
*--I--->*--I--->*--I--->*

Note

Links set to LinkStatus.ACTIVE are not shown in this diagram.

* indicates the nodes that are set to NodeStatus.CLOSED

o indicates the nodes that are set to NodeStatus.CORE

I indicates the links that are set to LinkStatus.INACTIVE

>>> import numpy as np
>>> import landlab as ll
>>> mg = ll.RasterModelGrid((3, 4))
>>> mg.status_at_node.reshape(mg.shape)
array([[1, 1, 1, 1],
       [1, 0, 0, 1],
       [1, 1, 1, 1]], dtype=uint8)
>>> h = np.array(
...     [
...         [-9999, -9999, -9999, -9999],
...         [-9999, -9999, 12345.0, 0.0],
...         [-9999, 0.0, 0.0, 0.0],
...     ]
... ).flatten()
>>> mg.set_nodata_nodes_to_closed(h, -9999)
>>> mg.status_at_node.reshape(mg.shape)
array([[4, 4, 4, 4],
       [4, 4, 0, 1],
       [4, 1, 1, 1]], dtype=uint8)

set_nodata_nodes_to_fixed_gradient(node_data, nodata_value)

Make no-data nodes fixed gradient boundaries.

Set node status to BC_NODE_IS_FIXED_VALUE for all nodes whose value of node_data is equal to nodata_value.

Any links between BC_NODE_IS_FIXED_GRADIENT nodes and BC_NODE_IS_CORE are automatically set to LinkStatus.FIXED boundary status.

Parameters:

• node_data (ndarray) – Data values.

• nodata_value (float) – Value that indicates an invalid value.

Examples

The following examples use this grid:

*--I--->*--I--->*--I--->*--I--->*--I--->*--I--->*--I--->*--I--->*
^       ^       ^       ^       ^       ^       ^       ^       ^
I       I       I       X       X       X       X       X       I
|       |       |       |       |       |       |       |       |
*--I--->*--I--->*--X--->o       o       o       o       o--X--->*
^       ^       ^       ^       ^       ^       ^       ^       ^
I       I       I       |       |       |       |       |       I
|       |       |       |       |       |       |       |       |
*--I--->*--I--->*--X--->o       o       o       o       o--X--->*
^       ^       ^       ^       ^       ^       ^       ^       ^
I       I       I       X       X       X       X       X       I
|       |       |       |       |       |       |       |       |
*--I--->*--I--->*--I--->*--I--->*--I--->*--I--->*--I--->*--I--->*

Note

Links set to LinkStatus.ACTIVE are not shown in this diagram.

X indicates the links that are set to LinkStatus.FIXED

I indicates the links that are set to LinkStatus.INACTIVE

o indicates the nodes that are set to NodeStatus.CORE

* indicates the nodes that are set to

BC_NODE_IS_FIXED_GRADIENT

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 9))
>>> rmg.status_at_node.reshape(rmg.shape)
array([[1, 1, 1, 1, 1, 1, 1, 1, 1],
       [1, 0, 0, 0, 0, 0, 0, 0, 1],
       [1, 0, 0, 0, 0, 0, 0, 0, 1],
       [1, 1, 1, 1, 1, 1, 1, 1, 1]], dtype=uint8)

>>> z = np.array(
...     [
...         [-99.0, -99.0, -99.0, -99.0, -99.0, -99.0, -99.0, -99.0, -99.0],
...         [-99.0, -99.0, -99.0, 0.0, 0.0, 0.0, 0.0, 0.0, -99.0],
...         [-99.0, -99.0, -99.0, 0.0, 0.0, 0.0, 0.0, 0.0, -99.0],
...         [-99.0, -99.0, -99.0, -99.0, -99.0, -99.0, -99.0, -99.0, -99.0],
...     ]
... ).flatten()

>>> rmg.set_nodata_nodes_to_fixed_gradient(z, -99)
>>> rmg.status_at_node.reshape(rmg.shape)
array([[2, 2, 2, 2, 2, 2, 2, 2, 2],
       [2, 2, 2, 0, 0, 0, 0, 0, 2],
       [2, 2, 2, 0, 0, 0, 0, 0, 2],
       [2, 2, 2, 2, 2, 2, 2, 2, 2]], dtype=uint8)

>>> rmg.status_at_link[rmg.horizontal_links].reshape((4, 8))
array([[4, 4, 4, 4, 4, 4, 4, 4],
       [4, 4, 2, 0, 0, 0, 0, 2],
       [4, 4, 2, 0, 0, 0, 0, 2],
       [4, 4, 4, 4, 4, 4, 4, 4]], dtype=uint8)
>>> rmg.status_at_link[rmg.vertical_links].reshape((3, 9))
array([[4, 4, 4, 2, 2, 2, 2, 2, 4],
       [4, 4, 4, 0, 0, 0, 0, 0, 4],
       [4, 4, 4, 2, 2, 2, 2, 2, 4]], dtype=uint8)

property status_at_link

Get array of the status of all links.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> mg.status_at_node[mg.nodes_at_left_edge] = mg.BC_NODE_IS_CLOSED
>>> mg.status_at_node[mg.nodes_at_right_edge] = mg.BC_NODE_IS_FIXED_GRADIENT
>>> mg.status_at_link
array([4, 4, 4, 4, 4, 0, 0, 0, 4, 4, 0, 0, 2, 4, 0, 0, 0, 4, 4, 0, 0,
       2, 4, 0, 0, 0, 4, 4, 4, 4, 4], dtype=uint8)

property status_at_node

Get array of the boundary status for each node.

Examples

>>> import numpy as np
>>> from landlab import LinkStatus, NodeStatus, RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> mg.status_at_node.reshape((4, 5))
array([[1, 1, 1, 1, 1],
       [1, 0, 0, 0, 1],
       [1, 0, 0, 0, 1],
       [1, 1, 1, 1, 1]], dtype=uint8)
>>> np.any(mg.status_at_link == LinkStatus.FIXED)
False

>>> mg.status_at_node[mg.nodes_at_left_edge] = NodeStatus.FIXED_GRADIENT
>>> mg.status_at_node.reshape((4, 5))
array([[2, 1, 1, 1, 1],
       [2, 0, 0, 0, 1],
       [2, 0, 0, 0, 1],
       [2, 1, 1, 1, 1]], dtype=uint8)
>>> np.any(mg.status_at_link == LinkStatus.FIXED)  # links auto-update
True

property unit_vector_sum_xcomponent_at_node

Get array of x-component of unit vector sums at each node.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 3))
>>> len(grid.unit_vector_sum_xcomponent_at_node) == grid.number_of_nodes
True
>>> grid.unit_vector_sum_xcomponent_at_node
array([ 1.,  2.,  1.,  1.,  2.,  1.,  1.,  2.,  1.])

property unit_vector_sum_ycomponent_at_node

Get array of y-component of unit vector sums at each node.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 3))
>>> len(grid.unit_vector_sum_ycomponent_at_node) == grid.number_of_nodes
True
>>> grid.unit_vector_sum_ycomponent_at_node
array([ 1.,  1.,  1.,  2.,  2.,  2.,  1.,  1.,  1.])

upwind_links_at_node(values, bad_index=-1)

Return an (nnodes, X) shape array of link IDs of which links are upwind of each node, according to values (field or array).

X is the maximum upwind links at any node. Nodes with fewer upwind links than this have additional slots filled with bad_index. Links are ordered anticlockwise from east.

Parameters:

• values (str or array) – Name of variable field defined at links, or array of values at links.

• bad_index (int) – Index to place in array indicating no link.

Returns:

Array of upwind link IDs

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -5.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> rmg.upwind_links_at_node("grad", bad_index=-1)
array([[-1, -1],
       [ 0, -1],
       [ 1, -1],
       [ 2, -1],
       [ 3, -1],
       [ 7,  4],
       [ 8,  5],
       [ 9,  6],
       [10, -1],
       [14, 11],
       [15, 12],
       [16, 13]])

property xy_of_reference

Return the coordinates (x, y) of the reference point.

For RasterModelGrid and HexModelGrid the reference point is the minimum of x_of_node and of y_of_node. By default it is (0, 0). For VoronoiDelaunayGrid the reference point is (0, 0). For RadialModelGrid it is the (x, y) of the center point.

The intention of these coordinates is to provide a method to store the large float values of projected coordinates.

Example

>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 5), xy_of_reference=(12345, 678910))
>>> rmg.xy_of_reference
(12345, 678910)
>>> rmg.xy_of_reference = (98765, 43210)
>>> rmg.xy_of_reference
(98765, 43210)

class NetworkModelGrid(yx_of_node, links, xy_axis_name=('x', 'y'), xy_axis_units='-', xy_of_reference=(0.0, 0.0))

Create a ModelGrid of just nodes and links.

Parameters:

• yx_of_node (tuple of ndarray) – Node y and x coordinates.

• links (array of tuple of int) – Nodes at link tail and head.

• xy_of_reference (tuple, optional) – Coordinate value in projected space of (0., 0.) Default is (0., 0.)

Examples

>>> from landlab import NetworkModelGrid
>>> y_of_node = (0, 1, 2, 2)
>>> x_of_node = (0, 0, -1, 1)
>>> nodes_at_link = ((1, 0), (2, 1), (3, 1))
>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)
>>> grid.x_of_node
array([ 0.,  0., -1.,  1.])
>>> grid.y_of_node
array([ 0.,  1.,  2.,  2.])
>>> grid.nodes_at_link
array([[0, 1],
       [2, 1],
       [1, 3]])

Define a graph of connected nodes.

Parameters:

mesh (Dataset) – xarray Dataset that defines the topology in ugrid format.

BAD_INDEX = -1

Indicates a node is bad index.

BC_LINK_IS_ACTIVE = 0

Indicates a link is active, and can carry flux

BC_LINK_IS_FIXED = 2

Indicates a link has a fixed gradient value, and behaves as a boundary

BC_LINK_IS_INACTIVE = 4

Indicates a link is inactive, and cannot carry flux

BC_NODE_IS_CLOSED = 4

Indicates a boundary node is closed

BC_NODE_IS_CORE = 0

Indicates a node is core.

BC_NODE_IS_FIXED_GRADIENT = 2

Indicates a boundary node has a fixed gradient.

BC_NODE_IS_FIXED_VALUE = 1

Indicates a boundary node has a fixed value.

BC_NODE_IS_LOOPED = 3

Indicates a boundary node is wrap-around.

VALID_LOCATIONS = ('node', 'link', 'grid')

Grid elements on which fields can be placed.

property active_links

Get array of active links.

Examples

>>> from landlab import NetworkModelGrid

>>> y_of_node = (0, 1, 2, 2)
>>> x_of_node = (0, 0, -1, 1)
>>> nodes_at_link = ((1, 0), (2, 1), (3, 1))
>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)
>>> grid.active_links
array([0, 1, 2])

at_grid = {}

at_link = {}

at_node = {}

property axis_name

Get the name of each coordinate axis.

Returns:

The names of each axis.

Return type:

tuple of str

Examples

>>> from landlab import NetworkModelGrid
>>> y_of_node = (0, 1, 2, 2)
>>> x_of_node = (0, 0, -1, 1)
>>> nodes_at_link = ((1, 0), (2, 1), (3, 1))

>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)
>>> grid.axis_name
('x', 'y')
>>> grid.axis_name = ("lon", "lat")
>>> grid.axis_name
('lon', 'lat')

>>> grid = NetworkModelGrid(
...     (y_of_node, x_of_node), nodes_at_link, xy_axis_name=("lon", "lat")
... )
>>> grid.axis_name
('lon', 'lat')

property axis_units

Get units for each axis.

Returns:

The units (as a string) for each of a grid’s coordinates.

Return type:

tuple of str

Examples

>>> from landlab import NetworkModelGrid
>>> y_of_node = (0, 1, 2, 2)
>>> x_of_node = (0, 0, -1, 1)
>>> nodes_at_link = ((1, 0), (2, 1), (3, 1))
>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)
>>> grid.axis_units
('-', '-')
>>> grid.axis_units = ("km", "km")
>>> grid.axis_units
('km', 'km')

calc_grad_at_link(node_values, out=None)

Calculate gradients of node values at links.

Calculates the gradient in node_values at each link in the grid, returning an array of length number_of_links.

Parameters:

• node_values (ndarray or field name (x number of nodes)) – Values at grid nodes.

• out (ndarray, optional (x number of links)) – Buffer to hold the result.

Returns:

Gradients across active links.

Return type:

ndarray

Examples

>>> from landlab import RasterModelGrid
>>> rg = RasterModelGrid((3, 4), xy_spacing=10.0)
>>> z = rg.add_zeros("topographic__elevation", at="node")
>>> z[5] = 50.0
>>> z[6] = 36.0
>>> calc_grad_at_link(rg, z)  # there are 17 links
array([ 0. ,  0. ,  0. ,  0. ,  5. ,  3.6,  0. ,  5. , -1.4, -3.6,  0. ,
       -5. , -3.6,  0. ,  0. ,  0. ,  0. ])

>>> from landlab import HexModelGrid
>>> hg = HexModelGrid((3, 3), spacing=10.0)
>>> z = hg.add_zeros("topographic__elevation", at="node", clobber=True)
>>> z[4] = 50.0
>>> z[5] = 36.0
>>> calc_grad_at_link(hg, z)  # there are 11 faces
array([ 0. ,  0. ,  0. ,  5. ,  5. ,  3.6,  3.6,  0. ,  5. , -1.4, -3.6,
        0. , -5. , -5. , -3.6, -3.6,  0. ,  0. ,  0. ])

classmethod from_dict(params)

classmethod from_file(file_like)

map_downwind_node_link_max_to_node(var_name, out=None)

Map the largest magnitude of the links carrying flux from the node to the node.

map_downwind_node_link_max_to_node iterates across the grid and identifies the link values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links carrying flux out of the node, then maps the maximum magnitude of ‘var_name’ found on these links onto the node. If no downwind link is found, the value will be recorded as zero.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_downwind_node_link_max_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     0.0,
...     0.0,
...     0.0,
...     0.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     0.0,
...     0.0,
...     0.0,
...     0.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> map_downwind_node_link_max_to_node(rmg, "grad")
array([ 1.,  2.,  1.,  0.,
        1.,  2.,  1.,  0.,
        1.,  2.,  1.,  0.])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_downwind_node_link_max_to_node(rmg, "grad", out=values_at_nodes)
>>> values_at_nodes
array([ 1.,  2.,  1.,  0.,
        1.,  2.,  1.,  0.,
        1.,  2.,  1.,  0.])
>>> rtn is values_at_nodes
True

map_downwind_node_link_mean_to_node(var_name, out=None)

Map the mean magnitude of the links carrying flux out of the node to the node.

map_downwind_node_link_mean_to_node iterates across the grid and identifies the link values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links carrying flux out of the node, then maps the mean magnitude of ‘var_name’ found on these links onto the node. Links with zero values are not included in the means, and zeros are returned if no upwind links are found.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_downwind_node_link_mean_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -5.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> map_downwind_node_link_mean_to_node(rmg, "grad")
array([ 1.5,  2.5,  2.5,  5. ,
        1. ,  2. ,  2. ,  4. ,
        1. ,  2. ,  1. ,  0. ])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_downwind_node_link_mean_to_node(rmg, "grad", out=values_at_nodes)
>>> values_at_nodes
array([ 1.5,  2.5,  2.5,  5. ,
        1. ,  2. ,  2. ,  4. ,
        1. ,  2. ,  1. ,  0. ])
>>> rtn is values_at_nodes
True

map_link_head_node_to_link(var_name, out=None)

Map values from a link head nodes to links.

Iterate over a grid and identify the node at the head. For each link, the value of var_name at the head node is mapped to the corresponding link.

In a RasterModelGrid, each one node has two adjacent “link heads”. This means each node value is mapped to two corresponding links.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_link_head_node_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_node["z"] = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
>>> map_link_head_node_to_link(rmg, "z")
array([  1.,   2.,   3.,   4.,   5.,   6.,   7.,   5.,   6.,   7.,   8.,
      9.,  10.,  11.,   9.,  10.,  11.])

>>> values_at_links = rmg.empty(at="link")
>>> rtn = map_link_head_node_to_link(rmg, "z", out=values_at_links)
>>> values_at_links
array([  1.,   2.,   3.,   4.,   5.,   6.,   7.,   5.,   6.,   7.,   8.,
      9.,  10.,  11.,   9.,  10.,  11.])
>>> rtn is values_at_links
True

map_link_tail_node_to_link(var_name, out=None)

Map values from a link tail nodes to links.

map_link_tail_node_to_link iterates across the grid and identifies the node at the “tail”, or the “from” node for each link. For each link, the value of ‘var_name’ at the “from” node is mapped to the corresponding link.

In a RasterModelGrid, each one node has two adjacent “link tails”. This means each node value is mapped to two corresponding links.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_link_tail_node_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_node["z"] = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
>>> map_link_tail_node_to_link(rmg, "z")
array([  0.,   1.,   2.,   0.,   1.,   2.,   3.,   4.,   5.,   6.,   4.,
         5.,   6.,   7.,   8.,   9.,  10.])

>>> values_at_links = rmg.empty(at="link")
>>> rtn = map_link_tail_node_to_link(rmg, "z", out=values_at_links)
>>> values_at_links
array([  0.,   1.,   2.,   0.,   1.,   2.,   3.,   4.,   5.,   6.,   4.,
         5.,   6.,   7.,   8.,   9.,  10.])
>>> rtn is values_at_links
True

map_link_vector_components_to_node(data_at_link)

Map (x,y) components of link data data_at_link onto nodes.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid, HexModelGrid

>>> grid = RasterModelGrid((3, 4))
>>> link_data = np.arange(grid.number_of_links)

>>> vx, vy = grid.map_link_vector_components_to_node(link_data)
>>> vx[5:7]
array([ 7.5, 8.5])

>>> grid = HexModelGrid((3, 3))
>>> link_data = np.zeros(grid.number_of_links) + 0.5 * 3.0**0.5
>>> link_data[np.isclose(grid.angle_of_link, 0.0)] = 0.0
>>> vx, vy = grid.map_link_vector_components_to_node(link_data)
>>> vy
array([ 0.,  0.,  0.,  0.,  1.,  1.,  0.,  0.,  0.,  0.])

map_max_of_link_nodes_to_link(var_name, out=None)

Map the maximum of a link’s nodes to the link.

map_max_of_link_nodes_to_link iterates across the grid and identifies the node values at both the “head” and “tail” of a given link. This function evaluates the value of ‘var_name’ at both the “to” and “from” node. The maximum value of the two node values is then mapped to the link.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_max_of_link_nodes_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field(
...     "z",
...     [
...         [0, 1, 2, 3],
...         [7, 6, 5, 4],
...         [8, 9, 10, 11],
...     ],
...     at="node",
... )
>>> map_max_of_link_nodes_to_link(rmg, "z")
array([  1.,   2.,   3.,   7.,   6.,   5.,   4.,   7.,   6.,   5.,   8.,
         9.,  10.,  11.,   9.,  10.,  11.])

>>> values_at_links = rmg.empty(at="link")
>>> rtn = map_max_of_link_nodes_to_link(rmg, "z", out=values_at_links)
>>> values_at_links
array([  1.,   2.,   3.,   7.,   6.,   5.,   4.,   7.,   6.,   5.,   8.,
         9.,  10.,  11.,   9.,  10.,  11.])
>>> rtn is values_at_links
True

map_max_of_node_links_to_node(var_name, out=None)

Map the maximum value of a nodes’ links to the node.

map_max_of_node_links_to_node iterates across the grid and identifies the link values at each link connected to a node. This function finds the maximum value of ‘var_name’ of each set of links, and then maps this value to the node. Note no attempt is made to honor the directionality of the links.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_max_of_node_links_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = np.arange(rmg.number_of_links)
>>> map_max_of_node_links_to_node(rmg, "grad")
array([  3.,   4.,   5.,   6.,
        10.,  11.,  12.,  13.,
        14.,  15.,  16.,  16.])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_max_of_node_links_to_node(rmg, "grad", out=values_at_nodes)
>>> values_at_nodes
array([  3.,   4.,   5.,   6.,
        10.,  11.,  12.,  13.,
        14.,  15.,  16.,  16.])
>>> rtn is values_at_nodes
True

map_mean_of_link_nodes_to_link(var_name, out=None)

Map the mean of a link’s nodes to the link.

map_mean_of_link_nodes_to_link iterates across the grid and identifies the node values at both the “head” and “tail” of a given link. This function takes the sum of the two values of ‘var_name’ at both the “to” and “from” node. The average value of the two node values of ‘var_name’ is then mapped to the link.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_mean_of_link_nodes_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_node["z"] = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
>>> map_mean_of_link_nodes_to_link(rmg, "z")
array([  0.5,   1.5,   2.5,   2. ,   3. ,   4. ,   5. ,   4.5,   5.5,
         6.5,   6. ,   7. ,   8. ,   9. ,   8.5,   9.5,  10.5])

>>> values_at_links = rmg.empty(at="link")
>>> rtn = map_mean_of_link_nodes_to_link(rmg, "z", out=values_at_links)
>>> values_at_links
array([  0.5,   1.5,   2.5,   2. ,   3. ,   4. ,   5. ,   4.5,   5.5,
         6.5,   6. ,   7. ,   8. ,   9. ,   8.5,   9.5,  10.5])
>>> rtn is values_at_links
True

map_min_of_link_nodes_to_link(var_name, out=None)

Map the minimum of a link’s nodes to the link.

map_min_of_link_nodes_to_link iterates across the grid and identifies the node values at both the “head” and “tail” of a given link. This function evaluates the value of ‘var_name’ at both the “to” and “from” node. The minimum value of the two node values is then mapped to the link.

Parameters:

• var_name (array or field name) – Values defined at nodes.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_min_of_link_nodes_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field(
...     "z",
...     [
...         [0, 1, 2, 3],
...         [7, 6, 5, 4],
...         [8, 9, 10, 11],
...     ],
...     at="node",
... )
>>> map_min_of_link_nodes_to_link(rmg, "z")
array([  0.,   1.,   2.,   0.,   1.,   2.,   3.,   6.,   5.,   4.,   7.,
         6.,   5.,   4.,   8.,   9.,  10.])

>>> values_at_links = rmg.empty(at="link")
>>> rtn = map_min_of_link_nodes_to_link(rmg, "z", out=values_at_links)
>>> values_at_links
array([  0.,   1.,   2.,   0.,   1.,   2.,   3.,   6.,   5.,   4.,   7.,
         6.,   5.,   4.,   8.,   9.,  10.])
>>> rtn is values_at_links
True

map_min_of_node_links_to_node(var_name, out=None)

Map the minimum value of a nodes’ links to the node.

map_min_of_node_links_to_node iterates across the grid and identifies the link values at each link connected to a node. This function finds the minimum value of ‘var_name’ of each set of links, and then maps this value to the node. Note no attempt is made to honor the directionality of the links.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_min_of_node_links_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = np.arange(rmg.number_of_links)
>>> map_min_of_node_links_to_node(rmg, "grad")
array([  0.,   0.,   1.,   2.,
         3.,   4.,   5.,   6.,
        10.,  11.,  12.,  13.])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_min_of_node_links_to_node(rmg, "grad", out=values_at_nodes)
>>> values_at_nodes
array([  0.,   0.,   1.,   2.,
         3.,   4.,   5.,   6.,
        10.,  11.,  12.,  13.])
>>> rtn is values_at_nodes
True

map_node_to_link_lax_wendroff(v, c, out=None)

Assign values to links using a weighted combination of node values.

Assign to each link a weighted combination of values v at nodes using the Lax-Wendroff method for upwind weighting.

c is a scalar or link vector that gives the link-parallel signed Courant number. Where c is positive, velocity is in the direction of the link; where negative, velocity is in the opposite direction.

As an example, consider 3x5 raster grid with the following values at the nodes in the central row:

0---1---2---3---4

Consider a uniform Courant value c = +0.2 at the horizontal links. The mapped link values should be:

.-0.4-.-1.4-.-2.4-.-3.4-.

Values at links when c = -0.2:

.-0.6-.-1.6-.-2.6-.-3.6-.

Parameters:

• v ((n_nodes,) ndarray) – Values at grid nodes.

• c (float or (n_links,) ndarray) – Courant number to use at links.

• out ((n_links,) ndarray, optional) – If provided, place calculated values in this array. Otherwise, create a new array.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid

>>> grid = RasterModelGrid((3, 5))
>>> grid.at_node["node_value"] = [
...     [0.0, 0.0, 0.0, 0.0, 0.0],
...     [0.0, 1.0, 2.0, 3.0, 4.0],
...     [0.0, 0.0, 0.0, 0.0, 0.0],
... ]
>>> v = grid.at_node["node_value"]

>>> c = grid.add_zeros("courant_number", at="link")
>>> c[grid.horizontal_links] = 0.2

Set values for the middle row of horizontal links.

>>> val_at_link = grid.map_node_to_link_lax_wendroff(v, c)
>>> val_at_link[9:13]
array([ 0.4,  1.4,  2.4,  3.4])
>>> val_at_link = grid.map_node_to_link_lax_wendroff(v, -c)
>>> val_at_link[9:13]
array([ 0.6,  1.6,  2.6,  3.6])

map_node_to_link_linear_upwind(v, u, out=None)

Assign values to links from upstream nodes.

Assign to each link the value v associated with whichever of its two nodes lies upstream, according to link value u.

Consider a link k with tail node t(k) and head node t(h). Nodes have value v(n). We want to assign a value to links, v’(k). The assignment is:

v'(k) = v(t(k)) where u(k) > 0,
v'(k) = v(h(k)) where u(k) <= 0

As an example, consider 3x5 raster grid with the following values at the nodes in the central row:

0---1---2---3---4

Consider a uniform velocity value u = 1 at the horizontal links. The mapped link values should be:

.-0-.-1-.-2-.-3-.

If u < 0, the link values should be:

.-1-.-2-.-3-.-4-.

Parameters:

• v ((n_nodes,), ndarray) – Values at grid nodes.

• u ((n_links,) ndarray) – Values at grid links.

• out ((n_links,) ndarray, optional) – If provided, place calculated values in this array. Otherwise, create a new array.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid

>>> grid = RasterModelGrid((3, 5))
>>> grid.at_node["node_value"] = [
...     [0.0, 0.0, 0.0, 0.0, 0.0],
...     [0.0, 1.0, 2.0, 3.0, 4.0],
...     [0.0, 0.0, 0.0, 0.0, 0.0],
... ]
>>> v = grid.at_node["node_value"]

>>> u = grid.add_zeros("advection_speed", at="link")
>>> u[grid.horizontal_links] = 1.0

Set values for the middle row of horizontal links.

>>> val_at_link = grid.map_node_to_link_linear_upwind(v, u)
>>> val_at_link[9:13]
array([ 0.,  1.,  2.,  3.])
>>> val_at_link = grid.map_node_to_link_linear_upwind(v, -u)
>>> val_at_link[9:13]
array([ 1.,  2.,  3.,  4.])

map_upwind_node_link_max_to_node(var_name, out=None)

Map the largest magnitude of the links bringing flux into the node to the node.

map_upwind_node_link_max_to_node iterates across the grid and identifies the link values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links bringing flux into the node, then maps the maximum magnitude of ‘var_name’ found on these links onto the node. If no upwind link is found, the value will be recorded as zero.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_upwind_node_link_max_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.1,
...     -1.2,
...     -1.3,
...     1.4,
...     1.5,
...     1.6,
...     -1.7,
...     -1.8,
...     -1.9,
...     2.0,
...     2.1,
...     2.2,
...     -2.3,
...     2.4,
...     2.5,
...     2.6,
...     -2.7,
... ]
>>> map_upwind_node_link_max_to_node(rmg, "grad").reshape((3, 4))
array([[ 1.4,  1.5,  1.6,  1.3],
       [ 2.1,  2.2,  2. ,  2.4],
       [ 2.5,  2.6,  2.3,  2.7]])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_upwind_node_link_max_to_node(rmg, "grad", out=values_at_nodes)
>>> values_at_nodes.reshape((3, 4))
array([[ 1.4,  1.5,  1.6,  1.3],
       [ 2.1,  2.2,  2. ,  2.4],
       [ 2.5,  2.6,  2.3,  2.7]])
>>> rtn is values_at_nodes
True

map_upwind_node_link_mean_to_node(var_name, out=None)

Map the mean magnitude of the links bringing flux into the node to the node.

map_upwind_node_link_mean_to_node iterates across the grid and identifies the link values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links bringing flux into the node, then maps the mean magnitude of ‘var_name’ found on these links onto the node. Links with zero values are not included in the means, and zeros are returned if no upwind links are found.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_upwind_node_link_mean_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -5.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     -1.0,
...     -2.0,
...     -3.0,
...     -4.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> map_upwind_node_link_mean_to_node(rmg, "grad")
array([ 0. ,  1. ,  2. ,  1. ,
        2. ,  2. ,  3. ,  3. ,
        1. ,  1.5,  2.5,  2.5])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_upwind_node_link_mean_to_node(rmg, "grad", out=values_at_nodes)
>>> values_at_nodes
array([ 0. ,  1. ,  2. ,  1. ,
        2. ,  2. ,  3. ,  3. ,
        1. ,  1.5,  2.5,  2.5])
>>> rtn is values_at_nodes
True

map_value_at_downwind_node_link_max_to_node(control_name, value_name, out=None)

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_downwind_node_link_max_to_node iterates across the grid and identifies the link control_values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links carrying flux out of the node, then identifies the link with the maximum magnitude. The value of the second field ‘value_name’ at these links is then mapped onto the node. If no downwind link is found, the value will be recorded as zero.

Parameters:

• control_name (array or field name) – Values defined at nodes that dictate which end of the link to draw values from.

• value_name (array or field name) – Values defined at nodes from which values are drawn, based on control_name.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_value_at_downwind_node_link_max_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     0.0,
...     0.0,
...     0.0,
...     0.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     0.0,
...     0.0,
...     0.0,
...     0.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> rmg.at_link["vals"] = np.arange(rmg.number_of_links, dtype=float)
>>> map_value_at_downwind_node_link_max_to_node(rmg, "grad", "vals")
array([  0.,   1.,   2.,   0.,
         7.,   8.,   9.,   0.,
        14.,  15.,  16.,   0.])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_value_at_downwind_node_link_max_to_node(
...     rmg, "grad", "vals", out=values_at_nodes
... )
>>> values_at_nodes
array([  0.,   1.,   2.,   0.,
         7.,   8.,   9.,   0.,
        14.,  15.,  16.,   0.])
>>> rtn is values_at_nodes
True

map_value_at_max_node_to_link(control_name, value_name, out=None)

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_max_node_to_link iterates across the grid and identifies the node values at both the “head” and “tail” of a given link. This function evaluates the value of ‘control_name’ at both the “to” and “from” node. The value of ‘value_name’ at the node with the maximum value of the two values of ‘control_name’ is then mapped to the link.

Parameters:

• control_name (array or field name) – Name of field defined at nodes or a node array that dictates which end of the link to draw values from.

• value_name (array or field name) – Name of field defined at nodes or node array from which values are drawn, based on control_name.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_value_at_max_node_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field(
...     "z",
...     [
...         [0, 1, 2, 3],
...         [7, 6, 5, 4],
...         [8, 9, 10, 11],
...     ],
...     at="node",
... )
>>> _ = rmg.add_field(
...     "vals_to_map",
...     [
...         [0, 10, 20, 30],
...         [70, 60, 50, 40],
...         [80, 90, 100, 110],
...     ],
...     at="node",
... )
>>> map_value_at_max_node_to_link(rmg, "z", "vals_to_map")
array([  10.,   20.,   30.,   70.,   60.,   50.,   40.,   70.,   60.,
         50.,   80.,   90.,  100.,  110.,   90.,  100.,  110.])

map_value_at_min_node_to_link(control_name, value_name, out=None)

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_min_node_to_link iterates across the grid and identifies the node values at both the “head” and “tail” of a given link. This function evaluates the value of ‘control_name’ at both the “to” and “from” node. The value of ‘value_name’ at the node with the minimum value of the two values of ‘control_name’ is then mapped to the link.

Parameters:

• control_name (array or field name) – Name of field defined at nodes or a node array that dictates which end of the link to draw values from.

• value_name (array or field name) – Name of field defined at nodes or node array from which values are drawn, based on control_name.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_value_at_min_node_to_link
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field(
...     "z",
...     [
...         [0, 1, 2, 3],
...         [7, 6, 5, 4],
...         [8, 9, 10, 11],
...     ],
...     at="node",
... )
>>> _ = rmg.add_field(
...     "vals_to_map",
...     [
...         [0, 10, 20, 30],
...         [70, 60, 50, 40],
...         [80, 90, 100, 110],
...     ],
...     at="node",
... )
>>> map_value_at_min_node_to_link(rmg, "z", "vals_to_map")
array([   0.,   10.,   20.,    0.,   10.,   20.,   30.,   60.,   50.,
         40.,   70.,   60.,   50.,   40.,   80.,   90.,  100.])

map_value_at_upwind_node_link_max_to_node(control_name, value_name, out=None)

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.

map_upwind_node_link_max_to_node iterates across the grid and identifies the link control_values at each link connected to a node. It then uses the link_dirs_at_node data structure to identify links bringing flux into the node, then identifies the link with the maximum magnitude. The value of the second field ‘value_name’ at these links is then mapped onto the node. If no upwind link is found, the value will be recorded as zero.

Parameters:

• control_name (array or field name) – Values defined at nodes that dictate which end of the link to draw values from.

• value_name (array or field name) – Values defined at nodes from which values are drawn, based on control_name.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.mappers import map_value_at_upwind_node_link_max_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> rmg.at_link["grad"] = [
...     -1.0,
...     -2.0,
...     -1.0,
...     0.0,
...     0.0,
...     0.0,
...     0.0,
...     -1.0,
...     -2.0,
...     -1.0,
...     0.0,
...     0.0,
...     0.0,
...     0.0,
...     -1.0,
...     -2.0,
...     -1.0,
... ]
>>> rmg.at_link["vals"] = np.arange(rmg.number_of_links, dtype=float)
>>> map_value_at_upwind_node_link_max_to_node(rmg, "grad", "vals")
array([  0.,   0.,   1.,   2.,
         0.,   7.,   8.,   9.,
         0.,  14.,  15.,  16.])

>>> values_at_nodes = rmg.add_empty("z", at="node")
>>> rtn = map_value_at_upwind_node_link_max_to_node(
...     rmg, "grad", "vals", out=values_at_nodes
... )
>>> values_at_nodes
array([  0.,   0.,   1.,   2.,
         0.,   7.,   8.,   9.,
         0.,  14.,  15.,  16.])
>>> rtn is values_at_nodes
True

map_vectors_to_links(ux, uy, out=None)

Map magnitude and sign of vectors with components (ux, uy) onto grid links.

Examples

>>> from landlab import HexModelGrid
>>> import numpy
>>> hmg = HexModelGrid((3, 2))
>>> (numpy.round(10 * map_vectors_to_links(hmg, 1.0, 0.0))).astype(int)
array([10, -5,  5, -5,  5, 10, 10,  5, -5,  5, -5, 10])

reset_status_at_node()

property status_at_link

Get array of the status of all links.

Examples

>>> from landlab import NetworkModelGrid
>>> y_of_node = (0, 1, 2, 2)
>>> x_of_node = (0, 0, -1, 1)
>>> nodes_at_link = ((1, 0), (2, 1), (3, 1))
>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)
>>> grid.status_at_link
array([0, 0, 0], dtype=uint8)

property status_at_node

Get array of the boundary status for each node.

Examples

>>> from landlab import NetworkModelGrid

>>> y_of_node = (0, 1, 2, 2)
>>> x_of_node = (0, 0, -1, 1)
>>> nodes_at_link = ((1, 0), (2, 1), (3, 1))
>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)
>>> grid.status_at_node
array([0, 0, 0, 0], dtype=uint8)
>>> grid.status_at_link
array([0, 0, 0], dtype=uint8)

Now we change the status at node 0 to a closed boundary. This will result in changing the link status as well.

>>> grid.status_at_node = [
...     grid.BC_NODE_IS_CLOSED,
...     grid.BC_NODE_IS_CORE,
...     grid.BC_NODE_IS_CORE,
...     grid.BC_NODE_IS_CORE,
... ]
>>> grid.status_at_node
array([4, 0, 0, 0], dtype=uint8)
>>> grid.status_at_link
array([4, 0, 0], dtype=uint8)

property x_of_link

Get array of the x-coordinates of link midpoints.

Examples

>>> from landlab import NetworkModelGrid
>>> y_of_node = (0, 1, 2, 2)
>>> x_of_node = (0, 0, -1, 1)
>>> nodes_at_link = ((1, 0), (2, 1), (3, 1))
>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)
>>> grid.x_of_link
array([ 0. , -0.5,  0.5])

property xy_of_reference

Return the coordinates (x, y) of the reference point.

For RasterModelGrid and HexModelGrid the reference point is the minimum of x_of_node and of y_of_node. By default it is (0, 0). For VoronoiDelaunayGrid the reference point is (0, 0). For RadialModelGrid it is the (x, y) of the center point.

The intention of these coordinates is to provide a method to store the large float values of projected coordinates.

Example

>>> from landlab import NetworkModelGrid
>>> y_of_node = (0, 1, 2, 2)
>>> x_of_node = (0, 0, -1, 1)
>>> nodes_at_link = ((1, 0), (2, 1), (3, 1))
>>> grid = NetworkModelGrid(
...     (y_of_node, x_of_node), nodes_at_link, xy_of_reference=(12345, 678910)
... )
>>> grid.xy_of_reference
(12345, 678910)
>>> grid.xy_of_reference = (98765, 43210)
>>> grid.xy_of_reference
(98765, 43210)

property y_of_link

Get array of the y-coordinates of link midpoints.

Examples

>>> from landlab import NetworkModelGrid
>>> y_of_node = (0, 1, 2, 2)
>>> x_of_node = (0, 0, -1, 1)
>>> nodes_at_link = ((1, 0), (2, 1), (3, 1))
>>> grid = NetworkModelGrid((y_of_node, x_of_node), nodes_at_link)
>>> grid.y_of_link
array([ 0.5,  1.5,  1.5])

class NodeStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Define the boundary-type codes

CLOSED = 4

Indicate a boundary node is closed

CORE = 0

Indicate a node is core.

FIXED_GRADIENT = 2

Indicate a boundary node is has a fixed gradient.

FIXED_VALUE = 1

Indicate a boundary node is has a fixed values.

LOOPED = 3

Indicate a boundary node is wrap-around.

exception ParameterValueError(key, val, expected_type)

Error to indicate a bad parameter values.

Raise this error if a parameter value given by key is not of the expected type.

class RadialModelGrid(n_rings=0, nodes_in_first_ring=6, spacing=1.0, xy_of_center=(0.0, 0.0), xy_of_reference=(0.0, 0.0), xy_axis_name=('x', 'y'), xy_axis_units='-')

Grid of concentric circles.

This inherited class implements a circular grid in which grid nodes are placed at regular radial and semi-regular arc-wise intervals. That is, if the radial spacing between shells is dr, the nodes are placed around the circular shell at regular intervals that get as close as possible to dr. The points are then arranged in a Delaunay triangulation with Voronoi cells. Within each ring, nodes are numbered according to Landlab convention, from the first node counterclockwise of east. Numbering begins at the centermost node and works outwards through the rings.

Create a circular grid.

Create a circular grid in which grid nodes are placed at regular radial and semi-regular arc-wise intervals. That is, if the radial spacing between shells is dr, the nodes are placed around the circular shell at regular intervals that get as close as possible to dr. The points are then arranged in a Delaunay triangulation with Voronoi cells.

Parameters:

• n_rings (int) – Number of rings in the grid.

• nodes_in_first_ring (int, optional) – Number of nodes in the first ring.

• spacing (float, optional) – Distance between rings.

• xy_of_center (tuple, optional) – (x, y) coordinate of center point. Default is (0., 0.)

• xy_of_reference (tuple, optional) – Coordinate value in projected space of the reference point, xy_of_lower_left. Default is (0., 0.)

Returns:

A newly-created grid.

Return type:

RadialModelGrid

Examples

A grid with just one ring will have a node at the origin surrounded by six other nodes by default. This can be changed by providing the keyword argument nodes_in_first_ring.

>>> import numpy as np
>>> from landlab import RadialModelGrid
>>> omg = RadialModelGrid(
...     n_rings=1, nodes_in_first_ring=8, xy_of_center=(0.0, 0.0)
... )
>>> omg.number_of_nodes
9
>>> omg.number_of_cells
1

A second rings will have 16 nodes (1 + 8 + 16 = 25).

>>> omg = RadialModelGrid(2, nodes_in_first_ring=8)
>>> omg.number_of_nodes
25

>>> np.round(omg.radius_at_node)
array([ 2.,  2.,  2.,  2.,  2.,  1.,  2.,  2.,  1.,  1.,  2.,  1.,  0.,
        1.,  2.,  1.,  1.,  2.,  2.,  1.,  2.,  2.,  2.,  2.,  2.])

__init__(n_rings=0, nodes_in_first_ring=6, spacing=1.0, xy_of_center=(0.0, 0.0), xy_of_reference=(0.0, 0.0), xy_axis_name=('x', 'y'), xy_axis_units='-')

Create a circular grid.

Create a circular grid in which grid nodes are placed at regular radial and semi-regular arc-wise intervals. That is, if the radial spacing between shells is dr, the nodes are placed around the circular shell at regular intervals that get as close as possible to dr. The points are then arranged in a Delaunay triangulation with Voronoi cells.

Parameters:

• n_rings (int) – Number of rings in the grid.

• nodes_in_first_ring (int, optional) – Number of nodes in the first ring.

• spacing (float, optional) – Distance between rings.

• xy_of_center (tuple, optional) – (x, y) coordinate of center point. Default is (0., 0.)

• xy_of_reference (tuple, optional) – Coordinate value in projected space of the reference point, xy_of_lower_left. Default is (0., 0.)

Returns:

A newly-created grid.

Return type:

RadialModelGrid

Examples

A grid with just one ring will have a node at the origin surrounded by six other nodes by default. This can be changed by providing the keyword argument nodes_in_first_ring.

>>> import numpy as np
>>> from landlab import RadialModelGrid
>>> omg = RadialModelGrid(
...     n_rings=1, nodes_in_first_ring=8, xy_of_center=(0.0, 0.0)
... )
>>> omg.number_of_nodes
9
>>> omg.number_of_cells
1

A second rings will have 16 nodes (1 + 8 + 16 = 25).

>>> omg = RadialModelGrid(2, nodes_in_first_ring=8)
>>> omg.number_of_nodes
25

>>> np.round(omg.radius_at_node)
array([ 2.,  2.,  2.,  2.,  2.,  1.,  2.,  2.,  1.,  1.,  2.,  1.,  0.,
        1.,  2.,  1.,  1.,  2.,  2.,  1.,  2.,  2.,  2.,  2.,  2.])

property active_adjacent_corners_at_corner

Adjacent corners for each grid corner.

See also

active_adjacent_nodes_at_node

property active_face_dirs_at_corner

Return face directions into each corner.

See also

active_link_dirs_at_node

property all_corner_azimuths_map

Get azimuths from every corner to every other corner.

See also

all_node_azimuths_map

property all_corner_distances_map

Get distances from every corner to every other corner.

See also

all_node_distances_map

property angle_of_face_about_head

Find and return the angle of a face about the corner at the face head.

See also

angle_of_link_about_head

as_dataset(include='*', exclude=None, time=None)

Create an xarray Dataset representation of a grid.

This method creates a new xarray Dataset object that contains the grid’s data fields. A particular grid type (e.g. a RasterModelGrid) should define its own as_dataset method to represent that particular grid type as a Dataset and then call this method to add the data fields.

Parameters:

• include (str or iterable or str) – Glob-style patterns of fields to include in the dataset.

• exclude (str or iterable or str) – Glob-style patterns of fields to exclude from the dataset.

Returns:

An xarray Dataset representation of a ModelGrid.

Return type:

Dataset

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))

Add some fields to the grid. Notice that we have defined a field named “elevation” at both nodes and links.

>>> _ = grid.add_full("elevation", 3.0, at="node")
>>> _ = grid.add_full("elevation", 4.0, at="link")
>>> _ = grid.add_full("temperature", 5.0, at="node")

>>> ds = grid.as_dataset()
>>> sorted(ds.dims.items())
[('dim', 2), ('link', 17), ('node', 12)]
>>> sorted([var for var in ds.data_vars if var.startswith("at_")])
['at_link:elevation', 'at_node:elevation', 'at_node:temperature']

>>> grid.event_layers.add(1.0, rho=0.5)

>>> ds = grid.as_dataset()
>>> sorted(ds.dims.items())
[('cell', 2), ('dim', 2), ('layer', 1), ('link', 17), ('node', 12)]
>>> sorted([var for var in ds.data_vars if var.startswith("at_")])
['at_layer_cell:rho', 'at_layer_cell:thickness', 'at_link:elevation',
 'at_node:elevation', 'at_node:temperature']

property boundary_corners

Get array of boundary corners.

See also

boundary_nodes

property cells_present_at_corner

A boolean array, False where a cell has a closed corner or is

See also

patches_present_at_node

property cells_present_at_face

A boolean array, False where a cell has a closed corner or is

See also

patches_present_at_link

property closed_boundary_corners

Get array of closed boundary corners.

See also

closed_boundary_nodes

property core_corners

Get array of core corners.

See also

core_nodes

property core_patches

Get array of core patches.

See also

core_cells

property corner_at_core_patch

Get array of corners associated with core patches.

See also

node_at_core_cell

property face_status_at_corner

property fixed_faces

Get array of fixed faces.

See also

fixed_links

property fixed_gradient_boundary_corner_anchor_corner

Returns the corner at the other end of the fixed face for a fixed

See also

fixed_gradient_boundary_node_anchor_node

property fixed_gradient_boundary_corner_fixed_face

An array of the fixed_faces connected to fixed gradient boundary

See also

fixed_gradient_boundary_node_fixed_link

property fixed_gradient_boundary_corners

Get array of fixed gradient boundary corners.

See also

fixed_gradient_boundary_nodes

property fixed_value_boundary_corners

Get array of fixed value boundary corners.

See also

fixed_value_boundary_nodes

classmethod from_dataset(dataset)

classmethod from_dict(kwds)

Create grid from dictionary.

Parameters:

params (dictionary) – Dictionary of required parameters to create a model grid.

Examples

>>> from landlab import RasterModelGrid
>>> params = {"shape": (3, 4), "xy_spacing": 2}
>>> grid = RasterModelGrid.from_dict(params)
>>> grid.x_of_node
array([ 0.,  2.,  4.,  6.,  0.,  2.,  4.,  6.,  0.,  2.,  4.,  6.])
>>> grid.y_of_node
array([ 0.,  0.,  0.,  0.,  2.,  2.,  2.,  2.,  4.,  4.,  4.,  4.])

property number_of_cells_present_at_corner

Return the number of cells at a corner without a closed corner.

See also

number_of_patches_present_at_node

property number_of_cells_present_at_face

Return the number of cells at a face without a closed corner.

See also

number_of_patches_present_at_link

property number_of_core_corners

Number of core corners.

See also

number_of_core_nodes

property number_of_core_patches

Number of core patches.

See also

number_of_core_cells

property number_of_fixed_faces

Number of fixed faces.

See also

number_of_fixed_links

property open_boundary_corners

Get array of open boundary corners.

See also

open_boundary_nodes

property patch_area_at_corner

Cell areas in a ncorners-long array.

See also

cell_area_at_node

property status_at_corner

Get array of the boundary status for each corner.

See also

status_at_node

property status_at_face

Get array of the status of all faces.

See also

status_at_link

property unit_vector_sum_xcomponent_at_corner

Get array of x-component of unit vector sums at each corner.

See also

unit_vector_sum_xcomponent_at_node

property unit_vector_sum_ycomponent_at_corner

Get array of y-component of unit vector sums at each corner.

See also

unit_vector_sum_ycomponent_at_node

property xy_of_center

Return (x, y) of the reference point.

class RasterModelGrid(shape, xy_spacing=1.0, xy_of_lower_left=(0.0, 0.0), xy_of_reference=(0.0, 0.0), xy_axis_name=('x', 'y'), xy_axis_units='-', bc=None)

A 2D uniform rectilinear grid.

Examples

Create a uniform rectilinear grid that has 4 rows and 5 columns of nodes. Nodes along the edges will be open. That is, links connecting these nodes to core nodes are active.

>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 5))
>>> rmg.number_of_node_rows, rmg.number_of_node_columns
(4, 5)
>>> rmg.number_of_active_links
17

Set the nodes along the top edge of the grid to be closed boundaries. This means that any links touching these nodes will be inactive.

>>> rmg = RasterModelGrid((4, 5), bc={"top": "closed"})
>>> rmg.number_of_node_rows, rmg.number_of_node_columns
(4, 5)
>>> rmg.number_of_active_links
14

A RasterModelGrid can have different node spacings in the x and y directions.

>>> grid = RasterModelGrid((4, 5), xy_spacing=(2, 1))
>>> grid.dx, grid.dy
(2.0, 1.0)
>>> grid.node_y.reshape(grid.shape)
array([[ 0.,  0.,  0.,  0.,  0.],
       [ 1.,  1.,  1.,  1.,  1.],
       [ 2.,  2.,  2.,  2.,  2.],
       [ 3.,  3.,  3.,  3.,  3.]])
>>> grid.node_x.reshape(grid.shape)
array([[ 0.,  2.,  4.,  6.,  8.],
       [ 0.,  2.,  4.,  6.,  8.],
       [ 0.,  2.,  4.,  6.,  8.],
       [ 0.,  2.,  4.,  6.,  8.]])

Create a 2D grid with equal spacing.

Optionally takes numbers of rows and columns and cell size as inputs. If this are given, calls initialize() to set up the grid. At the moment, num_rows and num_cols MUST be specified. Both must be >=3 to allow correct automated setup of boundary conditions.

Parameters:

• shape (tuple of int) – Shape of the grid in nodes as (nrows, ncols).

• xy_spacing (tuple or float, optional) – dx and dy spacing. Either provided as a float or a (dx, dy) tuple.

• xy_of_lower_left (tuple, optional) – (x, y) coordinates of the lower left corner.

• xy_of_reference (tuple, optional) – Coordinate value in projected space of the reference point, xy_of_lower_left. Default is (0., 0.)

• xy_axis_name (tuple of str) – Name to use for each axis.

• xy_axis_units (tuple of str, or str) – Units for coordinates of each axis.

• bc (dict, optional) – Edge boundary conditions.

Returns:

A newly-created grid.

Return type:

RasterModelGrid

Notes

The option for NOT giving rows, cols, and dx no longer works, because the field init requires num_active_cells, etc., to be defined. Either we force users to give arguments on instantiation, or set it up such that one can create a zero-node grid.

__getstate__()

Get state for pickling.

__init__(shape, xy_spacing=1.0, xy_of_lower_left=(0.0, 0.0), xy_of_reference=(0.0, 0.0), xy_axis_name=('x', 'y'), xy_axis_units='-', bc=None)

Create a 2D grid with equal spacing.

Optionally takes numbers of rows and columns and cell size as inputs. If this are given, calls initialize() to set up the grid. At the moment, num_rows and num_cols MUST be specified. Both must be >=3 to allow correct automated setup of boundary conditions.

Parameters:

• shape (tuple of int) – Shape of the grid in nodes as (nrows, ncols).

• xy_spacing (tuple or float, optional) – dx and dy spacing. Either provided as a float or a (dx, dy) tuple.

• xy_of_lower_left (tuple, optional) – (x, y) coordinates of the lower left corner.

• xy_of_reference (tuple, optional) – Coordinate value in projected space of the reference point, xy_of_lower_left. Default is (0., 0.)

• xy_axis_name (tuple of str) – Name to use for each axis.

• xy_axis_units (tuple of str, or str) – Units for coordinates of each axis.

• bc (dict, optional) – Edge boundary conditions.

Returns:

A newly-created grid.

Return type:

RasterModelGrid

Notes

The option for NOT giving rows, cols, and dx no longer works, because the field init requires num_active_cells, etc., to be defined. Either we force users to give arguments on instantiation, or set it up such that one can create a zero-node grid.

__setstate__(state_dict)

Set state for of RasterModelGrid from pickled state_dict.

property active_adjacent_corners_at_corner

Adjacent corners for each grid corner.

See also

active_adjacent_nodes_at_node

property active_d8_dirs_at_corner

property active_diagonal_dirs_at_corner

property active_face_dirs_at_corner

Return face directions into each corner.

See also

active_link_dirs_at_node

property all_corner_azimuths_map

Get azimuths from every corner to every other corner.

See also

all_node_azimuths_map

property all_corner_distances_map

Get distances from every corner to every other corner.

See also

all_node_distances_map

property angle_of_face_about_head

Find and return the angle of a face about the corner at the face head.

See also

angle_of_link_about_head

as_dataset(include='*', exclude=None, time=None)

Create an xarray Dataset representation of a grid.

This method creates a new xarray Dataset object that contains the grid’s data fields. A particular grid type (e.g. a RasterModelGrid) should define its own as_dataset method to represent that particular grid type as a Dataset and then call this method to add the data fields.

Parameters:

• include (str or iterable or str) – Glob-style patterns of fields to include in the dataset.

• exclude (str or iterable or str) – Glob-style patterns of fields to exclude from the dataset.

Returns:

An xarray Dataset representation of a ModelGrid.

Return type:

Dataset

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))

Add some fields to the grid. Notice that we have defined a field named “elevation” at both nodes and links.

>>> _ = grid.add_full("elevation", 3.0, at="node")
>>> _ = grid.add_full("elevation", 4.0, at="link")
>>> _ = grid.add_full("temperature", 5.0, at="node")

>>> ds = grid.as_dataset()
>>> sorted(ds.dims.items())
[('dim', 2), ('link', 17), ('node', 12)]
>>> sorted([var for var in ds.data_vars if var.startswith("at_")])
['at_link:elevation', 'at_node:elevation', 'at_node:temperature']

>>> grid.event_layers.add(1.0, rho=0.5)

>>> ds = grid.as_dataset()
>>> sorted(ds.dims.items())
[('cell', 2), ('dim', 2), ('layer', 1), ('link', 17), ('node', 12)]
>>> sorted([var for var in ds.data_vars if var.startswith("at_")])
['at_layer_cell:rho', 'at_layer_cell:thickness', 'at_link:elevation',
 'at_node:elevation', 'at_node:temperature']

property boundary_corners

Get array of boundary corners.

See also

boundary_nodes

calc_aspect_at_cell_subtriangles(elevs='topographic__elevation', subtriangle_unit_normals=None, unit='degrees')

Get tuple of arrays of aspect of each of the eight cell subtriangles.

Aspect is returned as radians clockwise of north, unless input parameter units is set to ‘degrees’.

If subtriangle_unit_normals is provided the aspect will be calculated from these data.

If it is not, it will be derived from elevation data at the nodes, which can either be a string referring to a grid field (default: ‘topographic__elevation’), or an nnodes-long numpy array of the values themselves.

Parameters:

• elevs (str or array (optional)) – Node field name or node array of elevations. If subtriangle_unit_normals is not provided, must be set, but unused otherwise.

• subtriangle_unit_normals (tuple of 8 (ncels, 3) arrays (optional)) – The unit normal vectors for the eight subtriangles of each cell, if already known. Order is from north of east, counter clockwise to south of east (East North East, North North East, North North West, West North West, West South West, South South West, South South East, East South East).

• unit ({'degrees', 'radians'}) – Controls the unit that the aspect is returned as.

Returns:

each a length num-cells array Len-8 tuple of the aspect of each of the eight cell subtriangles. Aspect is returned as angle clockwise of north. Units are given as radians unless input parameter units is set to ‘degrees’. Order is from north of east, counter clockwise to south of east (East North East, North North East, North North West, West North West, West South West, South South West, South South East, East South East).

Return type:

(a_ENE, a_NNE, a_NNW, a_WNW, a_WSW, a_SSW, a_SSE, a_ESE)

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((3, 3))
>>> z = np.array([1.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0])
>>> eight_tris = mg.calc_unit_normals_at_cell_subtriangles(z)
>>> A = mg.calc_aspect_at_cell_subtriangles(z, eight_tris)
>>> A0 = mg.calc_aspect_at_cell_subtriangles(z)
>>> np.allclose(A, A0)
True
>>> type(A) is tuple
True
>>> len(A)
8
>>> len(A[0]) == mg.number_of_cells
True
>>> A0
(array([ 180.]), array([ 270.]), array([ 90.]), array([ 180.]),
 array([ 0.]), array([ 90.]), array([ 270.]), array([ 0.]))

calc_diff_at_d8(node_values, out=None)

Calculate differences of node values over links and diagonals.

Calculates the difference in quantity node_values at each link in the grid.

Parameters:

• node_values (ndarray or field name) – Values at grid nodes.

• out (ndarray, optional) – Buffer to hold the result.

Returns:

Differences across links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4), xy_spacing=(4, 3))
>>> z = [
...     [60.0, 60.0, 60.0, 60.0],
...     [60.0, 60.0, 0.0, 0.0],
...     [60.0, 0.0, 0.0, 0.0],
... ]
>>> grid.calc_diff_at_d8(z)
array([  0.,   0.,   0.,   0.,   0., -60., -60.,   0., -60.,   0.,   0.,
       -60.,   0.,   0., -60.,   0.,   0.,   0.,   0., -60.,   0., -60.,
       -60., -60.,   0., -60.,   0.,   0.,   0.])

calc_diff_at_diagonal(node_values, out=None)

Calculate differences of node values over diagonals.

Calculates the difference in quantity node_values at each link in the grid.

Parameters:

• node_values (ndarray or field name) – Values at grid nodes.

• out (ndarray, optional) – Buffer to hold the result.

Returns:

Differences across links.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4), xy_spacing=(4, 3))
>>> z = [
...     [5.0, 5.0, 5.0, 5.0],
...     [5.0, 5.0, 0.0, 0.0],
...     [5.0, 0.0, 0.0, 0.0],
... ]
>>> grid.calc_diff_at_diagonal(z)
array([ 0.,  0., -5.,  0., -5., -5., -5.,  0., -5.,  0.,  0.,  0.])

calc_diff_at_link(value_at_node, out=None)

Calculate differences in node_values at links.

Parameters:

• value_at_node (array_like or field name) – Values at nodes.

• out (ndarray, optional) – Buffer to hold result. If None, create a new array.

Returns:

Differences of the nodes values for each link.

Return type:

ndarray

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 3))
>>> node_values = [
...     [0.0, 0.0, 0.0],
...     [1.0, 3.0, 1.0],
...     [2.0, 2.0, 2.0],
... ]
>>> grid.calc_diff_at_link(node_values)
array([ 0.,  0.,  1.,  3.,  1.,  2., -2.,  1., -1.,  1.,  0.,  0.])

>>> out = np.empty(grid.number_of_links, dtype=float)
>>> rtn = grid.calc_diff_at_link(node_values, out=out)
>>> rtn is out
True
>>> out
array([ 0.,  0.,  1.,  3.,  1.,  2., -2.,  1., -1.,  1.,  0.,  0.])

>>> grid = RasterModelGrid((3, 3), xy_spacing=(2, 1))
>>> grid.calc_diff_at_link(node_values)
array([ 0.,  0.,  1.,  3.,  1.,  2., -2.,  1., -1.,  1.,  0.,  0.])
>>> _ = grid.add_field("elevation", node_values, at="node")
>>> grid.calc_diff_at_link("elevation")
array([ 0.,  0.,  1.,  3.,  1.,  2., -2.,  1., -1.,  1.,  0.,  0.])

calc_grad_across_cell_corners(node_values, *args, **kwds)

grid.calc_grad_across_cell_corners(node_values, [cell_ids], out=None)

Get gradients to diagonally opposite nodes.

Calculate gradient of the value field provided by node_values to the values at diagonally opposite nodes. The returned gradients are ordered as upper-right, upper-left, lower-left and lower-right.

Parameters:

• node_values (array_like or field name) – Quantity to take the gradient of defined at each node.

• cell_ids (array_like, optional) – If provided, cell ids to measure gradients. Otherwise, find gradients for all cells.

• out (array_like, optional) – Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output.

Returns:

Gradients to each diagonal node.

Return type:

(N, 4) ndarray

Examples

Create a grid with two cells.

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> x = np.array([1.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 3.0, 3.0, 3.0, 3.0])

A decrease in quantity to a diagonal node is a negative gradient.

>>> from math import sqrt
>>> grid.calc_grad_across_cell_corners(x) * sqrt(2.0)
array([[ 3.,  3.,  1.,  0.],
       [ 2.,  2., -1.,  0.]])

>>> grid = RasterModelGrid((3, 4), xy_spacing=(4, 3))
>>> grid.calc_grad_across_cell_corners(x)
array([[ 0.6,  0.6,  0.2,  0. ],
       [ 0.4,  0.4, -0.2,  0. ]])

calc_grad_across_cell_faces(node_values, *args, **kwds)

grid.calc_grad_across_cell_faces(node_values, [cell_ids], out=None)

Get gradients across the faces of a cell.

Calculate gradient of the value field provided by node_values across each of the faces of the cells of a grid. The returned gradients are ordered as right, top, left, and bottom.

Note that the returned gradients are masked to exclude neighbor nodes which are closed. Beneath the mask is the value -1.

Parameters:

• node_values (array_like or field name) – Quantity to take the gradient of defined at each node.

• cell_ids (array_like, optional) – If provided, cell ids to measure gradients. Otherwise, find gradients for all cells.

• out (array_like, optional) – Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output.

Returns:

Gradients for each face of the cell.

Return type:

(N, 4) Masked ndarray

Examples

Create a grid with two cells.

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> x = np.array([0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 3.0, 3.0, 3.0, 3.0])

A decrease in quantity across a face is a negative gradient.

>>> grid.calc_grad_across_cell_faces(x)
masked_array(data =
 [[ 1.  3.  0.  0.]
 [ 0.  2. -1. -1.]],
             mask =
 False,
       fill_value = 1e+20)

>>> grid = RasterModelGrid((3, 4), xy_spacing=(1, 2))
>>> grid.calc_grad_across_cell_faces(x)
masked_array(data =
 [[ 1.   1.5  0.   0. ]
 [ 0.   1.  -1.  -0.5]],
              mask =
 False,
       fill_value = 1e+20)

calc_grad_along_node_links(node_values, *args, **kwds)

grid.calc_grad_along_node_links(node_values, [cell_ids], out=None)

Get gradients along links touching a node.

Calculate gradient of the value field provided by node_values across each of the faces of the nodes of a grid. The returned gradients are ordered as right, top, left, and bottom. All returned values follow our standard sign convention, where a link pointing N or E and increasing in value is positive, a link pointing S or W and increasing in value is negative.

Note that the returned gradients are masked to exclude neighbor nodes which are closed. Beneath the mask is the value -1.

Parameters:

• node_values (array_like or field name) – Quantity to take the gradient of defined at each node.

• node_ids (array_like, optional) – If provided, node ids to measure gradients. Otherwise, find gradients for all nodes.

• out (array_like, optional) – Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output.

Returns:

Gradients for each link of the node. Ordering is E,N,W,S.

Return type:

(N, 4) Masked ndarray

Examples

Create a grid with nine nodes.

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 3))
>>> x = np.array([0.0, 0.0, 0.0, 0.0, 1.0, 2.0, 2.0, 2.0, 2.0])

A decrease in quantity across a face is a negative gradient.

>>> grid.calc_grad_along_node_links(x)
masked_array(data =
 [[-- -- -- --]
 [-- 1.0 -- --]
 [-- -- -- --]
 [1.0 -- -- --]
 [1.0 1.0 1.0 1.0]
 [-- -- 1.0 --]
 [-- -- -- --]
 [-- -- -- 1.0]
 [-- -- -- --]],
             mask =
 [[ True  True  True  True]
 [ True False  True  True]
 [ True  True  True  True]
 [False  True  True  True]
 [False False False False]
 [ True  True False  True]
 [ True  True  True  True]
 [ True  True  True False]
 [ True  True  True  True]],
       fill_value = 1e+20)

>>> grid = RasterModelGrid((3, 3), xy_spacing=(4, 2))
>>> grid.calc_grad_along_node_links(x)
masked_array(data =
 [[-- -- -- --]
 [-- 0.5 -- --]
 [-- -- -- --]
 [0.25 -- -- --]
 [0.25 0.5 0.25 0.5]
 [-- -- 0.25 --]
 [-- -- -- --]
 [-- -- -- 0.5]
 [-- -- -- --]],
             mask =
 [[ True  True  True  True]
 [ True False  True  True]
 [ True  True  True  True]
 [False  True  True  True]
 [False False False False]
 [ True  True False  True]
 [ True  True  True  True]
 [ True  True  True False]
 [ True  True  True  True]],
       fill_value = 1e+20)

calc_grad_at_d8(node_values, out=None)

Calculate gradients over all diagonals and links.

Parameters:

• node_values (array_like or field name) – Values at nodes.

• out (ndarray, optional) – Buffer to hold result. If None, create a new array.

Examples

>>> from landlab import RasterModelGrid
>>> import numpy as np
>>> grid = RasterModelGrid((3, 4), xy_spacing=(4, 3))
>>> z = [
...     [60.0, 60.0, 60.0, 60.0],
...     [60.0, 60.0, 0.0, 0.0],
...     [60.0, 0.0, 0.0, 0.0],
... ]
>>> grid.calc_grad_at_d8(z)
array([  0.,   0.,   0.,   0.,   0., -20., -20.,   0., -15.,   0.,   0.,
       -20.,   0.,   0., -15.,   0.,   0.,   0.,   0., -12.,   0., -12.,
       -12., -12.,   0., -12.,   0.,   0.,   0.])

calc_grad_at_diagonal(node_values, out=None)

Calculate gradients over all diagonals.

Parameters:

• node_values (array_like or field name) – Values at nodes.

• out (ndarray, optional) – Buffer to hold result. If None, create a new array.

Examples

>>> from landlab import RasterModelGrid
>>> import numpy as np
>>> grid = RasterModelGrid((3, 4), xy_spacing=(4, 3))
>>> z = [
...     [5.0, 5.0, 5.0, 5.0],
...     [5.0, 5.0, 0.0, 0.0],
...     [5.0, 0.0, 0.0, 0.0],
... ]
>>> grid.calc_grad_at_diagonal(z)
array([ 0.,  0., -1.,  0., -1., -1., -1.,  0., -1.,  0.,  0.,  0.])

calc_grad_at_link(value_at_node, out=None)

Calculate gradients in node_values at links.

Parameters:

• value_at_node (array_like or field name) – Values at nodes.

• out (ndarray, optional) – Buffer to hold result. If None, create a new array.

Returns:

Gradients of the nodes values for each link.

Return type:

ndarray

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 3))
>>> node_values = [0.0, 0.0, 0.0, 1.0, 3.0, 1.0, 2.0, 2.0, 2.0]
>>> grid.calc_grad_at_link(node_values)
array([ 0.,  0.,  1.,  3.,  1.,  2., -2.,  1., -1.,  1.,  0.,  0.])

>>> out = np.empty(grid.number_of_links, dtype=float)
>>> rtn = grid.calc_grad_at_link(node_values, out=out)
>>> rtn is out
True
>>> out
array([ 0.,  0.,  1.,  3.,  1.,  2., -2.,  1., -1.,  1.,  0.,  0.])

>>> grid = RasterModelGrid((3, 3), xy_spacing=(2, 1))
>>> grid.calc_grad_at_link(node_values)
array([ 0.,  0.,  1.,  3.,  1.,  1., -1.,  1., -1.,  1.,  0.,  0.])
>>> _ = grid.add_field("elevation", node_values, at="node")
>>> grid.calc_grad_at_link("elevation")
array([ 0.,  0.,  1.,  3.,  1.,  1., -1.,  1., -1.,  1.,  0.,  0.])

calc_grad_at_patch(elevs='topographic__elevation', ignore_closed_nodes=True, subtriangle_unit_normals=None, slope_magnitude=None)

Calculate the components of the gradient of each raster patch.

Returns the mean gradient of the four possible patch subtriangles, in radians.

If ignore_closed_nodes is True, closed nodes do not affect gradient calculations. If more than one closed node is present in a patch, the patch gradients in both x and y directions are set to zero.

Parameters:

• elevs (str or ndarray, optional) – Field name or array of node values.

• ignore_closed_nodes (bool) – If True, do not incorporate values at closed nodes into the calc.

• subtriangle_unit_normals (tuple of 4 (npatches, 3) arrays (optional)) – The unit normal vectors for the four subtriangles of each patch, if already known. Order is TR, TL, BL, BR.

• slope_magnitude (array with size num_patches (optional)) – The mean slope of each patch, if already known. Units must be the same as provided here!

Returns:

gradient_tuple – Len-2 tuple of arrays giving components of gradient in the x and y directions, in the units of radians.

Return type:

(x_component_at_patch, y_component_at_patch)

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> z = mg.node_y
>>> (x_grad, y_grad) = mg.calc_grad_at_patch(elevs=z)
>>> np.allclose(y_grad, np.pi / 4.0)
True
>>> np.allclose(x_grad, 0.0)
True

>>> z = mg.node_x.copy()
>>> mg.set_closed_boundaries_at_grid_edges(True, True, True, True)
>>> mg.status_at_node[11] = mg.BC_NODE_IS_CLOSED
>>> mg.status_at_node[[9, 2]] = mg.BC_NODE_IS_FIXED_VALUE
>>> z[11] = 100.0  # this should get ignored now
>>> z[9] = 2.0  # this should be felt by patch 7 only
>>> z[2] = 1.0  # should be felt by patches 1 and 2
>>> xgrad, ygrad = mg.calc_grad_at_patch(elevs=z, ignore_closed_nodes=True)
>>> (xgrad.reshape((3, 4)) * 4.0 / np.pi)[1, 1:]
array([ 1.,  1., -1.])
>>> np.allclose(ygrad[1:3], xgrad[1:3])
True

calc_slope_at_cell_subtriangles(elevs='topographic__elevation', subtriangle_unit_normals=None)

Calculate the slope (positive magnitude of gradient) at each of the eight cell subtriangles.

Parameters:

• elevs (str or ndarray, optional) – Field name or array of node values.

• subtriangle_unit_normals (tuple of 8 (ncells, 3) arrays (optional)) – The unit normal vectors for the eight subtriangles of each cell, if already known. Order is from north of east, counter clockwise to south of east (East North East, North North East, North North West, West North West, West South West, South South West, South South East, East South East).

Returns:

each a length num-cells array Len-8 tuple of the slopes (positive gradient magnitude) of each of the eight cell subtriangles, in radians. Order is from north of east, counter clockwise to south of east (East North East, North North East, North North West, West North West, West South West, South South West, South South East, East South East).

Return type:

(s_ENE, s_NNE, s_NNW, s_WNW, s_WSW, s_SSW, s_SSE, s_ESE)

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((3, 3))
>>> z = np.array(
...     [np.sqrt(3.0), 0.0, 4.0 / 3.0, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0 / np.sqrt(3.0)]
... )
>>> eight_tris = mg.calc_unit_normals_at_cell_subtriangles(z)
>>> S = mg.calc_slope_at_cell_subtriangles(z, eight_tris)
>>> S0 = mg.calc_slope_at_cell_subtriangles(z)
>>> np.allclose(S, S0)
True
>>> type(S) is tuple
True
>>> len(S)
8
>>> len(S[0]) == mg.number_of_cells
True
>>> np.allclose(S[0], S[1])
True
>>> np.allclose(S[2], S[3])
True
>>> np.allclose(S[4], S[5])
True
>>> np.allclose(S[6], S[7])
True
>>> np.allclose(np.rad2deg(S[0])[0], 30.0)
True
>>> np.allclose(np.rad2deg(S[2])[0], 45.0)
True
>>> np.allclose(np.rad2deg(S[4])[0], 60.0)
True
>>> np.allclose(np.cos(S[6])[0], 3.0 / 5.0)
True

calc_slope_at_node(elevs='topographic__elevation', method='patch_mean', ignore_closed_nodes=True, return_components=False)

Array of slopes at nodes, averaged over neighboring patches.

Produces a value for node slope (i.e., mean gradient magnitude) at each node in a manner analogous to a GIS-style slope map. If method==’patch_mean’, it averages the gradient on each of the patches surrounding the node; if method==’Horn’, it returns the resolved slope direction. Directional information can still be returned through use of the return_components keyword. All values are returned in radians, including the components; take the tan to recover the rise/run.

Note that under these definitions, it is not always true that:

mag, cmp = mg.calc_slope_at_node(z)
mag**2 == cmp[0]**2 + cmp[1]**2  # only if method=='Horn'

If ignore_closed_nodes is False, all proximal elevation values will be used in the calculation. If True, only unclosed nodes are used.

This is a verion of this code specialized for a raster. It subdivides the four square patches around each node into subtriangles, in order to ensure more correct solutions that incorporate equally weighted information from all surrounding nodes on rough surfaces.

Parameters:

• elevs (str or ndarray, optional) – Field name or array of node values.

• method ({'patch_mean', 'Horn'}) – Controls the slope algorithm. Current options are ‘patch_mean’, which takes the mean slope of each pf the four neighboring square patches, and ‘Horn’, which is the standard ArcGIS slope algorithm. These produce very similar solutions; the Horn method gives a vector mean and the patch_mean gives a scalar mean.

• ignore_closed_nodes (bool) – If True, do not incorporate values at closed nodes into the calc.

• return_components (bool) – If True, return a tuple, (array_of_magnitude, (array_of_slope_x_radians, array_of_slope_y_radians)). If false, return an array of floats of the slope magnitude.

Returns:

If return_components, returns (array_of_magnitude, (array_of_slope_x_radians, array_of_slope_y_radians)). If not return_components, returns an array of slope magnitudes.

Return type:

float array or length-2 tuple of float arrays

Examples

>>> import numpy as np
>>> from landlab import RadialModelGrid, RasterModelGrid
>>> mg = RasterModelGrid((5, 5))
>>> z = mg.node_x
>>> slopes = mg.calc_slope_at_node(elevs=z)
>>> np.allclose(slopes, np.pi / 4.0)
True
>>> mg = RasterModelGrid((4, 5), xy_spacing=2.0)
>>> z = -mg.node_y
>>> slope_mag, cmp = mg.calc_slope_at_node(elevs=z, return_components=True)
>>> np.allclose(slope_mag, np.pi / 4.0)
True
>>> np.allclose(cmp[0], 0.0)
True
>>> np.allclose(cmp[1], -np.pi / 4.0)
True
>>> mg = RasterModelGrid((4, 4))
>>> z = mg.node_x**2 + mg.node_y**2
>>> slopes, cmp = mg.calc_slope_at_node(z, return_components=True)
>>> slopes
array([ 0.95531662,  1.10991779,  1.32082849,  1.37713803,  1.10991779,
        1.20591837,  1.3454815 ,  1.38904403,  1.32082849,  1.3454815 ,
        1.39288142,  1.41562833,  1.37713803,  1.38904403,  1.41562833,
        1.43030663])

Check radial symmetry.

>>> np.allclose(cmp[0].reshape((4, 4))[:, 0], cmp[1].reshape((4, 4))[0, :])
True

calc_slope_at_patch(elevs='topographic__elevation', ignore_closed_nodes=True, subtriangle_unit_normals=None)

Calculate the slope (positive magnitude of gradient) at raster patches.

Returns the mean of the slopes of the four possible patch subtriangles.

If ignore_closed_nodes is True, closed nodes do not affect slope calculations. If more than one closed node is present in a patch, the patch slope is set to zero.

Parameters:

• elevs (str or ndarray, optional) – Field name or array of node values.

• ignore_closed_nodes (bool) – If True, do not incorporate values at closed nodes into the calc.

• subtriangle_unit_normals (tuple of 4 (npatches, 3) arrays (optional)) – The unit normal vectors for the four subtriangles of each patch, if already known. Order is TR, TL, BL, BR.

Returns:

slopes_at_patch – The slope (positive gradient magnitude) of each patch, in radians.

Return type:

n_patches-long array

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> z = mg.node_x
>>> S = mg.calc_slope_at_patch(elevs=z)
>>> S.size == mg.number_of_patches
True
>>> np.allclose(S, np.pi / 4.0)
True
>>> z = mg.node_y**2
>>> mg.calc_slope_at_patch(elevs=z).reshape((3, 4))
array([[ 0.78539816,  0.78539816,  0.78539816,  0.78539816],
       [ 1.24904577,  1.24904577,  1.24904577,  1.24904577],
       [ 1.37340077,  1.37340077,  1.37340077,  1.37340077]])

>>> z = mg.node_x.copy()
>>> mg.set_closed_boundaries_at_grid_edges(True, True, True, True)
>>> mg.status_at_node[11] = mg.BC_NODE_IS_CLOSED
>>> mg.status_at_node[9] = mg.BC_NODE_IS_FIXED_VALUE
>>> z[11] = 100.0  # this should get ignored now
>>> z[9] = 2.0  # this should be felt by patch 7 only
>>> mg.calc_slope_at_patch(elevs=z, ignore_closed_nodes=True).reshape(
...     (3, 4)
... ) * 4.0 / np.pi
array([[ 0.,  0.,  0.,  0.],
       [ 0.,  1.,  1.,  1.],
       [ 0.,  0.,  0.,  0.]])

calc_unit_normal_at_patch(elevs='topographic__elevation')

Calculate and return the unit normal vector <a, b, c> to a patch.

This method is not defined on a raster, as there is no unique unit normal for a square patch. Use _calc_unit_normals_to_patch_subtriangles instead.

calc_unit_normals_at_cell_subtriangles(elevs='topographic__elevation')

Calculate unit normals on a cell.

Calculate the eight unit normal vectors <a, b, c> to the eight subtriangles of a four-cornered (raster) cell.

Parameters:

elevs (str or ndarray, optional) – Field name or array of node values.

Returns:

each a num-cells x length-3 array Len-8 tuple of the eight unit normal vectors <a, b, c> for the eight subtriangles in the cell. Order is from north of east, counter clockwise to south of east (East North East, North North East, North North West, West North West, West South West, South South West, South South East, East South East).

Return type:

(n_ENE, n_NNE, n_NNW, n_WNW, n_WSW, n_SSW, n_SSE, n_ESE)

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((3, 3))
>>> z = mg.node_x**2
>>> eight_tris = mg.calc_unit_normals_at_cell_subtriangles(z)
>>> type(eight_tris) is tuple
True
>>> len(eight_tris)
8
>>> eight_tris[0].shape == (mg.number_of_cells, 3)
True
>>> eight_tris
(array([[-0.9486833 ,  0.        ,  0.31622777]]),
 array([[-0.9486833 ,  0.        ,  0.31622777]]),
 array([[-0.70710678,  0.        ,  0.70710678]]),
 array([[-0.70710678,  0.        ,  0.70710678]]),
 array([[-0.70710678,  0.        ,  0.70710678]]),
 array([[-0.70710678,  0.        ,  0.70710678]]),
 array([[-0.9486833 ,  0.        ,  0.31622777]]),
 array([[-0.9486833 ,  0.        ,  0.31622777]]))

calc_unit_normals_at_patch_subtriangles(elevs='topographic__elevation')

Calculate unit normals on a patch.

Calculate the four unit normal vectors <a, b, c> to the four possible subtriangles of a four-cornered (raster) patch.

Parameters:

elevs (str or ndarray, optional) – Field name or array of node values.

Returns:

(n_TR, n_TL, n_BL, n_BR) – Len-4 tuple of the four unit normal vectors <a, b, c> for the four possible subtriangles in the patch. Order is (topright, topleft, bottomleft, bottomright).

Return type:

each a num-patches x length-3 array

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> z = mg.node_x**2
>>> four_tris = mg.calc_unit_normals_at_patch_subtriangles(z)
>>> type(four_tris) is tuple
True
>>> len(four_tris)
4
>>> np.allclose(four_tris[0], four_tris[1])
True
>>> np.allclose(four_tris[2], four_tris[3])
True
>>> np.allclose(four_tris[0], four_tris[2])
True
>>> np.allclose(np.square(four_tris[0]).sum(axis=1), 1.0)
True
>>> four_tris[0]
array([[-0.70710678,  0.        ,  0.70710678],
       [-0.9486833 ,  0.        ,  0.31622777],
       [-0.98058068,  0.        ,  0.19611614],
       [-0.98994949,  0.        ,  0.14142136],
       [-0.70710678,  0.        ,  0.70710678],
       [-0.9486833 ,  0.        ,  0.31622777],
       [-0.98058068,  0.        ,  0.19611614],
       [-0.98994949,  0.        ,  0.14142136],
       [-0.70710678,  0.        ,  0.70710678],
       [-0.9486833 ,  0.        ,  0.31622777],
       [-0.98058068,  0.        ,  0.19611614],
       [-0.98994949,  0.        ,  0.14142136]])

calculate_slope_aspect_at_nodes_burrough(ids=None, vals='Elevation')

Calculate topographic slope.

Calculates the local topographic slope (i.e., the down-dip slope, and presented as positive), and the aspect (dip direction in degrees clockwise from north), at the given nodes, ids. All ids must be of core nodes. This method uses Burrough’s 1998 Pg. 190 method similar to the methods used by ArcMap to calculate slope and aspect.

If ids is not provided, the slope will be returned for nodes at all cells.

vals is either the name of an existing grid field from which to draw topographic data, or an array of values to use. If an array of values is passed, it must be nnodes long. If vals is not provided, this method will default to trying to use the field ‘Elevation’.

Returns:

(slope, aspect) – slope, a len(ids) array of slopes at each node provided. aspect, a len(ids) array of aspects at each node provided.

Return type:

tuple of float

Examples

>>> import pytest
>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4), xy_spacing=(4, 4))
>>> z = np.array([0.0, 0.0, 0.0, 0.0, 3.0, 3.0, 3.0, 3, 6.0, 6.0, 6.0, 6.0])
>>> slope, aspect = grid.calculate_slope_aspect_at_nodes_burrough(vals=z)
>>> np.tan(slope)
array([ 0.75,  0.75])
>>> np.degrees(aspect)
array([ 180.,  180.])

We recommend using the following functions instead of this one: - calc_slope_at_node - calc_aspect_at_node Notice that calc_slope_at_node and :py:meth:`~landlab.grid.RasterModelGrid.calc_aspect_at_node return values for all nodes, not just core nodes. In addition, :py:meth:`~landlab.grid.RasterModelGrid.calc_aspect_at_node returns compass-style angles in degrees.

>>> np.tan(grid.calc_slope_at_node(elevs=z)[grid.core_nodes])
array([ 0.75,  0.75])
>>> grid.calc_aspect_at_node(elevs=z)[grid.core_nodes]
array([ 180.,  180.])

property cell_grid_shape

Get the shape of the cellular grid (grid with only cells).

Returns:

shape – The shape of the cellular grid as number of cell rows and cell columns.

Return type:

tuple of ints

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> grid.cell_grid_shape
(1, 2)

cell_vector_to_raster(u, flip_vertically=False)

Unravel a 1D array.

Converts cell vector u to a 2D array and returns it, so that it can be plotted, output, etc.

If the optional argument flip_vertically=True, the function returns an array that has the rows in reverse order, for use in plot commands (such as the image display functions) that put the (0,0) axis at the top left instead of the bottom left.

Examples

>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 5))
>>> u = rmg.zeros(centering="cell")
>>> u = u + range(0, len(u))
>>> u
array([ 0.,  1.,  2.,  3.,  4.,  5.])
>>> ur = rmg.cell_vector_to_raster(u)
>>> ur
array([[ 0.,  1.,  2.],
       [ 3.,  4.,  5.]])
>>> ur = rmg.cell_vector_to_raster(u, flip_vertically=True)
>>> ur
array([[ 3.,  4.,  5.],
       [ 0.,  1.,  2.]])

property cells_at_corners_of_grid

Get array of cells in cellular grid (grid with only cells) corners.

Return the IDs to the corner cells of the cellular grid, sorted by ID.

Returns:

Array of corner node IDs.

Return type:

(4, ) ndarray

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.cells_at_corners_of_grid
array([0, 2, 3, 5])

property cells_present_at_corner

A boolean array, False where a cell has a closed corner or is

See also

patches_present_at_node

property cells_present_at_face

A boolean array, False where a cell has a closed corner or is

See also

patches_present_at_link

property closed_boundary_corners

Get array of closed boundary corners.

See also

closed_boundary_nodes

property core_corners

Get array of core corners.

See also

core_nodes

property core_patches

Get array of core patches.

See also

core_cells

property corner_at_core_patch

Get array of corners associated with core patches.

See also

node_at_core_cell

property corners_at_d8

property corners_at_diagonal

Nodes at diagonal tail and head.

See also

nodes_at_diagonal

property d8_adjacent_corners_at_corner

property d8_dirs_at_corner

property d8_status_at_corner

property d8s_at_corner

Links and diagonals attached to corners.

See also

d8s_at_node

property diagonal_adjacent_corners_at_corner

Get adjacent corners along diagonals.

See also

diagonal_adjacent_nodes_at_node

property diagonal_dirs_at_corner

Directions of diagonals attached to corners.

See also

diagonal_dirs_at_node

property diagonal_status_at_corner

property diagonals_at_corner

Diagonals attached to corners.

See also

diagonals_at_node

property extent

Extent of the grid in the y and x-dimensions.

Return the y and x-dimension of the grid. Because boundary nodes don’t have cells, the dimension of the grid is ((num_rows - 1) * dy, (num_columns - 1) * dx), not (num_rows * dy, num_cols * dx).

Returns:

(y_extent, x_extent) – Length of the grid in the y and x-dimensions.

Return type:

tuple of float

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.extent
(3.0, 4.0)

>>> grid = RasterModelGrid((4, 5), xy_spacing=2.0)
>>> grid.extent
(6.0, 8.0)

>>> grid = RasterModelGrid((4, 5), xy_spacing=(3, 2))
>>> grid.extent
(6.0, 12.0)

property face_status_at_corner

find_nearest_node(coords, mode='raise')

Node nearest a point.

Find the index to the node nearest the given x, y coordinates. Coordinates are provided as numpy arrays in the coords tuple.

Use the mode keyword to specify what to do if the given coordinates are out-of-bounds. See np.ravel_multi_index for a description of possible values for mode. Note that a coordinate is out-of-bounds if it is beyond one half the node spacing from the exterior nodes.

Returns the indices of the nodes nearest the given coordinates.

Parameters:

• coords (tuple of array-like) – Coordinates of points.

• mode ({'raise', 'wrap', 'clip'}, optional) – What to do if a point is off the grid.

Returns:

IDs of the nearest nodes.

Return type:

array-like

Notes

For coordinates that are equidistant to two or more nodes, see the rounding rules for numpy.around.

Examples

>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 5))
>>> rmg.find_nearest_node([0.2, 0.2])
0
>>> rmg.find_nearest_node((np.array([1.6, 3.6]), np.array([2.3, 0.7])))
array([12,  9])
>>> rmg.find_nearest_node((-0.4999, 1.0))
5

property fixed_faces

Get array of fixed faces.

See also

fixed_links

property fixed_gradient_boundary_corner_anchor_corner

Returns the corner at the other end of the fixed face for a fixed

See also

fixed_gradient_boundary_node_anchor_node

property fixed_gradient_boundary_corner_fixed_face

An array of the fixed_faces connected to fixed gradient boundary

See also

fixed_gradient_boundary_node_fixed_link

property fixed_gradient_boundary_corners

Get array of fixed gradient boundary corners.

See also

fixed_gradient_boundary_nodes

property fixed_value_boundary_corners

Get array of fixed value boundary corners.

See also

fixed_value_boundary_nodes

classmethod from_dataset(dataset)

classmethod from_dict(params)

Create a RasterModelGrid from a dictionary.

Parameters:

params (dict_like) – Initialization parameters for a RasterModelGrid.

Returns:

A newly-created grid.

Return type:

RasterModelGrid

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid.from_dict({"shape": (3, 4), "bc": {"top": "closed"}})
>>> grid.number_of_nodes
12

grid_coords_to_node_id(row, col, **kwds)

Convert node indices to node ID.

Returns the ID of the node at the specified row and col of the raster grid. Since this is a wrapper for the numpy ravel_multi_index function, the keyword arguments are the same as that function. In addition, row and col can both be either scalars or arrays (of the same length) to get multiple ids.

As with ravel_multi_index use the mode keyword to change the behavior of the method when passed an out-of-range row or col. The default is to raise ValueError (not IndexError, as you might expect).

Note

The syntax assumes that first row and column are 0, so max entry for a mg with 4 rows and 5 cols is row=3, col=4

Parameters:

• row (array-like) – Row of node.

• col (array-like) – Column of node.

Returns:

Node IDs.

Return type:

ndarray

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((4, 5))
>>> mg.grid_coords_to_node_id(2, 3)
13

>>> mg.grid_coords_to_node_id([2, 0], [3, 4])
array([13,  4])

is_point_on_grid(xcoord, ycoord)

Check if a point is on the grid.

This method takes x, y coordinates and tests whether they lie within the grid. The limits of the grid are taken to be links connecting the boundary nodes. We perform a special test to detect looped boundaries.

Coordinates can be ints or arrays of ints. If arrays, will return an array of the same length of boolean truth values.

Parameters:

• xcoord (float or array_like) – The point’s x-coordinate.

• ycoord (float or array_like) – The point’s y-coordinate.

Returns:

True if the point is on the grid. Otherwise, False.

Return type:

bool

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5), xy_spacing=(1, 2))
>>> grid.is_point_on_grid(1, 1)
True
>>> grid.is_point_on_grid(
...     (1, 1, 1),
...     (1, 3.1, 6.1),
... )
array([ True,  True, False], dtype=bool)
>>> grid.is_point_on_grid((-0.1, 0.1, 3.9, 4.1), (1, 1, 1, 1))
array([False,  True,  True, False], dtype=bool)

property looped_neighbors_at_cell

For each cell in a raster, return the D8 neighboring cells, looping across grid boundaries as necessary.

Returns lists of looped neighbor cell IDs of given cell ids. If cell ids are not given, it returns a 2D array of size (self.number_of_cells, 8). Order or neighbors is [ E, NE, N, NW, W, SW, S, SE ]

Output is looped, regardless of boundary conditions! (see examples)

Returns:

The eight neighbors of each cell.

Return type:

ndarray (num_cells, 8)

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> neighbors = grid.looped_neighbors_at_cell
>>> neighbors[1, :]
array([2, 5, 4, 3, 0, 3, 4, 5])
>>> neighbors[5, :]
array([3, 0, 2, 1, 4, 1, 2, 0])
>>> grid.looped_neighbors_at_cell[np.array([1, 5]), :]
array([[2, 5, 4, 3, 0, 3, 4, 5],
       [3, 0, 2, 1, 4, 1, 2, 0]])

property looped_neighbors_at_patch

For each patch in a raster, return the D8 neighboring patches, looping

See also

looped_neighbors_at_cell

map_link_vector_components_to_node_raster(data_at_link)

Map (x,y) vector components of data_at_link onto nodes.

Examples

>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((3, 4))
>>> link_data = np.arange(rmg.number_of_links)
>>> x, y = map_link_vector_components_to_node_raster(rmg, link_data)
>>> x[5:7]
array([ 7.5,  8.5])
>>> y[5:7]
array([ 7.5,  8.5])

map_max_of_inlinks_to_node(var_name, out=None)

Map the maximum of links entering a node to the node.

map_max_of_inlinks_to_node takes an array at the links and finds the inlink values for each node in the grid. it finds the maximum value at the the inlinks and returns values at the nodes.

Note

This considers all inactive links to have a value of 0.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import map_max_of_inlinks_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", np.arange(17.0), at="link")
>>> map_max_of_inlinks_to_node(rmg, "z")
array([  0.,   0.,   1.,   2.,
         3.,   7.,   8.,   9.,
        10.,  14.,  15.,  16.])

map_max_of_outlinks_to_node(var_name, out=None)

Map the max of links leaving a node to the node.

map_max_of_outlinks_to_node takes an array at the links and finds the outlink values for each node in the grid. it finds the maximum value at the the outlinks and returns values at the nodes.

Note

This considers all inactive links to have a value of 0.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import map_max_of_outlinks_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", np.arange(17.0), at="link")
>>> map_max_of_outlinks_to_node(rmg, "z")
array([  3.,   4.,   5.,   6.,  10.,  11.,  12.,  13.,  14.,  15.,  16.,
         0.])

map_mean_of_horizontal_active_links_to_node(var_name, out=None)

Map the mean of active links in the x direction touching node to the node.

map_mean_of_horizontal_active_links_to_node takes an array at the links and finds the average of all horizontal (x-direction) link neighbor values for each node in the grid. It returns an array at the nodes of the mean of these values. If a link is absent, it is ignored. If a node has no active links, it receives 0. Note that here a positive returned value means flux to the east, and a negative to the west.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import (
...     map_mean_of_horizontal_active_links_to_node,
... )
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", -np.arange(17, dtype=float), at="link")
>>> rmg.status_at_node[rmg.nodes_at_left_edge] = rmg.BC_NODE_IS_CLOSED
>>> map_mean_of_horizontal_active_links_to_node(rmg, "z")
array([ 0. ,  0. ,  0. ,  0. ,  0. , -8. , -8.5, -9. ,  0. ,  0. ,  0. ,
        0. ])

map_mean_of_horizontal_links_to_node(var_name, out=None)

Map the mean of links in the x direction touching a node to the node.

map_mean_of_horizontal_links_to_node takes an array at the links and finds the average of all horizontal (x-direction) link neighbor values for each node in the grid. It returns an array at the nodes of the mean of these values. If a link is absent, it is ignored. Note that here a positive returned value means flux to the east, and a negative to the west.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import map_mean_of_horizontal_links_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", np.arange(17.0), at="link")
>>> map_mean_of_horizontal_links_to_node(rmg, "z")
array([  0. ,   0.5,   1.5,   2. ,   7. ,   7.5,   8.5,   9. ,  14. ,
        14.5,  15.5,  16. ])

map_mean_of_inlinks_to_node(var_name, out=None)

Map the mean of links entering a node to the node.

map_mean_of_inlinks_to_node takes an array at the links and finds the inlink values for each node in the grid. It finds the average of the inlinks and returns values at the nodes.

This considers all inactive links to have a value of 0.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import map_mean_of_inlinks_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", np.arange(17.0), at="link")
>>> map_mean_of_inlinks_to_node(rmg, "z")
array([  0. ,   0. ,   0.5,   1. ,   1.5,   5.5,   6.5,   7.5,   5. ,
        12.5,  13.5,  14.5])

map_mean_of_links_to_node(var_name, out=None)

Map the mean of links touching a node to the node.

map_mean_all_links_to_node takes an array at the links and finds the average of all ~existing~ link neighbor values for each node in the grid. it returns values at the nodes.

Note

This considers all inactive links to have a value of 0.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import map_mean_of_links_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", np.arange(17.0), at="link")
>>> map_mean_of_links_to_node(rmg, "z")
array([  1.5       ,   1.66666667,   2.66666667,   4.        ,
         6.66666667,   7.5       ,   8.5       ,   9.33333333,
        12.        ,  13.33333333,  14.33333333,  14.5       ])

map_mean_of_outlinks_to_node(var_name, out=None)

Map the mean of links leaving a node to the node.

map_mean_of_outlinks_to_node takes an array at the links and finds the outlink values for each node in the grid. it finds the average of the outlinks and returns values at the nodes.

Note

This considers all inactive links to have a value of 0.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import map_mean_of_outlinks_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", np.arange(17.0), at="link")
>>> map_mean_of_outlinks_to_node(rmg, "z")
array([  1.5,   2.5,   3.5,   3. ,   8.5,   9.5,  10.5,   6.5,   7. ,
         7.5,   8. ,   0. ])

map_mean_of_vertical_active_links_to_node(var_name, out=None)

Map the mean of active links in the y direction touching node to the node.

map_mean_of_vertical_active_links_to_node takes an array at the links and finds the average of all vertical (y-direction) link neighbor values for each node in the grid. It returns an array at the nodes of the mean of these values. If a link is absent, it is ignored. If a node has no active links, it receives 0. Note that here a positive returned value means flux to the north, and a negative to the south.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import (
...     map_mean_of_vertical_active_links_to_node,
... )
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", -np.arange(17, dtype=float), at="link")
>>> rmg.status_at_node[rmg.nodes_at_bottom_edge] = rmg.BC_NODE_IS_CLOSED
>>> map_mean_of_vertical_active_links_to_node(rmg, "z")
array([  0.,   0.,   0.,   0.,   0., -11., -12.,   0.,   0., -11., -12.,
         0.])

map_mean_of_vertical_links_to_node(var_name, out=None)

Map the mean of links in the y direction touching a node to the node.

map_mean_of_vertical_links_to_node takes an array at the links and finds the average of all vertical (y-direction) link neighbor values for each node in the grid. It returns an array at the nodes of the mean of these values. If a link is absent, it is ignored. Note that here a positive returned value means flux to the north, and a negative to the south.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import map_mean_of_vertical_links_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", np.arange(17.0), at="link")
>>> map_mean_of_vertical_links_to_node(rmg, "z")
array([  3. ,   4. ,   5. ,   6. ,   6.5,   7.5,   8.5,   9.5,  10. ,
        11. ,  12. ,  13. ])

map_min_of_inlinks_to_node(var_name, out=None)

Map the minimum of links entering a node to the node.

map_min_of_inlinks_to_node takes an array at the links and finds the inlink values for each node in the grid. it finds the minimum value at the the inlinks and returns values at the nodes.

Note

This considers all inactive links to have a value of 0.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import map_min_of_inlinks_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", np.arange(17.0), at="link")
>>> map_min_of_inlinks_to_node(rmg, "z")
array([  0.,   0.,   0.,   0.,   0.,   4.,   5.,   6.,   0.,  11.,  12.,
        13.])

map_min_of_outlinks_to_node(var_name, out=None)

Map the min of links leaving a node to the node.

map_min_of_outlinks_to_node takes an array at the links and finds the outlink values for each node in the grid. It finds the minimum value at the the outlinks and returns values at the nodes.

Note

This considers all inactive links to have a value of 0.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import map_min_of_outlinks_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", np.arange(17.0), at="link")
>>> map_min_of_outlinks_to_node(rmg, "z")
array([ 0.,  1.,  2.,  0.,  7.,  8.,  9.,  0.,  0.,  0.,  0.,  0.])

map_sum_of_inlinks_to_node(var_name, out=None)

Map the sum of links entering a node to the node.

map_sum_of_inlinks_to_node takes an array at the links and finds the inlink values for each node in the grid. it sums the inlinks and returns values at the nodes.

Note

This considers all inactive links to have a value of 0.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import map_sum_of_inlinks_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", np.arange(17.0), at="link")
>>> map_sum_of_inlinks_to_node(rmg, "z")
array([  0.,   0.,   1.,   2.,   3.,  11.,  13.,  15.,  10.,  25.,  27.,
        29.])

map_sum_of_outlinks_to_node(var_name, out=None)

Map the sum of links leaving a node to the node.

map_sum_of_outlinks_to_node takes an array at the links and finds the outlink values for each node in the grid. it sums the outlinks and returns values at the nodes.

Note

This considers all inactive links to have a value of 0.

Parameters:

• var_name (array or field name) – Values defined at links.

• out (ndarray, optional) – Buffer to place mapped values into or None to create a new array.

Returns:

Mapped values at nodes.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from landlab.grid.raster_mappers import map_sum_of_outlinks_to_node
>>> from landlab import RasterModelGrid

>>> rmg = RasterModelGrid((3, 4))
>>> _ = rmg.add_field("z", np.arange(17.0), at="link")
>>> map_sum_of_outlinks_to_node(rmg, "z")
array([  3.,  5.,  7.,   6.,  17.,  19.,  21.,  13.,  14.,  15.,  16.,
         0.])

node_has_boundary_neighbor(ids, method='d8')

Check if nodes have neighbors that are boundary nodes.

Checks to see if one of the eight neighbor nodes of node(s) with id has a boundary node. Returns True if a node has a boundary node, False if all neighbors are interior.

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((5, 5))
>>> mg.node_has_boundary_neighbor(6)
True
>>> mg.node_has_boundary_neighbor(12)
False
>>> mg.node_has_boundary_neighbor([12, -1])
array([False,  True], dtype=bool)

>>> mg.node_has_boundary_neighbor(25)
Traceback (most recent call last):
    ...
IndexError: index 25 is out of bounds for axis 0 with size 25

node_vector_to_raster(u, flip_vertically=False)

Unravel an array of node values.

Converts node vector u to a 2D array and returns it, so that it can be plotted, output, etc.

If the flip_vertically keyword is True, this function returns an array that has the rows in reverse order. This is useful for use in plot commands (such as the image display functions) that puts the first row at the top of the image. In the landlab coordinate system, the first row is thought to be at the bottom. Thus, a flipped matrix will plot in the landlab style with the first row at the bottom.

The returned array is a view of u, not a copy.

See also

RasterModelGrid.nodes

An equivalent property, but without the option to flip the grid.

Examples

>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 5))
>>> u = rmg.zeros(centering="node")
>>> u = u + range(0, len(u))
>>> u
array([ 0.,   1.,   2.,   3.,   4.,   5.,   6.,   7.,   8.,   9.,  10.,
       11.,  12.,  13.,  14.,  15.,  16.,  17.,  18.,  19.])
>>> ur = rmg.node_vector_to_raster(u)
>>> ur
array([[  0.,   1.,   2.,   3.,   4.],
       [  5.,   6.,   7.,   8.,   9.],
       [ 10.,  11.,  12.,  13.,  14.],
       [ 15.,  16.,  17.,  18.,  19.]])
>>> ur = rmg.node_vector_to_raster(u, flip_vertically=True)
>>> ur
array([[ 15.,  16.,  17.,  18.,  19.],
       [ 10.,  11.,  12.,  13.,  14.],
       [  5.,   6.,   7.,   8.,   9.],
       [  0.,   1.,   2.,   3.,   4.]])

nodes_around_point(xcoord, ycoord)

Get the nodes surrounding a point.

Return IDs of the four nodes of the area around a point with coordinates xcoord, ycoord. Node IDs are returned counter-clockwise order starting from the southwest node.

If either xcoord or ycoord are arrays the usual numpy broadcasting rules apply.

Parameters:

• xcoord (float, array-like) – x-coordinate of point

• ycoord (float, array-like) – y-coordinate of point

Returns:

IDs of nodes around the point.

Return type:

(4, N) ndarray

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> grid.nodes_around_point(0.4, 1.2)
array([4, 8, 9, 5])

>>> grid.nodes_around_point([0.9, 1.1], 1.2)
array([[ 4,  5],
       [ 8,  9],
       [ 9, 10],
       [ 5,  6]])

>>> grid = RasterModelGrid((3, 4), xy_spacing=(1, 2))
>>> grid.nodes_around_point(0.5, 1.5)
array([0, 4, 5, 1])
>>> grid = RasterModelGrid((3, 4))
>>> grid.nodes_around_point(0.5, 1.5)
array([4, 8, 9, 5])

property number_of_cell_columns

Number of cell columns.

Returns the number of columns, including boundaries.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.number_of_cell_columns
3

property number_of_cell_rows

Number of cell rows.

Returns the number of rows, including boundaries.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.number_of_cell_rows
2

property number_of_cells_present_at_corner

Return the number of cells at a corner without a closed corner.

See also

number_of_patches_present_at_node

property number_of_cells_present_at_face

Return the number of cells at a face without a closed corner.

See also

number_of_patches_present_at_link

property number_of_core_corners

Number of core corners.

See also

number_of_core_nodes

property number_of_core_patches

Number of core patches.

See also

number_of_core_cells

property number_of_fixed_faces

Number of fixed faces.

See also

number_of_fixed_links

property number_of_interior_corners

Number of interior corners.

See also

number_of_interior_nodes

property number_of_interior_nodes

Number of interior nodes.

Returns the number of interior nodes on the grid, i.e., non-perimeter nodes. Compare self.number_of_core_nodes.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.number_of_interior_nodes
6

property number_of_patch_columns

Number of patch columns.

See also

number_of_cell_columns

property number_of_patch_rows

Number of patch rows.

See also

number_of_cell_rows

property open_boundary_corners

Get array of open boundary corners.

See also

open_boundary_nodes

property patch_area_at_corner

Cell areas in a ncorners-long array.

See also

cell_area_at_node

property patch_grid_shape

Get the shape of the patchular grid (grid with only patches).

See also

cell_grid_shape

property patches_at_nodes_of_grid

Get array of patches in patchular grid (grid with only patches) nodes.

See also

cells_at_corners_of_grid

roll_nodes_ud(data_name, shift, interior_only=False)

Roll (shift) specified data on nodes up or down in a raster grid.

Similar to the Numpy roll() function, in that it shifts node values up by shift rows, wrapping the data in the top row(s) around to the bottom. If the interior_only is set, data along the left and right grid edges are not changed.

Note that the contents of the data_name field are changed.

Parameters:

• data_name (string) – Name of node-data item attached to grid.

• shift (int) – Number of rows to shift upward.

• interior_only (bool, optional) – If True, data along left and right edges are not shifted

Examples

>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 3))
>>> data = rmg.add_zeros("test_data", at="node")
>>> data[:] = np.arange(12)
>>> rmg.roll_nodes_ud("test_data", 1)
>>> data.reshape(rmg.shape)
array([[  9.,  10.,  11.],
       [  0.,   1.,   2.],
       [  3.,   4.,   5.],
       [  6.,   7.,   8.]])
>>> rmg.roll_nodes_ud("test_data", 2)
>>> data.reshape(rmg.shape)
array([[  3.,   4.,   5.],
       [  6.,   7.,   8.],
       [  9.,  10.,  11.],
       [  0.,   1.,   2.]])
>>> rmg.roll_nodes_ud("test_data", 1, interior_only=True)
>>> data.reshape(rmg.shape)
array([[  3.,   1.,   5.],
       [  6.,   4.,   8.],
       [  9.,   7.,  11.],
       [  0.,  10.,   2.]])

save(path, names=None, format=None, at=None)

Save a grid and fields.

If more than one field name is specified for names when saving to ARC ascii, multiple files will be produced, suffixed with the field names.

When saving to netCDF (.nc), the fields are incorporated into the single named .nc file.

Parameters:

• path (str) – Path to output file.

• names (iterable of strings, optional) – List of field names to save, defaults to all if not specified.

• format ({'netcdf', 'esri-ascii'}, optional) – Output file format. Guess from file extension if not given.

• at (str) – Grid element where values are defined.

Examples

>>> from landlab import RasterModelGrid
>>> import os
>>> from tempfile import mkdtemp

>>> grid = RasterModelGrid((4, 5))
>>> fname = os.path.join(mkdtemp(), "mysave.nc")
>>> grid.save(fname)
>>> os.path.isfile(fname)
True
>>> os.remove(fname)

property second_ring_looped_neighbors_at_cell

Get list of second ring looped neighbor cell IDs (all 16 neighbors).

Returns lists of looped second ring neighbor cell IDs of given cell ids. If cell ids are not given, it returns a 2D array of size ( self.number_of_cells, 16 ).

The cells are the 16 which encircle the nine true neighbor cells. Order of neighbors: Starts with E and goes counter clockwise

Examples

>>> from landlab import RasterModelGrid
>>> mg = RasterModelGrid((10, 10))
>>> mg.second_ring_looped_neighbors_at_cell[36, :]
array([38, 46, 54, 53, 52, 51, 50, 42, 34, 26, 18, 19, 20, 21, 22, 30])
>>> mg.second_ring_looped_neighbors_at_cell[8, :]
array([10, 18, 26, 25, 24, 31, 30, 22, 14,  6, 62, 63, 56, 57, 58,  2])

…take a look at the cell grid to understand why:

[56, 57, 58, 59, 60, 61, 62, 63]
[48, 49, 50, 51, 52, 53, 54, 55]
[40, 41, 42, 43, 44, 45, 46, 47]
[32, 33, 34, 35, 36, 37, 38, 39]
[24, 25, 26, 27, 28, 29, 30, 31]
[16, 17, 18, 19, 20, 21, 22, 23]
[ 8,  9, 10, 11, 12, 13, 14, 15]
[ 0,  1,  2,  3,  4,  5,  6,  7]

property second_ring_looped_neighbors_at_patch

Get list of second ring looped neighbor patch IDs (all 16 neighbors).

See also

second_ring_looped_neighbors_at_cell

set_closed_boundaries_at_grid_edges(right_is_closed, top_is_closed, left_is_closed, bottom_is_closed)

Set boundary not to be closed.

Sets the status of nodes along the specified side(s) of a raster grid (bottom, right, top, and/or left) to BC_NODE_IS_CLOSED.

Arguments are booleans indicating whether the bottom, left, top, and right are closed (True) or not (False).

For a closed boundary:

• the nodes are flagged BC_NODE_IS_CLOSED (status type 4)

• all links that connect to a BC_NODE_IS_CLOSED node are flagged as inactive (so they appear on link-based lists, but not active_link-based lists)

This means that if you call the calc_grad_at_active_link method, links connecting to closed boundaries will be ignored: there can be no gradients or fluxes calculated, because the links that connect to that edge of the grid are not included in the calculation. So, setting a grid edge to BC_NODE_IS_CLOSED is a convenient way to impose a no-flux boundary condition. Note, however, that this applies to the grid as a whole, rather than a particular variable that you might use in your application. In other words, if you want a no-flux boundary in one variable but a different boundary condition for another, then use another method.

Parameters:

• right_is_closed (boolean) – If True right-edge nodes are closed boundaries.

• top_is_closed (boolean) – If True top-edge nodes are closed boundaries.

• left_is_closed (boolean) – If True left-edge nodes are closed boundaries.

• bottom_is_closed (boolean) – If True bottom-edge nodes are closed boundaries.

Notes

Note that the four corners are treated as follows:

• bottom left = BOTTOM

• bottom right = BOTTOM

• top right = TOP

• top left = TOP

This scheme is necessary for internal consistency with looped boundaries.

Examples

The following example sets the top and left boundaries as closed in a four-row by five-column grid that initially has all boundaries open and all boundary nodes coded as BC_NODE_IS_FIXED_VALUE (=1):

>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 5))  # rows, columns, spacing
>>> rmg.number_of_active_links
17
>>> rmg.status_at_node.reshape(rmg.shape)
array([[1, 1, 1, 1, 1],
       [1, 0, 0, 0, 1],
       [1, 0, 0, 0, 1],
       [1, 1, 1, 1, 1]], dtype=uint8)
>>> rmg.set_closed_boundaries_at_grid_edges(True, True, False, False)
>>> rmg.number_of_active_links
12
>>> rmg.status_at_node.reshape(rmg.shape)
array([[1, 1, 1, 1, 1],
       [1, 0, 0, 0, 4],
       [1, 0, 0, 0, 4],
       [4, 4, 4, 4, 4]], dtype=uint8)

set_fixed_value_boundaries_at_grid_edges(right_is_fixed_val, top_is_fixed_val, left_is_fixed_val, bottom_is_fixed_val, value=None, value_of='topographic__elevation')

Create fixed values boundaries.

Sets the status of nodes along the specified side(s) of a raster grid—bottom, right, top, and/or left—to NODE_IS_FIXED_VALUE

Arguments are booleans indicating whether the bottom, right, top, and left sides are to be set (True) or not (False).

value controls what values are held constant at these nodes. It can be either a float, an array of length number_of_fixed_nodes or number_of_nodes (total), or left blank. If left blank, the values will be set from the those already in the grid fields, according to ‘value_of’.

value_of controls the name of the model field that contains the values. Remember, if you don’t set value, the fixed values will be set from the field values *at the time you call this method*. If no values are present in the field, the module will complain but accept this, warning that it will be unable to automatically update boundary conditions.

The status of links (active or inactive) is automatically updated to reflect the changes.

The following example sets the bottom and right boundaries as fixed-value in a four-row by five-column grid that initially has all boundaries closed (i.e., flagged as node_status=4):

Parameters:

• bottom_is_fixed_val (boolean) – Set bottom edge as fixed boundary.

• left_is_fixed_val (boolean) – Set left edge as fixed boundary.

• top_is_fixed_val (boolean) – Set top edge as fixed boundary.

• right_is_fixed_val (boolean) – Set right edge as fixed boundary.

• value (float, array or None (default).) – Override value to be kept constant at nodes.

• value_of (string.) – The name of the grid field containing the values of interest.

Examples

>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 5), xy_spacing=(1, 1))
>>> rmg.number_of_active_links
17

Put some arbitrary values in the grid fields:

>>> import numpy as np
>>> rmg.at_node["topographic__elevation"] = np.random.rand(20)
>>> rmg.set_closed_boundaries_at_grid_edges(True, True, True, True)
>>> rmg.status_at_node.reshape(rmg.shape)
array([[4, 4, 4, 4, 4],
       [4, 0, 0, 0, 4],
       [4, 0, 0, 0, 4],
       [4, 4, 4, 4, 4]], dtype=uint8)
>>> rmg.set_fixed_value_boundaries_at_grid_edges(True, True, False, False)
>>> rmg.number_of_active_links
12
>>> rmg.status_at_node.reshape(rmg.shape)
array([[4, 4, 4, 4, 4],
       [4, 0, 0, 0, 1],
       [4, 0, 0, 0, 1],
       [1, 1, 1, 1, 1]], dtype=uint8)

Note that the four corners are treated as follows:

• bottom left = BOTTOM

• bottom right = BOTTOM

• top right = TOP

• top left = TOP

This scheme is necessary for internal consistency with looped boundaries.

set_looped_boundaries(top_bottom_are_looped, sides_are_looped)

Create wrap-around boundaries.

Handles boundary conditions by setting corresponding parallel grid edges as looped “tracks_cell” (==3) status, linked to each other. If top_bottom_are_looped is True, the top and bottom edges will link to each other. If sides_are_looped is True, the left and right edges will link to each other.

Looped boundaries are experimental, and not as yet well integrated into the Landlab framework. Many functions may not recognise them, or silently create unforeseen errors. Use at your own risk!

Note that because of the symmetries this BC implies, the corner nodes are all paired with the bottom/top edges, not the sides.

Parameters:

• top_bottom_are_looped (bool) – Top and bottom are wrap-around.

• sides_are_looped (bool) – Left and right sides are wrap-around.

Examples

>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 5))  # rows, columns, spacing
>>> rmg.number_of_active_links
17
>>> rmg.status_at_node.reshape(rmg.shape)
array([[1, 1, 1, 1, 1],
       [1, 0, 0, 0, 1],
       [1, 0, 0, 0, 1],
       [1, 1, 1, 1, 1]], dtype=uint8)
>>> rmg.add_zeros("topographic__elevation", at="node")
array([ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,
        0.,  0.,  0.,  0.,  0.,  0.,  0.])
>>> rmg.set_looped_boundaries(True, True)
>>> rmg.looped_node_properties["boundary_node_IDs"]
array([ 0,  1,  2,  3,  4,  5,  9, 10, 14, 15, 16, 17, 18, 19])
>>> rmg.looped_node_properties["linked_node_IDs"]
array([10, 11, 12, 13, 14,  8,  6, 13, 11,  5,  6,  7,  8,  9])

set_open_nodes_disconnected_from_watershed_to_closed(node_data, outlet_id=None, nodata_value=-9999.0, adjacency_method='D8')

Identifys all non-closed nodes that are disconnected from the node given in.

outlet_id and sets them as closed.

If outlet_id is not given, the outlet will be identified as the node for which the status at the node is BC_NODE_IS_FIXED_VALUE. If more than one node has this value, the algorithm will fail.

If outlet_id is given, the algorithm will check that it is not a node with status of BC_NODE_IS_CLOSED.

The method supports both D4 and D8 (default) neighborhood evaluation in determining if a node is connected. This can be modified with the flag adjacency_method.

This function can be run directly, or by setting the flag remove_disconnected to True in set_watershed_boundary_condition

Parameters:

• node_data (field name or ndarray) – At-node field name or at-node data values to use for identifying watershed location.

• outlet_id (one element numpy array, optional.) – The node ID of the outlet that all open nodes must be connected to. If a node ID is provided, it does not need have the status BC_NODE_IS_FIXED_VALUE. However, it must not have the status of BC_NODE_IS_CLOSED.

• nodata_value (float, optional, default is -9999.) – Value that indicates an invalid value.

• adjacency_method (string, optional. Default is 'D8'.) – Sets the connection method.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> mg1 = RasterModelGrid((4, 6))
>>> z1 = np.array(
...     [
...         [-9999.0, -9999.0, -9999.0, -9999.0, -9999.0, -9999.0],
...         [-9999.0, 67.0, 67.0, -9999.0, 50.0, -9999.0],
...         [-9999.0, 67.0, 0.0, -9999.0, -9999.0, -9999.0],
...         [-9999.0, -9999.0, -9999.0, -9999.0, -9999.0, -9999.0],
...     ]
... ).flatten()
>>> mg2 = RasterModelGrid((4, 6))
>>> z2 = np.array(
...     [
...         [-9999.0, -9999.0, -9999.0, -9999.0, -9999.0, -9999.0],
...         [-9999.0, 67.0, 67.0, -9999.0, 50.0, -9999.0],
...         [-9999.0, 67.0, 0.0, -9999.0, -9999.0, -9999.0],
...         [-9999.0, -9999.0, -9999.0, -9999.0, -9999.0, -9999.0],
...     ]
... ).flatten()
>>> mg1.set_watershed_boundary_condition(z1, remove_disconnected=True)
>>> mg2.set_watershed_boundary_condition(z2)
>>> mg2.status_at_node.reshape(mg2.shape)
array([[4, 4, 4, 4, 4, 4],
       [4, 0, 0, 4, 0, 4],
       [4, 0, 1, 4, 4, 4],
       [4, 4, 4, 4, 4, 4]], dtype=uint8)
>>> mg2.set_open_nodes_disconnected_from_watershed_to_closed(z2)
>>> np.allclose(mg1.status_at_node, mg2.status_at_node)
True
>>> np.allclose(z1, z2)
True
>>> mg2.status_at_node.reshape(mg2.shape)
array([[4, 4, 4, 4, 4, 4],
       [4, 0, 0, 4, 4, 4],
       [4, 0, 1, 4, 4, 4],
       [4, 4, 4, 4, 4, 4]], dtype=uint8)
>>> z1.reshape(mg1.shape)
array([[-9999., -9999., -9999., -9999., -9999., -9999.],
       [-9999.,    67.,    67., -9999., -9999., -9999.],
       [-9999.,    67.,     0., -9999., -9999., -9999.],
       [-9999., -9999., -9999., -9999., -9999., -9999.]])

set_status_at_node_on_edges(right=None, top=None, left=None, bottom=None)

Set node status on grid edges.

Parameters:

• right (int, optional) – Node status along right edge.

• top (int, optional) – Node status along top edge.

• left (int, optional) – Node status along left edge.

• bottom (int, optional) – Node status along bottom edge.

Examples

>>> from landlab import RasterModelGrid

>>> grid = RasterModelGrid((3, 4))
>>> grid.status_at_node.reshape(grid.shape)
array([[1, 1, 1, 1],
       [1, 0, 0, 1],
       [1, 1, 1, 1]], dtype=uint8)

>>> grid.set_status_at_node_on_edges(right=grid.BC_NODE_IS_CLOSED)
>>> grid.status_at_node.reshape(grid.shape)
array([[1, 1, 1, 4],
       [1, 0, 0, 4],
       [1, 1, 1, 4]], dtype=uint8)

>>> grid = RasterModelGrid((3, 4))

The status of a corner is set along with its clockwise edge. That is, if setting the status for the top and right edges, the upper-right corner has the status of the right edge.

>>> grid.set_status_at_node_on_edges(
...     top=grid.BC_NODE_IS_CLOSED, right=grid.BC_NODE_IS_FIXED_GRADIENT
... )
>>> grid.status_at_node.reshape(grid.shape)
array([[1, 1, 1, 2],
       [1, 0, 0, 2],
       [4, 4, 4, 2]], dtype=uint8)

In the above example, if you wanted the corner to have the status of the top edge, you need to make two calls to set_status_at_node_on_edges,

>>> grid = RasterModelGrid((3, 4))
>>> grid.set_status_at_node_on_edges(right=grid.BC_NODE_IS_FIXED_GRADIENT)
>>> grid.set_status_at_node_on_edges(top=grid.BC_NODE_IS_CLOSED)
>>> grid.status_at_node.reshape(grid.shape)
array([[1, 1, 1, 2],
       [1, 0, 0, 2],
       [4, 4, 4, 4]], dtype=uint8)

An example that sets all of the edges shows how corners are set.

>>> grid.set_status_at_node_on_edges(right=1, top=2, left=3, bottom=4)
>>> grid.status_at_node.reshape(grid.shape)
array([[3, 4, 4, 4],
       [3, 0, 0, 1],
       [2, 2, 2, 1]], dtype=uint8)

set_watershed_boundary_condition(node_data, nodata_value=-9999.0, return_outlet_id=False, remove_disconnected=False, adjacency_method='D8')

Finds the node adjacent to a boundary node with the smallest value. This node is set as the outlet. The outlet node must have a data value. Can return the outlet id as a one element numpy array if return_outlet_id is set to True.

All nodes with nodata_value are set to BC_NODE_IS_CLOSED (grid.status_at_node == 4). All nodes with data values are set to BC_NODE_IS_CORE (grid.status_at_node == 0), with the exception that the outlet node is set to a BC_NODE_IS_FIXED_GRADIENT (grid.status_at_node == 1).

Note that the outer ring (perimeter) of the raster is set to BC_NODE_IS_CLOSED, even if there are nodes that have values. The only exception to this would be if the outlet node is on the perimeter, which is acceptable.

This routine assumes that all of the nodata_values are on the outside of the data values. In other words, there are no islands of nodata_values surrounded by nodes with data.

This also assumes that the grid has a single watershed (that is a single outlet node).

If you are considering running flow routing algorithms on this model grid, it is recommended that you verify the absence of non-closed nodes surrounded only by closed nodes. The presence of these isolated non- closed nodes may result from clipping a raster to a polygon and will prevent the flow router from functioning as intended.

This can be acomplished by setting the parameter: remove_disconnected to True (default is False).

This will run the function: set_open_nodes_disconnected_from_watershed_to_closed which will find any isolated open nodes that have no neigbors in the main watershed and set them to closed. The adjacency method used to assess connectivity can be set to either ‘D8’(default) or ‘D4’ using the flag adjacency_method.

Finally, the developer has seen cases in which DEM data that has been filled results in a different outlet from DEM data which has not been filled. Be aware that if you identify an outlet on a filled DEM, make sure that the filled DEM is what is being used for your modeling. Otherwise, this may find a different outlet. To force the outlet location, use either set_watershed_boundary_condition_outlet_coords or set_watershed_boundary_condition_outlet_id.

Parameters:

• node_data (field name or ndarray) – At-node field name or at-node data values to use for identifying watershed location.

• nodata_value (float, optional) – Value that indicates an invalid value.

• return_outlet_id (boolean, optional) – Indicates whether or not to return the id of the found outlet

• remove_disconnected (boolean, optional) – Indicates whether to search for and remove disconnected nodes.

• adjacency_method (string, optional. Default is 'D8'.) – Sets the connection method for use if remove_disconnected==True

Returns:

outlet_loc – Array of size 1 containing id of outlet location

Return type:

array

Examples

The first example will use a 4,4 grid with node data values as illustrated:

-9999. -9999. -9999. -9999.
-9999.    67.     0. -9999.
-9999.    67.    67. -9999.
-9999. -9999. -9999. -9999.

The second example will use a 4,4 grid with node data values as illustrated:

-9999. -9999. -9999. -9999.
-9999.    67.     0. -9999.
-9999.    67.     67.   -2.
-9999. -9999. -9999. -9999.

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 4))
>>> node_data = np.array(
...     [
...         [-9999.0, -9999.0, -9999.0, -9999.0],
...         [-9999.0, 67.0, 67.0, -9999.0],
...         [-9999.0, 67.0, 0.0, -9999.0],
...         [-9999.0, -9999.0, -9999.0, -9999.0],
...     ]
... ).flatten()
>>> out_id = rmg.set_watershed_boundary_condition(node_data, -9999.0, True)
>>> out_id
array([10])
>>> rmg.status_at_node
array([4, 4, 4, 4, 4, 0, 0, 4, 4, 0, 1, 4, 4, 4, 4, 4], dtype=uint8)
>>> rmg2 = RasterModelGrid((4, 4))
>>> node_data2 = np.array(
...     [
...         [-9999.0, -9999.0, -9999.0, -9999.0],
...         [-9999.0, 67.0, 67.0, -2.0],
...         [-9999.0, 67.0, 0.0, -9999.0],
...         [-9999.0, -9999.0, -9999.0, -9999.0],
...     ]
... ).flatten()
>>> rmg2.set_watershed_boundary_condition(node_data2, -9999.0)
>>> rmg2.status_at_node
array([4, 4, 4, 4, 4, 0, 0, 1, 4, 0, 0, 4, 4, 4, 4, 4], dtype=uint8)

The node data can also be provided as a model grid field.

>>> rmg = RasterModelGrid((4, 4))
>>> node_data = [
...     [-9999.0, -9999.0, -9999.0, -9999.0],
...     [-9999.0, 67.0, 67.0, -9999.0],
...     [-9999.0, 67.0, 0.0, -9999.0],
...     [-9999.0, -9999.0, -9999.0, -9999.0],
... ]
>>> _ = rmg.add_field("topographic__elevation", node_data, at="node")
>>> out_id = rmg.set_watershed_boundary_condition(
...     "topographic__elevation", -9999.0, True
... )
>>> out_id
array([10])
>>> rmg.status_at_node
array([4, 4, 4, 4, 4, 0, 0, 4, 4, 0, 1, 4, 4, 4, 4, 4], dtype=uint8)

set_watershed_boundary_condition_outlet_coords(outlet_coords, node_data, nodata_value=-9999.0)

Set the boundary conditions for a watershed. All nodes with nodata_value are set to BC_NODE_IS_CLOSED (grid.status_at_node == 4). All nodes with data values are set to CORE_NODES (grid.status_at_node == 0), with the exception that the outlet node is set to a BC_NODE_IS_FIXED_VALUE (grid.status_at_node == 1).

Note that the outer ring of the raster is set to BC_NODE_IS_CLOSED, even if there are nodes that have values. The only exception to this would be if the outlet node is on the boundary, which is acceptable.

Assumes that outlet is already known.

This assumes that the grid has a single watershed. If this is not the case this will not work.

This must be passed the values of the outlet_row and outlet_column. Also takes node_data and optionally, nodata_value.

Parameters:

• outlet_coords (list - two integer values) – row, column of outlet, NOT THE ABSOLUTE X AND Y LOCATIONS

• node_data (field name or ndarray) – At-node field name or at-node data values to use for identifying watershed location.

• nodata_value (float, optional) – Value that indicates an invalid value.

Examples

The example will use a 4,4 grid with node data values as illustrated:

-9999. -9999. -9999. -9999.
-9999.    67.     0. -9999.
-9999.    67.    67. -9999.
-9999. -9999. -9999. -9999.

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 4))
>>> rmg.status_at_node
array([1, 1, 1, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 1, 1, 1], dtype=uint8)
>>> node_data = np.array(
...     [
...         [-9999.0, -9999.0, -9999.0, -9999.0],
...         [-9999.0, 67.0, 67.0, -9999.0],
...         [-9999.0, 67.0, 0.0, -9999.0],
...         [-9999.0, -9999.0, -9999.0, -9999.0],
...     ]
... ).flatten()
>>> rmg.set_watershed_boundary_condition_outlet_coords(
...     (2, 2), node_data, -9999.0
... )
>>> rmg.status_at_node.reshape(rmg.shape)
array([[4, 4, 4, 4],
       [4, 0, 0, 4],
       [4, 0, 1, 4],
       [4, 4, 4, 4]], dtype=uint8)

set_watershed_boundary_condition_outlet_id(outlet_id, node_data, nodata_value=-9999.0)

Set the boundary conditions for a watershed. All nodes with nodata_value are set to BC_NODE_IS_CLOSED (4). All nodes with data values are set to BC_NODE_IS_CORE (0), with the exception that the outlet node is set to a BC_NODE_IS_FIXED_VALUE (1).

Note that the outer ring of the raster is set to BC_NODE_IS_CLOSED, even if there are nodes that have values. The only exception to this would be if the outlet node is on the boundary, which is acceptable.

Assumes that the id of the outlet is already known.

This assumes that the grid has a single watershed. If this is not the case this will not work.

Parameters:

• outlet_id (integer) – id of the outlet node

• node_data (field name or ndarray) – At-node field name or at-node data values to use for identifying watershed location.

• nodata_value (float, optional) – Value that indicates an invalid value.

Examples

The example will use a 4,4 grid with node data values as illustrated:

-9999. -9999. -9999. -9999. -9999. 67. 0. -9999. -9999. 67. 67. -9999. -9999. -9999. -9999. -9999.

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> rmg = RasterModelGrid((4, 4))
>>> rmg.status_at_node.reshape(rmg.shape)
array([[1, 1, 1, 1],
       [1, 0, 0, 1],
       [1, 0, 0, 1],
       [1, 1, 1, 1]], dtype=uint8)
>>> node_data = np.array(
...     [
...         [-9999.0, -9999.0, -9999.0, -9999.0],
...         [-9999.0, 67.0, 67.0, -9999.0],
...         [-9999.0, 67.0, 0.0, -9999.0],
...         [-9999.0, -9999.0, -9999.0, -9999.0],
...     ]
... ).flatten()
>>> outlet = rmg.set_watershed_boundary_condition_outlet_id(
...     10, node_data, -9999.0
... )
>>> rmg.status_at_node.reshape(rmg.shape)
array([[4, 4, 4, 4],
       [4, 0, 0, 4],
       [4, 0, 1, 4],
       [4, 4, 4, 4]], dtype=uint8)

property status_at_corner

Get array of the boundary status for each corner.

See also

status_at_node

property status_at_face

Get array of the status of all faces.

See also

status_at_link

property unit_vector_sum_xcomponent_at_corner

Get array of x-component of unit vector sums at each corner.

See also

unit_vector_sum_xcomponent_at_node

property unit_vector_sum_ycomponent_at_corner

Get array of y-component of unit vector sums at each corner.

See also

unit_vector_sum_ycomponent_at_node

property xy_of_lower_left

Return (x, y) of the reference point.

class VoronoiDelaunayGrid(x=None, y=None, reorient_links=True, xy_of_reference=(0.0, 0.0), xy_axis_name=('x', 'y'), xy_axis_units='-')

This inherited class implements an unstructured grid in which cells are Voronoi polygons and nodes are connected by a Delaunay triangulation. Uses scipy.spatial module to build the triangulation.

Create an unstructured grid from points whose coordinates are given by the arrays x, y.

Returns:

A newly-created grid.

Return type:

VoronoiDelaunayGrid

Examples

>>> import numpy as np
>>> from numpy.random import rand
>>> from landlab.grid import VoronoiDelaunayGrid

>>> x, y = rand(25), rand(25)
>>> vmg = VoronoiDelaunayGrid(x, y)  # node_x_coords, node_y_coords
>>> vmg.number_of_nodes
25

>>> x = np.array(
...     [
...         [0, 0.1, 0.2, 0.3],
...         [1, 1.1, 1.2, 1.3],
...         [2, 2.1, 2.2, 2.3],
...     ]
... ).flatten()
>>> y = np.array(
...     [
...         [0.0, 1.0, 2.0, 3.0],
...         [0.0, 1.0, 2.0, 3.0],
...         [0.0, 1.0, 2.0, 3.0],
...     ]
... ).flatten()

>>> vmg = VoronoiDelaunayGrid(x, y)
>>> vmg.node_x
array([ 0. ,  1. ,  2. ,
        0.1,  1.1,  2.1,
        0.2,  1.2,  2.2,
        0.3,  1.3,  2.3])
>>> vmg.node_y
array([ 0.,  0.,  0.,
        1.,  1.,  1.,
        2.,  2.,  2.,
        3.,  3.,  3.])
>>> vmg.adjacent_nodes_at_node
array([[ 1,  3, -1, -1, -1, -1],
       [ 2,  4,  3,  0, -1, -1],
       [ 5,  4,  1, -1, -1, -1],
       [ 4,  6,  0,  1, -1, -1],
       [ 5,  7,  6,  3,  1,  2],
       [ 8,  7,  4,  2, -1, -1],
       [ 7,  9,  3,  4, -1, -1],
       [ 8, 10,  9,  6,  4,  5],
       [11, 10,  7,  5, -1, -1],
       [10,  6,  7, -1, -1, -1],
       [11,  9,  7,  8, -1, -1],
       [10,  8, -1, -1, -1, -1]])

Create a Voronoi Delaunay grid from a set of points.

Create an unstructured grid from points whose coordinates are given by the arrays x, y.

Parameters:

• x (array_like) – x-coordinate of points

• y (array_like) – y-coordinate of points

• (optional) (reorient_links) – whether to point all links to the upper-right quadrant

• xy_of_reference (tuple, optional) – Coordinate value in projected space of (0., 0.) Default is (0., 0.)

Returns:

A newly-created grid.

Return type:

VoronoiDelaunayGrid

Examples

>>> from numpy.random import rand
>>> from landlab.grid import VoronoiDelaunayGrid
>>> x, y = rand(25), rand(25)
>>> vmg = VoronoiDelaunayGrid(x, y)  # node_x_coords, node_y_coords
>>> vmg.number_of_nodes
25

__init__(x=None, y=None, reorient_links=True, xy_of_reference=(0.0, 0.0), xy_axis_name=('x', 'y'), xy_axis_units='-')

Create a Voronoi Delaunay grid from a set of points.

Create an unstructured grid from points whose coordinates are given by the arrays x, y.

Parameters:

• x (array_like) – x-coordinate of points

• y (array_like) – y-coordinate of points

• (optional) (reorient_links) – whether to point all links to the upper-right quadrant

• xy_of_reference (tuple, optional) – Coordinate value in projected space of (0., 0.) Default is (0., 0.)

Returns:

A newly-created grid.

Return type:

VoronoiDelaunayGrid

Examples

>>> from numpy.random import rand
>>> from landlab.grid import VoronoiDelaunayGrid
>>> x, y = rand(25), rand(25)
>>> vmg = VoronoiDelaunayGrid(x, y)  # node_x_coords, node_y_coords
>>> vmg.number_of_nodes
25

property active_adjacent_corners_at_corner

Adjacent corners for each grid corner.

See also

active_adjacent_nodes_at_node

property active_face_dirs_at_corner

Return face directions into each corner.

See also

active_link_dirs_at_node

property all_corner_azimuths_map

Get azimuths from every corner to every other corner.

See also

all_node_azimuths_map

property all_corner_distances_map

Get distances from every corner to every other corner.

See also

all_node_distances_map

property angle_of_face_about_head

Find and return the angle of a face about the corner at the face head.

See also

angle_of_link_about_head

property boundary_corners

Get array of boundary corners.

See also

boundary_nodes

property cells_present_at_corner

A boolean array, False where a cell has a closed corner or is

See also

patches_present_at_node

property cells_present_at_face

A boolean array, False where a cell has a closed corner or is

See also

patches_present_at_link

property closed_boundary_corners

Get array of closed boundary corners.

See also

closed_boundary_nodes

property core_corners

Get array of core corners.

See also

core_nodes

property core_patches

Get array of core patches.

See also

core_cells

property corner_at_core_patch

Get array of corners associated with core patches.

See also

node_at_core_cell

property face_status_at_corner

property fixed_faces

Get array of fixed faces.

See also

fixed_links

property fixed_gradient_boundary_corner_anchor_corner

Returns the corner at the other end of the fixed face for a fixed

See also

fixed_gradient_boundary_node_anchor_node

property fixed_gradient_boundary_corner_fixed_face

An array of the fixed_faces connected to fixed gradient boundary

See also

fixed_gradient_boundary_node_fixed_link

property fixed_gradient_boundary_corners

Get array of fixed gradient boundary corners.

See also

fixed_gradient_boundary_nodes

property fixed_value_boundary_corners

Get array of fixed value boundary corners.

See also

fixed_value_boundary_nodes

classmethod from_dict(kwds)

Create grid from dictionary.

Parameters:

params (dictionary) – Dictionary of required parameters to create a model grid.

Examples

>>> from landlab import RasterModelGrid
>>> params = {"shape": (3, 4), "xy_spacing": 2}
>>> grid = RasterModelGrid.from_dict(params)
>>> grid.x_of_node
array([ 0.,  2.,  4.,  6.,  0.,  2.,  4.,  6.,  0.,  2.,  4.,  6.])
>>> grid.y_of_node
array([ 0.,  0.,  0.,  0.,  2.,  2.,  2.,  2.,  4.,  4.,  4.,  4.])

property number_of_cells_present_at_corner

Return the number of cells at a corner without a closed corner.

See also

number_of_patches_present_at_node

property number_of_cells_present_at_face

Return the number of cells at a face without a closed corner.

See also

number_of_patches_present_at_link

property number_of_core_corners

Number of core corners.

See also

number_of_core_nodes

property number_of_core_patches

Number of core patches.

See also

number_of_core_cells

property number_of_fixed_faces

Number of fixed faces.

See also

number_of_fixed_links

property open_boundary_corners

Get array of open boundary corners.

See also

open_boundary_nodes

property patch_area_at_corner

Cell areas in a ncorners-long array.

See also

cell_area_at_node

save(path, clobber=False)

Save a grid and fields.

This method uses pickle to save a Voronoi grid as a pickle file. At the time of coding, this is the only convenient output format for Voronoi grids, but support for netCDF is likely coming.

All fields will be saved, along with the grid.

The recommended suffix for the save file is ‘.grid’. This will be added to your save if you don’t include it.

This method is equivalent to save_grid, and load_grid can be used to load these files.

Caution: Pickling can be slow, and can produce very large files. Caution 2: Future updates to Landlab could potentially render old saves unloadable.

Parameters:

• path (str) – Path to output file.

• clobber (bool (defaults to false)) – Set to true to allow overwriting

Returns:

The name of the saved file (with the “.grid” extension).

Return type:

str

Examples

>>> from landlab import VoronoiDelaunayGrid
>>> import numpy as np

>>> grid = VoronoiDelaunayGrid(np.random.rand(20), np.random.rand(20))
>>> grid.save("mytestsave.grid")  
'mytestsave.grid'

property status_at_corner

Get array of the boundary status for each corner.

See also

status_at_node

property status_at_face

Get array of the status of all faces.

See also

status_at_link

property unit_vector_sum_xcomponent_at_corner

Get array of x-component of unit vector sums at each corner.

See also

unit_vector_sum_xcomponent_at_node

property unit_vector_sum_ycomponent_at_corner

Get array of y-component of unit vector sums at each corner.

See also

unit_vector_sum_ycomponent_at_node

create_grid(file_like, section=None)

Create grid, initialize fields, and set boundary conditions.

create_grid expects a dictionary with three keys: “grid”, “fields”, and “boundary_conditions”.

Dictionary Section “grid”

The value associated with the “grid” key should itself be a dictionary containing the name of a Landlab model grid type as its only key. The following grid types are valid:

• RasterModelGrid

• VoronoiDelaunayGrid

• HexModelGrid

• RadialModelGrid

• NetworkModelGrid

The value associated with the grid name key is a list containing the arguments. If any keyword arguments are passed, they should be passed as the last element of the list. For example the following code block is a yaml file indicating a RasterModelGrid with shape (4, 5) and xy-spacing of (3, 4).

grid:
  RasterModelGrid:
    - [4, 5]
    - xy_spacing: [3, 4]

These arguments and keyword arguments will be passed to the __init__ constructor of the specified model grid. Refer to the documentation for each grid to determine its requirements.

Dictionary Section “fields”

Fields can be created by reading from files or by creating synthetic values.

The value associated with the “fields” key is a nested set of dictionaries indicating where the fields are created, what the field names are, and how to create the fields. As part of a grid’s description, the value associated with the “fields” key must be a dictionary with keys indicating at which grid elements fields should be created (e.g. to create fields at node, use “node”).

The value associated with each “xxx” (i.e. “node”, “link”, “patch”, etc.) value is itself a dictionary indicating the name of the field and how it should be created. A field can either be created by reading from a file or creating synthetic values. The read_netcdf and read_esri_ascii functions, and the synthetic fields package are currently supported methods to create fields. These may be chained together (as is shown in the Example section below). If these functions do not meet your needs, we welcome contributions that extend the capabilities of this function.

An additional supported method, which can be chained together with either synthetic fields or fields read from a file, is units. The units function will set the units attribute of its corresponding field. If this optional function is not used, the resulting field will not be given any units.

The following example would use the plane function from the synthetic values package to create a node value for the field topographic__elevation. The plane function adds values to a Landlab model grid field that lie on a plane specified by a point and a normal vector. In the below example the plane goes through the point (1.0, 1.0, 1.0) and has a normal of (-2.0, -1.0, 1.0). The units function sets the units of elevation to meters.

grid:
  RasterModelGrid:
    - [4, 5]
    - xy_spacing: [3, 4]
    - fields:
        node:
          topographic__elevation:
            plane:
              - point: [1, 1, 1]
                normal: [-2, -1, 1]
            units:
                - units: "meters"

Dictionary Section “boundary_conditions”

The final portion of the input dictionary calls bound functions of the model grid to set boundary conditions. Any valid bound function can be called. The specified functions are provided in a list, and called in order. If required, multiple functions may be called.

Each entry to the list is a dictionary with a single key, the name of the bound function. The value associated with that key is a list of arguments and keyword arguments, similar in structure to those described above. As with the “fields” section, the “boundary_conditions” section must be described under its associated grid description.

For example, the following sets closed boundaries at all sides of the grid.

grid:
  RasterModelGrid:
    - [4, 5]
    - xy_spacing: [3, 4]
    - boundary_conditions:
      - set_closed_boundaries_at_grid_edges:
        - True
        - True
        - True
        - True

Parameters:

file_like (file_like or str) – Dictionary, contents of a dictionary as a string, a file-like object, or the path to a file containing a YAML dictionary.

Examples

>>> import numpy as np
>>> from landlab import create_grid
>>> np.random.seed(42)
>>> p = {
...     "grid": {
...         "RasterModelGrid": [
...             (4, 5),
...             {"xy_spacing": (3, 4)},
...             {
...                 "fields": {
...                     "node": {
...                         "spam": {
...                             "plane": [
...                                 {"point": (1, 1, 1), "normal": (-2, -1, 1)}
...                             ],
...                             "random": [
...                                 {"distribution": "uniform", "low": 1, "high": 4}
...                             ],
...                         }
...                     },
...                     "link": {
...                         "eggs": {
...                             "constant": [{"where": "ACTIVE_LINK", "value": 12}]
...                         }
...                     },
...                 }
...             },
...             {
...                 "boundary_conditions": [
...                     {
...                         "set_closed_boundaries_at_grid_edges": [
...                             True,
...                             True,
...                             True,
...                             True,
...                         ]
...                     }
...                 ]
...             },
...         ]
...     }
... }
>>> mg = create_grid(p, section="grid")
>>> mg.number_of_nodes
20
>>> "spam" in mg.at_node
True
>>> "eggs" in mg.at_link
True
>>> mg.x_of_node
array([  0.,   3.,   6.,   9.,  12.,
         0.,   3.,   6.,   9.,  12.,
         0.,   3.,   6.,   9.,  12.,
         0.,   3.,   6.,   9.,  12.])
>>> mg.status_at_node
array([4, 4, 4, 4, 4,
       4, 0, 0, 0, 4,
       4, 0, 0, 0, 4,
       4, 4, 4, 4, 4], dtype=uint8)
>>> np.round(mg.at_node["spam"].reshape(mg.shape), decimals=2)
array([[  0.12,   7.85,  13.2 ,  18.8 ,  23.47],
       [  3.47,   9.17,  17.6 ,  22.8 ,  29.12],
       [  7.06,  15.91,  21.5 ,  25.64,  31.55],
       [ 11.55,  17.91,  24.57,  30.3 ,  35.87]])

imshow_grid(grid, values, **kwds)

Prepare a map view of data over all nodes or cells in the grid.

Data is plotted as colored cells. If at=’node’, the surrounding cell is shaded with the value at the node at its center. If at=’cell’, the cell is shaded with its own value. Outer edges of perimeter cells are extrapolated. Closed elements are colored uniformly (default black, overridden with kwd ‘color_for_closed’); other open boundary nodes get their actual values.

values can be a field name, a regular array, or a masked array. If a masked array is provided, masked entries will be treated as if they were Landlab BC_NODE_IS_CLOSED. Used together with the color_for_closed=None keyword (i.e., “transparent”), this can allow for construction of overlay layers in a figure (e.g., only defining values in a river network, and overlaying it on another landscape).

Use matplotlib functions like xlim, ylim to modify your plot after calling imshow_grid, as desired.

This function happily works with both regular and irregular grids.

Parameters:

• grid (ModelGrid) – Grid containing the field to plot, or describing the geometry of the provided array.

• values (array_like, masked_array, or str) – Node or cell values, or a field name as a string from which to draw the data.

• at (str, {'node', 'cell'}) – Tells plotter where values are defined.

• plot_name (str, optional) – String to put as the plot title.

• var_name (str, optional) – Variable name, to use as a colorbar label.

• var_units (str, optional) – Units for the variable being plotted, for the colorbar.

• grid_units (tuple of str, optional) – Units for y, and x dimensions. If None, component will look to the gri property axis_units for this information. If no units are specified there, no entry is made.

• symmetric_cbar (bool) – Make the colormap symetric about 0.

• cmap (str) – Name of a colormap

• alpha (array-like or scalar or None, optional) – Set the transparency.

• limits (tuple of float) – Minimum and maximum of the colorbar.

• vmin (floats) – Alternatives to limits.

• vmax (floats) – Alternatives to limits.

• allow_colorbar (bool) – If True, include the colorbar.

• colorbar_label (str or None) – The string with which to label the colorbar.

• norm (matplotlib.colors.Normalize) – The normalizing object which scales data, typically into the interval [0, 1]. Ignore in most cases.

• shrink (float) – Fraction by which to shrink the colorbar.

• color_for_closed (str or None) – Color to use for closed elements (default ‘black’). If None, closed (or masked) elements will be transparent.

• color_for_background (color str or other color declaration, or None) – Color to use for closed elements (default None). If None, the background will be transparent, and appear white.

• show_elements (bool) – If True, and grid is a Voronoi, the faces will be plotted in black along with just the colour of the cell, defining the cell outlines (defaults False).

• output (None, string, or bool) – If None (or False), the image is sent to the imaging buffer to await an explicit call to show() or savefig() from outside this function. If a string, the string should be the path to a save location, and the filename (with file extension). The function will then call plt.savefig([string]) itself. If True, the function will call plt.show() itself once plotting is complete.

imshow_grid_at_node(grid, values, **kwds)

Prepare a map view of data over all nodes in the grid. Data is plotted as cells shaded with the value at the node at its center. Outer edges of perimeter cells are extrapolated. Closed elements are colored uniformly (default black, overridden with kwd ‘color_for_closed’); other open boundary nodes get their actual values.

values can be a field name, a regular array, or a masked array. If a masked array is provided, masked entries will be treated as if they were Landlab BC_NODE_IS_CLOSED. Used together with the color_at_closed=None keyword (i.e., “transparent”), this can allow for construction of overlay layers in a figure (e.g., only defining values in a river network, and overlaying it on another landscape).

Use matplotlib functions like xlim, ylim to modify your plot after calling imshow_grid, as desired.

Node coordinates are printed when a mouse button is pressed on a cell in the plot.

This function happily works with both regular and irregular grids.

Parameters:

• grid (ModelGrid) – Grid containing the field to plot, or describing the geometry of the provided array.

• values (array_like, masked_array, or str) – Node values, or a field name as a string from which to draw the data.

• plot_name (str, optional) – String to put as the plot title.

• var_name (str, optional) – Variable name, to use as a colorbar label.

• var_units (str, optional) – Units for the variable being plotted, for the colorbar.

• grid_units (tuple of str, optional) – Units for y, and x dimensions. If None, component will look to the grid property axis_units for this information. If no units are specified there, no entry is made.

• symmetric_cbar (bool) – Make the colormap symetric about 0.

• cmap (str) – Name of a colormap

• limits (tuple of float) – Minimum and maximum of the colorbar.

• vmin (floats) – Alternatives to limits.

• vmax (floats) – Alternatives to limits.

• allow_colorbar (bool) – If True, include the colorbar.

• colorbar_label (str or None) – The string with which to label the colorbar.

• norm (matplotlib.colors.Normalize) – The normalizing object which scales data, typically into the interval [0, 1]. Ignore in most cases.

• shrink (float) – Fraction by which to shrink the colorbar.

• color_for_closed (str or None) – Color to use for closed nodes (default ‘black’). If None, closed (or masked) nodes will be transparent.

• color_for_background (color str or other color declaration, or None) – Color to use for closed elements (default None). If None, the background will be transparent, and appear white.

• show_elements (bool) – If True, and grid is a Voronoi, the faces will be plotted in black along with just the colour of the cell, defining the cell outlines (defaults False).

• output (None, string, or bool) – If None (or False), the image is sent to the imaging buffer to await an explicit call to show() or savefig() from outside this function. If a string, the string should be the path to a save location, and the filename (with file extension). The function will then call plt.savefig([string]) itself. If True, the function will call plt.show() itself once plotting is complete.

imshowhs_grid(grid, values, **kwds)

Prepare a map view of data over all nodes in the grid using a hillshade topography map in the background.

Data are plotted as cells shaded with the value at the node at its center. Outer edges of perimeter cells are extrapolated. Closed elements are colored uniformly (with the color being controlled by the color_for_closed keyword); other open boundary nodes get their actual values.

values can be a field name, a regular array, or a masked array. If a masked array is provided, masked entries are treated as if they were landlab CLOSED nodes. If closed nodes are also set to be transparent (i.e. color_for_closed=None), this can allow for the construction of overlying layers in a figure (e.g., only defining values in a river network, and then overlaying it on another landscape).

Use matplotlib functions like xlim, ylim to modify your plot after calling imshowhs_grid, as desired.

Node coordinates are printed when a mouse button is pressed on a cell in the plot.

Note

For now, this function only works with RasterModelGrid.

Parameters:

• grid (ModelGrid) – Grid containing the field to plot, or describing the geometry of the provided array.

• values (array_like, masked_array, or str) – Node values, or a field name as a string from which to draw the data.

• plot_name (str, optional) – String to put as the plot title.

• var_name (str, optional) – Variable name, to use as a colorbar label.

• var_name_two (str, optional) – Variable name of second layer, to use as a colorbar label.

• var_units (str, optional) – Units for the variable being plotted, for the colorbar.

• grid_units (tuple of str, optional) – Units for y, and x dimensions. If None, component will look to the grid property axis_units for this information. If no units are specified there, no entry is made.

• symmetric_cbar (bool) – Make the colormap symmetric about 0.

• cmap (str) – Name of a colormap

• limits (tuple of float) – Minimum and maximum of the colorbar.

• vmin (floats) – Alternatives to limits.

• vmax (floats) – Alternatives to limits.

• norm (matplotlib.colors.Normalize) – The normalizing object which scales data, typically into the interval [0, 1]. Ignore in most cases.

• ticks_km (bool, optional) – Display ticks in km instead of m

• allow_colorbar (bool) – If True, include the colorbar.

• shrink (float) – Fraction by which to shrink the colorbar.

• color_for_closed (str or None) – Color to use for closed nodes (default None). If None, (or masked) nodes will be transparent.

• color_for_background (color str or other color declaration, or None) – Color to use for closed elements (default None). If None, the background will be transparent, and appear white.

• output (None, string, or bool) – If None (or False), the image is sent to the imaging buffer to await an explicit call to show() or savefig() from outside this function. If a str, the string should be the path to a save location, and the filename (with file extension). The function will then call plt.savefig([string]) itself. If True, the function will call plt.show() itself once plotting is complete.

• fontweight_xlabel (str, optional) – Weight of x label. The default is ‘bold’.

• fontweight_ylabel (str, optional) – Weight of y label. The default is ‘bold’.

• plot_type ({"DEM", "Hillshade", "Drape1", "Drape2"}, optional) –

  The type of plot that will be plotted.

  • ’DEM’: Display a digital elevation map underlain by a shaded relief, based on the same DEM (‘topographic__elevation’)

  • ’Hillshade’: Display the shaded relief, of the provided DEM (‘topographic__elevation’)

  • ’Drape1’: Display any kind of provided layer on top of a shaded relief provided in the ‘topographic__elevation’ field

  • ’Drape2’: Display two layers on top of a shaded relief provided in the ‘topographic__elevation’ field

  The default is “DEM”.

• drape1 (array_like, masked_array) – Node values to plot on top of a hillshade map. The default is None.

• drape2 (array_like, masked_array) – Node values to plot on top of drape1 and a hillshade map. The default is None.

• cmap2 (str) – Name of a colormap for drape 2. The default is None.

• vertical_exa (float, optional) – Vertical exaggeration of hillshade map. The default is None.

• azdeg (float, optional) – Azimuth of the light source. The default is 315.

• altdeg (float, optional) – Elevation of the light source. The default is 65.

• thres_drape1 (float, optional) – Threshold below which drape1 is made transparent. The default is None.

• alpha (float (0-1), optional) – Transparency of DEM/Drape1 . The default is None.

• thres_drape2 (float, optional) – Threshold below which drape2 is made transparent. The default is None.

• alpha2 (float (0-1), optional) – Transparency of Drape2 . The default is None.

• add_double_colorbar (bool, optional) – Add a double colorbar when two drapes are plotted. The default is False.

• plt_contour (bool, optional) – Add contour lines to elevation plot. The default is False.

• contour_nb (int, optional) – Number of contour lines. The default is 50.

• default_fontsize (float, optional) – Default font size for plot labels. The default is 10.

• cbar_height (percentage, optional) – Height of colorbar as a percentage of the figure. The default is 5%.

• cbar_width (percentage, optional) – Width of colorbar in percentage of figure. The default is 30%.

• cbar_or (str, optional) – Orientation of colorbar. The default is “horizontal”.

• cbar_loc (str, optional) – Location of colorbar. The default is “lower right”.

• bbox_to_anchor (vector, optional) – Bounding box to anchor. The default is (0, 0, 1, 1).

• cbar_ticks_position (str, optional) – location of colorbar ticks (below or on top of the colorbar). The default is “top”.

• cbar_ticks_position2 (str, optional) – location of colorbar ticks for colorbar of Drape2 (below or on top of the colorbar). The default is “bottom”.

• colorbar_label_y (float, optional) – location of colorbar label with respect to the colorbar in y direction. The default is -40.

• colorbar_label_x (float , optional) – location of colorbar label with respect to the colorbar in x direction. The default is 0.5.

• cbar_tick_size (float, optional) – Colorbar tick size. The default is 10.

• cbar_label_color (str, optional) – Colorbar tick color. The default is ‘black’.

• cbar_label_fontweight (str, optional) – Colorbar font weight. The default is ‘bold’.

• add_label_bbox (bool, optional) – Add a bbox surrounding the colorbar label. The default is False.

• y_label_offSet_var_1 (float, optional) – Offset of ylabel on colorbar of first variable in plot with two overlaying plots. The default is 3.0.

• y_label_offSet_var_2 (float, optional) – Offset of ylabel on colorbar of first variable in plot with two overlaying plots. The default is -1.25.

Returns:

Axis of the plot if output keyword is True.

Return type:

ax

imshowhs_grid_at_node(grid, values, **kwds)

Prepare a map view of data over all nodes in the grid using a hillshade topography map in the background.

Data are plotted as cells shaded with the value at the node at its center. Outer edges of perimeter cells are extrapolated. Closed elements are colored uniformly (with the color being controlled by the color_for_closed keyword); other open boundary nodes get their actual values.

values can be a field name, a regular array, or a masked array. If a masked array is provided, masked entries are treated as if they were landlab CLOSED nodes. If closed nodes are also set to be transparent (i.e. color_for_closed=None), this can allow for the construction of overlying layers in a figure (e.g., only defining values in a river network, and then overlaying it on another landscape).

Use matplotlib functions like xlim, ylim to modify your plot after calling imshowhs_grid, as desired.

Node coordinates are printed when a mouse button is pressed on a cell in the plot.

Note

For now, this function only works with RasterModelGrid.

Parameters:

• grid (ModelGrid) – Grid containing the field to plot, or describing the geometry of the provided array.

• values (array_like, masked_array, or str) – Node values, or a field name as a string from which to draw the data.

• plot_name (str, optional) – String to put as the plot title.

• var_name (str, optional) – Variable name, to use as a colorbar label.

• var_name_two (str, optional) – Variable name of second layer, to use as a colorbar label.

• var_units (str, optional) – Units for the variable being plotted, for the colorbar.

• grid_units (tuple of str, optional) – Units for y, and x dimensions. If None, component will look to the grid property axis_units for this information. If no units are specified there, no entry is made.

• symmetric_cbar (bool) – Make the colormap symmetric about 0.

• cmap (str) – Name of a colormap

• limits (tuple of float) – Minimum and maximum of the colorbar.

• vmin (floats) – Alternatives to limits.

• vmax (floats) – Alternatives to limits.

• norm (matplotlib.colors.Normalize) – The normalizing object which scales data, typically into the interval [0, 1]. Ignore in most cases.

• ticks_km (bool, optional) – Display ticks in km instead of m

• allow_colorbar (bool) – If True, include the colorbar.

• shrink (float) – Fraction by which to shrink the colorbar.

• color_for_closed (str or None) – Color to use for closed nodes (default None). If None, (or masked) nodes will be transparent.

• color_for_background (color str or other color declaration, or None) – Color to use for closed elements (default None). If None, the background will be transparent, and appear white.

• output (None, string, or bool) – If None (or False), the image is sent to the imaging buffer to await an explicit call to show() or savefig() from outside this function. If a str, the string should be the path to a save location, and the filename (with file extension). The function will then call plt.savefig([string]) itself. If True, the function will call plt.show() itself once plotting is complete.

• fontweight_xlabel (str, optional) – Weight of x label. The default is ‘bold’.

• fontweight_ylabel (str, optional) – Weight of y label. The default is ‘bold’.

• plot_type ({"DEM", "Hillshade", "Drape1", "Drape2"}, optional) –

  The type of plot that will be plotted.

  • ’DEM’ (the default): Display a digital elevation map underlain by a shaded relief, based on the same DEM (‘topographic__elevation’)

  • ’Hillshade’: Display the shaded relief, of the provided DEM (‘topographic__elevation’)

  • ’Drape1’: Display any kind of provided layer on top of a shaded relief provided in the ‘topographic__elevation’ field

  • ’Drape2’: Display two layers on top of a shaded relief provided in the ‘topographic__elevation’ field

  The default is “DEM”.

• drape1 (array_like, masked_array) – Node values to plot on top of a hillshade map. The default is None.

• drape2 (array_like, masked_array) – Node values to plot on top of drape1 and a hillshade map. The default is None.

• cmap2 (str) – Name of a colormap for drape 2. The default is None.

• vertical_exa (float, optional) – Vertical exaggeration of hillshade map. The default is None.

• azdeg (float, optional) – Azimuth of the light source. The default is 315.

• altdeg (float, optional) – Elevation of the light source. The default is 65.

• thres_drape1 (float, optional) – Threshold below which drape1 is made transparent. The default is None.

• alpha (float (0-1), optional) – Transparency of DEM/Drape1 . The default is None.

• thres_drape2 (float, optional) – Threshold below which drape2 is made transparent. The default is None.

• alpha2 (float (0-1), optional) – Transparency of Drape2 . The default is None.

• add_double_colorbar (bool, optional) – Add a double colorbar when two drapes are plotted. The default is False.

• plt_contour (bool, optional) – Add contour lines to elevation plot. The default is False.

• contour_nb (int, optional) – Number of contour lines. The default is 50.

• default_fontsize (float, optional) – Default font size for plot labels. The default is 10.

• cbar_height (percentage, optional) – Height of colorbar as a percentage of the figure. The default is 5%.

• cbar_width (percentage, optional) – Width of colorbar in percentage of figure. The default is 30%.

• cbar_or (str, optional) – Orientation of colorbar. The default is “horizontal”.

• cbar_loc (str, optional) – Location of colorbar. The default is “lower right”.

• bbox_to_anchor (vector, optional) – Bounding box to anchor. The default is (0, 0, 1, 1).

• cbar_ticks_position (str, optional) – Location of colorbar ticks (below or on top of the colorbar). The default is “top”.

• cbar_ticks_position2 (str, optional) – Location of colorbar ticks for colorbar of Drape2 (below or on top of the colorbar). The default is “bottom”.

• colorbar_label_y (float, optional) – Location of colorbar label with respect to the colorbar in y direction. The default is -40.

• colorbar_label_x (float , optional) – Location of colorbar label with respect to the colorbar in x direction. The default is 0.5.

• cbar_tick_size (float, optional) – Colorbar tick size. The default is 10.

• cbar_label_color (str, optional) – Colorbar tick color. The default is ‘black’.

• cbar_label_fontweight (str, optional) – Colorbar font weight. The default is ‘bold’.

• add_label_bbox (bool, optional) – Add a bbox surrounding the colorbar label. The default is False.

• y_label_offSet_var_1 (float, optional) – Offset of ylabel on colorbar of first variable in plot with two overlaying plots. The default is 3.0.

• y_label_offSet_var_2 (float, optional) – Offset of ylabel on colorbar of first variable in plot with two overlaying plots. The default is -1.25.

Returns:

Axis of the plot if output keyword is True.

Return type:

ax

load_params(file_like)

Load parameters from a YAML style file.

Parameters:

file_like (file_like or str) – Contents of a parameter file, a file-like object, or the path to a parameter file.

Returns:

Parameters as key-value pairs.

Return type:

dict

Examples

>>> from landlab.core import load_params
>>> contents = '''
... start: 0.
... stop: 10.
... step: 2.
... '''
>>> params = load_params(contents)
>>> isinstance(params, dict)
True
>>> params["start"], params["stop"], params["step"]
(0.0, 10.0, 2.0)