Class SEDMesh#

class sed.sedplex.SEDMesh(*args, **kwargs)[source]#

This class encapsulates all the functions related to sediment transport and deposition in the continental domain.

Methods

sedChange()

This function is the main entry point to perform continental river-induced deposition.

Initialise

__init__(*args, **kwargs)

The initialisation of SEDMesh class consists in the declaration of several PETSc vectors.

Public Methods

sedChange()

This function is the main entry point to perform continental river-induced deposition.

Private Methods

_getSedFlux()

This function computes sediment flux in cubic metres per year from incoming rivers.

_moveDownstream(vSed, vSedF, step[, vSedP])

In cases where river sediment fluxes drain into depressions, they might fill the sink completely and overspill or be deposited in it.

_distributeSediment(hl)

This function finds the continental sediment volumes to distribute downstream (down to the ocean or sinks) for a given iteration.

_bottomUpDelta(hl, depo, pit_select)

Compute per-node deposit thickness for the pits flagged in pit_select using the bottom-up rule: lake surface stays horizontal at the level matching the deposited volume.

_spillCoords()

Globally-known XYZ coordinates of each pit's spill point.

_addPitMicroTilt(delta, pit_select)

Tilt each lake's deposited surface very slightly toward its spill point so the next flow-routing step doesn't have to deal with large flat areas.

_identifyPitInlets()

Identify cells that receive flow from a donor outside their own pit.

_diffuseLargePit(hl, depo, pit_select)

Deposit sediment in large/deep partially-filled pits.

_pitFineFraction(hl, delta, depo)

Dual-lithology (3b + fine-enriched overspill): set the per-node fine fraction of the continental pit/lake deposit so fine settles toward the depocenter and coarse builds the inlet/margins, conserving each pit's RETAINED fine volume.

_pitProvFraction(depo)

Provenance (B2b-pit): set the per-node source composition of the continental pit/lake deposit to each pit's RETAINED provenance mix, tracked through the overspill cascade by _moveDownstream.

_updateSinks(hl)

Update depression elevations based on incoming sediment volumes.

Public functions#

SEDMesh.sedChange()[source]#

This function is the main entry point to perform continental river-induced deposition. It calls the private functions:

  • _getSedFlux

  • _distributeSediment

  • _updateSinks

Private functions#

SEDMesh._getSedFlux()[source]#

This function computes sediment flux in cubic metres per year from incoming rivers. Like for the computation of the flow discharge and erosion rates, the sediment flux is solved by an implicit time integration method, the matrix system is the one obtained from the receiver distributions over the unfilled elevation mesh for the flow discharge (fMat).

The PETSc scalable linear equations solvers (KSP) is used here again with an iterative method obtained from PETSc Richardson solver (richardson) with block Jacobian preconditioning (bjacobi).

SEDMesh._moveDownstream(vSed, vSedF, step, vSedP=None)[source]#

In cases where river sediment fluxes drain into depressions, they might fill the sink completely and overspill or be deposited in it. This function computes the excess of sediment (if any) able to flow dowstream.

Important

The excess sediment volume is then added to the downstream sediment flux (vSed).

Dual lithology: the fine sub-volume vSedF is threaded in lockstep so overspill is fine-enriched — coarse settles first (retained up to the pit capacity), so a filled pit keeps a coarse-enriched deposit and the excess that overspills carries the remaining fine. The fine overspill is routed through the same flow matrix as the total (linear); the per-pit retained fine is accumulated in self._pitRetFine (used by _pitFineFraction) and the routed-downstream fine is returned in self._routedFine.

Parameters:

  • vSed – excess sediment volume array (total)

  • vSedF – excess fine sediment volume array (ignored when single)

  • step – downstream distribution step

Returns:

(excess, sedFilled_changed) where excess is True when sediment still needs to be redistributed, and sedFilled_changed is True when at least one pit saturated this iteration (signalling that the flow direction matrix should be rebuilt next call).

SEDMesh._distributeSediment(hl)[source]#

This function finds the continental sediment volumes to distribute downstream (down to the ocean or sinks) for a given iteration.

Parameters:

hl – local elevation prior deposition

SEDMesh._bottomUpDelta(hl, depo, pit_select)[source]#

Compute per-node deposit thickness for the pits flagged in pit_select using the bottom-up rule: lake surface stays horizontal at the level matching the deposited volume.

Parameters:

  • hl – local elevation prior deposition

  • depo – per-pit deposited volume (m^3)

  • pit_select – boolean array (num_pits) selecting which pits to fill

Returns:

