has_biharmonic_backstop Function

public pure function has_biharmonic_backstop(nu_4, smag_ah, smag_bi_const, code, c_leith_bi, nu_4_bg) result(ok)

.true. iff the configured biharmonic dispatch will produce a STRICTLY POSITIVE dissipation coefficient somewhere. Drives the configure-time fail-loud guard requiring a biharmonic backstop when MEKE backscatter is on — the negative harmonic backscatter feeds a grid-scale mode that only a positive biharmonic can dissipate.

Two failure modes closed here (both silently passed the guard before this signature): (1) a flow-aware closure SELECTED with a zero coefficient (c_leith_bi default 0, smag_bi_const user-settable to 0) still fills nu4_face ≡ 0 — not a backstop unless the nu_4_bg floor clamp is positive; (2) the flow-aware face path, when engaged, returns before the scalar nu_4 arm in ocean_horizontal_viscosity_compute_tendencies (the dispatch at rdb_ocean_horizontal_viscosity.F90:470-497), so nu_4 > 0 is NOT a backstop whenever the face path is taken — only the scalar arm’s own nu_4 counts, and only when the face path is not.

Binding contract — keep in lock-step with the biharmonic dispatch in ocean_horizontal_viscosity_compute_tendencies (rdb_ocean_horizontal_viscosity.F90:470-497): any PR that adds a biharmonic arm to that dispatch must extend this predicate in the same commit.

Arguments

Type IntentOptional Attributes Name
real(kind=wp), intent(in) :: nu_4
logical, intent(in) :: smag_ah
real(kind=wp), intent(in) :: smag_bi_const
integer, intent(in) :: code
real(kind=wp), intent(in) :: c_leith_bi
real(kind=wp), intent(in) :: nu_4_bg

Return Value logical


Called by

proc~~has_biharmonic_backstop~~CalledByGraph proc~has_biharmonic_backstop has_biharmonic_backstop proc~validate_config validate_config proc~validate_config->proc~has_biharmonic_backstop proc~build_pending_handle build_pending_handle proc~build_pending_handle->proc~validate_config proc~rdb_ocean_create_from_string rdb_ocean_create_from_string proc~rdb_ocean_create_from_string->proc~build_pending_handle proc~rdb_ocean_create_pending rdb_ocean_create_pending proc~rdb_ocean_create_pending->proc~build_pending_handle

Variables

Type Visibility Attributes Name Initial
real(kind=wp), private :: coeff
logical, private :: face_path

Source Code

   pure function has_biharmonic_backstop(nu_4, smag_ah, smag_bi_const, code, &
                                         c_leith_bi, nu_4_bg) result(ok)
      !! `.true.` iff the configured biharmonic dispatch will produce a
      !! STRICTLY POSITIVE dissipation coefficient somewhere.  Drives the
      !! configure-time fail-loud guard requiring a biharmonic backstop when
      !! MEKE backscatter is on — the negative harmonic backscatter feeds a
      !! grid-scale mode that only a positive biharmonic can dissipate.
      !!
      !! Two failure modes closed here (both silently passed the guard
      !! before this signature): (1) a flow-aware closure SELECTED with a
      !! zero coefficient (`c_leith_bi` default 0, `smag_bi_const`
      !! user-settable to 0) still fills `nu4_face ≡ 0` — not a backstop
      !! unless the `nu_4_bg` floor clamp is positive; (2) the flow-aware
      !! face path, when engaged, `return`s before the scalar `nu_4` arm in
      !! `ocean_horizontal_viscosity_compute_tendencies` (the dispatch at
      !! `rdb_ocean_horizontal_viscosity.F90:470-497`), so `nu_4 > 0` is
      !! NOT a backstop whenever the face path is taken — only the scalar
      !! arm's own `nu_4` counts, and only when the face path is not.
      !!
      !! **Binding contract — keep in lock-step with the biharmonic
      !! dispatch** in `ocean_horizontal_viscosity_compute_tendencies`
      !! (`rdb_ocean_horizontal_viscosity.F90:470-497`): any PR that adds a
      !! biharmonic arm to that dispatch must extend this predicate in the
      !! same commit.
      real(wp), intent(in) :: nu_4
      logical, intent(in) :: smag_ah
      real(wp), intent(in) :: smag_bi_const
      integer, intent(in) :: code
      real(wp), intent(in) :: c_leith_bi
      real(wp), intent(in) :: nu_4_bg
      logical :: ok
      logical :: face_path
      real(wp) :: coeff

      ! Mirrors the dispatch guard at :470-473: the flow-aware face path
      ! is taken (and the scalar nu_4 arm below it never runs) whenever
      ! smag_ah is active or the closure is Leith-biharmonic. These two
      ! are already mutually exclusive at configure time
      ! (lateral_closure_conflicts_smag_ah).
      face_path = smag_ah .or. (code == LMIX_LEITH_BIHARM)
      if (face_path) then
         ! nu4_face = clamp(coeff * scale * |strain|, nu_4_bg, nu4_max)
         ! (rdb_ocean_lateral_mix.F90:599/643/743/781) — a positive
         ! coefficient OR a positive floor clamp both guarantee
         ! nu4_face > 0 somewhere.
         coeff = merge(smag_bi_const, c_leith_bi, smag_ah)
         ok = (coeff > 0.0_wp) .or. (nu_4_bg > 0.0_wp)
      else
         ok = (nu_4 > 0.0_wp)
      end if
   end function has_biharmonic_backstop