Derived Types

Depth-integrated state on an Arakawa C-grid (face-located velocities as continuity-PPM produces/consumes; cell-centred h-update by flux div).

Wide-halo shadow state for the barotropic fast loop.

One source/sink of a conserved quantity, populated by a physics kernel each step (adds dt·delta into per_cell) and drained at eval cadence (drain_contributors integrates per_cell·mask·dA over k into total_integrated, then zeroes per_cell). total_integrated is the cumulative RHS checked against LHS = current_total − values_init.

Config + one-shot header state. Lives on ocean_dyn_t; host-only (never device-mapped).

One field’s reduction bundle.

Container for all runtime simulation parameters

Cumulative (time-integrated, since t=0) budget terms that CLOSE the domain integral of each extensive quantity, so the reported Error is a true numerical-leak residual even with open boundaries + surface forcing. For quantity Q the residual is

Holds initial-snapshot values for relative-drift reporting. is_initialised flips on the first report call.

One registered (file, variable, destination-shape) triple. Array-of-derived-type element — NEVER dereference this from inside a do concurrent/device-kernel body (outer-shim + flat-impl rule); every place this type is touched below is a host-side registry walk that hands plain explicit-shape arrays to a pure flat-impl kernel.

One file-driven surface-forcing tag in &ocean_dataovr_nml. A blank file means “this tag is not file-driven” — the slot keeps whatever the configure-time scalar/formula path seeded.

Domain decomposition descriptor

One entry in the static catalog. Buffer layout is implicit in is_layered: layered → (nx, ny, nz_ml), 2D → (nx, ny, 1).

One parsed entry of the &ocean_diag_nml diags selection list. Produced by parse_diag_spec; consumed by register_default_diags (canonical-default overrides / skips) and the derived-diagnostic orchestrator (apply_diag_selection). Unset attributes carry sentinels so the consumer falls back to the canonical default.

Per-variable diagnostic record. Owned by ocean_diag_t.

An order-invariant fixed-point value: Sum_n v(n) * pr(n). The component is PUBLIC (unlike MOM6’s private EFP_type%v) so the comm facade (halo_allreduce_efp_list) can pack/unpack it without an accessor procedure – Roundabout splits the arithmetic module (here) from the collective (in src/comm/), so the layering requires v to be reachable from both. Tests asserting bit- identity compare v(:) directly, never the reconstructed real.

Persistent EVP-rheology scratch (SIS2 C-grid dynamics), hung off ocean_sea_ice_t as the evp_ws slot — eagerly allocated in the ice state’s init and GPU-mapped via enter_data, so it matches the rest of src/core/ocean/ (which carries ZERO module-level save allocatables — every kernel puts its scratch on a state DT). Replaces the retired rdb_ice_evp module-level save workspace + its lazy evp_workspace_ensure/ice_evp_cleanup lifecycle. Allocated / mapped ONLY when ocean_sea_ice_t%dynamics is on (the workspace is EVP-dynamics-only).

One north-row tile’s routing for the distributed fold. Entries of family f for peer p live at start(p,f)+1 .. start(p,f)+n(p,f) of the flat entry arrays (send and receive separately).

Persistent state for split begin/end halo exchange

EVP physical + numerical parameters (SIS2 SIS_C_dyn_CS subset). Passed intent(in) into the core; every scalar is hoisted to a local before the substep loop (no derived-type deref inside a do concurrent). Defaults + meanings mirror the &ocean_ice_nml block in rdb_config.F90 (the config is the authoritative knob set; keep the two in sync).

Sea-ice IC scalar knob bundle (mirrors ice_evp_params_t). Built ONCE from &ocean_ice_ic_nml via ice_ic_params_from_config; every field a plain scalar (no derived-type deref inside the host loop, same discipline as the EVP params — though this module never runs on-device at all).

Config + running state for the KE attribution meter. Lives on ocean_dyn_t; host-only (never device-mapped).

Per-u-face coefficient pack for the piecewise-cubic barotropic-continuity flux closure (find_uhbt four-branch transport function consumes these).

