Adds the thermo coupling by alicebarthel · Pull Request #461 · E3SM-Project/Omega

alicebarthel · 2026-07-06T22:49:28Z

This (draft) PR adds the thermo coupling - from forcing terms to thickness and tracer tendencies.
The energy of mass fluxes and phase changes are hard-coded into the tendency conversions, like it was in MPAS-O. Hopefully the documentation (inline or otherwise) clarifies the meaning of each term.

This PR is 3/3 to make #418 more digestible.

Checklist

vanroekel · 2026-07-07T03:36:14Z

 - Surface stress forcing (e.g. wind stress)
- Surface tracer restoring
+- Surface flux forcing (actively coupled or data-forced)
+- Surface tracer restoring (soon to be ported)


somewhere, I don't think it needs to be in this PR, but we should separate out salinity restoring (or explicitly call it out) and note we plan to do this in the coupler instead of the framework from mpas.

The plan is to do restoring in the Forcing infrastructure too, as its own tendencies. I was planning to do a simple port into Forcing like I did for winds. With the timeline getting a little tight, I decided to prioritize implementing the new capability rather than spending time on the port.
The original PR (#418) had all the terms moved over but it was too big to test and review cleanly.
Are you thinking that you'd prefer a different design?

Yep this sounds right, not saying it needs to be higher priority. And I was wanting us to note when we do restoring that the time varying salinity will come from the coupler not from a Omega forcing framework like we have for MPAS. I don't think that changes anything you plan, just where you get the restoring target from.

vanroekel · 2026-07-07T03:38:05Z

+- `SensibleHeatFlux`: sensible heat transfer
+- `LongWaveHeatFluxUp`: upward longwave radiation
+- `LongWaveHeatFluxDown`: downward longwave radiation
+- `SeaIceHeatFlux`: heat from sea-ice interaction


I don't understand what you mean by sea ice interaction, can you clarify?

I'll clarify. This includes the direct heat fluxes (conduction, etc.) and the enthalpy of liquid water from sea ice melt.

vanroekel · 2026-07-07T03:39:21Z

+- `SnowFlux`: precipitation from snow
+- `RainFlux`: precipitation from rain
+- `EvaporationFlux`: evaporative water loss
+- `SeaIceFreshWaterFlux`: freshwater input from sea-ice melt or formation


do we want to say freshwater input here since it can get positive and negative? Maybe just 'mass input from sea ice melt/formation?

Good point, maybe "water mass flux from sea ice metl/formation"?

I like that.

vanroekel · 2026-07-07T03:41:23Z

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


would the iceberg flux be a modification to iceRunoffFlux?

The iceberg fluxes are their own additional terms. It's not hard to add an extra term, but given that we clearly stated that icebergs were out of scope for Omega, I thought I could skip defining/including them for now.

Yes you can for sure. I was mostly curious

vanroekel · 2026-07-07T04:04:16Z

+                               Mesh->NCellsSize),
+      SeaIceHeatFluxCell("seaIceHeatFlux" + Suffix, Mesh->NCellsSize),
+      ShortWaveHeatFluxCell("shortWaveHeatFlux" + Suffix, Mesh->NCellsSize),
+      SeaIceSaltFluxCell("seaIceSalinityFlux" + Suffix, Mesh->NCellsSize),


Why is there a SeaIceSalinityFlux here? Is this because it's assuming that's the form in forcing.nc?

Good catch. yes, it's a remnant from previous versions because I used to run a test reading from forcing.nc and loading the terms. This test has been removed so I can modify that to align it with the coupler terms.

vanroekel · 2026-07-07T04:19:26Z

   Err += MeshHalo->exchangeFullArrayHalo(SfcStressForcing.MeridStressCell,
                                          OnCell);

+   Err += MeshHalo->exchangeFullArrayHalo(TracerForcing.SnowFluxCell, OnCell);


Can you explain why a halo exchange is needed for on cell quantities? I would have thought the owned cells is enough

Good catch. Cell centered variables should not need the halo exchange.

vanroekel · 2026-07-10T18:56:09Z

+    fluxes, and 1 salt flux component
+  - Fields initialized to zero and registered in `Forcing` field group
+- `SfcThicknessForcingOnCell` tendency term
+  - Computes freshwater flux contribution: $\sum (\text{SnowFlux} + \text{RainFlux} + \text{EvaporationFlux} + \text{SeaIceFreshWaterFlux} + \text{IceRunoffFlux} + \text{RiverRunoffFlux} + \text{SeaIceSaltFlux}) / \rho_{sw}$


even though I think this works out, is SeaIceSaltFlux/\rho_{sw} the right form? It's kg Salt instead of water. Should we be specific about that? I recall you are elsewhere. I also recall the conversion factor works out to 1 to go from kg salt to kg water, so maybe it's not a big deal

actually isn't this a direct salt flux and maybe shouldn't appear here at all?

I clarified the text: these are all the mass contributions to the layer. The salt mass flux is taken into account in the same way as freshwater mass fluxes.

vanroekel · 2026-07-10T19:05:00Z

 This page documents the user-facing configuration and behavior for current forcing in Omega:

 - Surface stress forcing (e.g. wind stress)
+- Coupled flux forcing


surface stress is a momentum flux, so perhaps 'coupled thermodynamic and mass flux forcing'?

vanroekel · 2026-07-10T19:05:40Z


+## Surface flux forcing
+
+Surface flux forcing applies ocean-atmosphere and ocean-sea ice fluxes from the other model


