rdb_ocean_surface_flux Module

2D net surface heat flux (W/m^2, positive downward), shape (nx, ny). Fill via set_surface_flux_const for spatially-uniform forcing (the default); Area-A3 override or Area-A4 restoring writes the field directly.

Scalar fill source for Q_heat(:,:). Seeded from &ocean_thermo_nml q_heat by set_surface_flux_const. Kept for diagnostic logging; kernels read Q_heat directly.

2D net surface salt flux (kg salt/m^2/s, positive salinifies), shape (nx, ny).

Scalar fill source for Q_salt(:,:). Seeded from &ocean_thermo_nml q_salt by set_surface_flux_const.

Specific heat capacity (J/kg/K).

Evaporative mass flux (kg/m^2/s, <= 0 — MOM6 convention, (-1)*flux out of the ocean). v1: enthalpy + salt bookkeeping only — does NOT change column mass (real freshwater is a named follow-up, see the module docstring).

Frozen precipitation / snowfall (kg/m^2/s, >= 0).

Frozen (calving/ice) runoff (kg/m^2/s, >= 0).

Floor on the surface-layer thickness in the 1/h_top division — keeps the kernel finite when the top layer pinches out.

True when Q_heat carries a non-zero fill (set by set_surface_flux_const when q_heat_val /= 0). Any future field-fill path (A3 data-override, A4 restoring) MUST set has_heat = .true. after writing into Q_heat so the apply-tracers kernel fires. Host-side flag only (early-return guard in ocean_surface_flux_apply_tracers).

Host-side latch — set by a filler after writing ANY of evap/lprec/fprec/vprec/lrunoff/frunoff/ seaice_melt. Cheap early-return gate for a future freshwater kernel (real-mass PR). Same contract as has_heat (:56-62) — never set from a device reduction.

Host-side latch — set by a filler after writing q_sw (e.g. an ice sw_thru coupler). Not the same as has_sw below (that gates shortwave penetration, an unrelated pre-existing switch) — do not conflate the two.

True when SSS restoring is active (enable_restore_salt .and. restore_piston_S /= 0).

True when SST restoring is active (enable_restore_temp .and. restore_piston_T /= 0). Host-side gate only — ocean_surface_restore_apply_tracers early-returns unless this or has_restore_S is set, so the default-off path is byte-for-byte unchanged.

True when Q_salt carries a non-zero fill (set by set_surface_flux_const when q_salt_val /= 0). Same contract as has_heat for any field-fill path.

True when shortwave penetration is active (set by set_sw_penetration when sw_pen_frac /= 0). Host-side gate only — ocean_surface_flux_apply_sw_penetration early-returns unless this is set, so the default-off path leaves the surface-flux deposition byte-for-byte unchanged.

Restoring / flux-adjustment / “other” net heat term not decomposed into the radiative/turbulent bands above (W/m^2, either sign; MOM6 heat_added). The v1 ice coupler’s heat_flux_diag lands here (§5.4 of the PR-12 plan) — it is already a net W/m^2, not further decomposable.

Ice-shelf cavity basal-melt heat component (W/m^2, same positive-DOWN-into-the-ocean convention as every other heat band; &ocean_cavity_melt_nml). OWNED by rdb_ocean_cavity_flux; written heat_cavity = -q_ocean, where q_ocean = rho_w*c_w*gamma_t*(T_w - T_b) > 0 is the kernel’s turbulent heat flux OCEAN -> INTERFACE, so warm water under a shelf COOLS the top of the column. It is a SEPARATE field from heat_added precisely because the sea-ice coupler full-overwrites heat_added — two writers on one slot clobber silently (cavity x sea ice is refused today, but the ownership rule must not depend on that). Zero unless a cavity melt step ran.

Enthalpy carried by fprec (W/m^2).

Enthalpy carried by frunoff (W/m^2).

Enthalpy carried by lprec (W/m^2). A filler that writes lprec MUST fill this — the v1 convenience is SEAWATER_CP * T_source * lprec. The source (not the ocean) owns this enthalpy — see the module docstring §(d).

Enthalpy carried by lrunoff (W/m^2).

