class ErosionModel

Erosion Model

Base class for common functions of all terrainbento erosion models.

class ErosionModel(clock, grid, precipitator=None, runoff_generator=None, flow_director='FlowDirectorSteepest', depression_finder=None, flow_accumulator_kwargs=None, boundary_handlers=None, output_writers=None, output_default_netcdf=True, output_interval=None, save_first_timestep=True, save_last_timestep=True, output_prefix='terrainbento-output', output_dir='./output', fields=None)

Bases: object

Base class providing common functionality for terrainbento models.

An ErosionModel is the skeleton for the models of terrain evolution in terrainbento.

This is a base class that does not implement any processes, but rather simply handles I/O and setup. Derived classes are meant to include Landlab components to model actual erosion processes.

It is expected that a derived model will define an __init__ and a run_one_step method. If desired, the derived model can overwrite the existing run_for, run, and finalize methods.

The following at-node fields must be specified in the grid:

• topographic__elevation

__init__(clock, grid, precipitator=None, runoff_generator=None, flow_director='FlowDirectorSteepest', depression_finder=None, flow_accumulator_kwargs=None, boundary_handlers=None, output_writers=None, output_default_netcdf=True, output_interval=None, save_first_timestep=True, save_last_timestep=True, output_prefix='terrainbento-output', output_dir='./output', fields=None)

Parameters

• clock (terrainbento Clock instance) –

• grid (landlab model grid instance) – The grid must have all required fields.

• precipitator (terrainbento precipitator, optional) – An instantiated version of a valid precipitator. See the precipitator module for valid options. The precipitator creates rain. Default value is the UniformPrecipitator with a rainfall flux of 1.0.

• runoff_generator (terrainbento runoff_generator, optional) –

  An instantiated version of a valid runoff generator. See the runoff generator module for valid options. The runoff generator converts rain into runoff. This runoff is then accumulated into surface water discharge (\(Q\)) and used by channel erosion components. Default value is SimpleRunoff in which all rainfall turns into runoff. For the drainage area version of the stream power law use the default precipitator and runoff_generator.

  If the default values of both the precipitator and runoff_generator are used, then \(Q\) will be equal to drainage area.

• flow_director (str, optional) – String name of a Landlab FlowDirector. Default is “FlowDirectorSteepest”.

• depression_finder (str, optional) – String name of a Landlab depression finder. Default is None.

• flow_accumulator_kwargs (dictionary, optional) – Dictionary of any additional keyword arguments to pass to the Landlab FlowAccumulator. Default is an empty dictionary.

• boundary_handlers (dictionary, optional) – Dictionary with name: instance key-value pairs. Each entry must be a valid instance of a terrainbento boundary handler. See the boundary handlers module for valid options.

• output_writers (dictionary of output writers.) –

  Classes or functions used to write incremental output (e.g. make a diagnostic plot). There are two formats for the dictionary entries:

  1. (“Old style”) Items can have a key of “class” or “function” and a value that is a list of uninstantiated output classes or a list of output functions, respectively. All output writers defined this way will use the output_interval argument provided to the ErosionModel constructor.

  2. (“New style”) Items can have a key of any unique string representing the output writer’s name and a value that is a dictionary containing the uninstantiated class and any arguments. The dictionary follows the format:

     {
       'class' : MyWriter,
       'args' : [], # optional
       'kwargs' : {}, # optional
       }
     

     where args and kwargs are passed to the constructor for MyWriter. All new style output writers must be a child class of GenericOutputWriter. The ErosionModel reference is automatically prepended to args.

  The two formats can be present simultaneously. See the Jupyter notebook examples for more details.

• output_default_netcdf (bool, optional) – Indicates whether the erosion model should automatically create a simple netcdf output writer which behaves identical to the built-in netcdf writer from older terrainbento versions. Uses the ‘output_interval’ argument as the output interval. Defaults to True.

• output_interval (float, optional) – The time between output calls for old-style output writers and the default netcdf writer. Default is the Clock’s stop time.

• save_first_timestep (bool, optional) – Indicates whether model output should be saved at time zero (the initial conditions). This affects old and new style output writers. Default is True.

• save_last_timestep (bool, optional) – Indicates that the last output time must be at the clock stop time. This affects old and new style output writers. Defaults to True.

• output_prefix (str, optional) – String prefix for names of all output files. Default is "terrainbento-output".

• output_dir (string, optional) – Directory that output should be saved to. Defaults to an “output” directory in the current directory.

• fields (list, optional) – List of field names to write as netCDF output. Default is to only write out “topographic__elevation”.

Returns

ErosionModel

Return type

object

Examples

This model is a base class and is not designed to be run on its own. We recommend that you look at the terrainbento tutorials for examples of usage.

calculate_cumulative_change()

Calculate cumulative node-by-node changes in elevation.

create_and_move_water(step)

Create and move water.

Run the precipitator, the runoff generator, and the flow accumulator, in that order.

finalize()

Finalize model.

This base-class method does nothing. Derived classes can override it to run any required finalization steps.

finalize__run_one_step(step)

Finalize run_one_step method.

This base-class method increments model time and updates boundary conditions.

classmethod from_dict(params, output_writers=None)

Construct a terrainbento model from an input parameter dictionary.

The input parameter dictionary portion associated with the “grid” keword will be passed directly to the Landlab create_grid. function.

Parameters

• params (dict) – Dictionary of input parameters.

