API for landlab.grid.radial#

Python implementation of RadialModelGrid, a grid class used to create and manage structured Voronoi-Delaunay grids for 2D numerical models.

Do NOT add new documentation here. Grid documentation is now built in a semi- automated fashion. To modify the text seen on the web, edit the files docs/text_for_[gridfile].py.txt.

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='-')[source]#

Bases: DualRadialGraph, ModelGrid

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.)
... )
>>> 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.])
BAD_INDEX = -1#

Indicates a node is bad index.

Indicates a link is active, and can carry flux

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

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.

__getitem__(name)#

Get the collection of fields from the named group.

__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='-')[source]#

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

Graph.active_adjacent_nodes_at_node

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_face_dirs_at_corner#

1=incoming flux, -1=outgoing

See also

Graph.active_link_dirs_at_node

Type

Link flux directions at each corner

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

1=incoming flux, -1=outgoing flux, 0=no flux. Note that inactive links receive zero, 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 rows by max number of links per node. A zero indicates no link at this position.

Return type

(NODES, LINKS) ndarray of int

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 3))
>>> 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,  0,  0,  0],
       [ 0,  0,  0,  0], [-1, -1,  0,  1], [ 0,  0,  1,  0],
       [ 0,  0,  0,  0], [-1, -1,  0,  1], [ 0,  0,  1,  0],
       [ 0,  0,  0,  0], [ 0,  0,  0,  1], [ 0,  0,  0,  0]],
       dtype=int8)
Type

Link flux directions at each node

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])
add_empty(name, at='node', units='-', clobber=False)#

Create and add an uninitialized array of values to the field.

Create a new array of the data field size, without initializing entries, and add it to the field as name. The units keyword gives the units of the new fields as a string. Remaining keyword arguments are the same as that for the equivalent numpy function.

This method is not valid for the group grid.

Parameters
  • name (str) – Name of the new field to add.

  • at (str, optional) – Grid location to store values. If not given, values are assumed to be on node.

  • units (str, optional) – Optionally specify the units of the field.

  • clobber (bool, optional) – Raise an exception if adding to an already existing field.

Returns

A reference to the newly-created array.

Return type

numpy.ndarray

See also

numpy.empty

See for a description of optional keywords.

GraphFields.empty

Equivalent method that does not initialize the new array.

GraphFields.zeros

Equivalent method that initializes the data to 0.

add_field(name, value_array, at='node', units='-', copy=False, clobber=False)#

Add an array of values to the field.

Add an array of data values to a collection of fields and associate it with the key, name. Use the copy keyword to, optionally, add a copy of the provided array.

In the case of adding to the collection grid, the added field is a numpy scalar rather than a numpy array.

Parameters
  • name (str) – Name of the new field to add.

  • value_array (numpy.array) – Array of values to add to the field.

  • at (str, optional) – Grid location to store values. If not given, values are assumed to be on node.

  • units (str, optional) – Optionally specify the units of the field.

  • copy (bool, optional) – If True, add a copy of the array to the field. Otherwise save add a reference to the array.

  • clobber (bool, optional) – Raise an exception if adding to an already existing field.

Returns

The data array added to the field. Depending on the copy keyword, this could be a copy of value_array or value_array itself.

Return type

numpy.ndarray

Raises

ValueError – If value_array has a size different from the field.

Examples

>>> import numpy as np
>>> from landlab.field import GraphFields
>>> field = GraphFields()
>>> field.new_field_location("node", 4)
>>> values = np.ones(4, dtype=int)
>>> field.add_field("topographic__elevation", values, at="node")
array([1, 1, 1, 1])

A new field is added to the collection of fields. The saved value array is the same as the one initially created.

>>> field.at_node["topographic__elevation"] is values
True

If you want to save a copy of the array, use the copy keyword. In addition, adding values to an existing field will remove the reference to the previously saved array. The clobber=False keyword changes this behavior to raise an exception in such a case.

>>> field.add_field(
...     "topographic__elevation", values, at="node", copy=True, clobber=True
... )
array([1, 1, 1, 1])
>>> field.at_node["topographic__elevation"] is values
False
>>> field.add_field(
...     "topographic__elevation", values, at="node", clobber=False
... ) 
Traceback (most recent call last):
FieldError: topographic__elevation
add_full(*args, **kwds)#

Create and add an array of values, fill with fill_value.

Parameters
  • name (str) – Name of the new field to add.

  • fill_value (scalar) – Fill value.

  • at (str, optional) – Grid location to store values. If not given, values are assumed to be on node.

  • units (str, optional) – Optionally specify the units of the field.

  • copy (bool, optional) – If True, add a copy of the array to the field. Otherwise save add a reference to the array.

  • clobber (bool, optional) – Raise an exception if adding to an already existing field.

Returns

A reference to the newly-created array.

Return type

numpy.ndarray

add_ones(name, at='node', units='-', clobber=False)#

Create and add an array of values, initialized to 1, to the field.

Create a new array of the data field size, filled with ones, and add it to the field as name. The units keyword gives the units of the new fields as a string. Remaining keyword arguments are the same as that for the equivalent numpy function.

This method is not valid for the group grid.

Parameters
  • name (str) – Name of the new field to add.

  • at (str, optional) – Grid location to store values. If not given, values are assumed to be on node.

  • units (str, optional) – Optionally specify the units of the field.

  • clobber (bool, optional) – Raise an exception if adding to an already existing field.

Returns

A reference to the newly-created array.

Return type

numpy.ndarray

See also

numpy.ones

See for a description of optional keywords.

GraphFields.add_empty

Equivalent method that does not initialize the new array.

GraphFields.add_zeros

Equivalent method that initializes the data to 0.

Examples

Add a new, named field to a collection of fields.

>>> from landlab.field import GraphFields
>>> field = GraphFields()
>>> field.new_field_location('node', 4)
>>> field.add_ones("topographic__elevation", at="node")
array([ 1.,  1.,  1.,  1.])
>>> list(field.keys('node'))
['topographic__elevation']
>>> field['node']['topographic__elevation']
array([ 1.,  1.,  1.,  1.])
>>> field.at_node['topographic__elevation']
array([ 1.,  1.,  1.,  1.])
add_zeros(name, at='node', units='-', clobber=False)#