Meridional mirror of local_BT_cont_u_type — north-draw and south-draw branches around v=0.

Per-layer multilayer C-grid state.

Enum key: a string restricted to an allowed list, validated case-insensitively and assigned its canonical spelling.

A namelist group: a name, doc, growable key list, parse-state, and an optional cross-key validation callback.

Integer-valued key with optional [min,max] range validation.

Boxes a polymorphic key so groups can hold a growable array.

Abstract base for a single namelist key descriptor.

Logical-valued key.

Real-array key: accepts 1..size(tgt) values, fills from element 1, errors if more than size(tgt) values are given.

Real-valued key with optional [min,max] range validation.

The top-level schema: validated groups plus external (skipped) group names.

String key. Deferred-len char pointer associates with a fixed-len target and assumes its length; parsing errors if the parsed value is LONGER than len(tgt) (no silent truncation).

Boundary-condition configuration read from &ocean_bc_nml. All defaults reproduce a closed-wall run — existing nmls that omit this block are bit-identical to prior behaviour.

Configuration for one outer edge. Defaults yield a closed wall.

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.

Trivial backend: writes user-supplied constant scalars straight to bc%west/east/south/north’s clamped_* fields. For fixed-inflow tests and as a polymorphic-dispatch sanity check.

Polymorphic base. Concrete backends extend this and provide update + destroy.

Thermodynamic + turbulence constants. All SI.

Static ice-shelf cavity GEOMETRY (&ocean_cavity_dyn_nml, Phase 5.1). A prescribed, time-constant ice draft z_draft(i,j) (m, positive DOWN — the depth of the ice base below z = 0) is laid over the bed and absorbed into the barotropic DATUM:

Exchange-law selector + its parameters. ONE bundle for every law, so the dispatch is a single select case and a later do concurrent kernel can call it without reshaping. Members a given law does not read are ignored.

Ice-shelf basal-melt slot: the 2-D interface state plus the parameter bundles the kernel is called with.

Ice-side conduction selector + its parameter.

Ice-shelf basal-melt THERMODYNAMICS (&ocean_cavity_melt_nml, Phase 2b). The three-equation interface of Holland & Jenkins (1999), solved once per thermo step on every ice-covered column and delivered to the ocean as two OWNED surface-flux components (heat_cavity, salt_cavity).

Everything cavity_solve_melt returns: the interface state, the fluxes a coupling seam needs, and the solver diagnostics.

All ocean-path knobs, nested by concern. Parallel to the state composition pattern (ocean_state%dyn, %vcoord, etc.). Read-side: see the per-sub-nml blocks in read_config. Call-side: cfg%ocean%bt%use_cont_type, cfg%ocean%pgf%form, etc.

Brunt-Vaisala-triggered convective adjustment (&ocean_conv_nml, CVMix_conv-style). Where the interior N^2 < n2_thresh (dense-over-light), raises kt -> max(kt, kd_conv) and kv -> max(kv, prandtl_conv*kd_conv), strictly below the active surface boundary layer (KPP/EPBL own that). An INTERIOR closure CONTRIBUTOR – it does not clip/floor on its own; it feeds vmix_assemble. enable = .false. keeps the existing path bit-identical. Knob table: docs/generated_nml_knobs.md.

&ocean_coriolis_nml.

&ocean_data_nml: the shared time-varying NetCDF input reader (rdb_ocean_data_input, PR-14). Deliberately two knobs — this group carries NO per-field entries. Registration is programmatic: each consumer (surface forcing, OBC segments, sponge targets, tidal-mixing maps, …) calls ocean_data_input_register_2d/_3d from its OWN namelist group at setup and gets back an opaque id. A field never appears here. Zero registered fields on every shipped namelist today ⇒ ocean_data_input_update_all is a no-op ⇒ bit-identical.

Registration bookkeeping for the file-driven surface tags. A zero id_* means that tag is not file-driven (blank file in &ocean_dataovr_nml) and its slot keeps whatever the configure-time scalar/formula path seeded.

