ocean_bc_state_t Derived Type

   type :: ocean_bc_state_t
      !! Per-state OBC bookkeeping. Composed onto `ocean_state_t`; the
      !! dispatch helpers in `rdb_ocean_boundary` consume it via `class(*)`
      !! polymorphism, keeping kernels decoupled from the full state.
      logical :: is_init = .false.

      ! Per-edge tag (the load-bearing config).
      type(ocean_bc_face_tag_t) :: west, east, south, north

      ! Derived periodic flags — cached at init from the edge tags.
      ! Kernels read these two logicals (never re-derive from tags per step).
      logical :: periodic_x = .false.
         !! True when west and east edges are both OBC_PERIODIC.
      logical :: periodic_y = .false.
         !! True when south and north edges are both OBC_PERIODIC.
      logical :: north_fold = .false.
         !! True when THIS RANK applies the tripolar north fold: the north
         !! edge is OBC_TRIPOLAR_FOLD AND this subdomain owns the physical
         !! north edge (`has_north`).  Gates every fold exchange in the dyn
         !! loop + BT substep + continuity + setup wraps.  On a north-south
         !! split (px = 1, py > 1) only the north rank row folds; every other
         !! rank's north ghosts are an MPI seam the halo exchange fills, and
         !! folding them would overwrite that with a mirror of the rank's
         !! own tile.  (`ocean_bc_state_set_edges` re-derives it once the
         !! decomposition is known.)  Default .false. is bit-identical.
      logical :: has_west = .true.
         !! False when the west edge of this subdomain is an MPI seam (a
         !! neighbouring rank owns the cells beyond it), true when it is a
         !! physical domain edge.  Set from decomp%has_west at BC configure.
         !! Default .true. => single-rank / physical-edge behaviour
         !! (bit-identical to the pre-decomp code).
      logical :: has_east = .true.
         !! False when the east edge of this subdomain is an MPI seam; true
         !! when it is a physical domain edge.  (analogous to has_west)
      logical :: has_south = .true.
         !! False when the south edge of this subdomain is an MPI seam; true
         !! when it is a physical domain edge.  (analogous to has_west)
      logical :: has_north = .true.
         !! False when the north edge of this subdomain is an MPI seam; true
         !! when it is a physical domain edge.  (analogous to has_west)
      logical :: tidal_nodal = .false.
         !! Global switch (capability C3): apply the 18.6-yr nodal factor `f_c`
         !! + equilibrium/nodal phase `(V_c + u_c)` to the OBC tidal elevation
         !! forcing. Baked into the per-edge `tidal_fnodal`/`tidal_arg` at setup
         !! from the shared `&ocean_tides_nml` reference epoch. Cached into the
         !! barotropic substep like `periodic_x`. Default .false. ⇒ bit-identical
         !! legacy static-phase sum. When .true. the phase convention flips: the
         !! Greenwich phase `tidal_phase` becomes a LAG (subtracted).

      ! Persistent Chapman state — previous-timestep η at the wet side of each
      ! open edge. Per-cell `eta_old_<edge>(:)` arrays are declared for a
      ! future per-face adaptive Orlanski; currently unallocated (scalar
      ! Chapman on edge-mean η is used instead).
      real(wp), allocatable :: eta_old_west(:), eta_old_east(:)
      real(wp), allocatable :: eta_old_south(:), eta_old_north(:)

      ! Scalar Chapman state — one persistent η per edge, used by the
      ! barotropic substep's OBC_CHAPMAN dispatch when no per-cell array is
      ! supplied.  Updated at the end of each barotropic-substep call so the
      ! next call sees the radiation history.
      real(wp) :: eta_old_chapman_w = 0.0_wp
      real(wp) :: eta_old_chapman_e = 0.0_wp
      real(wp) :: eta_old_chapman_s = 0.0_wp
      real(wp) :: eta_old_chapman_n = 0.0_wp

      ! Open-edge tracer reservoirs. Allocated only when res_lscale_out > 0
      ! or res_lscale_in > 0 on an open-ish edge. Shape per edge:
      !   tres_west/east : (ny_total, nz_ml, n_tracers)
      !   tres_south/north : (nx_total, nz_ml, n_tracers)
      real(wp), allocatable :: tres_west(:, :, :)   !! West  reservoir concentration
      real(wp), allocatable :: tres_east(:, :, :)   !! East  reservoir concentration
      real(wp), allocatable :: tres_south(:, :, :)  !! South reservoir concentration
      real(wp), allocatable :: tres_north(:, :, :)  !! North reservoir concentration
      ! Cached length-scale knobs (m, default 0 = feature disabled).
      real(wp) :: res_lscale_out = 0.0_wp
         !! Outflow reservoir length scale (m).  0 ⇒ instantaneous outflow.
      real(wp) :: res_lscale_in = 0.0_wp
         !! Inflow reservoir length scale (m).  0 ⇒ instantaneous inflow.

      ! Per-layer Orlanski radiation state. Allocated when
      ! radiation_scheme == "orlanski" AND the edge radiates.
      ! Shapes: rx_*/u_prev_* west/east (ny_total, nz_ml), south/north
      ! (nx_total, nz_ml).
      ! rx:     running-mean nondimensional phase speed (grid cells / step).
      !         Not restart-registered ⇒ restarts cold.
      ! u_prev: first-interior-face normal velocity from the previous call
      !         (seeded from u_new on first call ⇒ rx = 0 cold start).
      real(wp), allocatable :: rx_west(:, :)     !! Running-mean rx, west  edge.
      real(wp), allocatable :: rx_east(:, :)     !! Running-mean rx, east  edge.
      real(wp), allocatable :: rx_south(:, :)    !! Running-mean rx, south edge.
      real(wp), allocatable :: rx_north(:, :)    !! Running-mean rx, north edge.
      real(wp), allocatable :: u_prev_west(:, :)  !! Prev-call u at first interior face, west.
      real(wp), allocatable :: u_prev_east(:, :)  !! Prev-call u at first interior face, east.
      real(wp), allocatable :: u_prev_south(:, :)  !! Prev-call v at first interior face, south.
      real(wp), allocatable :: u_prev_north(:, :)  !! Prev-call v at first interior face, north.

      ! Cached Orlanski / nudging / Flather knobs (set from config in configure_ocean_bc).
      integer  :: radiation_scheme = 0
         !! 0 = anomaly (default); 1 = orlanski.
      real(wp) :: orlanski_rx_max = 10.0_wp
         !! Upper clamp on the nondimensional phase speed (Orlanski 1976).
      real(wp) :: orlanski_gamma = 1.0_wp
         !! Running-mean weight.  1.0 = no running mean (instant rx).
      real(wp) :: nudge_tau_in = 0.0_wp
         !! Inflow nudging timescale (s, Marchesiello et al. 2001).  0 = off.
      real(wp) :: nudge_tau_out = 0.0_wp
         !! Outflow nudging timescale (s).  0 = off.

      ! Cached Flather-form knob.
      logical  :: use_full_flather = .false.
         !! .false. = legacy (default, bit-identical); .true. = full Flather
         !! (Flather 1976 half-characteristic form with exterior velocity).
      real(wp) :: ext_u_west = 0.0_wp  !! Exterior barotropic u, west  (m/s).
      real(wp) :: ext_u_east = 0.0_wp  !! Exterior barotropic u, east  (m/s).
      real(wp) :: ext_v_south = 0.0_wp  !! Exterior barotropic v, south (m/s).
      real(wp) :: ext_v_north = 0.0_wp  !! Exterior barotropic v, north (m/s).

      ! Per-step boundary data populated by the data source before each outer
      ! step. Shapes (ny[+1], nz_ml) or (nx[+1], nz_ml) per edge. Empty when
      ! all edges are WALL (the data source sizes them only when needed).
      real(wp), allocatable :: data_u_west(:, :), data_u_east(:, :)
      real(wp), allocatable :: data_v_south(:, :), data_v_north(:, :)
      real(wp), allocatable :: data_eta_west(:), data_eta_east(:)
      real(wp), allocatable :: data_eta_south(:), data_eta_north(:)
      real(wp), allocatable :: data_tracer_west(:, :, :), data_tracer_east(:, :, :)
      real(wp), allocatable :: data_tracer_south(:, :, :), data_tracer_north(:, :, :)
         !! (ny|nx, nz_ml, n_tracers).

      ! Cached grid metadata (avoids passing the grid through every helper).
      integer :: nx_total = 0, ny_total = 0
      integer :: nx_phys = 0, ny_phys = 0
      integer :: nghost = 0
      integer :: nz_ml = 0
      integer :: n_tracers = 0
   contains
      procedure, non_overridable :: bytes => ocean_bc_state_bytes
   end type ocean_bc_state_t