landlab.field package¶

Submodules¶

landlab.field.field_mixin module¶

class ModelDataFieldsMixIn(**kwds)[source]¶

Bases: landlab.field.grouped.ModelDataFields

Mix-in that provides un-sized fields.

Inherit from this class to provide fields that do not have to be given a size on instantiation. The size of a particular group will only be set after the first time a group is accessed (a field is added to a group or an array is created for a group). The size of that group will be the size as returned by the number_of_elements method.

This mix-in assumes it is being added to a class that implements a method that, given an element name as a string, returns the number of elements for that group. A RasterModelGrid is an excellent example of this.

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.number_of_elements('node')
20

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

Array, filled with unititialized values, for a given element.

Returns a numpy array of uninitialized values that is the same length as the number of nodes in the grid. Use the centering keyword to return an array for other elements of the grid. centering is a string that is one of node, cell, link, or face.

All other keywords are the same as for the numpy zeros function.

Parameters:

centering : str, optional

Grid element on which the values are defined.

Returns:

ndarray

A newly-allocated array.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> len(grid.empty())
20

LLCATS: FIELDADD

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

Array, filled with ones, for a given element.

Returns a numpy array of ones that is the same length as the number of nodes in the grid. Use the centering keyword to return an array for other elements of the grid. centering is a string that is one of node, cell, link, or face.

All other keywords are the same as for the numpy zeros function.

Parameters:

centering : str, optional

Grid element on which the values are defined.

Returns:

ndarray

A newly-allocated array.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.zeros(dtype=int) 
array([0, 0, 0, 0, 0,
       0, 0, 0, 0, 0,
       0, 0, 0, 0, 0,
       0, 0, 0, 0, 0])
>>> grid.zeros('cell') 
array([ 0., 0., 0.,
        0., 0., 0.])

LLCATS: FIELDADD

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

Array, filled with zeros, for a given element.

Returns a numpy array of zeros that is the same length as the number of nodes in the grid. Use the centering keyword to return an array for other elements of the grid. centering is a string that is one of node, cell, link, or face.

All other keywords are the same as for the numpy zeros function.

Parameters:

centering : str, optional

Grid element on which the values are defined.

Returns:

ndarray

A newly-allocated array.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.zeros()
array([ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,
        0.,  0.,  0.,  0.,  0.,  0.,  0.])

LLCATS: FIELDADD

landlab.field.grouped module¶

Store collections of data fields.

exception Error[source]¶

Bases: exceptions.Exception

Base class for errors in this module.

exception GroupError(group)[source]¶

Bases: landlab.field.grouped.Error, exceptions.KeyError

Raise this error for a missing group name.

exception GroupSizeError(group, old_size, new_size)[source]¶

Bases: landlab.field.grouped.Error, exceptions.KeyError

Raise this error if a group has changed sizes.

class ModelDataFields(**kwds)[source]¶

Bases: object

Collection of grouped data-fields.

The ModelDataFields class holds a set of ScalarDataFields 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.

Most of the method functions for ModelDataFields are the same as those for the ScalarDataFields class but with the first argument being a string that defines the group name.

See also

landlab.field.ScalarDataFields: Data fields within a group are stored as landlab.field.ScalarDataFields.
landlab.grid.ModelGrid: Inherits from ModelDataFields.

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 ModelDataFields
>>> fields = ModelDataFields()
>>> 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('node', 'topographic__elevation')
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('cell', 'topographic__elevation')
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']

Attributes

groups List of group names.

