Always take the shortest path between section waypoints

[hdrake]

Addresses r3752599198, r3752605844 and r3752736092 from the review of MOM6-community#47 (MOM6-community#47, review 4899521952). Targets topology-driven-neighbors.

Shortest path, always

Every segment follows the shortest path between its two waypoints. Raw longitudes are never read as an instruction to go the long way round, so a segment written 0 -> 270 along a parallel runs 90° west. The old "each segment must span less than 180 degrees" ValueError is gone.

The walk already did the right thing — the constant-latitude progress metric is sin²(Δlon/2), periodic in 360° and monotonic in |Δlon| up to 180° — only _check_segment_span refused to let such a segment through. This also fixes segments that were wrongly rejected before: 350 -> 10 (20° east across the prime meridian) and -170 -> 170 (20° west across the dateline) now work.

Three curve options

value	behaviour
"great circle"	unchanged — every segment follows the geodesic
"latitude circle"	every segment follows a parallel; a segment whose endpoints do not share a latitude raises
"latitude and great circle" (new)	decided per segment — parallels where the endpoints share a latitude, geodesics everywhere else

"latitude circle" now means what it says, meridional segments included. They were previously waved through on the grounds that a meridian is unambiguous, and that was hiding a real failure: the constant-latitude metric is flat along a meridian, so the walk admits no neighbour and falls through to a fallback. On ECCO LLC90, grid_section(grid, [0., 0.], [80., 60.], curve="latitude circle") raised RuntimeError: Should have reached the endpoint by now. in that direction while 60 -> 80 traced fine. That failure is pre-existing on the base branch, not introduced here. It is now either refused with a clear message or, under the combined option, routed to the geodesic and traced identically both ways (49 points each, exact reverses).

There is one ambiguity error, shared by all options: endpoints written exactly half a circle apart, where neither way round is shorter. It names the measure it reports — degrees of longitude along the parallel, or degrees of arc.

Tolerances

Two separately named constants replace the single SEGMENT_ATOL_DEG, because they were never the same quantity:

• CONSTANT_LATITUDE_ATOL_DEG = 1e-6 (~11 cm) classifies whether a segment follows a parallel. The old 1e-9 (0.11 mm) rejected float(np.float32(26.4)) against 26.4 — 4 cm apart — and ECCO stores geolat_c as float32.
• HALF_CIRCLE_ATOL_DEG = 1e-9 guards the ambiguity check. The docs now say plainly that it catches endpoints typed exactly half a circle apart and nothing else: 0 -> 179.9999999 runs east and 0 -> 180.0000001 runs west, with no warning either side.

Notes

The earlier claim that a latitude circle and a great circle produce identical paths was checked at latitude 0, where a latitude circle is a great circle — true but vacuous. The suite now discriminates on a 2° global grid: 0 -> 120 at lat 40 holds the parallel in 61 points while the geodesic bows to 60°N. The 7×5 fixture has rows 40° apart and cannot show this at any latitude.

The literal "latitude and great circle" reads oddly beside two options that each name a single curve; "latitude circle where possible" or "mixed" would also do. One-line change to CURVES plus the test literals if you want it renamed before merge.

Tests

85 passed, 0 skips, in docs_env_sectionate_pr47-lat-circle-shortest-path. Covers all three options against zonal, meridional, oblique and exactly-180 segments; the lat-40 discriminator; float32 waypoint classification; and a meridional ECCO LLC90 segment tracing both directions. test_oblique_latitude_circle_segments_reversible was renamed — its legs are zonal and meridional.

Both notebooks that pass curve use only constant-latitude waypoints, so no notebook output changes; they are re-executed on the integrated branch.

🤖 Generated with Claude Code

[hdrake]

Three curve options, and the review findings

curve now takes three values rather than two:

value	behaviour
"great circle"	unchanged — every segment follows the geodesic
"latitude circle"	every segment follows a parallel; a segment whose endpoints do not share a latitude raises
"latitude and great circle" (new)	decided per segment — parallels where the endpoints share a latitude, geodesics everywhere else

This replaces the oblique-only rejection the first version shipped. "latitude circle" now means
what it says, including for meridional segments, which were previously waved through on the
grounds that a meridian is unambiguous.

That accepting-meridians behaviour was hiding a real failure. The constant-latitude progress
metric measures progress purely in longitude, so along a meridian it is flat: the walk admits no
neighbour and falls through to a fallback. On ECCO LLC90,
grid_section(grid, [0., 0.], [80., 60.], curve="latitude circle") raised
RuntimeError: Should have reached the endpoint by now. in that direction while 60 -> 80 traced
fine — a direction-dependent failure. This is pre-existing on the base branch, not introduced
here. Under "latitude circle" the segment is now refused with a clear message; under
"latitude and great circle" it routes to the geodesic and traces identically in both directions
(49 points each way, exact reverses).

Review findings fixed alongside:

• The classification tolerance was 1e-9 degrees — 0.11 mm — and it was a rejection threshold.
  float(np.float32(26.4)) differs from 26.4 by 3.8e-07 degrees (about 4 cm), and ECCO stores
  geolat_c as float32, so a user reading one latitude off the grid and typing the other got a
  hard error. It is now CONSTANT_LATITUDE_ATOL_DEG = 1e-6 (~11 cm, five orders of magnitude
  below any grid cell) and it classifies rather than rejects. The half-circle comparison keeps its
  own tight 1e-9 as a separately named constant — the two are not the same physical quantity and
  should never have shared one.
• The merged ambiguity message was wrong for latitude circles. At 89°N, 0 -> 180 reported
  "half a circle apart (separation ~180.0000 degrees)" for two points 222 km apart, because the
  separation is degrees of longitude, not arc. It still is one message for all options, but it now
  names the measure it reports.
• The near-180 guard was oversold. 0 -> 179.999999999 raises while 0 -> 179.9999999 runs
  east and 0 -> 180.0000001 runs west — a 2e-07 degree move flips the section to the other side
  of the planet with no error. The docs now say plainly that it catches endpoints typed exactly
  half a circle apart and that anything short of it is settled by round-off.
• The contract was stated in full in five places; it is now stated once, in grid_section.
  test_oblique_latitude_circle_segments_reversible was renamed — its legs are zonal and
  meridional, so under these rules it is not oblique at all.

On the discriminating test: the previous check that a latitude circle and a great circle agree
was run at latitude 0, where a latitude circle is a great circle — true but vacuous. The suite
now uses a 2° global grid where 0 -> 120 at lat 40 holds the parallel in 61 points while the
geodesic bows to 60°N in 81. The old 7×5 fixture has rows 40° apart and cannot tell the metrics
apart at any latitude.

Full suite: 85 passed, 0 skips.

The literal "latitude and great circle" reads a little oddly beside two options that each name a
single curve; "latitude circle where possible" or "mixed" would also work. It is a one-line
change to CURVES plus the test literals if you would rather rename before merge.

Written by Claude Code.

[hdrake]

Looks great