ocean_engine_t Derived Type

   type :: ocean_engine_t
      !! One ocean simulation's setup products, minus the caller-owned
      !! time-loop bookkeeping (t_current/n_steps/status-restart
      !! cadence/console_stats stay with the caller — see the module
      !! docstring).
      type(ocean_state_t) :: state
      type(hgrid_t) :: grid
      type(ocean_geothermal_t) :: geo
      type(ocean_boundary_data_constant_t) :: bc_source
         !! Boundary data source, refreshed once per outer step via
         !! `engine_step` -> `bc_source%update(t, state%bc)`.
      type(decomp_t) :: decomp
      type(ice_evp_params_t) :: evp_params
         !! Sea-ice EVP physical + numerical parameters, built once from
         !! `&ocean_ice_nml` at setup.
      type(ice_ic_params_t) :: ic_par
         !! Sea-ice initial-condition parameters, built once from
         !! `&ocean_ice_ic_nml` at setup.
      real(wp) :: cfl_vtol = 0.0_wp
         !! Console-stats MaxCFL vanish tolerance; 0 when off. Consumed
         !! by the caller's own `ocean_console_stats_report`, not by
         !! the engine itself.
      integer :: n_inner = 0
         !! Resolved barotropic fast-loop substep count
         !! (`cfg%ocean%bt%n_inner`, possibly auto-derived by
         !! `configure_ocean_bt_split`). `engine_step` dispatches to
         !! the split-RK2 path when `n_inner >= 1`, else the legacy
         !! unsplit `ocean_dyn_step` — mirrors `driver_run_ocean`'s own
         !! dispatch exactly; `engine_setup` does not itself require
         !! `n_inner >= 1` (a caller wanting that guarantee, such as
         !! the C ABI, checks it after `engine_setup` returns).
      logical :: diag_enabled = .false.
         !! Latched `cfg%ocean%diag%enabled` at setup, so `engine_step`
         !! can gate its `state%diag%step` call without needing `cfg`.
      logical :: device_mapped = .false.
         !! True between `engine_enter_data` and `engine_exit_data`.
      logical :: warm_restart = .false.
         !! Latched by `engine_setup`: the prognostic state came from a
         !! checkpoint, ghosts included, so no setup pass may re-derive its
         !! halo (see the init-time wrap in `engine_setup`).
      logical :: is_setup = .false.
         !! True once `engine_setup` has completed (host-side only;
         !! device mapping is a separate step).

      ! ---- P2.5: pre-create geometry injection staging ----
      ! Populated (by the C ABI's rdb_ocean_stage_* calls, or directly by
      ! a Fortran caller) BEFORE engine_setup runs, and consumed inside it —
      ! geometry must land before ocean_state_enter_data, exactly like
      ! passive-tracer registration (registry_locked closes at enter_data).
      ! Unset (not `allocated`/`.false.`) ⇒ engine_setup falls through to
      ! its ordinary namelist-driven path, byte-identical to before P2.5.
      real(wp), allocatable :: staged_bathymetry(:, :)
         !! Interior-sized (nx_phys, ny_phys) bathymetry, RAW in the
         !! caller's own sign convention (`staged_bathymetry_convention`).
         !! Consumed by `ocean_state_seed_from_cfg`'s `injected_b` argument,
         !! which overrides `cfg%ocean%topo%topo_config` entirely.
      integer :: staged_bathymetry_convention = 0
         !! `BATHY_CONVENTION_*` (`rdb_ocean_bathymetry_inject`). Only
         !! meaningful when `staged_bathymetry` is allocated — no default
         !! (D6.2: sign is the single most dangerous argument here).
      real(wp), allocatable :: staged_metrics_x(:, :), staged_metrics_y(:, :)
      real(wp), allocatable :: staged_metrics_dx(:, :), staged_metrics_dy(:, :)
      real(wp), allocatable :: staged_metrics_area(:, :)
         !! In-memory MOM6-style supergrid arrays
         !! (`metrics_assemble_from_supergrid_arrays`'s `sg_x/sg_y/sg_dx/
         !! sg_dy/sg_area`). When `staged_metrics_x` is allocated,
         !! `engine_setup` assembles metrics directly from these instead of
         !! dispatching on `cfg%ocean%grid%grid_config`.
      logical :: has_staged_topology = .false.
         !! True after a topology injection call; `staged_periodic_x/y`
         !! are only meaningful when this is true.
      logical :: staged_periodic_x = .false.
      logical :: staged_periodic_y = .false.
         !! Oceananigans-style "the grid owns periodicity": applied via
         !! `ocean_bc_state_set_topology` right after `configure_ocean_bc`,
         !! overriding whatever the namelist edge tags derived.
   end type ocean_engine_t