sequence package#

Submodules#

sequence.bathymetry module#

Read bathymetry.

This module contains Landlab components to read bathymetry into a SequenceModelGrid.

class sequence.bathymetry.BathymetryReader(*args, **kwds)[source]#

Bases: Component

Landlab component that reads bathymetry from a file.

__init__(grid: SequenceModelGrid, filepath: str | PathLike[str], kind: str = 'linear')[source]#

Generate a bathymetric profile from a file.

Parameters:

grid (SequenceModelGrid) – A landlab grid.
filepath (str) – Name of csv-formatted bathymetry file.
kind (str, optional) – Kind of interpolation as a string (one of ‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’). Default is ‘linear’.

run_one_step(dt: float | None = None) → None[source]#

Update the grid’s bathymetry.

Parameters:: dt (float, optional) – Time step to update the component by. Currently this value is unused.

property x: ndarray[Any, dtype[floating]]#: Return the x-coordinates of the grid.

property z: ndarray[Any, dtype[floating]]#: Return the elevations along the grid.

sequence.cli module#

The command line interface for Sequence.

sequence.cli.err(message: str | None = None, nl: bool = True, **styles: Any) → None[source]#: Print a user error message.

sequence.cli.out(message: str | None = None, nl: bool = True, **styles: Any) → None[source]#: Print a user info message.

sequence.errors module#

Errors used by sequence.

exception sequence.errors.InvalidRowError(row: int, n_rows: int)[source]#

Bases: OutputValidationError

Raise this exception if a required variable is missing from an output file.

__str__() → str[source]#: Return error message that includes the requested row.

exception sequence.errors.MissingRequiredVariable(name: str)[source]#

Bases: OutputValidationError

Raise this exception if a required variable is missing from an output file.

__str__() → str[source]#: Return error message that includes the name of the missing variable.

exception sequence.errors.OutputValidationError[source]#

Bases: SequenceError

Raise this exception if there is something wrong with an output file.

exception sequence.errors.ParameterMismatchError(keys: Iterable[str])[source]#

Bases: SequenceError

Raise this exception if values from two configurations are mismatched.

__str__() → str[source]#: Return an error message with the offending keys.

exception sequence.errors.SequenceError[source]#

Bases: Exception

All sequence errors should inherit from this class.

exception sequence.errors.ShelfEdgeError(msg: str)[source]#

Bases: SequenceError

Raise this exception is there was an errors locating the shelf edge.

__str__() → str[source]#: Return an error message in human-readable form.

exception sequence.errors.ShorelineError(msg: str)[source]#

Bases: SequenceError

Raise this exception if there was an error locating the shoreline.

__str__() → str[source]#: Return an error message in human-readable form.

sequence.fluvial module#

Calculate the fraction of sand on the delta plain.

This module contains Landlab components that add a sand fraction to a SequenceModelGrid.

class sequence.fluvial.Fluvial(*args, **kwds)[source]#

Bases: Component

Landlab component that calculates delta-plain sand fraction.

__init__(grid: SequenceModelGrid, sand_frac: float = 0.5, wave_base: float = 60.0, sediment_load: float = 3.0, sand_density: float = 2650.0, plain_slope: float = 0.0008, hemipelagic: float = 0.0, sea_level: float = 0.0)[source]#

Generate percent sand/mud for fluvial section.

Add hemipelagic mud to the seaward end of section.

Parameters:

grid (SequenceModelGrid) – A landlab grid.
sand_frac (str, optional) – Fraction of sand on the delta.
wave_base (float, optional) – Wave base (m).
sediment_load (float, optional) – Sediment load.
sand_density (float, optional) – The grain density of sand [kg / m^3]
plain_slope (float, optional) – The gradient of the flood plain.
hemipelagic (float, optional) – Hemipelagic sedimentation.
sea_level (float, optional) – The current sea level (m).

run_one_step(dt: float) → None[source]#

Update the component one time step.

Parameters:: dt (float) – The time step to update the component by.

sequence.grid module#

Define the grid used for creating Sequence models.

class sequence.grid.SequenceModelGrid(shape: int | tuple[int, int], spacing: float | tuple[float, float] = 100.0)[source]#

Bases: RasterModelGrid

Create a Landlab ModelGrid for use with Sequence.

__init__(shape: int | tuple[int, int], spacing: float | tuple[float, float] = 100.0)[source]#

Create a Landlab ModelGrid for use with Sequence.

Parameters:

shape (int or tuple of int) – The number of columns in the cross-shore direction or, if a tuple, (n_rows, n_cols) where rows are in the along-shore direction and columns in the cross-shore direction.
spacing (float or tuple of float, optional) – The spacing between columns or, if len(shape) == 2, (row_spacing, col_spacing).

Examples

>>> from sequence.grid import SequenceModelGrid
>>> grid = SequenceModelGrid(5, spacing=10.0)
>>> grid.y_of_row
array([  0.,  1.,  2.])
>>> grid.x_of_column
array([ 0.,  10.,  20.,  30.,  40.])

>>> grid = SequenceModelGrid((3, 5), spacing=(10000.0, 10.0))
>>> grid.y_of_row
array([  0.,  10000.,  20000.,  30000., 40000.])
>>> grid.x_of_column
array([ 0.,  10.,  20.,  30.,  40.])

classmethod from_dict(params: dict) → SequenceModelGrid[source]#

Create a SequenceModelGrid from a dict.

If possible, this alternate constructor simply passes along the dictionary’s items as keywords to __init__(). It also, however, supports a dictionary that contains the parameters used to create a general RasterModelGrid, quietly ignoring the extra parameters.

Parameters:: params (dict) – A dictionary that contains the parameters needed to create the grid.

Examples

>>> from sequence.grid import SequenceModelGrid
>>> params = {"shape": 5, "spacing": 10.0}
>>> grid = SequenceModelGrid.from_dict(params)
>>> grid.y_of_row
array([  0.,  1.,  2.])
>>> grid.x_of_column
array([ 0.,  10.,  20.,  30.,  40.])

