Add submesoscale eddy parametrization by mwarusz · Pull Request #438 · E3SM-Project/Omega

mwarusz · 2026-06-20T05:40:22Z

This PR adds the submesoscale eddy parametrization in the form presented in Fox-Kemper et al. 2011. The parametrization class provides three main methods that

determine mixed layer depth
compute buoyancy gradient
compute submesoscale induced velocity

respectively. A new auxiliary variable named NormalTransportVelocity has been added. This velocity variable is used to advect pseudo-thickness and tracers, and can optionally include the submesocale induced velocity.

Checklist

mwarusz · 2026-06-20T05:58:13Z

The parametrization unit tests are passing. However, after turning it on in the baroclinic channel polaris test with the default parameters, I see NaNs after about 3 hours of simulation time, so there is still some debugging to be done. Moreover, user and developer documentation needs to be added.

Copilot

Pull request overview

This PR introduces a new submesoscale eddy parameterization module (Fox-Kemper
et al. 2011) into Omega’s ocean model, wires it into initialization/finalization
and tendency/auxiliary-state workflows, and adds a dedicated unit test plus
broad test-harness updates to support new analytic-field helper signatures.

Changes:

Add SubmesoEddies module (config-driven) and integrate it into ocean module
init/finalize and auxiliary-state computation.
Introduce TransportAuxVars::NormalTransportVelocity and use it in thickness
and tracer tendency computations as the transport velocity (optionally
including submesoscale-induced velocity).
Update unit test utilities and many tests to accommodate updated analytic
field setters; add SubmesoEddiesTest.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
components/omega/test/timeStepping/TimeStepperTest.cpp	Initialize/destroy `SubmesoEddies` in the time stepper test harness.
components/omega/test/ocn/TendencyTermsTest.cpp	Update analytic-field lambdas to match updated `setScalar`/`setVectorEdge` signatures.
components/omega/test/ocn/TendenciesTest.cpp	Initialize/destroy `SubmesoEddies`; update analytic-field lambdas and `setScalar`/`setVectorEdge` call signatures.
components/omega/test/ocn/SubmesoEddiesTest.cpp	New unit test covering mixed-layer depth, buoyancy gradient, and eddy velocity computations.
components/omega/test/ocn/OceanTestCommon.h	Extend `setScalar`/`setVectorEdge` helpers to pass element indices and optional Z coordinates.
components/omega/test/ocn/HorzOperatorsTest.cpp	Update analytic-field lambdas to match updated helper signatures.
components/omega/test/ocn/AuxiliaryVarsTest.cpp	Update analytic-field lambdas to match updated helper signatures.
components/omega/test/ocn/AuxiliaryStateTest.cpp	Initialize/destroy `SubmesoEddies`; update analytic-field lambdas and helper call signatures.
components/omega/test/CMakeLists.txt	Register new `SUBMESOEDDIES_TEST`.
components/omega/src/timeStepping/ForwardBackwardStepper.cpp	Pass tracer array into thickness tendency computation.
components/omega/src/ocn/Tendencies.h	Extend thickness tendency API to accept a tracer array (for aux-state computations).
components/omega/src/ocn/Tendencies.cpp	Route thickness/tracer tendencies through new aux-state compute routines and use `NormalTransportVelocity`.
components/omega/src/ocn/SubmesoEddies.h	New `SubmesoEddies` public interface.
components/omega/src/ocn/SubmesoEddies.cpp	New implementation and IO field registration for `SubmesoEddies`.
components/omega/src/ocn/OceanInit.cpp	Initialize `SubmesoEddies` during ocean module init.
components/omega/src/ocn/OceanFinal.cpp	Destroy `SubmesoEddies` during ocean finalize.
components/omega/src/ocn/auxiliaryVars/TransportAuxVars.h	New aux-var container for `NormalTransportVelocity`.
components/omega/src/ocn/auxiliaryVars/TransportAuxVars.cpp	Register/unregister IO field for `NormalTransportVelocity`.
components/omega/src/ocn/AuxiliaryState.h	Add `TransportAuxVars` member and new aux compute entry points.
components/omega/src/ocn/AuxiliaryState.cpp	Compute Brunt–Väisälä frequency, compute transport velocity (optionally + submeso), and use it for vertical pseudo-velocity.
components/omega/configs/Default.yml	Add `Omega.Submeso` configuration group and defaults.

