Landlab Fields

Submodules

landlab.field.graph_field module

class GraphFields(*args, **kwds)[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 differenct 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., 4.)
>>> 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])
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 (boolean, 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.empty

See for a description of optional keywords.

landlab.field.GraphFields.empty

Equivalent method that does not initialize the new array.

landlab.field.GraphFields.zeros

Equivalent method that initializes the data to 0.

LLCATS

FIELDCR

add_field(*args, **kwds)[source]

add_field(name, value_array, at=’node’, units=’-’, copy=False, clobber=False)

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 (boolean, optional) – If True, add a copy of the array to the field. Otherwise save add a reference to the array.

  • clobber (boolean, 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.array

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

LLCATS: FIELDCR

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 (boolean, optional) – If True, add a copy of the array to the field. Otherwise save add a reference to the array.

  • clobber (boolean, optional) – Raise an exception if adding to an already existing field.

Returns

  • array – A reference to the newly-created array.

  • LLCATS (FIELDCR)

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 (boolean, 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.ones

See for a description of optional keywords.

andlab.field.GraphFields.add_empty

Equivalent method that does not initialize the new array.

andlab.field.GraphFields.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.])

LLCATS: FIELDCR

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 (boolean, 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.

landlab.field.GraphFields.add_empty

Equivalent method that does not initialize the new array.

landlab.field.GraphFields.add_ones

Equivalent method that initializes the data to 1.

LLCATS

FIELDCR

property default_group
delete_field(loc, name)[source]

Erases an existing field.

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

  • name (str) – Name of the field.

Raises
  • KeyError – If the named field does not exist.

  • LLCATS – FIELDCR:

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.

landlab.field.GraphFields.ones

Equivalent method that initializes the data to 1.

landlab.field.GraphFields.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'))
[]

LLCATS: FIELDCR

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.

  • LLCATS – FIELDINF:

field_values(field, at=None)[source]

Get 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 withing group.

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

Returns

The values of the field.

Return type

array

Raises
  • GroupError – If group does not exits

  • FieldError – If field does not exits

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

LLCATS: FIELDIO

property groups

List of group names.

Returns

Set of quantity names.

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

boolean

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

LLCATS: FIELDINF

has_group(name)[source]

Check if a group exists.

Parameters

group (str) – Name of the group.

Returns

True if the field contains group, otherwise False.

Return type

boolean

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

LLCATS: FIELDINF

keys(group)[source]

List of field names in a group.

Returns a list of the field names as a list of strings.

Parameters

group (str) – Group name.

Returns

List of field names.

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

LLCATS: FIELDINF

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
  • group (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 goup.

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

LLCATS: FIELDCR

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.

landlab.field.GraphFields.empty

Equivalent method that does not initialize the new array.

landlab.field.GraphFields.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'))
[]

LLCATS: FIELDCR

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

array

Raises
  • GroupError – If group does not exits

  • FieldError – If field does not exits

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., 5., 7., 3.])
>>> 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., 2., 1.])
>>> fields.return_array_or_field_values(vals, at="node")
...     
Traceback (most recent call last):
ValueError: Array has incorrect size.

LLCATS: FIELDIO

size(group)[source]

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

LLCATS: GINF FIELDINF

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.

landlab.field.GraphFields.empty

Equivalent method that does not initialize the new array.

landlab.field.GraphFields.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'))
[]

LLCATS: FIELDCR