Create and add an array of values, initialized to 0, to the field.

Create a new array of the data field size, filled with zeros, and add it to the field as name. The units keyword gives the units of the new fields as a string. Remaining keyword arguments are the same as that for the equivalent numpy function.

Parameters
  • name (str) – Name of the new field to add.

  • at (str, optional) – Grid location to store values. If not given, values are assumed to be on node.

  • units (str, optional) – Optionally specify the units of the field.

  • clobber (bool, optional) – Raise an exception if adding to an already existing field.

Returns

A reference to the newly-created array.

Return type

array

See also

numpy.zeros

See for a description of optional keywords.

GraphFields.add_empty

Equivalent method that does not initialize the new array.

GraphFields.add_ones

Equivalent method that initializes the data to 1.

property adjacent_corners_at_corner#

Get adjacent corners.

See also

Graph.adjacent_nodes_at_node

property adjacent_faces_at_face#
property adjacent_nodes_at_node#

Get adjacent nodes.

Examples

>>> from landlab.graph import Graph

First, a simple example with no diagonals.

>>> node_x, node_y = [0, 0, 0, 1, 1, 1, 2, 2, 2], [0, 1, 2, 0, 1, 2, 0, 1, 2]
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8))
>>> graph = Graph((node_y, node_x), links=links, sort=True)
>>> graph.adjacent_nodes_at_node
array([[ 1,  3, -1, -1],
       [ 2,  4,  0, -1],
       [ 5,  1, -1, -1],
       [ 4,  6,  0, -1],
       [ 5,  7,  3,  1],
       [ 8,  4,  2, -1],
       [ 7,  3, -1, -1],
       [ 8,  6,  4, -1],
       [ 7,  5, -1, -1]])

Next, we add the diagonal from node 0 to node 4.

>>> node_x, node_y = [0, 0, 0, 1, 1, 1, 2, 2, 2], [0, 1, 2, 0, 1, 2, 0, 1, 2]
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8),
...          (0, 4))
>>> graph = Graph((node_y, node_x), links=links, sort=True)
>>> graph.adjacent_nodes_at_node
array([[ 1,  4,  3, -1, -1],
       [ 2,  4,  0, -1, -1],
       [ 5,  1, -1, -1, -1],
       [ 4,  6,  0, -1, -1],
       [ 5,  7,  3,  0,  1],
       [ 8,  4,  2, -1, -1],
       [ 7,  3, -1, -1, -1],
       [ 8,  6,  4, -1, -1],
       [ 7,  5, -1, -1, -1]])
property all_corner_azimuths_map#

Get azimuths from every corner to every other corner.

See also

Graph.all_node_azimuths_map

property all_corner_distances_map#

Get distances from every corner to every other corner.

See also

Graph.all_node_distances_map

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. / 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_at_corner#
property angle_at_node#
property angle_of_face#

Get the angle of each face.

See also

Graph.angle_of_link

property angle_of_face_about_head#

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

See also

Graph.angle_of_link_about_head

Get the angle of each link.

Examples

>>> import numpy as np
>>> from landlab.graph import Graph
>>> node_x, node_y = ([0, 1, 2, 0, 1, 2],
...                   [0, 0, 0, 1, 1, 1])
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5))
>>> graph = Graph((node_y, node_x), links=links)
>>> graph.angle_of_link * 180. / np.pi
array([  0.,   0.,  90.,  90.,  90.,   0.,   0.])

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.])
property angle_spacing_of_ring#
property area_of_cell#

Get the area of each cell.

See also

Graph.area_of_patch

property area_of_patch#

Get the area of each patch.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1, 2, 2, 2]
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8))
>>> patches = ((0, 3, 5, 2), (1, 4, 6, 3))
>>> graph = Graph((node_y, node_x), links=links, patches=patches)
>>> graph.area_of_patch
array([ 1.,  1.])
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)[source]#

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 = {}#
property at_layer#

EventLayers for each cell.

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., 2.))
>>> 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_corners#

Get array of boundary corners.

See also

Graph.boundary_nodes

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., 2.))
>>> 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.

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

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.)
True
>>> np.allclose(x_grad, 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.)
>>> z = mg.x_of_node * np.tan(60. * np.pi / 180.)
>>> mg.calc_hillshade_at_node(elevs=z, alt=30., az=210.)
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 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((4, 5))
>>> z = mg.node_x
>>> slopes = mg.calc_slope_at_node(elevs=z)
>>> np.allclose(slopes, 45. / 180. * 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.)
True
>>> np.allclose(cmp[0], 0.)
True
>>> np.allclose(cmp[1], - np.pi / 4.)
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.)
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. / 4.
>>> 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 cell_at_node#
property cells_at_corner#

Get the cells that touch each corner.

See also

Graph.patches_at_node

property cells_at_face#

Get the cells on either side of each face.

See also

Graph.patches_at_link

property cells_present_at_corner#

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

See also

Graph.patches_present_at_node

property cells_present_at_face#

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

See also

Graph.patches_present_at_link

property closed_boundary_corners#

Get array of closed boundary corners.

See also

Graph.closed_boundary_nodes

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_corners#

Get array of core corners.

See also

Graph.core_nodes

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])
property core_patches#

Get array of core patches.

See also

Graph.core_cells

property corner_at_core_patch#

Get array of corners associated with core patches.

See also

Graph.node_at_core_cell

property corner_at_face_head#

Get corners at face head.

See also

Graph.node_at_link_head

property corner_at_face_tail#

Get corners at face tail.

See also

Graph.node_at_link_tail

property corner_at_patch#
property corner_x#
property corner_y#
property corners#

Get identifier for each corner.

See also

Graph.nodes

property corners_at_cell#

Get the corners that define a cell.

See also

Graph.nodes_at_patch

property corners_at_face#

Get corners at either end of faces.

See also

Graph.nodes_at_link

property corners_per_ring#
property default_group#

Return the name of the group into which fields are put by default.

delete_field(loc, name)#

Erases an existing field.