>>> params = {"shape": (3, 5), "spacing": (10000.0, 10.0)}
>>> grid = SequenceModelGrid.from_dict(params)
>>> grid.y_of_row
array([  0.,  10000.,  20000.,  30000., 40000.])
>>> grid.x_of_column
array([ 0.,  10.,  20.,  30.,  40.])

classmethod from_toml(filepath: PathLike[str]) → SequenceModelGrid[source]#

Load a SequenceModelGrid from a toml-formatted file.

Parameters:: filepath (os.PathLike[str]) – Path to the toml file that contains the grid parameters.

get_profile(name: str) → ndarray[Any, dtype[_ScalarType_co]][source]#

Return the values of a field along the grid’s profile.

Parameters:: name (str) – The name of an at-node field.
Returns:: values – The values of the field located at the middle row of nodes.
Return type:: ndarray

property number_of_columns: int#: Number of columns of nodes.

property number_of_rows: int#: Number of rows of nodes.

property x_of_column: ndarray[Any, dtype[_ScalarType_co]]#: X-coordinate for each column of the grid.

property y_of_row: ndarray[Any, dtype[_ScalarType_co]]#: Y-coordinate for each row of the grid.

sequence.input_reader module#

Read input files.

This module contains utilities for reading Sequence input data.

class sequence.input_reader.TimeVaryingConfig(times: Iterable[float], dicts: Iterable[dict])[source]#

Bases: object

A configuration dictionary that is able to change with time.

__call__(time: float) → dict[source]#

Return the configuration at a given time.

Parameters:: time (float) – The time of the configuration.
Returns:: The configuration at the time.
Return type:: dict

__init__(times: Iterable[float], dicts: Iterable[dict])[source]#

Create a time-varying configuration.

Parameters:

times (iterable of int) – Time keys for each dictionary.
dicts (iterable of dict) – Dictionary to use at each time.

Examples

>>> from sequence.input_reader import TimeVaryingConfig
>>> params = TimeVaryingConfig([0, 1], [dict(foo=0, bar=1), dict(foo=1)])
>>> sorted(params.items())
[(('bar',), 1), (('foo',), 0)]
>>> params.update(1)
{'foo': 1}
>>> sorted(params.items())
[(('bar',), 1), (('foo',), 1)]

as_dict() → dict[source]#: Represent the current configuration as a dict.

diff(start: float, stop: float) → dict[source]#

Return the difference between two different configurations.

Parameters:

start (float) – The time of the first configuration.
stop (float) – The time of the second configuration.

Returns:

The key/values that have changed between the two configurations.

Return type:

dict

dump(fmt: str = 'toml') → str[source]#

Write the current configurations to a string.

Parameters:: fmt (str, optional) – Format to dump the configuration to.
Returns:: The configuration in the requested format.
Return type:: str

classmethod from_file(name: PathLike, fmt: str | None = None) → TimeVaryingConfig[source]#

Load a configuration from a file.

Parameters:

name (path-like) – The name of the configuration file to read.
fmt (str, optional) – The format of the configuration file.

classmethod from_files(names: Iterable[str | PathLike[str]], times: Iterable[float] | None = None) → TimeVaryingConfig[source]#

Load a configuration from a set of files.

Parameters:

names (iterable of path-like) – Names of files to read.
times (iterable of float) – Times associated with each file.

static get_loader(fmt: str) → Callable[[TextIO], list[tuple[float, dict]]][source]#

Get a configuration loader for a given format.

Parameters:: fmt (str) – The configuration format (e.g. ‘toml’, ‘yaml’).
Returns:: A loader function for the format.
Return type:: func
Raises:: ValueError – If a loader for the format can’t be found.

static get_supported_formats() → list[str][source]#

Return a list of supported configuration formats.

Returns:: Names of the supported formats.
Return type:: list of str

items() → Iterable[tuple[float, dict]][source]#: Return the items of the current configuration.

static load_toml(stream: TextIO) → list[tuple[float, dict]][source]#

Load a configuration in toml-format.

Parameters:: stream (file-like) – The toml-formatted configuration.
Returns:: The configurations and their associated times.
Return type:: list of (float, dict)

static load_yaml(stream: TextIO) → list[tuple[float, dict]][source]#

Load a configuration in yaml-format.

Parameters:: stream (file-like) – The yaml-formatted configuration.
Returns:: The configurations and their associated times.
Return type:: list of (float, dict)

update(inc: int) → dict[source]#

Update the configurations by a time step.

Parameters:: inc (float) – The amount of time to increment the configuration by.
Returns:: The difference between the current configuration and the new configuration.
Return type:: dict

sequence.input_reader.load_config(stream: TextIO | str | PathLike[str], fmt: str | None = None) → Iterable[tuple[float, dict]] | dict[source]#

Load model configuration from a file-like object.

Parameters:

stream (file-like) – A test stream that contains the configuration.
fmt (str, optional) – The format of the configuration (e.g. ‘toml’, ‘yaml’).

Returns:

The, possibly time-varying, configuration.

Return type:

TimeVaryingConfig

sequence.logging module#

Logger used for printing Sequence log messages.

class sequence.logging.LoggingHandler(level=0)[source]#

Bases: Handler

Print Sequence log messages.

emit(record: LogRecord) → None[source]#

Print a log message.

Parameters:: record (LogRecord) – The log to print.

sequence.logging.logging_handler() → Generator[None, None, None][source]#: Change, temporarily, the current logger.

sequence.netcdf module#

Write a SequenceModelGrid to a NetCDF file.

Write a grid and fields to a netCDF file.

Parameters:

grid (grid_like) – A landlab grid.
filepath (str) – File to which to save the grid.
mode ({'w', 'a'}, optional) – Write (‘w’) or append (‘a’) mode. If mode=’w’, any existing file at this location will be overwritten. If mode=”a”, existing variables will be appended as a new time slice.
format ({'NETCDF4', 'NETCDF4_CLASSIC', 'NETCDF3_64BIT', 'NETCDF3_CLASSIC'}, optional) – File format for the resulting netCDF file.
time (float, optional) – Time to use when adding data. This will be appended to the time variable.
at (str or iterable or str, optional) – Field location(s) on the grid for fields to write. Locations can be ‘node’, ‘link’, ‘patch’, ‘corner’, ‘face’, ‘patch’. The default is to write variables from all field locations.
ids (array_like of int, optional) – Indices of elements to write.
names (iterable or str, optional) – Names of fields to write to the netCDF file.
with_layers (bool, optional) – Indicate if the NetCDF file should contain the grid’s layers.

