NormalFault: Vertical uplift of grid nodes based on a user-specified uplift time series#

Rock uplift along a normal fault.

Landlab component that implements rock uplift by a normal fault. Note that this component does not make any attempt to advect topography laterally.

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

Bases: Component

NormalFault implements relative rock motion due to a normal fault.

The fault can have an arbitrary trace given by two points (x1, y1) and (x2, y2) in the fault_trace input parameter. These value of these points is in model-space coordinates and is not based on node id values or number of rows and columns.

This NormalFault component permits two primary methods for enacting fault motion.

  1. run_one_step: The throw rate is provided through the fault_throw_rate_through_time parameter. This rate can be constant or arbitrary. See the NormalFault tutorial in the landlab tutorials repository for an extensive example. In this case, the NormalFault component will keep track of the cumulative amount of model-run-time and set the rate based on interpolating the provided rate-time history. NOTE: this means that the model run timesteps must align with the time-rate relationship provided to NormalFault. Improving this is on the developers todo list but is of low priority.

  2. run_one_earthquake: A single uplift event of size dz can be specified by this method. If NormalFault is used in this way, any specifications provided in the fault_throw_rate_through_time keyword argument will be ignored.

Note that the NormalFault component does not prevent a user from combining the run_one_step and run_one_earthquake methods. It is encumbent upon the user, however, to ensure that these two methods are used in combination correctly for their specific use case.

References

Required Software Citation(s) Specific to this Component

None Listed

Additional References

None Listed

Instantiation of a NormalFault.

Parameters:
  • grid (ModelGrid) –

  • faulted_surface (str or list of str) – Surface that is modified by the NormalFault component. Must be a field name or a list of field names if the fault should uplift more than one field. Default value is topographic__elevation. If the faulted surface does not yet exist, it will be ingored. The run_one_step method will check to see an ignored field has been added and if it has been, it will modify it.

  • fault_throw_rate_through_time (dict, optional) – Dictionary that specifies the time varying throw rate on the fault. Expected format is: fault_throw_rate_through_time = {‘time’: array, ‘rate’: array} Default value is a constant rate of 0.001 (units not specified). This is acomplished by providing the dictionary {‘time’: [0], ‘rate’: [0.001]}. NormalFault uses numpy.interp to interpolate the time and rate pattern to the current model time. This function uses the first value for all values less than the first, and the last value for all values greater than the last, and thus providing only one number results in all times getting a rate of that value.

  • fault_dip_angle (float, optional) – Dip angle of the fault in degrees. Default value is 90 degrees.

  • fault_trace (dictionary, optional) –

    Dictionary that specifies the coordinates of two locations on the fault trace. Expected format is

    fault_trace = {"x1": float, "y1": float, "x2": float, "y2": float}
    

    where the vector from (x1, y1) to (x2, y2) defines the strike of the fault trace. The orientation of the fault dip relative to the strike follows the right hand rule. Default is for the fault to strike NE.

  • include_boundaries (boolean, optional) – Flag to indicate if model grid boundaries should be uplifted. If set to True uplifted model grid boundaries will be set to the average value of their upstream nodes. Default value is False.

Examples

Create a grid on which we will run the NormalFault component.

>>> from landlab import RasterModelGrid
>>> from landlab.components import NormalFault
>>> grid = RasterModelGrid((6, 6), xy_spacing=10)

Add an elevation field.

>>> z = grid.add_zeros("topographic__elevation", at="node")

Set the parameter values for the NormalFault component.

>>> param_dict = {
...     "faulted_surface": "topographic__elevation",
...     "fault_dip_angle": 90.0,
...     "fault_throw_rate_through_time": {
...         "time": [0, 9, 10],
...         "rate": [0, 0, 0.05],
...     },
...     "fault_trace": {"y1": 0, "x1": 0, "y2": 30, "x2": 60},
...     "include_boundaries": False,
... }

Instantiate a NormalFault component.

