Dynamics: Pressure Gradients, Velocities, Waves, and Vertical Advection¶

These sections provide 3-D-effect forcing for the inherently 1-D column model: external and internal pressure gradients, prescribed velocity profiles, wave–current interactions, and vertical advection.

All scalar forcing fields in this section that use method: file read the Timeseries (Scalar) File format. Velocity profiles (velocities.u, velocities.v) use the Profile (Depth-Series) File format. See Input Data File Formats for complete specifications.

`mimic_3d`¶

Horizontal gradients that drive mean flow within the single column. Because pyGOTM is a 1-D model, horizontal advection and pressure gradients must be prescribed externally. The mimic_3d block allows these boundary-condition-like inputs to be provided as time series.

Parsed by pygotm.config.settings.Mimic3DSettings.

mimic_3d:
  ext_pressure:
    type: elevation
    dpdx:
      method: file
      file: ext_press_file.dat
      column: 2
    dpdy:
      method: file
      file: ext_press_file.dat
      column: 3
  int_pressure:
    type: none
  zeta:
    method: constant
    constant_value: 0.0

`mimic_3d.ext_pressure`¶

External (barotropic) pressure gradient.

Parsed by pygotm.config.settings.ExtPressureSettings.

`mimic_3d.ext_pressure.type`¶

Type	string
Valid values	`elevation`, `velocity`, `average_velocity`
Default	`"elevation"`

How the external pressure gradient is specified.

elevation: The gradient is expressed as a horizontal gradient in sea-surface elevation \(\partial\zeta/\partial x\) (dimensionless). The values provided in dpdx and dpdy are directly \(\partial\zeta/\partial x\) and \(\partial\zeta/\partial y\).
velocity: A reference velocity at a given height above the bottom is specified; the pressure gradient is inferred to maintain that velocity.
average_velocity: Vertically averaged (depth-mean) horizontal velocities are prescribed.

`mimic_3d.ext_pressure.dpdx`¶

External pressure gradient in the West–East direction.

Follows the extended InputSetting pattern (method: constant | tidal | file). When method: file: timeseries file (see Timeseries (Scalar) File). The conventional layout stores dpdx and dpdy as columns 2 and 3 of a shared three-column file (column 1 is often a placeholder or a third gradient quantity):

# Columns: placeholder   dpdx [m/m]   dpdy [m/m]
1976/04/06 06:00:00    0.00  -3.2010771E-06  -1.6297247E-06
1976/04/06 06:15:00    0.00  -2.9533401E-06  -2.1274509E-06

Default

0.0

The tidal extension adds a tidal sub-block for composing two harmonic constituents:

dpdx:
  method: tidal
  tidal:
    amp_1: 0.0        # amplitude of 1st harmonic
    phase_1: 0.0      # phase of 1st harmonic [s]
    amp_2: 0.0        # amplitude of 2nd harmonic
    phase_2: 0.0      # phase of 2nd harmonic [s]
  period_1: 44714.0   # period of 1st harmonic [s]  (≈ M2 tide)
  period_2: 43200.0   # period of 2nd harmonic [s]  (≈ S2 tide)

period_1 and period_2 are the tidal periods (seconds). Default values correspond to the M2 (44714 s ≈ 12.42 h) and S2 (43200 s = 12 h) tidal constituents.

`mimic_3d.ext_pressure.dpdy`¶

External pressure gradient in the South–North direction. Same structure as dpdx.

`mimic_3d.ext_pressure.h`¶

Reference height above the bottom (m) used when type: velocity.

Follows the InputSetting pattern.

`mimic_3d.int_pressure`¶

Internal (baroclinic) pressure gradient arising from horizontal density gradients.

Parsed by pygotm.config.settings.IntPressureSettings.

`mimic_3d.int_pressure.type`¶

Type	string
Valid values	`none`, `prescribed`, `plume`
Default	`"none"`

