Add Omega horizontal pressure gradient tests by xylar · Pull Request #465 · E3SM-Project/polaris

xylar · 2026-02-18T14:47:11Z

This merge adds three horiz_press_grad tests for the horizontal pressure-gradient acceleration (HPGA) in Omega:

salinity_gradient - salinity varies horizontally; temperature varies only with depth and layer pseudo-thicknesses are uniform
temperature_gradient - temperature varies horizontally; salinity varies only with depth and layer pseudo-thicknesses are uniform
ztilde_gradient - pseudo-height of layers are sloped; temperature and salinity vary only with depth (thus, HPGA should be close to zero)

The tests include :

a reference step that computes a high-fidelity reference solution (numerical quadrature in the vertical; a 4th-order gradient in the horizontal)
init steps at each of a list of horizontal and vertical resolutions that provide initial conditions and a Python implementation of the centered, 2nd-order HPGA
forward steps at each resolution that just computes the HPGA (in NormalVelocityTend) in Omega
an analysis step that checks the RMS difference between the Omega and Polaris centered HPGA (verification of the implementation) and plots the convergence of the HPGA with respect to the reference solution. Errors are raised if the Omega solution diverges too much from the Python implementation at any resolution or from the reference solution at the highest resolution. An error is also raised if the convergence rate is too poor.

Checklist

Developer's Guide has been updated
API documentation in the Developer's Guide (api.md) has any new or modified class, method and/or functions listed
Documentation has been built locally and changes look as expected
Testing comment in the PR documents testing used to verify the changes
New tests have been added to a test suite

xylar · 2026-02-18T15:24:11Z

This is build off of #464 so I will hold off a bit on asking for reviews and rebase once that (hopefully) goes in.

xylar · 2026-03-11T09:58:28Z

This needs to be updated to not use the Density0 Omega config option to be consistent with E3SM-Project/Omega#358.

cbegeman · 2026-04-13T19:22:06Z

Updated
I think the order of integration related to testing the pressure gradient might be

Turn off HPG term in tests that do not require it #529 with submodule update to include Add centered pressure gradient Omega#353
this PR
a polaris PR to extend Omega support for the overflow test case led by @mark-petersen
a polaris PR to extend Omega support for the seamount test case led by (?)

xylar · 2026-04-13T19:32:05Z

@cbegeman, I would like #529 to bring in the submodule update. Form there, I agree.

cbegeman · 2026-04-13T19:37:28Z

@xylar Thanks for pointing that out. Sounds good

sbrus89 · 2026-04-14T03:09:33Z

I'll add the submodule update tomorrow. Sorry I forgot to do that today.

cbegeman · 2026-04-14T19:54:36Z

+
+
+class Reference(OceanIOStep):
+    r"""


Suggested change

r"""

