cavity_datum_impl Subroutine

   pure subroutine cavity_datum_impl(H_ref, b, z_draft, h_min, nx, ny)
      !! The BAROTROPIC DATUM: `bt_H_ref = b - z_draft` on a column that
      !! has water under the ice, and exactly `0` on one that is
      !! GROUNDED (`b - z_draft < h_min`, i.e. land by the very rule
      !! `seed_wet_mask_impl` applies).
      !!
      !! ### Why the grounded branch is not `b - z_draft`
      !!
      !! `bt_H_ref` is the reference WATER-COLUMN thickness.  A grounded
      !! column has no water column, and `b - z_draft` there is not a
      !! small thickness — it is NEGATIVE, by hundreds of metres for a
      !! real draft over a real bed.  Carrying that number had three
      !! consequences, none of them wanted:
      !!
      !!   * `bt_eta = sum h_layer - bt_H_ref` came out at `+|b -
      !!     z_draft|` on every grounded column — a phantom few-hundred-
      !!     metre free surface, masked out of the dynamics but visible
      !!     in `eta` min/max and in the `ssh` diagnostic;
      !!   * the ALE target on that column is built as
      !!     `(remap_h_ref + bt_eta)*dsig` with `remap_h_ref = total_h -
      !!     bt_eta`, so recovering the land column's `nz*H_VANISHED`
      !!     total meant CANCELLING two numbers of order the draft.  The
      !!     land thickness then jittered at `eps*z_draft` — round-off of
      !!     the wrong quantity — instead of sitting bit-stably at
      !!     `H_VANISHED`;
      !!   * it made a grounded column distinguishable from an ordinary
      !!     land column (`bt_H_ref = b`), for no dynamical reason: every
      !!     face metric on a land cell is zeroed, so nothing downstream
      !!     reads either value.
      !!
      !! Zero is the value that says "no water column" and the value that
      !! makes a grounded column arithmetically indistinguishable from
      !! the ordinary land it IS.
      !!
      !! ### Why this does not un-count the ice load
      !!
      !! Invariant (I) — the load reaching the barotropic mode exactly
      !! once, through the datum — is a statement about the BAROTROPIC
      !! MOMENTUM EQUATION, and that equation exists only on wet columns:
      !! on a land column every face metric is zero, `-G*grad(eta -
      !! eta_forcing)` is multiplied by nothing, and there is no load to
      !! count once or twice.  So (I) is asserted, by
      !! `cavity_datum_residual`, over the WET columns — which is where
      !! it is a physical statement rather than a bookkeeping one.
      !!
      !! Explicit-shape by the house rule; host-only (setup).
      integer, intent(in) :: nx, ny
      real(wp), intent(out) :: H_ref(nx, ny)
      real(wp), intent(in) :: b(nx, ny)
      real(wp), intent(in) :: z_draft(nx, ny)
      real(wp), intent(in) :: h_min
         !! `&ocean_cavity_dyn_nml h_min_cavity` (m, validated `> 0`) —
         !! the SAME grounding cutoff the wet-mask seed applies, passed
         !! rather than re-spelled so the two decisions cannot drift.
      real(wp) :: water
      integer :: i, j
      do j = 1, ny
         do i = 1, nx
            water = b(i, j) - z_draft(i, j)
            if (water < h_min) then
               H_ref(i, j) = 0.0_wp
            else
               H_ref(i, j) = water
            end if
         end do
      end do
   end subroutine cavity_datum_impl