Landlab: A modular Earth Surface Dynamics modeling library#
Landlab is an opensource Pythonlanguage package for numerical modeling of Earth surface dynamics. It contains
A gridding engine which represents the model domain. Regular and irregular grids are supported.
A library of process components, each of which represents a physical process (e.g., generation of rain, erosion by flowing water). These components have a common interface and can be combined based on a user’s needs.
Utilities that support general numerical methods, file input/output, and visualization.
In addition Landlab contains a set of Jupyter notebook tutorials providing an introduction to core concepts and examples of use.
Landlab was designed for disciplines that quantify Earth surface dynamics such as geomorphology, hydrology, glaciology, and stratigraphy. It can also be used in related fields. Scientists who use this type of model often build their own unique model from the ground up, recoding the basic building blocks of their landscape model rather than taking advantage of codes that have already been written. Landlab saves practitioners from the need for this kind of reinvention by providing standardized components that they can reuse.
Watch the webinar Landlab Toolkit Overview at CSDMS to learn more.
Install#
Important
The following commands will install landlab into your current environment. Although not necessary, we highly recommend you install landlab into its own virtual environment.
In order to use landlab you will first need Python. While not necessary, we recommend using the Anaconda Python distribution as it provides a large number of thirdparty packages useful for scientific computing.
To install landlab, simply run the following in your terminal of choice:
$ conda install mamba c condaforge
$ mamba install landlab c condaforge
$ conda install landlab c condaforge
$ pip install landlab
If you would like the very latest development version of landlab or want to modify or contribute code to the landlab project, you will need to do a developer installation of landlab from source.
Getting Started#
10 minutes to Landlab#
For a quick introduction to Landlab, check out this tutorial on Binder showing its major features in the context of a 2D model for faultscarp degradation.
Selfstudy course for learning to use Landlab in your research#
This course is entirely hosted in our Jupyter notebook tutorials. Here is a link to the syllabus on Binder.
User Guide#
The User Guide describes Landlab by topic area.
Users brandnew to Landlab should start with 10 minutes to Landlab.
Further information on any specific method can be obtained in the API reference.
The Landlab project creates an environment in which scientists can build a numerical surface process model without having to code all of the individual components. Surface process models compute flows of mass, such as water, sediment, glacial ice, volcanic material, or landslide debris, across a gridded terrain surface. Surface process models have a number of commonalities, such as operating on a grid of points and routing material across the grid. Scientists who want to use a surface process model often build their own unique model from the ground up, recoding the basic building blocks of their surface process model rather than taking advantage of codes that have already been written.
A list of papers and presentations using Landlab can be found here.
Introduction to Python#
Why Python?#
Landlab is coded in Python and includes as dependencies a number of widely used scientific Python packages—in particular, NumPy and SciPy. The decision to code in Python was explicitly made to lower the bar to entry for Landlab; to increase the flexibility and reusability of the code base; and to increase development speed both for the core development team and for future users. The choice of Python also means that developers using Landlab can take advantage of that language’s affinity for rapid development timescales.
Other advantages of this choice include high portability between platforms, open source language, numerous existing scientific libraries that prevent developers having to “reinvent the wheel,” and support for selective optimization of timecritical parts of the code base in Cython (see Cython).
Getting to know Python#
We recommend you approach Landlab with a basic working knowledge of the Python coding language. A good, concise, complete beginner’s guide that will get you to enough knowledge to be able to get started can be found at interactivepython. We like the Software Carpentry intro and these Python notebooks as more comprehensive introductions to Python.
Landlab is also written in an objectoriented coding style. Many of the elements of Landlab that you will interact with—grids, components, utilities—are Python objects, which means they contain both data that describe the object and functions that you can call that operate on the object. Think of the object as a container in which everything relevant to that part of the code is stored, so that it can be accessed easily. You can read a bit more about Python objects on this page for general information. There is more detail on what this means in terms of running our code on the Build a Model page.
If you know MatLab…#
If you’re already familiar with Matlab, you will probably feel at home with Python fairly quickly. However, there are some critical differences. Important things to remember include:
Python’s indexing is inclusive at the start and exclusive at the end (in contrast to Matlab). For example, in Python
numpy.arange(0, 100)
will give an array of 100 numbers, starting at 0 and ending at 99.
Python doesn’t use parentheses or brackets to delimit code blocks (functions, loops, if statements, etc.). Instead it uses a colon to declare the start of a code block, then consistent indenting (normally 4 spaces) to for the rest of the block. e.g.,
def myfunction(input_param):
if type(input_param) is str:
print("The input to the function said: ", input_param)
else:
print("The input parameter wasn't a string.")
print("It was actually " + str(type(input_param)))
Lines don’t need to end with the semicolon to suppress output; Python won’t
print output unless you explicitly call print
.
Finally, but importantly, Python doesn’t use the hat ^
as its
raisetothepower symbol. Instead, it uses a double star **
. Simple, but
typically very frustrating for a day or two during transition! There’s also the
NumPy method, np.square
, which if you’re using arrays typically outperforms
the **
operator.
We have a very short tutorial on Python and NumPy from the point of view of Landlab (and the key differences with Matlab) here.
NumPy, SciPy, and Efficient Coding Style#
NumPy and SciPy are the workhorse scientific computing packages of Python. They provide fast, efficient, and surprisingly comprehensive data structures and numerical methods that we (and you) can exploit to make coding in Landlab faster and easier.
In particular, Landlab makes extensive use of the NumPy array data structure. Almost all data input and output from Landlab is in the form of an array (see Landlab Fields for more information). These arrays allow operations to happen much faster on the data than would be possible in a pure Python data structure like a list or a dictionary. (This is possible because NumPy arrays suppress some of Python’s inbuilt type checking and memory management and impose a more ordered structure on the way raw data is held in your computer’s memory).
In order to exploit the speed gains that NumPy can give you, you’ll need to adopt a coding style quite different to what would be natural in, say, C++ (or likely, Matlab). A typical bottleneck in Python code occurs when looping over data, and NumPy arrays let you avoid doing this. So if you find yourself about to write something like:
for i in range(len(myarray)):
myoutputarray[i] = myoutputarray[i] + myarray[i]
 Don’t! Try instead to develop a coding style where each line operates on the
