ocean_vdiff_config_t Derived Type

   type :: ocean_vdiff_config_t
      !! Backward-Euler vertical-friction solver knobs (`&ocean_vdiff_nml`).
      !! The implicit folds default `.false.` (explicit wind-stress apply);
      !! MOM6's face treatment (`hvel_mom6` + `bbl_glue`) defaults ON.
      logical :: implicit_stress = .false.
         !! Fold the surface wind stress into the vdiff surface (k=nz) RHS
         !! row (Neumann top-BC) instead of the explicit pre-solve add.
      logical :: accel_visc_rem = .false.
         !! RETIRED (PR-3, 2026-10): setting `.true.` is a fail-loud
         !! `validate_config` error.  This attenuated the slow EXPLICIT
         !! accelerations by the per-layer viscous remnant —
         !! `u = u_entry + visc_rem·(u_applied − u_entry)` after the
         !! CorAdv/PGF/hvisc/drag applies, before the BT correction — but
         !! PR-3's audit found NO MOM6 state-update equivalent:
         !! `btstep_layer_accel` and the split-explicit RK2 corrector's
         !! `up`/`vp` update both apply the depth-mean barotropic acceleration
         !! `u_accel_bt` UNIFORMLY across every layer, with no `visc_rem`
         !! weight anywhere in that path.  The real MOM6 mechanisms that
         !! multiply a velocity correction by `visc_rem` are
         !! `&ocean_bt_nml renorm_visc_rem` (continuity `u_cor = u +
         !! du·visc_rem`) and `rescale_strong_drag`.  The underlying
         !! kernels (`accel_visc_rem_snapshot`/`accel_visc_rem_reweight`
         !! in `rdb_ocean_dyn.F90`) and their direct unit tests
         !! (`tests/test_ocean_accel_visc_rem.F90`) are untouched — only
         !! the configure-time path to reach them from a namelist is
         !! refused.
      logical :: implicit_drag = .false.
         !! Fold the bottom drag into the vdiff bed-row diagonal (stress
         !! bottom-BC; the row is the face's first LIVE layer `k_bot_u/v`,
         !! `k = 1` off `z_fixed`) instead of the explicit pre-solve add.  Mutually
         !! exclusive with `&ocean_bdrag_nml implicit` (split-apply) and,
         !! without `bbl_glue`, incompatible with HBBL-distributed drag
         !! (`hbbl > 0`); both fail loud at configure.  Under `bbl_glue`
         !! the glue's piston replaces the fold.
      logical :: hvel_mom6 = .true.
         !! MOM6 momentum face thickness `hvel` for the vertical-friction
         !! solve (`vertvisc_coef`), with MOM6's arithmetic `h_shear` and
         !! the height-above-bed stack the BBL glue reads; the branch is
         !! `hvel_harmonic`.  DEFAULT ON (2026-10, with `bbl_glue`: MOM6's
         !! face treatment everywhere).  `.false.` ⇒ the historical
         !! arithmetic `h_u` / `face_thick` pair.
      real(wp) :: hbbl_visc = 10.0_wp
         !! MOM6 `HBBL` (m) for the `hvel_mom6` botfn blend without the
         !! BBL glue (under the glue each face's `bbl_thick` normalises the
         !! height above the bed), and the glue's HBBL when
         !! `&ocean_bdrag_nml hbbl = 0`.
      logical :: implicit_top_drag = .false.
         !! Fold the ICE-SHELF TOP drag into the vdiff `k = nz` DIAGONAL
         !! (`&ocean_tdrag_nml`'s mirror of `implicit_drag`) instead of
         !! the explicit pre-solve add.  The wind stress already owns
         !! that row's RHS; a drag is a diagonal term, so the two
         !! compose — but on a face the ice covers, the wind RHS is
         !! MASKED OFF here (there is no atmosphere under a shelf).
         !! That masking is now BELT AND BRACES and kept deliberately:
         !! the cover mask zeroes the `tau` pair at its source, so the
         !! factor multiplies zero, and it stays so the fold is correct
         !! STANDALONE if a later forcing path ever writes `tau` after
         !! the configure-time mask.
         !! Requires `&ocean_tdrag_nml enable`; mutually exclusive with
         !! `&ocean_tdrag_nml implicit` (both would damp the top layer)
         !! and with `htbl > 0` (the fold is one `k = nz` rate and
         !! cannot represent a distributed band).  All fail loud at
         !! configure.  Default `.false.` ⇒ bit-identical.
      logical :: hvel_harmonic = .false.
         !! Which MOM6 face-thickness branch `hvel_mom6` builds (MOM6
         !! `HARMONIC_VISC`).  `.false.` (MOM6's default): arithmetic face
         !! thickness, blended to harmonic near the bed for thin -> thick
         !! flow, height above the bed `max(zh, z_clear)` — every face layer
         !! below the shallower bed of a step sits inside the BBL.  `.true.`:
         !! the harmonic branch (harmonic thickness, upwind-arithmetic blend
         !! gated by `hvel_upwind`) — the historical `hvel_mom6`.
      logical :: bbl_glue = .true.
         !! DEFAULT ON (2026-10; `.false.` restores the explicit / folded
         !! bed drag).  MOM6 `BOTTOMDRAGLAW`: the bottom drag lives in the vertical
         !! viscosity.  MOM6 `set_viscous_BBL` computes, per face and once
         !! per outer step, the BBL viscosity `kv_bbl = sqrt(CDRAG)·u*·
         !! bbl_thick` (`u*` from the HBBL-mean speed under the quadratic
         !! law, `sqrt(CDRAG)·DRAG_BG_VEL` under the linear one) and the
         !! rotation/stratification-limited `bbl_thick` (KW99); the
         !! momentum solve then raises the interface viscosity by
         !! `(kv_bbl − KV)·botfn` near the bed and takes the bed row as the
         !! piston `kv_bbl/(min(hvel₁/2, bbl_thick))`, which REPLACES the
         !! explicit / folded bed drag.  The drag law and its parameters
         !! come from `&ocean_bdrag_nml` (`form`, `cd` or `r`, `hbbl` —
         !! falling back to `hbbl_visc` when 0 — `bg_vel`,
         !! `bbl_thick_min`); with no drag configured the glue is inert.
         !! Requires `hvel_mom6` (fail-loud at configure).
      real(wp) :: bbl_piston = 3.0e-4_wp
         !! Historical constant BBL piston velocity (m/s), `kv_bbl =
         !! bbl_piston·hbbl_visc`: read only by a hand-built vdiff slot
         !! without the per-face BBL (unit tests).  A configured run's glue
         !! takes its drag from `&ocean_bdrag_nml`.
      logical :: hvel_upwind = .true.
         !! Near-bed upwind (arithmetic-donor) blend in the `hvel_mom6`
         !! face-thickness build.  Default `.true.` = MOM6 parity /
         !! bit-identical hvel_mom6 behaviour.  `.false.` = pure harmonic
         !! hvel — the blend's u-sign test flip-flops on roundoff
         !! velocities at (near-)rest and collapses the BBL glue at
         !! whichever faces flip (PGF_BUG.md §9.8).
   end type ocean_vdiff_config_t