rdb_barotropic_workstate Module

Per-u-face flux-closure coefficients, shape (nx+1, ny). Allocated only when use_bt_cont_type = .true..

Per-v-face counterpart, shape (nx, ny+1).

Depth-mean of F_slow_u, shape (nx+1, ny). Used in the apply_bt_correction subtraction to clean the slow-apply’s bt projection out of every layer before installing the barotropic-substep bt mode.

F_bt_u minus the bt projection of the PGF, shape (nx+1, ny). Passed as the substep’s force_u so the substep’s own -G·∂η/∂x is the only bt PGF on the bt mode (else the slow + internal PGF stack to -2G·∂η/∂x, doubling the effective gravity-wave speed).

Depth-mean of F_slow_v, shape (nx, ny+1).

v counterpart, shape (nx, ny+1).

Per-face slow u-acceleration sum, shape (nx+1, ny, nz_ml).

Per-face slow v-acceleration sum, shape (nx, ny+1, nz_ml).

u-face visc_rem depth mean, shape (nx+1, ny).

v-face counterpart, shape (nx, ny+1).

MOM6 BEBT (default 0.1, as MOM6). Continuity flux uses ubt_trans = (1+bebt)·ubt^n − bebt·ubt^{n-1} — the BT_PROJECT_VELOCITY spelling. Because η is updated BEFORE the velocity in this loop, it is the same scheme as MOM6’s default (BT_PROJECT_VELOCITY = .false.: predictor η, then (1−bebt)·ubt^n + bebt·ubt^{n+1} transport): this loop’s η is MOM6’s eta_pred and the velocity sequence is identical, so the per-substep damping |λ|² = 1 − bebt·a² and the stability limit a ≤ 2/√(1+2·bebt) are MOM6’s. bebt = 0 ⇒ ubt_trans = ubt^n (neutral forward-backward Euler). Set via &ocean_bt_nml bebt.

Reference column thickness (m) at cell centres, shape (nx, ny). Constant for Eulerian-z; set by the driver from the initial multilayer state. Used as H in the linearized continuity ∂η/∂t = -div(H · u_bt).

&ocean_bt_nml bc_pgf_forcing (default .true., MOM6 parity). When .true. the fast forcing is F_bt_*_fast = F_bt + g_pf·∇(η_PF − η_seam) — the depth mean of the FULL slow PGF stays in the forcing and only the free-surface term the slow PGF itself carries (g_pf, pgf_free_surface_gravity: 0 for MONT/FV_LITE/FV_WRIGHT) at the stage-entry η it was evaluated on is removed. .false. = legacy F_bt − ⟨PGF⟩, which discarded the depth-mean baroclinic PGF. See set_fast_forcing_eta_pf.

When .true., apply_bt_correction adds the per-layer baroclinic-PGF retro-correction on top of the uniform / visc_rem-weighted Δu. Requires ocean_pgf_form = "fv_mom6" and the pbce / gtot_* / e_anom / eta_PF fields filled.

RETIRED-by-D1 (2026-10, PR-3 follow-up): when .true., apply_bt_correction weights the per-layer barotropic increment by visc_rem_*(k)/⟨visc_rem⟩_h instead of uniformly, biasing the Δu distribution toward layers LESS damped by vertical viscosity (&ocean_bt_nml correction_visc_rem, now fail-loud at configure outside direct test construction of cfg). MOM6’s split-explicit barotropic solver (Hallberg 1997; Hallberg & Adcroft 2009) gives every layer the SAME u_accel_bt via accel_layer_u (plus only the depth-mean-zero pbce baroclinic term) — NO visc_rem weight — so this fold has no MOM6 counterpart, and on a 1-degree Southern Ocean z* OPEN-step probe it is the mechanism that NaNs at step ~40 under bbl_glue (the weight ratio is unbounded when a column’s glue damping is uneven across layers; MOM6 never risks this because it never weights the fold at all). visc_rem_chain does NOT set this field — see bt_visc_rem_producer below for the (now decoupled) producer gate.

Barotropic SSH at cell centres, shape (nx, ny). Defined as sum_k(h_layer) - bt_H_ref.

Per-substep η^{n+1} scratch, shape (nx, ny). Jacobi buffer so the face-thickness reads in Pass 1 stay race- free under the Fortran 2018 do concurrent semantics.

MOM6 wt_u parity for the BT forcing assembly: weight the F_bt_u/v depth-mean (and the PGF-projection subtraction) by h_face·visc_rem(k) (&ocean_bt_nml forcing_visc_rem).

Barotropic kinetic energy at cell centres, shape (nx, ny).

