ocean_handle_t Derived Type

type, public :: ocean_handle_t

One ocean simulation: config + the P2.4 setup/step/teardown engine (god-state + grid + geothermal + bc_source + decomp + sea-ice params — rdb_ocean_engine). state/grid below are thin views onto engine%state/engine%grid kept ONLY so the P2 accessor bodies (h%state%..., h%grid%...) did not all need touching when this handle was rewired onto the shared engine (P2.4): state is POINTER-associated to engine%state right after engine_enter_data (stable for the handle’s lifetime — engine is a component of this heap-allocated, pointer-accessed handle, never copied/reallocated); grid is a ONE-TIME VALUE COPY of engine%grid right after engine_setup (safe because grid metadata is read-only after setup — no kernel ever mutates nx_phys/dx/… mid-run). The standalone sf slot from P1 is gone: engine_setup now fully configures engine%state%surface_flux from the namelist (P2.4 closes the “API surface flux is a separate, minimally-seeded object” gap), so rdb_ocean_get/set_*_flux read/write h%state%surface_flux directly, same as the driver.


Inherits

type~~ocean_handle_t~~InheritsGraph type~ocean_handle_t ocean_handle_t type~config_t config_t type~ocean_handle_t->type~config_t cfg type~hgrid_t hgrid_t type~ocean_handle_t->type~hgrid_t grid type~ocean_engine_t ocean_engine_t type~ocean_handle_t->type~ocean_engine_t engine type~ocean_state_t ocean_state_t type~ocean_handle_t->type~ocean_state_t state type~ocean_config_t ocean_config_t type~config_t->type~ocean_config_t ocean type~ocean_engine_t->type~hgrid_t grid type~ocean_engine_t->type~ocean_state_t state type~decomp_t decomp_t type~ocean_engine_t->type~decomp_t decomp type~ice_evp_params_t ice_evp_params_t type~ocean_engine_t->type~ice_evp_params_t evp_params type~ice_ic_params_t ice_ic_params_t type~ocean_engine_t->type~ice_ic_params_t ic_par type~ocean_boundary_data_constant_t ocean_boundary_data_constant_t type~ocean_engine_t->type~ocean_boundary_data_constant_t bc_source type~ocean_geothermal_t ocean_geothermal_t type~ocean_engine_t->type~ocean_geothermal_t geo type~barotropic_state_t barotropic_state_t type~ocean_state_t->type~barotropic_state_t barotropic type~continuity_t continuity_t type~ocean_state_t->type~continuity_t continuity type~coriolis_adv_t coriolis_adv_t type~ocean_state_t->type~coriolis_adv_t coriolis_adv type~eos_t eos_t type~ocean_state_t->type~eos_t eos type~multilayer_state_t multilayer_state_t type~ocean_state_t->type~multilayer_state_t multilayer type~ocean_bc_state_t ocean_bc_state_t type~ocean_state_t->type~ocean_bc_state_t bc type~ocean_bottom_drag_t ocean_bottom_drag_t type~ocean_state_t->type~ocean_bottom_drag_t bdrag type~ocean_cavity_flux_t ocean_cavity_flux_t type~ocean_state_t->type~ocean_cavity_flux_t cavity_flux type~ocean_data_forcing_t ocean_data_forcing_t type~ocean_state_t->type~ocean_data_forcing_t data_forcing type~ocean_data_input_t ocean_data_input_t type~ocean_state_t->type~ocean_data_input_t data_input type~ocean_diag_t ocean_diag_t type~ocean_state_t->type~ocean_diag_t diag type~ocean_dyn_t ocean_dyn_t type~ocean_state_t->type~ocean_dyn_t dyn type~ocean_epbl_t ocean_epbl_t type~ocean_state_t->type~ocean_epbl_t epbl type~ocean_gm_t ocean_gm_t type~ocean_state_t->type~ocean_gm_t gm type~ocean_hdiff_tracer_t ocean_hdiff_tracer_t type~ocean_state_t->type~ocean_hdiff_tracer_t hdiff_tracer type~ocean_horizontal_viscosity_t ocean_horizontal_viscosity_t type~ocean_state_t->type~ocean_horizontal_viscosity_t hvisc type~ocean_kappa_shear_t ocean_kappa_shear_t type~ocean_state_t->type~ocean_kappa_shear_t kshear type~ocean_lateral_mix_t ocean_lateral_mix_t type~ocean_state_t->type~ocean_lateral_mix_t lateral_mix type~ocean_meke_t ocean_meke_t type~ocean_state_t->type~ocean_meke_t meke type~ocean_metrics_t ocean_metrics_t type~ocean_state_t->type~ocean_metrics_t metrics type~ocean_mle_t ocean_mle_t type~ocean_state_t->type~ocean_mle_t mle type~ocean_obc_t ocean_obc_t type~ocean_state_t->type~ocean_obc_t obc type~ocean_p_surf_t ocean_p_surf_t type~ocean_state_t->type~ocean_p_surf_t p_surf type~ocean_pressure_force_t ocean_pressure_force_t type~ocean_state_t->type~ocean_pressure_force_t pressure_force type~ocean_redi_t ocean_redi_t type~ocean_state_t->type~ocean_redi_t redi type~ocean_restart_t ocean_restart_t type~ocean_state_t->type~ocean_restart_t restart type~ocean_sea_ice_t ocean_sea_ice_t type~ocean_state_t->type~ocean_sea_ice_t ice type~ocean_slopes_t ocean_slopes_t type~ocean_state_t->type~ocean_slopes_t slopes type~ocean_sponge_t ocean_sponge_t type~ocean_state_t->type~ocean_sponge_t sponge type~ocean_surface_flux_t ocean_surface_flux_t type~ocean_state_t->type~ocean_surface_flux_t surface_flux type~ocean_surface_stress_t ocean_surface_stress_t type~ocean_state_t->type~ocean_surface_stress_t surface_stress type~ocean_tidal_mixing_t ocean_tidal_mixing_t type~ocean_state_t->type~ocean_tidal_mixing_t vmix_tidal type~ocean_tides_t ocean_tides_t type~ocean_state_t->type~ocean_tides_t tides type~ocean_top_drag_t ocean_top_drag_t type~ocean_state_t->type~ocean_top_drag_t tdrag type~ocean_varmix_t ocean_varmix_t type~ocean_state_t->type~ocean_varmix_t varmix type~ocean_vcoord_t ocean_vcoord_t type~ocean_state_t->type~ocean_vcoord_t vcoord type~ocean_vdiff_t ocean_vdiff_t type~ocean_state_t->type~ocean_vdiff_t vdiff type~ocean_vertical_advection_t ocean_vertical_advection_t type~ocean_state_t->type~ocean_vertical_advection_t vert_advect type~ocean_vmix_t ocean_vmix_t type~ocean_state_t->type~ocean_vmix_t vmix type~ocean_wave_speed_t ocean_wave_speed_t type~ocean_state_t->type~ocean_wave_speed_t wavespeed type~scratch_3d_buffer_t scratch_3d_buffer_t type~continuity_t->type~scratch_3d_buffer_t h_face_left_x, h_face_right_x, h_face_left_y, h_face_right_y, mt_h_new, mt_grounded, pd_theta type~coriolis_adv_t->type~scratch_3d_buffer_t q_corner, ke_centre, pv_flux_x, pv_flux_y, mass_flux_u, mass_flux_v type~tracer_t tracer_t type~multilayer_state_t->type~tracer_t tracers type~ocean_bc_face_tag_t ocean_bc_face_tag_t type~ocean_bc_state_t->type~ocean_bc_face_tag_t west, east, south, north type~ocean_bottom_drag_t->type~scratch_3d_buffer_t du_drag, dv_drag, lambda_side_u, lambda_side_v type~ocean_boundary_data_source_t ocean_boundary_data_source_t type~ocean_boundary_data_constant_t->type~ocean_boundary_data_source_t type~ocean_cavity_const_t ocean_cavity_const_t type~ocean_cavity_flux_t->type~ocean_cavity_const_t const type~ocean_cavity_exchange_t ocean_cavity_exchange_t type~ocean_cavity_flux_t->type~ocean_cavity_exchange_t par type~ocean_cavity_ice_t ocean_cavity_ice_t type~ocean_cavity_flux_t->type~ocean_cavity_ice_t ice type~ocean_bc_config_t ocean_bc_config_t type~ocean_config_t->type~ocean_bc_config_t bc type~ocean_bdrag_config_t ocean_bdrag_config_t type~ocean_config_t->type~ocean_bdrag_config_t bdrag type~ocean_bt_config_t ocean_bt_config_t type~ocean_config_t->type~ocean_bt_config_t bt type~ocean_cavity_dyn_config_t ocean_cavity_dyn_config_t type~ocean_config_t->type~ocean_cavity_dyn_config_t cavity_dyn type~ocean_cavity_melt_config_t ocean_cavity_melt_config_t type~ocean_config_t->type~ocean_cavity_melt_config_t cavity_melt type~ocean_continuity_config_t ocean_continuity_config_t type~ocean_config_t->type~ocean_continuity_config_t continuity type~ocean_conv_config_t ocean_conv_config_t type~ocean_config_t->type~ocean_conv_config_t conv type~ocean_coriolis_config_t ocean_coriolis_config_t type~ocean_config_t->type~ocean_coriolis_config_t coriolis type~ocean_data_config_t ocean_data_config_t type~ocean_config_t->type~ocean_data_config_t data type~ocean_dataovr_config_t ocean_dataovr_config_t type~ocean_config_t->type~ocean_dataovr_config_t dataovr type~ocean_ddiff_config_t ocean_ddiff_config_t type~ocean_config_t->type~ocean_ddiff_config_t ddiff type~ocean_debug_config_t ocean_debug_config_t type~ocean_config_t->type~ocean_debug_config_t debug type~ocean_diag_config_t ocean_diag_config_t type~ocean_config_t->type~ocean_diag_config_t diag type~ocean_eos_config_t ocean_eos_config_t type~ocean_config_t->type~ocean_eos_config_t eos type~ocean_epbl_config_t ocean_epbl_config_t type~ocean_config_t->type~ocean_epbl_config_t epbl type~ocean_forcing_config_t ocean_forcing_config_t type~ocean_config_t->type~ocean_forcing_config_t forcing type~ocean_foxkemper_config_t ocean_foxkemper_config_t type~ocean_config_t->type~ocean_foxkemper_config_t foxkemper type~ocean_geothermal_config_t ocean_geothermal_config_t type~ocean_config_t->type~ocean_geothermal_config_t geothermal type~ocean_gm_config_t ocean_gm_config_t type~ocean_config_t->type~ocean_gm_config_t gm type~ocean_grid_config_t ocean_grid_config_t type~ocean_config_t->type~ocean_grid_config_t grid type~ocean_hdiff_config_t ocean_hdiff_config_t type~ocean_config_t->type~ocean_hdiff_config_t hdiff type~ocean_hvisc_config_t ocean_hvisc_config_t type~ocean_config_t->type~ocean_hvisc_config_t hvisc type~ocean_ic_config_t ocean_ic_config_t type~ocean_config_t->type~ocean_ic_config_t ic type~ocean_ice_config_t ocean_ice_config_t type~ocean_config_t->type~ocean_ice_config_t ice type~ocean_ice_ic_config_t ocean_ice_ic_config_t type~ocean_config_t->type~ocean_ice_ic_config_t ice_ic type~ocean_isopycnal_config_t ocean_isopycnal_config_t type~ocean_config_t->type~ocean_isopycnal_config_t isopycnal type~ocean_kappa_shear_config_t ocean_kappa_shear_config_t type~ocean_config_t->type~ocean_kappa_shear_config_t kshear type~ocean_meke_config_t ocean_meke_config_t type~ocean_config_t->type~ocean_meke_config_t meke type~ocean_mpi_config_t ocean_mpi_config_t type~ocean_config_t->type~ocean_mpi_config_t mpi type~ocean_pgf_config_t ocean_pgf_config_t type~ocean_config_t->type~ocean_pgf_config_t pgf type~ocean_porous_config_t ocean_porous_config_t type~ocean_config_t->type~ocean_porous_config_t porous type~ocean_psurf_config_t ocean_psurf_config_t type~ocean_config_t->type~ocean_psurf_config_t psurf type~ocean_redi_config_t ocean_redi_config_t type~ocean_config_t->type~ocean_redi_config_t redi type~ocean_restore_config_t ocean_restore_config_t type~ocean_config_t->type~ocean_restore_config_t restore type~ocean_slopes_config_t ocean_slopes_config_t type~ocean_config_t->type~ocean_slopes_config_t slopes type~ocean_sponge_config_t ocean_sponge_config_t type~ocean_config_t->type~ocean_sponge_config_t sponge type~ocean_tdrag_config_t ocean_tdrag_config_t type~ocean_config_t->type~ocean_tdrag_config_t tdrag type~ocean_thermo_config_t ocean_thermo_config_t type~ocean_config_t->type~ocean_thermo_config_t thermo type~ocean_tidal_mixing_config_t ocean_tidal_mixing_config_t type~ocean_config_t->type~ocean_tidal_mixing_config_t tidal_mixing type~ocean_tides_config_t ocean_tides_config_t type~ocean_config_t->type~ocean_tides_config_t tides type~ocean_topo_config_t ocean_topo_config_t type~ocean_config_t->type~ocean_topo_config_t topo type~ocean_tracers_config_t ocean_tracers_config_t type~ocean_config_t->type~ocean_tracers_config_t tracers type~ocean_varmix_config_t ocean_varmix_config_t type~ocean_config_t->type~ocean_varmix_config_t varmix type~ocean_vdiff_config_t ocean_vdiff_config_t type~ocean_config_t->type~ocean_vdiff_config_t vdiff type~ocean_vmix_config_t ocean_vmix_config_t type~ocean_config_t->type~ocean_vmix_config_t vmix type~ocean_wave_speed_config_t ocean_wave_speed_config_t type~ocean_config_t->type~ocean_wave_speed_config_t wavespeed type~ocean_wetdry_config_t ocean_wetdry_config_t type~ocean_config_t->type~ocean_wetdry_config_t wetdry type~ocean_zinit_config_t ocean_zinit_config_t type~ocean_config_t->type~ocean_zinit_config_t zinit type~data_input_field_t data_input_field_t type~ocean_data_input_t->type~data_input_field_t fields type~ocean_diag_t->type~hgrid_t grid type~diag_var_t diag_var_t type~ocean_diag_t->type~diag_var_t vars type~ocean_diag_nc_stream_t ocean_diag_nc_stream_t type~ocean_diag_t->type~ocean_diag_nc_stream_t nc_stream type~barotropic_workstate_t barotropic_workstate_t type~ocean_dyn_t->type~barotropic_workstate_t bt_work type~bt_wide_t bt_wide_t type~ocean_dyn_t->type~bt_wide_t bt_wide type~chksum_probe_t chksum_probe_t type~ocean_dyn_t->type~chksum_probe_t chksum_probe type~ke_probe_t ke_probe_t type~ocean_dyn_t->type~ke_probe_t ke_probe type~ocean_epbl_t->type~eos_t eos type~ocean_epbl_t->type~scratch_3d_buffer_t t0, s0, dpe_t, dpe_s, dcolht_t, dcolht_s, ctke_sw type~ocean_hdiff_tracer_t->type~scratch_3d_buffer_t T_centre, F_x_face, F_y_face type~ocean_horizontal_viscosity_t->type~scratch_3d_buffer_t du_visc, dv_visc, lap_u, lap_v, str_xx, str_xy, ah_t, ah_q type~ocean_kappa_shear_t->type~eos_t eos type~ocean_lateral_mix_t->type~scratch_3d_buffer_t vort_corner type~ocean_pressure_force_t->type~scratch_3d_buffer_t p_edge, z_centre, mont_M, rho_insitu, dpdx_face, dpdy_face, e_face, pa, intz_dpa, intx_pa, inty_pa, intx_dpa, inty_dpa, conc_T, conc_S, recon_T_t, recon_T_b, recon_S_t, recon_S_b type~evp_workspace_t evp_workspace_t type~ocean_sea_ice_t->type~evp_workspace_t evp_ws type~ocean_surface_stress_t->type~scratch_3d_buffer_t du_stress, dv_stress type~ocean_tidal_mixing_t->type~eos_t eos type~ocean_top_drag_t->type~scratch_3d_buffer_t du_drag, dv_drag type~ocean_vdiff_t->type~scratch_3d_buffer_t a_diag_t, b_diag_t, c_diag_t, rhs_t, a_diag_u, b_diag_u, c_diag_u, rhs_u, a_diag_v, b_diag_v, c_diag_v, rhs_v, kv_scalar_buf type~ocean_vertical_advection_t->type~scratch_3d_buffer_t F_face type~ocean_vmix_t->type~eos_t eos type~local_bt_cont_u_type local_BT_cont_u_type type~barotropic_workstate_t->type~local_bt_cont_u_type BTCL_u type~local_bt_cont_v_type local_BT_cont_v_type type~barotropic_workstate_t->type~local_bt_cont_v_type BTCL_v type~bt_wide_t->type~hgrid_t grid_w type~bt_wide_t->type~ocean_metrics_t metrics_w type~diag_mask_t diag_mask_t type~diag_var_t->type~diag_mask_t mask type~dataovr_entry_config_t dataovr_entry_config_t type~ocean_dataovr_config_t->type~dataovr_entry_config_t tau_x, tau_y, heat, evap, lprec, salt

