
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)[source]¶ Bases:
terrainbento.base_class.erosion_model.ErosionModel
Base class for stochasticprecipitation terrainbento models.
A StochasticErosionModel inherits from
ErosionModel
and provides functionality needed by all stochasticprecipitation 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 parameterstep
will first be split into a series of subtimesteps based on the parameternumber_of_sub_time_steps
, and then each of these subtimesteps will experience a duration of rain and norain based on the value ofrainfall_intermittency_factor
. The duration of rain and norain will not change, but the intensity of rain will vary based on a stretched exponential distribution described by the shape factorrainfall__shape_factor
and with a scale factor calculated so that the mean of the distribution has the value given byrainfall__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 userspecified 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
toFalse
), 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 parameterrainfall__mean_rate
. The stream power component is run for only a fraction of the time step duration step, as specified by the parameterrainfall_intermittency_factor
. For example, ifstep
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 subgrid 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 nearzero runoff (when \(I>>P\)) to \(R \approx P\) (when \(P>>I\)), without a “hard threshold.”
 The following atnode 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)[source]¶  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 subtimesteps. 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
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.

finalize
()[source]¶ 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 toTrue
.

handle_water_erosion
(step)[source]¶ 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 subtime steps, each with its own randomly drawn precipitation intensity.
This routine assumes that a modelspecific 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.

record_rain_event
(event_start_time, event_duration, rainfall_rate, runoff_rate)[source]¶ Record rain events.
Create a record of event start time, event duration, rainfall rate, and runoff rate.

run_for_stochastic
(step, runtime)[source]¶ 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 bystep
.