sequence.output_writer module#

Write a SequenceModelGrid to a file.

class sequence.output_writer.OutputWriter(*args, **kwds)[source]#

Bases: Component

Write output to a netcdf file.

__init__(grid: SequenceModelGrid, filepath: str | PathLike[str], interval: int = 1, fields: Iterable[str] | None = None, clobber: bool = False, rows: Iterable[str] | None = None)[source]#

Create an output-file writer.

Parameters:

grid (SequenceModelGrid) – The grid to write to a file.
filepath (path-like) – Path to the output file.
interval (int, optional) – The number of time steps between updates to the output file.
fields (list of str, optional) – Names of (at-node) fields to include in the output file.
clobber (bool, optional) – If True and the provided file already exists, quietly overwrite it, otherwise raise an exception.
rows (iterable of int) – The rows of the grid to include in the file.

property fields: Iterable[str]#: Return the names of the fields to include in the output file.

property filepath: str | PathLike[str]#: Return the path to the output file.

property interval: int#: Return the interval for which output will be written.

run_one_step(dt: float | None = None) → None[source]#

Update the writer by a time step.

Parameters:: dt (float, optional) – The time step to update the component by.

sequence.plot module#

Plot the layers of a SequenceModelGrid.

sequence.plot.plot_file(filename: str | PathLike, row: int | None = None, **kwds: Any) → None[source]#

Plot a SequenceModelGrid from a Sequence output file.

Parameters:

filename (path-like) – Path to the file to plot.
row (int, optional) – Row to plot. If not provided, plot the middle row.
**kwds (dict, optional) – Additional keyword arguments that are passed along to plot_layers().

sequence.processes module#

All available processes to include in a Sequence model.

class sequence.processes.Compact(*args, **kwds)[source]#

Bases: Component

__init__(grid, c: float = 5e-08, rho_grain: float = 2650.0, excess_pressure: float = 0.0, porosity_min: float = 0.0, porosity_max: float = 1.0, rho_void: float = 1000.0, gravity: float = 9.80665)[source]#

Compact layers of sediment.

Parameters:

grid (RasterModelGrid) – A landlab grid.
c (ndarray or number, optional) – Compaction coefficient that describes how easily the sediment is to compact [Pa^-1].
rho_grain (ndarray or number, optional) – Grain density of the sediment [kg / m^3].
excess_pressure (ndarray or number, optional) – Excess pressure with depth [Pa].
porosity_min (ndarray or number, optional) – Minimum porosity that can be achieved by the sediment. This is the porosity of the sediment in its closest-compacted state [-].
porosity_max (ndarray or number, optional) – Maximum porosity of the sediment. This is the porosity of the sediment without any compaction [-].
rho_void (ndarray or number, optional) – Density of the interstitial fluid [kg / m^3].
gravity (float) – Acceleration due to gravity [m / s^2].

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid

>>> grid = RasterModelGrid((3, 5))
>>> for layer in range(5):
...     grid.event_layers.add(100.0, porosity=0.7)

>>> compact = Compact(grid, porosity_min=0.1, porosity_max=0.7)
>>> compact.run_one_step()
RasterModelGrid((3, 5), xy_spacing=(1.0, 1.0), xy_of_lower_left=(0.0, 0.0))

>>> compact.grid.event_layers["porosity"] < 0.7
array([[ True,  True,  True],
       [ True,  True,  True],
       [ True,  True,  True],
       [ True,  True,  True],
       [False, False, False]], dtype=bool)
>>> compact.grid.event_layers.dz < 100.0
array([[ True,  True,  True],
       [ True,  True,  True],
       [ True,  True,  True],
       [ True,  True,  True],
       [False, False, False]], dtype=bool)

property c: float#

calculate()[source]#

property excess_pressure: float#

property gravity: float#

property params#

property porosity_max: float#

property porosity_min: float#

property rho_grain: float#

property rho_void: float#

run_one_step(dt=None)[source]#

class sequence.processes.Fluvial(*args, **kwds)[source]#

Bases: Component

Landlab component that calculates delta-plain sand fraction.

Generate percent sand/mud for fluvial section.

Add hemipelagic mud to the seaward end of section.

Parameters:

grid (SequenceModelGrid) – A landlab grid.
sand_frac (str, optional) – Fraction of sand on the delta.
wave_base (float, optional) – Wave base (m).
sediment_load (float, optional) – Sediment load.
sand_density (float, optional) – The grain density of sand [kg / m^3]
plain_slope (float, optional) – The gradient of the flood plain.
hemipelagic (float, optional) – Hemipelagic sedimentation.
sea_level (float, optional) – The current sea level (m).

run_one_step(dt: float) → None[source]#

Update the component one time step.

Parameters:: dt (float) – The time step to update the component by.

class sequence.processes.SeaLevelTimeSeries(*args, **kwds)[source]#

Bases: Component

Modify sea level through a time series.

__init__(grid: SequenceModelGrid, filepath: str | PathLike[str], kind: str = 'linear', start: float = 0.0)[source]#

Generate sea level values.

Parameters:

grid (SequenceModelGrid) – A landlab grid.
filepath (str) – Name of csv-formatted sea-level file.
kind (str, optional) – Kind of interpolation as a string (one of ‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’). Default is ‘linear’.
start (float, optional) – Set the initial time for the component.

property filepath: str | PathLike[str]#: Return the path to the sea-level file.

run_one_step(dt: float) → None[source]#

Update the component by a time step.

Parameters:: dt (float) – The time step.

property time: float#: Return the current component time.

class sequence.processes.SedimentFlexure(*args, **kwds)[source]#

Bases: DynamicFlexure

Landlab component that deflects a SequenceModelGrid due to sediment loading.

