Class SEAMesh#

class sed.seaplex.SEAMesh(*args, **kwargs)[source]#

This class encapsulates all the functions related to sediment transport and deposition in the marine environment for river delivered sediments.

Note

For an overview of solution to nonlinear ODE and PDE problems, one might find the online book from Langtangen (2016) relevant.

Methods

seaChange()

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

Initialise

__init__(*args, **kwargs)

Initialisation of the SEAMesh class.

Public Methods

seaChange()

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

Private Methods

_globalCoastsTree(coastXYZ[, k_neighbors])

This function takes all local coastline points and computes locally the distance of all marine points to the coastline.

_distanceCoasts(data[, k_neighbors])

This function computes for every marine vertices the distance to the closest coastline.

_matOcean()

This function builds from neighbouring slopes the downstream directions in the marine environment.

_depMarineSystem(sedflux)

Setup matrix for the marine sediment deposition.

_distOcean(sedflux[, provFlux])

Based on the incoming marine volumes of sediment and maximum clinoforms slope we distribute locally sediments downslope.

_marineFineFraction(hl, sedFlux, fineFlux)

Dual-lithology (3c): set the per-node fine fraction of the marine deposit so fine concentrates in deep / distal water and coarse stays proximal (near the coast), conserving the marine fine volume.

_marineProvFraction(sedFlux)

In-model provenance (B2b, marine, lockstep): set each marine node's deposit source composition to the per-node mix that was actually routed there by _distOcean — depoProvFrac[node, c] = _marDepProv[node, c] / Σ_c _marDepProv[node, c] — so a source confined to one margin's rivers stays confined to its offshore depocenter instead of being smeared across the whole ocean (the previous domain-uniform average, see DESIGN_PROVENANCE.md §6).

Public functions#

SEAMesh.seaChange()[source]#

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

  • _distanceCoasts

  • _matOcean

  • _diffuseOcean

Private functions#

SEAMesh._globalCoastsTree(coastXYZ, k_neighbors=1)[source]#

This function takes all local coastline points and computes locally the distance of all marine points to the coastline.

Parameters:

  • coastXYZ – local coastline coordinates

  • k_neighbors – number of nodes to use when querying the kd-tree

SEAMesh._distanceCoasts(data, k_neighbors=1)[source]#

This function computes for every marine vertices the distance to the closest coastline. It calls the private function:

  • _globalCoastsTree

Important

The calculation takes advantage of the vtkContourFilter function from VTK library which is performed on the global VTK mesh. Once the coastlines have been extracted, the distances are obtained by querying a kd-tree (initialised with the coastal nodes) for marine vertices contained within each partition.

Parameters:

  • data – local elevation Numpy Array

  • k_neighbors – number of nodes to use when querying the kd-tree

SEAMesh._matOcean()[source]#

This function builds from neighbouring slopes the downstream directions in the marine environment. It calls a Fortran subroutine that locally computes for each vertice:

  • the indices of receivers (downstream) nodes depending on the desired number of flow directions (SFD to MFD).

  • the distances to the receivers based on mesh resolution.

  • the associated weights calculated based on the number of receivers and proportional to the slope.

From these downstream directions, a local ocean downstream matrix is computed.

SEAMesh._depMarineSystem(sedflux)[source]#

Setup matrix for the marine sediment deposition.

The upstream incoming sediment flux is obtained from the total river sediment flux \(\mathrm{Q_{t_i}}\) where:

\[\mathrm{Q_{t_i}^{t+\Delta t} - \sum_{ups} w_{i,j} Q_{t_u}^{t+\Delta t}}= \mathrm{(\eta_i^{t} - \eta_i^{t+\Delta t}) \frac{\Delta t}{\Omega_i}}\]

which gives:

\[\mathrm{Q_{s_i}} = \mathrm{Q_{t_i}} - \mathrm{(\eta_i^{t} - \eta_i^{t+\Delta t}) \frac{\Delta t}{\Omega_i}}\]

And the evolution of marine elevation is based on incoming sediment flux:

