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.0
>>> 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.0)
>>> np.allclose(
...     mg.at_node["topographic__elevation"],
...     np.array(
...         [1002.0, 1001.0, 1000.0, 1002.0, 1001.0, 1000.0, 1002.0, 1001.0, 1000.0]
...     )
... )
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 RuntimeError 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.0)
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).

  • slope_crit (float, optional) – Critical slope.

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

  • dynamic_dt (bool, optional) – Turn dynamic time-stepping on or off.

  • if_unstable ({'pass', 'warn', 'raise'}, optional) – Specify how potential instability due to slopes that are too high is handled.

  • courant_factor (float, optional) – 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).

  • slope_crit (float, optional) – Critical slope.

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

  • dynamic_dt (bool, optional) – Turn dynamic time-stepping on or off.

  • if_unstable ({'pass', 'warn', 'raise'}, optional) – Specify how potential instability due to slopes that are too high is handled.

  • courant_factor (float, optional) – 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) – The imposed timestep.

soilflux(dt)[source]#

Calculate soil flux for a time period, dt.

Parameters:

dt (float) – The imposed timestep.