Components

Type Visibility Attributes Name Initial
type(config_t), public :: cfg
logical, public :: device_mapped = .false.

True between ocean_state_enter_data and ocean_state_exit_data — tells destroy whether an exit_data pairing is owed.
type(ocean_engine_t), public :: engine

Not declared target — component attributes may not include target (illegal syntax) — but this needs none: h is only ever reached through a pointer variable (c_f_pointer off the opaque c_ptr handle), and a pointer’s entire pointee, subobjects included, is a valid pointer-association target for as long as that association persists. h%state => h%engine%state below relies on exactly this.
type(hgrid_t), public :: grid
logical, public :: host_is_current = .true.

P2 lazy-sync gate (docs/ocean_python_api_plan.md, 06_python_surface_design.md D3.4): true iff the HOST copies of the API-exposed prognostic/forcing arrays match the (possibly more advanced) device copies. rdb_ocean_step clears it unconditionally — it does not sync; rdb_ocean_refresh_host is the only thing that sets it back to true (via a leaf-array !$acc update self, never the aggregate state). Starts true: right after create() the host seed IS what enter_data copied to the device, so the two agree with nothing to refresh yet.
logical, public :: is_initialised = .false.

True once create() has completed device mapping. step/ get_* reject a handle that never got this far.
logical, public :: is_pending = .false.

