Add basic frazil only

components/omega/configs/Default.yml

@@ -58,6 +58,8 @@ Omega:
       Mode: Implicit
       Type: Constant
       BottomDragCoeff: 1.0e-3
+    SfcThicknessForcingTendencyEnable: false
+    SfcTracerForcingTendencyEnable: false
     TracerHorzAdvTendencyEnable: true
     TracerDiffTendencyEnable: true
     EddyDiff2: 10.0
@@ -69,6 +71,7 @@ Omega:
     VelocityVertAdvTendencyEnable: true
     TracerVertAdvTendencyEnable: true
     PressureGradTendencyEnable: true
+    FrazilTendencyEnable: false
     VelVertMixTendencyEnable: true
     TracerVertMixTendencyEnable: true
   ManufacturedSolution:
@@ -84,6 +87,11 @@ Omega:
       DRhoDT: -0.2
       DRhoDS: 0.8
       RhoT0S0: 1000.0
+  Frazil:
+    FrazilType: basic
+    MassLimit: 0.1
+    DepthLimit: -1.0
+    ConservationCheck: false
   VertMix:
     Background:
       Diffusivity: 1.0e-5

components/omega/doc/devGuide/Forcing.md

@@ -6,7 +6,8 @@ This page describes design and implementation details for forcing-related
 pathways in Omega, currently this includes:
 
 - Surface stress forcing (e.g. wind stress)
-- Surface tracer restoring
+- Surface thickness and tracer flux forcing (actively coupled or data-forced)
+- Surface tracer restoring (soon to be ported as a field originating from the coupler)
 
 ## Surface stress forcing design
 
@@ -37,6 +38,70 @@ pathways in Omega, currently this includes:
 - `Omega.Tendencies.SfcStressForcingTendencyEnable`
   - gates execution of surface stress forcing tendency kernel
 
+## Surface thickness and tracer flux forcing design
+
+### Surface thickness and tracer flux forcing data flow
+
+**Thickness equation pathway:**
+
+1. External fields provide freshwater and salt flux components:
+   - `SnowFlux`, `RainFlux`, `EvaporationFlux`
+   - `SeaIceFreshWaterFlux`, `IceRunoffFlux`, `RiverRunoffFlux`
+   - `SeaIceSaltFlux`
+2. `Forcing` stores the flux fields in `TracerForcingVars`
+3. The tendency term `SfcThicknessForcingOnCell` sums the freshwater and salt mass fluxes and applies them to
+the surface layer pseudo-thickness.
+
+**Tracer equation pathway:**
+
+1. External fields provide heat and salt flux components:
+   - `LatentHeatFlux`, `SensibleHeatFlux`
+   - `LongWaveHeatFluxUp`, `LongWaveHeatFluxDown`
+   - `SeaIceHeatFlux`, `ShortWaveHeatFlux`
+   - mass fluxes which add energy changes (`SnowFlux`, `RainFlux`, `IceRunoffFlux`, `RiverRunoffFlux`)
+   - `SeaIceSaltFlux`
+2. `Forcing` stores the flux fields in `TracerForcingVars`
+3. The tendency term `SfcTracerForcingOnCell` converts the summed external heat fluxes to a conservative-temperature tendency,
+  and applies the external sea-ice salt flux to the top layer salt content thus impacting salinity.
+
+### Surface thickness and tracer flux forcing key classes/components
+
+- `TracerForcingVars`
+  - Stores 13 coupled flux cell-centered fields: 6 freshwater fluxes, 6 heat
+    fluxes, and 1 salt flux component
+  - Fields initialized to zero and registered in `Forcing` field group
+- `SfcThicknessForcingOnCell` tendency term
+  - Computes the layer mass contribution (converted to pseudo-thickness): $\sum (\text{SnowFlux} + \text{RainFlux} + \text{EvaporationFlux} + \text{SeaIceFreshWaterFlux} + \text{IceRunoffFlux} + \text{RiverRunoffFlux} + \text{SeaIceSaltFlux}) / \rho_{sw}$
+  - Applied only at surface layer (top active layer) using `MinLayerCell`
+- `SfcTracerForcingOnCell` tendency term
+  - For temperature: adds the direct heat fluxes
+    $Q_{\text{latent}} + Q_{\text{sensible}} + Q_{\text{lw,up}} + Q_{\text{lw,down}} + Q_{\text{ice}} + Q_{\text{sw}}$
+, the phase change and enthalpy of added mass $(\text{RainFlux} + \text{RiverRunoffFlux}) c^0_{p,sw} C_T^{\text{top}} + (\text{SnowFlux} + \text{IceRunoffFlux})(c^0_{p,sw} C_T^{\text{frz}} - L_{\text{ice}})$,
+    (where $C_T^{\text{frz}}$ is from EOS at top-layer salinity and pressure),
+    and scales by $H_{\text{FluxFac}}$.
+  - For salinity: applies salt flux with unit conversion: $\text{SeaIceSaltFlux} \times S_{\text{FluxFac}}$
+  - Applied only at surface layer using `MinLayerCell`
+  - Uses tracer index validation to apply to specific tracers only
+- `Forcing`
+  - Manages `TracerForcingVars` instance
+- `Tendencies`
+  - Calls `SfcThicknessForcingOnCell` in `computePseudoThicknessTendenciesOnly`
+  - Calls `SfcTracerForcingOnCell` in `computeTracerTendenciesOnly` after surface tracer restoring
+
+### Surface thickness and tracer flux forcing config coupling
+
+- `Omega.Tendencies.SfcThicknessForcingTendencyEnable`
+  - gates execution of coupled flux thickness kernel
+  - controls freshwater and salt flux forcing on sea surface height
+- `Omega.Tendencies.SfcTracerForcingTendencyEnable`
+  - gates execution of coupled flux tracer kernel
+  - controls direct heat flux forcing on temperature and salt flux forcing on salinity
+
+## Notes
+
+- Currently all forcing is applied to the surface layer only. In the future, vertical spreading of river runoff contributions will be needed.
+- `SeaIceFreshWaterFlux` is the pure freshwater mass from sea ice. The full mass flux from sea ice is `SeaIceFreshWaterFlux + SeaIceSaltFlux`
+
 ## Surface tracer restoring design
 
 ### Surface tracer restoring data flow

