bathymetry_normalise_sign Subroutine

public subroutine bathymetry_normalise_sign(b, convention, ierr)

In-place sign-normalise b (any shape — interior or full array, the caller decides what it passes) to Roundabout’s positive-down depth convention, then validate on the NORMALISED array: zero wet cells (b > LAND_DEPTH_THRESHOLD) is rejected as OCEAN_STATUS_ERR_BATHYMETRY_SIGN, naming the median depth and the convention that was requested, so the caller can see at a glance that the OTHER convention was probably meant. NOT a “no negatives” check (see module docstring) — a majority-negative but non-empty wet fraction is accepted (legal under wet/dry).

Arguments

Type IntentOptional Attributes Name
real(kind=wp), intent(inout) :: b(:,:)
integer, intent(in) :: convention

One of BATHY_CONVENTION_DEPTH_POSITIVE_DOWN / _HEIGHT_POSITIVE_UP. No default — any other value is OCEAN_STATUS_ERR_SETUP.
integer, intent(out), optional :: ierr

Non-zero (OCEAN_STATUS_ERR_SETUP on an unrecognised convention, OCEAN_STATUS_ERR_BATHYMETRY_SIGN on a zero-wet-cell array) when present; absent behaves as today (error stop).

Calls

proc~~bathymetry_normalise_sign~~CallsGraph proc~bathymetry_normalise_sign bathymetry_normalise_sign proc~bathymetry_median bathymetry_median proc~bathymetry_normalise_sign->proc~bathymetry_median proc~fail fail proc~bathymetry_normalise_sign->proc~fail to_string to_string proc~bathymetry_normalise_sign->to_string proc~sort_real sort_real proc~bathymetry_median->proc~sort_real error error proc~fail->error proc~error_ring_push error_ring_push proc~fail->proc~error_ring_push

Called by

proc~~bathymetry_normalise_sign~~CalledByGraph proc~bathymetry_normalise_sign bathymetry_normalise_sign proc~ocean_state_seed_from_cfg ocean_state_seed_from_cfg proc~ocean_state_seed_from_cfg->proc~bathymetry_normalise_sign proc~engine_setup engine_setup proc~engine_setup->proc~ocean_state_seed_from_cfg proc~complete_ocean_create complete_ocean_create proc~complete_ocean_create->proc~engine_setup proc~driver_run_ocean driver_run_ocean proc~driver_run_ocean->proc~engine_setup proc~driver_validate driver_validate proc~driver_validate->proc~engine_setup proc~driver_run driver_run proc~driver_run->proc~driver_run_ocean proc~rdb_ocean_create_finalize rdb_ocean_create_finalize proc~rdb_ocean_create_finalize->proc~complete_ocean_create proc~rdb_ocean_create_from_string rdb_ocean_create_from_string proc~rdb_ocean_create_from_string->proc~complete_ocean_create

Variables

Type Visibility Attributes Name Initial
real(kind=wp), private :: median_b
integer, private :: n_total
integer, private :: n_wet
real(kind=wp), private :: wet_frac

Source Code

   subroutine bathymetry_normalise_sign(b, convention, ierr)
      !! In-place sign-normalise `b` (any shape — interior or full array,
      !! the caller decides what it passes) to Roundabout's positive-down depth
      !! convention, then validate on the NORMALISED array: zero wet cells
      !! (`b > LAND_DEPTH_THRESHOLD`) is rejected as
      !! `OCEAN_STATUS_ERR_BATHYMETRY_SIGN`, naming the median depth and the
      !! convention that was requested, so the caller can see at a glance
      !! that the OTHER convention was probably meant. NOT a "no negatives"
      !! check (see module docstring) — a majority-negative but non-empty
      !! wet fraction is accepted (legal under wet/dry).
      real(wp), intent(inout) :: b(:, :)
      integer, intent(in) :: convention
         !! One of `BATHY_CONVENTION_DEPTH_POSITIVE_DOWN` /
         !! `_HEIGHT_POSITIVE_UP`. No default — any other value is
         !! `OCEAN_STATUS_ERR_SETUP`.
      integer, intent(out), optional :: ierr
         !! Non-zero (`OCEAN_STATUS_ERR_SETUP` on an unrecognised
         !! `convention`, `OCEAN_STATUS_ERR_BATHYMETRY_SIGN` on a
         !! zero-wet-cell array) when present; absent behaves as today
         !! (`error stop`).

      integer :: n_wet, n_total
      real(wp) :: wet_frac, median_b

      select case (convention)
      case (BATHY_CONVENTION_DEPTH_POSITIVE_DOWN)
         ! Already Roundabout's internal convention — no flip.
      case (BATHY_CONVENTION_HEIGHT_POSITIVE_UP)
         b = -b
      case default
         call fail("bathymetry_normalise_sign: unrecognised convention = "// &
                   to_string(convention)//" (must be BATHY_CONVENTION_DEPTH_POSITIVE_DOWN "// &
                   "= 1 or BATHY_CONVENTION_HEIGHT_POSITIVE_UP = 2 — this argument has no "// &
                   "default; see D6.2 in the Python API design notes)", ierr, OCEAN_STATUS_ERR_SETUP)
         return
      end select

      n_total = size(b)
      n_wet = count(b > LAND_DEPTH_THRESHOLD)
      wet_frac = 0.0_wp
      if (n_total > 0) wet_frac = real(n_wet, wp)/real(n_total, wp)

      if (n_wet == 0) then
         median_b = bathymetry_median(b)
         call fail("bathymetry_normalise_sign: zero wet cells after sign "// &
                   "normalisation (convention = "//to_string(convention)// &
                   ", median depth = "//to_string(median_b)// &
                   " m) — every cell reads as land, which produces a clean, "// &
                   "crash-free, entirely wrong quiescent run. Check the convention "// &
                   "argument; the OTHER convention is probably intended.", &
                   ierr, OCEAN_STATUS_ERR_BATHYMETRY_SIGN)
         return
      end if

      if (present(ierr)) ierr = OCEAN_STATUS_OK
   end subroutine bathymetry_normalise_sign