>>> nf = NormalFault(grid, **param_dict)
>>> nf.faulted_nodes.reshape(grid.shape)
array([[False, False, False, False, False, False],
       [False,  True, False, False, False, False],
       [False,  True,  True,  True, False, False],
       [False,  True,  True,  True,  True, False],
       [False,  True,  True,  True,  True, False],
       [False, False, False, False, False, False]], dtype=bool)

As we can see, only a subset of the nodes have been identified as faulted nodes. Because we have set include_boundaries’ to False none of the boundary nodes are faulted nodes.

Next we will run the NormalFault for 30 1-year timesteps.

>>> dt = 1.0
>>> for i in range(30):
...     nf.run_one_step(dt)
...
>>> z.reshape(grid.shape)
array([[ 0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  1.,  0.,  0.,  0.,  0.],
       [ 0.,  1.,  1.,  1.,  0.,  0.],
       [ 0.,  1.,  1.,  1.,  1.,  0.],
       [ 0.,  1.,  1.,  1.,  1.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.]])

This results in uplift of the faulted nodes, as we would expect.

If the user knows how much uplift (dz) they want to occur in an event, they can use the run_one_earthquake function with a specified dz. In this case fault_throw_rate_through_time will be ignored.

>>> nf.run_one_earthquake(dz=100)
>>> z.reshape(grid.shape)
array([[   0.,    0.,    0.,    0.,    0.,    0.],
       [   0.,  101.,    0.,    0.,    0.,    0.],
       [   0.,  101.,  101.,  101.,    0.,    0.],
       [   0.,  101.,  101.,  101.,  101.,    0.],
       [   0.,  101.,  101.,  101.,  101.,    0.],
       [   0.,    0.,    0.,    0.,    0.,    0.]])

Next, we make a very simple landscape model. We need a few components and we will set include_boundaries to True.

>>> from landlab.components import FastscapeEroder, FlowAccumulator
>>> grid = RasterModelGrid((6, 6), xy_spacing=10)
>>> z = grid.add_zeros("topographic__elevation", at="node")
>>> param_dict = {
...     "faulted_surface": "topographic__elevation",
...     "fault_dip_angle": 90.0,
...     "fault_throw_rate_through_time": {
...         "time": [0, 900, 1000],
...         "rate": [0, 0, 0.05],
...     },
...     "fault_trace": {"y1": 0, "x1": 0, "y2": 30, "x2": 60},
...     "include_boundaries": True,
... }
>>> nf = NormalFault(grid, **param_dict)
>>> fr = FlowAccumulator(grid)
>>> fs = FastscapeEroder(grid, K_sp=0.01)

Run this model for 300 100-year timesteps.

>>> dt = 100.0
>>> for i in range(300):
...     nf.run_one_step(dt)
...     fr.run_one_step()
...     fs.run_one_step(dt)
...
>>> z.reshape(grid.shape).round(decimals=2)
array([[  0.  ,   0.  ,   0.  ,   0.  ,   0.  ,   0.  ],
       [  5.  ,   5.  ,   0.  ,   0.  ,   0.  ,   0.  ],
       [  7.39,   7.38,   2.38,   2.89,   0.  ,   0.  ],
       [  9.36,  11.43,   5.51,   6.42,   3.54,   3.54],
       [ 15.06,  15.75,  10.6 ,  11.42,   8.54,   8.54],
       [ 15.06,  15.06,  10.7 ,  11.42,   8.54,   8.54]])

The faulted nodes have been uplifted and eroded! Note that here the boundary nodes are also uplifted.

NormalFault keeps track of internal time.

For example, if a user wanted to only run NormalFault every tenth timestep (or some more seismogenically reasonable set of times).