whole array at once. For example:
myoutputarray += myarray
In particular, it can be very tempting to use loops to apply a condition over a whole array. Try not to do this! Instead of
for i in myarray:
if i < 0:
i = 0
which will be really slow. Do this:
myarray[myarray < 0] = 0
There is much more information about writing efficient NumPy code online.
We also strongly recommend the book “High Performance Python” by Gorelick and Ozsvald, published by O’Reilly, if you’re looking for a more comprehensive treatment.
Cython#
If you explore the Landlab source code, you will discover that not all of Landlab is written in pure Python. Some of it is written in Cython. Cython is a programming language closely related to Python, and indeed, all code written in pure Python is automatically also Cython code. Cython is probably best thought of as a cross between C++ and Python, which aims to combine the flexibility of Python with the brute power and granular control that C++ provides. For example, if there are sections of code where looping through an array is unavoidable, Cython provides a way to significantly accelerate the speed of this code. Cython code largely looks like straightforward Python, but may have type declarations or other C++like features.
From the user’s perspective, the most important thing to note is that Cython is a compiled language. (This isn’t true of Python, which is an interpreted—compiled at run time—language.) We provide the precompiled executables you will need to run Landlab when you install, and this should be sufficient for the vast majority of users.
However if, as a developer, you intend to modify any of the sections of code that we provide to you, you will probably need to recompile that code on your machine before the changes take effect. See the developer installation instructions for more information on this.
Introduction to Landlab’s Gridding Library#
When creating a twodimensional simulation model, often the most timeconsuming and errorprone task involves writing the code to set up the underlying grid. Irregular (or “unstructured”) grids are especially tricky to implement. Landlab’s ModelGrid package makes this process much easier, by providing a set of library routines for creating and managing a 2D grid, attaching data to the grid, performing common input and output operations, and providing library functions that handle common numerical operations such as calculating a field of gradients for a particular state variable. By taking care of much of the overhead involved in writing gridmanagement code, ModelGrid is designed to help you build 2D models quickly and efficiently, freeing you to concentrate on the science behind the code.
Some of the things you can do with ModelGrid include:
Create and configure a structured or unstructured grid in a one or a few lines of code
Create various data arrays attached to the grid
Easily implement staggeredgrid finitedifference/finitevolume schemes
Calculate gradients in state variables in a single line
Calculate net fluxes in/out of grid cells in a single line
Set up and run “linkbased” cellular automaton models
Switch between structured and unstructured grids without needing to change the rest of the code
Develop complete, 2D numerical finitevolume or finitedifference models much more quickly and efficiently than would be possible using straight C, Fortran, Matlab, or Python code
Some of the Landlab capabilities that work with ModelGrid to enable easy numerical modeling include:
Easily read in model parameters from a formatted text file
Write grid and data output to netCDF files for import into opensource visualization packages such as ParaView and VisIt
Create grids from ArcGISformatted ascii files
Create models by coupling together your own and/or prebuilt process components
Use models built by others from process components
This document provides a basic introduction to building applications using Landlab’s ModelGrid. It covers: (1) how grids are represented, and (2) a set of tutorial examples that illustrate how to build models using simple scripts.
How a Grid is Represented#
Basic Grid Elements#
Figure 1 illustrates how ModelGrid represents a simulation grid. The grid contains a set of (x,y) points called nodes. In a typical finitedifference or finitevolume model, nodes are the locations at which one tracks scalar state variables, such as water depth, land elevation, seasurface elevation, or temperature.
Each adjacent pair of nodes is connected by a line segment known as a link. A link has both a position in space, denoted by the coordinates of the two bounding nodes, and a direction: a link runs from one node (known as its fromnode or tailnode) to another node (known as its tonode or headnode).
Every node in the grid interior is associated with a polygon known as a cell (illustrated, for example, by the shaded square region in Figure 1a). Each cell is bounded by a set of line segments known as faces, which it shares with its neighboring cells.
In the simple case of a regular (raster) grid, the cells are square, the nodes are the center points of the cells (Figure 1), and the links and faces have identical length (equal to the node spacing). In a VoronoiDelaunay grid, the cells are Voronoi polygons (also known as Theissen polygons) (Figure 1a). In this case, each cell represents the surface area that is closer to its own node than to any other node in the grid. The faces represent locations that are equidistant between two neighboring nodes. Other grid configurations are possible as well. The spring 2015 version of Landlab includes support for hexagonal and radial grids, which are specialized versions of the VoronoiDelaunay grid shown in Figure 1a. Note that the nodelinkcellface topology is general enough to represent other types of grid; for example, one could use ModelGrid’s data structures to implement a quadtree grid, or a DelaunayVoronoi grid in which cells are triangular elements with nodes at their circumcenters.
Creating a Grid#
Creating a grid is easy. The first step is to import Landlab’s
RasterModelGrid
class (this
assumes you have installed Landlab
and are working in your favorite
Python environment):
>>> from landlab import RasterModelGrid
Now, create a regular (raster) grid with 10 rows and 40 columns, with a node spacing (dx) of 5:
>>> mg = RasterModelGrid((10, 40), 5.)
mg is now a grid object with 400 ( 10*40 )
nodes and 750 ( 40*(101) + 30*(101) )
links.
>>> mg.number_of_node_columns
40
>>> mg.number_of_nodes
400
>>> mg.number_of_links
750
Adding Data to a Landlab Grid Element using Fields#
Landlab has a data structure called fields that will store data associated with different types of grid elements. Fields are convenient because 1) fields create data arrays of the proper length for the associated grid element, and 2) fields attach these data to the grid, so that any piece of code that has access to the grid also has access to the data stored in fields.
Suppose you would like like to track the elevation at each node. The following code creates a data field (array) called elevation. In this case, we’ll use the grid method add_zeros to create a field that initially sets all values in the field to zero (we’ll explain how to read in elevation values from a file in the section on DEMs below). The add_zeros method takes two arguments: the name of the grid element (in this case, node, in the singular) and a name we choose for the value in the data field (here we’ll just call it elevation). Each elevation value in the data field is then associated with a specific grid node. The data field is just a NumPy array whose length is equal to the number of nodes in the grid.
>>> z = mg.add_zeros("elevation", at="node")
Here z is an array of zeros. We can verify that z has the same length as the number of nodes:
>>> z.size # or len(z)
400
Note that z is a reference to the data stored in the model field. This means that if you change z, you also change the data in the ModelGrid’s elevation field. Therefore, you can access and manipulate data in the field either through the variable z or through the grid, as in the following examples:
>>> mg.at_node["elevation"][5] = 1000.0
or the alternative notation:
>>> mg['node']['elevation'][5]
1000.
Now the sixth element in the model’s elevation field array, or in z, is equal to 1000. (Remember that the first element of a Python array has an index of 0 (zero)).
You can see all of the field data available at the nodes on mg with the following:
>>> mg.at_node.keys()
['elevation']
You may recognize this as a dictionarytype structure, where the keys are the names (as strings) of the data arrays.
There are currently no data values (fields) assigned to the links, as shown by the following:
>>> mg.at_link.keys()
[]
It is also possible, and indeed, often quite useful, to initialize a field from an
existing NumPy array of data. You can do this with the
add_field
method.
This method allows slightly more granular control over how the field gets
created. In addition to the grid element and field name, this method takes an
array of values to assign to the field. Optional arguments include: units=
to assign a unit of measurement (as a string) to the value, copy=
a boolean
to determine whether to make a copy of the data, and clobber=
a boolean
that prevents accidentally overwriting an existing field.
>>> import numpy as np
>>> elevs_in = np.random.rand(mg.number_of_nodes)
>>> mg.add_field("elevation", elevs_in, at="node", units="m", copy=True, clobber=True)
Fields can store data at nodes, cells, links, faces, patches, junctions, and corners (though the latter two or three are very rarely, if ever, used). The grid element you select is described in Landlab jargon as that field’s centering or group, and you will sometimes see these terms used as input parameters to various grid methods.
To access only the core nodes, core cells, active links, or some other subset of node values using the properties available through the ModelGrid, you can specify a subset of the field data array. For example, if we wanted to determine the elevations at core nodes only we can do the following:
>>> core_node_elevs = mg.at_node["elevation"][mg.core_nodes]
The first set of brackets, in this case elevation, indicates the field data array, and the second set of brackets, in this case mg.core_nodes (itself an array of core node IDs), is a NumPy filter that specifies which elevation elements to return.
Here is another example of initializing a field with the add_ones method. Note that when initializing a field, the singular of the grid element type is provided:
>>> veg = mg.add_ones("percent_vegetation", at="cell")
>>> mg.at_cell.keys()
['percent_vegetation']
Here veg is an array of ones that has the same length as the number of cells. Because there are no cells around the edge of a grid, there are fewer cells than nodes:
>>> mg.at_cell['percent_vegetation'].size
304
As you can see, fields are convenient because you don’t have to keep track of how many nodes, links, cells, etc. there are on the grid. It is easy for any part of the code to query what data are already associated with the grid and operate on these data.
You are free to call your fields whatever you want. However, field names are more useful if standardized across components. If you are writing a Landlab component you should use Landlab’s standard names. Standard names for fields in a particular component can be accessed individually through the properties component_instance._input_var_names and component_instance._output_var_names (returned as dictionaries), and are listed in the docstring for each component.
>>> from landlab.components.flexure import Flexure
>>> flexer = Flexure(rg)
>>> flexer._input_var_names
{'lithosphere__elevation',
'lithosphere__overlying_pressure',
'planet_surface_sediment__deposition_increment'}
>>> flexer._output_var_names
{'lithosphere__elevation', 'lithosphere__elevation_increment'}
We also maintain this list of all the Landlab standard names.
Our fields also offer direct compatibility with CSDMS’s standard naming system for variables. However, note that, for ease of use and readability, Landlab standard names are typically much shorter than CSDMS standard names. We anticipate that future Landlab versions will be able to automatically map from Landlab standard names to CSDMS standard names as part of Landlab’s builtin Basic Model Interface for CSDMS compatibility.
The following gives an overview of the commands you can use to interact with the grid fields.
Field initialization#
grid.add_empty(name, at="group", units="")
grid.add_ones(name, at="group", units="")
grid.add_zeros(name, at="group", units="")
“group” is one of ‘node’, ‘link’, ‘cell’, ‘face’, ‘corner’, ‘junction’, ‘patch’
“name” is a string giving the field name
“units” (optional) is a string denoting the units associated with the field values.
Field creation from existing data#
grid.add_field(name, value_array, at="group", units="", copy=False, clobber=True)
Arguments as above, plus:
“value_array” is a correctly sized numpy array of data from which you want to create the field.
“copy” (optional) if True adds a copy of value_array to the field; if False, creates a reference to value_array.
“clobber” (optional) if False, raises an exception if a field called name already exists.
Field access#
grid.at_node
orgrid['node']
grid.at_cell
orgrid['cell']
grid.at_link
orgrid['link']
grid.at_face
orgrid['face']
grid.at_corner
orgrid['corner']
grid.at_junction
orgrid['junction']
grid.at_patch
orgrid['patch']
Each of these is then followed by the field name as a string in square brackets, e.g.,
>>> grid.at_node['my_field_name'] #or
>>> grid['node']['my_field_name']
You can also use these commands to create fields from existing arrays,
as long as you don’t want to take advantage of the added control add_field()
gives you.
Getting information about fields#
Landlab offers a command line interface that lets you find out about all the fields that are in use across all the Landlab components. You can find out the following:
$ landlab used_by [ComponentName]
# What fields does ComponentName take as inputs?
$ landlab provided_by [ComponentName]
# What fields does ComponentName give as outputs?
$ landlab uses [field__name]
# What components take the field field__name as an input?
$ landlab provides [field__name]
# What components give the field field__name as an output?
$ landlab list
# list all the components
$ (landlab provided_by && landlab used_by)  sort  uniq
# some command line magic to see all the fields currently used in components
Representing Gradients in a Landlab Grid#
Finitedifference and finitevolume models usually need to calculate spatial gradients in one or more scalar variables, and often these gradients are evaluated between pairs of adjacent nodes. ModelGrid makes these calculations easier for programmers by providing builtin functions to calculate gradients along links and allowing applications to associate an array of gradient values with their corresponding links or edges. The tutorial examples illustrate how this capability can be used to create models of processes such as diffusion and overland flow.
Here we simply illustrate the method for calculating gradients on the links. Remember that we have already created the elevation array z, which is also accessible from the elevation field on mg.
>>> gradients = mg.calculate_gradients_at_active_links(z)
Now gradients have been calculated at all links that are active, or links on which flow is possible (see boundary conditions below).
Other Grid Elements#
The cell vertices are called corners (Figure 1, solid squares <basic_grid_elements>). Each face is therefore a line segment connecting two corners. The intersection of a face and a link (or directed edge) is known as a junction (Figure 1, open diamonds). Often, it is useful to calculate scalar values (say, ice thickness in a glacier) at nodes, and vector values (say, ice velocity) at junctions. This approach is sometimes referred to as a staggeredgrid scheme. It lends itself naturally to finitevolume methods, in which one computes fluxes of mass, momentum, or energy across cell faces, and maintains conservation of mass within cells. (In the spring 2015 version of Landlab, there are no supporting functions for the use of junctions, but support is imminent.)
Notice that the links also enclose a set of polygons that are offset from the cells. These secondary polygons are known as patches (Figure 1, dotted). This means that any grid comprises two complementary tesselations: one made of cells, and one made of patches. If one of these is a Voronoi tessellation, the other is a Delaunay triangulation. For this reason, Delaunay triangulations and Voronoi diagrams are said to be dual to one another: for any given Delaunay triangulation, there is a unique corresponding Voronoi diagram. With ModelGrid, one can create a mesh with Voronoi polygons as cells and Delaunay triangles as patches (Figure 1b). Alternatively, with a raster grid, one simply has two sets of square elements that are offset by half the grid spacing (Figure 1a). Whatever the form of the tessellation, ModelGrid keeps track of the geometry and topology of the grid. patches can be useful for processes like calculating the mean gradient at a node, incorporating influence from its neighbors.
Managing Grid Boundaries#
An important component of any numerical model is the method for handling boundary conditions. In general, it’s up to the application developer to manage boundary conditions for each variable. However, ModelGrid makes this task a bit easier by tagging nodes that are treated as boundaries (boundary nodes) and those that are treated as regular nodes belonging to the interior computational domain (core nodes). It also allows you to deactivate (“close”) portions of the grid perimeter, so that they effectively act as walls.
Let’s look first at how ModelGrid treats its own geometrical boundaries. The outermost elements of a grid are nodes and links (as opposed to corners and faces). For example, Figure 2 shows a sketch of a regular fourrow by fivecolumn grid created by RasterModelGrid. The edges of the grid are composed of nodes and links. Only the inner six nodes have cells around them; the remaining 14 nodes form the perimeter of the grid.
All nodes are tagged as either boundary or core. Those on the perimeter of the grid are automatically tagged as boundary nodes. Nodes on the inside are core by default, but it is possible to tag some of them as boundary instead (this would be useful, for example, if you wanted to represent an irregular region, such as a watershed, inside a regular grid). In the example shown in Figure 2, all the interior nodes are core, and all perimeter nodes are open boundary.
Boundary nodes are flagged as either open or closed, and links are tagged as either active or inactive (Figure 3).
A closed boundary is one at which no flux is permitted enter or leave, ever. By definition, all links coming into or out of a closed boundary node must be inactive. There is effectively no value assigned to a closed boundary; it will probably have a grid.BAD_INDEX_VALUE or null value of some kind. An open boundary is one at which flux can enter or leave, but whose value is controlled by some boundary condition rule, updated at the end of each timestep.
An active link is one that joins either two core nodes, or one core and one open boundary node (Figure 3). You can use this distinction in models to implement closed boundaries by performing flow calculations only on active links, as seen in this tutorial.
Boundary condition details and methods#
A call to mg.node_status returns the codes representing the boundary condition of each node in the grid. There are 5 possible types, they are stored on the model grid:
mg.BC_NODE_IS_CORE (Type 0)
mg.BC_NODE_IS_FIXED_VALUE (Type 1)
mg.BC_NODE_IS_FIXED_GRADIENT (Type 2)
mg.BC_NODE_IS_LOOPED (Type 3, used for looped boundaries)
mg.BC_NODE_IS_CLOSED (Type 4)
A number of different methods are available to you to interact with (i.e., set and update) boundary conditions at nodes. Landlab is smart enough to automatically initialize new grids with fixed value boundary conditions at all perimeters and core nodes for all interior nodes, but if you want something else, you’ll need to modify the boundary conditions.
If you are working with a simple Landlab raster where all interior nodes are core and all perimeter nodes are boundaries, you will find useful the set of commands:
mg.set_closed_boundaries_at_grid_edges(right, top, left, bottom)
mg.set_fixed_value_boundaries_at_grid_edges(right, top, left, bottom)
mg.set_fixed_link_boundaries_at_grid_edges(right, top, left, bottom, link_value=None)
mg.set_looped_boundaries(top_bottom_are_looped, left_right_are_looped)
Where right, top, left, bottom are all booleans. See the relevant docstring for each method for more detailed information.
If you are working with an imported irregularly shaped raster grid, you can close nodes which have some fixed NODATA value in the raster using:
mg.set_nodata_nodes_to_closed(node_data, nodata_value)
Note that all of these commands will treat the status of node links as slave to the status of the nodes, as indicated in Figure 3. Links will be set to active or inactive according to what you set the node boundary conditions as, when you call each method.
If you are working on an irregular grid, or want to do something more complicated
with your raster boundary conditions, you will need to modify the
grid.status_at_node
array by hand, using indexes to node IDs. Simply import the
boundary types from landlab then set the node statuses. The links will be updated
alongside these changes automatically:
>>> grid = RasterModelGrid((5,5))
>>> grid.set_closed_boundaries_at_grid_edges(False, True, False, True)
>>> grid.number_of_active_links
18
>>> grid.status_at_node[[6, 8]] = mg.BC_NODE_IS_CLOSED
>>> grid.status_at_node.reshape((5,5))
array([[4, 4, 4, 4, 4],
[1, 4, 0, 4, 1],
[1, 0, 0, 0, 1],
[1, 0, 0, 0, 1],
[4, 4, 4, 4, 4]], dtype=int8)
>>> grid.number_of_active_links # links were inactivated automatically when we closed nodes
12
Note that while setting Landlab boundary conditions on the grid is straightforward, it is up to the individual developer of each Landlab component to ensure it is compatible with these boundary condition schemes! Almost all existing components work fine with core, closed, and fixed_value conditions, but some may struggle with fixed_gradient, and most will struggle with looped. If you’re working with the component library, take a moment to check your components can understand your implemented boundary conditions! See the Component Developer’s Guide for more information.
Using a Different Grid Type#
As noted earlier, Landlab provides several different types of grid. Available grids (as of this writing) are listed in the table below. Grids are designed using Python classes, with more specialized grids inheriting properties and behavior from more general types. The class hierarchy is given in the second column, Inherits from.
Grid type 
Inherits from 
Node arrangement 
Cell geometry 



raster 
squares 


Delaunay triangles 
Voronoi polygons 


Delaunay triangles 
Voronoi polygons 


triagonal 
hexagons 


concentric 
Voronoi polygons 


