class StochasticErosionModel

Stochastic Erosion Model

Base class for common functions of terrainbento stochastic erosion models.

class StochasticErosionModel(clock, grid, random_seed=0, record_rain=False, opt_stochastic_duration=False, mean_storm_duration=1, mean_interstorm_duration=1, mean_storm_depth=1, rainfall__shape_factor=1, number_of_sub_time_steps=1, rainfall_intermittency_factor=1, rainfall__mean_rate=1, storm_sequence_filename='storm_sequence.txt', frequency_filename='exceedance_summary.txt', **kwargs)

Bases: terrainbento.base_class.erosion_model.ErosionModel

Base class for stochastic-precipitation terrainbento models.

A StochasticErosionModel inherits from ErosionModel and provides functionality needed by all stochastic-precipitation models.

This is a base class that handles processes related to the generation of preciptiation events.

Two primary options are avaliable for the stochastic erosion models. When opt_stochastic_duration=True the model will use the PrecipitationDistribution Landlab component to generate a random storm duration, interstorm duration, and precipitation intensity or storm depth from an exponential distribution. When this option is selected, the following parameters are used:

• mean_storm_duration

• mean_interstorm_duration

• mean_storm_depth

When opt_stochastic_duration==False the model will have uniform timesteps but generate rainfall from a stretched exponential distribution. The duration indicated by the parameter step will first be split into a series of sub-timesteps based on the parameter number_of_sub_time_steps, and then each of these sub-timesteps will experience a duration of rain and no-rain based on the value of rainfall_intermittency_factor. The duration of rain and no-rain will not change, but the intensity of rain will vary based on a stretched exponential distribution described by the shape factor rainfall__shape_factor and with a scale factor calculated so that the mean of the distribution has the value given by rainfall__mean_rate.

The following parameters are used:

• rainfall__shape_factor

• number_of_sub_time_steps

• rainfall_intermittency_factor

• rainfall__mean_rate

The hydrology uses calculation of drainage area using the user-specified routing method. It then performs one of two options, depending on the user’s choice of opt_stochastic_duration (True or False).

If the user requests stochastic duration, the model iterates through a sequence of storm and interstorm periods. Storm depth is drawn at random from a gamma distribution, and storm duration from an exponential distribution; storm intensity is then depth divided by duration. This sequencing is implemented by overriding the run_for method.

If the user does not request stochastic duration (indicated by setting opt_stochastic_duration to False), then the default (erosion_model base class) run_for method is used. Whenever run_one_step is called, storm intensity is generated at random from an exponential distribution with mean given by the parameter rainfall__mean_rate. The stream power component is run for only a fraction of the time step duration step, as specified by the parameter rainfall_intermittency_factor. For example, if step is 10 years and the intermittency factor is 0.25, then the stream power component is run for only 2.5 years.

In either case, given a storm precipitation intensity \(P\), the runoff production rate \(R\) [L/T] is calculated using:

\[R = P - I (1 - \exp ( -P / I ))\]

where \(I\) is the soil infiltration capacity. At the sub-grid scale, soil infiltration capacity is assumed to have an exponential distribution of which \(I\) is the mean. Hence, there are always some spots within any given grid cell that will generate runoff. This approach yields a smooth transition from near-zero runoff (when \(I>>P\)) to \(R \approx P\) (when \(P>>I\)), without a “hard threshold.”

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

• topographic__elevation

__init__(clock, grid, random_seed=0, record_rain=False, opt_stochastic_duration=False, mean_storm_duration=1, mean_interstorm_duration=1, mean_storm_depth=1, rainfall__shape_factor=1, number_of_sub_time_steps=1, rainfall_intermittency_factor=1, rainfall__mean_rate=1, storm_sequence_filename='storm_sequence.txt', frequency_filename='exceedance_summary.txt', **kwargs)

Parameters

• clock (terrainbento Clock instance) –

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

• int, optional (random_seed,) – Random seed. Default is 0.

• opt_stochastic_duration (bool, optional) – Flag indicating if timestep is stochastic or constant. Default is False.

• mean_storm_duration (float, optional) – Average duration of a precipitation event. Default is 1.

• mean_interstorm_duration (float, optional) – Average duration between precipitation events. Default is 1.

• mean_storm_depth (float, optional) – Average depth of precipitation events. Default is 1.

• number_of_sub_time_steps (int, optional) – Number of sub-timesteps. Default is 1.

• rainfall_intermittency_factor (float, optional) – Value between zero and one that indicates the proportion of time rain occurs. A value of 0 means it never rains and a value of 1 means that rain never ceases. Default is 1.

• rainfall__mean_rate (float, optional) – Mean of the precipitation distribution. Default is 1.

• rainfall__shape_factor (float, optional) – Shape factor of the precipitation distribution. Default is 1.

• record_rain (boolean) – Flag to indicate if a sequence of storms should be saved. Default is False.

• storm_sequence_filename (str) – Storm sequence filename. Default is “storm_sequence.txt”

• frequency_filename (str) – Filename for precipitation exceedance frequency summary. Default value is “exceedance_summary.txt”

• **kwargs – Keyword arguments to pass to ErosionModel

Returns

StochasticErosionModel

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.

calc_runoff_and_discharge()

Calculate runoff rate and discharge; return runoff.

finalize()

Finalize stochastic erosion models.

The finalization step of stochastic erosion models in terrainbento results in writing out the storm sequence file and the precipitation exceedence statistics summary if record_rain was set to True.

handle_water_erosion(step)

Handle water erosion for stochastic models.

If we are running stochastic duration, then self.rain_rate will have been calculated already. It might be zero, in which case we are between storms, so we don’t do water erosion.

If we’re NOT doing stochastic duration, then we’ll run water erosion for one or more sub-time steps, each with its own randomly drawn precipitation intensity.

This routine assumes that a model-specific method:

calc_runoff_and_discharge()

will have been defined. Additionally a model eroder must also have been defined.

For example, BasicStVs calculated runoff and discharge in a different way than the other models.

If the model has a function update_threshold_field, this function will test for it and run it. This is presently done in BasicDdSt.

Parameters

step (float) – Model run timestep.

instantiate_rain_generator()

Instantiate component used to generate storm sequence.

record_rain_event(event_start_time, event_duration, rainfall_rate, runoff_rate)

Record rain events.

Create a record of event start time, event duration, rainfall rate, and runoff rate.

Parameters

• event_start_time (float) –

• event_duration (float) –

• rainfall_rate (float) –

• runoff_rate (float) –

reset_random_seed()

Reset the random number generation sequence.

run_for_stochastic(step, runtime)

Run_for with stochastic duration.

Run model without interruption for a specified time period, using random storm/interstorm sequence.

run_for_stochastic runs the model for the duration runtime with model time steps given by the PrecipitationDistribution component. Model run steps will not exceed the duration given by step.

Parameters

• step (float) – Model run timestep,

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

write_exceedance_frequency_file(filename='exceedance_summary.txt')

Write summary of rainfall exceedance statistics to file.

Parameters

filename (str) – Default value is “exceedance_summary.txt”

write_storm_sequence_to_file(filename='storm_sequence.txt')

Write event duration and intensity to a formatted text file.

Parameters

filename (str) – Default value is “storm_sequence.txt”

main()

Executes model.