&ocean_dataovr_nml: file-backed surface forcing (PR-15, the A3 keystone consumer). Binds time-varying NetCDF fields, through the shared PR-14 reader (&ocean_data_nml), onto the surface stress and surface-flux slots. enable = .false. registers nothing ⇒ ocean_data_input_update_all stays a no-op ⇒ bit-identical.

Double diffusion (&ocean_ddiff_nml, CVMix_ddiff-style): salt fingering (Large et al. 1994) + diffusive convection (Marmorino-Caldwell 1976 / Kelley 1990). Folded INTO the heat/salt split (not a kv/kt contributor) to give an asymmetric ks-vs-kt divergence. Defaults are the CVMix defaults; enable = .false. keeps the path bit-identical. Knob table: docs/generated_nml_knobs.md.

&ocean_debug_nml: forensic probes for the ocean dyn-core. Every knob defaults off ⇒ bit-identical (untaken branches); all are HEAVY when on (device waits / serialised apply chains) — investigation tools, not production diagnostics. Output is greppable fixed-format rows (BUDGET / KE_ATTR / CHKSUM / HOTFACE); reader: tools/read_chksum.py.

NetCDF output stream state. Carried inline on ocean_diag_t so the diag module stays NetCDF-free (no use netcdf here); the actual file operations live in rdb_ocean_diag_netcdf which manipulates these fields.

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).

Energetics-based planetary boundary layer (&ocean_epbl_nml). All defaults preserve bit-identity: enable = .false. keeps the existing PP81 + KPP path untouched. Knob table + MOM6 name mapping: docs/generated_nml_knobs.md.

&ocean_forcing_nml: PR-12 surface-flux component-set gate. Default OFF ⇒ bit-identical (no component array allocated, no assembler kernel runs; ocean_surface_flux_t%Q_heat/Q_salt are filled exactly as &ocean_thermo_nml always has).

&ocean_foxkemper_nml: Fox-Kemper mixed-layer-eddy restratification. Default off ⇒ bit-identical. Reads epbl%mld.

&ocean_geothermal_nml: bottom-heat-flux knobs. Default OFF = bit-identical.

&ocean_gm_nml: Gent-McWilliams thickness diffusion — eddy-induced bolus transport folded into continuity. Reads the slopes slot. Default off ⇒ no bolus flux.

Gent-McWilliams thickness-diffusion state. All fields default to the inert (enable=.false.) configuration so an ocean run that never sets &ocean_gm_nml is bit-identical.

&ocean_grid_nml: horizontal-grid generator + geometry knobs.

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.

&ocean_hdiff_nml — along-coordinate tracer Laplacian (rdb_ocean_hdiff_tracer). Diffusion along the MODEL coordinate, not neutral surfaces (that is &ocean_redi_nml, a separate already-reachable capability).

Initial-condition overlay + EOS reference state. Drives the analytical configurations (eady-front, geostrophic- adjustment, …) plus the linear-EOS reference values that the rest of the ocean dyn step reads.

&ocean_ice_nml: sea-ice model master switch + category/layer counts (SIS2 port, PLAN_SEA_ICE.md). PR 0 scaffold — the knobs size the gated ocean_sea_ice_t slot. PR 3c adds the v1 scalar restoring atmospheric-forcing filler (air_temp/restore_lambda/ sw_down) that drives the column live in the driver. Default OFF ⇒ byte-identical.

&ocean_ice_ic_nml: sea-ice ANALYTIC initial-condition path (PR 24). Default conc_config="zero" early-returns before touching a single ice array => byte-identical to today for every existing nml/test. v1 ships "uniform" (scalar) and "latitudes" (SIS2 polar-cap analytic form) only — file-backed ICs are deliberately NOT in the allowed list ("file" is v1.1, PR-14).