components/omega/doc/devGuide/Frazil.md

@@ -0,0 +1,93 @@
+(omega-dev-frazil)=
+
+# Frazil
+
+This page describes frazil design and implementation details in Omega,
+for the current basic pathway. A TEOS-10 option will be added soon.
+
+## Purpose and coupling points
+
+Frazil computes phase-change-related tendencies that modify:
+
+- pseudo-thickness tendency
+- temperature tracer tendency
+- salinity tracer tendency
+
+The tendency hook-up is implemented through `FrazilOnCell` in the tracer
+tendency phase, where frazil contributions are added to accumulated
+`PseudoThicknessTend` and `TracerTend` arrays.
+
+## Data flow and call sequence
+
+1. `Tendencies.computeTracerTendenciesOnly` checks
+   `Tendencies.FrazilTendencyEnable`.
+2. If enabled, `FrazilOnCell.operator()` retrieves the default Frazil object
+   and zeros frazil tendency and accumulator arrays.
+3. `FrazilOnCell` extracts `Temperature` and `Salinity` tracer subviews, then calls
+   `Frazil.computeFrazil(CT, SA, PressureMid, PseudoThickness)`.
+4. `Frazil.computeFrazil` dispatches using FrazilType. The only current supported
+   option is basic. A TEOS-10 option will be added soon.
+5. Returned frazil tendencies are added into `PseudoThicknessTend` and
+   `TracerTend` for active cell layers.
+
+## Configuration coupling
+
+Frazil behavior is configured with:
+
+- `Omega.Tendencies.FrazilTendencyEnable`
+  - Global switch for applying frazil tendency terms.
+- `Omega.Frazil.FrazilType`
+  - Implementation choice. Only current supported value: `basic`.
+- `Omega.Frazil.MassLimit`
+  - Per-layer mass and thickness limiter used by basic formation and melt.
+- `Omega.Frazil.DepthLimit`
+  - Optional depth cutoff for frazil activity. Negative means no cutoff.
+- `Omega.Frazil.ConservationCheck`
+  - Optional post-compute column conservation diagnostic logging.
+
+## Basic pathway summary
+
+- Freezing-point checks are based on conservative temperature and absolute
+  salinity with pressure-dependent freezing temperature.
+- Vertical accumulation order is bottom-to-top within each active column.
+- Frazil tendencies are not time-step scaled inside `Frazil`; they are
+  accumulated as tendency contributions.
+- Surface salt redistribution is applied at the top active layer.
+- Column accumulators are converted to coupler units at the end of the
+  per-column loop.
+
+### Basic pathway (`FrazilType: basic`)
+
+- Uses simplified energetics: the energy of the super-cooled water sets the
+amount of solid ice formed (used constant latent heat of fusion of fresh ice).
+Salt is added based on a constant bulk salinity `IceRefSal` (default) or a
+manual toggle (for now) using the local salinity and the frazil porosity.
+Melting of existing frazil is set by the amount of pure ice that can be melted
+by the warm layer, and the enthalpy of melt water at the local freezing point
+is added to the temperature tendency.
+- Computes local layer tendencies (`HTend`, `TTend`, `STend`) and updates
+  accumulated frazil stores.
+- Applies surface salt redistribution adjustment and converts accumulators to
+  coupler units at the end of the column loop.
+- Warnings: 1) basic frazil formation/melt is does not conserve energy.
+  2) Using porosity to set the salt content includes a redistribution of excess
+  salt in the surface layer, which can be very significant.
+
+## Existing ctest coverage
+
+The existing frazil test driver is in
+`components/omega/test/ocn/FrazilTest.cpp` and covers:
+
+- basic frazil formation in cold and warm single-layer states
+- mixed warm/cold column behavior with sign checks for branch switching
+- depth-limit behavior ensuring excluded deep layers have zero frazil tendency
+
+## Extensibility
+
+The frazil choice dispatch and configuration plumbing are retained so future
+frazil options can be added without changing Tendencies call sites.
+
+## Related pages
+
+- User-facing options: [User Frazil Guide](../userGuide/Frazil.md)
+- Tendency container and hook-up: [Tendencies](Tendencies.md)