"""

I'll check on this. There may be a math reason this needs to be a literal string rather than decoding the back-slashes.

Ah, I didn't think of that

cbegeman · 2026-04-14T20:19:48Z

+- Omega RMS error versus reference (`omega_vs_reference.png`), including a
+  power-law fit and convergence slope, and
+- Omega RMS difference versus Python initialization (`omega_vs_python.png`).


Can we provide more detail here to explain exactly what we're evaluating against? It's not immediately apparent to me why, in order to evaluate the pressure gradient tendency at the midpoint of edges given the T,S,layerThickness fields at the midpoint of cells, we choose as "truth" a 4th-order reconstruction given T,S,dTdx,dSdx at the midpoint of edges (not sure that I got all these details right, just trying to be specific about what details would be helpful). I realize that some of this info might be in the design doc but I think it would be good to include here or in the description section.

Noted. I will try to do a better job of documenting this.

I made major revisions to the docs. Hopefully, this is clarified. Please have a look if you have time.

xylar · 2026-04-17T16:38:08Z

@sbrus89, I rebased this following #529. Could you give it one more test and let me know if you want anything changed? I'd like to get this merged pretty soon.

For now, just creates initial conditions in each column, including specific volume.

The vertical coordinate is z-tilde, but the z-tilde at the sea floor has to be found iteratively such that the geometric water-column thickness is as expected

The analysis fails if errors exceed the thresholds or if the convergence rate is outside the expected range.

Limit the convergence analysis to 6 km and higher. Add absolute error threshold for situations where the HPGA is too small for the normalize error to be useful.

Add 0.5 km resolution and lower convergence fit to <= 4 km. Switch reference solution to higher res (0.25 km). Adjust convergence thresholds.

This makes the problem more numerically challenging.

Drop coarsest resolutions (16, 8, 6 km) and add more fine resolutions (1.5 and 0.75 km).

Flesh out the description of the reference and init implelmentaitons of the HPGF.

xylar · 2026-04-17T16:57:29Z

I'm rerunning the omega_nightly suite on Frontier right now (with craygnu).

cbegeman · 2026-04-17T16:58:37Z

@xylar Thanks for expanding the docs. Unless I missed it, can you state that you are evaluating the pressure gradient at the one edge adjoining the two columns and that the x-axis is normal to that edge (or a similar corrected statement if I'm mistaken).

xylar · 2026-04-17T18:54:58Z

@cbegeman, I'm trying my best to clarify this further:

mesh

The mesh is planar with two adjacent ocean cells. For each resolution in
horiz_resolutions, the spacing between the two columns is set by that value
(in km).

The HPGA diagnostic is evaluated on the single internal horizontal edge that
connects the two columns, at each layer midpoint. In this page, x denotes
the along-layer horizontal direction used by Omega's horizontal gradient
operator. In the idealized two-column planar geometry, this direction follows
the line joining the two cell centers. It is therefore related to the shared
edge normal, but it is not intended to define a separate exact geometric
edge-normal coordinate.

vertical grid

The vertical coordinate is z-tilde with a uniform pseudo-height spacing for
each test in vert_resolutions.

The meaning of the along-layer x direction depends on the task variant. In
the salinity_gradient and temperature_gradient tests, the z-tilde
interfaces are level, so pressure surfaces are also horizontally level except
where they intersect the bathymetry. In the ztilde_gradient test, the
prescribed z-tilde gradient tilts the layers, so the pressure surfaces are
sloped and the along-layer direction follows those sloping layers.

The reference step uses a finer spacing vert_res chosen so that every test
spacing is an integer multiple of 2 * vert_res. This allows reference
interfaces to align with test midpoints for exact subsampling in analysis.

Although I do keep flat z-tilde layers in 2 of the 3 tests, this is only true until we hit the bathymetry, which is flat in geometric height but not in z-tilde. The 3rd test has tilted layers and the gradient in computed along layer, not normal to the edge.

xylar · 2026-04-17T18:56:03Z

I tried to create a figure illustrating the configuration but it was not really good enough to be helpful. I think a more cartoonish illustration might show the concepts but wouldn't be particularly true to the test. Happy to keep iterating.

cbegeman

@xylar I think what you added provides enough clarity. I think a diagram could be reserved for the Omega documentation of the pgrad algorithm (I don't recall whether it already has one). Thanks for iterating!

xylar · 2026-04-17T20:09:12Z

@cbegeman, thank you for pushing things to be better.

sbrus89

I tested this by doing a local merge into main on pm-cpu. All tests pass with baseline comparisons to the current main except for the salinity_gradient test, which this PR adds to the omega_pr suite:

Polaris `omega_pr` suite

Baseline workdir: /global/homes/s/sbrus/scratch/polaris_constant_eos_omega_pr_baseline/
Baseline build: /global/homes/s/sbrus/scratch/polaris_constant_eos_omega_pr_baseline/build
PR build: /global/homes/s/sbrus/scratch/polaris_add-two-column/build
PR workdir: /global/homes/s/sbrus/scratch/polaris_add-two-column
Machine: pm-cpu
Compiler: gnu
Build type: Release
Log: not found
Result:
- Diffs (1 of 10):
  - ocean/horiz_press_grad/salinity_gradient

sbrus89 · 2026-04-21T21:48:15Z

Thanks for all your work on this @xylar!

xylar · 2026-04-22T05:43:16Z

Thanks for reviewing and merging @sbrus89!

xylar added enhancement New feature or request ocean Related to the ocean component Omega PR required The polaris changes won't work with the current Omega submodule and require an update labels Feb 19, 2026

xylar self-assigned this Feb 19, 2026

xylar requested a review from sbrus89 February 19, 2026 07:27

sbrus89 mentioned this pull request Feb 24, 2026

Add centered pressure gradient E3SM-Project/Omega#353

Merged

19 tasks

xylar mentioned this pull request Mar 11, 2026

Get Omega reference density from polaris.constants when computing z-tilde #489

Merged

1 task

xylar force-pushed the add-omega-two-column branch from c5259f4 to 5edaee3 Compare March 11, 2026 11:00

xylar force-pushed the add-omega-two-column branch from 5edaee3 to a385f6b Compare April 12, 2026 08:18

cbegeman reviewed Apr 14, 2026

View reviewed changes

xylar force-pushed the add-omega-two-column branch from a385f6b to c613e45 Compare April 17, 2026 16:30

xylar marked this pull request as ready for review April 17, 2026 16:36

xylar force-pushed the add-omega-two-column branch from c613e45 to 6681b49 Compare April 17, 2026 16:36

xylar added Omega PR finished The polaris changes required an update to the Omega submodule and this is now finished and removed Omega PR required The polaris changes won't work with the current Omega submodule and require an update labels Apr 17, 2026

xylar added 7 commits April 17, 2026 18:41

Fix single_column docstring

a4a98bb

Add two_column test for TEOS-10

19a6b58

For now, just creates initial conditions in each column, including specific volume.

Use z-tilde rather than z-star in two_column

900a532

Compute and output geometric z in two_column init

c4a5580

Iteratively compute p and spec vol in two_column

58680d4

Find iteratively find z-tilde of sea floor

0108269

The vertical coordinate is z-tilde, but the z-tilde at the sea floor has to be found iteratively such that the geometric water-column thickness is as expected

Add a function for computing geometric height by quadrature

2aaf464

xylar added 15 commits April 17, 2026 18:41

Add thresholds to analysis step

d9a8554

The analysis fails if errors exceed the thresholds or if the convergence rate is outside the expected range.

Add a temperature gradient task

fc307cd

Add 6 km and 3 km resolutions

17c9b8f

Limit the convergence analysis to 6 km and higher. Add absolute error threshold for situations where the HPGA is too small for the normalize error to be useful.

Rename two_column --> horiz_press_grad

1669ea2

Switch back to absolute RMS error or difference in analysis

388653e

Add 0.5 km resolution and lower convergence fit to <= 4 km. Switch reference solution to higher res (0.25 km). Adjust convergence thresholds.

Vary the salinity gradient with depth

3c999ab

This makes the problem more numerically challenging.

Stop iterating in init if converged

9f45c89

Change resolutions

87f6159

Drop coarsest resolutions (16, 8, 6 km) and add more fine resolutions (1.5 and 0.75 km).

Fix reference vertical res

4e18421

Add horiz_press_grad tests to Omega suites

c3529f8

Add horiz_press_grad to the docs

1a9fba9

Fix docstring for Reference step

76a4726

Fix f-string for python <3.12

d2aaa9d

Remove rho0 config options from horiz press grad

9d79e83

Improve the documentation

9e83366

Flesh out the description of the reference and init implelmentaitons of the HPGF.

xylar force-pushed the add-omega-two-column branch from 6681b49 to 9e83366 Compare April 17, 2026 16:41

Add more details on the x coordinate in the docs

2a6184f

cbegeman approved these changes Apr 17, 2026

View reviewed changes

xylar assigned sbrus89 and unassigned xylar Apr 20, 2026

sbrus89 approved these changes Apr 21, 2026

View reviewed changes

sbrus89 merged commit d4bcf57 into E3SM-Project:main Apr 21, 2026
5 checks passed

xylar deleted the add-omega-two-column branch April 22, 2026 05:42

Conversation

xylar commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xylar commented Feb 18, 2026

Uh oh!

xylar commented Mar 11, 2026

Uh oh!

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

Uh oh!

Uh oh!

xylar commented Apr 13, 2026

Uh oh!

cbegeman commented Apr 13, 2026

Uh oh!

sbrus89 commented Apr 14, 2026

Uh oh!

cbegeman Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

xylar Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

cbegeman Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

cbegeman Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

xylar Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

xylar Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

xylar commented Apr 17, 2026

Uh oh!

xylar commented Apr 17, 2026

Uh oh!

cbegeman commented Apr 17, 2026

Uh oh!

xylar commented Apr 17, 2026

mesh

vertical grid

Uh oh!

xylar commented Apr 17, 2026

Uh oh!

cbegeman left a comment

Choose a reason for hiding this comment

Uh oh!

xylar commented Apr 17, 2026

Uh oh!

sbrus89 left a comment

Choose a reason for hiding this comment

Polaris omega_pr suite

Uh oh!

Uh oh!

sbrus89 commented Apr 21, 2026

Uh oh!

xylar commented Apr 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

xylar commented Feb 18, 2026 •

edited

Loading

cbegeman commented Apr 13, 2026 •

edited

Loading

Polaris `omega_pr` suite