&ocean_isopycnal_nml: grounding-stability controls for the Lagrangian (isopycnal-class, remap-free) vertical coordinate. Every knob here engages ONLY under sim_type=’ocean’ + VCOORD_LAGRANGIAN, so the whole group is bit-identical on every other vertical coordinate. All are default-OFF except pgf_skip_nonoverlap, which is a correctness fix and defaults ON.

&ocean_kappa_shear_nml: shear-driven interior turbulence (Jackson, Hallberg & Legg 2008). Coexists with KPP/EPBL/PP81 — kappa is ADDED to the interior diffusivities. Default off ⇒ bit-identical.

&ocean_meke_nml: mesoscale eddy kinetic energy — a 2D prognostic eddy-energy field fed back as a thickness/tracer diffusivity into VarMix’s KhTh/KhTr. Reads gm%gm_src. Default off ⇒ no-op.

Mesoscale eddy kinetic energy state. All fields default to the inert (enable=.false.) configuration so an ocean run that never sets &ocean_meke_nml is bit-identical.

Fox-Kemper mixed-layer-eddy restratification state. All fields default to the inert (enable=.false.) configuration so an ocean run that never sets &ocean_foxkemper_nml is bit-identical.

&ocean_mpi_nml: multi-rank MPI debug and tuning controls.

Porous barriers (&ocean_porous_nml): subgrid sill/strait blocking of the C-grid face widths via the Adcroft (2013) three-parameter fit. The layer-averaged OPEN-AREA fraction multiplies dy_cu / dx_cv in the layer mass transport (continuity-PPM + Coriolis advection), so a deep sill blocks the bottom layers while the surface layers stay fully open. enable = .false. keeps the existing path bit-identical. Knob table: docs/generated_nml_knobs.md.

Atmospheric surface-pressure loading / inverse barometer (&ocean_psurf_nml, PR-17). Folds eta_ib = -p_surf/(rho0 g) into the barotropic eta_forcing seam so an atmospheric high depresses SSH (~1 cm/hPa; Wunsch & Stammer 1997). enable = .false. keeps the existing path bit-identical. Split-solver only and mutually exclusive with &ocean_bt_nml bt_halo > 0. Requires &ocean_forcing_nml enable_components=.true. (the p_surf field is allocated only with the component set). ρ₀ is NOT a knob here — it is taken from ocean_state%eos%rho0 (the single ρ₀ of record).

&ocean_redi_nml: Redi continuous neutral (along-isopycnal) tracer diffusion — the rotated diffusion tensor. Default off ⇒ no neutral flux.

Redi continuous neutral-diffusion state. Defaults inert (enable=.false.) ⇒ bit-identical. Reads the prognostic T/S + EOS directly (recomputes its own interface dR/dT, dR/dS — does NOT consume GM slopes). Augments rdb_ocean_hdiff_tracer.

Grid/coordinate/tracer fingerprint validated on read. Distinct from the decomposition metadata (px/py/dims) so a file built with a different vertical resolution, ghost width, vcoord, or tracer set is rejected loudly rather than silently mis-mapped.

Restart-manager lifecycle marker. The registry is built per-run by ocean_state_build_restart_registry (it holds live pointers into the freshly allocated slots), not stored here. Cadence is driven by the driver off cfg%restart_interval/cfg%output_dir.

&ocean_restore_nml: surface buoyancy restoring of top-layer T/S toward scalar targets via a piston velocity. Default OFF = bit-identical.

Sea-ice state slot. All fields default to the inert (enable=.false.) configuration so an ocean run that never sets &ocean_ice_nml is byte-identical to a build without this slot.

&ocean_slopes_nml: isopycnal (neutral) slope diagnostics (Griffies 1998) at C-grid interfaces. Foundational gate for GM/Redi/VarMix. Default off ⇒ no-op.

&ocean_sponge_nml: the map-driven sponge (PR-23). Default OFF (enable = .false.) ⇒ the legacy &ocean_bc_nml band kernels run unchanged ⇒ bit-identical. See rdb_ocean_sponge.F90’s module docstring for the physics; docs/plans/PLAN_PR23_real_sponge.md for the design record.