none: No internal pressure gradient.
prescribed: Horizontal T/S gradients are prescribed as time series and used to compute the baroclinic pressure gradient.
plume: Dense water inflow (bottom plume) configuration.

`mimic_3d.int_pressure.gradients`¶

Temperature and salinity gradient inputs. Only used when int_pressure.type: prescribed.

Each follows the InputSetting pattern:

dtdx / dtdy: Horizontal temperature gradients (°C m⁻¹).
dsdx / dsdy: Horizontal salinity gradients (psu m⁻¹).

`mimic_3d.int_pressure.plume`¶

Dense bottom-plume configuration. Only used when int_pressure.type: plume.

type: Plume type: bottom or surface. Default: "bottom".
x_slope / y_slope: Bottom slope in the West–East and South–North directions. Dimensionless. Default: 0.0.

`mimic_3d.int_pressure.t_adv`¶

Type	boolean
Default	`false`

Include temperature horizontal advection computed from the prescribed gradient.

`mimic_3d.int_pressure.s_adv`¶

Type	boolean
Default	`false`

Include salinity horizontal advection.

`mimic_3d.zeta`¶

Sea-surface elevation \(\zeta\) (m).

Follows the extended InputSetting pattern (method: constant | tidal | file). Used to set the free-surface height for pressure gradient calculations.

`velocities`¶

Prescribes and/or relaxes the horizontal velocity profiles.

Parsed by pygotm.config.settings.VelocitySettings.

velocities:
  u:
    method: off
  v:
    method: off
  relax:
    tau: 1.0e15
    ramp: 1.0e15

`velocities.u` / `velocities.v`¶

Observed or prescribed horizontal velocity profiles (m s⁻¹) in the West–East and South–North directions.

Follows the InputSetting pattern (method: off | constant | file).

When method: file, a time series of full-depth profiles is read. These are used to nudge the model velocities via relax.tau, or to initialise the velocity field. The file uses the Profile (Depth-Series) File format. Both components can share one file using column: 1 for u and column: 2 for v:

# Horizontal velocity profiles [m/s]: col1=u (W-E), col2=v (S-N)
# Header: timestamp   N_levels   up_down
2001/08/30 07:00:00   22   2
   -6.00000   0.00000   0.12000
   -8.00000   0.01000   0.11000
  -10.00000   0.02000   0.09000
  ...
  -50.00000  -0.14000  -0.14000

YAML reference:

velocities:
  u: { method: file, file: velprof.dat, column: 1 }
  v: { method: file, file: velprof.dat, column: 2 }

`velocities.relax.tau`¶

Units	s
Default	`1.0e15` (no relaxation)

Relaxation time scale for nudging model velocities toward the prescribed profile.

`velocities.relax.ramp`¶

Units	s
Default	`1.0e15`

Duration of a linear ramp-up period at the start of the simulation over which the relaxation strength increases from 0 to its full value.

`waves`¶

Surface wave parameters for Stokes drift and wave–turbulence interaction.

Parsed by pygotm.config.settings.WaveSettings.

Note

Full Stokes drift integration (Craig–Banner TKE injection) is [unsupported in compiled runtime] in the current release. The stokes_active flag in pygotm.gotm.runtime_params.RuntimeParams must be non-zero to activate this path.

waves:
  Hs:
    method: constant
    constant_value: 0.0
  Tz:
    method: constant
    constant_value: 1.0
  phiw:
    method: constant
    constant_value: 0.0

`waves.Hs`¶

Significant wave height.

Follows the InputSetting pattern.

Units	m
Default	`0.0`

Used to compute the Stokes drift profile and wave-breaking TKE injection.

`waves.Tz`¶

Zero-crossing wave period (peak period).

Follows the InputSetting pattern.

Units	s
Default	`0.0`

Together with Hs, determines the amplitude and depth penetration of the Stokes drift velocity profile.

`waves.phiw`¶

Wave propagation direction (meteorological convention: direction from).