Parameters
  • loc (str) – Name of the group.

  • name (str) – Name of the field.

Raises

KeyError – If the named field does not exist.

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'] = np.array([-1., -2., -1.,
...                                 -2., -3., -4., -5.,
...                                 -1., -2., -1.,
...                                 -1., -2., -3., -4.,
...                                 -1., -2., -1.])
>>> 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]])
property ds#
property dual#
empty(*args, **kwds)#

Uninitialized array whose size is that of the field.

Return a new array of the data field size, without initializing entries. Keyword arguments are the same as that for the equivalent numpy function.

Parameters

group (str) – Name of the group.

See also

numpy.empty

See for a description of optional keywords.

GraphFields.ones

Equivalent method that initializes the data to 1.

GraphFields.zeros

Equivalent method that initializes the data to 0.

Examples

>>> from landlab.field import GraphFields
>>> field = GraphFields()
>>> field.new_field_location("node", 4)
>>> field.empty("node") 
array([  2.31584178e+077,  -2.68156175e+154,   9.88131292e-324,
... 2.78134232e-309]) # Uninitialized memory

Note that a new field is not added to the collection of fields.

>>> list(field.keys("node"))
[]
property event_layers#

EventLayers for each cell.

property face_dirs_at_corner#

Get directions of faces touching a corner.

See also

Graph.link_dirs_at_node

property face_status_at_corner#
property faces_at_cell#

Get the faces that define a cell.

See also

Graph.links_at_patch

property faces_at_corner#

Get faces touching a corner.

See also

Graph.links_at_node

field_units(field, at=None)#

Get units for a field.

Returns the unit string associated with the data array in group and field.

Parameters
  • field (str) – Name of the field withing group.

  • at (str, optional) – Name of the group.

Returns

The units of the field.

Return type

str

Raises

KeyError – If either field or group does not exist.

field_values(field, at=None)#

Return the values of a field.

Given a group and a field, return a reference to the associated data array.

Parameters
  • field (str) – Name of the field within group.

  • at (str, optional) – Name of the group.

Returns

The values of the field.

Return type

array

Raises
  • landlab.field.errors.GroupError – If group does not exist

  • landlab.field.errors.FieldError – If field does not exist

Examples

Create a group of fields called node.

>>> from landlab.field import GraphFields
>>> fields = GraphFields()
>>> fields.new_field_location("node", 4)

Add a field, initialized to ones, called topographic__elevation to the node group. The field_values method returns a reference to the field’s data.

>>> _ = fields.add_ones("topographic__elevation", at="node")
>>> fields.field_values("topographic__elevation", at="node")
array([ 1.,  1.,  1.,  1.])

Raise FieldError if field does not exist in group.

>>> fields.field_values("planet_surface__temperature", at="node")
...     
Traceback (most recent call last):
FieldError: planet_surface__temperature

If group does not exists, raise GroupError.

>>> fields.field_values("topographic__elevation", at="cell")
...     
Traceback (most recent call last):
GroupError: cell
fields(include='*', exclude=None)#

List of fields held by the grid.

The returned field names are returned as their canonical names. This 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_faces#

Get array of fixed faces.

See also

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

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

Graph.fixed_gradient_boundary_node_fixed_link

property fixed_gradient_boundary_corners#

Get array of fixed gradient boundary corners.

See also

Graph.fixed_gradient_boundary_nodes

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

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

Get array of fixed links.

Examples

>>> from landlab import NodeStatus, RasterModelGrid
>>> grid = RasterModelGrid((3, 4))
>>> grid.status_at_node 
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 
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_corners#

Get array of fixed value boundary corners.

See also

Graph.fixed_value_boundary_nodes

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])
freeze()#

Freeze the graph by making arrays read-only.

classmethod from_dataset(dataset)[source]#
classmethod from_dict(kwds)[source]#

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.])
classmethod from_netcdf(fname)#
property frozen#
property groups#

List of group names.

Returns

Names of field groupings.

Return type

set

has_field(field, at=None)#

Check if a field is in a group.

Parameters
  • field (str) – Name of the field.

  • at (str, optional) – Name of the group.

Returns

True if the group contains the field, otherwise False.

Return type

bool

Examples

Check if the field named topographic__elevation is contained in a group.

>>> from landlab.field import GraphFields
>>> fields = GraphFields()
>>> fields.new_field_location("node", 12)
>>> _ = fields.add_ones("topographic__elevation", at="node")
>>> fields.has_field("topographic__elevation", at="node")
True
>>> fields.has_field("topographic__elevation", at="cell")
False
>>> fields = GraphFields()
>>> fields.new_field_location("node", 12)
>>> _ = fields.add_ones("topographic__elevation", at="node")
>>> fields.has_field("node", "topographic__elevation")
True
>>> fields.has_field("cell", "topographic__elevation")
False
has_group(name)#

Check if a group exists.

Parameters

name (str) – Name of the group.

Returns

True if the field contains group, otherwise False.

Return type

bool

Examples

Check if the field has the groups named node or cell.

>>> from landlab.field import GraphFields
>>> fields = GraphFields()
>>> fields.new_field_location('node', 12)
>>> fields.has_group('node')
True
>>> fields.has_group('cell')
False
imshow(*args, **kwds)#

Plot a data field.

This is a wrapper for plot.imshow_grid, and can take the same keywords. See that function for full documentation.

Parameters

values (str, or array-like) – Name of a field or an array of values to plot.

See also

landlab.plot.imshow_grid

LLCATS

GINF

keys(group)#

Return the field names in a group.

Parameters

group (str) – Group name.

Returns

Names of fields held in the given group.

Return type

list

Examples

>>> from landlab.field import GraphFields
>>> fields = GraphFields()
>>> fields.new_field_location("node", 4)
>>> list(fields.keys("node"))
[]
>>> _ = fields.add_empty("topographic__elevation", at="node")
>>> list(fields.keys("node"))
['topographic__elevation']
property length_of_face#

Get the length of faces.

See also

Graph.length_of_link

Get the length of links.

Examples

>>> import numpy as np
>>> from landlab.graph import UniformRectilinearGraph
>>> graph = UniformRectilinearGraph((2, 3), spacing=(1, 2))
>>> graph.length_of_link
array([ 2.,  2.,  1.,  1.,  1.,  2.,  2.])

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'] = np.array([-1., -2., -1.,
...                                 -2., -3., -4., -5.,
...                                 -1., -2., -1.,
...                                 -1., -2., -3., -4.,
...                                 -1., -2., -1.])
>>> 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)

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'] = np.array([-1., -2., -1.,
...                                 -2., -3., -4., -5.,
...                                 -1., -2., -1.,
...                                 -1., -2., -3., -4.,
...                                 -1., -2., -1.])
>>> 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)

Get directions of links touching a node.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1, 2, 2, 2]
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8))
>>> graph = Graph((node_y, node_x), links=links)
>>> graph.link_dirs_at_node 
array([[-1, -1,  0,  0], [-1, -1,  1,  0], [-1,  1,  0,  0],
       [-1, -1,  1,  0], [-1, -1,  1,  1], [-1,  1,  1,  0],
       [-1,  1,  0,  0], [-1,  1,  1,  0], [ 1,  1,  0,  0]],
      dtype=int8)

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

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

Get links touching a node.

Examples

>>> from landlab.graph import Graph
>>> node_x = [0, 1, 2, 0, 1, 2, 0, 1, 2]
>>> node_y = [0, 0, 0, 1, 1, 1, 2, 2, 2]
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8))
>>> graph = Graph((node_y, node_x), links=links)
>>> graph.links_at_node 
array([[ 0,  2, -1, -1], [ 1,  3,  0, -1], [ 4,  1, -1, -1],
       [ 5,  7,  2, -1], [ 6,  8,  5,  3], [ 9,  6,  4, -1],
       [10,  7, -1, -1], [11, 10,  8, -1], [11,  9, -1, -1]])

Get the links that define a patch.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1, 2, 2, 2]
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8))
>>> patches = ((0, 3, 5, 2), (1, 4, 6, 3))
>>> graph = Graph((node_y, node_x), links=links, patches=patches, sort=True)
>>> graph.links_at_patch
array([[3, 5, 2, 0],
       [4, 6, 3, 1]])
classmethod load(source)#

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'] = np.array([-1., -2., -1.,
...                                  0.,  0.,  0.,  0.,
...                                 -1., -2., -1.,
...                                  0.,  0.,  0.,  0.,
...                                 -1., -2., -1.])
>>> 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 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'] = np.array([-1., -2., -1.,
...                                 -2., -3., -4., -5.,
...                                 -1., -2., -1.,
...                                 -1., -2., -3., -4.,
...                                 -1., -2., -1.])
>>> 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 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 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 (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 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., -1.,  1., -1., -1., -1., -1.])

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 data defined on links to nodes.

Given a variable defined on links, breaks it into x and y components and assigns values to nodes by averaging each node’s attached links.

Parameters

q (ndarray of floats (1D, length = number of links in grid)) – Variable defined on links

Returns

x and y components of variable mapped to nodes (1D, length = number of nodes)

Return type

ndarray, ndarray

See also

_create_link_unit_vectors

sets up unit vectors at links and unit-vector sums at nodes

Notes

THIS ALGORITHM IS NOT CORRECT AND NEEDS TO BE CHANGED!

The concept here is that q contains a vector variable that is defined at each link. The magnitude is given by the value of q, and the direction is given by the orientation of the link, as described by its unit vector.

To map the link-vector values to the nodes, we break the values into x- and y-components according to each link’s unit vector. The x-component of q at a node is a weighted sum of the x-components of the links that are attached to that node. A good way to appreciate this is by example. Consider a 3x4 raster grid:

8--14---9--15--10--16--11
|       |       |       |
4       5       6       7
|       |       |       |
4--11---5---12--6---13--7
|       |       |       |
0       1       2       3
|       |       |       |
0---8---1---9---2--10---3

Imagine that for each node, we were to add up the unit vector components for each connected link; in other words, add up all the x components of the unit vectors associated with each link, and add up all the y components. Here’s what that would look like for the above grid (“vsx” and “vsy” stand for “vector sum x” and “vector sum y”):

  • Corner nodes (0, 3, 8, 11): vsx = 1, vsy = 1

  • Bottom and top nodes (1-2, 9-10): vsx = 2, vsy = 1

  • Left and right nodes (4, 7): vsx = 1, vsy = 2

  • All others: vsx = 2, vsy = 2

The process of creating unit-vector sums at nodes is handled by ModelGrid._create_link_unit_vectors() (and, for raster grids, by the overriding method RasterModelGrid._create_link_unit_vectors()). The node unit-vector sums are then stored in self.node_unit_vector_sum_x and self.node_unit_vector_sum_y.

How would you use this? Suppose you have a vector variable q defined at links. What’s the average at the nodes? We’ll define the average as follows. The terminology here is: \(q = (u,v)\) represents the vector quantity defined at links, \(Q = (U,V)\) represents its definition at nodes, \((m,n)\) represents the unit vector components at a link, and \((S_x,S_y)\) represents the unit-vector sum at a given node.

\[U_i = \sum_{j=1}^{L_i} q_j m_j / S_{xi} V_i = \sum_{j=1}^{L_i} q_j n_j / S_{yi}\]

Suppose that the vector q is uniform and equal to one. Then, at node 0 in the above grid, this works out to:

U_0 = (q_0 m_0) / 1 + (q_8 m_8) / 1 = (1 0)/ 1 + (1 1)/1 = 1
V_0 = (q_0 n_0) / 1 + (q_8 n_8) / 1 = (1 1) / 1 + (1 0) / 1 = 1

At node 1, in the bottom row but not a corner, we add up the values of q associated with THREE links. The x-vector sum of these links is 2 because there are two horizontal links, each with an x- unit vector value of unity. The y-vector sum is 1 because only one of the three (link #1) has a non-zero y component (equal to one). Here is how the numbers work out:

U_1 = (q_1 m_1) / 2 + (q_8 m_8) / 2 + (q_9 m_9) / 2
    = (1 0) / 2 + (1 1) / 2 + (1 1) / 2 = 1
V_1 = (q_1 n_1) / 1 + (q_8 n_8) / 1 + (q_9 n_9) / 1
    = (1 1) / 1 + (1 0) / 1 + (1 0) / 1 = 1

At node 5, in the interior, there are four connected links (two in-links and two out-links; two horizontal and two vertical). So, we add up the q values associated with all four:

U_5 = (q_1 m_1) / 2 + (q_5 m_5) / 2 + (q_11 m_11) / 2 + (q_12 m_12) / 2
    = (1 0) / 2 + (1 0) / 2 + (1 1) / 2 + (1 1) / 2 = 1

V_5 = (q_1 n_1) / 2 + (q_5 n_5) / 2 + (q_11 n_11) / 2 + (q_12 n_12) / 2
    = (1 1) / 2 + (1 1) / 2 + (1 0) / 2 + (1 0) / 2 = 1

To do this calculation efficiently, we use the following algorithm:

FOR each row in _node_inlink_matrix (representing one inlink @ each
node)
    Multiply the link's q value by its unit x component ...
    ... divide by node's unit vector sum in x ...
    ... and add it to the node's total q_x
    Multiply the link's q value by its unit y component ...
    ... divide by node's unit vector sum in y ...
    ... and add it to the node's total q_y

Examples

Example 1

q[:] = 1. Vector magnitude is \(\sqrt{2}\), direction is \((1,1)\).

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((3, 4), xy_spacing=(2., 2.))
>>> grid.unit_vector_at_node
array([[ 1.,  1.],
       [ 2.,  1.],
       [ 2.,  1.],
       [ 1.,  1.],
       [ 1.,  2.],
       [ 2.,  2.],
       [ 2.,  2.],
       [ 1.,  2.],
       [ 1.,  1.],
       [ 2.,  1.],
       [ 2.,  1.],
       [ 1.,  1.]])
>>> q = grid.ones(at='link')
>>> grid.map_link_vector_to_nodes(q)
array([[ 1.,  1.],
       [ 1.,  1.],
       [ 1.,  1.],
       [ 1.,  1.],
       [ 1.,  1.],
       [ 1.,  1.],
       [ 1.,  1.],
       [ 1.,  1.],
       [ 1.,  1.],
       [ 1.,  1.],
       [ 1.,  1.],
       [ 1.,  1.]])

Example 2

Vector magnitude is 5, angle is 30 degrees from horizontal, forming a 3-4-5 triangle.

>>> import numpy as np
>>> q = np.array([4., 4., 4., 3., 3., 3., 3.,
...               4., 4., 4., 3., 3., 3., 3.,
...               4., 4., 4])
>>> grid.map_link_vector_to_nodes(q)
array([[ 4.,  3.],
       [ 4.,  3.],
       [ 4.,  3.],
       [ 4.,  3.],
       [ 4.,  3.],
       [ 4.,  3.],
       [ 4.,  3.],
       [ 4.,  3.],
       [ 4.,  3.],
       [ 4.,  3.],
       [ 4.,  3.],
       [ 4.,  3.]])

..todo:

Fix and finish example 3 below.

Example 3: Hexagonal grid with vector as above. Here, q is pre-calculated to have the right values to represent a uniform vector with magnitude 5 and orientation 30 degrees counter-clockwise from horizontal.

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 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'] = np.array([5., 4., 3., 2.,
...                                 3., 4., 3., 2.,
...                                 3., 2., 1., 0.])
>>> map_max_of_patch_nodes_to_patch(rmg, 'vals')
array([ 5., 4., 3.,
        4., 4., 3.])
>>> rmg.at_node['vals'] = np.array([5., 4., 3., 2.,
...                                 3., 4., 3., 2.,
...                                 3., 2., 1., 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 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'] = np.array([5., 4., 3., 2.,
...                                 5., 4., 3., 2.,
...                                 3., 2., 1., 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'] = np.array([5., 4., 3., 2.,
...                                 5., 4., 3., 2.,
...                                 3., 2., 1., 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 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 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'] = np.array([5., 4., 3., 2.,
...                                 5., 4., 3., 2.,
...                                 3., 2., 1., 0.])
>>> map_min_of_patch_nodes_to_patch(rmg, 'vals')
array([ 4., 3., 2.,
        2., 1., 0.])
>>> rmg.at_node['vals'] = np.array([5., 4., 3., 2.,
...                                 5., 4., 3., 2.,
...                                 3., 2., 1., 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.), 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 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'] = np.array([-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 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'] = np.array([-1., -2., -1.,
...                                 -2., -3., -4., -5.,
...                                 -1., -2., -1.,
...                                 -1., -2., -3., -4.,
...                                 -1., -2., -1.])
>>> 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 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'] = np.array([-1., -2., -1.,
...                                  0.,  0.,  0.,  0.,
...                                 -1., -2., -1.,
...                                  0.,  0.,  0.,  0.,
...                                 -1., -2., -1.])
>>> 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 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 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 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'] = np.array([-1., -2., -1.,
...                                  0.,  0.,  0.,  0.,
...                                 -1., -2., -1.,
...                                  0.,  0.,  0.,  0.,
...                                 -1., -2., -1.])
>>> 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
property material_layers#

MaterialLayers for each cell.

merge(dual, node_at_cell=None, nodes_at_face=None)#
property midpoint_of_face#

Get the middle of faces.

See also

Graph.midpoint_of_link

Get the middle of links.

Examples

>>> import numpy as np
>>> from landlab.graph import UniformRectilinearGraph
>>> graph = UniformRectilinearGraph((2, 3), spacing=(1, 2))
>>> graph.midpoint_of_link 
array([[ 1. ,  0. ], [ 3. ,  0. ],
       [ 0. ,  0.5], [ 2. ,  0.5], [ 4. ,  0.5],
       [ 1. ,  1. ], [ 3. ,  1. ]])
property ndim#

Number of spatial dimensions of the grid.

new_field_location(loc, size=None)#

Add a new quantity to a field.

Create an empty group into which new fields can be added. The new group is created but no memory allocated yet. The dictionary of the new group can be through a new at_ attribute of the class instance.

