landlab.grid.create¶
Create landlab model grids.
- exception BadGridTypeError[source]¶
Bases:
Error
Raise this error for a bad grid type.
- __new__(**kwargs)¶
- add_note()¶
Exception.add_note(note) – add a note to the exception
- args¶
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception Error[source]¶
Bases:
Exception
Base class for exceptions from this module.
- __init__(*args, **kwargs)¶
- __new__(**kwargs)¶
- add_note()¶
Exception.add_note(note) – add a note to the exception
- args¶
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- 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:
- 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:
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
andload
functions, and thesynthetic 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:
str (file_like or) – 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]])
- 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)]