Add submesoscale eddy parametrization

[mwarusz]

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

• Documentation:
  • User's Guide has been updated
  • Developer's Guide has been updated
  • Documentation has been built locally and changes look as expected
• Linting
  • Pre-commit run locally
• Building
  • CMake build does not produce any new warnings from changes in this PR
• Testing
  • Add a comment to the PR titled Testing with the following:
    • Which machines CTest unit tests
      have been run on and indicate that are all passing.
    • The Polaris omega_pr test suite
      has passed, using the Polaris e3sm_submodules/Omega baseline
    • Document machine(s), compiler(s), and the build path(s) used for -p for both the baseline (Polaris e3sm_submodules/Omega) and the PR build
    • Indicate "All tests passed" or document failing tests
    • Document testing used to verify the changes including any tests that are added/modified/impacted.
  • New tests:
    • CTest unit tests for new features have been added per the approved design.

[mwarusz]

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.