Vincenty Ellipsoidal Distance

Inspectable records

Ledger state

The current ledger marks this instrument verified with errata that must be applied at binding time.

Area

Earth & Space (astronomy, orbital mechanics, meteorology, geology, geodesy, oceanography)

Tranche

tranche-6

Evidence ID

t6-050

Ledger rows

1

No ledger note is attached.

Review findings

The underlying method is standard for WGS84 inverse geodesics, but the spec is not complete enough to certify an implementation. Explicitly document decimal-degree versus radian inputs, azimuth convention, lambda tolerance, maximum iterations, non-convergence behavior, coincident-point behavior, and longitude normalization. CoreLocation integration is irrelevant to the offline pure-JS mathematical result unless it changes the coordinate datum or units.

Formula and scope findings

• The named Vincenty inverse method is the standard algorithm for ellipsoidal geodesic distance and azimuths, but the spec does not provide the actual equations, convergence tolerance, maximum iteration count, longitude normalization rule, or fallback behavior after non-convergence.
• Input angle units are unspecified. A math.js implementation commonly expects radians, while user-facing geodesy tools commonly accept degrees; this must be explicit.
• The azimuth convention is unspecified. Vincenty alpha2 is the terminal forward azimuth, which differs by 180 degrees from the destination-to-origin back bearing.
• Coincident points have zero distance but no mathematically defined azimuth; the output contract must define whether azimuths are null, NaN, or a chosen convention.
• The honest-label warning about near-antipodal non-convergence is appropriate but should also require an explicit convergence failure status rather than returning stale or partially converged values.

Unit assumptions

• Test inputs below use decimal degrees and are converted internally to radians: radians = degrees × pi/180.
• WGS84 semimajor axis a = 6378137 m; flattening f = 1/298.257223563; semiminor axis b = a(1-f) = 6356752.314245179 m.
• Distances are returned in metres.
• Azimuths below use the standard Vincenty terminal-forward-azimuth convention, normalized to [0,360) degrees. A reverse back bearing would differ by 180 degrees.
• Vincenty lambda iteration is assumed to use an absolute change tolerance of 1e-12 radians and a sufficiently large finite iteration limit.

Boundary hardening

BREAK_CLAIMED · SELF_FLAGGED

The instrument specification is vulnerable at coincident points, where azimuths reduce to an undefined atan2(0,0), and at exact antipodal points, where the Vincenty inverse iteration contains singular 0/0 terms and must report non-convergence. The general cos(2σm) branch also fails for exact equatorial paths unless the equatorial special case is implemented.

Errata and corrections

Tranche errata

Inspectable example

4 review vectors are recorded. One source-bound sample is shown below.

{
  "inputs": {
    "lat1_deg": 0,
    "lon1_deg": 0,
    "lat2_deg": 0,
    "lon2_deg": 1,
    "tolerance_rad": 1e-12
  },
  "expected_outputs": {
    "distance_m": 111319.490793,
    "forward_azimuth_deg": 90,
    "reverse_terminal_azimuth_deg": 90
  },
  "working": "Convert longitude difference: L = 1 × pi/180 = 0.0174532925199 rad. For the equator, U1 = U2 = 0, sin(alpha) = 1, cos²(alpha) = 0, C = f/4 = 0.000838202666. Vincenty lambda iterations: lambda0 = 0.0174532925199; lambda1 ≈ 0.017454313; lambda2 ≈ 0.017454313; converged lambda ≈ 0.017454313 rad. For an equatorial geodesic, the distance simplifies exactly to aL: distance = 6378137 × 0.0174532925199 = 111319.490793 m. The forward and terminal azimuths are both 90 degrees."
}

Related workflows

No source-defined multi-instrument workflow membership is recorded.

Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

• VERIFIED_LEDGER.json · VERIFIED_WITH_ERRATA
• evidence-tranche6/tranche6-results.json
• BOUNDARY_HAZARD_CATALOG.json