PR-2 (bt-rem-from-av-rem, &ocean_bt_nml bt_rem_from_visc_rem): compute_bt_rem_from_visc_rem builds bt_rem_u/v from av_rem_u/v (:= Σ_k frhat_k·visc_rem_k, frhat_k the face layer fraction derive_bt_from_layers uses) instead of the linear-piston law — MOM6’s barotropic solver. Mutually exclusive with bt_substep_drag (double-counted bed drag) and bt_halo > 0 (checked in validate_config).

u-face damping factor, shape (nx+1, ny).

v-face counterpart, shape (nx, ny+1).

MOM6 continuity-inversion parity (SPEC S2b): γ-weighted transport-matching renormaliser (&ocean_bt_nml renorm_visc_rem) — visc_rem_u/v forwarded into the slow continuity so u_cor = u + du·γ_k and the fluxes carry the same weights.

MOM6 RESCALE_STRONG_DRAG. Requires bt_strong_drag.

MOM6 BT_STRONG_DRAG: the rational- approximation bt_rem form. Requires bt_rem_from_visc_rem.

When .true., driver fills bt_rem_u/v with the multiplicative BT-substep drag factor that damps bt_ubt / bt_vbt each inner step. Default off ⇒ bt_rem ≡ 1, multiplication is a no-op (bit-identical).

Depth-mean u at east faces, shape (nx+1, ny).

u-face velocity from the previous substep, shape (nx+1, ny).

Time-mean east-face transport (m²/s), shape (nx+1, ny). uhbt_sum / n_inner.

Depth-mean v at north faces, shape (nx, ny+1).

v-face counterpart, shape (nx, ny+1).

Time-mean north-face transport (m²/s), shape (nx, ny+1).

D1 follow-up: gates the visc_rem PRODUCER fused into vmix_apply_in_stage’s momentum vdiff solve (MOM6 vertvisc_remnant, sharing vertvisc_coef’s SAME coupling coefficients a_u — includes kv_bbl/the BBL glue and the Rayleigh/bed piston whenever the glue or implicit_drag folds them into the matrix; the producer itself does NOT require implicit_drag — see vdiff_apply_momentum’s do_remnant). Decoupled from bt_correction_visc_rem: the producer must run whenever ANY consumer needs visc_rem_u/v fresh — bt_forcing_visc_rem (wt_u), bt_renorm_visc_rem (continuity u_cor), or bt_rem_from_visc_rem (av_rem/bt_rem) — not only the (retired) weighted BT-correction fold. Set to the OR of all four (including the legacy bt_correction_visc_rem, so a test that constructs cfg directly and sets it still gets a live producer) by configure_ocean_bt.

Barotropic relative vorticity at corners, shape (nx+1, ny+1).

u-face Coriolis/advection reference velocity, shape (nx+1, ny).

v-face counterpart, shape (nx, ny+1).

SSH anomaly relative to eta_PF, shape (nx, ny). e_anom = 0.5·(bt_eta_end + bt_eta) − eta_PF.

Snapshot of bt_eta taken just before the slow PGF is computed (= η the PGF “saw”). Updated each RK2 stage. Shape (nx, ny).

&ocean_bt_nml frhat_scheme (rdb_constants::FRHAT_*, parse_frhat_scheme; default FRHAT_ARITHMETIC, bit-identical to the pre-port tree). FRHAT_HYBRID ports MOM6’s btcalc HVEL_SCHEME=HYBRID face-thickness closure into every barotropic depth mean that reads a layer’s face thickness: derive_bt_from_ layers, face_depth_mean_u/v, face_depth_mean_rem_u/v, apply_bt_correction’s open/visc_rem folds, and (through face_depth_mean_u/v) compute_bt_rem_from_visc_rem’s av_rem. Read on the host before each do concurrent (a plain scalar dispatch flag, like bt_strong_drag — never dereferenced from bt_work INSIDE a kernel, so it needs no enter_data map of its own). See rdb_barotropic_coupling::frhat_h_face_step (src/shared_module_utilities/rdb_frhat_face.inc) for the bottom-up port of MOM6’s e_u/D_shallow_u sweep, and derive_bt_from_layers’s docstring for the one site (use_upstream_h_face) that has no MOM6 frhat counterpart and is deliberately left untouched.

Acceleration in the barotropic-substep η-gradient PGF (a = -g_bt · ∇η), m/s². Defaults to full gravity (bit-identical for Mont/FV/coastal). For OPGF_VARIANT_GPRIME the driver overrides with pgf%gprime_gfs so the BT mode runs at the reduced-gravity speed sqrt(g_FS · H); else the gprime knobs net out to full g.

Depth-weighted column average of pbce evaluated at the east face of cell (i, j), shape (nx, ny). Built by compute_gtot_faces.

North-face counterpart, shape (nx, ny).

South-face counterpart, shape (nx, ny).