Map-driven sponge state: per-cell Idamp [1/s] + a 3-D reference state. See the module docstring for the physics + the MOM6 divergences. Value-semantics slot (no CS pointer, no associated(CS) guards) per src/core/ocean/README.md.

&ocean_tdrag_nml — ICE-SHELF TOP drag, the mirror of &ocean_bdrag_nml at k = nz. Requires &ocean_cavity_dyn_nml enable (without a draft there is no ice base and cover_frac is identically zero, so the kernel would be a no-op with a cost). Default enable = .false. ⇒ the slot is a placeholder, no kernel runs, every path is bit-identical.

Thermodynamics master switches + scalar surface fluxes.

St-Laurent/Simmons internal-tide interior mixing (&ocean_tidal_mixing_nml). Bottom-intensified diapycnal diffusivity from the local dissipation of internal-tide energy over rough topography (Jayne & St Laurent 2001; St Laurent et al. 2002; Simmons et al. 2004). An INTERIOR closure: its Kd is ADDED to the surface PBL schemes (KPP or EPBL) and to PP81/background/kappa-shear. enable = .false. keeps the existing path bit-identical. Knob table: docs/generated_nml_knobs.md.

Equilibrium (astronomical) body-force tide (&ocean_tides_nml, capability C1). Drives -g grad(eta - eta_eq) in the barotropic momentum solve from a set of harmonic constituents. enable = .false. keeps the existing path bit-identical. Requires a non-cartesian grid (needs lat/lon).

Ice-shelf top-drag slot. Every array is full size when enable, a (1,1) / (1,1,1) placeholder otherwise — the ocean_cavity_flux_t gating convention, latched in ocean_state_init_from_config BEFORE init so the allocation gate can read it.

Basin geometry + surface-forcing setup. Despite the name, this carries forcing knobs (wind_config / taux_magnitude) and Coriolis tilt (beta / y_ref) alongside the bathymetry profile, because all of them live in the same logical “set up the box and what’s pushing it” slot at init — the &ocean_topo_nml block is read once before the IC is seeded. This grouping is settled (reviewed 2026-05-27); the form knob in &ocean_coriolis_nml is the scheme selector (Sadourny vs HK), distinct from the beta/y_ref parameters here.

Prognostic-tracer registry switches.

&ocean_varmix_nml: spatially-varying GM/Redi lateral-diffusivity coefficients = (background + Visbeck) × resolution_fn, clamped. Reads the slopes + wavespeed slots. Default off ⇒ GM keeps constant khth.

Spatially-varying lateral-diffusivity-coefficient state. All fields default to the inert (enable=.false.) configuration so an ocean run that never sets &ocean_varmix_nml is bit-identical.

Backward-Euler vertical-friction solver knobs (&ocean_vdiff_nml). The implicit folds default .false. (explicit wind-stress apply); MOM6’s face treatment (hvel_mom6 + bbl_glue) defaults ON.

&ocean_wavespeed_nml: first-baroclinic wave speed + deformation radius. Diagnostic, default off — feeds GM/Redi/MEKE resolution scaling.

&ocean_wetdry_nml: dynamic wetting/drying for the split-explicit barotropic substep (docs/ocean_wetdry_plan.md). Default off ⇒ byte-identical everywhere (the wd_* workspaces stay unallocated and the substep runs its unmodified centred-face path).

Z-level T/S initial-condition overlay (&ocean_zinit_nml, capability A2). Reads pre-regridded T/S from a model-grid NetCDF and interpolates linearly in depth onto the seeded layer-centre depths, overwriting any analytical T/S. All defaults preserve bit-identity: enable = .false. is a no-op. Design + MOM6 divergences: local_archive/specs/a2_zinit_spec.md.

One registered checkpoint field. Holds a pointer to the slot’s host array (or host scalar) plus the interior extents needed to slice owned cells. Exactly one of p0 / p2 / p3 is associated (per rank: 0 = host scalar, 2/3 = array).

Append-only registry of checkpoint fields. Slots call register_2d / register_3d from their (or the state’s) init.