horiz_press_grad

The 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 horizontal pressure gradient in the User’s Guide.

The User’s Guide is also place to go for the mathematical formulation, the reference-solution definition, and the algorithmic interpretation of the two task baselines. This page focuses on how that workflow is implemented in the code.

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 polaris.tasks.ocean.horiz_press_grad.reference.Reference defines a step that builds a high-fidelity reference HPGA solution in reference_solution.nc.

In implementation terms, Reference.run() does four things:

  • determines the refined vertical resolution from the configured test resolutions,

  • builds the reference columns and their thermodynamic profiles,

  • computes the reference diagnostic fields, and

  • writes reference_solution.nc.

Most of the work is organized through the private helpers _get_ssh_z_bot(), _get_z_tilde_t_s_nodes(), _compute_column(), and _integrate_geometric_height(). Together, these routines reconstruct the column state, convert from pseudo-height to geometric height, and populate the reference dataset.

reference_solution.nc contains both the baseline fields used directly in analysis and additional diagnostics that are useful when debugging or inspecting the reference calculation, including HPGAMid, HPGAInter, MontgomeryMid, MontgomeryInter, dMdxMid, dalphadxMid, PEdgeMid, and the valid-gradient masks.

init

The 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.

The implementation is centered around Init.run() and three helpers:

  • _init_z_tilde_vert_coord() initializes the vertical coordinate for each column separately,

  • _interpolate_t_s() reconstructs temperature and salinity on the test grid,

  • _compute_montgomery_and_hpga() computes the Python-side HPGA diagnostic and related output fields.

initial_state.nc stores both the fields needed by Omega and the offline diagnostics later used in analysis, including PressureMid, SpecVol, Density, GeomZMid, GeomZInter, MontgomeryMid, MontgomeryInter, HPGA, dMdxMid, dalphadxMid, PEdgeMid, and dSAdxMid.

forward

The 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 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.

Implementation-wise, Analysis.run() reads the reference, init, and forward outputs for each configured horizontal resolution, then uses helper routines such as _get_internal_edge(), _get_forward_z_tilde_edge_mid(), _sample_reference_without_interpolation(), _check_vertical_match(), _rms_error(), and _power_law_fit() to produce the comparison datasets and plots.

The key code-level distinction is that the reference comparison is built from reference_solution.nc, whereas the implementation-consistency comparison is built from initial_state.nc. The forward solution always comes from output.nc via NormalVelocityTend.