__init__(grid: SequenceModelGrid, sand_density: float = 2650, mud_density: float = 2720.0, isostasytime: float | None = 7000.0, water_density: float = 1030.0, **kwds: dict)[source]#

Subside elevations due to sediment loading.

Parameters:

grid (ModelGrid) – A landlab grid.
sand_density (float, optional) – Grain density of the sediment sand-fraction.
mud_density (float, optional) – Grain density of the sediment mud-fraction.
water_density (float, optional) – Density of water.
isostasytime (float, optional) – Response time of the lithosphere to loading.
**kwds (dict, optional) – Additional keyword arguments that are passed to Flexure1D.

static calc_bulk_density(grain_density: float | ndarray[Any, dtype[floating]], void_density: float | ndarray[Any, dtype[floating]], porosity: float | ndarray[Any, dtype[floating]]) → float | ndarray[Any, dtype[floating]][source]#

Calculate the bulk density of a material with a given porosity.

Parameters:

grain_density (float) – Density of grains.
void_density (float) – Density of material that fills the void space.
porosity (float) – The porosity of the mixture.

Returns:

The bulk density of the material.

Return type:

float

property mud_bulk_density: float | ndarray[Any, dtype[floating]]#: Return the bulk density of mud.

property mud_density: float#: Return the density of mud.

run_one_step(dt: float = 1.0) → None[source]#

Update the component by a time step.

Parameters:: dt (float, optional) – The time step over which to update the component.

property sand_bulk_density: float | ndarray[Any, dtype[floating]]#: Return the bulk density of sand.

property sand_density: float#: Return the density of sand.

update() → None[source]#: Update the component by a single time step.

static validate_density(density: float) → float[source]#

Validate a density value.

Parameters:: density (float) – The density value to validate.
Returns:: The density value.
Return type:: float
Raises:: ValueError – Raised if the value is invalid.

property water_density: float#: Return the density of water.

class sequence.processes.ShorelineFinder(*args, **kwds)[source]#

Bases: Component

Find a grid’s shoreline.

__init__(grid: SequenceModelGrid, alpha: float = 0.0005)[source]#

Create a shoreline finder.

Parameters:

grid (SequenceModelGrid) – A Sequence grid.
alpha (float, optional) – Parameter used to find the shoreline when interpolating between nodes.

property alpha: float#: Return the alpha parameter used to calculate the shoreline.

run_one_step(dt: float | None = None) → None[source]#

Update the component on time step.

Parameters:: dt (float, optional) – The time step to update the component by. Since this component is not time-varying, this value is ignored.

update() → None[source]#: Update the component one time step to find the new shoreline.

class sequence.processes.SinusoidalSeaLevel(*args, **kwds)[source]#

Bases: SeaLevelTimeSeries

Adjust a grid’s sea level using a sine curve.

__init__(grid: SequenceModelGrid, wave_length: float = 1.0, amplitude: float = 1.0, phase: float = 0.0, mean: float = 0.0, start: float = 0.0, linear: float = 0.0)[source]#

Generate sea level values.

Parameters:

grid (SequenceModelGrid) – A landlab grid.
wave_length (float, optional) – The wave length of the sea-level curve in [y].
amplitude (float, optional) – The amplitude of the sea-level curve.
phase (float, optional) – The phase shift of the sea-level curve [y].
mean (float, optional) – Mean sea-level (disregarding any trend with time).
start (float, optional) – The time of the component [y].
linear (float, optional) – Linear trend of the sea-level curve with time [m / y].

class sequence.processes.SubmarineDiffuser(*args, **kwds)[source]#

Bases: LinearDiffuser

Model sea-floor evolution on a SequenceModelGrid as diffusion.

__init__(grid: SequenceModelGrid, sea_level: float = 0.0, plain_slope: float = 0.0008, wave_base: float = 60.0, shoreface_height: float = 15.0, alpha: float = 0.0005, shelf_slope: float = 0.001, sediment_load: float = 3.0, load_sealevel: float = 0.0, basin_width: float = 500000.0, **kwds: Any)[source]#

Diffuse the ocean bottom.

Parameters:

grid (RasterModelGrid) – A landlab grid.
sea_level (float, optional) – The current sea level (m).
plain_slope (float, optional) – Slope of the delta plain (m / m).
wave_base (float, optional) – Wave base (m).
shoreface_height (float, optional) – Water depth of the shelf/slope break (m).
alpha (float, optional) – Coefficient used to calculate the diffusion coefficient (1 / m).
shelf_slope (float, optional) – Slope of the shelf (m / m).
sediment_load (float, optional) – Sediment load entering the profile (m2 / y).
load_sealevel (float, optional) – Fractional variation of sediment load with sea level (m2/y/m_sl). i.e., .003 =0.3% increase/decrease with sea level rise/fall (30% with 100m)
basin_width (float, optional) – Length of drainage basin upstream of model. Creates increase in diffusivity downstream by (basin_width + x) / basin_width from increase river flow (m).
**kwds (dict, optional) – Additional keyword arguments that are passed along to LinearDiffuser.

property alpha: float#: Return the alpha parameter.

calc_diffusion_coef(x_of_shore: ndarray[Any, dtype[floating]] | float) → ndarray[Any, dtype[floating]][source]#

Calculate and store diffusion coefficient values.

Parameters:: x_of_shore (float) – The x-position of the shoreline.

Examples

The example below tests the result with 3 of the middle-row nodes above sea level and three below, two of which are in deep water (below the default 60 m wave base).

>>> from sequence.grid import SequenceModelGrid
>>> import numpy as np

>>> grid = SequenceModelGrid((1, 6), spacing=(1.0, 200.0))
>>> z = grid.add_zeros("topographic__elevation", at="node")
>>> z[6:12] = np.array([3., 3., 1., -1., -85., -85.])
>>> z.reshape((3, 6))
array([[  0.,   0.,   0.,   0.,   0.,   0.],
       [  3.,   3.,   1.,  -1., -85., -85.],
       [  0.,   0.,   0.,   0.,   0.,   0.]])

>>> submarine_diffuser = SubmarineDiffuser(grid, basin_width=0.0)
>>> diffusion_coef = submarine_diffuser.calc_diffusion_coef(x_of_shore=500.0)

