Grid creation from a formatted input file#

Create landlab model grids.

exception BadGridTypeError(grid_type)[source]#

Bases: Error

Raise this error for a bad grid type.

exception Error[source]#

Bases: Exception

Base class for exceptions from this module.

add_boundary_conditions(grid, boundary_conditions=())[source]#

add_field_from_function(grid, name, functions, at='node')[source]#

Add a field to a grid as functions.

Parameters:

grid (ModelGrid) – A landlab grid to add fields to.
name (str) – Name of the new field.
functions ((func_name, func_args) or iterable of (func_name, func_args)) – The functions to apply to the field. Functions are applied in the order the appear in the list.
at (str) – The grid element to which the field will be added.

Returns:

The grid with the new field.

Return type:

ModelGrid

add_fields_from_dict(grid, fields)[source]#: Add fields to a grid from a dictionary.

as_list_of_tuples(items)[source]#

Convert a collection of key/values to a list of tuples.

Examples

>>> from collections import OrderedDict
>>> from landlab.grid.create import as_list_of_tuples
>>> as_list_of_tuples({"eric": "idle"})
[('eric', 'idle')]
>>> as_list_of_tuples([("john", "cleese"), {"eric": "idle"}])
[('john', 'cleese'), ('eric', 'idle')]
>>> as_list_of_tuples(
...     [("john", "cleese"), OrderedDict([("eric", "idle"), ("terry", "gilliam")])]
... )
[('john', 'cleese'), ('eric', 'idle'), ('terry', 'gilliam')]

create_grid(file_like, section=None)[source]#

Create grid, initialize fields, and set boundary conditions.

create_grid expects a dictionary with three keys: “grid”, “fields”, and “boundary_conditions”.

Dictionary Section “grid”

The value associated with the “grid” key should itself be a dictionary containing the name of a Landlab model grid type as its only key. The following grid types are valid:

RasterModelGrid

VoronoiDelaunayGrid

HexModelGrid

RadialModelGrid

NetworkModelGrid

The value associated with the grid name key is a list containing the arguments. If any keyword arguments are passed, they should be passed as the last element of the list. For example the following code block is a yaml file indicating a RasterModelGrid with shape (4, 5) and xy-spacing of (3, 4).

grid:
  RasterModelGrid:
    - [4, 5]
    - xy_spacing: [3, 4]

These arguments and keyword arguments will be passed to the __init__ constructor of the specified model grid. Refer to the documentation for each grid to determine its requirements.

Dictionary Section “fields”

Fields can be created by reading from files or by creating synthetic values.

The value associated with the “fields” key is a nested set of dictionaries indicating where the fields are created, what the field names are, and how to create the fields. As part of a grid’s description, the value associated with the “fields” key must be a dictionary with keys indicating at which grid elements fields should be created (e.g. to create fields at node, use “node”).

The value associated with each “xxx” (i.e. “node”, “link”, “patch”, etc.) value is itself a dictionary indicating the name of the field and how it should be created. A field can either be created by reading from a file or creating synthetic values. The read_netcdf and read_esri_ascii functions, and the synthetic fields package are currently supported methods to create fields. These may be chained together (as is shown in the Example section below). If these functions do not meet your needs, we welcome contributions that extend the capabilities of this function.

An additional supported method, which can be chained together with either synthetic fields or fields read from a file, is units. The units function will set the units attribute of its corresponding field. If this optional function is not used, the resulting field will not be given any units.

The following example would use the plane function from the synthetic values package to create a node value for the field topographic__elevation. The plane function adds values to a Landlab model grid field that lie on a plane specified by a point and a normal vector. In the below example the plane goes through the point (1.0, 1.0, 1.0) and has a normal of (-2.0, -1.0, 1.0). The units function sets the units of elevation to meters.

grid:
  RasterModelGrid:
    - [4, 5]
    - xy_spacing: [3, 4]
    - fields:
        node:
          topographic__elevation:
            plane:
              - point: [1, 1, 1]
                normal: [-2, -1, 1]
            units:
                - units: "meters"

Dictionary Section “boundary_conditions”

The final portion of the input dictionary calls bound functions of the model grid to set boundary conditions. Any valid bound function can be called. The specified functions are provided in a list, and called in order. If required, multiple functions may be called.

Each entry to the list is a dictionary with a single key, the name of the bound function. The value associated with that key is a list of arguments and keyword arguments, similar in structure to those described above. As with the “fields” section, the “boundary_conditions” section must be described under its associated grid description.

For example, the following sets closed boundaries at all sides of the grid.

grid:
  RasterModelGrid:
    - [4, 5]
    - xy_spacing: [3, 4]
    - boundary_conditions:
      - set_closed_boundaries_at_grid_edges:
        - True
        - True
        - True
        - True

Parameters:: file_like (file_like or str) – Dictionary, contents of a dictionary as a string, a file-like object, or the path to a file containing a YAML dictionary.

Examples

>>> import numpy as np
>>> from landlab import create_grid
>>> np.random.seed(42)
>>> p = {
...     "grid": {
...         "RasterModelGrid": [
...             (4, 5),
...             {"xy_spacing": (3, 4)},
...             {
...                 "fields": {
...                     "node": {
...                         "spam": {
...                             "plane": [
...                                 {"point": (1, 1, 1), "normal": (-2, -1, 1)}
...                             ],
...                             "random": [
...                                 {"distribution": "uniform", "low": 1, "high": 4}
...                             ],
...                         }
...                     },
...                     "link": {
...                         "eggs": {
...                             "constant": [{"where": "ACTIVE_LINK", "value": 12}]
...                         }
...                     },
...                 }
...             },
...             {
...                 "boundary_conditions": [
...                     {
...                         "set_closed_boundaries_at_grid_edges": [
...                             True,
...                             True,
...                             True,
...                             True,
...                         ]
...                     }
...                 ]
...             },
...         ]
...     }
... }
>>> mg = create_grid(p, section="grid")
>>> mg.number_of_nodes
20
>>> "spam" in mg.at_node
True
>>> "eggs" in mg.at_link
True
>>> mg.x_of_node
array([  0.,   3.,   6.,   9.,  12.,
         0.,   3.,   6.,   9.,  12.,
         0.,   3.,   6.,   9.,  12.,
         0.,   3.,   6.,   9.,  12.])
>>> mg.status_at_node
array([4, 4, 4, 4, 4,
       4, 0, 0, 0, 4,
       4, 0, 0, 0, 4,
       4, 4, 4, 4, 4], dtype=uint8)
>>> np.round(mg.at_node["spam"].reshape(mg.shape), decimals=2)
array([[  0.12,   7.85,  13.2 ,  18.8 ,  23.47],
       [  3.47,   9.17,  17.6 ,  22.8 ,  29.12],
       [  7.06,  15.91,  21.5 ,  25.64,  31.55],
       [ 11.55,  17.91,  24.57,  30.3 ,  35.87]])

grid_from_dict(grid_type, params)[source]#: Create a grid from a dictionary of parameters.

grids_from_file(file_like, section=None)[source]#: Create grids from a file.

norm_grid_description(grid_desc)[source]#

Normalize a grid description into a canonical form.

Examples

>>> from landlab.grid.create import norm_grid_description

>>> grid_desc = [(3, 4), {"xy_spacing": 4.0, "xy_of_lower_left": (1.0, 2.0)}]
>>> normed_items = list(norm_grid_description(grid_desc).items())
>>> normed_items.sort()
>>> normed_items
[('args', [(3, 4)]), ('xy_of_lower_left', (1.0, 2.0)), ('xy_spacing', 4.0)]