
class
PrecipChanger
¶
Precipitation Changer¶
PrecipChanger changes precipitation frequency and intensity over time.
This terrainbento boundarycondition handler was designed to change the precipitation frequency and intensity over time in order to modify the water erodibility coefficient.
In order to accomplish this, we need a theory by which to relate changes in the precipitation to changes in erodibility.
We start by describing the assumed precipitation model.
The precipitation model considers the fraction of wet days, \(F\), and the frequency distribution of precipitation depth on wet days. Precipitation on a given day is given as \(p\). For daily average precipitation intensity, we assume that the complementary cumulative distribution function is a stretched exponential:
where \(c\) is the shape factor and \(\lambda\) is the scale factor. The corresponding probability density function is a Weibull distribution. The mean wetday precipitation depth \(p_d\) is related to the scale factor by
where \(\Gamma\) is the gamma function.
The drainage areabased basic erosion law considered here is:
where \(E\) is channel erosion rate, \(A\) is contributing drainage area, and \(S\) is local channel gradient. \(m\) and \(n\) are the slope and area exponents
With \(m=1\), \(K\) has dimensions of inverse length.
Here, we present the approach used to relate changes in \(K\) to changes in \(p_d\)
Deriving a relation between \(K\), \(p_d\), and \(F\) requires defining an underlying hydrology model. We start by noting that drainage area serves as a surrogate for discharge, \(Q\). We can therefore write an instantaneous version of the erosion law as:
This formulation represents the erosion rate during a particular daily event, \(E_i\) with dailyaverage discharge \(Q_q\), as opposed to the longterm average rate of erosion, \(E\). It introduces a new term \(K_q\), the dailyaveraged erosion coefficent.
We next assume that discharge is the product of runoff rate, \(r\), and drainage area:
Combining these we can write
This equation establishes the dependence of shortterm erosion rate on catchmentaverage runoff rate, \(r\).
Next we need to relate runoff rate to precipitation rate. A common method is to acknowledge that there exists a soil infiltration capacity, \(I_c\), such that when \(p<I_c\), no runoff occurs, and when \(p>I_c\),
An advantage of this simple approach is that \(I_c\) can be measured directly or inferred from streamflow records.
To relate shortterm (“instantaneous”) erosion rate to the longterm average, one can first integrate the erosion rate over the full probability distribution of daily precipitation intensity. This operation yields the average erosion rate produced on wet days. To convert this into an average that includes dry days, we simply multiply the integral by the wetday fraction \(F\). Thus, the longterm erosion rate by water can be expressed as:
where \(f(p)\) is the probability density function (PDF) of daily precipitation intensity. By equating the above definition of longterm erosion math:E with the simpler definition \(E = K Q^{m}S^{n}\), we can solve for the effective erosion coefficient, \(K\):
In this case, what is of interest is the change in \(K\) given some change in precipitation frequency distribution \(f(p)\). Suppose we have an original value of the effective erodibility coefficient, \(K_0\), and an original precipitation distribution, \(f_0(p)\). Given a future change to a new precipitation distribution \(f(p)\), we wish to know what is the ratio of the new effective erodibility coefficient \(K\) to its original value. Using the definition of \(K\) above, the ratio of old to new coefficient is:
Here \(F_0\) is the starting intermittency factor.
Thus, if we know the original and new precipitation distributions and intermittency factors, we can determine the resulting change in \(K\).
We assume that the daily precipitation intensity PDF is given by the Weibull distribution such that \(f(p)\) has the form:
The above definition can be substituted in the integrals in the equation for \(\frac{K}{K_0}\). We are not aware of a closedform solution to the resulting integrals. Therefore, we apply a numerical integration to convert the input values of \(F\), \(c\), and \(p_d\) into a corresponding new value of \(K\).
For computational convenience, we define and calculate \(\Psi\) which represents the portion of the erosion coefficient that depends on precipitation.
\(\Psi\) is defined as the integral from \(I_c\) to infinity of the rainfall in excess of infiltration.
Finally we define the erodibility adjustment factor \(F_{w}\):
Here \(F_0\) and \(\Psi_0\) are the starting fraction of wet days and starting value for \(\Psi\).
PrecipChanger presently supports changes in \(F\) and \(p_d\) but not \(c\).

class
PrecipChanger
(grid, daily_rainfall__intermittency_factor=None, daily_rainfall__intermittency_factor_time_rate_of_change=None, rainfall__mean_rate=None, rainfall__mean_rate_time_rate_of_change=None, rainfall__shape_factor=None, infiltration_capacity=None, m_sp=0.5, precipchanger_start_time=0, precipchanger_stop_time=None, **kwargs)[source]¶ Bases:
object
Handle time varying precipitation.
The PrecipChanger handles timevarying precipitation by changing the proportion of time rain occurs (
daily_rainfall_rainfall_intermittency_factor
) and the mean of the daily rainfall Weibull distribution (rainfall__mean_rate
).Note that PrecipChanger increments time at the end of the run_one_step method.