>>> np.round(diffusion_coef.reshape((3, 6))[1])
array([ 3750.,  3750.,  3750.,   333.,    11.,    16.])

The calculated diffusion coefficient is also saved as an at-node field.

>>> diffusion_coef is grid.at_node["kd"]
True

property k_land: float#: Return the diffusion coefficient use for land.

property load0: float#: Return the sediment load entering the profile.

property plain_slope: float#: Return the gradient of the delta plain.

run_one_step(dt: float) → None[source]#

Advance component one time step.

Parameters:: dt (float) – Time step to advance component by.

property sea_level: float#: Return sea level elevation.

property sediment_load: float#: Return the sediment load entering the profile.

property shelf_slope: float#: Return the slope of the shelf.

property shoreface_height: float#: Return the height of the shoreface.

property time: float#: Return the component’s current time.

property wave_base: float#: Return the depth of the wave base.

class sequence.processes.SubsidenceTimeSeries(*args, **kwds)[source]#

Bases: Component

A Landlab component that subsides a grid.

__init__(grid: SequenceModelGrid, filepath: PathLike, kind: str = 'linear')[source]#

Create a grid subsider from a time-series file.

Parameters:

grid (SequenceModelGrid) – A landlab grid.
filepath (os.PathLike) – Name of csv-formatted subsidence file.
kind (str, optional) – Kind of interpolation as a string (one of ‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’). Default is ‘linear’.

property filepath: str#: Return the path to the current subsidence file.

run_one_step(dt: float) → None[source]#

Update the component by a time step.

Parameters:: dt (float) – The time step to update the component by.

property subsidence_rate: ndarray[Any, dtype[_ScalarType_co]]#: Return the current subsidence rate.

property time: float#: Return the current component time.

sequence.sea_level module#

Components that adjust sea level.

This module contains Landlab components used for adjusting a grid’s sea level.

class sequence.sea_level.SeaLevelTimeSeries(*args, **kwds)[source]#

Bases: Component

Modify sea level through a time series.

__init__(grid: SequenceModelGrid, filepath: str | PathLike[str], kind: str = 'linear', start: float = 0.0)[source]#

Generate sea level values.

Parameters:

grid (SequenceModelGrid) – A landlab grid.
filepath (str) – Name of csv-formatted sea-level file.
kind (str, optional) – Kind of interpolation as a string (one of ‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’). Default is ‘linear’.
start (float, optional) – Set the initial time for the component.

property filepath: str | PathLike[str]#: Return the path to the sea-level file.

run_one_step(dt: float) → None[source]#

Update the component by a time step.

Parameters:: dt (float) – The time step.

property time: float#: Return the current component time.

class sequence.sea_level.SinusoidalSeaLevel(*args, **kwds)[source]#

Bases: SeaLevelTimeSeries

Adjust a grid’s sea level using a sine curve.

__init__(grid: SequenceModelGrid, wave_length: float = 1.0, amplitude: float = 1.0, phase: float = 0.0, mean: float = 0.0, start: float = 0.0, linear: float = 0.0)[source]#

Generate sea level values.

Parameters:

grid (SequenceModelGrid) – A landlab grid.
wave_length (float, optional) – The wave length of the sea-level curve in [y].
amplitude (float, optional) – The amplitude of the sea-level curve.
phase (float, optional) – The phase shift of the sea-level curve [y].
mean (float, optional) – Mean sea-level (disregarding any trend with time).
start (float, optional) – The time of the component [y].
linear (float, optional) – Linear trend of the sea-level curve with time [m / y].

sequence.sediment_flexure module#

Subside a SequenceModelGrid using flexure.

class sequence.sediment_flexure.DynamicFlexure(*args, **kwds)[source]#

Bases: Flexure1D

Calculate non-isostatic flexure.

__init__(grid: SequenceModelGrid, isostasytime: float | None = 7000.0, **kwds: dict[str, Any])[source]#

Inherit from this base class for non-isostatic flexure.

Parameters:

grid (SequenceModelGrid) – A Landlab grid.
isostasytime (float, optional) – The e-folding time for a deflection to reach equilibrium.
**kwds (dict, optional) – Additional keyword arguments that are passed to Flexure1D.

calc_dynamic_deflection(isostatic_deflection: ndarray[Any, dtype[floating]], dt: float) → ndarray[Any, dtype[floating]][source]#

Calculate the non-isostatic deflection.

Parameters:

isostatic_deflection (ndarray of float) – The isostatic deflection.
dt (float) – Time step over which to subside.

Returns:

deflection – The deflections over the given time step.

Return type:

ndarray of float

static calc_isostasy_fraction(isostasy_time: float | None, dt: float) → float[source]#

Calculate the fraction of isostatic subsidence.

Parameters:

isostasy_time (float or None) – The time parameter that represente the e-folding time to isostasy. If None, assume isostasy.
dt (float) – Time step.

Returns:

Fraction of isostatic subsidence that occurs over the time step.

Return type:

float

property isostasy_time: float | None#: Return the isostasy time.

static validate_isostasy_time(time: float) → float[source]#

Validate an isostasy time value.

Parameters:: time (float) – The isostasy time value to validate.
Returns:: The isostasy time value.
Return type:: float
Raises:: ValueError – Raised if the value is invalid.

class sequence.sediment_flexure.SedimentFlexure(*args, **kwds)[source]#

Bases: DynamicFlexure

Landlab component that deflects a SequenceModelGrid due to sediment loading.

__init__(grid: SequenceModelGrid, sand_density: float = 2650, mud_density: float = 2720.0, isostasytime: float | None = 7000.0, water_density: float = 1030.0, **kwds: dict)[source]#

Subside elevations due to sediment loading.

Parameters:

grid (ModelGrid) – A landlab grid.
sand_density (float, optional) – Grain density of the sediment sand-fraction.
mud_density (float, optional) – Grain density of the sediment mud-fraction.
water_density (float, optional) – Density of water.
isostasytime (float, optional) – Response time of the lithosphere to loading.
**kwds (dict, optional) – Additional keyword arguments that are passed to Flexure1D.