Assembler output — do NOT write. Sum of the six heat_content_<flux> companions above (W/m^2, >= 0 for warm inflow). Filled by ocean_surface_flux_assemble.

Assembler output — do NOT write. SEAWATER_CP * T_sst * evap (W/m^2, <= 0 since evap <= 0) — the enthalpy the ocean loses with evaporating mass, computed from the ocean’s own surface temperature (the ocean, not a filler, owns this number). There is deliberately NO heat_content_evap field — see the PR-12 plan §11.6. Filled by ocean_surface_flux_assemble.

Enthalpy carried by seaice_melt (W/m^2).

Enthalpy carried by vprec (W/m^2).

True between init and destroy.

Liquid precipitation (kg/m^2/s, >= 0 into the ocean).

Liquid river runoff (kg/m^2/s, >= 0).

Assembled total (Pa, >= 0) — p_surf_atm plus any ice mass-loading term, full overwrite, never += (a += ratchets the load across outer steps with no bound). No consumer in this PR; ships zeroed alongside p_surf_atm so the follow-up PGF fold needs no further plumbing.

Input component. Atmospheric surface-pressure load (Pa, >= 0). Filled by an external reader / configure-time scalar seed — the sea-ice path never writes this field. Ships zeroed with no consumer in this PR (the inverse- barometer PGF fold is a same-release-cycle follow-up).

Host latch, 1 once ocean_surface_flux_assemble has derived Q_heat/Q_salt from the component set. From then on the two arrays are CARRIED state: the assembler runs at the END of a thermo step and the steps up to the next one read what it left (SST-dependent terms included), so with use_components they are checkpointed, and this latch tells a warm restart that the checkpointed arrays are an assembly to resume from (0 => an older checkpoint or none yet: the configure-time seed stands). A real, not a logical, because the restart registry carries real scalars.

Latent heat flux (W/m^2, typically < 0, positive down).

Net longwave (W/m^2, typically < 0, positive down).

Sensible heat flux (W/m^2, typically < 0, positive down).

Shortwave into the ocean (W/m^2, >= 0, positive down).

Scalar target SSS (PSU).

Scalar target SST (degC). Read by-value into the device _impl kernel — no per-cell field (so no extra device array, the enter_data orchestrator is untouched). A 2D-field target is the documented A4-v2 follow-up.

SSS piston velocity (m/s).

SST piston velocity (m/s), seeded from &ocean_restore_nml piston_t (m/day) via /86400. The surface relaxation rate for a top layer of thickness h_top is lambda = restore_piston_T / h_top [1/s].

Boussinesq reference density (kg/m^3) — the dt/(rho0*cp) heat and dt/rho0 salt divisors applied to EVERY surface tracer source, including whatever the sea-ice coupler writes into Q_heat/Q_salt.

Ice-shelf cavity basal-melt salt component, same units and sign as salt_flux (positive salinifies; &ocean_cavity_melt_nml). OWNED by rdb_ocean_cavity_flux and never written by the ice coupler, which full-overwrites salt_flux.

Net surface salt-flux COMPONENT (kg salt/m^2/s, positive salinifies) — a filler writes this (e.g. the ice brine coupler); the assembler adds Q_salt_const to produce Q_salt. Virtual in v1 (no column-mass change).

Sea-ice melt-water mass flux (kg/m^2/s, >0 = melt into the ocean, <0 = formation / freezing withdraws mass).

Band-1 weight R of the two-band irradiance decay. Jerlov type I (clear open ocean) default.

Selects the irradiance source for shortwave penetration and the boundary-layer SW coupling. .false. (default): the source is the NET heat flux Q_heat (sw_source="net_heat", legacy, bit-identical). .true. (sw_source="q_sw"): the source is the dedicated q_sw component (>= 0), which removes the night-time negative-I0 hazard where sw_pen_frac*Q_heat < 0 drives unphysical negative irradiance down the two-band profile. Set by set_sw_penetration; host-side gate only (never a device reduction) — the shim selects the source array on the host so the conditionally-allocated q_sw is never dereferenced in a device kernel.

Penetrating fraction of Q_heat carried below the surface layer as a two-band exponential (Paulson & Simpson 1977). 0 = off (all of Q_heat lands at k = nz, legacy path).

