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.