TaylorNonLinearDiffuser: Model non-linear soil creep after Ganti et al. (2013)#

class TaylorNonLinearDiffuser(*args, **kwds)[source]#

Bases: Component

Hillslope evolution using a Taylor Series expansion of the Andrews- Bucknam formulation of nonlinear hillslope flux derived following following Ganti et al., 2012. The flux is given as:

qs = KS ( 1 + (S/Sc)**2 + (S / Sc)**4 + .. + (S / Sc)**2(n - 1) )

where K is is the diffusivity, S is the slope, Sc is the critical slope, and n is the number of terms.

The default behavior uses two terms to produce a flux law as described by Equation 6 of Ganti et al., (2012).

Examples

>>> import numpy as np
>>> import decimal
>>> from landlab import RasterModelGrid
>>> from landlab.plot.imshow import imshow_grid
>>> mg = RasterModelGrid((3, 3))
>>> z = mg.add_zeros("topographic__elevation", at="node")
>>> initial_slope=1.0
>>> leftmost_elev=1000.
>>> z[:] = leftmost_elev
>>> z[:] += (
...    (initial_slope * np.amax(mg.x_of_node)) -
...    (initial_slope * mg.x_of_node))
>>> mg.set_closed_boundaries_at_grid_edges(False, True, False, True)
>>> cubicflux = TaylorNonLinearDiffuser(mg, slope_crit=0.1)
>>> cubicflux.run_one_step(1.)
>>> np.allclose(
...     mg.at_node['topographic__elevation'],
...     np.array([ 1002.,  1001.,  1000.,  1002.,  1001.,  1000.,  1002.,  1001.,
...     1000.]))
True

The TaylorNonLinearDiffuser makes and moves soil at a rate proportional to slope, this means that there is a characteristic time scale for soil transport and an associated stability criteria for the timestep. The maximum characteristic time scale, Demax, is given as a function of the hillslope diffustivity, D, the maximum slope, Smax, and the critical slope Sc.

Demax = D ( 1 + ( Smax / Sc )**2 ( Smax / Sc )**4 + .. + ( Smax / Sc )**( 2 * ( n - 1 )) )

The maximum stable time step is given by

dtmax = courant_factor * dx * dx / Demax

Where the courant factor is a user defined scale (default is 0.2)

The TaylorNonLinearDiffuser has a boolean flag that permits a user to be warned if timesteps are too large for the slopes in the model grid (if_unstable = ‘warn’) and a boolean flag that turns on dynamic timesteppping (dynamic_dt = False).

>>> cubicflux = TaylorNonLinearDiffuser(mg, slope_crit=0.1, if_unstable='warn')
>>> cubicflux.run_one_step(2.)
Topographic slopes are high enough such that the Courant condition is
exceeded AND you have not selected dynamic timestepping with
dynamic_dt=True. This may lead to infinite and/or nan values for slope,
elevation, and soil depth. Consider using a smaller time step or dynamic
timestepping. The Courant condition recommends a timestep of  0.2 or
smaller.

Alternatively you can specify if_unstable=’raise’, and a Runtime Error will be raised if this condition is not met.

Next, lets do an example with dynamic timestepping.

>>> mg = RasterModelGrid((5, 5))
>>> z = mg.add_zeros("topographic__elevation", at="node")

We’ll use a steep slope.

>>> z += mg.node_x.copy()**2
>>> cubicflux = TaylorNonLinearDiffuser(
...     mg,
...     if_unstable='warn',
...     dynamic_dt=False)

Lets try to move the soil with a large timestep. Without dynamic time steps, this gives a warning that we’ve exceeded the dynamic timestep size and should use a smaller timestep. We could either use the smaller timestep, or specify that we want to use a dynamic timestep.

>>> cubicflux.run_one_step(10.)
Topographic slopes are high enough such that the Courant condition is
exceeded AND you have not selected dynamic timestepping with
dynamic_dt=True. This may lead to infinite and/or nan values for slope,
elevation, and soil depth. Consider using a smaller time step or dynamic
timestepping. The Courant condition recommends a timestep of
0.004 or smaller.

Now, we’ll re-build the grid and do the same example with dynamic timesteps.

>>> mg = RasterModelGrid((5, 5))
>>> z = mg.add_zeros("topographic__elevation", at="node")
>>> z += mg.node_x.copy()**2
>>> cubicflux = TaylorNonLinearDiffuser(
...     mg,
...     if_unstable='warn',
...     dynamic_dt=True)
>>> cubicflux.run_one_step(10.)
>>> np.any(np.isnan(z))
False

References

Required Software Citation(s) Specific to this Component

Barnhart, K., Glade, R., Shobe, C., Tucker, G. (2019). Terrainbento 1.0: a Python package for multi-model analysis in long-term drainage basin evolution. Geoscientific Model Development 12(4), 1267–1297. https://dx.doi.org/10.5194/gmd-12-1267-2019

Additional References

Ganti, V., Passalacqua, P., Foufoula-Georgiou, E. (2012). A sub-grid scale closure for nonlinear hillslope sediment transport models Journal of Geophysical Research: Earth Surface 117(F2). https://dx.doi.org/10.1029/2011jf002181

Initialize the TaylorNonLinearDiffuser.

Parameters
  • grid (ModelGrid) – Landlab ModelGrid object

  • linear_diffusivity (float, optional) – Hillslope diffusivity, m**2/yr Default = 1.0

  • slope_crit (float, optional) – Critical slope Default = 1.0

  • nterms (int, optional. default = 2) – number of terms in the Taylor expansion. Two terms (Default) gives the behavior described in Ganti et al. (2012).

  • dynamic_dt (boolean (optional, default is False)) – Keyword argument to turn on or off dynamic time-stepping.

  • if_unstable (string (optional, default is "pass")) – Keyword argument to determine how potential instability due to slopes that are too high is handled. Options are “pass”, “warn”, and “raise”.

  • courant_factor (float (optional, default = 0.2)) – Factor to identify stable time-step duration when using dynamic timestepping.

__init__(grid, linear_diffusivity=1.0, slope_crit=1.0, nterms=2, dynamic_dt=False, if_unstable='pass', courant_factor=0.2)[source]#

Initialize the TaylorNonLinearDiffuser.

Parameters
  • grid (ModelGrid) – Landlab ModelGrid object

  • linear_diffusivity (float, optional) – Hillslope diffusivity, m**2/yr Default = 1.0

  • slope_crit (float, optional) – Critical slope Default = 1.0

  • nterms (int, optional. default = 2) – number of terms in the Taylor expansion. Two terms (Default) gives the behavior described in Ganti et al. (2012).

  • dynamic_dt (boolean (optional, default is False)) – Keyword argument to turn on or off dynamic time-stepping.

  • if_unstable (string (optional, default is "pass")) – Keyword argument to determine how potential instability due to slopes that are too high is handled. Options are “pass”, “warn”, and “raise”.

  • courant_factor (float (optional, default = 0.2)) – Factor to identify stable time-step duration when using dynamic timestepping.

run_one_step(dt)[source]#

Advance cubic soil flux component by one time step of size dt.

Parameters

dt (float (time)) – The imposed timestep.

soilflux(dt)[source]#

Calculate soil flux for a time period ‘dt’.

Parameters

dt (float (time)) – The imposed timestep.