per-node delta thickness (m); zero outside selected pits

SEDMesh._spillCoords()[source]#

Globally-known XYZ coordinates of each pit’s spill point.

Each rank knows its own spill points (those it owns); we publish the full table by zero-filling the others and Allreducing with SUM.

Returns:

(num_pits, 3) numpy array of spill coordinates

SEDMesh._addPitMicroTilt(delta, pit_select)[source]#

Tilt each lake’s deposited surface very slightly toward its spill point so the next flow-routing step doesn’t have to deal with large flat areas. The tilt is mass-conservative per pit (mean removed) and small enough (~1e-6 m/m) to be physically negligible.

Parameters:

  • delta – per-node deposit thickness from bottom-up fill

  • pit_select – boolean array (num_pits) selecting tilted pits

Returns:

tilted delta (same shape, mass preserved per pit)

SEDMesh._identifyPitInlets()[source]#

Identify cells that receive flow from a donor outside their own pit. These are the natural inlets where upstream sediment enters a depression, used as the initial-pile location for the non-linear diffusion path in large/deep partially-filled pits.

Returns:

boolean array (lpoints) marking inlet cells (owned cells only)

SEDMesh._diffuseLargePit(hl, depo, pit_select)[source]#

Deposit sediment in large/deep partially-filled pits.

The initial deposit shape is a bathymetric bottom-up fill (most of the volume distributed proportional to water depth below the target lake level) combined with a small inlet bias that seeds delta progradation. Marine-style non-linear diffusion then refines the surface, and a per-pit rescale at the end enforces exact volume conservation.

Parameters:

  • hl – local elevation prior deposition

  • depo – per-pit deposited volume

  • pit_select – boolean array (num_pits) selecting diffused pits

Returns:

per-node delta thickness (m)

SEDMesh._pitFineFraction(hl, delta, depo)[source]#

Dual-lithology (3b + fine-enriched overspill): set the per-node fine fraction of the continental pit/lake deposit so fine settles toward the depocenter and coarse builds the inlet/margins, conserving each pit’s RETAINED fine volume.

Composition only — the deposit geometry delta is NOT modified, so model dynamics (elevations, flow) are untouched; the worst case of a bug here is a wrong recorded composition, caught by the per-fraction invariant + fine-conservation tests.

Mechanism:

  • Per-pit retained fine fraction ff_pit = _pitRetFine / depo — the fine actually kept in the pit under coarse-settles-first (accumulated through the cascade by _moveDownstream); a pit that overspilled keeps a coarse-enriched deposit, the excess fine having travelled downstream.

  • Bathymetric depth d = max(lFill − hl, 0) is the depocenter proxy (deep at the centre, shallow at the rim/inlet — independent of where the deposit piled).

  • Fine fraction is biased ∝ d and renormalised to the deposit-weighted mean depth, so Σ(delta·larea·ffrac) == ff_pit·Σ(delta·larea) == the fine volume retained in the pit.

Parameters:

  • hl – pre-deposition local elevation

  • delta – per-node continental deposit thickness (local)

  • depo – per-pit deposited (retained) volume (m^3)

SEDMesh._pitProvFraction(depo)[source]#

Provenance (B2b-pit): set the per-node source composition of the continental pit/lake deposit to each pit’s RETAINED provenance mix, tracked through the overspill cascade by _moveDownstream.

Unlike the dual-lithology fine fraction there is no depocenter bias — provenance is a passive label, so every node in a pit records the same retained mix. _pitRetProv[pit, :] sums over classes to the pit’s retained volume depo[pit] (the cascade conserves each class), so the per-pit fractions _pitRetProv / depo sum to 1 and depoProvFrac stays summed-to-1 — stratP partitions stratH machine-exactly.

Composition only — the deposit geometry is untouched.

Parameters:

depo – per-pit deposited (retained) volume (m^3)

SEDMesh._updateSinks(hl)[source]#

Update depression elevations based on incoming sediment volumes.

Three-path algorithm depending on the pit’s fill state and size:

  1. Pit fully filled (depo >= pitVolume) – bottom-up to lFill (rim).

  2. Partial fill, pit small/shallow (volume below nl_pit_volume OR depth below nl_pit_depth) – bottom-up + per-pit micro-tilt toward the spill point so the lake surface is not perfectly flat (avoids large flats in the next flow-routing step).

  3. Partial fill, pit large AND deep – inlet-pile initial condition + marine-style non-linear diffusion. Produces emergent clinoform-like deposit progradation from the inlets.

Parameters:

hl – local elevation prior deposition