+       KOKKOS_LAMBDA(int IEdge, const TeamMember &Team) {
+          const int KMin   = MinLayerEdgeBot(IEdge);
+          const int KMax   = MaxLayerEdgeTop(IEdge);
+          const int KRange = vertRangeChunked(KMin, KMax);
+
+          parallelForInner(
+              Team, KRange, INNER_LAMBDA(int KChunk) {
+                 LocPseudoThicknessAux.computeVarsOnEdge(
+                     IEdge, KChunk, PseudoThick, NormalVelEdge);
+              });


+/// Destroy instance of SubmesoEddies
+void SubmesoEddies::destroyInstance() {
+   delete Instance;
+   Instance = nullptr;
+}


mwarusz · 2026-07-15T23:22:59Z

Testing

CTest unit tests

Machine: pm-cpu / pm-gpu / frontier
Compiler: gnu / gnugpu / craygnu-mphipcc
Build type: Release
Result: All tests passed (on all machines)

Polaris `omega_pr` suite

Baseline workdir: /pscratch/sd/m/mwarusz/omega-pr-testing/submeso/baseline-gnu
Baseline build: /pscratch/sd/m/mwarusz/omega-pr-testing/submeso/baseline-gnu/build
PR build: /pscratch/sd/m/mwarusz/omega-pr-testing/submeso/build-gnu
PR workdir: /pscratch/sd/m/mwarusz/omega-pr-testing/submeso/pr-gnu
Machine: pm-cpu
Compiler: gnu
Build type: Release
Log: /pscratch/sd/m/mwarusz/omega-pr-testing/submeso/pr-gnu/polaris_omega_pr.o55955301
Result: All tests passed

mwarusz · 2026-07-15T23:29:40Z

The baroclinic channel test is now running stably with the submesoscale eddy parametrization turned on. This PR is ready for review. However, I haven't checked that the parametrization has the intended effect, and I'm not sure that I'm the best person to do that. @vanroekel could you help with this kind of testing ?

vanroekel · 2026-07-23T00:01:41Z

@mwarusz I ran a couple tests with baroclinic channel and it's too hard to tell what the effects must be. We need to add a mixed layer. Let me look and see how straight forward that might be.

vanroekel · 2026-07-24T22:23:49Z

update - I have a mixed layer variant of baroclinic channel I have a test run in the queue on frontier. Hopefully will have results by Monday

vanroekel · 2026-08-11T21:38:03Z

+                 PseudoThickML, GradBuoyML, BVFreqML);
+
+             GradBuoyML /= PseudoThickML;
+             BVFreqML /= PseudoThickML;


@mwarusz for small ML this could be be problematic, it's not clear above in the MLD code if there is a floor. maybe it's not an issue though

I agree that we should probably add a tiny value here. MPAS-O has it.

vanroekel · 2026-08-11T21:38:50Z