Band-1 e-folding depth (m) — the rapidly-absorbed red/near-IR band.

Band-2 e-folding depth (m) — the slowly-absorbed blue/green band.

Master gate (&ocean_forcing_nml enable_components). .false. (default): none of the arrays below are allocated, ocean_surface_flux_assemble is a no-op, and Q_heat/Q_salt are filled exactly as today — bit-identical. .true.: allocates the component set (set_components) and the assembler rebuilds Q_heat/Q_salt every thermo step.

Virtual precipitation (kg/m^2/s, either sign — SSS-restoring convention; NOT wired to the restoring kernel in v1, see set_restore below and the module docstring’s follow-up note).

Ice-cover fraction at cell centres (metrics%cover_frac).

Optional — absent ⇒ no-op (no forcing configured).

Optional thermo-cadence gate. Present-and-false ⇒ early return; absent ⇒ kernel runs.

Optional ice-shelf cover fraction (metrics%cover_frac, v1 binary). Present ⇒ the penetrating irradiance is scaled by 1 - cover_frac, so a covered column absorbs NOTHING — no sunlight reaches the ocean through several hundred metres of ice. Needed even on the sw_source="net_heat" branch, where Q_heat is already assembler-masked: this kernel’s job is to MOVE a surface lump down the column, and on a masked column the lump it would remove was never deposited (the same argument &ocean_wetdry_nml makes for a dry column). Absent ⇒ the original kernel, byte-identical.

Optional — when absent the kernel is a no-op (no surface forcing configured).

Optional gate (thermo cadence). Absent ⇒ kernel runs; present-and-false ⇒ early return.

Optional DYNAMIC cell wet mask (wet/dry, docs/ocean_wetdry_plan.md §4.4) composed multiplicatively with the static ms%wet_mask — surface fluxes must not enter a dynamically dry column (heating a mm-scale residual sliver blows its temperature up). Absent ⇒ the original static-mask path, byte-identical.

Optional thermo-cadence gate. Present-and-false ⇒ early return; absent ⇒ kernel runs (matches ocean_surface_flux_apply_tracers’s convention).

Optional ice-shelf cover fraction (metrics%cover_frac, v1 binary). Present ⇒ every ATMOSPHERIC contribution (Q_heat_const, q_sw, q_lw, q_lat, q_sens, heat_added, both mass-enthalpy terms, Q_salt_const, salt_flux) is scaled by 1 - cover_frac, while the cavity’s OWN heat_cavity / salt_cavity pass through unmasked. This is the single place those two groups are still distinguishable — see the module docstring for why the mask lives here and not at apply time. Absent ⇒ the original kernel, byte-identical.

Optional — absent ⇒ no-op (no forcing configured).

Optional thermo-cadence gate. Present-and-false ⇒ early return; absent ⇒ kernel runs.

Optional ice-shelf cover fraction (metrics%cover_frac, v1 binary). Present ⇒ the restoring increment is scaled by 1 - cover_frac, so a covered column is NOT relaxed toward an atmospheric target — under a shelf the surface is a melting ice interface, and restoring there would overwhelm the melt signal with a number the atmosphere never set. Absent ⇒ the original kernel, byte-identical.

See apply_surface_src_2d_impl.

See apply_surface_src_2d_impl.

ms%k_top — the first LIVE layer counting down from the top. nz on every column that has no top-side filler (which is every column on every coordinate but z_fixed under a rigid top), so this reads the same memory as the literal nz it replaced and the arithmetic is bit-identical.

See apply_surface_src_2d_impl. The SAME index salinity used, so the pseudo-salt increment stays bit-identical to salinity’s and the deviation keeps measuring transport.

ms%k_bot — the first LIVE layer counting up from the bed. The opaque-bed residual lands HERE, not on k = 1: under z_fixed the layers below are inert fillers (1 elsewhere ⇒ unchanged).

ms%k_bot — the first LIVE layer counting up from the bed. The opaque-bed residual lands HERE, not on k = 1: under z_fixed the layers below are inert fillers (1 elsewhere ⇒ unchanged).