West-face counterpart, shape (nx, ny).

East-face upstream-h column sum (m), shape (nx+1, ny). Σ_k h_layer(upstream_cell, j, k) where the per-layer upstream selection follows u_face_x_layer sign. Allocated only when use_upstream_h_face = .true..

North-face counterpart, shape (nx, ny+1). Built from v_face_y_layer sign.

True between init and destroy. Tracks GPU device attachment too — prefer to allocated(...) which only sees the host pointer.

u-face piston velocity r_H [m/s], shape (nx+1, ny). Static after configure_ocean_wave_drag; allocated only when lwd_enable = .true..

v-face counterpart, shape (nx, ny+1).

Driver writes from &ocean_bt_nml wave_drag.

Per-layer pressure-anomaly gravity coefficient (m/s²), shape (nx, ny, nz_ml). Column-mean equals gtot_face. Built by compute_pbce; requires the FV_MOM6 PGF.

Live (ζ_bt+f)·v − ∇KE in the fast loop (default, bit-identical). .false. = MOM6-parity planetary-only substeps; the subtract_fast_cor_ref reference reduces to f·v̄ to match. See &ocean_bt_nml substep_zeta_ke.

Depth-mean u at the start of the outer step, shape (nx+1, ny). Used in the recombine step: u^{n+1}(k) = u^*(k) + (⟨u_bt⟩ - ubt_at_n - dt·F_bt_u)

East-face transport accumulator, shape (nx+1, ny).

Driver writes from the ocean_use_bt_cont_type namelist.

Driver writes from the ocean_bt_upstream_h_face namelist.

v counterpart, shape (nx, ny+1).

North-face transport accumulator, shape (nx, ny+1).

u-face per-layer visc_rem, shape (nx+1, ny, nz_ml).

v-face per-layer visc_rem, shape (nx, ny+1, nz_ml).

Total-depth dry threshold (m); cells with D < wd_dry_depth are dynamically dry. From &ocean_wetdry_nml dry_depth.

East-face provisional-then-limited volume flux (m³/s), shape (nx+1, ny). Pass A fills h_up · ubt_trans · dy_cu with UPWIND face thickness + the FROUDE_CAP thin-face velocity guard; Pass C scales it by min(theta_L, theta_R) in place.

North-face counterpart, shape (nx, ny+1).

Dynamic u-face open mask (1 = open, 0 = blocked), shape (nx+1, ny). Bed-blocking (C-grid analogue of the coastal hydrostatic reconstruction): a face into a dry cell is a wall unless the wet side’s surface stands above the dry side’s bed elevation + dry_depth. Rewetting starts from rest at the face. Consumed by the substep Pass 2 gate and by the driver’s layer-velocity masking.

v-face counterpart, shape (nx, ny+1).

Hysteresis re-wet threshold (m), > wd_dry_depth. From &ocean_wetdry_nml rewet_depth.

Per-cell positive-definite outflow limiter factor in [0, 1], shape (nx, ny). theta = min(1, available_volume / substep_outflow_volume); each face flux is scaled by min(theta_L, theta_R), which guarantees D >= 0 every substep (a cell drains at most what it holds). Deep water ⇒ theta ≡ 1 ⇒ the limiter is exactly inert.

Dynamic cell wet mask (1 = wet, 0 = dry), shape (nx, ny). PERSISTENT hysteresis state: updated every BT substep from D = bt_H_ref + bt_eta (wet above wd_rewet_depth, dry below wd_dry_depth, held in between). Seeded from the initial D at configure. Composes multiplicatively ON TOP of the static land masks (metrics%wet_u/v + zeroed metrics) — a static-land face can never be dynamically opened.

Driver writes from &ocean_wetdry_nml enable.

Effective face area for near-zero u with u < 0 [m].

Marginal face area in the saturated far-east-draw regime u < uBT_EE [m].

Effective face area for near-zero u with u > 0 [m].

Marginal face area in the saturated far-west-draw regime u > uBT_WW [m].

Negative velocity threshold beyond which find_uhbt switches to the saturated linear branch [m/s]. Must be ≤ 0.

Positive velocity threshold beyond which find_uhbt switches to the saturated linear branch [m/s]. Must be ≥ 0.

Mass transport at u = uBT_EE so the saturated branch matches the cubic [m²/s].

Mass transport at u = uBT_WW so the saturated branch matches the cubic [m²/s].

Cubic correction in the near-zero negative branch providing C¹ continuity at uBT_EE [s²/m].

Cubic correction in the near-zero positive branch providing C¹ continuity at uBT_WW [s²/m].

Negative (northward-draw) threshold [m/s]; must be ≤ 0.

Positive (southward-draw) threshold [m/s]; must be ≥ 0.