>>> grid = RasterModelGrid((6, 6), xy_spacing=10)
>>> z = grid.add_zeros("topographic__elevation", at="node")
>>> nf = NormalFault(grid, **param_dict)
>>> fr = FlowAccumulator(grid)
>>> fs = FastscapeEroder(grid, K_sp=0.01)
>>> model_time = 0.0
>>> dt = 100.0
>>> for i in range(300):
...     if i % 10 == 0:
...         nf.run_one_step(dt * 10)
...     fr.run_one_step()
...     fs.run_one_step(dt)
...     model_time += dt
...
>>> model_time
30000.0
>>> nf.current_time
30000.0
__init__(grid, faulted_surface='topographic__elevation', fault_throw_rate_through_time=(('time', [0]), ('rate', [0.001])), fault_dip_angle=90.0, fault_trace=(('x1', 0), ('y1', 0), ('x2', 1), ('y2', 1)), include_boundaries=False)[source]#

Instantiation of a NormalFault.

Parameters:
  • grid (ModelGrid) –

  • faulted_surface (str or list of str) – Surface that is modified by the NormalFault component. Must be a field name or a list of field names if the fault should uplift more than one field. Default value is topographic__elevation. If the faulted surface does not yet exist, it will be ingored. The run_one_step method will check to see an ignored field has been added and if it has been, it will modify it.

  • fault_throw_rate_through_time (dict, optional) – Dictionary that specifies the time varying throw rate on the fault. Expected format is: fault_throw_rate_through_time = {‘time’: array, ‘rate’: array} Default value is a constant rate of 0.001 (units not specified). This is acomplished by providing the dictionary {‘time’: [0], ‘rate’: [0.001]}. NormalFault uses numpy.interp to interpolate the time and rate pattern to the current model time. This function uses the first value for all values less than the first, and the last value for all values greater than the last, and thus providing only one number results in all times getting a rate of that value.

  • fault_dip_angle (float, optional) – Dip angle of the fault in degrees. Default value is 90 degrees.

  • fault_trace (dictionary, optional) –

    Dictionary that specifies the coordinates of two locations on the fault trace. Expected format is

    fault_trace = {"x1": float, "y1": float, "x2": float, "y2": float}
    

    where the vector from (x1, y1) to (x2, y2) defines the strike of the fault trace. The orientation of the fault dip relative to the strike follows the right hand rule. Default is for the fault to strike NE.

  • include_boundaries (boolean, optional) – Flag to indicate if model grid boundaries should be uplifted. If set to True uplifted model grid boundaries will be set to the average value of their upstream nodes. Default value is False.

Examples

Create a grid on which we will run the NormalFault component.

>>> from landlab import RasterModelGrid
>>> from landlab.components import NormalFault
>>> grid = RasterModelGrid((6, 6), xy_spacing=10)

Add an elevation field.

>>> z = grid.add_zeros("topographic__elevation", at="node")

Set the parameter values for the NormalFault component.

>>> param_dict = {
...     "faulted_surface": "topographic__elevation",
...     "fault_dip_angle": 90.0,
...     "fault_throw_rate_through_time": {
...         "time": [0, 9, 10],
...         "rate": [0, 0, 0.05],
...     },
...     "fault_trace": {"y1": 0, "x1": 0, "y2": 30, "x2": 60},
...     "include_boundaries": False,
... }

Instantiate a NormalFault component.

>>> nf = NormalFault(grid, **param_dict)
>>> nf.faulted_nodes.reshape(grid.shape)
array([[False, False, False, False, False, False],
       [False,  True, False, False, False, False],
       [False,  True,  True,  True, False, False],
       [False,  True,  True,  True,  True, False],
       [False,  True,  True,  True,  True, False],
       [False, False, False, False, False, False]], dtype=bool)

As we can see, only a subset of the nodes have been identified as faulted nodes. Because we have set include_boundaries’ to False none of the boundary nodes are faulted nodes.

Next we will run the NormalFault for 30 1-year timesteps.

>>> dt = 1.0
>>> for i in range(30):
...     nf.run_one_step(dt)
...
>>> z.reshape(grid.shape)
array([[ 0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  1.,  0.,  0.,  0.,  0.],
       [ 0.,  1.,  1.,  1.,  0.,  0.],
       [ 0.,  1.,  1.,  1.,  1.,  0.],
       [ 0.,  1.,  1.,  1.,  1.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.]])