__init__
(grid, daily_rainfall__intermittency_factor=None, daily_rainfall__intermittency_factor_time_rate_of_change=None, rainfall__mean_rate=None, rainfall__mean_rate_time_rate_of_change=None, rainfall__shape_factor=None, infiltration_capacity=None, m_sp=0.5, precipchanger_start_time=0, precipchanger_stop_time=None, **kwargs)[source]¶  Parameters
grid (landlab model grid) –
daily_rainfall_intermittency_factor (float) – Starting value of the daily rainfall intermittency factor \(F\). This value is a proportion and ranges from 0 (no rain ever) to 1 (rains every day).
daily_rainfall_intermittency_factor__time_rate_of_change (float) – Time rate of change of the daily rainfall intermittency factor \(F\). Units are implied by the
time_unit
argument. Note that this factor must always be between 0 and 1.rainfall__mean_rate (float) – Starting value of the mean daily rainfall intensity \(p_d\). Units are implied by the
time_unit
argument.rainfall__mean_rate__time_rate_of_change (float) – Time rate of change of the mean daily rainfall intensity \(p_d\). Units are implied by the
time_unit
argument.rainfall__shape_factor (float) – Weibull distribution shape factor \(c\).
infiltration_capacity (float) – Infiltration capacity. Time units are implied by the
time_unit
argument.m_sp (float, optional) – Drainage area exponent in erosion rule, \(m\). Default value is 0.5.
precipchanger_start_time (float, optional) – Model time at which changing the precipitation should start. Default is at the onset of the model run.
precipchanger_stop_time (float, optional) – Model time at which changing the precipitation statistics should end. Default is no end time.
Notes
The time units of
rainfall__mean_rate
,rainfall__mean_rate_time_rate_of_change
, andinfiltration_capacity
are all assumed to be the same.The value passed by
time_unit
is assumed to be consistent with the time units of step.The length units are assumed to be consistent with the model grid definition.
Examples
Start by creating a landlab model grid.
>>> from landlab import RasterModelGrid >>> mg = RasterModelGrid((5, 5))
Now import the PrecipChanger and instantiate.
>>> from terrainbento.boundary_handlers import PrecipChanger >>> bh = PrecipChanger(mg, ... daily_rainfall__intermittency_factor = 0.3, ... daily_rainfall__intermittency_factor_time_rate_of_change = 0.01, ... rainfall__mean_rate = 3.0, ... rainfall__mean_rate_time_rate_of_change = 0.2, ... rainfall__shape_factor = 0.65, ... infiltration_capacity = 0)
We can get the current precipitation parameters
>>> I, pd = bh.get_current_precip_params() >>> print(I) 0.3
Note that
rainfall__mean_rate
is provided in units of length per year.>>> print(pd) 3.0
Since we did not specify a start time or stop time the PrecipChanger will immediate start to modify the values of precipitation parameters.
>>> bh.run_one_step(10.0) >>> I, pd = bh.get_current_precip_params() >>> print(I) 0.4 >>> print(pd) 5.0
If we are using an erosion model that requires the raw values of the precipitation parameters, we can use them. If instead we are using a model that does not explicitly treat eventscale precipitation, we can use the bulk erodibility adjustment factor \(F_w\).
>>> fw = bh.get_erodibility_adjustment_factor() >>> print(round(fw, 3)) 1.721

calculate_starting_psi
()[source]¶ Calculate and store for later the factor \(\Psi_0\).
\(\Psi\) represents the portion of the erosion coefficient that depends on precipitation intensity. \(\Psi_0\) is the starting value of \(\Psi\).
\(\Psi_0\) is defined as the integral from \(I_c\) to infinity of the rainfall in excess of infiltration.
\[\Psi_0 = \int_{I_c}^\infty (p  I_{c})^m f_0(p) dp\]where \(p\) is precipitation intensity, \(I_c\) is infiltration capacity, \(m\) is the discharge/area exponent (e.g., 1/2), and \(f_0(p)\) is the Weibull distribution representing the probability distribution of daily precipitation intensity at model run onset.

get_current_precip_params
()[source]¶ Return current values precipitation parameters.
 Returns
daily_rainfall_rainfall_intermittency_factor (float)
rainfall__mean_rate (float)

get_erodibility_adjustment_factor
()[source]¶ Calculates the erodibility adjustment factor at the current time.
Calculates and returns the factor \(F_{w}\) by which an erodibility by water should be adjusted.
\[K = F_{w} K_{0} = \frac{F \Psi}{F_0 \Psi_0} K_{0}\] Returns
erodibility_adjustment_factor
 Return type

run_one_step
(step)[source]¶ Run PrecipChanger forward and update model time.
The run_one_step method provides a consistent interface to update the terrainbento boundary condition handlers.
In the run_one_step routine, the PrecipChanger will update its internal record of model time.
 Parameters
step (float) – Duration of model time to advance forward.
