Optional Extensions

Optional physics extensions for specialised applications not needed for core turbulence modelling.

Seagrass

Seagrass canopy drag and turbulence generation. Treats seagrass canopies as Lagrangian tracers that advect with the horizontal current or rest at their excursion limits and exert friction on the mean flow (Verduin and Backhaus, 2000). Turbulence generation due to seagrass friction is included as an extra TKE production term.

Seagrass canopy parameterisation — translation of seagrass.F90.

Treats seagrass canopies as Lagrangian tracers that either advect passively with the horizontal current speed or rest at their excursion limits and thereby exert friction on the mean flow (Verduin and Backhaus, 2000). Turbulence generation due to seagrass friction is included as an extra production term in the TKE balance.

Public interface: init_seagrass(), post_init_seagrass(), do_seagrass(), end_seagrass(), SeagrassState, MISS_VALUE.

Original FORTRAN authors: Hans Burchard, Karsten Bolding.

class pygotm.extras.seagrass.seagrass.SeagrassState(seagrass_calc=False, method=0, grassfile='seagrass.dat', alpha=0.0, grassind=0, grassn=0, xx=None, yy=None, xxP=None, exc=None, vfric=None, grassz=None, excur=None, grassfric=None)[source]

Bases: object

State for the optional seagrass drag parameterization.

Parameters:
seagrass_calc: bool = False
method: int = 0
grassfile: str = 'seagrass.dat'
alpha: float = 0.0
grassind: int = 0
grassn: int = 0
xx: ndarray | None = None
yy: ndarray | None = None
xxP: ndarray | None = None
exc: ndarray | None = None
vfric: ndarray | None = None
grassz: ndarray | None = None
excur: ndarray | None = None
grassfric: ndarray | None = None
pygotm.extras.seagrass.seagrass.do_seagrass(state, nlev, dt, u, v, h, drag, xP)[source]

Update the sea grass model.

Return type:

None

Parameters:
pygotm.extras.seagrass.seagrass.end_seagrass(state)[source]

Release seagrass work arrays.

Return type:

None

Parameters:

state (SeagrassState)

pygotm.extras.seagrass.seagrass.init_seagrass(state, *, method=0, grassfile='seagrass.dat', alpha=0.0)[source]

Read seagrass configuration from a YAML-equivalent mapping.

Fortran-parity note: seagrass.F90’s init_seagrass contains a long- standing bug — the activation check uses an uninitialized local variable i instead of the freshly read method:

if (i .ne. 0) seagrass_calc = .true.

Under typical gfortran builds the stack value of i is zero, so seagrass_calc is never enabled regardless of YAML configuration, and the seagrass kernel becomes a no-op. The reference NetCDFs were produced with that behaviour, so for bit-for-bit parity we mirror it here by leaving state.seagrass_calc at its initial value (False).

Return type:

None

Parameters:
pygotm.extras.seagrass.seagrass.post_init_seagrass(state, nlev, h)[source]

Allocate and initialise seagrass memory from file.

Return type:

None

Parameters:

Sediment

Suspended sediment transport, settling, and resuspension. Solves the concentration transport equation with settling advection and turbulent diffusion. Supports Eulerian (default) and Lagrangian particle methods.

Suspended sediment transport — translation of sediment.F90.

Computes the transport of suspended sediment concentration \(C\) via:

\[\frac{\partial C}{\partial t} + \frac{\partial w_s C}{\partial z} = \mathcal{D}_C\]

where \(w_s < 0\) is the sinking speed and \(\mathcal{D}_C\) is turbulent diffusion with diffusivity equal to the turbulent momentum diffusivity \(\nu_t\). Two transport methods are supported:

  • sedi_eulerian = True (default) — settling advection via adv_center() plus diffusion via diff_center().

  • sedi_eulerian = False — Lagrangian particle tracking via lagrange().

Settling velocity is computed from grain properties using the Zanke (1977) formula in settling_velocity_zanke(). Bottom boundary conditions are either no-flux (NoFlux) or the Smith–McLean (SmithMcLean) resuspension formula.

