API for landlab.grid.hex

Python implementation of HexModelGrid, 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 HexModelGrid(shape, spacing=1.0, xy_of_lower_left=(0.0, 0.0), orientation='horizontal', node_layout='hex', reorient_links=True, xy_of_reference=(0.0, 0.0), xy_axis_name=('x', 'y'), xy_axis_units='-')[source]

Bases: DualHexGraph, ModelGrid

A grid of hexagonal cells.

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

Examples

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

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

Create a grid of hexagonal cells.

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

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

  • spacing (float, optional) – Node spacing.

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

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

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

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

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

Returns

A newly-created grid.

Return type

HexModelGrid

Examples

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

>>> from landlab import HexModelGrid
>>> hmg = HexModelGrid((3, 2), spacing=1.0)
>>> hmg.number_of_nodes
7
__init__(shape, spacing=1.0, xy_of_lower_left=(0.0, 0.0), orientation='horizontal', node_layout='hex', reorient_links=True, xy_of_reference=(0.0, 0.0), xy_axis_name=('x', 'y'), xy_axis_units='-')[source]

Create a grid of hexagonal cells.

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

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

  • spacing (float, optional) – Node spacing.

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

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

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

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

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

Returns

A newly-created grid.

Return type

HexModelGrid

Examples

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

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

Adjacent corners for each grid corner.

See also

Graph.active_adjacent_nodes_at_node

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

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']
property boundary_corners

Get array of boundary corners.

See also

Graph.boundary_nodes

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 core_corners

Get array of core corners.

See also

Graph.core_nodes

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 face_status_at_corner
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_value_boundary_corners

Get array of fixed value boundary corners.

See also

Graph.fixed_value_boundary_nodes

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.])
hexplot(data, data_label=None, color_map=None)[source]

Create a plot of the grid elements.

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

Parameters
  • data (str or node array (1d numpy array with number_of_nodes entries)) – Data field to be colored.

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

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

See also

plot.imshow_grid

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

LLCATS

GINF

node_row_and_column(node_id)[source]

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

Examples

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

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

See also

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_corners

Number of core corners.

See also

Graph.number_of_core_nodes

property number_of_core_patches

Number of core patches.

See also

Graph.number_of_core_cells

property number_of_corner_columns

Number of corner columns hex grid.

See also

Graph.number_of_node_columns

property number_of_corner_rows

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

See also

Graph.number_of_node_rows

property number_of_fixed_faces

Number of fixed faces.

See also

Graph.number_of_fixed_links

property number_of_node_columns

Number of node columns hex grid.

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

Returns the number of columns, including boundaries.

Notes

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

Examples

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

LLCATS: GINF NINF

property number_of_node_rows

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

Returns the number of rows, including boundaries.

Notes

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

Examples

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

LLCATS: GINF NINF

property open_boundary_corners

Get array of open boundary corners.

See also

Graph.open_boundary_nodes

property patch_area_at_corner

Cell areas in a ncorners-long array.

See also

Graph.cell_area_at_node

set_watershed_boundary_condition(node_data, nodata_value=-9999.0, return_outlet_id=False)[source]

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

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

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

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

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

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

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

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

Examples

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

      1. ,  2. ,  3. ,  4. ,
  0.5,  1.5,  2.5,  3.5,  4.5,
0. ,  1. ,  2. ,  3. ,  4. ,  5.,
  0.5,  1.5,  2.5,  3.5,  4.5,
      1. ,  2. ,  3. ,  4.
>>> from landlab import HexModelGrid
>>> hmg = HexModelGrid((5, 4))
>>> z = hmg.add_zeros("topographic__elevation", at="node")
>>> z += hmg.x_of_node + 1.0
>>> out_id = hmg.set_watershed_boundary_condition(z, -9999., True)
>>> out_id
array([9])
>>> hmg.status_at_node
array([4, 4, 4, 4, 4, 0, 0, 0, 4, 1, 0, 0, 0, 0, 4, 4, 0, 0, 0, 4, 4, 4, 4,
   4], dtype=uint8)

LLCATS: BC

set_watershed_boundary_condition_outlet_id(outlet_id, node_data, nodata_value=-9999.0)[source]

Set the boundary conditions for a watershed on a HexModelGrid.

All nodes with nodata_value are set to BC_NODE_IS_CLOSED. All nodes with data values are set to BC_NODE_IS_CORE, with the exception that the outlet node is set to a BC_NODE_IS_FIXED_VALUE.

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

Assumes that the id of the outlet is already known.

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

Parameters
  • outlet_id (integer) – id of the outlet node

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

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

Examples

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

      1. ,  2. ,  3. ,  4. ,
  0.5,  1.5,  2.5,  3.5,  4.5,
0. ,  1. ,  2. ,  3. ,  4. ,  5.,
  0.5,  1.5,  2.5,  3.5,  4.5,
      1. ,  2. ,  3. ,  4.
>>> from landlab import HexModelGrid
>>> hmg = HexModelGrid((5, 4))
>>> z = hmg.add_zeros("topographic__elevation", at="node")
>>> z += hmg.x_of_node + 1.0
>>> hmg.status_at_node
array([1, 1, 1, 1, 1, 0, 0, 0, 1, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 1, 1, 1, 1,
   1], dtype=uint8)
>>> outlet = hmg.set_watershed_boundary_condition_outlet_id(9, z, -9999.)
>>> hmg.status_at_node
array([4, 4, 4, 4, 4, 0, 0, 0, 4, 1, 0, 0, 0, 0, 4, 4, 0, 0, 0, 4, 4, 4, 4,
   4], dtype=uint8)

LLCATS: BC

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

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_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 xy_of_lower_left

Return (x, y) of the reference point.