landlab.utils.decorators module

General decorators for the landlab library.

General Landlab decorators

use_file_name_or_kwds(func)	Decorate a method so that it takes a file name or keywords.
use_field_name_or_array(at_element)	Decorate a function so that it accepts a field name or array.
make_return_array_immutable(func)	Decorate a function so that its return array is read-only.
deprecated(use, version)	Mark a function as deprecated.

deprecated(use, version)

Mark a function as deprecated.

Parameters:

use : str

Name of replacement function to use.

version : str

Version number when function was marked as deprecated.

Returns:

func

A wrapped function that issues a deprecation warning.

make_return_array_immutable(func)

Decorate a function so that its return array is read-only.

Parameters:

func : function

A function that returns a numpy array.

Returns:

func

A wrapped function that returns a read-only view of an array.

read_only_array(func)

Decorate a function so that its return array is read-only.

Parameters:

func : function

A function that returns a numpy array.

Returns:

func

A wrapped function that returns a read-only numpy array.

class store_result_in_grid(name=None)

Bases: object

class use_field_name_or_array(at_element)

Bases: object

Decorate a function so that it accepts a field name or array.

Parameters:

func : function

A function that accepts a grid and array as arguments.

at_element : str

The element type that the field is defined on (‘node’, ‘cell’, etc.)

Returns:

func

A wrapped function that accepts a grid and either a field name or a numpy array.

Examples

>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid((4, 5), spacing=(1, 2))

>>> def my_func(grid, vals):
...     return grid.area_of_cell * vals
>>> my_func(grid, np.arange(grid.number_of_cells))
array([  0.,   2.,   4.,   6.,   8.,  10.])

Decorate the function so that the second argument can be array-like or the name of a field contained withing the grid. The decorator takes a single argument that is the name (as a str) of the grid element that the values are defined on (“node”, “cell”, etc.).

>>> from landlab.utils.decorators import use_field_name_or_array
>>> @use_field_name_or_array('cell')
... def my_func(grid, vals):
...     return grid.area_of_cell * vals

The array of values now can be list or anything that can be converted to a numpy array.

>>> my_func(grid, [0, 1, 2, 3, 4, 5])
array([  0.,   2.,   4.,   6.,   8.,  10.])

The array of values doesn’t have to be flat.

>>> vals = np.array([[0, 1, 2], [3, 4, 5]])
>>> my_func(grid, vals)
array([  0.,   2.,   4.,   6.,   8.,  10.])

The array of values can be a field name.

>>> _ = grid.add_field('cell', 'elevation', [0, 1, 2, 3, 4, 5])
>>> my_func(grid, 'elevation')
array([  0.,   2.,   4.,   6.,   8.,  10.])

use_file_name_or_kwds(func)

Decorate a method so that it takes a file name or keywords.

Parameters:

func : A function

A method function that accepts a ModelGrid as a first argument.

Returns:

function

A function that takes an optional second argument, a file, from which to read keywords.

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.utils.decorators import use_file_name_or_kwds

>>> class MyClass(object):
...     @use_file_name_or_kwds
...     def __init__(self, grid, kw=0.):
...         self.kw = kw

>>> grid = RasterModelGrid((4, 5))
>>> foo = MyClass(grid)
>>> foo.kw
0.0

>>> foo = MyClass(grid, "kw: 1945")
>>> foo.kw
1945
>>> foo = MyClass(grid, "kw: 1945", kw=1973)
>>> foo.kw
1973

>>> mpd = """
... kw: kw value
... 1e6
... """
>>> foo = MyClass(grid, mpd)
>>> foo.kw
1000000.0