Calculate the bulk density of a material with a given porosity.

Parameters:

grain_density (float) – Density of grains.
void_density (float) – Density of material that fills the void space.
porosity (float) – The porosity of the mixture.

Returns:

The bulk density of the material.

Return type:

float

property mud_bulk_density: float | ndarray[Any, dtype[floating]]#: Return the bulk density of mud.

property mud_density: float#: Return the density of mud.

run_one_step(dt: float = 1.0) → None[source]#

Update the component by a time step.

Parameters:: dt (float, optional) – The time step over which to update the component.

property sand_bulk_density: float | ndarray[Any, dtype[floating]]#: Return the bulk density of sand.

property sand_density: float#: Return the density of sand.

update() → None[source]#: Update the component by a single time step.

static validate_density(density: float) → float[source]#

Validate a density value.

Parameters:: density (float) – The density value to validate.
Returns:: The density value.
Return type:: float
Raises:: ValueError – Raised if the value is invalid.

property water_density: float#: Return the density of water.

class sequence.sediment_flexure.WaterFlexure(*args, **kwds)[source]#

Bases: DynamicFlexure

Landlab component that deflects a SequenceModelGrid due to water loading.

__init__(grid: SequenceModelGrid, isostasytime: float | None = 7000.0, **kwds: dict)[source]#

Calculate flexural subsidence due to changes in water loading.

Parameters:

grid (SequenceModelGrid) – A Landlab grid.
isostasytime (float) – The e-folding time for a deflection to reach equilibrium.
water_density (float, optional) – Density of water.
**kwds (dict, optional) – Additional keyword arguments that are passed to Flexure1D.

calc_flexure_due_to_water(change_in_water_depth: ndarray[Any, dtype[floating]], change_in_sea_level: float) → ndarray[Any, dtype[floating]][source]#

Calculate flexure due to water loading.

Parameters:

change_in_water_depth (ndarray or float) – The change in water depth along the profile causing the deflection.
change_in_sea_level (float) – The change in sea level that adds to the deflection.

Returns:

Deflections along the profile caused by the water loading.

Return type:

ndarray of float

calc_half_plane_deflection(load: float) → ndarray[Any, dtype[floating]][source]#

Calculate the deflection due to a half-plane load.

Parameters:: load (float) – The added (or removed) load.
Returns:: The deflections along the grid.
Return type:: ndarray

static calc_water_loading(z: ndarray[Any, dtype[floating]], water_density: float) → ndarray[Any, dtype[floating]][source]#: Calculate the water load.

run_one_step(dt: float) → None[source]#

Update the component by a time step.

Parameters:: dt (float) – The time step over which to update the component.

update() → None[source]#: Update the component by a single time step.

sequence.sequence module#

Sequence’s main API for constructing sequence-stratigraphic models.

class sequence.sequence.Sequence(*args, **kwds)[source]#

Bases: Component

Landlab component interface to the Sequence model.

__init__(grid: SequenceModelGrid, time_step: float = 100.0, components: Iterable | None = None)[source]#

Create a Sequence model.

Parameters:

grid (SequenceModelGrid) – A model grid.
time_step (float, optional) – The time step at which the model will run each of its components.
components (iterable, optional) – A list of components to run every time step.

add_layer(dz_at_cell: ndarray[Any, dtype[floating]]) → None[source]#

Add a new layer to each cell.

Properties#

dz_at_cellarray-like: Thickness of the new layers for each cell along the profile.

Return the properties being tracked at each layer.

Returns:: properties – A dictionary of the tracked properties where the keys are the names of properties and the values are the property values at each column.
Return type:: dict

layer_reducers() → dict[str, Any][source]#

Return layer-reducers for each property.

Returns:: reducers – A dictionary of reducers where keys are property names and values are functions that act as layer reducers for those quantities.
Return type:: dict

plot() → None[source]#: Plot the grid.

run(until: float | None = None, dt: float | None = None, progress_bar: bool = True) → None[source]#

Run the model to a given time.

Parameters:

until (float, optional) – The time (in years) to run the model to. If not provided, run for a single time step.
dt (float, optional) – Run using a time step other than what the component was initialized with.
progress_bar (bool, optional) – If True display a progress bar while the model is running.

property time: float#: Return the current model time (in years).

update(dt: float | None = None) → None[source]#

Update the model of a given time step.

Parameters:: dt (float, optional) – The length of time to run the model for. If not given, update the model a single time step.

sequence.sequence_model module#

Build a SequenceModelGrid model from collection of components.

class sequence.sequence_model.SequenceModel(grid: SequenceModelGrid, clock: dict | None = None, processes: dict | None = None, output: dict | None = None)[source]#

Bases: object

Orchestrate a set of components that operate on a SequenceModelGrid.

ALL_PROCESSES = ('sea_level', 'subsidence', 'compaction', 'submarine_diffusion', 'fluvial', 'flexure')#

DEFAULT_PARAMS = {'bathymetry': {'filepath': 'bathymetry.csv', 'kind': 'linear'}, 'clock': {'start': 0.0, 'step': 100.0, 'stop': 600000.0}, 'compaction': {'c': 5e-08, 'porosity_max': 0.5, 'porosity_min': 0.01, 'rho_grain': 2650.0, 'rho_void': 1000.0}, 'flexure': {'isostasytime': 0, 'method': 'flexure', 'rho_mantle': 3300.0}, 'grid': {'shape': (1, 100), 'spacing': (1.0, 1000.0)}, 'output': {'clobber': True, 'fields': ['sediment_deposit__thickness', 'bedrock_surface__elevation'], 'filepath': 'sequence.nc', 'interval': 10}, 'sea_level': {'amplitude': 10.0, 'linear': 0.0, 'phase': 0.0, 'wave_length': 200000.0}, 'sediments': {'hemipelagic': 0.0, 'layers': 2, 'mud': 0.006, 'mud_density': 2720.0, 'sand': 1.0, 'sand_density': 2650.0, 'sand_frac': 0.5}, 'submarine_diffusion': {'alpha': 0.0005, 'basin_width': 500000.0, 'load_sealevel': 0.0, 'plain_slope': 0.0008, 'sediment_load': 3.0, 'shelf_slope': 0.001, 'shoreface_height': 15.0, 'wave_base': 60.0}, 'subsidence': {'filepath': 'subsidence.csv'}}#