Public interface: init_sediment(), do_sediment(), sediment_eulerian(), sediment_lagrangian(), settling_velocity_zanke(), save_sediment(), end_sediment(), SedimentState, NoFlux, SmithMcLean.

Original FORTRAN authors: Hans Burchard, Karsten Bolding.

class pygotm.extras.sediment.sediment.SedimentState(sedi_calc=False, sedi_eulerian=True, sedi_dens=False, rho_sed=2650.0, size=6.25e-05, init_conc=0.0001, adv_method=1, cnpar=0.5, sedi_method=1, z0b_method=1, sedi_npar=10000, take_mean=True, C=None, wc=None, Cobs=None, Qsour=None, Lsour=None, RelaxT=None, zp=None, zi=None, DiffBcup=1, DiffBcdw=1, AdvBcup=1, AdvBcdw=1, DiffCup=0.0, DiffCdw=0.0, AdvCup=0.0, AdvCdw=0.0, ustarc=0.0, gs=0.0, za=0.0, au=None, bu=None, cu=None, du=None, ru=None, qu=None, adv_cu=None, _lagrange_count=0, _lagrange_set_c_zero=True)[source]

Bases: object

State for suspended sediment transport.

Parameters:
sedi_calc: bool = False
sedi_eulerian: bool = True
sedi_dens: bool = False
rho_sed: float = 2650.0
size: float = 6.25e-05
init_conc: float = 0.0001
adv_method: int = 1
cnpar: float = 0.5
sedi_method: int = 1
z0b_method: int = 1
sedi_npar: int = 10000
take_mean: bool = True
C: ndarray | None = None
wc: ndarray | None = None
Cobs: ndarray | None = None
Qsour: ndarray | None = None
Lsour: ndarray | None = None
RelaxT: ndarray | None = None
zp: ndarray | None = None
zi: ndarray | None = None
DiffBcup: int = 1
DiffBcdw: int = 1
AdvBcup: int = 1
AdvBcdw: int = 1
DiffCup: float = 0.0
DiffCdw: float = 0.0
AdvCup: float = 0.0
AdvCdw: float = 0.0
ustarc: float = 0.0
gs: float = 0.0
za: float = 0.0
au: ndarray | None = None
bu: ndarray | None = None
cu: ndarray | None = None
du: ndarray | None = None
ru: ndarray | None = None
qu: ndarray | None = None
adv_cu: ndarray | None = None
pygotm.extras.sediment.sediment.do_sediment(state, nlev, dt, h, num, *, u_taub=0.0, kappa=0.4, z0b=0.01)[source]

Dispatch one sediment update.

Return type:

None

Parameters:
pygotm.extras.sediment.sediment.end_sediment(state)[source]

Release sediment arrays.

Return type:

None

Parameters:

state (SedimentState)

pygotm.extras.sediment.sediment.init_sediment(state, nlev, gravity, rho0, *, depth=1.0, h=None, sedi_calc=None, sedi_eulerian=None, sedi_method=None)[source]

Initialise sediment vectors and derived parameters.

Return type:

None

Parameters:
pygotm.extras.sediment.sediment.save_sediment(state, path=None)[source]

Return or optionally write the current sediment concentration.

Return type:

ndarray

Parameters:
pygotm.extras.sediment.sediment.sediment_eulerian(state, nlev, dt, h, num, *, u_taub=0.0, kappa=0.4, z0b=0.01, w_adv_method=0, grid_method=0)[source]

Eulerian sediment transport update.

Return type:

None

Parameters:
pygotm.extras.sediment.sediment.sediment_lagrangian(state, nlev, dt, zlev, nuh, h, *, write_results=False, rng=None)[source]

Lagrangian sediment particle update.

Return type:

None

Parameters:
pygotm.extras.sediment.sediment.settling_velocity_zanke(size, gravity, rho_sed, rho0, *, avmolu=1.3e-06)[source]

Return Zanke fall velocity and reduced gravity.

Return type:

tuple[float, float]

Parameters: