class CubicDiffusionModel(_ErosionModel):
"""
A CubicDiffusionModel is a single-component model that uses a finite-
volume solution to the 2D cubic diffusion equation to compute erosion.
"""
def __init__(self, input_file=None, params=None):
"""Initialize the CubicDiffusionModel."""
# Call ErosionModel's init
super(CubicDiffusionModel, self).__init__(input_file=input_file,
params=params)
# Instantiate a LinearDiffuser component
self.diffuser = TaylorNonLinearDiffuser(self.grid, **self.params)
def run_one_step(self, dt):
"""
Advance model for one time-step of duration dt.
"""
self.diffuser.run_one_step(dt)
class BasicChRt(ErosionModel):
"""
A BasicChRt model computes erosion using cubic diffusion, basic stream
power with two rock units, and Q~A.
"""
def __init__(self, input_file=None, params=None,
BaselevelHandlerClass=None):
"""Initialize the BasicChRt model."""
# Call ErosionModel's init
super(BasicChRt, self).__init__(input_file=input_file,
params=params,
BaselevelHandlerClass=BaselevelHandlerClass)
contact_zone__width = (self._length_factor)*self.params['contact_zone__width'] # has units length
self.K_rock_sp = self.get_parameter_from_exponent('K_rock_sp')
self.K_till_sp = self.get_parameter_from_exponent('K_till_sp')
linear_diffusivity = (self._length_factor**2.)*self.get_parameter_from_exponent('linear_diffusivity')
# Set up rock-till
self.setup_rock_and_till(self.params['rock_till_file__name'],
self.K_rock_sp,
self.K_till_sp,
contact_zone__width)
# Instantiate a FlowAccumulator with DepressionFinderAndRouter using D8 method
self.flow_router = FlowAccumulator(self.grid,
flow_director='D8',
depression_finder = DepressionFinderAndRouter)
# Instantiate a FastscapeEroder component
self.eroder = FastscapeEroder(self.grid,
m_sp=self.params['m_sp'],
n_sp=self.params['n_sp'],
K_sp=self.erody)
# Instantiate a LinearDiffuser component
self.diffuser = TaylorNonLinearDiffuser(self.grid,
linear_diffusivity=linear_diffusivity,
slope_crit=self.params['slope_crit'],
nterms=7)
def setup_rock_and_till(self, file_name, rock_erody, till_erody,
contact_width):
"""Set up lithology handling for two layers with different erodibility.
Parameters
----------
file_name : string
Name of arc-ascii format file containing elevation of contact
position at each grid node (or NODATA)
Read elevation of rock-till contact from an esri-ascii format file
containing the basal elevation value at each node, create a field for
erodibility.
Some considerations here:
1. We could represent the contact between two layers either as a
depth below present land surface, or as an altitude. Using a
depth would allow for vertical motion, because for a fixed
surface, the depth remains constant while the altitude changes.
But the depth must be updated every time the surface is eroded
or aggrades. Using an altitude avoids having to update the
contact position every time the surface erodes or aggrades, but
any tectonic motion would need to be applied to the contact
position as well. Here we'll use the altitude approach because
this model was originally written for an application with lots
of erosion expected but no tectonics.
"""
from landlab.io import read_esri_ascii
# Read input data on rock-till contact elevation
read_esri_ascii(file_name, grid=self.grid,
name='rock_till_contact__elevation',
halo=1)
# Get a reference to the rock-till field
self.rock_till_contact = self.grid.at_node['rock_till_contact__elevation']
# Create field for erodibility
if 'substrate__erodibility' in self.grid.at_node:
self.erody = self.grid.at_node['substrate__erodibility']
else:
self.erody = self.grid.add_zeros('node', 'substrate__erodibility')
# Create array for erodibility weighting function
self.erody_wt = np.zeros(self.grid.number_of_nodes)
# Read the erodibility value of rock and till
self.rock_erody = rock_erody
self.till_erody = till_erody
# Read and remember the contact zone characteristic width
self.contact_width = contact_width
def update_erodibility_field(self):
"""Update erodibility at each node based on elevation relative to
contact elevation.
To promote smoothness in the solution, the erodibility at a given point
(x,y) is set as follows:
1. Take the difference between elevation, z(x,y), and contact
elevation, b(x,y): D(x,y) = z(x,y) - b(x,y). This number could
be positive (if land surface is above the contact), negative
(if we're well within the rock), or zero (meaning the rock-till
contact is right at the surface).
2. Define a smoothing function as:
$F(D) = 1 / (1 + exp(-D/D*))$
This sigmoidal function has the property that F(0) = 0.5,
F(D >> D*) = 1, and F(-D << -D*) = 0.
Here, D* describes the characteristic width of the "contact
zone", where the effective erodibility is a mixture of the two.
If the surface is well above this contact zone, then F = 1. If
it's well below the contact zone, then F = 0.
3. Set the erodibility using F:
$K = F K_till + (1-F) K_rock$
So, as F => 1, K => K_till, and as F => 0, K => K_rock. In
between, we have a weighted average.
Translating these symbols into variable names:
z = self.elev
b = self.rock_till_contact
D* = self.contact_width
F = self.erody_wt
K_till = self.till_erody
K_rock = self.rock_erody
"""
# Update the erodibility weighting function (this is "F")
D_over_D_star = ((self.z[self.data_nodes] - self.rock_till_contact[self.data_nodes])
/ self.contact_width)
# truncate D_over_D star to remove potential for overflow in exponent
D_over_D_star[D_over_D_star < -100.0] = -100.0
D_over_D_star[D_over_D_star > 100.0] = 100.0
self.erody_wt[self.data_nodes] = (1.0 / (1.0 + np.exp(-D_over_D_star)))
# (if we're varying K through time, update that first)
if self.opt_var_precip:
erode_factor = self.pc.get_erodibility_adjustment_factor(self.model_time)
self.till_erody = self.K_till_sp * erode_factor
self.rock_erody = self.K_rock_sp * erode_factor
# Calculate the effective erodibilities using weighted averaging
self.erody[:] = (self.erody_wt * self.till_erody
+ (1.0 - self.erody_wt) * self.rock_erody)
def run_one_step(self, dt):
"""
Advance model for one time-step of duration dt.
"""
# Route flow
self.flow_router.run_one_step()
# Get IDs of flooded nodes, if any
flooded = np.where(self.flow_router.depression_finder.flood_status==3)[0]
# Update the erodibility field
self.update_erodibility_field()
# Do some erosion (but not on the flooded nodes)
self.eroder.run_one_step(dt, flooded_nodes=flooded,
K_if_used=self.erody)
# Do some soil creep
self.diffuser.run_one_step(dt,
dynamic_dt=True,
if_unstable='raise',
courant_factor=0.1)
# calculate model time
self.model_time += dt
# Lower outlet
self.update_outlet(dt)
# Check walltime
self.check_walltime()
class BasicCh(_ErosionModel):
"""
A BasicCh computes erosion using cubic diffusion, basic stream
power, and Q~A.
"""
def __init__(self, input_file=None, params=None,
BaselevelHandlerClass=None):
"""Initialize the BasicCh."""
# Call ErosionModel's init
super(BasicCh, self).__init__(input_file=input_file,
params=params,
BaselevelHandlerClass=BaselevelHandlerClass)
# Get Parameters and convert units if necessary:
self.K_sp = self.get_parameter_from_exponent('K_sp')
linear_diffusivity = (self._length_factor**2.)*self.get_parameter_from_exponent('linear_diffusivity') # has units length^2/time
# Instantiate a FlowAccumulator with DepressionFinderAndRouter using D8 method
self.flow_router = FlowAccumulator(self.grid,
flow_director='D8',
depression_finder = DepressionFinderAndRouter)
# Instantiate a FastscapeEroder component
self.eroder = FastscapeEroder(self.grid,
K_sp=self.K_sp,
m_sp=self.params['m_sp'],
n_sp=self.params['n_sp'])
# Instantiate a LinearDiffuser component
self.diffuser = TaylorNonLinearDiffuser(self.grid,
linear_diffusivity=linear_diffusivity,
slope_crit=self.params['slope_crit'],
nterms=11)
def run_one_step(self, dt):
"""
Advance model for one time-step of duration dt.
"""
# Route flow
self.flow_router.run_one_step()
# Get IDs of flooded nodes, if any
flooded = np.where(self.flow_router.depression_finder.flood_status==3)[0]
# Do some erosion (but not on the flooded nodes)
# (if we're varying K through time, update that first)
if self.opt_var_precip:
self.eroder.K = (self.K_sp
* self.pc.get_erodibility_adjustment_factor(self.model_time))
self.eroder.run_one_step(dt, flooded_nodes=flooded)
# Do some soil creep
self.diffuser.run_one_step(dt,
dynamic_dt=True,
if_unstable='raise',
courant_factor=0.1)
# calculate model time
self.model_time += dt
# Lower outlet
self.update_outlet(dt)
# Check walltime
self.check_walltime()
class BasicChRtTh(TwoLithologyErosionModel):
r"""**BasicChRtTh** model program.
This model program combines :py:class:`BasicCh`, :py:class:`BasicTh` and
:py:class:`BasicRt` programs by allowing for two lithologies, an "upper"
layer and a "lower" layer, permitting the use of an smooth erosion
threshold for each lithology, and using non-linear hillslope transport.
Given a spatially varying contact zone elevation, :math:`\eta_C(x,y))`,
model **BasicChRtTh** evolves a topographic surface described by
:math:`\eta` with the following governing equations:
.. math::
\frac{\partial \eta}{\partial t} = -\left[\omega
- \omega_c (1 - e^{-\omega /\omega_c}) \right]
- \nabla q_h
\omega = K(\eta, \eta_C) Q^{m} S^{n}
K(\eta, \eta_C ) = w K_1 + (1 - w) K_2,
\omega_c(\eta, \eta_C ) = w \omega_{c1} + (1 - w) \omega_{c2}
w = \frac{1}{1+\exp \left( -\frac{(\eta -\eta_C )}{W_c}\right)}
q_h = -DS \left[ 1 + \left( \frac{S}{S_c} \right)^2
+ \left( \frac{S}{S_c} \right)^4
+ ... \left( \frac{S}{S_c} \right)^{2(N-1)} \right]
where :math:`Q` is the local stream discharge, :math:`S` is the local
slope, :math:`m` and :math:`n` are the discharge and slope exponent
parameters, :math:`W_c` is the contact-zone width, :math:`K_1` and :
math:`K_2` are the erodabilities of the upper and lower lithologies,
:math:`\omega_{c1}` and :math:`\omega_{c2}` are the erosion thresholds of
the upper and lower lithologies, and :math:`D` is the regolith transport
parameter. :math:`w` is a weight used to calculate the effective
erodibility :math:`K(\eta, \eta_C)` based on the depth to the contact zone
and the width of the contact zone. :math:`N` is the number of terms in the
Taylor Series expansion.
The weight :math:`w` promotes smoothness in the solution of erodibility at
a given point. When the surface elevation is at the contact elevation, the
erodibility is the average of :math:`K_1` and :math:`K_2`; above and below
the contact, the erodibility approaches the value of :math:`K_1` and
:math:`K_2` at a rate related to the contact zone width. Thus, to make a
very sharp transition, use a small value for the contact zone width.
Refer to
`Barnhart et al. (2019) <https://doi.org/10.5194/gmd-12-1267-2019>`_
Table 5 for full list of parameter symbols, names, and dimensions.
The following at-node fields must be specified in the grid:
- ``topographic__elevation``
- ``lithology_contact__elevation``
"""
_required_fields = [
"topographic__elevation",
"lithology_contact__elevation",
]
def __init__(
self,
clock,
grid,
water_erosion_rule_upper__threshold=1.0,
water_erosion_rule_lower__threshold=1.0,
critical_slope=0.3,
number_of_taylor_terms=7,
**kwargs
):
"""
Parameters
----------
clock : terrainbento Clock instance
grid : landlab model grid instance
The grid must have all required fields.
m_sp : float, optional
Drainage area exponent (:math:`m`). Default is 0.5.
n_sp : float, optional
Slope exponent (:math:`n`). Default is 1.0.
water_erodibility_upper : float, optional
Water erodibility of the upper layer (:math:`K_{1}`). Default is
0.001.
water_erodibility_lower : float, optional
Water erodibility of the upper layer (:math:`K_{2}`). Default is
0.0001.
contact_zone__width : float, optional
Thickness of the contact zone (:math:`W_c`). Default is 1.
regolith_transport_parameter : float, optional
Regolith transport efficiency (:math:`D`). Default is 0.1.
water_erosion_rule_upper__threshold : float, optional.
Erosion threshold of the upper layer (:math:`\omega_{c1}`). Default
is 1.
water_erosion_rule_lower__threshold: float, optional.
Erosion threshold of the upper layer (:math:`\omega_{c2}`). Default
is 1.
critical_slope : float, optional
Critical slope (:math:`S_c`, unitless). Default is 0.3.
number_of_taylor_terms : int, optional
Number of terms in the Taylor Series Expansion (:math:`N`). Default
is 7.
**kwargs :
Keyword arguments to pass to :py:class:`TwoLithologyErosionModel`.
Importantly these arguments specify the precipitator and the runoff
generator that control the generation of surface water discharge
(:math:`Q`).
Returns
-------
BasicChRtTh : model object
Examples
--------
This is a minimal example to demonstrate how to construct an instance
of model **BasicChRtCh**. For more detailed examples, including
steady-state test examples, see the terrainbento tutorials.
To begin, import the model class.
>>> from landlab import RasterModelGrid
>>> from landlab.values import random, constant
>>> from terrainbento import Clock, BasicChRtTh
>>> clock = Clock(start=0, stop=100, step=1)
>>> grid = RasterModelGrid((5,5))
>>> _ = random(grid, "topographic__elevation")
>>> _ = constant(grid, "lithology_contact__elevation", value=-10.)
Construct the model.
>>> model = BasicChRtTh(clock, grid)
Running the model with ``model.run()`` would create output, so here we
will just run it one step.
>>> model.run_one_step(1.)
>>> model.model_time
1.0
"""
# Call ErosionModel"s init
super(BasicChRtTh, self).__init__(clock, grid, **kwargs)
if float(self.n) != 1.0:
raise ValueError("Model only supports n equals 1.")
# verify correct fields are present.
self._verify_fields(self._required_fields)
# Save the threshold values for rock and till
self.rock_thresh = water_erosion_rule_lower__threshold
self.till_thresh = water_erosion_rule_upper__threshold
# Set up rock-till boundary and associated grid fields.
self._setup_rock_and_till_with_threshold()
# Instantiate a StreamPowerSmoothThresholdEroder component
self.eroder = StreamPowerSmoothThresholdEroder(
self.grid,
K_sp=self.erody,
threshold_sp=self.threshold,
m_sp=self.m,
n_sp=self.n,
use_Q="surface_water__discharge",
)
# Instantiate a LinearDiffuser component
self.diffuser = TaylorNonLinearDiffuser(
self.grid,
linear_diffusivity=self.regolith_transport_parameter,
slope_crit=critical_slope,
nterms=number_of_taylor_terms,
)
def run_one_step(self, step):
"""Advance model **BasicChRtTh** for one time-step of duration step.
The **run_one_step** method does the following:
1. Creates rain and runoff, then directs and accumulates flow.
2. Assesses the location, if any, of flooded nodes where erosion should
not occur.
3. Assesses if a :py:mod:`PrecipChanger` is an active boundary handler
and if so, uses it to modify the erodibility by water.
4. Updates the spatially variable erodibility and threshold values
based on the relative distance between the topographic surface and
the lithology contact.
5. Calculates detachment-limited erosion by water.
6. Calculates topographic change by non-linear diffusion.
7. Finalizes the step using the :py:mod:`ErosionModel` base class
function **finalize__run_one_step**. This function updates all
boundary handlers handlers by ``step`` and increments model time by
``step``.
Parameters
----------
step : float
Increment of time for which the model is run.
"""
# create and move water
self.create_and_move_water(step)
# Get IDs of flooded nodes, if any
if self.flow_accumulator.depression_finder is None:
flooded = []
else:
flooded = np.where(
self.flow_accumulator.depression_finder.flood_status == 3
)[0]
# Update the erodibility and threshold field
self._update_erodibility_and_threshold_fields()
# Do some erosion (but not on the flooded nodes)
self.eroder.run_one_step(step, flooded_nodes=flooded)
# Do some soil creep
self.diffuser.run_one_step(
step, dynamic_dt=True, if_unstable="raise", courant_factor=0.1
)
# Finalize the run_one_step_method
self.finalize__run_one_step(step)
class BasicCh(ErosionModel):
r"""**BasicCh** model program.
This model program evolves a topographic surface, :math:`\eta`, with the
following governing equation:
.. math::
\frac{\partial \eta}{\partial t} = -KQ^{m}S^{n} + \nabla^2 q_h
q_h = -DS \left[ 1 + \left( \frac{S}{S_c} \right)^2
+ \left( \frac{S}{S_c} \right)^4
+ ... \left( \frac{S}{S_c} \right)^{2(N-1)} \right]
where :math:`Q` is the local stream discharge, :math:`S` is the local
slope, :math:`m` and :math:`n` are the discharge and slope exponent
parameters, :math:`K` is the erodibility by water, :math:`D` is the
regolith transport efficiency, and :math:`S_c` is the critical slope.
:math:`q_h` represents the hillslope sediment flux per unit width.
:math:`N` is the number of terms in the Taylor Series expansion.
Refer to
`Barnhart et al. (2019) <https://doi.org/10.5194/gmd-12-1267-2019>`_
Table 5 for full list of parameter symbols, names, and dimensions.
The following at-node fields must be specified in the grid:
- ``topographic__elevation``
"""
_required_fields = ["topographic__elevation"]
def __init__(
self,
clock,
grid,
m_sp=0.5,
n_sp=1.0,
water_erodibility=0.0001,
regolith_transport_parameter=0.1,
critical_slope=0.3,
number_of_taylor_terms=11,
**kwargs
):
"""
Parameters
----------
clock : terrainbento Clock instance
grid : landlab model grid instance
The grid must have all required fields.
m_sp : float, optional
Drainage area exponent (:math:`m`). Default is 0.5.
n_sp : float, optional
Slope exponent (:math:`n`). Default is 1.0.
water_erodibility : float, optional
Water erodibility (:math:`K`). Default is 0.0001.
regolith_transport_parameter : float, optional
Regolith transport efficiency (:math:`D`). Default is 0.1.
critical_slope : float, optional
Critical slope (:math:`S_c`, unitless). Default is 0.3.
number_of_taylor_terms : int, optional
Number of terms in the Taylor Series Expansion (:math:`N`). Default
is 11.
**kwargs :
Keyword arguments to pass to :py:class:`ErosionModel`. Importantly
these arguments specify the precipitator and the runoff generator
that control the generation of surface water discharge (:math:`Q`).
Returns
-------
BasicCh : model object
Examples
--------
This is a minimal example to demonstrate how to construct an instance
of model **BasicCh**. For more detailed examples, including
steady-state test examples, see the terrainbento tutorials.
To begin, import the model class.
>>> from landlab import RasterModelGrid
>>> from landlab.values import random
>>> from terrainbento import Clock, BasicCh
>>> clock = Clock(start=0, stop=100, step=1)
>>> grid = RasterModelGrid((5,5))
>>> _ = random(grid, "topographic__elevation")
Construct the model.
>>> model = BasicCh(clock, grid)
Running the model with ``model.run()`` would create output, so here we
will just run it one step.
>>> model.run_one_step(1.)
>>> model.model_time
1.0
"""
# Call ErosionModel"s init
super(BasicCh, self).__init__(clock, grid, **kwargs)
# verify correct fields are present.
self._verify_fields(self._required_fields)
# Get Parameters and convert units if necessary:
self.m = m_sp
self.n = n_sp
self.K = water_erodibility
regolith_transport_parameter = regolith_transport_parameter
# Instantiate a FastscapeEroder component
self.eroder = FastscapeEroder(
self.grid,
K_sp=self.K,
m_sp=self.m,
n_sp=self.n,
discharge_name="surface_water__discharge",
)
# Instantiate a NonLinearDiffuser component
self.diffuser = TaylorNonLinearDiffuser(
self.grid,
linear_diffusivity=regolith_transport_parameter,
slope_crit=critical_slope,
nterms=number_of_taylor_terms,
)
def run_one_step(self, step):
"""Advance model **BasicCh** for one time-step of duration step.
The **run_one_step** method does the following:
1. Creates rain and runoff, then directs and accumulates flow.
2. Assesses the location, if any, of flooded nodes where erosion should
not occur.
3. Assesses if a :py:mod:`PrecipChanger` is an active boundary handler
and if so, uses it to modify the erodibility by water.
4. Calculates detachment-limited erosion by water.
5. Calculates topographic change by nonlinear diffusion.
6. Finalizes the step using the :py:mod:`ErosionModel` base class
function **finalize__run_one_step**. This function updates all
boundary handlers handlers by ``step`` and increments model time by
``step``.
Parameters
----------
step : float
Increment of time for which the model is run.
"""
# create and move water
self.create_and_move_water(step)
# Get IDs of flooded nodes, if any
if self.flow_accumulator.depression_finder is None:
flooded = []
else:
flooded = np.where(
self.flow_accumulator.depression_finder.flood_status == 3
)[0]
# Do some erosion (but not on the flooded nodes)
# (if we're varying K through time, update that first)
if "PrecipChanger" in self.boundary_handlers:
self.eroder.K = (
self.K
* self.boundary_handlers[
"PrecipChanger"
].get_erodibility_adjustment_factor()
)
self.eroder.run_one_step(step, flooded_nodes=flooded)
# Do some soil creep
self.diffuser.run_one_step(
step, dynamic_dt=True, if_unstable="raise", courant_factor=0.1
)
# Finalize the run_one_step_method
self.finalize__run_one_step(step)