ad libitum 
No cells 
landlab.grid.raster.RasterModelGrid
gives a regular (square) grid, initialized
with number_of_node_rows, number_of_node_columns, and a spacing.
In a landlab.grid.voronoi.VoronoiDelaunayGrid
,
a set of node coordinates
is given as an initial condition.
Landlab then forms a Delaunay triangulation, so that the links between nodes are the
edges of the triangles, and the cells are Voronoi polygons.
A landlab.grid.framed_voronoi.FramedVoronoiGrid
is Voronoi grid where nodes coordinates are randomly moved from an initial rectangular regular grid.
A landlab.grid.hex.HexModelGrid
is a
special type of VoronoiDelaunayGrid in which the Voronoi cells happen to be
regular hexagons.
In a landlab.grid.radial.RadialModelGrid
, nodes are created in concentric
circles and then connected to
form a Delaunay triangulation (again with Voronoi polygons as cells).
Importing a DEM#
Landlab offers the methods
landlab.io.esri_ascii.read_esri_ascii
and
landlab.io.netcdf.read_netcdf
to allow ingestion of
existing digital elevation models as raster grids.
read_esri_ascii allows import of an ARCmap formatted ascii file (.asc or .txt) as a grid. It returns a tuple, containing the grid and the elevations in Landlab ID order. Use the name keyword to add the elevation to a field in the imported grid.
>>> from landlab.io import read_esri_ascii
>>> (mg, z) = read_esri_ascii("myARCoutput.txt", name="topographic__elevation")
>>> mg.at_node.keys()
['topographic__elevation']
read_netcdf allows import of the open source netCDF format for DEMs. Fields will
automatically be created according to the names of variables found in the file.
Returns a landlab.grid.raster.RasterModelGrid
.
>>> from landlab.io.netcdf import read_netcdf
>>> mg = read_netcdf("mynetcdf.nc")
After import, you can use landlab.grid.base.ModelGrid.set_nodata_nodes_to_closed
to handle the boundary conditions in your imported DEM.
Equivalent methods for output are also available for both esri ascii
(landlab.io.esri_ascii.write_esri_ascii
)
and netCDF
(landlab.io.netcdf.write_netcdf
) formats.
Plotting and Visualization#
Visualizing a Grid#
Landlab offers a set of matplotlibbased plotting routines for your data. These exist
in the landlab.plot library. You’ll also need to import some basic plotting functions
from pylab (or matplotlib) to let you control your plotting output: at a minimum show
and figure. The most useful function is called
landlab.plot.imshow.imshow_node_grid
, and is imported
and used as follows:
>>> from landlab.plot.imshow import imshow_node_grid
>>> from pylab import show, figure
>>> mg = RasterModelGrid((50, 50), 1.) # make a grid to plot
>>> z  mg.node_x * 0.1 # Make an arbitrary sloping surface
>>> mg.add_field("topographic_elevation", z, at="node", units="meters", copy=True) # Create the data as a field
>>> figure('Elevations from the field') # new fig, with a name
>>> imshow_node_grid(mg, 'topographic_elevation')
>>> figure('You can also use values directly, not fields') # ...but if you, do you'll lose the units, figure naming capabilities, etc
>>> imshow_node_grid(mg, z)
>>> show()
Note that landlab.plot.imshow.imshow_node_grid
is clever enough to examine the grid object you pass it,
work out whether the grid is irregular or regular, and plot the data appropriately.
By default, Landlab uses a Python colormap called ‘pink’. This was a deliberate choice to improve Landlab’s userfriendliness to the colorblind in the science community. Nonetheless, you can easily override this color scheme using the keyword cmap as an argument to imshow_node_grid. Other useful built in colorschemes are ‘bone’ (black to white), ‘jet’, (blue to red, through green), ‘Blues’ (white to blue), and ‘terrain’ (bluegreenbrownwhite) (note these names are case sensitive). See the matplotlib reference guide for more options. Note that imshow_node_grid takes many of the same keyword arguments as, and is designed to resemble, the standard matplotlib function imshow. See also the method help for more details. In particular, note you can set the maximum and minimum you want for your colorbar using the keywords vmin and vmax, much as in similar functions in the matplotlib library.
Note if using Anaconda: there have been documented issues with resolution with default inline plotting within the Spyder IDE iPython console. To generate dynamic plots (e.g. Matlablike plots), change the graphics settings in Spyder by following this work flow:
In Spyder > Preferences > iPython console > Graphics > Graphics Backend > Automatic > Apply > OK > Make sure to restart Spyder to update the preferences.
Visualizing transects through your data#
If you are working with a regular grid, it is trivial to plot horizontal and vertical
sections through your data. The grid provides the method
landlab.grid.raster.RasterModelGrid.node_vector_to_raster
,
which will turn a Landlab 1D node data array into a two dimensional rows*columns NumPy array,
which you can then take slices of, e.g., we can do this:
>>> from pylab import plot, show
>>> mg = RasterModelGrid((10, 10), 1.)
>>> z = mg.node_x * 0.1
>>> my_section = mg.node_vector_to_raster(z, flip_vertically=True)[:,5]
>>> my_ycoords = mg.node_vector_to_raster(mg.node_y, flip_vertically=True)[:,5]
>>> plot(my_ycoords, my_section)
>>> show()
Visualizing river profiles#
See the ChannelProfiler
component.
Making Movies#
Landlab does have an experimental movie making component. However, it has come to the
developers’ attention that the matplotlib functions it relies on in turn demand that
your machine already has installed one of a small set of highly temperamental open
source video codecs. It is quite likely using the component in its current form is
more trouble than it’s worth; however, the brave can take a look at the library
landlab.plot.video_out
. We intend to improve
video out in future Landlab releases.
For now, we advocate the approach of creating an animation by saving separately
individual plots from, e.g., plot() or
landlab.plot.imshow.imshow_node_grid
,
then stitching them together
into, e.g., a gif using external software. Note it’s possible to do this directly from
Preview on a Mac.
The Component Library#
Landlab offers an evergrowing library of components that aim to describe individual or closely associated suites of surface processes. Components are designed to be “plugandplay” and to interact with each other with the minimum of technical difficulties. Each component makes use of Landlab grid fields to enable the sharing of data between the components, and we aim to have a relatively standardized way of interacting with and using each different one.
Landlab components exist as classes, and can be imported from
landlab.components
.
To develop your own Landlab component, see this page and this tutorial.
Component Library Tutorial#
For a tutorial introduction to using the component library, see here.
Available Landlab components#
For the complete list of Landlab components type the following command in a command prompt:
landlab list
See the Components section of the Landlab reference manual for a list of all Landlab components currently available.
Landlab component classes, their import, and their instantiation#
Almost all Landlab components exist as Python classes. This means that to use
them, you must first import the class, then instantiate
a Python instance
of that class, then call a method from the class to run the component. The way
this is done has now been almost totally standardised across Landlab.
A component class is imported from the library as
from landlab.components import [ComponentClass]
e.g., to get the linear diffusion component, we would do:
from landlab.components import LinearDiffuser
The available components are listed in the Components section of the Landlab Reference Manual.
Component classes always take a copy of the grid as their first argument. They then take a sequence of additional keyword arguments that set the actual parameters for the component. This means that the instantiation of a component looks something like this:
dfn = LinearDiffuser(grid, linear_diffusivity=0.01)
These keywords can also be set by passing a Python dictionary, or using a text input file (see below).
Here, dfn is now the component object—an “instance” of the component. We can run it by calling its run method. The component’s documentation will explain how to do this for each individual case, but typically a component will have a method called run_one_step, which can be called like this:
dt = 100. # the timestep
dfn.run_one_step(dt)
If the component describes a timevarying process, the first argument of run_one_step will be the duration for which to run the component in this timestep. (If the component is not time sensitive, e.g., the FlowRouter, it won’t take dt). Some components may also allow/require additional input parameters to their run method; see individual component documentation for more details.
Running one of these methods will update the fields held in common by the single grid object which you linked to all your components during component instantiation. If you look inside the grid fields having run one of these methods, you’ll see the new fields it has created and populated. The docstrings for the component should make it clear which fields the component needs to have in the grid as inputs, and which it modifies and/or creates as outputs.
It should probably be emphasized here to always read the documentation for the component you are using! You can get at this documentation either on this website, or in a dynamic Python session by getting help for either the imported class or the instantiated component object. i.e., in this case, any of the following would work:
.. codeblock:: python
>>> help(LinearDiffuser)
>>> help(dfn)
>>> LinearDiffuser?
>>> dfn?
Quit interactive help in iPython by pressing “q”.
Inputs to components#
Landlab components are initialized by passing a copy of the grid, then by passing additional dynamic Python keyword arguments, almost all of which are set to default values if a value is not provided. This means all of the ways that you could call any other Python function using keywords also applies to our components.
Most simply, components can be initialized by passing only the keyword values that need to deviate from the defaults. So, for example, the default parameter values for the FastscapeEroder are K_sp=None, m_sp=0.5, n_sp=1., threshold_sp=0., rainfall_intensity=1.. So if I want to set the K_sp to, say, 1.e6, but I am happy with these other parameters, I can simply do:
fsc = FastscapeEroder(grid, K_sp=1.e6)
Because Landlab components make use of Python’s native **kwargs argument syntax, we can also pass multiple keywords at once to a component using a Python dictionary:
sp_thresholds = grid.add_ones('node', 'sp_thresholds')
myargs = {'K_sp': 1.e5, 'rainfall_intensity': 0.5, 'threshold_sp': sp_thresholds}
fsc = FastscapeEroder(grid, **myargs)
Note the “magic” ** decorator that is placed on the dictionary when it is passed to the component that makes this work. Also note that we can allow the component default values to continue to set any keywords we still don’t want to supply, and that as long as the component permits it, we can pass in arrays or field names like this too (see, e.g., threshold_sp above). You can have all of your input parameters for all components in one dictionary if you so wish; components will ignore any keywords they are passed that they don’t recognize.
Note that Landlab components will raise an error if they are passed keyword arguments that they do not need.
Landlab components always want to see a Python dictionary as their input, as illustrated above. However, Landlab does offer a native file reader called load_params that allows you to create dictionaries to pass to components from input files. This function recognizes both “yaml” formatted data files, e.g.,
K_sp: 0.3
m_sp: 0.5
n_sp: 1.
linear_diffusivity: 0.0001
The load_params method will figure out which to use by itself, and will do any necessary typecasting automatically (i.e., floats will be floats, not strings):
from landlab import load_params
my_input_dict = load_params('./mytextinputfile.txt')
dfn = FastscapeEroder(grid, **my_input_dict)
Component standard properties#
All Landlab components offer a standardized interface. This provides automated information on the fields, units, etc. that the component works with, creates, and/or modifies. For a fully compliant component, you will find you can call the following methods and attributes.
Property 
Description 

a string 

a tuple giving input field names 

a tuple giving output field names 

a tuple of (var_name, [‘node’, ‘link’, etc]) 

a tuple of pairs of (var_name, short description) 

a tuple of (var_name, [‘m’, ‘Pa’, etc]) 

method to return the unit of ‘field’ 

method to return a short description of ‘field’ 

method to return the element of ‘field’ (e.g., ‘node’) 

method to return dtype of ‘field’ (e.g., float) 

