✨ feat(manifolds): add chord_distance, the straight line through the ambient

[nstarman]

The follow-up promised in #715, which is now merged; this stands alone against main.

geodesic_distance measures along the manifold. The other honest answer is the straight line through the space it is embedded in — the tunnel rather than the surface path. On a sphere of radius $R$ separated by a central angle $\theta$:

$$d_{\mathrm{geodesic}} = R,\theta, \qquad d_{\mathrm{chord}} = 2R\sin(\theta/2)$$

They agree to first order and diverge as the points separate: 0.927 against 0.964 at $\theta = 1$ on the unit sphere, and $2R$ against $\pi R$ at antipodes. Which one is wanted depends on the question — a great-circle flight path is the geodesic, a line of sight through the body is the chord — so it is a separate verb rather than a mode of the first.

Implementation

Embed both points, then take the ambient manifold's geodesic_distance, which for flat ambient space is the straight line. So there is no second distance formula to keep in step, and it works for any embedding rather than only spheres.

Refusals are deliberate:

• Euclidean — it is its own ambient, so its chord is its geodesic. Returning the same number under a second name invites a reader to think two things were measured; the error points at geodesic_distance.
• No embedding — no ambient space to cut through.

Verification

theta        chord     2 sin(t/2)   geodesic       err
0.0010    0.00100000   0.00100000   0.001000   0.00e+00
0.1000    0.09995834   0.09995834   0.100000   0.00e+00
1.0000    0.95885108   0.95885108   1.000000   1.11e-16
3.1416    2.00000000   2.00000000   3.141593   0.00e+00

symmetry / chart-invariance:  d = swap = lonlat = 0.927111716274
embedded sphere R = 2 m, antipodes:  Distance(4., 'm')   # one diameter

Seven tests pin the analytic form across five separations, symmetry and chart-invariance, that it differs from the geodesic (√2 vs π/2 at a quarter turn — the point of two verbs), the embedded sphere carrying its radius, and flat space refusing.

• Full suite: 10430 passed, 10 skipped, 1 xfailed
• prek run --all-files clean, including ty

A fast path where it does pay

geodesic_distance gains one, in the same diff. Its packed overloads unpack their operands into component dicts so a curvilinear chart can be mapped to Cartesian first. In a Cartesian chart there is nothing to map, and plum can skip the unpacking entirely by dispatching on the chart type — 33x for arrays, 3.3x for quantities.

Registered as two signatures rather than one with a Quantity | Array union: each generic overload it overrides is typed for one of them, and a union would be narrower in the chart but wider in the operands, so plum would rank neither more specific and refuse the call as ambiguous.

No matching CDict fast path. The two pt_map calls it would skip are 4.8 µs of a ~3000 µs call — the time is in norm and in wrapping the result as a Distance — so it measured as no gain at all, and would have been dispatch surface bought with nothing.

No fast path for the chord, deliberately

Profiling an eager call:

chord_distance(sph2) total          11624.2 us
  pt_map(p, sph2, sph2)                 4.8 us
  pt_embed(p, unit_sphere)             41.2 us
  geodesic on ambient (2 pts)       11569.7 us   <- 99.5%

The embedding steps a chord-specific shortcut could skip are 0.5% of the call. Hand-rolling the sphere's embedding formula to dodge one pt_map would duplicate TwoSphereIn3D for a fraction of a percent, so the module says so instead.

That 99.5% is one chart transition, which is #719: eager pt_map costs ~5.9 ms against ~21 µs jitted, with 178 dispatch resolutions per call. Fixing it there fixes it here.

Scope

Manifold-level only. geodesic_distance has a Point overload and this does not, so there is an ergonomic asymmetry — whether cx.chord_distance(p, q) should exist at the vector level is a separate decision, happy to add it if you want it.

🤖 Generated with Claude Code

Doc and test-name corrections that came out of review here were split into #724, which is now merged. This branch has been rebased onto it and the duplicate commit dropped, so the diff is chord_distance and the fast path only — tests/unit/vectors/test_point.py and test_jit_parameterized_paths.py are no longer touched here at all.

[Copilot]

Pull request overview

This PR adds a new manifold-level distance verb, chord_distance, for measuring straight-line (ambient) distance through an embedding, and completes the separation → geodesic_distance API transition across code, tests, and docs/spec.

Changes:

• Introduces chord_distance manifold dispatches (with deliberate refusals for Euclidean and non-embedded manifolds) and exports it in the public API.
• Replaces the old separation implementation with geodesic_distance (manifold-geometry based), and updates vector Point overload wiring and tests accordingly.
• Updates documentation/tutorials/spec to reflect geodesic_distance semantics and Minkowski refusals (with a few doc mismatches noted in review comments).

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/unit/vectors/test_point.py	Updates Point-level distance tests to call cx.geodesic_distance.
tests/unit/manifolds/test_separation_dispatch.py	Removes obsolete separation dispatch tests.
tests/unit/manifolds/test_metric_arg_is_honoured.py	Updates metric-arg honoring test to use geodesic_distance.
tests/unit/manifolds/test_interval.py	Updates Minkowski interval tests/docs to reference geodesic_distance.
tests/unit/manifolds/test_geodesic_distance_dispatch.py	Adds dispatch coverage for geodesic_distance and chord_distance.
tests/unit/charts/test_jit_parameterized_paths.py	Updates JIT regression test to use geodesic_distance.
src/coordinax/vectors/_src/register_geodesic_distance.py	Implements Point overload for geodesic_distance and delegates to manifold API.
src/coordinax/vectors/_src/init.py	Switches registration import from register_separation to register_geodesic_distance.
src/coordinax/vectors/init.py	Re-exports geodesic_distance instead of separation.
src/coordinax/manifolds/lorentzian.py	Updates lorentzian namespace docstring wording around Minkowski/interval.
src/coordinax/manifolds/init.py	Re-exports geodesic_distance and new chord_distance.
src/coordinax/_src/minkowski/causality.py	Updates guidance text to reference geodesic_distance instead of separation.
src/coordinax/_src/manifolds/separation.py	Removes legacy separation implementation.
src/coordinax/_src/manifolds/quadratic_form.py	Updates references from separation to geodesic_distance.
src/coordinax/_src/manifolds/interval.py	Clarifies interval semantics vs geodesic_distance and updates wording.
src/coordinax/_src/manifolds/geodesic_distance.py	Adds manifold-based geodesic_distance dispatch implementations and fast paths.
src/coordinax/_src/manifolds/chord_distance.py	Adds new chord_distance dispatch implementations via embedding + ambient distance.
src/coordinax/_src/manifolds/init.py	Registers new manifold dispatch modules (geodesic_distance, chord_distance).
src/coordinax/init.py	Exports geodesic_distance and chord_distance at top-level coordinax.
packages/coordinaxs.api/src/coordinaxs/api/manifolds.py	Renames abstract API to geodesic_distance and adds abstract chord_distance.
docs/tutorials/special_relativity.md	Updates tutorial to use geodesic_distance refusal + interval guidance.
docs/spec.md	Updates authoritative spec section for geodesic_distance.
docs/guides/charts.md	Updates Minkowski chart guidance to reference geodesic_distance.
docs/api/manifolds.md	Updates API docs list for geodesic_distance/interval (needs chord_distance mention).

Suppressed comments (3)

packages/coordinaxs.api/src/coordinaxs/api/manifolds.py:87

• The abstract geodesic_distance docstring still describes the old separation semantics (norm of coordinate difference in the given chart). This is now incorrect: geodesic_distance is computed from manifold geometry (symmetric, chart-invariant), and Minkowski/unknown manifolds can refuse rather than approximate. Updating this docstring will prevent API users from relying on the removed behavior.

    """Distance between two points on a manifold.

    The straight-line distance is the manifold `norm` of the two points'
    coordinate difference, evaluated in the chart they are given in (exact for a
    flat manifold).  Dispatches on the inputs: two `~coordinax.vectors.Point`

docs/spec.md:3002

• chord_distance is introduced as a new public manifold measurement, but docs/spec.md (the authoritative spec) has no corresponding spec entry. Given the repo’s spec-first contract, this new API should be specified here alongside geodesic_distance (including its refusals for Euclidean/no-embedding and the fact it currently has no Point overload).

    ```

(software-spec-abstractatlas)=

tests/unit/manifolds/test_geodesic_distance_dispatch.py:72

• The test class name TestIndefiniteMetricSeparation still refers to separation, but the behavior under test is geodesic_distance refusing indefinite metrics. Renaming reduces ambiguity (especially now that separation no longer exists).

class TestIndefiniteMetricSeparation:
    """`geodesic_distance` inherits `norm`'s guard instead of returning ``nan``.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.55%. Comparing base (bc52af2) to head (64674a4).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #720      +/-   ##
==========================================
- Coverage   96.55%   96.55%   -0.01%     
==========================================
  Files         265      266       +1     
  Lines        8793     8849      +56     
==========================================
+ Hits         8490     8544      +54     
- Misses        303      305       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

docs/api/manifolds.md:52

• chord_distance is introduced as a new public API (exported from coordinax.manifolds / coordinax). Per the repo’s spec-first workflow, this should also be documented in the authoritative docs/spec.md (and/or the relevant spec section for manifolds/embeddings), otherwise the implementation and user-facing docs can drift from the source of truth.

- `chord_distance`: length of the straight line between two points _through the ambient space_ they are embedded in -- the tunnel rather than the surface path. A different measurement from `geodesic_distance`, not an approximation to it: on a sphere of radius $R$ separated by a central angle $\theta$, the geodesic is $R\theta$ and the chord is $2R\sin(\theta/2)$. Needs an embedding, so a manifold that is its own ambient (anything Euclidean) raises `NotImplementedError` and points at `geodesic_distance`

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.