Parameters
  • loc (str) – Name of the new group to add to the field.

  • size (int, optional) – Number of elements in the new quantity. If not provided, the size is set to be the size of the first field added to the group.

Raises

ValueError – If the field already contains the group.

Examples

Create a collection of fields and add two groups, node and cell, to it.

>>> from landlab.field import GraphFields
>>> fields = GraphFields()
>>> fields.new_field_location("node", 12)
>>> fields.new_field_location("cell", 2)

The group names in the collection are retrieved with the groups attribute as a set.

>>> names = list(fields.groups)
>>> names.sort()
>>> names
['cell', 'node']

Access the new (empty) groups with the at_ attributes.

>>> fields.at_cell
FieldDataset('cell', size=2, fixed_size=True)
>>> fields.at_node
FieldDataset('node', size=12, fixed_size=True)
>>> fields.new_field_location("core_node")
>>> fields.at_core_node.size is None
True
>>> fields.at_core_node["air__temperature"] = [0, 1]
>>> fields.at_core_node.size
2
property node_at_cell#
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])

Get nodes at link head.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1, 2, 2, 2]
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8))
>>> graph = Graph((node_y, node_x), links=links)
>>> graph.node_at_link_head
array([1, 2, 3, 4, 5, 4, 5, 6, 7, 8, 7, 8])

Get nodes at link tail.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1, 2, 2, 2]
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8))
>>> graph = Graph((node_y, node_x), links=links)
>>> graph.node_at_link_tail
array([0, 1, 0, 1, 2, 3, 4, 3, 4, 5, 6, 7])
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) 
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) 
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 node_x#
property node_y#
property nodes#

Get identifier for each node.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1]
>>> graph = Graph((node_y, node_x))
>>> graph.nodes
array([0, 1, 2, 3, 4, 5])
property nodes_at_face#

Get nodes at either end of links.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1, 2, 2, 2]
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8))
>>> graph = Graph((node_y, node_x), links=links)
>>> graph.nodes_at_link 
array([[0, 1], [1, 2],
       [0, 3], [1, 4], [2, 5],
       [3, 4], [4, 5],
       [3, 6], [4, 7], [5, 8],
       [6, 7], [7, 8]])
property nodes_at_patch#

Get the nodes that define a patch.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = ([0, 1, 2, 0, 1, 2, 0, 1, 2],
...                   [0, 0, 0, 1, 1, 1, 2, 2, 2])
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8))
>>> patches = ((0, 3, 5, 2), (1, 4, 6, 3))
>>> graph = Graph((node_y, node_x), links=links, patches=patches, sort=True)
>>> graph.nodes_at_patch
array([[4, 3, 0, 1],
       [5, 4, 1, 2]])
property nodes_per_ring#
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

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_cells#

Get the number of cells.

See also

Graph.number_of_patches

property number_of_cells_present_at_corner#

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

See also

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

Graph.number_of_patches_present_at_link

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_corners#

Number of core corners.

See also

Graph.number_of_core_nodes

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
property number_of_core_patches#

Number of core patches.

See also

Graph.number_of_core_cells

property number_of_corners#

Get total number of corners.

See also

Graph.number_of_nodes

property number_of_corners_in_ring#

Number of corners in each ring.

See also

Graph.number_of_nodes_in_ring

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_faces#

Get corners at face head.

See also

Graph.number_of_links

property number_of_fixed_faces#

Number of fixed faces.

See also

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

Get nodes at link head.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1, 2, 2, 2]
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8))
>>> graph = Graph((node_y, node_x), links=links)
>>> graph.number_of_links == 12
True
property number_of_nodes#

Get total number of nodes.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1]
>>> graph = Graph((node_y, node_x))
>>> graph.number_of_nodes == 6
True
property number_of_nodes_in_ring#

Number of nodes in each ring.

Returns

  • ndarray of int – Number of nodes in each ring, excluding the center node.

  • >>> from landlab.graph import RadialGraph

  • >>> graph = RadialGraph((4, 6))

  • >>> graph.number_of_nodes_in_ring

  • array([ 6, 12, 24, 48])

  • meta landlab: info-node, quantity

property number_of_patches#

Get the number of patches.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1, 2, 2, 2]
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8))
>>> patches = ((0, 3, 5, 2), (1, 4, 6, 3))
>>> graph = Graph((node_y, node_x), links=links, patches=patches)
>>> graph.number_of_patches == 2
True

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 number_of_rings#

Number of node rings in grid.

Returns

The number of node rings in the radial grid (not counting the center node).

Return type

int

Examples

>>> import numpy as np
>>> from landlab.graph import RadialGraph
>>> graph = RadialGraph((1, 4))
>>> graph.number_of_rings
1
ones(*args, **kwds)#

Array, initialized to 1, whose size is that of the field.

Return a new array of the data field size, filled with ones. Keyword arguments are the same as that for the equivalent numpy function.

Parameters

group (str) – Name of the group.

See also

numpy.ones

See for a description of optional keywords.

GraphFields.empty

Equivalent method that does not initialize the new array.

GraphFields.zeros

Equivalent method that initializes the data to 0.

Examples

>>> from landlab.field import GraphFields
>>> field = GraphFields()
>>> field.new_field_location("node", 4)
>>> field.ones("node")
array([ 1.,  1.,  1.,  1.])
>>> field.ones("node", dtype=int)
array([1, 1, 1, 1])

Note that a new field is not added to the collection of fields.

>>> list(field.keys("node"))
[]
property open_boundary_corners#

Get array of open boundary corners.

See also

Graph.open_boundary_nodes

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 origin#
property patch_area_at_corner#

Cell areas in a ncorners-long array.

See also

Graph.cell_area_at_node

property patch_at_corner#

Get the patches on either side of each link.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = ([0, 1, 2, 0, 1, 2],
...                   [0, 0, 0, 1, 1, 1])
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5))
>>> patches = ((0, 3, 5, 2), (1, 4, 6, 3))
>>> graph = Graph((node_y, node_x), links=links, patches=patches)
>>> graph.patches_at_link 
array([[ 0, -1], [ 1, -1],
       [ 0, -1], [ 0,  1], [ 1, -1],
       [ 0, -1], [ 1, -1]])