add_empty(*args, **kwds)[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.

Construction:

add_empty(group, name, units='-', noclobber=True)

Parameters:

group : str

Name of the group.

name : str

Name of the new field to add.

units : str, optional

Optionally specify the units of the field.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

array :

A reference to the newly-created array.

See also

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

add_field(*args, **kwds)[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.

Construction:

add_field(group, name, value_array, units='-', copy=False,
          noclobber=True)

Parameters:

group : str

Name of the group.

name : str

Name of the new field to add.

value_array : numpy.array

Array of values to add to the field.

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.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

numpy.array

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

Raises:

ValueError :

If value_array has a size different from the field.

Examples

>>> import numpy as np
>>> from landlab.field import ModelDataFields
>>> field = ModelDataFields()
>>> field.new_field_location('node', 4)
>>> values = np.ones(4, dtype=int)
>>> field.add_field('node', 'topographic__elevation', values)
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 noclobber keyword changes this behavior to raise an exception in such a case.

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

LLCATS: FIELDCR

add_ones(*args, **kwds)[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.

Construction:

add_ones(group, name, units='-', noclobber=True)

Parameters:

group : str

Name of the group.

name : str

Name of the new field to add.

units : str, optional

Optionally specify the units of the field.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

array :

A reference to the newly-created array.

See also

numpy.ones: See for a description of optional keywords.
andlab.field.ModelDataFields.add_empty: Equivalent method that does not initialize the new array.
andlab.field.ModelDataFields.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 ModelDataFields
>>> field = ModelDataFields()
>>> field.new_field_location('node', 4)
>>> field.add_ones('node', 'topographic__elevation')
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(*args, **kwds)[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.

Construction:

add_zeros(group, name, units='-', noclobber=True)

Parameters:

group : str

Name of the group.

name : str

Name of the new field to add.

units : str, optional

Optionally specify the units of the field.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

array :

A reference to the newly-created array.

See also

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

delete_field(group, 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(group, **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.ModelDataFields.ones: Equivalent method that initializes the data to 1.
landlab.field.ModelDataFields.zeros: Equivalent method that initializes the data to 0.

Examples

>>> from landlab.field import ModelDataFields
>>> field = ModelDataFields()
>>> 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(group, field)[source]¶

Get units for a field.

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

Parameters:

group: str

Name of the group.

field: str

Name of the field withing group.

Returns:

str

The units of the field.

Raises:

KeyError

If either field or group does not exist.

LLCATS: FIELDINF

field_values(group, field)[source]¶

Get values of a field.

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

Parameters:

group: str

Name of the group.

field: str

Name of the field withing group.

Returns:

array

The values of the field.

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 ModelDataFields
>>> fields = ModelDataFields()
>>> 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('node', 'topographic__elevation')
>>> fields.field_values('node', 'topographic__elevation')
array([ 1.,  1.,  1.,  1.])

Raise FieldError if field does not exist in group.

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

If group does not exists, Raise GroupError.

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

LLCATS: FIELDIO

groups¶

List of group names.

Returns:

set

Set of quantity names.

has_field(group, field)[source]¶

Check if a field is in a group.

Parameters:

group: str

Name of the group.

field: str

Name of the field.

Returns:

boolean

True if the group contains the field, otherwise False.

Examples

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

>>> from landlab.field import ModelDataFields
>>> fields = ModelDataFields()
>>> fields.new_field_location('node', 12)
>>> _ = fields.add_ones('node', 'topographic__elevation')
>>> fields.has_field('node', 'topographic__elevation')
True
>>> fields.has_field('cell', 'topographic__elevation')
False

LLCATS: FIELDINF

has_group(group)[source]¶

Check if a group exists.

Parameters:

group: str

Name of the group.

Returns:

boolean

True if the field contains group, otherwise False.

Examples

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

>>> from landlab.field import ModelDataFields
>>> fields = ModelDataFields()
>>> 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

List of field names.

Examples

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

LLCATS: FIELDINF

new_field_location(group, 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 ModelDataFields
>>> fields = ModelDataFields()
>>> 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, fields.at_node
({}, {})

>>> 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(group, **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.ModelDataFields.empty: Equivalent method that does not initialize the new array.
landlab.field.ModelDataFields.zeros: Equivalent method that initializes the data to 0.

Examples

>>> from landlab.field import ModelDataFields
>>> field = ModelDataFields()
>>> 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

set_default_group(group)[source]¶

Set the default group for which fields are added.

Parameters:

group : str

Name of a group to use as a default.

Examples

>>> from landlab.field import ModelDataFields
>>> fields = ModelDataFields()
>>> fields.new_field_location('node', 12)

>>> fields.add_field('z', [1.] * 12)
...     
Traceback (most recent call last):
ValueError: missing group name
>>> fields.set_default_group('node')
>>> _ = fields.add_field('z', [1.] * 12)
>>> 'z' in fields.at_node
True

set_units(group, name, units)[source]¶

Set the units for a field of values.

Parameters:

group : str

Name of the group.

name: str

Name of the field.

units: str

Units for the field.

Raises:

KeyError

If the named field does not exist.

LLCATS: FIELDCR FIELDIO

size(group)[source]¶

Size of the arrays stored in a group.

Parameters:

group : str

Group name.

Returns:

int

Array size.

Examples

>>> from landlab.field import ModelDataFields
>>> fields = ModelDataFields()
>>> fields.new_field_location('node', 4)
>>> fields.size('node')
4

LLCATS: GINF FIELDINF

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

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

Parameters:

group : str

Name of the group.

Return a new array of the data field size, filled with zeros. Keyword

arguments are the same as that for the equivalent numpy function.

This method is not valid for the group *grid*.

See also

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

Examples

>>> from landlab.field import ModelDataFields
>>> field = ModelDataFields()
>>> 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

landlab.field.scalar_data_fields module¶

Container that holds a collection of named data-fields.

exception Error[source]¶

Bases: exceptions.Exception

Base class for errors in this module.

exception FieldError(field)[source]¶

Bases: landlab.field.scalar_data_fields.Error, exceptions.KeyError

Raise this error for a missing field name.

class ScalarDataFields(size=None)[source]¶

Bases: dict

Collection of named data fields that are of the same size.

Holds a collection of data fields that all contain the same number of elements and index each of them with a name. This class inherits from a standard Python dict, which allows access to the fields through dict-like syntax.

The syntax .at_[element] can also be used as syntactic sugar to access fields. e.g., n1 = fields.at_node[‘name1’], n2 = grid.at_link[‘name2’].

Parameters:

size : int

The number of elements in each of the data fields.

See also

landlab.field.ModelDataFields.ones: Hold collections of ScalarDataFields.

Examples

>>> from landlab.field import ScalarDataFields
>>> fields = ScalarDataFields(5)
>>> fields.add_field('land_surface__elevation', [1, 2, 3, 4, 5])
array([1, 2, 3, 4, 5])
>>> fields['air__temperature'] = [2, 3, 4, 5, 6]
>>> fields['land_surface__temperature'] = [0, 1]
...     
Traceback (most recent call last):
ValueError: total size of the new array must be the same as the field

Fields can also be multidimensional arrays so long as they can be resized such that the first dimension is the size of the field. The stored field will be resized view of the input array such that the size of the first dimension is the size of the field.

>>> fields['air__temperature'] = [2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
>>> fields['air__temperature']
array([[ 2,  3],
       [ 4,  5],
       [ 6,  7],
       [ 8,  9],
       [10, 11]])

You can also create unsized fields. These fields will not be sized until the first field is added to the collection. Once the size is set, all fields must be the same size.

>>> fields = ScalarDataFields()
>>> fields['land_surface__temperature'] = [0, 1]
>>> fields['land_surface__temperature']
array([0, 1])
>>> fields['air__temperature'] = [2, 3, 4, 5, 6]
...     
Traceback (most recent call last):
ValueError: total size of the new array must be the same as the field

Fields defined on a grid, which inherits from the ScalarModelFields class, behave similarly, though the length of those fields will be forced by the element type they are defined on:

>>> from landlab import RasterModelGrid
>>> import numpy as np
>>> mg = RasterModelGrid((4, 5))
>>> z = mg.add_field('cell', 'topographic__elevation', np.random.rand(
...         mg.number_of_cells), units='m')
>>> mg.at_cell['topographic__elevation'].size == mg.number_of_cells
True

LLCATS: FIELDCR, FIELDIO

Attributes

`units`	Get units for values of the field.
`size`	Number of elements in the field.

add_empty(name, units='?', noclobber=True, **kwds)[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.

Parameters:

name : str

Name of the new field to add.

units : str, optional

Optionally specify the units of the field.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

array :

A reference to the newly-created array.

See also

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

add_field(name, value_array, units='?', copy=False, noclobber=True, **kwds)[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.

Parameters:

name : str

Name of the new field to add.

value_array : numpy.array

Array of values to add to the field.

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.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

numpy.array

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

Raises:

ValueError :

If value_array has a size different from the field.

Examples

>>> import numpy as np
>>> from landlab.field import ScalarDataFields
>>> field = ScalarDataFields(4)
>>> values = np.ones(4, dtype=int)
>>> field.add_field('topographic__elevation', values)
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['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 noclobber keyword changes this behavior to raise an exception in such a case.

>>> field.add_field('topographic__elevation', values, copy=True,
...                 noclobber=False)
array([1, 1, 1, 1])
>>> field['topographic__elevation'] is values
False
>>> field.add_field('topographic__elevation', values, noclobber=True)
...     
Traceback (most recent call last):
FieldError: topographic__elevation already exists

LLCATS: FIELDCR

add_ones(name, units='?', noclobber=True, **kwds)[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.

Parameters:

name : str

Name of the new field to add.

units : str, optional

Optionally specify the units of the field.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

array :

A reference to the newly-created array.

See also

numpy.ones: See for a description of optional keywords.
andlab.field.ScalarDataFields.add_empty: Equivalent method that does not initialize the new array.
andlab.field.ScalarDataFields.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 ScalarDataFields
>>> field = ScalarDataFields(4)
>>> field.add_ones('topographic__elevation')
array([ 1.,  1.,  1.,  1.])
>>> list(field.keys())
['topographic__elevation']
>>> field['topographic__elevation']
array([ 1.,  1.,  1.,  1.])

LLCATS: FIELDCR

add_zeros(name, units='?', noclobber=True, **kwds)[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.

units : str, optional

Optionally specify the units of the field.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

array :

A reference to the newly-created array.

See also

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

empty(**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.

See also

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

Examples

>>> from landlab.field import ScalarDataFields
>>> field = ScalarDataFields(4)
>>> field.empty() 
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())
[]

ones(**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.

See also

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

Examples

>>> from landlab.field import ScalarDataFields
>>> field = ScalarDataFields(4)
>>> field.ones()
array([ 1.,  1.,  1.,  1.])
>>> field.ones(dtype=int)
array([1, 1, 1, 1])

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

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

set_units(name, units)[source]¶

Set the units for a field of values.

Parameters:

name: str

Name of the field.

units: str

Units for the field

Raises:

KeyError

If the named field does not exist.

LLCATS: FIELDCR

size¶

Number of elements in the field.

Returns:

int

The number of elements in the field.

units¶

Get units for values of the field.

Returns:

str

Units of the field.

zeros(**kwds)[source]¶

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

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

See also

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

Examples

>>> from landlab.field import ScalarDataFields
>>> field = ScalarDataFields(4)
>>> field.zeros()
array([ 0.,  0.,  0.,  0.])

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

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

need_to_reshape_array(array, field_size)[source]¶

Check to see if an array needs to be resized before storing.

When possible, a reference to an array is stored. However, if the array is not of the correct shape, a view of the array (with the correct shape) is stored.

Parameters:

array : numpy array

Numpy array to check.

field_size : int

Size of the field the array will be placed into.

Returns:

bool

True is the array should be resized.

Module contents¶

class ScalarDataFields(size=None)[source]¶

Bases: dict

Collection of named data fields that are of the same size.

Holds a collection of data fields that all contain the same number of elements and index each of them with a name. This class inherits from a standard Python dict, which allows access to the fields through dict-like syntax.

The syntax .at_[element] can also be used as syntactic sugar to access fields. e.g., n1 = fields.at_node[‘name1’], n2 = grid.at_link[‘name2’].

Parameters:

size : int

The number of elements in each of the data fields.

See also

landlab.field.ModelDataFields.ones: Hold collections of ScalarDataFields.

Examples

>>> from landlab.field import ScalarDataFields
>>> fields = ScalarDataFields(5)
>>> fields.add_field('land_surface__elevation', [1, 2, 3, 4, 5])
array([1, 2, 3, 4, 5])
>>> fields['air__temperature'] = [2, 3, 4, 5, 6]
>>> fields['land_surface__temperature'] = [0, 1]
...     
Traceback (most recent call last):
ValueError: total size of the new array must be the same as the field

Fields can also be multidimensional arrays so long as they can be resized such that the first dimension is the size of the field. The stored field will be resized view of the input array such that the size of the first dimension is the size of the field.

>>> fields['air__temperature'] = [2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
>>> fields['air__temperature']
array([[ 2,  3],
       [ 4,  5],
       [ 6,  7],
       [ 8,  9],
       [10, 11]])

You can also create unsized fields. These fields will not be sized until the first field is added to the collection. Once the size is set, all fields must be the same size.

>>> fields = ScalarDataFields()
>>> fields['land_surface__temperature'] = [0, 1]
>>> fields['land_surface__temperature']
array([0, 1])
>>> fields['air__temperature'] = [2, 3, 4, 5, 6]
...     
Traceback (most recent call last):
ValueError: total size of the new array must be the same as the field

Fields defined on a grid, which inherits from the ScalarModelFields class, behave similarly, though the length of those fields will be forced by the element type they are defined on:

>>> from landlab import RasterModelGrid
>>> import numpy as np
>>> mg = RasterModelGrid((4, 5))
>>> z = mg.add_field('cell', 'topographic__elevation', np.random.rand(
...         mg.number_of_cells), units='m')
>>> mg.at_cell['topographic__elevation'].size == mg.number_of_cells
True

LLCATS: FIELDCR, FIELDIO

Attributes

`units`	Get units for values of the field.
`size`	Number of elements in the field.

add_empty(name, units='?', noclobber=True, **kwds)[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.

Parameters:

name : str

Name of the new field to add.

units : str, optional

Optionally specify the units of the field.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

array :

A reference to the newly-created array.

See also

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

add_field(name, value_array, units='?', copy=False, noclobber=True, **kwds)[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.

Parameters:

name : str

Name of the new field to add.

value_array : numpy.array

Array of values to add to the field.

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.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

numpy.array

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

Raises:

ValueError :

If value_array has a size different from the field.

Examples

>>> import numpy as np
>>> from landlab.field import ScalarDataFields
>>> field = ScalarDataFields(4)
>>> values = np.ones(4, dtype=int)
>>> field.add_field('topographic__elevation', values)
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['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 noclobber keyword changes this behavior to raise an exception in such a case.

>>> field.add_field('topographic__elevation', values, copy=True,
...                 noclobber=False)
array([1, 1, 1, 1])
>>> field['topographic__elevation'] is values
False
>>> field.add_field('topographic__elevation', values, noclobber=True)
...     
Traceback (most recent call last):
FieldError: topographic__elevation already exists

LLCATS: FIELDCR

add_ones(name, units='?', noclobber=True, **kwds)[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.

Parameters:

name : str

Name of the new field to add.

units : str, optional

Optionally specify the units of the field.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

array :

A reference to the newly-created array.

See also

numpy.ones: See for a description of optional keywords.
andlab.field.ScalarDataFields.add_empty: Equivalent method that does not initialize the new array.
andlab.field.ScalarDataFields.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 ScalarDataFields
>>> field = ScalarDataFields(4)
>>> field.add_ones('topographic__elevation')
array([ 1.,  1.,  1.,  1.])
>>> list(field.keys())
['topographic__elevation']
>>> field['topographic__elevation']
array([ 1.,  1.,  1.,  1.])

LLCATS: FIELDCR

add_zeros(name, units='?', noclobber=True, **kwds)[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.

units : str, optional

Optionally specify the units of the field.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

array :

A reference to the newly-created array.

See also

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

empty(**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.

See also

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

Examples

>>> from landlab.field import ScalarDataFields
>>> field = ScalarDataFields(4)
>>> field.empty() 
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())
[]

ones(**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.

See also

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

Examples

>>> from landlab.field import ScalarDataFields
>>> field = ScalarDataFields(4)
>>> field.ones()
array([ 1.,  1.,  1.,  1.])
>>> field.ones(dtype=int)
array([1, 1, 1, 1])

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

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

set_units(name, units)[source]¶

Set the units for a field of values.

Parameters:

name: str

Name of the field.

units: str

Units for the field

Raises:

KeyError

If the named field does not exist.

LLCATS: FIELDCR

size¶

Number of elements in the field.

Returns:

int

The number of elements in the field.

units¶

Get units for values of the field.

Returns:

str

Units of the field.

zeros(**kwds)[source]¶

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

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

See also

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

Examples

>>> from landlab.field import ScalarDataFields
>>> field = ScalarDataFields(4)
>>> field.zeros()
array([ 0.,  0.,  0.,  0.])

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

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

class ModelDataFields(**kwds)[source]¶

Bases: object

Collection of grouped data-fields.

The ModelDataFields class holds a set of ScalarDataFields 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.

Most of the method functions for ModelDataFields are the same as those for the ScalarDataFields class but with the first argument being a string that defines the group name.

See also

landlab.field.ScalarDataFields: Data fields within a group are stored as landlab.field.ScalarDataFields.
landlab.grid.ModelGrid: Inherits from ModelDataFields.

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 ModelDataFields
>>> fields = ModelDataFields()
>>> 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('node', 'topographic__elevation')
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('cell', 'topographic__elevation')
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']

Attributes

groups List of group names.

add_empty(*args, **kwds)[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.

Construction:

add_empty(group, name, units='-', noclobber=True)

Parameters:

group : str

Name of the group.

name : str

Name of the new field to add.

units : str, optional

Optionally specify the units of the field.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

array :

A reference to the newly-created array.

See also

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

add_field(*args, **kwds)[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.

Construction:

add_field(group, name, value_array, units='-', copy=False,
          noclobber=True)

Parameters:

group : str

Name of the group.

name : str

Name of the new field to add.

value_array : numpy.array

Array of values to add to the field.

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.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

numpy.array

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

Raises:

ValueError :

If value_array has a size different from the field.

Examples

>>> import numpy as np
>>> from landlab.field import ModelDataFields
>>> field = ModelDataFields()
>>> field.new_field_location('node', 4)
>>> values = np.ones(4, dtype=int)
>>> field.add_field('node', 'topographic__elevation', values)
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 noclobber keyword changes this behavior to raise an exception in such a case.

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

LLCATS: FIELDCR

add_ones(*args, **kwds)[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.

Construction:

add_ones(group, name, units='-', noclobber=True)

Parameters:

group : str

Name of the group.

name : str

Name of the new field to add.

units : str, optional

Optionally specify the units of the field.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

array :

A reference to the newly-created array.

See also

numpy.ones: See for a description of optional keywords.
andlab.field.ModelDataFields.add_empty: Equivalent method that does not initialize the new array.
andlab.field.ModelDataFields.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 ModelDataFields
>>> field = ModelDataFields()
>>> field.new_field_location('node', 4)
>>> field.add_ones('node', 'topographic__elevation')
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(*args, **kwds)[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.

Construction:

add_zeros(group, name, units='-', noclobber=True)

Parameters:

group : str

Name of the group.

name : str

Name of the new field to add.

units : str, optional

Optionally specify the units of the field.

noclobber : boolean, optional

Raise an exception if adding to an already existing field.

Returns:

array :

A reference to the newly-created array.

See also

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

delete_field(group, 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(group, **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.ModelDataFields.ones: Equivalent method that initializes the data to 1.
landlab.field.ModelDataFields.zeros: Equivalent method that initializes the data to 0.

Examples

>>> from landlab.field import ModelDataFields
>>> field = ModelDataFields()
>>> 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(group, field)[source]¶

Get units for a field.

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

Parameters:

group: str

Name of the group.

field: str

Name of the field withing group.

Returns:

str

The units of the field.

Raises:

KeyError

If either field or group does not exist.

LLCATS: FIELDINF

field_values(group, field)[source]¶

Get values of a field.

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

Parameters:

group: str

Name of the group.

field: str

Name of the field withing group.

Returns:

array

The values of the field.

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 ModelDataFields
>>> fields = ModelDataFields()
>>> 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('node', 'topographic__elevation')
>>> fields.field_values('node', 'topographic__elevation')
array([ 1.,  1.,  1.,  1.])

Raise FieldError if field does not exist in group.

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

If group does not exists, Raise GroupError.

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

LLCATS: FIELDIO

groups¶

List of group names.

Returns:

set

Set of quantity names.

has_field(group, field)[source]¶

Check if a field is in a group.

Parameters:

group: str

Name of the group.

field: str

Name of the field.

Returns:

boolean

True if the group contains the field, otherwise False.

Examples

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

>>> from landlab.field import ModelDataFields
>>> fields = ModelDataFields()
>>> fields.new_field_location('node', 12)
>>> _ = fields.add_ones('node', 'topographic__elevation')
>>> fields.has_field('node', 'topographic__elevation')
True
>>> fields.has_field('cell', 'topographic__elevation')
False

LLCATS: FIELDINF

has_group(group)[source]¶

Check if a group exists.

Parameters:

group: str

Name of the group.

Returns:

boolean

True if the field contains group, otherwise False.

Examples

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

>>> from landlab.field import ModelDataFields
>>> fields = ModelDataFields()
>>> 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

List of field names.

Examples

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

LLCATS: FIELDINF

new_field_location(group, 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 ModelDataFields
>>> fields = ModelDataFields()
>>> 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, fields.at_node
({}, {})

>>> 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(group, **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.ModelDataFields.empty: Equivalent method that does not initialize the new array.
landlab.field.ModelDataFields.zeros: Equivalent method that initializes the data to 0.

Examples

>>> from landlab.field import ModelDataFields
>>> field = ModelDataFields()
>>> 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

set_default_group(group)[source]¶

Set the default group for which fields are added.

Parameters:

group : str

Name of a group to use as a default.

Examples

>>> from landlab.field import ModelDataFields
>>> fields = ModelDataFields()
>>> fields.new_field_location('node', 12)

>>> fields.add_field('z', [1.] * 12)
...     
Traceback (most recent call last):
ValueError: missing group name
>>> fields.set_default_group('node')
>>> _ = fields.add_field('z', [1.] * 12)
>>> 'z' in fields.at_node
True

set_units(group, name, units)[source]¶

Set the units for a field of values.

Parameters:

group : str

Name of the group.

name: str

Name of the field.

units: str

Units for the field.

Raises:

KeyError

If the named field does not exist.

LLCATS: FIELDCR FIELDIO

size(group)[source]¶

Size of the arrays stored in a group.

Parameters:

group : str

Group name.

Returns:

int

Array size.

Examples

>>> from landlab.field import ModelDataFields
>>> fields = ModelDataFields()
>>> fields.new_field_location('node', 4)
>>> fields.size('node')
4

LLCATS: GINF FIELDINF

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

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

Parameters:

group : str

Name of the group.

Return a new array of the data field size, filled with zeros. Keyword

arguments are the same as that for the equivalent numpy function.

This method is not valid for the group *grid*.

See also

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

Examples

>>> from landlab.field import ModelDataFields
>>> field = ModelDataFields()
>>> 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

class ModelDataFieldsMixIn(**kwds)[source]¶

Bases: landlab.field.grouped.ModelDataFields

Mix-in that provides un-sized fields.

Inherit from this class to provide fields that do not have to be given a size on instantiation. The size of a particular group will only be set after the first time a group is accessed (a field is added to a group or an array is created for a group). The size of that group will be the size as returned by the number_of_elements method.

This mix-in assumes it is being added to a class that implements a method that, given an element name as a string, returns the number of elements for that group. A RasterModelGrid is an excellent example of this.

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.number_of_elements('node')
20

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

Array, filled with unititialized values, for a given element.

Returns a numpy array of uninitialized values that is the same length as the number of nodes in the grid. Use the centering keyword to return an array for other elements of the grid. centering is a string that is one of node, cell, link, or face.

All other keywords are the same as for the numpy zeros function.

Parameters:

centering : str, optional

Grid element on which the values are defined.

Returns:

ndarray

A newly-allocated array.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> len(grid.empty())
20

LLCATS: FIELDADD

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

Array, filled with ones, for a given element.

Returns a numpy array of ones that is the same length as the number of nodes in the grid. Use the centering keyword to return an array for other elements of the grid. centering is a string that is one of node, cell, link, or face.

All other keywords are the same as for the numpy zeros function.

Parameters:

centering : str, optional

Grid element on which the values are defined.

Returns:

ndarray

A newly-allocated array.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.zeros(dtype=int) 
array([0, 0, 0, 0, 0,
       0, 0, 0, 0, 0,
       0, 0, 0, 0, 0,
       0, 0, 0, 0, 0])
>>> grid.zeros('cell') 
array([ 0., 0., 0.,
        0., 0., 0.])

LLCATS: FIELDADD

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

Array, filled with zeros, for a given element.

Returns a numpy array of zeros that is the same length as the number of nodes in the grid. Use the centering keyword to return an array for other elements of the grid. centering is a string that is one of node, cell, link, or face.

All other keywords are the same as for the numpy zeros function.

Parameters:

centering : str, optional

Grid element on which the values are defined.

Returns:

ndarray

A newly-allocated array.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5))
>>> grid.zeros()
array([ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,
        0.,  0.,  0.,  0.,  0.,  0.,  0.])

LLCATS: FIELDADD

exception FieldError(field)[source]¶

Bases: landlab.field.scalar_data_fields.Error, exceptions.KeyError

Raise this error for a missing field name.

exception GroupError(group)[source]¶

Bases: landlab.field.grouped.Error, exceptions.KeyError

Raise this error for a missing group name.

exception GroupSizeError(group, old_size, new_size)[source]¶

Bases: landlab.field.grouped.Error, exceptions.KeyError

Raise this error if a group has changed sizes.

INDEX

Table Of Contents

This Page

landlab.field package¶

Submodules¶

landlab.field.field_mixin module¶

landlab.field.grouped module¶

landlab.field.scalar_data_fields module¶

Module contents¶