E3SM-Project · xylar · Nov 4, 2025 · Nov 4, 2025 · Nov 5, 2025 · Nov 5, 2025
diff --git a/docs/developers_guide/ocean/api.md b/docs/developers_guide/ocean/api.md
@@ -198,6 +198,33 @@
    viz.Viz.run
 ```
 
+### horiz_press_grad
+
+```{eval-rst}
+.. currentmodule:: polaris.tasks.ocean.horiz_press_grad
+
+.. autosummary::
+   :toctree: generated/
+
+   add_horiz_press_grad_tasks
+
+   task.HorizPressGradTask
+   task.HorizPressGradTask.configure
+
+   reference.Reference
+   reference.Reference.run
+
+   init.Init
+   init.Init.run
+
+   forward.Forward
+   forward.Forward.setup
+
+   analysis.Analysis
+   analysis.Analysis.setup
+   analysis.Analysis.run
+```
+
 ### ice_shelf_2d
 
 ```{eval-rst}

diff --git a/docs/developers_guide/ocean/tasks/horiz_press_grad.md b/docs/developers_guide/ocean/tasks/horiz_press_grad.md
@@ -0,0 +1,72 @@
+(dev-ocean-horiz-press-grad)=
+
+# horiz_press_grad
+
+The {py:class}`polaris.tasks.ocean.horiz_press_grad.task.HorizPressGradTask`
+provides two-column Omega tests for pressure-gradient-acceleration (`HPGA`)
+accuracy and convergence across horizontal and vertical resolutions.
+
+The task family includes three variants:
+
+- `salinity_gradient`
+- `temperature_gradient`
+- `ztilde_gradient`
+
+## framework
+
+The config options for these tests are described in
+{ref}`ocean-horiz-press-grad` in the User's Guide.
+
+The task dynamically rebuilds `init` and `forward` steps in `configure()` so
+user-supplied `horiz_resolutions` and `vert_resolutions` in config files are
+reflected in the work directory setup.
+
+### reference
+
+The class {py:class}`polaris.tasks.ocean.horiz_press_grad.reference.Reference`
+defines a step that builds a high-fidelity reference HPGA solution in
+`reference_solution.nc`.
+
+It computes pseudo-height and geometric-height profiles on a refined reference
+grid, evaluates TEOS-10 specific volume, and computes HPGA at the center
+column using a 4th-order finite-difference stencil.
+
+### init
+
+The class {py:class}`polaris.tasks.ocean.horiz_press_grad.init.Init`
+defines one step per `(horiz_res, vert_res)` pair.
+
+Each `init` step:
+
+- builds and culls a planar two-cell mesh,
+- sets up z-tilde vertical coordinates and profile fields,
+- iteratively adjusts pseudo-bottom depth to match target geometric
+  water-column thickness, and
+- writes `culled_mesh.nc` and `initial_state.nc`.
+
+### forward
+
+The class {py:class}`polaris.tasks.ocean.horiz_press_grad.forward.Forward`
+defines one model step per horizontal resolution.
+
+It runs Omega from the corresponding `init` output and writes `output.nc`
+(with `NormalVelocityTend` validation), using options from `forward.yaml`.
+
+### analysis
+
+The class {py:class}`polaris.tasks.ocean.horiz_press_grad.analysis.Analysis`
+compares each `forward` result with:
+
+- the high-fidelity reference solution, and
+- the Python-computed HPGA from `initial_state.nc`.
+
+The step writes:
+
+- `omega_vs_reference.nc` and `omega_vs_reference.png`
+- `omega_vs_python.nc` and `omega_vs_python.png`
+
+and enforces regression criteria from `[horiz_press_grad]`, including:
+
+- allowed convergence-slope range for Omega-vs-reference,
+- high-resolution RMS threshold for Omega-vs-reference, and
+- RMS threshold for Omega-vs-Python consistency.
diff --git a/docs/developers_guide/ocean/tasks/index.md b/docs/developers_guide/ocean/tasks/index.md
@@ -13,6 +13,7 @@ cosine_bell
 customizable_viz
 external_gravity_wave
 geostrophic