• output_writers (dictionary of output writers.) –

  Classes or functions used to write incremental output (e.g. make a diagnostic plot). There are two formats for the dictionary entries:

  1. Items can have a key of “class” or “function” and a value of a list of simple output classes (uninstantiated) or functions, respectively. All output writers defined this way will use the output_interval provided to the ErosionModel constructor.

  2. Items can have a key with any unique string representing the output writer’s name and a value containing a dict with the uninstantiated class and arguments. The value follows the format:

     {
      'class' : MyWriter,
      'args' : [], # optional
      'kwargs' : {}, # optional
      }
     

     where args and kwargs are passed to the constructor for MyWriter. MyWriter must be a child class of GenericOutputWriter.

     The two formats can be present simultaneously. See the Jupyter notebook examples for more details.

Examples

>>> params = {
...     "grid": {
...         "RasterModelGrid": [
...             (4, 5),
...             {
...                 "fields": {
...                     "node": {
...                         "topographic__elevation": {
...                             "constant": [{"value": 0.0}]
...                         }
...                     }
...                 }
...             },
...         ]
...     },
...     "clock": {"step": 1, "stop": 200},
... }
>>> model = ErosionModel.from_dict(params)
>>> model.clock.step
1.0
>>> model.clock.stop
200.0
>>> model.grid.shape
(4, 5)

classmethod from_file(file_like)

Construct a terrainbento model from a file.

Parameters

file_like (file_like or str) – Contents of a parameter file, a file-like object, or the path to a parameter file.

Examples

>>> from io import StringIO
>>> filelike = StringIO('''
... grid:
...   RasterModelGrid:
...     - [4, 5]
...     - fields:
...         node:
...           topographic__elevation:
...             constant:
...               - value: 0.0
... clock:
...   step: 1
...   stop: 200
... ''')
>>> model = ErosionModel.from_file(filelike)
>>> model.clock.step
1.0
>>> model.clock.stop
200.0
>>> model.grid.shape
(4, 5)

get_output(extension=None, writer=None)

Get a list of filepaths for files written by new style writers during a model run. Does not work for old style writers which have no way to report what they have written. Can specify types of files and/or writers.

Parameters

• extension (string or list of strings, optional) – Specify what type(s) of files should be returned. Defaults to None which returns all file types. Don’t include a leading period.

• writer (GenericOutputWriter instance or list of instances or string or list of strings or None) – Specify if the files should come from certain output writers either by the writer’s handle or by the writer’s name. Defaults to returning files from all writers.

Returns

filepaths – A list of filepath strings that match the desired extensions and writers.

Return type

list of strings

get_output_writer(name)

Get the references for object writer(s) from the writer’s name.

Parameters

name (string) – The name of the output writer to look for. Can match multiple writers.

Returns

matches – The list of any GenericOutputWriter whose name contains the argument name string. Will return an empty list if there are no matches.

Return type

list of GenericOutputWriter objects

property model_time

Return current time of model integration in model time units.

property next_output_time

Return the next output time in model time units. If there are no more active output writers, return np.inf instead.

property output_prefix

Model prefix for output filenames.

remove_output(extension=None, writer=None)

Remove files written by new style writers during a model run. Does not work for old style writers which have no way to report what they have written. Can specify types of files and/or writers.

To do: allow ‘writer’ to be a string for the name of the writer?

Parameters

• extension (string or list of strings, optional) – Specify what type(s) of files should be deleted. Defaults to None which deletes all file types. Don’t include a leading period.

• writer (GenericOutputWriter instance or list of instances or string or list of strings or None) – Specify if the files should come from certain output writers either by the writer’s handle or by the writer’s name. Defaults to deleting files from all writers.

remove_output_netcdfs()

Remove netcdf output files written during a model run. Only works for new style writers including the default netcdf writer.

run()

Run the model until complete.

The model will run for the duration indicated by the input file or dictionary parameter "stop", at a time step specified by the parameter "step", and create ouput at intervals specified by the individual output writers.

run_for(step, runtime)

Run model without interruption for a specified time period.

run_for runs the model for the duration runtime with model time steps of step.

Parameters

• step (float) – Model run timestep.

• runtime (float) – Total duration for which to run model.

save_to_xarray_dataset(filename='terrainbento.nc', time_unit='time units', reference_time='model start', space_unit='space units')

Save model output to xarray dataset.

If you would like to have CF compliant NetCDF make sure that your time and space units and reference times will work with standard decoding.

The default time unit and reference time will give the time dimention a value of “time units since model start”. The default space unit will give a value of “space unit”.

Parameters

• filename (str, optional) – The file path where the file should be saved. The default value is “terrainbento.nc”.

• time_unit (str, optional) – Name of time unit. Default is “time units”.

• time (reference) – Reference tim. Default is “model start”.

• space_unit (str, optional) – Name of space unit. Default is “space unit”.

to_xarray_dataset(time_unit='time units', reference_time='model start', space_unit='space units')

Convert model output to an xarray dataset.

If you would like to have CF compliant NetCDF make sure that your time and space units and reference times will work with standard decoding.

The default time unit and reference time will give the time dimention a value of “time units since model start”. The default space unit will give a value of “space unit”.

Parameters

• time_unit (str, optional) – Name of time unit. Default is “time units”.

• time (reference) – Reference tim. Default is “model start”.

• space_unit (str, optional) – Name of space unit. Default is “space unit”.

update_boundary_conditions(step)

Run all boundary handlers forward by step.

Parameters

step (float) – Timestep in unit of model time.

write_output()

Run output writers if it is the correct model time.

main()

Executes model.