landlab.field.graph_field¶

Define collections of fields that are attached to a Landlab Graph.

class GraphFields[source]¶

Bases: object

Collection of grouped data-fields.

The GraphFields class holds a set of data fields that are separated into groups. A typical use for this class would be to define the groups as being locations on a grid where the values are defined. For instance, the groups could be node, cell, link, and face.

Examples

Create two groups of data fields defined at node and cell. Each set can have a different number of values.

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

Create some new value arrays for each of the data fields.

>>> fields.ones("node")
array([1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.])
>>> fields.zeros("cell")
array([0., 0.])

Create new value arrays and add them to the data fields. Because the data fields are in different groups (node and cell), they can have the same name.

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

>>> fields.add_ones("topographic__elevation", at="cell")
array([1., 1.])
>>> fields.at_cell["topographic__elevation"]
array([1., 1.])

Each group acts as a dict so, for instance, to get the variables names in a group use the keys method,

>>> list(fields.at_cell.keys())
['topographic__elevation']

If the size of the new field location is None, the field will be unsized. This means that fields added to this location can be of any size.

>>> fields = GraphFields()
>>> fields.new_field_location("grid", None)
>>> fields.at_grid["g"] = 9.81
>>> fields.at_grid["g"]
array(9.81)
>>> fields.at_grid["w"] = (3.0, 4.0)
>>> fields.at_grid["w"]
array([3., 4.])

The dimensions of groups can also be specified when the object is instantiated. In this case, group sizes are specified as a dictionary with keys being group names and values group sizes.

>>> fields = GraphFields({"node": 6, "grid": None})
>>> fields.at_grid["g"] = 9.81
>>> fields.at_node["x"] = [0, 1, 2, 3, 4, 5]
>>> fields.at_grid["g"]
array(9.81)
>>> fields.at_node["x"]
array([0, 1, 2, 3, 4, 5])

Create a new collection of field groups.

__getitem__(name)[source]¶: Get the collection of fields from the named group.

__init__(*args, **kwds)[source]¶: Create a new collection of field groups.

__new__(**kwargs)¶

add_empty(name, at='node', units='-', clobber=False)[source]¶

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

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

This method is not valid for the group grid.

Parameters:

name (str) – Name of the new field to add.
at (str, optional) – Grid location to store values. If not given, values are assumed to be on node.
units (str, optional) – Optionally specify the units of the field.
clobber (bool, optional) – Raise an exception if adding to an already existing field.

Returns:

A reference to the newly-created array.

Return type:

numpy.ndarray

See also

numpy.empty: See for a description of optional keywords.
empty: Equivalent method that does not initialize the new array.
zeros: Equivalent method that initializes the data to 0.

add_field(name, value_array, at='node', units='-', copy=False, clobber=False)[source]¶

Add an array of values to the field.

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

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

Parameters:

name (str) – Name of the new field to add.
value_array (numpy.array) – Array of values to add to the field.
at (str, optional) – Grid location to store values. If not given, values are assumed to be on node.
units (str, optional) – Optionally specify the units of the field.
copy (bool, optional) – If True, add a copy of the array to the field. Otherwise save add a reference to the array.
clobber (bool, optional) – Raise an exception if adding to an already existing field.

Returns:

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

Return type:

numpy.ndarray

Raises:

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

Examples

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

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

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

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

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

add_full(*args, **kwds)[source]¶

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

Parameters:

name (str) – Name of the new field to add.
fill_value (scalar) – Fill value.
at (str, optional) – Grid location to store values. If not given, values are assumed to be on node.
units (str, optional) – Optionally specify the units of the field.
copy (bool, optional) – If True, add a copy of the array to the field. Otherwise save add a reference to the array.
clobber (bool, optional) – Raise an exception if adding to an already existing field.

Returns:

A reference to the newly-created array.

Return type:

numpy.ndarray

add_ones(name, at='node', units='-', clobber=False)[source]¶

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

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

This method is not valid for the group grid.

Parameters:

name (str) – Name of the new field to add.
at (str, optional) – Grid location to store values. If not given, values are assumed to be on node.
units (str, optional) – Optionally specify the units of the field.
clobber (bool, optional) – Raise an exception if adding to an already existing field.

Returns:

A reference to the newly-created array.

Return type:

numpy.ndarray

See also

numpy.ones: See for a description of optional keywords.
add_empty: Equivalent method that does not initialize the new array.
add_zeros: Equivalent method that initializes the data to 0.

Examples

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

>>> from landlab.field import GraphFields
>>> field = GraphFields()
>>> field.new_field_location("node", 4)
>>> field.add_ones("topographic__elevation", at="node")
array([1., 1., 1., 1.])
>>> list(field.keys("node"))
['topographic__elevation']
>>> field["node"]["topographic__elevation"]
array([1., 1., 1., 1.])
>>> field.at_node["topographic__elevation"]
array([1., 1., 1., 1.])