property patches_at_node#

Get the patches that touch each node.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = ([0, 1, 2, 0, 1, 2],
...                   [0, 0, 0, 1, 1, 1])
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5))
>>> patches = ((0, 3, 5, 2), (1, 4, 6, 3))
>>> graph = Graph((node_y, node_x), links=links, patches=patches, sort=True)
>>> graph.patches_at_node 
array([[ 0, -1], [ 1,  0], [ 1, -1],
       [ 0, -1], [ 0,  1], [ 1, -1]])

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
property perimeter_corners#

Get corners on the convex hull of a Graph.

See also

Graph.perimeter_nodes

property perimeter_nodes#

Get nodes on the convex hull of a Graph.

Examples

>>> import numpy as np
>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1]
>>> graph = Graph((node_y, node_x))
>>> np.sort(graph.perimeter_nodes)
array([0, 2, 3, 5])
property radius_at_corner#

Distance for center corner to each corner.

See also

Graph.radius_at_node

property radius_at_node#

Distance for center node to each node.

Returns

  • ndarray of float – The distance from the center node of each node.

  • >>> from landlab.graph import RadialGraph

  • >>> graph = RadialGraph((2, 6), sort=True)

  • >>> np.round(graph.radius_at_node, 3)

  • array([ 2., 2., 2., 2., 2., 1., 1., 2., 1., 0., 1., 2., 1., – 1., 2., 2., 2., 2., 2.])

  • meta landlab: info-node, quantity

property radius_of_ring#
reset_status_at_node()#

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

return_array_or_field_values(field, at=None)#

Return field given a field name, or array of with the correct shape.

Given a group and a field, return a reference to the associated data array. field is either a string that is a field in the group or an array of the correct size.

This function is meant to serve like the use_field_name_or_array decorator for bound functions.

Parameters
  • field (str or array) – Name of the field withing group.

  • at (str, optional) – Name of the group.

Returns

The values of the field.

Return type

numpy.ndarray

Raises
  • landlab.field.errors.GroupError – If group does not exist

  • landlab.field.errors.FieldError – If field does not exist

Examples

Create a group of fields called node.

>>> import numpy as np
>>> from landlab.field import GraphFields
>>> fields = GraphFields()
>>> fields.new_field_location('node', 4)

Add a field, initialized to ones, called topographic__elevation to the node group. The field_values method returns a reference to the field’s data.

>>> _ = fields.add_ones("topographic__elevation", at="node")
>>> fields.field_values("topographic__elevation", at="node")
array([ 1.,  1.,  1.,  1.])

Alternatively, if the second argument is an array, its size is checked and returned if correct.

>>> vals = np.array([4., 5., 7., 3.])
>>> fields.return_array_or_field_values(vals, at="node")
array([ 4.,  5.,  7.,  3.])

Raise FieldError if field does not exist in group.

>>> fields.return_array_or_field_values("surface__temperature", at="node")
...     
Traceback (most recent call last):
FieldError: surface__temperature

If group does not exists, Raise GroupError.

>>> fields.return_array_or_field_values("topographic__elevation", at="cell")
...     
Traceback (most recent call last):
GroupError: cell

And if the array of values provided is incorrect, raise a ValueError.

>>> vals = np.array([3., 2., 1.])
>>> fields.return_array_or_field_values(vals, at="node")
...     
Traceback (most recent call last):
ValueError: Array has incorrect size.
property ring_at_corner#
property ring_at_node#
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
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., -9999, 0., 0., 0.])
>>> mg.set_nodata_nodes_to_closed(h, -9999)
>>> mg.status_at_node
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 
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 = rmg.zeros(at='node')
>>> z = np.array([
...     -99., -99., -99., -99., -99., -99., -99., -99., -99.,
...     -99., -99., -99.,   0.,   0.,   0.,   0.,   0., -99.,
...     -99., -99., -99.,   0.,   0.,   0.,   0.,   0., -99.,
...     -99., -99., -99., -99., -99., -99., -99., -99., -99.])
>>> rmg.set_nodata_nodes_to_fixed_gradient(z, -99)
>>> rmg.status_at_node 
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 
array([4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 2, 2, 2, 2, 2, 4,
       4, 4, 2, 0, 0, 0, 0, 2, 4, 4, 4, 0, 0, 0, 0, 0, 4,
       4, 4, 2, 0, 0, 0, 0, 2, 4, 4, 4, 2, 2, 2, 2, 2, 4,
       4, 4, 4, 4, 4, 4, 4, 4], dtype=uint8)
property shape#
size(group)#

Return the size of the arrays stored in a group.

Parameters

group (str) – Group name.

Returns

Array size.

Return type

int

Examples

>>> from landlab.field import GraphFields
>>> fields = GraphFields()
>>> fields.new_field_location("node", 4)
>>> fields.size("node")
4
sort()#

Sort graph elements.

property spacing#
property spacing_of_rings#

Fixed distance between rings.

Returns

  • ndarray of float – The distance from the center node of each node.

  • >>> from landlab.graph import RadialGraph

  • >>> graph = RadialGraph((2, 6), spacing=2.)

  • >>> graph.spacing_of_rings

  • 2.0

  • meta landlab: info-grid, quantity

property status_at_corner#

Get array of the boundary status for each corner.

See also

Graph.status_at_node

property status_at_face#

Get array of the status of all faces.

See also

Graph.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
thaw()#

Thaw the graph by making arrays writable.

thawed()#
to_dict()#
to_json()#
to_netcdf(*args, **kwds)#

Write graph contents to a netCDF file.

See xarray.Dataset.to_netcdf for a complete list of parameters. Below are only the most common.