components/omega/doc/devGuide/Tendencies.md

@@ -64,6 +64,22 @@ Tendencies.computeVelocityTendencies(State, AuxState, ThickTimeLevel, VelTimeLev
 To call only the tracer tendency terms:
 Tendencies.computeTracerTendencies(State, AuxState, TracerArray, ThickTimeLevel, VelTimeLevel);
 
+## Frazil tendencies
+
+Frazil tendencies are calculated by the Frazil class, not the TendencyTerms.
+The tendencies are integrated in the tracer tendency compute path and read in from
+the frazil computation. When
+`Omega.Tendencies.FrazilTendencyEnable` is true,
+`computeTracerTendenciesOnly` invokes `FrazilOnCell`, which calls the default
+`Frazil` object and adds frazil contributions to:
+
+- `PseudoThicknessTend`
+- `TracerTend` for `Temperature`
+- `TracerTend` for `Salinity`
+
+The frazil implementation choice and parameters are read from the
+`Omega.Frazil` block. Detailed algorithm notes are in [Frazil](Frazil.md).
+
 ## Removal of tendencies
 To erase a specific named tendencies instance use `erase`
 ```c++

components/omega/doc/devGuide/TendencyTerms.md

@@ -41,9 +41,11 @@ implemented:
 - `TracerHighOrderHorzAdvOnCell`
 - `TracerDiffOnCell`
 - `TracerHyperDiffOnCell`
+- `SfcThicknessForcingOnCell`
+- `SfcTracerForcingOnCell`
 - `SurfaceTracerRestoringOnCell`
 
 ## See Also
 
-Additional information on forcing (currently wind forcing and surface tracer
-restoring) is detailed in [](omega-dev-forcing).
+Additional information on forcing (surface stress, surface mass and tracer flux forcing, and
+surface tracer restoring) is detailed in [](omega-dev-forcing).

components/omega/doc/index.md

@@ -54,6 +54,7 @@ userGuide/Timing
 userGuide/VerticalMixingCoeff
 userGuide/VertAdv
 userGuide/Forcing
+userGuide/Frazil
 userGuide/SfcCoupling
 userGuide/Analysis
 ```
@@ -102,6 +103,7 @@ devGuide/Timing
 devGuide/VerticalMixingCoeff
 devGuide/VertAdv
 devGuide/Forcing
+devGuide/Frazil
 devGuide/SfcCoupling
 devGuide/Analysis
 ```

components/omega/doc/userGuide/Forcing.md

@@ -5,6 +5,7 @@
 This page documents the user-facing configuration and behavior for current forcing in Omega:
 
 - Surface stress forcing (e.g. wind stress)
+- Coupled tracer flux forcing (mass, energy and salt)
 - Surface tracer restoring
 
 ## Surface stress forcing
@@ -39,6 +40,74 @@ Surface stress forcing uses surface stress input fields:
 These are stored in forcing variables and used to form edge-normal stress
 (`NormalStressEdge`) that enters momentum tendencies.
 
+## Surface thickness and tracer flux forcing
+
+Surface thickness and tracer flux forcing applies ocean-atmosphere and ocean-sea ice fluxes from the other model
+components (atmosphere, sea ice) to the thickness and tracer equations. This enables
+the ocean to respond to heat, freshwater, and salt exchanges at the surface. These fluxes can be from data or (active) coupled components.
+
+### Surface thickness and tracer flux forcing configuration
+
+Surface thickness and tracer flux forcing is controlled by two configuration flags:
+
+```yaml
+Omega:
+  Tendencies:
+    SfcThicknessForcingTendencyEnable: false
+    SfcTracerForcingTendencyEnable: false
+```
+
+- `Tendencies.SfcThicknessForcingTendencyEnable`: enables coupled freshwater and salt flux forcing on thickness
+- `Tendencies.SfcTracerForcingTendencyEnable`: enables coupled heat and salt flux forcing on tracers
+
+
+### Required input fields
+
+Coupled tracer flux forcing uses 13 auxiliary fields organized by type:
+
+**Freshwater mass fluxes (kg m⁻² s⁻¹):**
+- `SnowFlux`: precipitation from snow
+- `RainFlux`: precipitation from rain
+- `EvaporationFlux`: evaporative water loss
+- `SeaIceFreshWaterFlux`: freshwater mass flux from sea-ice melt or formation
+- `IceRunoffFlux`: runoff from land ice
+- `RiverRunoffFlux`: runoff from rivers
+
+**Heat fluxes (W m⁻²):**
+- `LatentHeatFlux`: latent heat transfer
+- `SensibleHeatFlux`: sensible heat transfer
+- `LongWaveHeatFluxUp`: upward longwave radiation
+- `LongWaveHeatFluxDown`: downward longwave radiation
+- `SeaIceHeatFlux`: heat/energy from sea-ice interaction (incl. enthalpy of meltwater)
+- `ShortWaveHeatFlux`: shortwave (solar) radiation
+
+**Salt mass flux (kg m⁻² s⁻¹):**
+- `SeaIceSaltFlux`: salt flux from sea-ice formation/melt processes
+
+These fields are populated by external coupling components (typically atmosphere
+and ice models). Omega assumes the incoming values match the documented units.
+For now, there are assumed to come from a `forcing.nc` file, but later will be provided
+by the equivalent `ocn_comp_mct.F`.
+
+### Notes
+
+- Coupled fluxes are applied only at the surface layer (top active layer) for each cell. In the future, vertical spreading of contributions from river runoff will be needed.
+- Pseudo-thickness tendency is computed from the (six) freshwater mass fluxes and the salt mass flux
+  `SeaIceSaltFlux`, converted to a pseudo-thickness change.
+- Temperature tendency is computed from direct heat flux plus
+  mass-flux enthalpy terms, converted to conservative-temperature tendency via
+  $H_{\text{FluxFac}} = 1.0 / (\rho_{sw} c^0_{p,sw})$ where $c^0_{p,sw}$ is the reference
+  specific heat of seawater defined by TEOS-10. The enthalpy associated with mass fluxes is currently hard-coded to SST for liquid fluxes and the freezing temperature for solid fluxes (which are melted using a constant latent heat of fusion). Note that the enthalpy of liquid meltwater from sea ice is already included in `SeaIceHeatFlux`.
+- Salinity tendency from `SeaIceSaltFlux` is scaled by
+  $S_{\text{FluxFac}} = 1.0e3 / \rho_{sw}$ to account for unit conversion from
+  kg/(m²·s) to salinity units (g/kg).
+- Fluxes are assumed to be in the documented units (i.e. net mass fluxes);
+  any unit conversion should be performed by the coupling component before providing flux
+  values to Omega.
+- The reference density used here ($\rho_{sw}$) is not a Boussinesq density, it is the
+  conversion factor from mass to pseudo-thickness.
+- No iceberg fluxes are included for now.
+
 ## Surface tracer restoring
 
 Surface tracer restoring applies a piston-velocity tendency, or damping, at the ocean