similar comment, I don't think we should use surface flux and surface stress

vanroekel · 2026-07-10T19:08:20Z

-Additional information on forcing (currently wind forcing and surface tracer
-restoring) is detailed in [](omega-user-forcing).
+Additional information on forcing, including surface stress forcing,
+surface flux forcing, and surface tracer restoring, is detailed in


flagging surface flux again

vanroekel · 2026-07-10T19:41:14Z

+                                  SeaIceFreshWaterFlux(ICell) +
+                                  IceRunoffFlux(ICell) + RiverRunoffFlux(ICell);
+
+      Tend(ICell, KTop) += (FreshWaterFlux + SeaIceSaltFlux(ICell)) / RhoSw;


i'm still unsure why this appears as a thickness flux

@vanroekel the variable is pseudo-thickness, which is directly proportional to layer mass. So the question is: do we explicitly add the salt mass to the layer mass?
It changes the interplay between equations but isn't it more rigorous to include it?
I've been pondering this on the frazil side too.

oh yes right. good point. What is the SeaIceSaltFlux term in the ocean? If I recall right it's the consequence of the 4PSU assumption, do you understand why it's a separate field and not directly included with the SeaIceFreshwaterFlux?

The sea ice stores the freshwater and salt into 2 separate channels. In omega, both are mass (SI unit: kg) fluxes that come straight from the coupler (no 4psu assumption), with mass of salt and mass of pure freshwater as separate coupling terms. Both terms are added to the layer mass evolution, but only salt mass is added to the salinity tendency.
The use of "variable salinity coupling" will allow for time-varying salt flux due to sea ice drainage (i.e. prognostic salinity within the sea ice - translated to mass fluxes for coupling).

(note: if seaIceHeatFlux did not already include the enthalpy of melted water, we would use SeaIceFreshWaterFlux in the temperature tendency - here we don't because it would double count)

vanroekel · 2026-07-10T19:42:06Z

+         const Real PTopDb = PressureMid(ICell, KTop) * Pa2Db;
+         const Real SaTop  = SaltIndex >= 0
+                                 ? TracerCell(SaltIndex, ICell, KTop)
+                                 : 0.0_Real; // not sure we want zero here?


I think 0 is a fine limit. Does this form of code preclude logging when we go below this threshold?

vanroekel · 2026-07-10T19:59:55Z

overall this looks quite good @alicebarthel I only had pretty minor comments

…iscussion" This reverts commit 70b0ca2.

alicebarthel · 2026-07-13T22:53:30Z

One key test to do is to verify that omega_pr is BFB with develop baseline since we do not currently have a polaris test using the surface tracer forcing. @katsmith133

Here is my current test report:

Polaris `omega_pr` suite

Baseline workdir: /global/homes/a/abarthel/pscratch/polaris-scratch/baseline-current-develop-cpu
Baseline build: /global/homes/a/abarthel/pscratch/omega_scratch/develop-cpu
PR build: /global/homes/a/abarthel/pscratch/omega_scratch/add-thermo-forcing-cpu-gnu
PR workdir: /global/homes/a/abarthel/pscratch/polaris-scratch/add-thermo-cpu_vsbaseline
Machine: pm-cpu
Compiler: gnu
Build type: Debug
Log: not found
Result:
- Diffs (1 of 12):
  - ocean/planar/barotropic_gyre/munk/free-slip

alicebarthel · 2026-07-14T00:50:46Z

the log is at
/pscratch/sd/a/abarthel/polaris-scratch/add-thermo-cpu_vsbaseline/case_outputs/ocean_planar_barotropic_gyre_munk_free-slip.log
if that can be helpful

alicebarthel requested a review from vanroekel July 6, 2026 22:49

vanroekel reviewed Jul 7, 2026

View reviewed changes

vanroekel reviewed Jul 10, 2026

View reviewed changes

mark-petersen requested a review from katsmith133 July 13, 2026 15:09

alicebarthel added 9 commits July 13, 2026 10:32

port forcing tendencies (thickness and tracers) + update doc, yml

7bb8d3e

added the enthalpy of mass fluxes; CtFrz has public interface

d5168b7

added a test for thermo forcing tendencies

8c5db79

made mass enthalpy flux dependent on thickness flag - under discussion

2f9696f

draft a non-teos10 CtFrz in comments - WIP

d00bcd2

updated the documentation

f9d77f5

Revert "made mass enthalpy flux dependent on thickness flag - under d…

b99c94d

…iscussion" This reverts commit 70b0ca2.

updated the documentation

ff48c66

correction to pressure units and ctest

96c15a7

alicebarthel force-pushed the omega/add-thermo-forcing branch from f814b7a to 47abc12 Compare July 13, 2026 20:01

alicebarthel marked this pull request as ready for review July 13, 2026 20:07

update due to fill values and review comments

2e13052

alicebarthel force-pushed the omega/add-thermo-forcing branch from 47abc12 to 2e13052 Compare July 13, 2026 20:15

resolve memory issue on GPUs

69ca6c2


		## Surface flux forcing

		Surface flux forcing applies ocean-atmosphere and ocean-sea ice fluxes from the other model

Uh oh!

Conversation

alicebarthel commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vanroekel commented Jul 10, 2026

Uh oh!

alicebarthel commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Polaris omega_pr suite

Uh oh!

alicebarthel commented Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alicebarthel commented Jul 6, 2026 •

edited

Loading

alicebarthel commented Jul 13, 2026 •

edited

Loading

Polaris `omega_pr` suite