a text summary of all of this information for ‘field’ 
See the tutorials for examples of use cases with one, two, and more coupled components.
You can also get an overview of field usage by all components through Landlab’s command line interface. See here for more information.
Landlab standard naming conventions#
The Landlab component library attempts to make use of a relatively standardized set of names across the various components, in order to maximize ease of component coupling. If you’re familiar with the concept of the CSDMS standard naming conventions, note that we have tried to strike a balance between the rigor and uniqueness of those names and a more userfriendly, succinct approach. Nonetheless, you may recognize the basic style of the names:
thing_described__what_is_described
e.g., topographic__elevation, water_surface__gradient, water__volume_flux
We compile three tables to assist users with the Landlab standard names.
First is a list of all names with their definitions.
Second is a table listing which components use each field.
Third is a table listing which components provide each field.
See here for a list of changes to the standard name list associated with the release of Landlab version 1.x (relative to 0.x).
Dealing with nonstandard names#
The large number of developers on Landlab and historical accident have meant that despite our best efforts you’ll inevitably find instances where different components use different names for the same thing. In these cases, you need to make equivalent two fields in the grid which have different names so that two components can talk to each other. This is actually easy; you can just do:
>>> mg.add_field('node', 'second_name', mg.at_node['first_name'])
Note that we are making slow progress towards truly standardizing the component library, but these kind of idiosyncrasies might yet persist for a while!
What goes into a Landlab model?#
In the previous section, Grid we showed you most of the core functionality of the Landlab grid. In this section, we introduce you to how to actually use it to build models and work with the Landlab component library.
Using Landlab requires that you build a Python script to import, instantiate, and then run your landscape model. We describe such a script as a driver. It’s also possible to do the same set of processes on the fly in an interactive Python environment like iPython.
Typically, a driver file will consist of six distinct sections:
Import the Python and Landlab libraries you’ll need to run your model
Instantiate the Landlab elements (grid and, if using them, components)
Load any necessary data into the grid fields
Set the boundary conditions
Run the model, typically by creating a for loop or using a Landlab generator (see below)
Finalize and handle the data (e.g., plot, export)
Beyond the driver, if you’re using Landlab components, you’ll probably also need
a parameter file. This file supplies the components with the additional
parameter and setup information they need. Landlab parameter files are text
files .txt
, have fixed format, and for convenience (so you only have to
specify the minimum of path information in the file name) should be placed in
the same folder as the driver file. Find out more about parameter files
here. However, if you’re not using components, there’s little need
to create a parameter file; you can just directly pass other parameters to the grid
in the driver.
A brief introduction to components#
A key strength of Landlab is that not only is it designed to make implementing your own process simulations as simple as possible, but it also offers an offtheshelf library of predesigned process descriptions that you can use in your drivers. We call these process simulators Landlab components. The intention is that each component be:
Plugandplay
Interoperable with all other components
Implementable in your driver in only one or two lines of code
By no means is using the component library necessary or even always desirable when working with Landlab. However, we hope that components will dramatically reduce the time investment needed to implement a wide variety of modeling scenarios. In particular, components should make producing models that couple more than one process significantly easier because existing, offtheshelf components can be slotted in alongside novel process descriptions.
A list of the current components is found within the Reference guide components section.
Note that not all components will run under all conditions, but any limitations should be made clear in the documentation associated with that component.
In particular, some components may demand you are running on a regular grid. It should probably also be emphasized that most of these components are still under active development within this beta release of Landlab, and may behave in idiosyncratic ways or be subject to sudden changes with little or no warning. In all cases, before setting out on any major research challenges using a component, we’d recommend contacting the original coder of the component to let them know they have external users to think about!
Implementing a Landlab driver#
As noted above, the process of creating a driver is essentially equivalent whether you want to implement Landlab components, purely use your own code, or combine some mixture of the two. Here we take a closer look at the various steps.
1. Import the libraries and functions you need#
Landlab handles a lot like NumPy, and like NumPy you’ll need to import the various libraries and functions that you’ll want to use. At the very least, we suspect you’ll need from outside Landlab:
NumPy itself
rudimentary Pylab plotting routines: plot, show, figure
Also useful can be:
the Python module time, to time various parts of your code elements
from SciPy, the scientific computing library. Lots of useful methods (e.g., matrix solutions, curve fitting) can be found in here, to avoid reinventing the wheel.
From inside Landlab, you’ll also need:
A grid class—choose from
RasterModelGrid
,landlab.grid.voronoi.VoronoiDelaunayGrid
, or some of the more specialized classes listed on the grid documentation page.Any components you want to run
Any Landlab utilities you need, such as plotters (
imshow_grid
) or io functions.
A specific example might be:
import numpy as np
from pylab import show, figure, plot
import time
from landlab import RasterModelGrid
from landlab.components import FlowAccumlator
from landlab.plot.imshow import imshow_node_grid
2. Instantiate objects#
As noted in previous sections, Landlab is coded in an objectoriented style. This means that we need to “instantiate” the various Landlab objects such as the grid and the components that we will use to store data and run the model.
Note that most components require the grid object be passed to them as one of their arguments during instantiation, so the first thing you’ll want to instantiate will be the grid.
Check the docstrings for each class (grid, component) you want to instantiate for a detailed description of what you need to supply as arguments.
For a RasterModelGrid, this will be ((i, j), [node_spacing])
. Here, (i, j)
is a tuple where i is the number of rows and j the number of columns, and node_spacing
is an optional second tuple or float. If you want uniform node spacing in the y and x directions, use a float, otherwise use a tuple to specify (dy, dx)
if you want them to be different (see example immediately below). Spacing will default to (1., 1.). [Landlab also recognizes an older style of RasterModelGrid signature, which looks like (number_of_node_rows, number_of_node_columns, node_spacing(optional))
, and is clever enough to work with this form.] For a VoronoiDelaunayGrid, the signature will be (array_of_node_x_coords, array_of_node_y_coords)
. For a generic component, it will typically be (ModelGrid, 'path_to_parameter_file.txt')
, though there may be some variation, and optional inputs may also be available.
Give each object you instantiate a variable name. We like mg
for ModelGrid
objects and some appropriate abbreviation for a component.
An example might be:
mg = RasterModelGrid((10, 10), xy_spacing(1., 2.)) # 100 nodes, dy=1., dx=2.
fr = FlowAccumlator(mg)
3. Load/create data in fields#
(See this section if you don’t know what a Landlab field is.)
Now we need some data to work with. Here we’ll assume that you’re going to be working with a DEMstyle elevation map across the nodes of the grid, but similar considerations would apply for any other type of data.
You will likely be in one of two situations regarding the initial data you want to put on the grid—either you will have some external data source that you want to load in and use as your initial conditions (e.g., a DEM of some basin, or some other real topography), or you want to set up some simple analytical initial condition like a flat surface with noise or an inclined surface.
In both cases, we advocate a two step process: creating a NumPy array of the data, then loading it into the grid as a field. We can illustrate both of the above cases:
mg = RasterModelGrid((10, 10), 1.) # make a grid
z = np.zeros(100, dtype=float) # make a flat surface, elev 0
# or…
z = mg.node_y*0.01 # a flat surface dipping shallowly south
# add a little noise to the surface:
z += np.random.rand(100.)/10000.
# create the field:
mg.add_field('node', 'topographic__elevation', z, units='m')
Alternatively, we can use the specialized Landlab function
read_esri_ascii
to import an ascii raster that can be output from ARC. Note this function both
creates the grid for you and loads the data as a field if you provide name
.
If not, you’ll have to load the data output (z, below) manually
from landlab.io import read_esri_ascii mg, z = read_esri_ascii('my_ARC_output.asc', name='topographic__elevation') np.all(mg.at_node['topographic__elevation'] == z)
Note that if you don’t want to use any Landlab components, you can continue to work with data as “free floating” NumPy arrays, and can ignore the fields (e.g., see this simple introductory tutorial).
4. Set the boundary conditions#
Once you have a grid and the initial condition data you’ll need, it’s time to set the boundary conditions. If you’re working with a raster, or some preexisting imported data, this is very straightforward using the built in RasterModelGrid functions. For a raster where only the edges are to be boundary nodes
mg.set_fixed_value_boundaries_at_grid_edges(False, True, False, True) mg.set_closed_boundaries_at_grid_edges(True, False, True, False)
This will give a grid with fixed value boundaries at the left and right edges, and closed boundaries at the top and bottom.
If you’re working with, say, an ARC imported array with a null value on the closed nodes (e.g., 9999), you can do this
mg.set_nodata_nodes_to_closed(mg.at_node['topographic__elevation'], 9999)
(Be aware that you’re still likely to have to reopen an outlet node manually! In which case you’ll also need to follow the instructions below.)
If you’re working with individual node’s boundary statuses, you’ll need to set the boundary conditions by hand. This means individually modifying the boundary condition status of each node or link that you want to be of the new type. Fortunately, Landlab uses some Python magic to make sure that when you update, for example, the status of a node, the statuses of attached links and cells change concomitantly. For example
# find the ID of the lowest elevation core node. # we'll make this a fixed gradient outlet: outlet_id = mg.core_nodes[np.argmin(mg.at_node['topographic__elevation'][mg.core_nodes])] # show there are no links with *mg.BC_LINK_IS_FIXED* boundary conditions in the grid yet: np.any(mg.status_at_link==mg.BC_LINK_IS_FIXED) # update the outlet node: mg.status_at_node[outlet_id] = mg.BC_LINK_IS_FIXED np.any(mg.status_at_link==mg.BC_LINK_IS_FIXED) # the corresponding link has been automatically updated.
5. Run the model#
We’re now ready to actually implement a run of our model! Most things you might want to do with Landlab are probably timesensitive, so in almost all cases, you’ll probably be placing the guts of your simulation inside a loop of some sort. In simple cases, you can just use some variation on a simple for loop or while statement, either:
dt = 10.
for tstep in xrange(100):
#...do the thing for one timestep dt
or:
dt = 10.
accumulated_time = 0.
while accumulated_time<1000.:
#...do the thing for one timestep dt
accumulated_time += dt
Both produce 1000 time units of run, with an explicit timestep of 10. Notice that the latter technique is particularly amenable to situations where your explicit timestep is varying (e.g., a storm sequence). (For more on time steps in numerical models see the Time Steps page.)
Landlab also however has a built in storm generator component,
PrecipitationDistribution
,
which (as its name suggests) acts as a true Python generator. The main method is
yield_storm_interstorm_duration_intensity
.
This means producing a storm series in Landlab is also very easy:
from landlab.components.uniform_precip import PrecipitationDistribution
time_to_run = 500000.
precip_perturb = PrecipitationDistribution(input_file=input_file_string, total_t=time_to_run)
for (interval_duration, rainfall_rate) in precip_perturb.yield_storm_interstorm_duration_intensity():
if rainfall_rate != 0.:
# ...do the thing, making sure to pass it the current
# interval_duration and rainfall_rate
Notice that the advantage of the generator is that it just stops when the desired number of events/time duration has expired! See the end of this tutorial for an example of this generator in action.
What exactly “…do the thing” consists of is up to you. You can either design your own operations to do in the loop for yourself, or you can implement processes from Landlab’s component library. See here for more information on using the components.
6. Finalize and handle the data#
Once the looping is complete, the model is effectively finished. However, you will still need to output the data somehow! Some options include:
Save or export the data#
If you’re using a raster grid, you can easily save your grid output to either ESRI ascii (i.e., ARCmap) or open source netCDF formats. netCDF in particular is a powerful format, and allows easy subsequent reloading of a Landlab modelgrid and all its fields. Save your raster like this:
rmg.save('my_savename.asc', names=['field1','field2'])
# for esri ascii, only saving the fields 1 and 2
or:
rmg.save('my_savename.nc')
# save as netCDF3, saving all fields by default
The former way will give two save files, my_savename_field1.asc
and
my_savename_field2.asc
. The latter will just give my_savename.nc
.
To reload a netCDF file, use the Landlab io function
read_netcdf
from landlab.io.netcdf import read_netcdf
mg = read_netcdf('my_savename.nc')
Note all the original fields you had will automatically be repopulated.
If you’re using an irregular grid, the simple grid save function is not yet operational (though is under development). Instead, we recommend using Pickle, a native Python way of saving (“pickling”) any Python object. It works like this:
>>> import cPickle as pickle
# cPickle is a lot faster than normal pickle
>>> pickle.dump( mg, open('my_savename.pickle', 'wb') )
# ...save the grid, and all its fields
>>> mg = pickle.load( open('my_savename.pickle', 'rb') )
# ...load the grid and fields back into a grid object
Unfortunately, the power of pickle comes somewhat at the expense of both disk space and speed. Saves this way can be slow and, if the grid is big, memory expensive (e.g., ~1 Gb for millions of nodes).
You can also use lower level, NumPy save routines to preserve just your data
(rather than the whole grid object). The NumPy methods save
and savetxt
and load
and loadtxt
can be called on any NumPy array, including those
saved as fields. Save and load use the NumPy specific .npy
file format;
savetxt
and loadtxt
use textfiles
. Use them like this:
>>> np.save('savename.npy', mg.at_node['my_field'])
>>> mg.at_node['my_field'] = np.load('savename.npy')
>>> np.savetxt('savename.txt', mg.at_node['my_field'])
>>> mg.at_node['my_field'] = np.loadtxt('savename.txt')
Plot the data#
Landlab has a fairly comprehensive suite of built in plotting functions; read more about them here.
You also of course have the option of using the matplotlib plotting library of Python for things like crosssections.
If you’re careful, you can also build plotting functions into the body of a run loop for your model, so you can see how your output evolves through time. Note however that all Python save and plot functions are considerably time expensive, so it would probably be a bad idea to do this kind of thing every timestep. Instead, you can try something like:
import plot
dt = 10.
accumulated_time = 0.
last_accumulated_time_remainder = 0.
while accumulated_time<1000.:
#...do the thing for one timestep dt
accumulated_time += dt
if last_accumulated_time_remainder < accumulated_time%100.: # output every 100.
plot(mg.node_vector_to_raster(z)[mg.number_of_node_rows//2,:]) # a cross section
last_accumulated_time_remainder = accumulated_time%100.
show()
Note that if you’re running inside an interactive Python session like iPython, all the variables and objects (both grid and component) that you’ve used in your model will still be available in the environment. Thus, you can play with your data for as long as you want!
Animating figures#
Due to issues surrounding platformdependent video codecs, Landlab does not currently
support native video or animated output. However, numerous effective hacks using free
third party software can be effective. We recommend saving your figure for animation
at the desired frame interval using the matplotlib savefig
command, then
stitching these images together into a video file externally.
DEJH has had a lot of success doing this in Preview on a Mac (which has the great
advantage that it is always available). Simply open the first image, go to Export...
under file, then while holding down alt click on the Format
button to gain
access to a list of extra formats, including .gif
. Open your new gif file, also
in preview, then just drag the remaining image files into the sidebar onto the first
slide, where they will be appended to the gif as individual frames. Save, and you
will now have an animated gif of your output (note you’ll have to open the file in a
browser or drag it into Powerpoint to get it to run  for mysterious reasons,
Preview always opens the frames as images, and cannot show the gif running!).
How Landlab Is/Is Not Unit Agnostic#
This page describes how Landlab handles units. Our approach is intended to balance usability, effective communication of component expectations to users, and a low barrier for developers.
Component inputs and outputs with units may be fields (arrays stored on the grid), or arguments/keyword arguments to the component instantiation and run functions.
All components require that a user is consistent between the space/time/mass
units used within one and across multiple components. For example, if you were
to couple a StreamPowerEroder
and a LinearDiffuser
your x, y, and z
coordinates, the field topographic__elevation and all input parameters would
need to share a common length unit. Further, input parameters with units that
include time and your time step would need to share a common time unit.
Components that require that you are consistent with units but do not care
whether you use feet or meters for your length unit are called “unit agnostic”.
You can find out if a component is unit agnostic by querying the attribute:
Component.unit_agnostic
which will return True
or False
.
Unit agnostic components will provide specific units in the field and parameter metadata. However, no computation within a unit agnostic component assumes a specific unit. If you provide a consistent set of inputs, you can use whichever units you prefer. Note that this may require specifying ALL keyword arguments (e.g., if gravitational acceleration as 9.81 m/s^2 is a default value, you must provide 32.2 ft/s^2 as an input if you want to use feet as your length unit).
In contrast to unitagnostic components, nonunitagnostic components REQUIRE that a specific set of units be used. This typically occurs because built into the source code of the computation are assumptions or conversions about the units of inputs.
When it doubt, the best approach is to open a GitHub issue.
Below is a list of nonunit agnostic components:
Tutorials#
The Landlab Tutorials provide examples of Landlab core concepts and component introductions. Tutorials exist as interactive Jupyter notebooks that contain alternating cells of computer code and text that explain the code. In addition to Landlab Tutorials that exemplify Landlab, notebooks intended to teach and learn surface dynamics are the Landlab Teaching Tutorials.
Launch notebooks online#
Landlab Notebooks can be accessed online with the following link: Binder. Here the notebooks are provided within a binder online environment that includes Landlab.
The welcome page on Binder provides onward links to most of our tutorials. If you’re a newbie you might want to skip directly to a recommended syllabus for learning Landlab here.
Launch notebooks locally#
To run the tutorials locally, you will first need to install landlab on your computer. If you have not already done so, please see the landlab installation guide. Because several of the notebooks depend on packages that cannot be installed using pip, we recommend you use conda to install the tutorial notebook requirements.
Get the notebooks#
If you have the landlab source code, you already have the notebooks (they are in the notebooks/ folder).
If you don’t have a copy of the source code, you can run the notebooks.py script to fetch the set of notebooks that matches your version of landlab. This can be done either by running,
$ curl L https://raw.githubusercontent.com/landlab/landlab/mcflugen/fetchnotebooksscript/notebooks.py  python 
or by downloading the script and running the following from the terminal,
$ python m notebooks
Install dependencies#
The dependencies required to run the notebooks are listed in the file, requirementsnotebooks.txt and can be installed with conda,
$ conda install file=requirementsnotebooks.txt
Run the tutorials#
It’s now time to run the tutorials. Opening the welcome page is a good place to start but you can also open individual notebooks as well.
$ jupyter notebook notebooks/welcome.ipynb
Contributing new or modified tutorials#
If you write a Landlab Tutorial or Gist, please contribute it via a pull request to the master branch of the Landlab repository. See this page about contributing to Landlab, and reach out for help when needed.
Landlab clinics and workshops#
For more examples and tutorials, see also our Clinics & workshops page.
Teaching Tutorials#
Landlab teaching tools#
This page describes the Jupyter Notebooks that implement Landlab for use in teaching undergraduate and graduate courses. Jupyter Notebooks combine formatted text with code that can be run. Students can run small parts of code bit by bit as they follow along with the text.
The notebooks illustrate examples of physical processes implemented numerically. These notebooks are designed to teach about processes. The notebooks are not designed to teach students to code, or to teach students to use Landlab. No coding experience is needed to successfully carry out these activities  just the ability to read and a classroom introduction of the specific processes being illustrated.
The notebooks are primarily designed for use as homework assignments or laboratory assignments. However, they can be used to illustrate concepts onthefly in the classroom.
The easiest way to see what is in the notebooks is through the Binder welcome page for the teaching notebooks. This also allows you to run the notebooks online.
The notebooks can also be run locally by installing Landlab on your computer.
For an introduction to using Jupyter Notebooks locally, see this webpage. [Quick Summary: The way to launch a Jupyter notebook is to enter ‘jupyter notebook’ from a command line prompt. Jupyter notebooks can also be launched from within Anaconda.]
More information#
If you have suggestions on improving these notebooks and developing new ones, or are having trouble running them, please leave us a question in our GitHub Issues page. Please make sure you include that you are working with a Landlab Teaching Notebook and include the name of the notebook and as much information as possible. If you are getting an error, please taking a screenshot and upload it.
The development of these Notebooks has been made possible by the Landlab project funded by the National Science Foundation (OAC 1450338 to N. Gasparini, OAC 1450409 to G. Tucker, OAC 1450412 to E. Istanbulluoglu).
List of Components#
Calculate the location and magnitude of episodic bedrock landsliding. 

Calculate marine carbonate production and deposition. 

Extract and plot the channel profiles in drainage networks. 

Calculate Chi Indices. 

Find depressions on a topographic surface. 

This component implements a depth and slope dependent linear diffusion 

This component implements a depthdependent Taylor series diffusion rule, 


Calculate erosion rate as a function of the depthslope product. 
Simulate detachment limited sediment transport. 

Component that calculates dimensionless discharge of stream 


Diffuse sediment proportional to an implicit water discharge value. 
Calculate drainage density over a DEM. 

ErosionDeposition model in the style of Davy and Lague (2009). It uses a 

This component implements exponential weathering of bedrock on hillslopes. 

This component implements exponential weathering of bedrock on 

Fastscape stream power erosion. 

Generate a random fire event or time series. 

Deform the lithosphere with 1D or 2D flexure. 

Deform the lithosphere with 1D flexure. 

Component to accumulate flow and calculate drainage area. 

Singlepath (steepest direction) flow direction with diagonals on 

Flow direction on a raster grid by the D infinity method. 

Multiplepath flow direction with or without out diagonals. 

Singlepath (steepest direction) flow direction without diagonals. 

Create a 2D grid with randomly generated fractures. 

This is a Landlab wrapper for A Wickert’s gFlex flexure model (Wickert 

Model drainage network evolution for a network of transportlimited 

Simulate groundwater flow in a shallow unconfined aquifer. 

This component calculates Hack’s law parameters for drainage basins. 

Calculate the elevation difference between each node and its nearest 

This code is based on an overland flow model by Francis Rengers and 

Calculate shallow water flow over topography. 

Calculate water flow over topography. 

A Landlab implementation of the Barnes et al. (2014) lake filling & lake 

Landslide probability component using the infinite slope stability 

Laterally erode neighbor node through fluvial erosion. 

This component implements linear diffusion of a Landlab field. 

Calculate water flow over topography. 

Apply tectonic extension and subsidence kinematically to a raster or 

Create LithoLayers component. 

Create a Lithology object. 

Component to calculate drainage area and accumulate flow, while 

Move sediment parcels on a river network. 

NormalFault implements relative rock motion due to a normal fault. 

Simulate overland flow using de Almeida approximations. 

Simulate overland flow using Bates et al. (2010). 

Nonlinear diffusion, following Perron (2011). 

Potential Evapotranspiration Component calculates spatially distributed 

Multidirectional flow routing using a novel method. 

Generate precipitation events. 

Component to accumulate flow and calculate drainage area based RICHDEM software package. 

Extract and plot profiles set up using points within a grid. 

Compute 1D and 2D total incident shortwave radiation. 

This module implements sediment flux dependent channel incision 

Transport marine sediment using a waterdepthdependent diffusion model. 

This component identifies depressions in a topographic surface, then 

Uses the Barnes et al (2014) algorithms to replace pits in a topography 

Infiltrate surface water into a soil following the GreenAmpt method. 

Landlab component that simulates rootzone average soil moisture at each 

Stream Power with Alluvium Conservation and Entrainment (SPACE) 

Stream Power with Alluvium Conservation and Entrainment (SPACE) large scale eroder 

Generate spatially resolved precipitation events. 

Evolve life in a landscape. 

This component calculates steepness indices, sensu Wobus et al. 2006, 

Erode where channels are. 

Stream erosion component with smooth threshold function. 

Hillslope evolution using a Taylor Series expansion of the Andrews 

Threshold eroder. 

Component that calculates average flow over a tidal cycle. 

Transport length hillslope diffusion. 

Extract and a profile from one or more node IDs to their downstream termini. 

Landlab component that simulates interspecies plant competition using a 

Landlab component that simulates net primary productivity, biomass and 
List of Landlab Fields#
The following tables list all of the field names used by landlab components. The Used By tab lists component that use a given field (i.e. it is an input for the component), while the Provided By tab lists components that provide the field as output.
aquifer__thickness 
thickness of saturated zone 
aquifer_base__elevation 
elevation of impervious layer 
aquifer_base__gradient 
gradient of the aquifer base in the link direction 
area_coefficient 
Area coefficient to define channels. 
area_exponent 
Area exponent to define channels. 
average_surface_water__specific_discharge 
average surface water specific discharge over variable timesteps 
bedload_sediment__rate_of_loss_to_abrasion 
Rate of bedload sediment volume loss to abrasion per unit area 
bedload_sediment__volume_influx 
Volumetric incoming streamwise bedload sediment transport rate 
bedload_sediment__volume_outflux 
Volumetric outgoing streamwise bedload sediment transport rate 
bedrock__elevation 
elevation of the bedrock surface 
carbonate_production_rate 
Carbonate production rate 
carbonate_thickness 
Carbonate thickness 
channel__bed_shear_stress 
Shear exerted on the bed of the channel, assuming all discharge travels along a single, selfformed channel 
channel__chi_index 
the local steepness index 
channel__depth 
Depth of the a single channel carrying all runoff through the node 
channel__discharge 
Volumetric water flux of the a single channel carrying all runoff through the node 
channel__mask 
Logical map of at which grid nodes channels are present 
channel__steepness_index 
the local steepness index 
channel__width 
Width of the a single channel carrying all runoff through the node 
channel_bottom_sediment_grain__d50_diameter 
soil grain size average in stream segment 
channel_sediment__relative_flux 
The fluvial_sediment_flux_into_node divided by the fluvial_sediment_transport_capacity 
channel_sediment__volumetric_flux 
Total volumetric fluvial sediment flux brought into the node from upstream 
channel_sediment__volumetric_transport_capacity 
Volumetric transport capacity of a channel carrying all runoff through the node, assuming the MeyerPeter Muller transport equation 
channel_slope 
Slope of the river channel through each reach 
channel_width 
Flow width of the channel, assuming constant width 
channelization_threshold 
Channelization threshold for use with area and slope coefficients and exponents. 
cumulative_subsidence_depth 
Cumulative depth of tectonic subsidence 
depression__depth 
Depth of depression below its spillway point 
depression__outlet_node 
If a depression, the id of the outlet node for that depression, otherwise grid.BAD_INDEX 
depression_free_elevation 
Filled land surface topographic elevation, at closed borders, value equals 1! 
dimensionless_discharge 
Dimensionless discharge value for a stream segment. 
dimensionless_discharge_above_threshold 
True if dimensionless discharge value is above threshold value, false otherwise. 
dimensionless_discharge_threshold 
Dimensionless discharge threshold for each stream segment. 
distance_to_divide 
Distance from drainage divide. 
drainage_area 
Upstream accumulated surface area contributing to the node’s discharge 
ebb_tide_flow__velocity 
Horizontal flow velocity along links during ebb tide 
flood_status_code 
Map of flood status (_PIT, _CURRENT_LAKE, _UNFLOODED, or _FLOODED). 
flood_tide_flow__velocity 
Horizontal flow velocity along links during flood tide 
flow__data_structure_delta 
Node array containing the elements delta[1:] of the data structure ‘delta’ used for construction of the downstreamtoupstream node array 
flow__link_direction 
Direction of flow on link. A value of 1 indicates that water flow goes from head node to tail node, while a value of 1 indicates that water flow goes from tail node to head node. 
flow__link_to_receiver_node 
ID of link downstream of each node, which carries the discharge 
flow__potential 
Value of the hypothetical field ‘K’, used to force water flux to flow downhill 
flow__receiver_node 
Node array of receivers (node that receives flow from current node) 
flow__receiver_proportions 
Node array of proportion of flow sent to each receiver. 
flow__sink_flag 
Boolean array, True at local lows 
flow__upstream_node_order 
Node array containing downstreamtoupstream ordered list of node IDs 
flow_depth 
Flow depth of the channel 
fracture_at_node 
presence (1) or absence (0) of fracture 
groundwater__specific_discharge 
discharge per width in link dir 
groundwater__velocity 
velocity of groundwater in link direction 
height_above_drainage__elevation 
Elevation above the nearest channel node 
hill_drainage_area 
Node array of proportion of flow sent to each receiver. 
hill_flow__receiver_node 
Node array of receivers (node that receives flow from current node) 
hill_flow__receiver_proportions 
Node array of proportion of flow sent to each receiver. 
hill_flow__upstream_node_order 
Node array containing downstreamtoupstream ordered list of node IDs 
hill_surface_water__discharge 
Node array of proportion of flow sent to each receiver. 
hill_topographic__steepest_slope 
The steepest downhill slope 
hillslope_sediment__unit_volume_flux 
Volume flux per unit width along links 
hydraulic__gradient 
gradient of water table in link direction 
is_pit 
Boolean flag indicating whether a node is a pit. 
landslide__deposition 
Total deposition of derived sediment 
landslide__erosion 
Total erosion caused by landsliding 
landslide__probability_of_failure 
number of times FS is <=1 out of number of iterations user selected 
landslide_sediment_point_source 
Landslide derived sediment, as point sources on all the critical nodes where landslides initiate, before landslide runout is calculated 
lateral_erosion__depth_increment 
Change in elevation at each node from lateral erosion during time step 
lithosphere__increment_of_overlying_pressure 
Applied pressure to the lithosphere over a time step 
lithosphere__overlying_pressure_increment 
Applied pressure to the lithosphere over a time step 
lithosphere_surface__elevation_increment 
The change in elevation of the top of the lithosphere (the land surface) in one timestep 
lithosphere_surface__increment_of_elevation 
The change in elevation of the top of the lithosphere (the land surface) in one timestep 
LS_sediment__flux 
Sediment flux originating from landslides (volume per unit time of sediment entering each node) 
mean_water__depth 
Tidal mean water depth 
plant__age 
Age of plant 
plant__live_index 
1  vegetation__cumulative_water_stress 
radiation__incoming_shortwave_flux 
total incident shortwave radiation over the time step 
radiation__net_flux 
net total radiation over the time step 
radiation__net_longwave_flux 
net incident longwave radiation over the time step 
radiation__net_shortwave_flux 
net incident shortwave radiation over the time step 
radiation__ratio_to_flat_surface 
ratio of total incident shortwave radiation on sloped surface to flat surface 
rainfall__daily_depth 
Rain in (mm) as a field, allowing spatiotemporal soil moisture saturation analysis. 
rainfall__flux 
Depth of water delivered per unit time in each storm 
rainfall__total_depth_per_year 
Depth of water delivered in total in each model year 
reach_length 
Length of each reach 
sea_level__elevation 
Sea level elevation 
sediment__deposition_coeff 
Fraction of incoming sediment that is deposited on the node 
sediment__deposition_rate 
Deposition rate on node 
sediment__discharge_in 
Sediment discharge into a node. 
sediment__erosion_rate 
Erosion rate on node 
sediment__flux_in 
Incoming sediment rate on node (=qs/dx) 
sediment__flux_out 
Outgoing sediment rate on node = sediment eroded on node + sediment transported across node from upstream 
sediment__influx 
Sediment flux (volume per unit time of sediment entering each node) 
sediment__outflux 
Sediment flux (volume per unit time of sediment leaving each node) 
sediment__rate_of_change 
Time rate of change of sediment thickness 
sediment__transfer_rate 
Rate of transferred sediment across a node (incoming sediment  deposited sediment on node) 
sediment_deposit__thickness 
Thickness of deposition or erosion in latest time step 
sediment_fill__depth 
Depth of sediment added at eachnode 
slope_coefficient 
Slope coefficient to define channels. 
slope_exponent 
Slope exponent to define channels. 
soil__density 
wet bulk density of soil 
soil__depth 
Depth of soil or weathered bedrock 
soil__flux 
flux of soil in direction of link 
soil__internal_friction_angle 
critical angle just before failure due to friction between particles 
soil__maximum_total_cohesion 
maximum of combined root and soil cohesion at node 
soil__mean_relative_wetness 
Indicator of soil wetness; relative depth perched water table within the soil layer 
soil__minimum_total_cohesion 
minimum of combined root and soil cohesion at node 
soil__mode_total_cohesion 
mode of combined root and soil cohesion at node 
soil__probability_of_saturation 
number of times relative wetness is >=1 out of number of iterations user selected 
soil__saturated_hydraulic_conductivity 
mode rate of water transmitted through soil  provided if transmissivity is NOT provided to calculate tranmissivity with soil depth 
soil__thickness 
soil depth to restrictive layer 
soil__transmissivity 
mode rate of water transmitted through a unit width of saturated soil  either provided or calculated with Ksat and soil depth 
soil_moisture__initial_saturation_fraction 
initial soil_moisture__saturation_fraction 
soil_moisture__root_zone_leakage 
leakage of water into deeper portions of the soil not accessible to the plant 
soil_moisture__saturation_fraction 
relative volumetric water content (theta)  limits=[0,1] 
soil_production__dt_produced_depth 
thickness of soil produced at nodes over time dt 
soil_production__dt_weathered_depth 
thickness of bedrock weathered at nodes over time dt 
soil_production__rate 
rate of soil production at nodes 
soil_water_infiltration__depth 
Water column height above the surface previously absorbed into the soil. Note that this is NOT the actual depth of the wetted front, which also depends on the porosity. 
squared_length_adjacent 
Length to adjacent nodes, squared (calcualted in advance to save time during calculation 
subsidence_rate 
Rate of tectonic subsidence in hangingwall area 
surface__evapotranspiration 
actual sum of evaporation and plant transpiration 
surface__potential_evapotranspiration_30day_mean 
30 day mean of surface__potential_evapotranspiration 
surface__potential_evapotranspiration_rate 
potential sum of evaporation and potential transpiration 
surface__runoff 
runoff from ground surface 
surface_load__stress 
Magnitude of stress exerted by surface load 
surface_to_channel__minimum_distance 
Distance from each node to the nearest channel 
surface_water__depth 
Depth of water on the surface 
surface_water__depth_at_link 
Depth of water on the surface at grid links 
surface_water__discharge 
Volumetric discharge of surface water 
surface_water__discharge_loss 
Total volume of water per second lost during all flow out of the node 
surface_water__specific_discharge 
rate of seepage to surface 
surface_water__unit_discharge 
Volumetric discharge of surface water per unit width 
surface_water__velocity 
Speed of water flow above the surface 
surface_water_inflow__discharge 
water volume inflow rate to the cell around each node 
taxa__richness 
The number of taxa at each node 
topographic__elevation 
Land surface topographic elevation 
topographic__gradient 
Gradient of the ground surface 
topographic__slope 
gradient of the ground surface 
topographic__specific_contributing_area 
specific contributing (upslope area/cell face ) that drains to node 
topographic__steepest_slope 
The steepest downhill slope 
upper_crust_thickness 
Thickness of upper crust (arbitrary datum) 
vegetation__cover_fraction 
fraction of land covered by vegetation 
vegetation__cumulative_water_stress 
cumulative vegetation__water_stress over the growing season 
vegetation__dead_biomass 
weight of dead organic mass per unit area  measured in terms of dry matter 
vegetation__dead_leaf_area_index 
onesided dead leaf area per unit ground surface area 
vegetation__live_biomass 
weight of green organic mass per unit area  measured in terms of dry matter 
vegetation__live_leaf_area_index 
onesided green leaf area per unit ground surface area 
vegetation__plant_functional_type 
classification of plants (int), grass=0, shrub=1, tree=2, bare=3, shrub_seedling=4, tree_seedling=5 
vegetation__water_stress 
parameter that represents nonlinear effects of water deficit on plants 
volume__lateral_erosion 
Array tracking volume eroded at each node from lateral erosion 
water__depth 
depth of water under current sea level 
water__discharge_in 
Incoming water discharge at node. 
water__specific_discharge 
flow discharge component in the direction of the link 
water__unit_flux_in 
External volume water per area per time input to each node (e.g., rainfall rate) 
water__velocity 
flow velocity component in the direction of the link 
water_depth 
Water depth 
water_surface__elevation 
Elevation of the water surface. 
water_surface__gradient 
Downstream gradient of the water surface. 
water_table__elevation 
elevation of water table 
aquifer__thickness 

aquifer_base__elevation 

aquifer_base__gradient 

area_coefficient 

area_exponent 

average_surface_water__specific_discharge 

bedload_sediment__rate_of_loss_to_abrasion 

bedload_sediment__volume_influx 

bedload_sediment__volume_outflux 

bedrock__elevation 

carbonate_production_rate 

carbonate_thickness 

channel__bed_shear_stress 

channel__chi_index 

channel__depth 

channel__discharge 

channel__mask 

channel__steepness_index 

channel__width 

channel_bottom_sediment_grain__d50_diameter 

channel_sediment__relative_flux 

channel_sediment__volumetric_flux 

channel_sediment__volumetric_transport_capacity 

channel_slope 

channel_width 

channelization_threshold 

cumulative_subsidence_depth 

depression__depth 

depression__outlet_node 

depression_free_elevation 

dimensionless_discharge 

dimensionless_discharge_above_threshold 

dimensionless_discharge_threshold 

distance_to_divide 

drainage_area 

ebb_tide_flow__velocity 

flood_status_code 

flood_tide_flow__velocity 

flow__data_structure_delta 

flow__link_direction 

flow__link_to_receiver_node 

flow__potential 

flow__receiver_node 

flow__receiver_proportions 

flow__sink_flag 

flow__upstream_node_order 

flow_depth 

fracture_at_node 

groundwater__specific_discharge 

groundwater__velocity 

height_above_drainage__elevation 

hill_drainage_area 

hill_flow__receiver_node 

hill_flow__receiver_proportions 

hill_flow__upstream_node_order 

hill_surface_water__discharge 

hill_topographic__steepest_slope 

hillslope_sediment__unit_volume_flux 

hydraulic__gradient 

is_pit 

landslide__deposition 

landslide__erosion 

landslide__probability_of_failure 

landslide_sediment_point_source 

lateral_erosion__depth_increment 

lithosphere__increment_of_overlying_pressure 

lithosphere__overlying_pressure_increment 

lithosphere_surface__elevation_increment 

lithosphere_surface__increment_of_elevation 

LS_sediment__flux 

mean_water__depth 

plant__age 

plant__live_index 

radiation__incoming_shortwave_flux 

radiation__net_flux 

radiation__net_longwave_flux 

radiation__net_shortwave_flux 

radiation__ratio_to_flat_surface 

rainfall__daily_depth 

rainfall__flux 

rainfall__total_depth_per_year 

reach_length 

sea_level__elevation 

sediment__deposition_coeff 

sediment__deposition_rate 

sediment__discharge_in 

sediment__erosion_rate 

sediment__flux_in 

sediment__flux_out 

sediment__influx 

sediment__outflux 

sediment__rate_of_change 

sediment__transfer_rate 

sediment_deposit__thickness 

sediment_fill__depth 

slope_coefficient 

slope_exponent 

soil__density 

soil__depth 

soil__flux 

soil__internal_friction_angle 

soil__maximum_total_cohesion 

soil__mean_relative_wetness 

soil__minimum_total_cohesion 

soil__mode_total_cohesion 

soil__probability_of_saturation 

soil__saturated_hydraulic_conductivity 

soil__thickness 

soil__transmissivity 

soil_moisture__initial_saturation_fraction 

soil_moisture__root_zone_leakage 

soil_moisture__saturation_fraction 

soil_production__dt_produced_depth 

soil_production__dt_weathered_depth 

soil_production__rate 

soil_water_infiltration__depth 

squared_length_adjacent 

subsidence_rate 

surface__evapotranspiration 

surface__potential_evapotranspiration_30day_mean 

surface__potential_evapotranspiration_rate 

surface__runoff 

surface_load__stress 

surface_to_channel__minimum_distance 

surface_water__depth 

surface_water__depth_at_link 

surface_water__discharge 

surface_water__discharge_loss 

surface_water__specific_discharge 

surface_water__unit_discharge 

surface_water__velocity 

surface_water_inflow__discharge 

taxa__richness 

topographic__elevation 

topographic__gradient 

topographic__slope 

topographic__specific_contributing_area 

topographic__steepest_slope 

upper_crust_thickness 

vegetation__cover_fraction 

vegetation__cumulative_water_stress 

vegetation__dead_biomass 

vegetation__dead_leaf_area_index 

vegetation__live_biomass 

vegetation__live_leaf_area_index 

vegetation__plant_functional_type 

vegetation__water_stress 

volume__lateral_erosion 

water__depth 

water__discharge_in 

water__specific_discharge 

water__unit_flux_in 

water__velocity 

water_depth 

water_surface__elevation 

water_surface__gradient 

water_table__elevation 
aquifer__thickness 

aquifer_base__elevation 

aquifer_base__gradient 

area_coefficient 

area_exponent 

average_surface_water__specific_discharge 

bedload_sediment__rate_of_loss_to_abrasion 

bedload_sediment__volume_influx 

bedload_sediment__volume_outflux 

bedrock__elevation 

carbonate_production_rate 

carbonate_thickness 

channel__bed_shear_stress 

channel__chi_index 

channel__depth 

channel__discharge 

channel__mask 

channel__steepness_index 

channel__width 

channel_bottom_sediment_grain__d50_diameter 

channel_sediment__relative_flux 

channel_sediment__volumetric_flux 

channel_sediment__volumetric_transport_capacity 

channel_slope 

channel_width 

channelization_threshold 

cumulative_subsidence_depth 

depression__depth 

depression__outlet_node 

depression_free_elevation 

dimensionless_discharge 

dimensionless_discharge_above_threshold 

dimensionless_discharge_threshold 

distance_to_divide 

drainage_area 

ebb_tide_flow__velocity 

flood_status_code 

flood_tide_flow__velocity 

flow__data_structure_delta 

flow__link_direction 

flow__link_to_receiver_node 

flow__potential 

flow__receiver_node 

flow__receiver_proportions 

flow__sink_flag 

flow__upstream_node_order 

flow_depth 

fracture_at_node 

groundwater__specific_discharge 

groundwater__velocity 

height_above_drainage__elevation 

hill_drainage_area 

hill_flow__receiver_node 

hill_flow__receiver_proportions 

hill_flow__upstream_node_order 

hill_surface_water__discharge 

hill_topographic__steepest_slope 

hillslope_sediment__unit_volume_flux 

hydraulic__gradient 

is_pit 

landslide__deposition 

landslide__erosion 

landslide__probability_of_failure 

landslide_sediment_point_source 

lateral_erosion__depth_increment 

lithosphere__increment_of_overlying_pressure 

lithosphere__overlying_pressure_increment 

lithosphere_surface__elevation_increment 

lithosphere_surface__increment_of_elevation 

LS_sediment__flux 

mean_water__depth 

plant__age 

plant__live_index 

radiation__incoming_shortwave_flux 

radiation__net_flux 

radiation__net_longwave_flux 

radiation__net_shortwave_flux 

radiation__ratio_to_flat_surface 

rainfall__daily_depth 

rainfall__flux 

rainfall__total_depth_per_year 

reach_length 

sea_level__elevation 

sediment__deposition_coeff 

sediment__deposition_rate 

sediment__discharge_in 

sediment__erosion_rate 

sediment__flux_in 

sediment__flux_out 

sediment__influx 

sediment__outflux 

sediment__rate_of_change 

sediment__transfer_rate 

sediment_deposit__thickness 

sediment_fill__depth 

slope_coefficient 

slope_exponent 

soil__density 

soil__depth 

soil__flux 

soil__internal_friction_angle 

soil__maximum_total_cohesion 

soil__mean_relative_wetness 

soil__minimum_total_cohesion 

soil__mode_total_cohesion 

soil__probability_of_saturation 

soil__saturated_hydraulic_conductivity 

soil__thickness 

soil__transmissivity 

soil_moisture__initial_saturation_fraction 

soil_moisture__root_zone_leakage 

soil_moisture__saturation_fraction 

soil_production__dt_produced_depth 

soil_production__dt_weathered_depth 

soil_production__rate 

soil_water_infiltration__depth 

squared_length_adjacent 

subsidence_rate 

surface__evapotranspiration 

surface__potential_evapotranspiration_30day_mean 

surface__potential_evapotranspiration_rate 

surface__runoff 

surface_load__stress 

surface_to_channel__minimum_distance 

surface_water__depth 

surface_water__depth_at_link 

surface_water__discharge 

surface_water__discharge_loss 

surface_water__specific_discharge 

surface_water__unit_discharge 

surface_water__velocity 

surface_water_inflow__discharge 

taxa__richness 

topographic__elevation 

topographic__gradient 

topographic__slope 

topographic__specific_contributing_area 

topographic__steepest_slope 

upper_crust_thickness 

vegetation__cover_fraction 

vegetation__cumulative_water_stress 

vegetation__dead_biomass 

vegetation__dead_leaf_area_index 

vegetation__live_biomass 

vegetation__live_leaf_area_index 

vegetation__plant_functional_type 

vegetation__water_stress 

volume__lateral_erosion 

water__depth 

water__discharge_in 

water__specific_discharge 

water__unit_flux_in 

water__velocity 

water_depth 

water_surface__elevation 

water_surface__gradient 

water_table__elevation 
List of Grid Methods#
Getting Information about a Grid#
The following attributes, properties, and methods provide data about the grid,
its geometry, and the connectivity among the various elements. Each grid
element has an ID number, which is also its position in an array that
contains information about that type of element. For example, the x
coordinate of node 5 would be found at grid.x_of_node[5]
.
The naming of gridelement arrays is <attribute>_at_<element>
, where
attribute is the name of the data in question, and element is the element
to which the attribute applies. For example, the property node_at_cell
is an array of length number_of_cells where each element of the array
is the ID of the node associated with that cell.
(e.g. node_at_cell[3]
is the ID of the node associated with cell 3).
In this case the attribute is singular since there is only one value per element.
Sometimes there are multiple attributes associated with each element. In this
case, the attribute is plural. For example, the faces_at_cell
array
contains multiple faces for each cell. Exceptions to these general rules are
functions that return indices of a subset of all elements of a particular type.
For example, you can obtain an array with IDs of only the core nodes using
core_nodes
, while active_links
provides an array
of IDs of active links (only). Finally, attributes that represent a measurement
of something, such as the length of a link or the surface area of a cell, are
described using _of_
(e.g. area_of_cell
).
Fields#
ModelGrid
inherits from the GraphFields
class. This
provides ModelGrid
, and its subclasses, with the ability to, optionally,
store data values associated with the different types grid elements
(nodes, cells, etc.). In particular, as part of __init__
,
data field groups are added to the ModelGrid
that provide containers to
put data fields into. There is one group for each of the eight grid elements
(node, cell, link, face, core_node, core_cell, active_link, and active_face).
Nodes, Links, and Patches#
Adjacent nodes for each grid node. 

1=incoming flux, 1=outgoing flux, 0=no flux. 

Get adjacent nodes. 

Get azimuths from every node to every other node. 

Get distances from every node to every other node. 

Get array of boundary nodes. 

Get array of aspect of a surface. 

Get distances for nodes to a given point. 

Calculate divergence of linkbased fluxes at cells. 

Calculate divergence of linkbased fluxes at nodes. 

grid.calc_grad_along_node_links(node_values, [cell_ids], out=None) 

Get array of hillshade. 

Calculate net link fluxes at nodes. 

Array of slopes at nodes, averaged over neighboring patches. 

Calculate topographic slope. 

Cell areas in a nnodeslong array. 

Get array of closed boundary nodes. 

Get array of core nodes. 

Links and diagonals attached to nodes. 

Get adjacent nodes along diagonals. 

Diagonals attached to nodes. 

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

Node nearest a point. 

Get array of fixed gradient boundary nodes. 

Get array of fixed value boundary nodes. 

Convert node indices to node ID. 

Return a boolean the same shape as 

Return a boolean the same shape as 

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

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

Map the maximum of links entering a node to the node. 

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

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

Map the max of links leaving a node to the node. 

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

Map the mean of active links in the x direction touching node to the node. 

Map the mean of links in the x direction touching a node to the node. 

Map the mean of links entering a node to the node. 

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

Map the mean of links touching a node to the node. 

Map the mean of links leaving a node to the node. 

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

Map the mean of active links in the y direction touching node to the node. 

Map the mean of links in the y direction touching a node to the node. 

Map the minimum of links entering a node to the node. 

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

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

Map the min of links leaving a node to the node. 

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

Map values for nodes to cells. 

Map the sum of links entering a node to the node. 

Map the sum of links leaving a node to the node. 

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

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

Get array of nodes associated with core cells. 

Get nodes at link head. 

Get nodes at link tail. 

Get the coordinates of nodes along a particular axis. 

Check if nodes have neighbors that are boundary nodes. 

Check if nodes are boundary nodes. 

Unravel an array of node values. 

Get the nodes surrounding a point. 

Get nodes at either end of links. 

Get the nodes that define a patch. 

Number of cell columns. 

Number of core nodes. 

Number of interior nodes. 

Get total number of nodes. 

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

Get array of open boundary nodes. 

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

Roll (shift) specified data on nodes up or down in a raster grid. 

Make nodata nodes closed boundaries. 

Make nodata nodes fixed gradient boundaries. 

Get array of the boundary status for each node. 

Get array of xcomponent of unit vector sums at each node. 

Get array of ycomponent of unit vector sums at each node. 

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

Get xcoordinate of node. 

Get x and ycoordinates of node. 

Get ycoordinate of node. 
1=incoming flux, 1=outgoing flux, 0=no flux. 

Get array of active links. 

Get the angle of each link. 

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

Calculate differences of node values over links and diagonals. 

Calculate differences of node values over diagonals. 

Calculate differences of node values over links. 

grid.calc_grad_along_node_links(node_values, [cell_ids], out=None) 

Calculate gradients over all diagonals and links. 

Calculate gradients over all diagonals. 

Calculate gradients in node_values at links. 

Links and diagonals attached to nodes. 

Diagonals attached to nodes. 

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

Get array of fixed links. 

Length of links and diagonals. 

Get the length of links. 

Return a boolean the same shape as 

Return a boolean the same shape as 

Get the links that define a patch. 

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

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

Map the maximum of links entering a node to the node. 

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

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

Map the max of links leaving a node to the node. 

Map the mean of active links in the x direction touching node to the node. 

Map the mean of links in the x direction touching a node to the node. 

Map the mean of links entering a node to the node. 

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

Map the mean of links touching a node to the node. 

Map the mean of links leaving a node to the node. 

Map the mean of active links in the y direction touching node to the node. 

Map the mean of links in the y direction touching a node to the node. 

Map the minimum of links entering a node to the node. 

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

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

Map the min of links leaving a node to the node. 

Map the sum of links entering a node to the node. 

Map the sum of links leaving a node to the node. 

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

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

Get the middle of links. 

Number of active links. 

Number of fixed links. 

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

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

Resolve the xycomponents of links. 

Get array of the status of all links. 

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

Calculate the components of the gradient of each raster patch. 

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

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

Calculate unit normals on a patch. 

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

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

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

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

Get the number of patches. 

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

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

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

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

Get the centroid of each patch. 
Adjacent nodes for each grid node. 

1=incoming flux, 1=outgoing flux, 0=no flux. 

Get adjacent nodes. 

Get azimuths from every node to every other node. 

Get distances from every node to every other node. 

Get array of boundary nodes. 

Get array of aspect of a surface. 

Get distances for nodes to a given point. 

Calculate divergence of linkbased fluxes at cells. 

Calculate divergence of linkbased fluxes at nodes. 

Get array of hillshade. 

Calculate net link fluxes at nodes. 

Array of slopes at nodes, averaged over neighboring patches. 

Cell areas in a nnodeslong array. 

Get array of closed boundary nodes. 

Get array of core nodes. 

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

Get array of fixed gradient boundary nodes. 

Get array of fixed value boundary nodes. 

Return a boolean the same shape as 

Return a boolean the same shape as 

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

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

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

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

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

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

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

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

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

Map values for nodes to cells. 

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

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

Get array of nodes associated with core cells. 

Get nodes at link head. 

Get nodes at link tail. 

Get the coordinates of nodes along a particular axis. 

Check if ModelGrid nodes have neighbors that are boundary nodes. 

Check if nodes are boundary nodes. 

Get identifier for each node. 

Get nodes at either end of links. 

Get the nodes that define a patch. 

Number of core nodes. 

Number of node columns hex grid. 

Number of node rows in a rectangularshaped and/or horizontally oriented hex grid. 

Get total number of nodes. 

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

Get array of open boundary nodes. 

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

Get nodes on the convex hull of a Graph. 

Make nodata nodes closed boundaries. 

Make nodata nodes fixed gradient boundaries. 

Get array of the boundary status for each node. 

Get array of xcomponent of unit vector sums at each node. 

Get array of ycomponent of unit vector sums at each node. 

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

Get xcoordinate of node. 

Get x and ycoordinates of node. 

Get ycoordinate of node. 
1=incoming flux, 1=outgoing flux, 0=no flux. 

Get array of active links. 

Get the angle of each link. 

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

Calculate differences of node values over links. 

Calculate gradients of node values at links. 

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

Get array of fixed links. 

Return a boolean the same shape as 

Return a boolean the same shape as 

Get links touching a node. 

Get the links that define a patch. 

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

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

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

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

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

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

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

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

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

Get the middle of links. 

Number of active links. 

Number of fixed links. 

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

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

Resolve the xycomponents of links. 

Get array of the status of all links. 

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

Calculate the components of the gradient at each patch. 

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

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

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

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

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

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

Get the number of patches. 

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

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

Get the patches on either side of each link. 

Get the patches that touch each node. 

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

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

Get the centroid of each patch. 
Adjacent nodes for each grid node. 

1=incoming flux, 1=outgoing flux, 0=no flux. 

Get adjacent nodes. 

Get azimuths from every node to every other node. 

Get distances from every node to every other node. 

Get array of boundary nodes. 

Get array of aspect of a surface. 

Get distances for nodes to a given point. 

Calculate divergence of linkbased fluxes at cells. 

Calculate divergence of linkbased fluxes at nodes. 

Get array of hillshade. 

Calculate net link fluxes at nodes. 

Array of slopes at nodes, averaged over neighboring patches. 

Cell areas in a nnodeslong array. 

Get array of closed boundary nodes. 

Get array of core nodes. 

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

Get array of fixed gradient boundary nodes. 

Get array of fixed value boundary nodes. 

Return a boolean the same shape as 

Return a boolean the same shape as 

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

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

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

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

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

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

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

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

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

Map values for nodes to cells. 

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

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

Get array of nodes associated with core cells. 

Get nodes at link head. 

Get nodes at link tail. 

Get the coordinates of nodes along a particular axis. 

Check if ModelGrid nodes have neighbors that are boundary nodes. 

Check if nodes are boundary nodes. 

Get identifier for each node. 

Get nodes at either end of links. 

Get the nodes that define a patch. 

Number of core nodes. 

Get total number of nodes. 

Number of nodes in each ring. 

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

Get array of open boundary nodes. 

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

Get nodes on the convex hull of a Graph. 

Distance for center node to each node. 

Make nodata nodes closed boundaries. 

Make nodata nodes fixed gradient boundaries. 

Get array of the boundary status for each node. 

Get array of xcomponent of unit vector sums at each node. 

Get array of ycomponent of unit vector sums at each node. 

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

Get xcoordinate of node. 

Get x and ycoordinates of node. 

Get ycoordinate of node. 
1=incoming flux, 1=outgoing flux, 0=no flux. 

Get array of active links. 

Get the angle of each link. 

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

Calculate differences of node values over links. 

Calculate gradients of node values at links. 

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

Get array of fixed links. 

Get the length of links. 

Return a boolean the same shape as 

Return a boolean the same shape as 

Get links touching a node. 

Get the links that define a patch. 

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

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

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

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

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

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

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

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

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

Get the middle of links. 

Number of active links. 

Number of fixed links. 

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

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

Resolve the xycomponents of links. 

Get array of the status of all links. 

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

Calculate the components of the gradient at each patch. 

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

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

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

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

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

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

Get the number of patches. 

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

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

Get the patches on either side of each link. 

Get the patches that touch each node. 

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

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

Get the centroid of each patch. 
Adjacent nodes for each grid node. 

1=incoming flux, 1=outgoing flux, 0=no flux. 

Get adjacent nodes. 

Get azimuths from every node to every other node. 

Get distances from every node to every other node. 

Get array of boundary nodes. 

Get array of aspect of a surface. 

Get distances for nodes to a given point. 

Calculate divergence of linkbased fluxes at cells. 

Calculate divergence of linkbased fluxes at nodes. 

Get array of hillshade. 

Calculate net link fluxes at nodes. 

Array of slopes at nodes, averaged over neighboring patches. 

Cell areas in a nnodeslong array. 

Get array of closed boundary nodes. 

Get array of core nodes. 

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

Get array of fixed gradient boundary nodes. 

Get array of fixed value boundary nodes. 

Return a boolean the same shape as 

Return a boolean the same shape as 

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

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

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

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

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

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

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

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

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

Map values for nodes to cells. 

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

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

Get array of nodes associated with core cells. 

Get nodes at link head. 

Get nodes at link tail. 

Get the coordinates of nodes along a particular axis. 

Check if ModelGrid nodes have neighbors that are boundary nodes. 

Check if nodes are boundary nodes. 

Get identifier for each node. 

Get nodes at either end of links. 

Get the nodes that define a patch. 

Number of core nodes. 

Get total number of nodes. 

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

Get array of open boundary nodes. 

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

Get nodes on the convex hull of a Graph. 

Make nodata nodes closed boundaries. 

Make nodata nodes fixed gradient boundaries. 

Get array of the boundary status for each node. 

Get array of xcomponent of unit vector sums at each node. 

Get array of ycomponent of unit vector sums at each node. 

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

Get xcoordinate of node. 

Get x and ycoordinates of node. 

Get ycoordinate of node. 
1=incoming flux, 1=outgoing flux, 0=no flux. 

Get array of active links. 

Get the angle of each link. 

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

Calculate differences of node values over links. 

Calculate gradients of node values at links. 

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

Get array of fixed links. 

Get the length of links. 

Return a boolean the same shape as 

Return a boolean the same shape as 

Get links touching a node. 

Get the links that define a patch. 

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

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

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

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

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

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

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

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

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

Get the middle of links. 

Number of active links. 

Number of fixed links. 

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

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

Resolve the xycomponents of links. 

Get array of the status of all links. 

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

Calculate the components of the gradient at each patch. 

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

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

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

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

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

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

Get the number of patches. 

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

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

Get the patches on either side of each link. 

Get the patches that touch each node. 

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

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

Get the centroid of each patch. 

Adjacent nodes for each grid node. 

1=incoming flux, 1=outgoing flux, 0=no flux. 

Get adjacent nodes. 

Get azimuths from every node to every other node. 

Get distances from every node to every other node. 

Get array of boundary nodes. 

Get array of aspect of a surface. 

Get distances for nodes to a given point. 

Calculate divergence of linkbased fluxes at cells. 

Calculate divergence of linkbased fluxes at nodes. 

Get array of hillshade. 

Calculate net link fluxes at nodes. 

Array of slopes at nodes, averaged over neighboring patches. 

Cell areas in a nnodeslong array. 

Get array of closed boundary nodes. 

Get array of core nodes. 

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

Get array of fixed gradient boundary nodes. 

Get array of fixed value boundary nodes. 

Return a boolean the same shape as 

Return a boolean the same shape as 

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

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

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

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

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

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

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

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

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

Map values for nodes to cells. 

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

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

Get array of nodes associated with core cells. 

Get nodes at link head. 

Get nodes at link tail. 

Get the coordinates of nodes along a particular axis. 

Check if ModelGrid nodes have neighbors that are boundary nodes. 

Check if nodes are boundary nodes. 

Get identifier for each node. 

Get nodes at either end of links. 

Get the nodes that define a patch. 

Number of core nodes. 

Get total number of nodes. 

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

Get array of open boundary nodes. 

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

Get nodes on the convex hull of a Graph. 

Make nodata nodes closed boundaries. 

Make nodata nodes fixed gradient boundaries. 

Get array of the boundary status for each node. 

Get array of xcomponent of unit vector sums at each node. 

Get array of ycomponent of unit vector sums at each node. 

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

Get xcoordinate of node. 

Get x and ycoordinates of node. 

Get ycoordinate of node. 

1=incoming flux, 1=outgoing flux, 0=no flux. 

Get array of active links. 

Get the angle of each link. 

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

Calculate differences of node values over links. 

Calculate gradients of node values at links. 

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

Get array of fixed links. 

Get the length of links. 

Return a boolean the same shape as 

Return a boolean the same shape as 

Get links touching a node. 

Get the links that define a patch. 

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

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

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

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

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

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

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

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

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

Get the middle of links. 

Number of active links. 

Number of fixed links. 

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

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

Resolve the xycomponents of links. 

Get array of the status of all links. 

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

Get the area of each patch. 

Calculate the components of the gradient at each patch. 

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

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

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

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

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

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

Get the number of patches. 

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

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

Get the patches on either side of each link. 

Get the patches that touch each node. 

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

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

Get the centroid of each patch. 
Corners, Faces, and Cells#
grid.calc_grad_across_cell_corners(node_values, [cell_ids], out=None) 
Get array of active faces. 

grid.calc_grad_across_cell_faces(node_values, [cell_ids], out=None) 

Total number of active faces. 
Get tuple of arrays of aspect of each of the eight cell subtriangles. 

Calculate the slope (positive magnitude of gradient) at each of the eight cell subtriangles. 

Calculate unit normals on a cell. 

Cell areas in a nnodeslong array. 

Get the shape of the cellular grid (grid with only cells). 

Unravel a 1D array. 

Get array of cells in cellular grid (grid with only cells) corners. 

Get array of core cells. 

For each cell in a raster, return the D8 neighboring cells, looping across grid boundaries as necessary. 

Map values for nodes to cells. 

Get array of nodes associated with core cells. 

Number of cell rows. 

Number of core cells. 

Get list of second ring looped neighbor cell IDs (all 16 neighbors). 
Get array of active faces. 

Total number of active faces. 
Cell areas in a nnodeslong array. 

Get array of core cells. 

Map values for nodes to cells. 

Get array of nodes associated with core cells. 

Number of core cells. 
Get array of active faces. 

Total number of active faces. 
Cell areas in a nnodeslong array. 

Get array of core cells. 

Map values for nodes to cells. 

Get array of nodes associated with core cells. 

Number of core cells. 
Get array of active faces. 

Total number of active faces. 
Cell areas in a nnodeslong array. 

Get array of core cells. 

Map values for nodes to cells. 

Get array of nodes associated with core cells. 

Number of core cells. 

Get array of active faces. 

Total number of active faces. 

Cell areas in a nnodeslong array. 

Get array of core cells. 

Map values for nodes to cells. 

Get array of nodes associated with core cells. 

Number of core cells. 
Boundary conditions#
These are the primary properties for getting and setting the grid boundary
conditions. Changes made to status_at_node
automatically
update the conditions defined at other grid elements.
Adjacent nodes for each grid node. 

Get array of active faces. 

Get array of active links. 

Get array of boundary nodes. 

Get array of closed boundary nodes. 

Get array of core cells. 

Get array of core nodes. 

Get array of fixed gradient boundary nodes. 

Get array of fixed links. 

Get array of fixed value boundary nodes. 

For each cell in a raster, return the D8 neighboring cells, looping across grid boundaries as necessary. 

Get array of nodes associated with core cells. 

Check if nodes have neighbors that are boundary nodes. 

Check if nodes are boundary nodes. 

Total number of active faces. 

Number of active links. 

Number of core cells. 

Number of core nodes. 

Number of fixed links. 

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

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

Get array of open boundary nodes. 

Get list of second ring looped neighbor cell IDs (all 16 neighbors). 

Set boundary not to be closed. 

Create fixed values boundaries. 

Create wraparound boundaries. 

Make nodata nodes closed boundaries. 

Make nodata nodes fixed gradient boundaries. 

Identifys all nonclosed nodes that are disconnected from the node given in. 

Set node status on grid edges. 

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

Set the boundary conditions for a watershed. 

Set the boundary conditions for a watershed. 

Get array of the status of all links. 

Get array of the boundary status for each node. 
Adjacent nodes for each grid node. 

Get array of active faces. 

Get array of active links. 

Get array of boundary nodes. 

Get array of closed boundary nodes. 

Get array of core cells. 

Get array of core nodes. 

Get array of fixed gradient boundary nodes. 

Get array of fixed links. 

Get array of fixed value boundary nodes. 

Get array of nodes associated with core cells. 

Check if ModelGrid nodes have neighbors that are boundary nodes. 

Check if nodes are boundary nodes. 

Total number of active faces. 

Number of active links. 

Number of core cells. 

Number of core nodes. 

Number of fixed links. 

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

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

Get array of open boundary nodes. 

Get nodes on the convex hull of a Graph. 

Make nodata nodes closed boundaries. 

Make nodata nodes fixed gradient boundaries. 

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

Set the boundary conditions for a watershed on a HexModelGrid. 

Get array of the status of all links. 

Get array of the boundary status for each node. 
Adjacent nodes for each grid node. 

Get array of active faces. 

Get array of active links. 

Get array of boundary nodes. 

Get array of closed boundary nodes. 

Get array of core cells. 

Get array of core nodes. 

Get array of fixed gradient boundary nodes. 

Get array of fixed links. 

Get array of fixed value boundary nodes. 

Get array of nodes associated with core cells. 

Check if ModelGrid nodes have neighbors that are boundary nodes. 

Check if nodes are boundary nodes. 

Total number of active faces. 

Number of active links. 

Number of core cells. 

Number of core nodes. 

Number of fixed links. 

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

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

Get array of open boundary nodes. 

Get nodes on the convex hull of a Graph. 

Make nodata nodes closed boundaries. 

Make nodata nodes fixed gradient boundaries. 

Get array of the status of all links. 

Get array of the boundary status for each node. 
Adjacent nodes for each grid node. 

Get array of active faces. 

Get array of active links. 

Get array of boundary nodes. 

Get array of closed boundary nodes. 

Get array of core cells. 

Get array of core nodes. 

Get array of fixed gradient boundary nodes. 

Get array of fixed links. 

Get array of fixed value boundary nodes. 

Get array of nodes associated with core cells. 

Check if ModelGrid nodes have neighbors that are boundary nodes. 

Check if nodes are boundary nodes. 

Total number of active faces. 

Number of active links. 

Number of core cells. 

Number of core nodes. 

Number of fixed links. 

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

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

Get array of open boundary nodes. 

Get nodes on the convex hull of a Graph. 

Make nodata nodes closed boundaries. 

Make nodata nodes fixed gradient boundaries. 

Get array of the status of all links. 

Get array of the boundary status for each node. 

Adjacent nodes for each grid node. 

Get array of active faces. 

Get array of active links. 

Get array of boundary nodes. 

Get array of closed boundary nodes. 

Get array of core cells. 

Get array of core nodes. 

Get array of fixed gradient boundary nodes. 

Get array of fixed links. 

Get array of fixed value boundary nodes. 

Get array of nodes associated with core cells. 

Check if ModelGrid nodes have neighbors that are boundary nodes. 

Check if nodes are boundary nodes. 

Total number of active faces. 

Number of active links. 

Number of core cells. 

Number of core nodes. 

Number of fixed links. 

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

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

Get array of open boundary nodes. 

Get nodes on the convex hull of a Graph. 

Make nodata nodes closed boundaries. 

Make nodata nodes fixed gradient boundaries. 

Get array of the status of all links. 

Get array of the boundary status for each node. 
Subsets of elements#
These methods are useful in identifying subsets of grid elements, e.g., closest node to a point; nodes at edges.
Get array of cells in cellular grid (grid with only cells) corners. 

Node nearest a point. 

Convert node indices to node ID. 

Check if a point is on the grid. 

Get the nodes surrounding a point. 

Set boundary not to be closed. 

Create fixed values boundaries. 

Create wraparound boundaries. 
Get nodes on the convex hull of a Graph. 
Get nodes on the convex hull of a Graph. 
Get nodes on the convex hull of a Graph. 

Get nodes on the convex hull of a Graph. 
Mapping between elements#
These methods allow mapping of values defined on one grid element onto a second, e.g., mapping upwind node values onto links, or mean link values onto nodes.
Map the largest magnitude of the links carrying flux from the node to the node. 

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

Map the maximum of links entering a node to the node. 

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

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

Map the max of links leaving a node to the node. 

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

Map the mean of active links in the x direction touching node to the node. 

Map the mean of links in the x direction touching a node to the node. 

Map the mean of links entering a node to the node. 

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

Map the mean of links touching a node to the node. 

Map the mean of links leaving a node to the node. 

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

Map the mean of active links in the y direction touching node to the node. 

Map the mean of links in the y direction touching a node to the node. 

Map the minimum of links entering a node to the node. 

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

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

Map the min of links leaving a node to the node. 

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

Map values for nodes to cells. 

Map the sum of links entering a node to the node. 

Map the sum of links leaving a node to the node. 

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

Map 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 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 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 the largest magnitude of the links carrying flux from the node to the node. 

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

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

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

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

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

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

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

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

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

Map values for nodes to cells. 

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

Map 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 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 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 the largest magnitude of the links carrying flux from the node to the node. 

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

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

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

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

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

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

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

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

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

Map values for nodes to cells. 

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

Map 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 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 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 the largest magnitude of the links carrying flux from the node to the node. 

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

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

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

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

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

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

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

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

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

Map values for nodes to cells. 

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

Map 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 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 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 the largest magnitude of the links carrying flux from the node to the node. 

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

Map values from a link head nodes to links. 

Map values from a link tail nodes to links. 

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

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

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

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

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

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

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

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

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

Map values for nodes to cells. 

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

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

Map the the value found in one link array to a node, based on the largest magnitude value of links carrying fluxes out of the node, found in a second node array or field. 

Map 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 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 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. 
Gradients, fluxes, and divergences#
Landlab is designed to easily calculate gradients in quantities across the
grid, and to construct fluxes and flux divergences from them. Because these
calculations tend to be a little more involved than property lookups, the
methods tend to start with calc_
.
Calculate differences of node values over links and diagonals. 

Calculate differences of node values over diagonals. 

Calculate differences of node values over links. 

Calculate divergence of linkbased fluxes at cells. 

Calculate divergence of linkbased fluxes at nodes. 

grid.calc_grad_across_cell_corners(node_values, [cell_ids], out=None) 

grid.calc_grad_across_cell_faces(node_values, [cell_ids], out=None) 

grid.calc_grad_along_node_links(node_values, [cell_ids], out=None) 

Calculate gradients over all diagonals and links. 

Calculate gradients over all diagonals. 

Calculate gradients in node_values at links. 

Calculate the components of the gradient of each raster patch. 

Calculate net link fluxes at nodes. 

Calculate the slope (positive magnitude of gradient) at each of the eight cell subtriangles. 

Array of slopes at nodes, averaged over neighboring patches. 

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

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

Calculate unit normals on a cell. 

Calculate unit normals on a patch. 

Calculate topographic slope. 
Calculate differences of node values over links. 

Calculate divergence of linkbased fluxes at cells. 

Calculate divergence of linkbased fluxes at nodes. 

Calculate gradients of node values at links. 

Calculate the components of the gradient at each patch. 

Calculate net link fluxes at nodes. 

Array of slopes at nodes, averaged over neighboring patches. 

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

Calculate and return the unit normal vector <a, b, c> to a patch. 
Calculate differences of node values over links. 

Calculate divergence of linkbased fluxes at cells. 

Calculate divergence of linkbased fluxes at nodes. 

Calculate gradients of node values at links. 

Calculate the components of the gradient at each patch. 

Calculate net link fluxes at nodes. 

Array of slopes at nodes, averaged over neighboring patches. 

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

Calculate and return the unit normal vector <a, b, c> to a patch. 
Calculate differences of node values over links. 

Calculate divergence of linkbased fluxes at cells. 

Calculate divergence of linkbased fluxes at nodes. 

Calculate gradients of node values at links. 

Calculate the components of the gradient at each patch. 

Calculate net link fluxes at nodes. 

Array of slopes at nodes, averaged over neighboring patches. 

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

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

Calculate differences of node values over links. 

Calculate divergence of linkbased fluxes at cells. 

Calculate divergence of linkbased fluxes at nodes. 

Calculate gradients of node values at links. 

Calculate the components of the gradient at each patch. 

Calculate net link fluxes at nodes. 

Array of slopes at nodes, averaged over neighboring patches. 

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

Calculate and return the unit normal vector <a, b, c> to a patch. 
Surface analysis#
These methods permit the kinds of surface analysis that you might expect to find in GIS software.
Get tuple of arrays of aspect of each of the eight cell subtriangles. 

Get array of aspect of a surface. 

Get array of hillshade. 

Array of slopes at nodes, averaged over neighboring patches. 

Calculate topographic slope. 
Get array of aspect of a surface. 

Get array of hillshade. 

Array of slopes at nodes, averaged over neighboring patches. 
Get array of aspect of a surface. 

Get array of hillshade. 

Array of slopes at nodes, averaged over neighboring patches. 
Get array of aspect of a surface. 

Get array of hillshade. 

Array of slopes at nodes, averaged over neighboring patches. 

Get array of aspect of a surface. 

Get array of hillshade. 

Array of slopes at nodes, averaged over neighboring patches. 
Fields#
ModelGrid
inherits several useful methods for creating new data
fields and adding new data fields to a ModelGrid
instance. Methods to add or
create a new data array follow the numpy
syntax for creating arrays. The
following methods create and, optionally, initialize new arrays. The size of the
new array is determined by the at keyword, which indicates on which element
the array is defined. Methods with the prefix add_
will add the newly created
field to the grid, otherwise a newlycreated array is not added to the grid.
Create and add an uninitialized array of values to the field. 

Add an array of values to the field. 

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

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

Erases an existing field. 

Uninitialized array whose size is that of the field. 

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

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

Return field given a field name, or array of with the correct shape. 
Return the size of the arrays stored in a group. 

Return the field names in a group. 

Check if a group exists. 

Check if a field is in a group. 

Get units for a field. 

Return the values of a field. 

List of group names. 
Uncategorized or Deprecated#
The following functions are either uncategorized or deprecated. Uncategorized functions are simply those to which we have not yet assigned a category (but we will as we continue to improve the documentation). Although functions marked as deprecated are currently still available, they will be removed in a future Landlab release and so their use is discouraged.
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 

Indicates a boundary node is closed 

Indicates a node is core. 

Indicates a boundary node has a fixed gradient. 

Indicates a boundary node has a fixed value. 

Indicates a boundary node is wraparound. 

Grid elements on which fields can be placed. 

Adjacent corners for each grid corner. 

1=incoming flux, 1=outgoing 

Get adjacent corners. 

Get azimuths from every corner to every other corner. 

Get distances from every corner to every other corner. 

Get the angle of each face. 

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

Get the area of each cell. 

Create an xarray DataArray representation of a grid field. 

Create an xarray Dataset representation of a grid. 

EventLayers for each cell. 

Get array of boundary corners. 

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

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

Get array of closed boundary corners. 

Get array of core corners. 

Get array of core patches. 

Get array of corners associated with core patches. 

Get corners at face head. 

Get corners at face tail. 

A shaped array of corner ids. 

Get the corners that define a cell. 

Nodes at diagonal tail and head. 

Get corners at either end of faces. 

Nodes at nodes of grid. 

Links and diagonals attached to corners. 

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

Get adjacent corners along diagonals. 

Directions of diagonals attached to corners. 

Directions of diagonals attached to nodes. 

Diagonals attached to corners. 

EventLayers for each cell. 

Get the faces that define a cell. 

List of fields held by the grid. 

Get array of fixed faces. 

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

An array of the fixed_faces connected to fixed gradient boundary 

Get array of fixed gradient boundary corners. 

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

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

Get array of fixed value boundary corners. 

Freeze the graph by making arrays readonly. 

Create grid from a filelike object. 

List of group names. 

Plot a data field. 

Get the length of faces. 

Get directions of links touching a node. 

Return array of IDs of links with given angle. 

Links with a given node status. 

Get links touching a node. 

For each patch in a raster, return the D8 neighboring patches, looping 

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

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

Map data defined on links to nodes. 

MaterialLayers for each cell. 

Get the middle of faces. 

Number of spatial dimensions of the grid. 

A shaped array of node ids. 

Nodes at corners of grid. 

Nodes at diagonal tail and head. 

Get the number of cells. 

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

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

Number of core corners. 

Number of core patches. 

Get total number of corners. 

Number of links and diagonals. 

Number of diagonals in the grid. 

Get corners at face head. 

Number of fixed faces. 

Number of interior corners. 

Get nodes at link head. 

Number of patch columns. 

Number of patch rows. 

Get array of open boundary corners. 

Cell areas in a ncornerslong array. 

Get the shape of the patchular grid (grid with only patches). 

Get the patches on either side of each link. 

Get the patches that touch each node. 

Get array of patches in patchular grid (grid with only patches) nodes. 

Get nodes on the convex hull of a Graph. 

Get list of second ring looped neighbor patch IDs (all 16 neighbors). 

Sort graph elements. 

Get array of the boundary status for each corner. 

Status at diagonals. 

Get array of the status of all faces. 

Thaw the graph by making arrays writable. 

Write graph contents to a netCDF file. 

Get a unit vector for each corner. 

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

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

Get a unit vector for each node. 

Get array of xcomponent of unit vector sums at each corner. 

Get array of ycomponent of unit vector sums at each corner. 

Get xcoordinate of corner. 

Get the centroid of each cell. 

Get x and ycoordinates of corner. 

Return (x, y) of the reference point. 

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

Get ycoordinate of corner. 
For each cell in a raster, return the D8 neighboring cells, looping across grid boundaries as necessary. 
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 

Indicates a boundary node is closed 

Indicates a node is core. 

Indicates a boundary node has a fixed gradient. 

Indicates a boundary node has a fixed value. 

Indicates a boundary node is wraparound. 

Grid elements on which fields can be placed. 

Adjacent corners for each grid corner. 

1=incoming flux, 1=outgoing 

Get adjacent corners. 

Get azimuths from every corner to every other corner. 

Get distances from every corner to every other corner. 

Get the angle of each face. 

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

Get the area of each cell. 

Create an xarray DataArray representation of a grid field. 

Create an xarray Dataset representation of a grid. 

EventLayers for each cell. 

Get array of boundary corners. 

Get the cells that touch each corner. 

Get the cells on either side of each face. 

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

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

Get array of closed boundary corners. 

Get array of core corners. 

Get array of core patches. 

Get array of corners associated with core patches. 

Get corners at face head. 

Get corners at face tail. 

Get identifier for each corner. 

Get corners along the bottom edge. 

Get the corners that define a cell. 

Get corners at either end of faces. 

Get corners along the left edge. 

Get corners along the right edge. 

Get corners along the top edge. 

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

EventLayers for each cell. 

Get directions of faces touching a corner. 

Get the faces that define a cell. 

Get faces touching a corner. 

List of fields held by the grid. 

Get array of fixed faces. 

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

An array of the fixed_faces connected to fixed gradient boundary 

Get array of fixed gradient boundary corners. 

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

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

Get array of fixed value boundary corners. 

Freeze the graph by making arrays readonly. 

Create grid from dictionary. 

Create grid from a filelike object. 

List of group names. 

Plot a data field. 

Get the length of links. 

Get directions of links touching a node. 

Return array of IDs of links with given angle. 

Links with a given node status. 

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

Map data defined on links to nodes. 

MaterialLayers for each cell. 

Get the middle of faces. 

Number of spatial dimensions of the grid. 

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

Get nodes along the bottom edge. 

Get nodes along the left edge. 

Get nodes along the right edge. 

Get nodes along the top edge. 

Get the number of cells. 

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

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

Number of core corners. 

Number of core patches. 

Number of corner columns hex grid. 

Number of corner rows in a rectangularshaped and/or horizontally 

Get total number of corners. 

Get corners at face head. 

Number of fixed faces. 

Get nodes at link head. 

Get array of open boundary corners. 

Cell areas in a ncornerslong array. 

Get corners on the convex hull of a Graph. 

Sort graph elements. 

Get array of the boundary status for each corner. 

Get array of the status of all faces. 

Thaw the graph by making arrays writable. 

Write graph contents to a netCDF file. 

Get a unit vector for each corner. 

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

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

Get a unit vector for each node. 

Get array of xcomponent of unit vector sums at each corner. 

Get array of ycomponent of unit vector sums at each corner. 

Get xcoordinate of corner. 

Get the centroid of each cell. 

Get x and ycoordinates of corner. 

Return (x, y) of the reference point. 

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

Get ycoordinate of corner. 