Add velocity-component reconstruction for I/O

[xylar]

Add ZonalVelocity and MeridionalVelocity as fields available for I/O in Omega. Omega carries only the edge-normal component of the velocity, so the zonal and meridional components at cell centers are reconstructed from it using the least-squares stencil and weights already supplied by the mesh file. The two new fields are registered with the auxiliary state and can be requested by any I/O stream. They are computed once per time step, and only when something asks for them. This also replaces the hardcoded placeholder value that surface coupling was exporting to the coupler as the surface velocity.

---

What this addresses

Omega is a C-grid model and stores only the edge-normal velocity, so there has never been a way to look at the velocity as a vector at cell centers. That has two consequences. Analysis and comparison against MPAS-Ocean output are awkward, since MPAS-Ocean writes velocityZonal and velocityMeridional. And more concretely, OcnToCplFields::updateFields had a // TODO: Implement vector reconstruction for velocity field and exported a hardcoded ConstSfcVelocity = 1e-4 to the coupler in place of a real surface velocity.

The machinery to fix this already landed in #480, which added the VectorReconOnCell operator plus the mesh-supplied stencil and weights (NEdgesReconOnCell, ReconStencilCell, ReconWeightsCell) that it needs. Nothing in src/ called it, and it only supported a single vertical layer on spherical meshes. This PR builds on that.

Direction of the solution

VectorReconOnCell gains an overload that takes a vertical index, so it can reconstruct one layer of a multi-layer field. It is the existing single-layer form with an index added, since the reconstruction is independent in each layer. The Cartesian to local geographic rotation is factored into a helper shared by both overloads. Note that neither the new overload nor anything else added here uses vertical chunking, in line with the direction of #473.

Whether the reconstruction is available is now treated as a property of the mesh file rather than of the geometry. The stencil and weights are precomputed as a mesh preprocessing step rather than by Omega, so Decomp detects their presence by attempting the read of NEdgesReconOnCell and treating a failure as "not present", and carries the answer as Decomp::HasVectorRecon and HorzMesh::HasVectorRecon. Previously all of this was gated on OnSphere, which meant planar meshes could never have it and forced Decomp to parse the OnSphere attribute itself, duplicating what HorzMesh does properly. That duplicate parsing is removed. The practical effect is that planar meshes work as soon as their mesh files carry the arrays, while planar meshes that predate them stay readable.

The fields themselves live in a new VelocityReconAuxVars auxiliary variable class, following the pattern of KineticAuxVars, and are registered into the existing AuxiliaryState field group. On a planar mesh the reconstructed vector already lies in the plane of the mesh, so the two variables hold the Cartesian x and y components instead of zonal and meridional ones.

They are driven by a new AuxiliaryState::computeVelocityRecon, deliberately kept out of computeAll. Nothing in the Omega equations reads these, so computing them once per time stepper stage would be wasted work; ocnRun calls them once per step instead, on the state the step just produced. They are also skipped entirely unless something needs them, which is decided by a new IOStream::isFieldRequested that reports whether a field is in the contents of any defined stream. Since validation is what expands a group name into its member fields, that answer is only meaningful after validation, so an unvalidated stream conservatively answers yes and the computation is done rather than skipped.

Surface coupling needs the reconstruction regardless of what the streams say, so SfcCoupling::init calls AuxiliaryState::requireVelocityRecon to force it on, and checks the mesh supplies the reconstruction data so a coupled run on a mesh without it fails at initialization rather than at the first time step. OcnToCplFields::updateFields then averages the real surface values in place of the 1e-4 placeholder.

Using the new fields

They are registered but are not in the contents of any stream by default, so add them to a stream to have them written:

      Contents:
        - VelocityZonalCell
        - VelocityMeridionalCell

Requesting them on a mesh whose file did not supply the reconstruction stencil and weights is an error, as is running coupled with such a mesh.

Tests

HORZ_OPERATORS_TEST gains a multi-layer check in testVectorRecon, alongside the existing single-layer one. Each layer holds the exact field scaled by a layer-dependent factor, so a reconstruction that mixed layers or reused a single layer shows up as an error. The error measures are normalized by the exact field, so a per-layer constant factor leaves them unchanged and the same expected error values apply as for the single-layer case.

SFC_COUPLING_TEST now checks the exported surface velocity instead of skipping it, comparing So_u and So_v against the reconstruction in the surface layer. At NAccumSteps == 0 the running average is exactly the single sampled value, so the comparison is exact, as it already is for temperature and salinity. This test now also initializes VertAdv and AuxiliaryState, which surface coupling depends on.

DECOMP_TEST gates its existing reconstruction stencil checks on HasVectorRecon rather than OnSphere.

Planar meshes

The code accepts planar meshes with reconstruction data, but no such mesh file exists yet, so the planar leg of testVectorRecon still returns early and this has only been exercised on spherical meshes. Generating one requires a Polaris fix: construct_rotation_matrix in polaris/mesh/reconstruct.py returned an all-ones matrix rather than the identity for planar meshes, which collapsed the local tangent frame and produced silently wrong weights. Reconstructing a uniform field on PlanarPeriodic48x48 gave a mean of (0.729, 0.729) for an exact (1.0, 0.5); with the identity it is exact to 2.7e-13. Weights on a spherical mesh are bit-identical before and after. That fix, with tests, is on the Polaris branch fix-planar-velocity-reconstruction. Enabling planar meshes here is left to a follow-up once it has merged and planar mesh files have been regenerated.

Checklist

• Documentation:

  • Design document has been generated and added to the docs
  • 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

  aurora, oneapi-ifx, mpich

  • CTests Pass
  • Polaris omega_pr Pass

  chrysalis, oneapi-ifx, openmpi

  • CTests Pass
  • Polaris omega_pr Pass

  frontier, craygnu, mpich

  • CTests Pass
  • Polaris omega_pr Pass

  frontier, craygnu-mphipcc, mpich

  • CTests Pass
  • Polaris omega_pr Pass

  pm-cpu, gnu, mpich

  • CTests Pass
  • Polaris omega_pr Pass

  pm-gpu, gnugpu, mpich

  • CTests Pass
  • Polaris omega_pr Pass

• Provide relevant details in 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.

• Performance related PRs: Please include a relevant PACE experiment link documenting performance before and after.

• New tests:

  • 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)

• Stealth Features

  • If any stealth features are included in the PR, please confirm that they have been documented.

[xylar]

This work is motivated by the need for reconstructed velocity components for analysis work in Polaris before the Sept. 15th deadline.

[xylar]

Needs to have the velocity reconstruction coefficients added to planar meshes for CTests, following the fix from E3SM-Project/polaris#721.

[xylar]

Early CTesting

CTest unit tests:

• Machine: chrysalis
• Compiler: intel
• Build type: Release
• Result: All tests passed
• Log: /gpfs/fs1/home/ac.xylar/e3sm_work/polaris/fix-planar-velocity-reconstruction/build_omega/build_chrysalis_intel/ctests.log