+                 Team, Range{MinLyrEdgeBot, IndexMLEdge},
+                 INNER_LAMBDA(int K, Real &AccumThick, Real &AccumGradBuoy,
+                              Real &AccumBVFreq) {
+                    const Real PseudoThickKm1 =


If your function starts at MinLyrEdgeBot can this lead to values lower than min layer edge?

No, this variable is set to

((K - 1) >= MinLyrEdgeBot ? MeanPseudoThickEdge(IEdge, K - 1) : 0)

which is 0 for K = MinLyrEdgeBot. In the end an average of PseudoThickKm1 and PseudoThickK is used. This means that for K = MinLyrEdgeBot you get

PseudoThickAvg = 0.5 * (0 + MeanPseudoThickEdge(IEdge, MinLyrEdgeBot));

This is a kinda hacky treatment of the first half layer. I will add a comment to explain this.

vanroekel · 2026-08-11T21:43:11Z

@mwarusz in testing I'm getting NaN for EddyVelocity quickly. CoPilot added some guards on the ML average and zero initializing and it fixed the NaN issue. I can point you at what the changes made were if you'd like

mwarusz · 2026-08-11T22:05:33Z

@vanroekel

@mwarusz in testing I'm getting NaN for EddyVelocity quickly. CoPilot added some guards on the ML average and zero initializing and it fixed the NaN issue. I can point you at what the changes made were if you'd like

Please do.

vanroekel · 2026-08-11T22:15:43Z

here it is - https://github.com/vanroekel/E3SM/tree/temp-submeso-branch

There is some extra stuff that is adding more diagnostics as well.

mwarusz · 2026-08-11T22:39:20Z

Hmm, Copilot added this check

if (PseudoThickML > Tiny && MLDepthEdge > Tiny)

but afterwards it is also explicitly checking for NaNs and skipping calculations if it finds any. It would good to see if the first check is enough.

mwarusz requested a review from Copilot June 20, 2026 05:59

Copilot started reviewing on behalf of mwarusz June 20, 2026 05:59 View session

Copilot AI reviewed Jun 20, 2026

View reviewed changes

mwarusz force-pushed the omega/submesoscale-eddies branch 2 times, most recently from 1d3f283 to 9825eda Compare July 14, 2026 21:14

mwarusz requested review from katsmith133 and vanroekel July 15, 2026 23:29

vanroekel reviewed Aug 11, 2026

View reviewed changes

mwarusz added 13 commits August 24, 2026 16:31

Allow passing vertical coord to setScalar and setVector

5de77ae

Update set helpers to also provide element indices

4182eb1

Add submesocale eddies

aca7a2b

Add a helper for computing pseudo-thickness equation aux

6ed8061

Add a helper for computing tracer aux

d656a05

Add TransportAuxVars

8d561d8

Add a function to compute transport velocity

07f828f

Compute and use transport velocity where needed

7a0c5e3

Add computation of Brunt-Vaisala freq in vert aux

0a263f0

Add submesoscale contribution to transport velocity

c86fb35

Define submeso parametrization fields

a70bf19

Incorporate some copilot suggestions

da66f43

Adapt submeso eddies test to fill value changes

78ab73a

mwarusz and others added 5 commits August 24, 2026 16:31

Fix linear interpolation

1c691c5

Use tiny value for minimum Brunt-Vaisala freq

e6ca054

Add Omega user and developer docs for submesoscale eddies

c8e01ae

Add eddy velocity only for active layers

61b618f

Use multiple ranks in submeso eddies test

b50883a

mwarusz force-pushed the omega/submesoscale-eddies branch from 89aae38 to 3660296 Compare August 24, 2026 22:31

mwarusz added 4 commits August 24, 2026 16:33

Fix linting

b42aa84

Add a workaround for CUDA extended lambda issue

a10f6f1

Add a teamBarrier

d1c7b78

Cleanup unused variables

a7bd36d

mwarusz force-pushed the omega/submesoscale-eddies branch from 3660296 to a7bd36d Compare August 24, 2026 22:33

Uh oh!

Conversation

mwarusz commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mwarusz commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mwarusz commented Jul 15, 2026

Testing

CTest unit tests

Polaris omega_pr suite

Uh oh!

mwarusz commented Jul 15, 2026

Uh oh!

vanroekel commented Jul 23, 2026

Uh oh!

vanroekel commented Jul 24, 2026

Uh oh!

vanroekel Aug 11, 2026

Choose a reason for hiding this comment

Uh oh!

mwarusz Aug 11, 2026

Choose a reason for hiding this comment

Uh oh!

vanroekel Aug 11, 2026

Choose a reason for hiding this comment

Uh oh!

mwarusz Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vanroekel commented Aug 11, 2026

Uh oh!

mwarusz commented Aug 11, 2026

Uh oh!

vanroekel commented Aug 11, 2026

Uh oh!

mwarusz commented Aug 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mwarusz commented Jun 20, 2026 •

edited

Loading

mwarusz commented Jun 20, 2026 •

edited

Loading

Polaris `omega_pr` suite

mwarusz Aug 11, 2026 •

edited

Loading