Follows the InputSetting pattern.

Units	degrees
Default	`0.0`

Used to project Stokes drift into U and V components.

`w`¶

Vertical (upwelling/downwelling) velocity prescribed at a given height.

Parsed by pygotm.config.settings.VerticalVelocitySettings.

w:
  max:
    method: off
  height:
    method: constant
    constant_value: 0.0
  adv_discr: p2_pdm

`w.max`¶

Maximum vertical velocity magnitude.

Follows the InputSetting pattern (method: off | constant | file).

Units	m s⁻¹
Default	`0.0` (off)

When active, a vertical velocity profile is imposed following a Gaussian distribution centred at w.height. The vertical velocity drives temperature and salinity advection via the scheme selected by adv_discr.

When method: file, w.max and w.height can share a single two-column timeseries file (see Timeseries (Scalar) File):

# Columns: w_max [m/s]   height_above_bottom [m]
2001/08/30 16:24:09   -0.268241e+02   -0.277951e-04
2001/08/30 16:34:09   -0.268404e+02   -0.265529e-04

YAML reference:

w:
  max:    { method: file, file: vertvel.dat, column: 1 }
  height: { method: file, file: vertvel.dat, column: 2 }

`w.height`¶

Height above the bottom where the prescribed vertical velocity is maximum.

Follows the InputSetting pattern.

Units	m
Default	`0.0`

`w.adv_discr`¶

Type	string
Valid values	`p2_pdm`, `upstream`, `p2`, `superbee`, `muscl`
Default	`"p2_pdm"`

Advection discretisation scheme for the vertical tracer advection terms.

p2_pdm: Second-order piecewise parabolic scheme with the Positive-Definite Monotone (PDM) limiter. Recommended default; balances accuracy and monotonicity.
upstream: First-order upwind scheme. Diffusive but robust.
p2: Second-order parabolic scheme without limiter.
superbee / muscl: TVD (Total Variation Diminishing) schemes for steep gradients.

Implemented in pygotm.util.adv_center.

Dynamics: Pressure Gradients, Velocities, Waves, and Vertical Advection¶

mimic_3d¶

mimic_3d.ext_pressure¶

mimic_3d.ext_pressure.type¶

mimic_3d.ext_pressure.dpdx¶

mimic_3d.ext_pressure.dpdy¶

mimic_3d.ext_pressure.h¶

mimic_3d.int_pressure¶

mimic_3d.int_pressure.type¶

mimic_3d.int_pressure.gradients¶

mimic_3d.int_pressure.plume¶

mimic_3d.int_pressure.t_adv¶

mimic_3d.int_pressure.s_adv¶

mimic_3d.zeta¶

velocities¶

velocities.u / velocities.v¶

velocities.relax.tau¶

velocities.relax.ramp¶

waves¶

waves.Hs¶

waves.Tz¶

waves.phiw¶

w¶

w.max¶

w.height¶

w.adv_discr¶

`mimic_3d`¶

`mimic_3d.ext_pressure`¶

`mimic_3d.ext_pressure.type`¶

`mimic_3d.ext_pressure.dpdx`¶

`mimic_3d.ext_pressure.dpdy`¶

`mimic_3d.ext_pressure.h`¶

`mimic_3d.int_pressure`¶

`mimic_3d.int_pressure.type`¶

`mimic_3d.int_pressure.gradients`¶

`mimic_3d.int_pressure.plume`¶

`mimic_3d.int_pressure.t_adv`¶

`mimic_3d.int_pressure.s_adv`¶

`mimic_3d.zeta`¶

`velocities`¶

`velocities.u` / `velocities.v`¶

`velocities.relax.tau`¶

`velocities.relax.ramp`¶

`waves`¶

`waves.Hs`¶

`waves.Tz`¶

`waves.phiw`¶

`w`¶

`w.max`¶

`w.height`¶

`w.adv_discr`¶