LONG_NAME = {'z': 'topographic__elevation', 'z0': 'bedrock_surface__elevation'}#

__init__(grid: SequenceModelGrid, clock: dict | None = None, processes: dict | None = None, output: dict | None = None)[source]#

Create a model on a SequenceModelGrid.

Parameters:

grid (SequenceModelGrid) – The grid on which the model is run.
clock (dict) – Parameters for the model’s clock.
processes (iterable of components) – A list of the components to run as part of the model.
output (component) – A component used to write output files.

advance_components(dt: float) → None[source]#

Update each of the components by a time step.

Parameters:: dt (float) – The time step to advance the components.

property clock: TimeStepper#: Return the model’s clock.

property components: tuple#: Return the name of enabled components.

property grid: SequenceModelGrid#: Return the model’s grid.

Return the properties being tracked at each layer.

Returns:: properties – A dictionary of the tracked properties where the keys are the names of properties and the values are the property values at each column.
Return type:: dict

layer_reducers() → dict[str, Any][source]#

Return layer-reducers for each property.

Returns:: reducers – A dictionary of reducers where keys are property names and values are functions that act as layer reducers for those quantities.
Return type:: dict

static load_grid(params: dict, bathymetry: dict | None = None) → SequenceModelGrid[source]#

Load a SequenceModelGrid.

Parameters:

params (dict) – Parameters used to create the grid.
bathymetry (dict, optional) – Parameters used to set the initial bathymetry of the grid.

static load_processes(grid: SequenceModelGrid, processes: Iterable[str], context: dict[str, dict]) → dict[source]#

Instantiate processes.

Parameters:

grid (SequenceModelGrid) – A Sequence grid.
processes (Iterable[str], optional) – List of the names of the processes to create.
context (dict) – A context from which to draw parameters to create the processes.

run() → None[source]#: Run the model until complete.

run_one_step(dt: float | None = None) → None[source]#: Run each component for one time step.

set_params(params: dict[str, dict]) → None[source]#

Update the parameters for the model’s processes.

Parameters:: params (dict) – The new parameters for the processes.

sequence.shoreline module#

Find the shoreline of a SequenceModelGrid.

This module contains methods for calculating a grid’s shoreline and shelf edge.

class sequence.shoreline.ShorelineFinder(*args, **kwds)[source]#

Bases: Component

Find a grid’s shoreline.

__init__(grid: SequenceModelGrid, alpha: float = 0.0005)[source]#

Create a shoreline finder.

Parameters:

grid (SequenceModelGrid) – A Sequence grid.
alpha (float, optional) – Parameter used to find the shoreline when interpolating between nodes.

property alpha: float#: Return the alpha parameter used to calculate the shoreline.

run_one_step(dt: float | None = None) → None[source]#

Update the component on time step.

Parameters:: dt (float, optional) – The time step to update the component by. Since this component is not time-varying, this value is ignored.

update() → None[source]#: Update the component one time step to find the new shoreline.

sequence.shoreline.find_shelf_edge(x: ndarray[Any, dtype[floating]], dz: ndarray[Any, dtype[floating]], x_of_shore: ndarray[Any, dtype[floating]] | float = 0.0, alpha: float = 0.0005) → float[source]#

Find the shelf edge based on deposit thickness.

Parameters:

x (ndarray of float) – x-positions of the profile.
dz (ndarray of float) – Deposit thickness.
x_of_shore (float, optional) – The x-position of the shoreline.
alpha (float, optional) – Constant used in interpolating the precise location of the shoreline.

Returns:

The x-coordinate of the shelf edge.

Return type:

float

Raises:

ShelfEdgeError – If the data do not contain the shelf edge.

Examples

>>> import numpy as np
>>> from sequence.shoreline import find_shelf_edge

Create a depositional profile where the maximum deposition is at x=1.0.

>>> x = np.arange(50.) / 5.0
>>> deposit = x * np.exp(-x)
>>> find_shelf_edge(x, deposit, x_of_shore=0.0, alpha=1e3)
1.0

sequence.shoreline.find_shelf_edge_by_curvature(x: ndarray[Any, dtype[floating]], z: ndarray[Any, dtype[floating]], sea_level: float = 0.0) → float[source]#

Find the x-coordinate of the shelf edge.

The shelf edge is the location where the curvature of sea-floor elevations is a minimum.

Parameters:

x (ndarray of float) – x-positions of the profile.
z (ndarray of float) – Elevations of the profile.
sea_level (float, optional) – Elevation of sea level.

Returns:

The x-coordinate of the shelf edge.

Return type:

float

Examples

>>> import numpy as np
>>> from sequence.shoreline import find_shelf_edge_by_curvature

>>> x = np.arange(50.)
>>> z = - np.arctan(x / 5.0 - 5.0)
>>> find_shelf_edge_by_curvature(x, z, sea_level=z.max())
22.0

sequence.shoreline.find_shoreline(x: ndarray[Any, dtype[floating]], z: ndarray[Any, dtype[floating]], sea_level: float = 0.0, kind: str = 'cubic') → ndarray[Any, dtype[floating]] | float[source]#

Find the shoreline of a profile.

Parameters:

x (array of float) – X-positions of profile.
z (array of float) – Elevations along the profile.
sea_level (float, optional) – Elevation of sea level.
kind (str, optional) – Interpolation method used to find shoreline. Values are the same as those used for scipy.interpolate.interp1d. Default is ‘cubic’.

Returns:

X-position of the shoreline.

Return type:

float

Examples

>>> from sequence.shoreline import find_shoreline
>>> import numpy as np

Create a linearly-dipping profile.

>>> x = np.arange(10.)
>>> z = - x + 5.
>>> z
array([ 5.,  4.,  3.,  2.,  1.,  0., -1., -2., -3., -4.])

Find the shoreline.

