class PrecipChanger

Precipitation Changer

PrecipChanger changes precipitation frequency and intensity over time.

This terrainbento boundary-condition 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:

\[Pr(P>p) = \exp \left[-\left( p \lambda \right)^c\right]\]

where \(c\) is the shape factor and \(\lambda\) is the scale factor. The corresponding probability density function is a Weibull distribution. The mean wet-day precipitation depth \(p_d\) is related to the scale factor by

\[p_d = \lambda \Gamma (1 + 1/c)\]

where \(\Gamma\) is the gamma function.

The drainage area-based basic erosion law considered here is:

\[E = KA^{m}S^{n}\]

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:

\[E_i = K_q Q^{m}S^n.\]

This formulation represents the erosion rate during a particular daily event, \(E_i\) with daily-average discharge \(Q_q\), as opposed to the long-term average rate of erosion, \(E\). It introduces a new term \(K_q\), the daily-averaged erosion coefficent.

We next assume that discharge is the product of runoff rate, \(r\), and drainage area:

\[Q = r A.\]

Combining these we can write

\[E_i = K_q r^{m} Q^{m} S^{m}.\]

This equation establishes the dependence of short-term erosion rate on catchment-average 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\),

\[r = p - I_c.\]

An advantage of this simple approach is that \(I_c\) can be measured directly or inferred from stream-flow records.

To relate short-term (“instantaneous”) erosion rate to the long-term 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 wet-day fraction \(F\). Thus, the long-term erosion rate by water can be expressed as:

\[E = F \int_{I_c}^\infty K_q (p-I_c)^{m}Q^{m} S^{n} f(p) dp,\]

where \(f(p)\) is the probability density function (PDF) of daily precipitation intensity. By equating the above definition of long-term erosion math:E with the simpler definition \(E = K Q^{m}S^{n}\), we can solve for the effective erosion coefficient, \(K\):

\[K = F K_q \int_{I_c}^\infty (p-I_c)^{m} f(p) dp.\]

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:

\[\frac{K}{K_0} = \frac{F\int_{I_c}^\infty (p-I_c)^{m} f(p) dp} {F_0\int_{I_c}^\infty (p-I_c)^{m} f_0(p) dp}\]

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:

\[f(p) = \frac{c} {\lambda}\left( \frac{p}{\lambda} \right)^{(c-1)} e^{-(p \lambda)^c}.\]

The above definition can be substituted in the integrals in the equation for \(\frac{K}{K_0}\). We are not aware of a closed-form 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.

\[\Psi = \int_{I_c}^\infty (p - I_{c})^m f(p) dp\]

Finally we define the erodibility adjustment factor \(F_{w}\):

\[K = F_{w} K_{0} = \frac{F \Psi}{F_0 \Psi_0} K_{0}\]

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 time-varying 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, and infiltration_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 event-scale 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

float

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.