landlab.components.normal_fault.normal_fault

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[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]])

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]])

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
static __new__(cls, *args, **kwds)
cite_as = ''
property coords

Return the coordinates of nodes on grid attached to the component.

property current_time

Current time.

Some components may keep track of the current time. In this case, the current_time attribute is incremented. Otherwise it is set to None.

Return type:

current_time

definitions = (('topographic__elevation', 'Land surface topographic elevation'),)
property faulted_nodes

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

classmethod from_path(grid, path)

Create a component from an input file.

Parameters:

  • grid (ModelGrid) – A landlab grid.

  • path (str or file_like) – Path to a parameter file, contents of a parameter file, or a file-like object.

Returns:

A newly-created component.

Return type:

Component

property grid

Return the grid attached to the component.

initialize_optional_output_fields()

Create fields for a component based on its optional field outputs, if declared in _optional_var_names.

This method will create new fields (without overwrite) for any fields output by the component as optional. New fields are initialized to zero. New fields are created as arrays of floats, unless the component also contains the specifying property _var_type.

initialize_output_fields(values_per_element=None)

Create fields for a component based on its input and output var names.

This method will create new fields (without overwrite) for any fields output by, but not supplied to, the component. New fields are initialized to zero. Ignores optional fields. New fields are created as arrays of floats, unless the component specifies the variable type.

Parameters:

values_per_element (int (optional)) – On occasion, it is necessary to create a field that is of size (n_grid_elements, values_per_element) instead of the default size (n_grid_elements,). Use this keyword argument to acomplish this task.

input_var_names = ()
name = 'NormalFault'
optional_var_names = ('topographic__elevation',)
output_var_names = ()
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.

property shape

Return the grid shape attached to the component, if defined.

unit_agnostic = True
units = (('topographic__elevation', 'm'),)
classmethod var_definition(name)

Get a description of a particular field.

Parameters:

name (str) – A field name.

Returns:

A description of each field.

Return type:

tuple of (name, *description*)

classmethod var_help(name)

Print a help message for a particular field.

Parameters:

name (str) – A field name.

classmethod var_loc(name)

Location where a particular variable is defined.

Parameters:

name (str) – A field name.

Returns:

The location (‘node’, ‘link’, etc.) where a variable is defined.

Return type:

str

var_mapping = (('topographic__elevation', 'node'),)
classmethod var_type(name)

Returns the dtype of a field (float, int, bool, str…).

Parameters:

name (str) – A field name.

Returns:

The dtype of the field.

Return type:

dtype

classmethod var_units(name)

Get the units of a particular field.

Parameters:

name (str) – A field name.

Returns:

Units for the given field.

Return type:

str