Parameters
  • path (str, optional) – Path to which to save this graph.

  • mode ({'w', 'a'}, optional) – Write (‘w’) or append (‘a’) mode. If mode=’w’, any existing file at this location will be overwritten.

  • format ({'NETCDF4', 'NETCDF4_CLASSIC', 'NETCDF3_64BIT', 'NETCDF3_CLASSIC'}, optional) –

    File format for the resulting netCDF file:

    • NETCDF4: Data is stored in an HDF5 file, using netCDF4 API features.

    • NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only netCDF 3 compatible API features.

    • NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, which fully supports 2+ GB files, but is only compatible with clients linked against netCDF version 3.6.0 or later.

    • NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not handle 2+ GB files very well.

    All formats are supported by the netCDF4-python library. scipy.io.netcdf only supports the last two formats.

    The default format is NETCDF4 if you are saving a file to disk and have the netCDF4-python library available. Otherwise, xarray falls back to using scipy to write netCDF files and defaults to the NETCDF3_64BIT format (scipy does not support netCDF4).

property unit_vector_at_corner#

Get a unit vector for each corner.

See also

Graph.unit_vector_at_node

property unit_vector_at_face#

Make arrays to store the unit vectors associated with each face.

See also

Graph.unit_vector_at_link

Make arrays to store the unit vectors associated with each link.

For each link, the x and y components of the link’s unit vector (that is, the link’s x and y dimensions if it were shrunk to unit length but retained its orientation).

Examples

The example below is a seven-node hexagonal grid, with six nodes around the perimeter and one node (#3) in the interior. There are four horizontal links with unit vector (1,0), and 8 diagonal links with unit vector (+/-0.5, +/-sqrt(3)/2) (note: sqrt(3)/2 ~ 0.866).

>>> from landlab.graph import TriGraph
>>> graph = TriGraph((3, 2), spacing=2.0, node_layout="hex", sort=True)
>>> np.round(graph.unit_vector_at_link[:, 0], decimals=5)
array([ 1. , -0.5,  0.5, -0.5,  0.5,  1. ,  1. ,  0.5, -0.5,  0.5, -0.5,
        1. ])
>>> np.round(graph.unit_vector_at_link[:, 1], decimals=5)
array([ 0.     ,  0.86603,  0.86603,  0.86603,  0.86603,  0.     ,
        0.     ,  0.86603,  0.86603,  0.86603,  0.86603,  0.     ])
property unit_vector_at_node#

Get a unit vector for each node.

Examples

>>> from landlab.graph import UniformRectilinearGraph
>>> graph = UniformRectilinearGraph((3, 3))
>>> graph.unit_vector_at_node
array([[ 1.,  1.],
       [ 2.,  1.],
       [ 1.,  1.],
       [ 1.,  2.],
       [ 2.,  2.],
       [ 1.,  2.],
       [ 1.,  1.],
       [ 2.,  1.],
       [ 1.,  1.]])
>>> from landlab.graph import TriGraph
>>> graph = TriGraph((3, 2), spacing=2.0, node_layout="hex", sort=True)
>>> unit_vector_at_node = np.round(graph.unit_vector_at_node, decimals=5)
>>> unit_vector_at_node[:, 0]
array([ 2.,  2.,  2.,  4.,  2.,  2.,  2.])
>>> unit_vector_at_node[:, 1]
array([ 1.73205,  1.73205,  1.73205,  3.4641 ,  1.73205,  1.73205,  1.73205])
property unit_vector_sum_xcomponent_at_corner#

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

See also

Graph.unit_vector_sum_xcomponent_at_node

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_corner#

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

See also

Graph.unit_vector_sum_ycomponent_at_node

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

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'] = np.array([-1., -2., -1.,
...                                 -2., -3., -4., -5.,
...                                 -1., -2., -1.,
...                                 -1., -2., -3., -4.,
...                                 -1., -2., -1.])
>>> 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 x_of_corner#

Get x-coordinate of corner.

See also

Graph.x_of_node

property x_of_node#

Get x-coordinate of node.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1]
>>> graph = Graph((node_y, node_x))
>>> graph.x_of_node
array([ 0.,  1.,  2.,  0.,  1.,  2.])
property xy_of_cell#

Get the centroid of each cell.

See also

Graph.xy_of_patch

property xy_of_center#

Return (x, y) of the reference point.

property xy_of_corner#

Get x and y-coordinates of corner.

See also

Graph.xy_of_node

property xy_of_face#
property xy_of_node#

Get x and y-coordinates of node.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1]
>>> graph = Graph((node_y, node_x))
>>> graph.xy_of_node[:, 0]
array([ 0.,  1.,  2.,  0.,  1.,  2.])
>>> graph.xy_of_node[:, 1]
array([ 0.,  0.,  0.,  1.,  1.,  1.])
property xy_of_patch#

Get the centroid of each patch.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1, 2, 2, 2]
>>> links = ((0, 1), (1, 2),
...          (0, 3), (1, 4), (2, 5),
...          (3, 4), (4, 5),
...          (3, 6), (4, 7), (5, 8),
...          (6, 7), (7, 8))
>>> patches = ((0, 3, 5, 2), (1, 4, 6, 3))
>>> graph = Graph((node_y, node_x), links=links, patches=patches)
>>> graph.xy_of_patch
array([[ 0.5,  0.5],
      [ 1.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 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)
property y_of_corner#

Get y-coordinate of corner.

See also

Graph.y_of_node

property y_of_node#

Get y-coordinate of node.

Examples

>>> from landlab.graph import Graph
>>> node_x, node_y = [0, 1, 2, 0, 1, 2], [0, 0, 0, 1, 1, 1]
>>> graph = Graph((node_y, node_x))
>>> graph.y_of_node
array([ 0.,  0.,  0.,  1.,  1.,  1.])
zeros(*args, **kwds)#

Array, initialized to 0, whose size is that of the field.

Parameters
  • group (str) – Name of the group.

  • size (Return a new array of the data field) –

  • Keyword (filled with zeros.) –

  • function. (arguments are the same as that for the equivalent numpy) –

  • grid. (This method is not valid for the group) –

See also

numpy.zeros

See for a description of optional keywords.

GraphFields.empty

Equivalent method that does not initialize the new array.

GraphFields.ones

Equivalent method that initializes the data to 1.

Examples

>>> from landlab.field import GraphFields
>>> field = GraphFields()
>>> field.new_field_location("node", 4)
>>> field.zeros("node")
array([ 0.,  0.,  0.,  0.])

Note that a new field is not added to the collection of fields.

>>> list(field.keys("node"))
[]