\[\mathrm{\frac{\eta_i^{t+\Delta t}-\eta_i^t}{\Delta t}} = \mathrm{G{_m} Q_{s_i} / \Omega_i}\]

This system of coupled equations is solved implicitly using PETSc by assembling the matrix and vectors using the nested submatrix and subvectors and by using the fieldsplit preconditioner combining two separate preconditioners for the collections of variables.

Parameters:

sedflux – incoming marine sediment volumes

Returns:

volDep (the deposited volume of the distributed sediments)

SEAMesh._distOcean(sedflux, provFlux=None)[source]#

Based on the incoming marine volumes of sediment and maximum clinoforms slope we distribute locally sediments downslope.

In-model provenance (B2b-marine, lockstep): when provFlux is given (the per-class incoming marine flux, shape (lpoints, provNb) with Σ_c provFlux == sedflux), each class’s sub-flux is routed through the same dMat1 cascade in lockstep with the total and deposited in the same proportion at every node (capacity marVol is shared, set by the total flux; provenance is a passive label, so the deposited and continuing fractions of a node’s arriving flux carry its arriving composition unchanged). This yields a spatially-resolved per-node deposited composition self._marDepProv (shape (lpoints, provNb), Σ_c == vdep exactly) — the source that actually drained to each offshore cell — instead of the old domain-wide average. This is the marine analogue of the continental _moveDownstream lockstep.

Parameters:

  • sedflux – incoming marine sediment volumes

  • provFlux – optional per-class incoming marine flux (lpoints, provNb)

Returns:

vdep (the deposited volume of the distributed sediments)

SEAMesh._marineFineFraction(hl, sedFlux, fineFlux)[source]#

Dual-lithology (3c): set the per-node fine fraction of the marine deposit so fine concentrates in deep / distal water and coarse stays proximal (near the coast), conserving the marine fine volume.

Composition only — the marine deposit geometry (already in self.tmp after _distOcean/_depMarineSystem/_diffuseOcean) is NOT modified, so elevations/flow are untouched. This is the subaqueous analogue of sedplex._pitFineFraction: the lower-Gmar “fines deposit less readily / travel farther” behaviour is expressed as fine biased toward the deeper deposits rather than re-routed.

Mechanism:

  • Domain marine fine fraction ff_mar = Σ(fineFlux) / Σ(sedFlux) — the fine that actually reached the sea after the continental cascade (fineFlux is the post-cascade fine input, sedFlux the total input, both zero outside the marine sinks). With the fine-enriched overspill in the cascade, this is genuinely enriched relative to the upstream-eroded composition.

  • Water depth d = max(sealevel − hl, 0) is the distal/deep proxy.

  • Fine fraction biased ∝ d, renormalised to the deposit-weighted mean depth, so Σ(mdep·larea·ffrac) == ff_mar·Σ(mdep·larea).

Parameters:

  • hl – pre-deposition local elevation

  • sedFlux – marine input sediment volume per node (m^3)

  • fineFlux – marine input fine sediment volume per node (m^3)

SEAMesh._marineProvFraction(sedFlux)[source]#

In-model provenance (B2b, marine, lockstep): set each marine node’s deposit source composition to the per-node mix that was actually routed there by _distOcean — depoProvFrac[node, c] = _marDepProv[node, c] / Σ_c _marDepProv[node, c] — so a source confined to one margin’s rivers stays confined to its offshore depocenter instead of being smeared across the whole ocean (the previous domain-uniform average, see DESIGN_PROVENANCE.md §6). Provenance is a passive label, so deposition does not sort by class — the lockstep split is exactly proportional, hence Σ_c depoProvFrac == 1 and stratP still partitions stratH.

Fallback: _diffuseOcean may give a marine node a thin deposit by lateral diffusion from neighbours after the routing pass, so it has deposit thickness but no routed composition (Σ_c _marDepProv == 0 there). Those few nodes get the domain-wide basin-delivered mix Σ(provFrac·sedFlux)/Σ sedFlux — the old uniform value — which keeps them sensible and conserving without affecting the spatially-resolved bulk.

Parameters:

sedFlux – marine input sediment volume per node (m^3).