>>> find_shoreline(x, z, kind='linear')
5.0
>>> find_shoreline(x, z, sea_level=.25, kind='linear')
4.75

If sea level is higher/lower than the max/min elevation, return the first/last x value.

>>> find_shoreline(x, z, sea_level=100., kind='linear')
0.0
>>> find_shoreline(x, z, sea_level=-100., kind='linear')
9.0

sequence.shoreline.find_shoreline_index(x: ndarray[Any, dtype[floating]], z: ndarray[Any, dtype[floating]], sea_level: float = 0.0) → ndarray[Any, dtype[integer]] | int[source]#

Find the landward-index of the shoreline.

Parameters:

x (array of float) – X-positions of profile.
z (array of float) – Elevations along the profile.
sea_level (float, optional) – Elevation of sea level.

Returns:

Index into z landward of the shoreline.

Return type:

int

Raises:

ValueError – If the profile does not contain a shoreline.

Examples

>>> from sequence.shoreline import find_shoreline_index
>>> import numpy as np

Create a linearly-dipping profile.

>>> x = np.arange(10.)
>>> z = - x + 5.
>>> z
array([ 5.,  4.,  3.,  2.,  1.,  0., -1., -2., -3., -4.])

Find the shoreline.

>>> find_shoreline_index(x, z)
6
>>> find_shoreline_index(x, z, sea_level=.25)
5

If sea level is higher/lower than the max/min elevation, raise a ShorelineError.

>>> find_shoreline_index(x, z, sea_level=100.)
Traceback (most recent call last):
sequence.errors.ShorelineError: No shoreline found. The profile is all below sea level
>>> find_shoreline_index(x, z, sea_level=-100.)
Traceback (most recent call last):
sequence.errors.ShorelineError: No shoreline found. The profile is all above sea level

sequence.submarine module#

Diffuse sediment along a profile.

class sequence.submarine.SubmarineDiffuser(*args, **kwds)[source]#

Bases: LinearDiffuser

Model sea-floor evolution on a SequenceModelGrid as diffusion.

Diffuse the ocean bottom.

Parameters:

grid (RasterModelGrid) – A landlab grid.
sea_level (float, optional) – The current sea level (m).
plain_slope (float, optional) – Slope of the delta plain (m / m).
wave_base (float, optional) – Wave base (m).
shoreface_height (float, optional) – Water depth of the shelf/slope break (m).
alpha (float, optional) – Coefficient used to calculate the diffusion coefficient (1 / m).
shelf_slope (float, optional) – Slope of the shelf (m / m).
sediment_load (float, optional) – Sediment load entering the profile (m2 / y).
load_sealevel (float, optional) – Fractional variation of sediment load with sea level (m2/y/m_sl). i.e., .003 =0.3% increase/decrease with sea level rise/fall (30% with 100m)
basin_width (float, optional) – Length of drainage basin upstream of model. Creates increase in diffusivity downstream by (basin_width + x) / basin_width from increase river flow (m).
**kwds (dict, optional) – Additional keyword arguments that are passed along to LinearDiffuser.

property alpha: float#: Return the alpha parameter.

calc_diffusion_coef(x_of_shore: ndarray[Any, dtype[floating]] | float) → ndarray[Any, dtype[floating]][source]#

Calculate and store diffusion coefficient values.

Parameters:: x_of_shore (float) – The x-position of the shoreline.

Examples

The example below tests the result with 3 of the middle-row nodes above sea level and three below, two of which are in deep water (below the default 60 m wave base).

>>> from sequence.grid import SequenceModelGrid
>>> import numpy as np

>>> grid = SequenceModelGrid((1, 6), spacing=(1.0, 200.0))
>>> z = grid.add_zeros("topographic__elevation", at="node")
>>> z[6:12] = np.array([3., 3., 1., -1., -85., -85.])
>>> z.reshape((3, 6))
array([[  0.,   0.,   0.,   0.,   0.,   0.],
       [  3.,   3.,   1.,  -1., -85., -85.],
       [  0.,   0.,   0.,   0.,   0.,   0.]])

>>> submarine_diffuser = SubmarineDiffuser(grid, basin_width=0.0)
>>> diffusion_coef = submarine_diffuser.calc_diffusion_coef(x_of_shore=500.0)

>>> np.round(diffusion_coef.reshape((3, 6))[1])
array([ 3750.,  3750.,  3750.,   333.,    11.,    16.])

The calculated diffusion coefficient is also saved as an at-node field.

>>> diffusion_coef is grid.at_node["kd"]
True

property k_land: float#: Return the diffusion coefficient use for land.

property load0: float#: Return the sediment load entering the profile.

property plain_slope: float#: Return the gradient of the delta plain.

run_one_step(dt: float) → None[source]#

Advance component one time step.

Parameters:: dt (float) – Time step to advance component by.

property sea_level: float#: Return sea level elevation.

property sediment_load: float#: Return the sediment load entering the profile.

property shelf_slope: float#: Return the slope of the shelf.

property shoreface_height: float#: Return the height of the shoreface.

property time: float#: Return the component’s current time.

property wave_base: float#: Return the depth of the wave base.

sequence.subsidence module#

Subside a SequenceModelGrid.

class sequence.subsidence.SubsidenceTimeSeries(*args, **kwds)[source]#

Bases: Component

A Landlab component that subsides a grid.

__init__(grid: SequenceModelGrid, filepath: PathLike, kind: str = 'linear')[source]#

Create a grid subsider from a time-series file.

Parameters:

grid (SequenceModelGrid) – A landlab grid.
filepath (os.PathLike) – Name of csv-formatted subsidence file.
kind (str, optional) – Kind of interpolation as a string (one of ‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’). Default is ‘linear’.

property filepath: str#: Return the path to the current subsidence file.

run_one_step(dt: float) → None[source]#

Update the component by a time step.

Parameters:: dt (float) – The time step to update the component by.

property subsidence_rate: ndarray[Any, dtype[_ScalarType_co]]#: Return the current subsidence rate.

property time: float#: Return the current component time.

Module contents#

A sequence-stratigraphic model of a 1D profile written with Landlab.