Port sphere transport time-varying prescribed velocity fields

[cbegeman]

This PR ports time-varying prescribed velocity fields for the sphere transport cases:

• https://docs.e3sm.org/polaris/main/users_guide/ocean/tasks/correlated_tracers_2d.html
• https://docs.e3sm.org/polaris/main/users_guide/ocean/tasks/divergent_2d.html
• https://docs.e3sm.org/polaris/main/users_guide/ocean/tasks/nondivergent_2d.html

and provides an option for the constant prescribed velocity field in the sphere transport case:

• https://docs.e3sm.org/polaris/main/users_guide/ocean/tasks/rotation_2d.html

Checklist

• [N/A] Documentation:
  • [N/A] Design document has been generated and added to the docs
  • [N/A] User's Guide has been updated
  • [N/A] Developer's Guide has been updated
  • [N/A] 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.
    • [N/A] Performance related PRs: Please include a relevant PACE experiment link documenting performance before and after.
  • [N/A] New tests:
    • [N/A] CTest unit tests for new features have been added per the approved design.
    • Polaris tests for new features have been added per the approved design (and included in a test suite) See Add omega support for time-variant sphere transport flows polaris#500
• Stealth Features
  • [N/A] If any stealth features are included in the PR, please confirm that they have been documented.

[cbegeman]

@overfelt Good catch! Thanks for investigating. Let me know when it's ready for me to retest.

[hyungyukang]

@cbegeman, @overfelt , As we discussed in yesterday’s meeting, I looked over this PR and made a few RK4-related changes in Omega.

I think the results are now correct. Omega and MPAS-O show the same convergence rate in the divergent_2d test when using 3rd-order horizontal tracer advection (tracer FCT disabled):

I will commit the changes once I confirm them with additional tests.

[hyungyukang]

nondivergent_2d test also works, but the convergence rates differ slightly, with 1.963 in Omega and 1.953 in MPAS-O.

[cbegeman]

@hyungyukang That's great news! Can you link to the PR that has those RK4 changes when you post it (assuming it's not #392)?

[cbegeman]

@hyungyukang I added you as a reviewer to this PR in case you noticed anything as you've tested it.

[hyungyukang]

@hyungyukang That's great news! Can you link to the PR that has those RK4 changes when you post it (assuming it's not #392)?

Sure, I will. Would it be okay for me to push the code directly to your branch omega/port-sphere-transport, or would you prefer that I create a separate branch from yours and merge it later?

[cbegeman]

@hyungyukang Hmm, I think it's likely that your changes are fairly unrelated to this PR so it might make more sense to get them in first unless you're concerned about having a good way to test those changes.

[hyungyukang]

@cbegeman , the changes I made are based on this PR. Here's the branch (https://github.com/hyungyukang/Omega/tree/omega/port-sphere-transport-timestepping-fix)

And here is the comparison between your omega/port-sphere-transport and my fix:
Comp: cbegeman/port-sphere-transport VS hyungyukang/port-sphere-transport-timestepping-fix

If you prefer, I can open a PR against your repo to merge these changes, since your branch is the base.

[cbegeman]

@hyungyukang That commit 0552d59 does seem like it belongs with this PR. Go ahead and push it or let me know if you have trouble and I can cherry-pick it.

Note that I have rebased this branch onto develop recently so just make sure that you rebase your branch onto this one

[hyungyukang]

@cbegeman , I’ve pushed the changes directly to this PR and reran the test with divergent_2d. The results look the same as those shown in the comment above. Are there any other tests you would recommend trying besides divergent_2d and nondivergent_2d?

[cbegeman]

@hyungyukang This PR also includes this test: https://docs.e3sm.org/polaris/main/users_guide/ocean/tasks/correlated_tracers_2d.html. I expect that it may not produce good results without FCT but we should try it anyhow. I'm running these tests myself as well.

[cbegeman]

I successfully ran this branch with the sphere_transport_with_viz suite from E3SM-Project/polaris#500

rotation_2d

divergent_2d

nondivergent_2d

correlated_tracers_2d

[cbegeman]

For all MPAS-O results without FCT, the convergence rates for tracer1 for each case were the same as or worse than Omega, which is satisfactory.

The overshoots for the correlated_tracers_2d case were also similar (Omega shown):

There is somewhat different behavior for the filament preservation diagnostic (nondivergent_2d, https://gmd.copernicus.org/articles/5/887/2012/gmd-5-887-2012.pdf), generally indicating that Omega is doing better than MPAS-O with FCT (values closer to the 1-line) (Omega top, mpas-o bottom):

[cbegeman]

Testing

All CTests pass on pm, cpu. No new CTests were added.
The Polaris Omega PR suite passes and is BFB with main + Omega submodule with the exception of the rotation_2d which is expected to be non-BFB along with all other sphere_transport tests.

### Polaris `omega_pr` suite
- Baseline workdir: `//pscratch/sd/c/cbegeman/polaris-scratch/main-omega-develop-20260504/`
- Baseline build: `/pscratch/sd/c/cbegeman/polaris-scratch/main-omega-develop-20260504/build`
- PR build: `/pscratch/sd/c/cbegeman/polaris-scratch/spheretransport-omega-prescribe-20260429/build`
- PR workdir: `/pscratch/sd/c/cbegeman/polaris-scratch/spheretransport-omega-prescribe-20260429`
- Machine: `pm-cpu`
- Compiler: `gnu`
- Build type: `Release`
- Log: not found
- Result:
  - Diffs (2 of 10):
    - `ocean/spherical/qu/rotation_2d`
    -  `ocean/spherical/icos/rotation_2d`

[cbegeman]

@hyungyukang and @overfelt Can you review this PR or let me know if you will be unable to review this week? Thanks so much!

[hyungyukang]

@cbegeman , thanks for the results! I will finish by this Thursday.

[cbegeman]

@overfelt Thank you for reviewing and your help debugging!