add_zeros(name, at='node', units='-', clobber=False)[source]¶

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

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

Parameters:

name (str) – Name of the new field to add.
at (str, optional) – Grid location to store values. If not given, values are assumed to be on node.
units (str, optional) – Optionally specify the units of the field.
clobber (bool, optional) – Raise an exception if adding to an already existing field.

Returns:

A reference to the newly-created array.

Return type:

array

See also

numpy.zeros: See for a description of optional keywords.
add_empty: Equivalent method that does not initialize the new array.
add_ones: Equivalent method that initializes the data to 1.

property default_group¶: Return the name of the group into which fields are put by default.

delete_field(loc, name)[source]¶

Erases an existing field.

Parameters:

loc (str) – Name of the group.
name (str) – Name of the field.

Raises:

KeyError – If the named field does not exist.

empty(*args, **kwds)[source]¶

Uninitialized array whose size is that of the field.

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

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

See also

numpy.empty: See for a description of optional keywords.
ones: Equivalent method that initializes the data to 1.
zeros: Equivalent method that initializes the data to 0.

Examples

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

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

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

field_units(field, at=None)[source]¶

Get units for a field.

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

Parameters:

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

Returns:

The units of the field.

Return type:

str

Raises:

KeyError – If either field or group does not exist.

field_values(field, at=None)[source]¶

Return the values of a field.

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

Parameters:

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

Returns:

The values of the field.

Return type:

array

Raises:

landlab.field.errors.GroupError – If group does not exist
landlab.field.errors.FieldError – If field does not exist

Examples

Create a group of fields called node.

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

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

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

Raise FieldError if field does not exist in group.

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

If group does not exists, raise GroupError.

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

property groups¶

List of group names.

Returns:: Names of field groupings.
Return type:: set

has_field(field, at=None)[source]¶

Check if a field is in a group.

Parameters:

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

Returns:

True if the group contains the field, otherwise False.

Return type:

bool

Examples

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

>>> from landlab.field import GraphFields

>>> fields = GraphFields()
>>> fields.new_field_location("node", 12)
>>> _ = fields.add_ones("topographic__elevation", at="node")
>>> fields.has_field("topographic__elevation", at="node")
True
>>> fields.has_field("topographic__elevation", at="cell")
False

>>> fields = GraphFields()
>>> fields.new_field_location("node", 12)
>>> _ = fields.add_ones("topographic__elevation", at="node")
>>> fields.has_field("node", "topographic__elevation")
True
>>> fields.has_field("cell", "topographic__elevation")
False

has_group(name)[source]¶

Check if a group exists.

Parameters:: name (str) – Name of the group.
Returns:: True if the field contains group, otherwise False.
Return type:: bool

Examples

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

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

keys(group)[source]¶

Return the field names in a group.

Parameters:: group (str) – Group name.
Returns:: Names of fields held in the given group.
Return type:: list

Examples

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

new_field_location(loc, size=None)[source]¶

Add a new quantity to a field.

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

Parameters:

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

Raises:

ValueError – If the field already contains the group.

Examples

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

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

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

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

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

>>> fields.at_cell
FieldDataset('cell', size=2, fixed_size=True)
>>> fields.at_node
FieldDataset('node', size=12, fixed_size=True)

>>> fields.new_field_location("core_node")
>>> fields.at_core_node.size is None
True
>>> fields.at_core_node["air__temperature"] = [0, 1]
>>> fields.at_core_node.size
2

ones(*args, **kwds)[source]¶

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

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

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

See also

numpy.ones: See for a description of optional keywords.
empty: Equivalent method that does not initialize the new array.
zeros: Equivalent method that initializes the data to 0.

Examples

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

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

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

return_array_or_field_values(field, at=None)[source]¶

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

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

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

Parameters:

field (str or array) – Name of the field withing group.
at (str, optional) – Name of the group.

Returns:

The values of the field.

Return type:

numpy.ndarray

Raises:

landlab.field.errors.GroupError – If group does not exist
landlab.field.errors.FieldError – If field does not exist

Examples

Create a group of fields called node.

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

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

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

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

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

Raise FieldError if field does not exist in group.

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

If group does not exists, Raise GroupError.

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

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

>>> vals = np.array([3.0, 2.0, 1.0])
>>> fields.return_array_or_field_values(vals, at="node")
Traceback (most recent call last):
...
ValueError: Array has incorrect size.

size(group)[source]¶

Return the size of the arrays stored in a group.

Parameters:: group (str) – Group name.
Returns:: Array size.
Return type:: int

Examples

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

zeros(*args, **kwds)[source]¶

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

Parameters:

group (str) – Name of the group.
size (Return a new array of the data field)
Keyword (filled with zeros.)
function. (arguments are the same as that for the equivalent numpy)
grid. (This method is not valid for the group)

See also

numpy.zeros: See for a description of optional keywords.
empty: Equivalent method that does not initialize the new array.
ones: Equivalent method that initializes the data to 1.

Examples

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

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

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