P2.5: true from rdb_ocean_create_pending until rdb_ocean_create_finalize completes (success or failure — failure destroys the whole handle, per the F9 rollback contract). The rdb_ocean_stage_* geometry-injection calls require this; is_initialised (above) still gates every step/getter/setter exactly as before P2.5.
integer, public :: magic = 0
integer, public :: n_inner = 0

Barotropic fast-loop substep count, mirrored from engine%n_inner once at create — kept as a separate field only because the C ABI’s OWN stricter “n_inner must resolve to >= 1” contract (P1) is enforced here, not inside the shared engine_setup (which tolerates n_inner < 1 the same way driver_run_ocean does — see ocean_engine_t’s docstring).
type(ocean_state_t), public, pointer :: state => null()
real(kind=wp), public :: t_current = 0.0_wp

Source Code

   type :: ocean_handle_t
      !! One ocean simulation: config + the P2.4 setup/step/teardown
      !! engine (god-state + grid + geothermal + bc_source + decomp +
      !! sea-ice params — `rdb_ocean_engine`). `state`/`grid` below are
      !! thin views onto `engine%state`/`engine%grid` kept ONLY so the
      !! P2 accessor bodies (`h%state%...`, `h%grid%...`) did not all
      !! need touching when this handle was rewired onto the shared
      !! engine (P2.4): `state` is POINTER-associated to `engine%state`
      !! right after `engine_enter_data` (stable for the handle's
      !! lifetime — `engine` is a component of this heap-allocated,
      !! pointer-accessed handle, never copied/reallocated); `grid` is a
      !! ONE-TIME VALUE COPY of `engine%grid` right after `engine_setup`
      !! (safe because grid metadata is read-only after setup — no
      !! kernel ever mutates `nx_phys`/`dx`/... mid-run). The standalone
      !! `sf` slot from P1 is gone: `engine_setup` now fully configures
      !! `engine%state%surface_flux` from the namelist (P2.4 closes the
      !! "API surface flux is a separate, minimally-seeded object" gap),
      !! so `rdb_ocean_get/set_*_flux` read/write `h%state%surface_flux`
      !! directly, same as the driver.
      integer :: magic = 0
      type(config_t) :: cfg
      type(ocean_engine_t) :: engine
         !! Not declared `target` — component attributes may not include
         !! `target` (illegal syntax) — but this needs none: `h` is only
         !! ever reached through a `pointer` variable (`c_f_pointer` off
         !! the opaque `c_ptr` handle), and a pointer's entire pointee,
         !! subobjects included, is a valid pointer-association target
         !! for as long as that association persists. `h%state =>
         !! h%engine%state` below relies on exactly this.
      type(hgrid_t) :: grid
      type(ocean_state_t), pointer :: state => null()
      integer :: n_inner = 0
         !! Barotropic fast-loop substep count, mirrored from
         !! `engine%n_inner` once at create — kept as a separate field
         !! only because the C ABI's OWN stricter "n_inner must resolve
         !! to >= 1" contract (P1) is enforced here, not inside the
         !! shared `engine_setup` (which tolerates n_inner < 1 the same
         !! way `driver_run_ocean` does — see `ocean_engine_t`'s
         !! docstring).
      real(wp) :: t_current = 0.0_wp
      logical :: is_initialised = .false.
         !! True once create() has completed device mapping. `step`/
         !! `get_*` reject a handle that never got this far.
      logical :: is_pending = .false.
         !! P2.5: true from `rdb_ocean_create_pending` until
         !! `rdb_ocean_create_finalize` completes (success or failure —
         !! failure destroys the whole handle, per the F9 rollback
         !! contract). The `rdb_ocean_stage_*` geometry-injection calls
         !! require this; `is_initialised` (above) still gates every
         !! step/getter/setter exactly as before P2.5.
      logical :: device_mapped = .false.
         !! True between `ocean_state_enter_data` and `ocean_state_exit_data`
         !! — tells `destroy` whether an exit_data pairing is owed.
      logical :: host_is_current = .true.
         !! P2 lazy-sync gate (`docs/ocean_python_api_plan.md`,
         !! `06_python_surface_design.md` D3.4): true iff the HOST copies of
         !! the API-exposed prognostic/forcing arrays match the (possibly
         !! more advanced) device copies. `rdb_ocean_step` clears it
         !! unconditionally — it does not sync; `rdb_ocean_refresh_host`
         !! is the only thing that sets it back to true (via a leaf-array
         !! `!$acc update self`, never the aggregate `state`). Starts `true`:
         !! right after `create()` the host seed IS what `enter_data` copied
         !! to the device, so the two agree with nothing to refresh yet.
   end type ocean_handle_t