+horiz_press_grad
 divergent_2d
 ice_shelf_2d
 inertial_gravity_wave

diff --git a/docs/users_guide/ocean/tasks/horiz_press_grad.md b/docs/users_guide/ocean/tasks/horiz_press_grad.md
@@ -0,0 +1,108 @@
+(ocean-horiz-press-grad)=
+
+# horizontal pressure gradient
+
+## description
+
+The `horiz_press_grad` tasks in `polaris.tasks.ocean.horiz_press_grad`
+exercise Omega's hydrostatic pressure-gradient acceleration (`HPGA`)
+for a two-column configuration with prescribed horizontal gradients.
+
+Each task includes:
+
+- a high-fidelity `reference` solution for HPGA,
+- an `init` step at each horizontal/vertical resolution pair,
+- a single-time-step `forward` run at each horizontal resolution, and
+- an `analysis` step comparing Omega output with both the reference and
+  Python-initialized HPGA.
+
+The tasks currently provided are:
+
+```
+ocean/horiz_press_grad/salinity_gradient
+ocean/horiz_press_grad/temperature_gradient
+ocean/horiz_press_grad/ztilde_gradient
+```
+
+```{image} images/horiz_press_grad_salin_grad.png
+:align: center
+:width: 600 px
+```
+## supported models
+
+These tasks currently support Omega only.
+
+## 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).
+
+## vertical grid
+
+The vertical coordinate is `z-tilde` with a uniform pseudo-height spacing for
+each test in `vert_resolutions`.
+
+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.
+
+(ocean-horiz-press-grad-config)=
+## config options
+
+Shared options are in section `[horiz_press_grad]`:
+
+```cfg
+# resolutions in km (distance between the two columns)
+horiz_resolutions = [4.0, 3.0, 2.0, 1.5, 1.0, 0.75, 0.5]
+
+# vertical resolution in m for each two-column setup
+vert_resolutions = [4.0, 3.0, 2.0, 1.5, 1.0, 0.75, 0.5]
+
+# geometric sea-surface and sea-floor midpoint values and x-gradients
+geom_ssh_mid = 0.0
+geom_ssh_grad = 0.0
+geom_z_bot_mid = -500.0
+geom_z_bot_grad = 0.0
+
+# pseudo-height bottom midpoint and x-gradient
+z_tilde_bot_mid = -576.0
+z_tilde_bot_grad = 0.0
+
+# midpoint and gradient node values for piecewise profiles
+z_tilde_mid = [0.0, -48.0, -144.0, -288.0, -576.0]
+z_tilde_grad = [0.0, 0.0, 0.0, 0.0, 0.0]
+
+temperature_mid = [22.0, 20.0, 14.0, 8.0, 5.0]
+temperature_grad = [0.0, 0.0, 0.0, 0.0, 0.0]
+
+salinity_mid = [35.6, 35.4, 35.0, 34.8, 34.75]
+salinity_grad = [0.0, 0.0, 0.0, 0.0, 0.0]
+
+# reference settings
+reference_quadrature_method = gauss4
+reference_horiz_res = 0.25
+```
+
+The three task variants specialize one horizontal gradient field:
+
+- `salinity_gradient`: nonzero `salinity_grad`
+- `temperature_gradient`: nonzero `temperature_grad`
+- `ztilde_gradient`: nonzero `z_tilde_bot_grad`
+
+## time step and run duration
+
+The `forward` step performs one model time step and outputs pressure-gradient
+diagnostics used in the analysis.
+
+## analysis
+
+The `analysis` step computes and plots:
+
+- 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`).
+
+The corresponding tabulated data are written to
+`omega_vs_reference.nc` and `omega_vs_python.nc`.
+
diff --git a/docs/users_guide/ocean/tasks/images/horiz_press_grad_salin_grad.png b/docs/users_guide/ocean/tasks/images/horiz_press_grad_salin_grad.png
diff --git a/docs/users_guide/ocean/tasks/index.md b/docs/users_guide/ocean/tasks/index.md
@@ -13,6 +13,7 @@ cosine_bell
 customizable_viz
 external_gravity_wave
 geostrophic
+horiz_press_grad
 divergent_2d
 ice_shelf_2d
 inertial_gravity_wave

diff --git a/polaris/ocean/model/mpaso_to_omega.yaml b/polaris/ocean/model/mpaso_to_omega.yaml
@@ -22,6 +22,12 @@ variables:
   cellsOnVertex: CellsOnVertex
   edgesOnVertex: EdgesOnVertex
 
+  # vertical coordinate
+  minLevelCell: MinLayerCell
+  maxLevelCell: MaxLayerCell
+  # currently hard-coded in horizontal mesh
+  # bottomDepth: BottomDepth
+
   # tracers
   temperature: Temperature
   salinity: Salinity

diff --git a/polaris/suites/ocean/omega_nightly.txt b/polaris/suites/ocean/omega_nightly.txt
@@ -1,4 +1,7 @@
 ocean/planar/barotropic_gyre/munk/free-slip
+ocean/horiz_press_grad/salinity_gradient
+ocean/horiz_press_grad/temperature_gradient
+ocean/horiz_press_grad/ztilde_gradient
 ocean/planar/manufactured_solution/convergence_both/default
 ocean/planar/manufactured_solution/convergence_both/del2
 ocean/planar/manufactured_solution/convergence_both/del4

diff --git a/polaris/suites/ocean/omega_pr.txt b/polaris/suites/ocean/omega_pr.txt
@@ -1,6 +1,7 @@
 #ocean/planar/barotropic_channel/default  # Supported but fails
 ocean/planar/merry_go_round/default
 ocean/planar/barotropic_gyre/munk/free-slip
+ocean/horiz_press_grad/salinity_gradient
 ocean/planar/manufactured_solution/convergence_both/default
 ocean/planar/manufactured_solution/convergence_both/del2
 ocean/planar/manufactured_solution/convergence_both/del4

diff --git a/polaris/tasks/ocean/add_tasks.py b/polaris/tasks/ocean/add_tasks.py
@@ -7,6 +7,7 @@
     add_external_gravity_wave_tasks as add_external_gravity_wave_tasks,
 )
 from polaris.tasks.ocean.geostrophic import add_geostrophic_tasks
+from polaris.tasks.ocean.horiz_press_grad import add_horiz_press_grad_tasks
 from polaris.tasks.ocean.ice_shelf_2d import add_ice_shelf_2d_tasks
 from polaris.tasks.ocean.inertial_gravity_wave import (
     add_inertial_gravity_wave_tasks as add_inertial_gravity_wave_tasks,
@@ -36,6 +37,7 @@ def add_ocean_tasks(component):
     add_baroclinic_channel_tasks(component=component)
     add_barotropic_channel_tasks(component=component)
     add_barotropic_gyre_tasks(component=component)
+    add_horiz_press_grad_tasks(component=component)
     add_ice_shelf_2d_tasks(component=component)
     add_inertial_gravity_wave_tasks(component=component)
     add_internal_wave_tasks(component=component)

diff --git a/polaris/tasks/ocean/horiz_press_grad/__init__.py b/polaris/tasks/ocean/horiz_press_grad/__init__.py
@@ -0,0 +1,19 @@
+from polaris.tasks.ocean.horiz_press_grad.task import HorizPressGradTask
+
+
+def add_horiz_press_grad_tasks(component):
+    """
+    Add tasks for various tests involving the horizonal pressure-gradient
+    acceleration between two adjacent ocean columns
+
+    Parameters
+    ----------
+    component : polaris.tasks.ocean.Ocean
+        the ocean component that the tasks will be added to
+    """
+    for name in [
+        'salinity_gradient',
+        'temperature_gradient',
+        'ztilde_gradient',
+    ]:
+        component.add_task(HorizPressGradTask(component=component, name=name))