This results in uplift of the faulted nodes, as we would expect.

If the user knows how much uplift (dz) they want to occur in an event, they can use the run_one_earthquake function with a specified dz. In this case fault_throw_rate_through_time will be ignored.

>>> nf.run_one_earthquake(dz=100)
>>> z.reshape(grid.shape)
array([[   0.,    0.,    0.,    0.,    0.,    0.],
       [   0.,  101.,    0.,    0.,    0.,    0.],
       [   0.,  101.,  101.,  101.,    0.,    0.],
       [   0.,  101.,  101.,  101.,  101.,    0.],
       [   0.,  101.,  101.,  101.,  101.,    0.],
       [   0.,    0.,    0.,    0.,    0.,    0.]])

Next, we make a very simple landscape model. We need a few components and we will set include_boundaries to True.

>>> from landlab.components import FastscapeEroder, FlowAccumulator
>>> grid = RasterModelGrid((6, 6), xy_spacing=10)
>>> z = grid.add_zeros("topographic__elevation", at="node")
>>> param_dict = {
...     "faulted_surface": "topographic__elevation",
...     "fault_dip_angle": 90.0,
...     "fault_throw_rate_through_time": {
...         "time": [0, 900, 1000],
...         "rate": [0, 0, 0.05],
...     },
...     "fault_trace": {"y1": 0, "x1": 0, "y2": 30, "x2": 60},
...     "include_boundaries": True,
... }
>>> nf = NormalFault(grid, **param_dict)
>>> fr = FlowAccumulator(grid)
>>> fs = FastscapeEroder(grid, K_sp=0.01)

Run this model for 300 100-year timesteps.

>>> dt = 100.0
>>> for i in range(300):
...     nf.run_one_step(dt)
...     fr.run_one_step()
...     fs.run_one_step(dt)
...
>>> z.reshape(grid.shape).round(decimals=2)
array([[  0.  ,   0.  ,   0.  ,   0.  ,   0.  ,   0.  ],
       [  5.  ,   5.  ,   0.  ,   0.  ,   0.  ,   0.  ],
       [  7.39,   7.38,   2.38,   2.89,   0.  ,   0.  ],
       [  9.36,  11.43,   5.51,   6.42,   3.54,   3.54],
       [ 15.06,  15.75,  10.6 ,  11.42,   8.54,   8.54],
       [ 15.06,  15.06,  10.7 ,  11.42,   8.54,   8.54]])

The faulted nodes have been uplifted and eroded! Note that here the boundary nodes are also uplifted.

NormalFault keeps track of internal time.

For example, if a user wanted to only run NormalFault every tenth timestep (or some more seismogenically reasonable set of times).

>>> grid = RasterModelGrid((6, 6), xy_spacing=10)
>>> z = grid.add_zeros("topographic__elevation", at="node")
>>> nf = NormalFault(grid, **param_dict)
>>> fr = FlowAccumulator(grid)
>>> fs = FastscapeEroder(grid, K_sp=0.01)
>>> model_time = 0.0
>>> dt = 100.0
>>> for i in range(300):
...     if i % 10 == 0:
...         nf.run_one_step(dt * 10)
...     fr.run_one_step()
...     fs.run_one_step(dt)
...     model_time += dt
...
>>> model_time
30000.0
>>> nf.current_time
30000.0
property faulted_nodes#

At node array indicating which nodes are on the upthrown block.

run_one_earthquake(dz)[source]#

Run one earthquake with uplift of magnitude dz.

run_one_step(dt)[source]#

Run_one_step method for NormalFault.

Parameters:
  • dt (float) – Time increment used to advance the NormalFault component.

  • current_time (float, optional) – If NormalFault is not being advanced by dt every timestep with all components, its internal time may be incorrect, this can be remedied by providing a value for current time. Default value is None which results in the internal timekeeping not being changed.