📝 fix(manifolds): correct the docs that still describe the old separation

[nstarman]

Split out of #720 so fixes stay separate from features. Docs and test names only — no behaviour change.

#715 renamed separation to geodesic_distance and gave it real geodesics, but four pieces of prose still describe the function it replaced.

The abstract dispatch still documented the removed definition

coordinaxs.api.manifolds.geodesic_distance read:

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

That is precisely what #715 removed, for being asymmetric on a curved manifold and therefore not a distance. The API's own contract was still advertising the behaviour the implementation now refuses.

interval == geodesic_distance**2 is no longer true

Two more places claimed it for any Riemannian metric. True when geodesic_distance was that norm; false now:

unit sphere, separation ~0.92 rad
  interval          0.7335
  geodesic**2       0.8430     <- 13% apart

flat cart3d
  interval         25.0
  geodesic**2      25.0        <- equal

The identity is with norm(diff), and the condition is flatness, not positive-definiteness — the sphere's metric is positive-definite and it still fails.

A test asserted the same over-general claim in its name and docstring (test_riemannian_interval_is_squared_separation, "for a positive-definite metric the two agree") while only ever exercising flat space, so it passed. It now says flat, and a curved counter-case pins the distinction.

Smaller

• lorentzian's module docstring said that without a Lorentzian signature "the interval has the same sign for every pair". True only for positive-definite metrics — an indefinite metric with two timelike directions varies in sign without defining causal structure.
• Three test names still said separation.

Verification

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

Found while splitting #720: cherry-picking onto clean main put the file in front of me without my own edits layered on top, which is what made the stale text visible.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates documentation and test naming around the separation → geodesic_distance refactor, correcting remaining prose that still described the old “norm of coordinate difference” behavior and clarifying when interval matches a squared distance.

Changes:

• Update API/docs text to describe geodesic_distance as a manifold-geodesic (and refusal behavior) rather than a coordinate-difference norm.
• Correct claims that interval == geodesic_distance**2 in general by narrowing the condition to flat/Cartesian, and add a curved counterexample test.
• Rename remaining tests/classes from “separation” to “geodesic_distance” (plus associated docstrings/comments).

Reviewed changes

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

Show a summary per file

File	Description
tests/unit/vectors/test_point.py	Renames Point-level tests to geodesic_distance (docstrings still contain a few “Separation” references).
tests/unit/manifolds/test_interval.py	Renames the “squared separation” test and adds a curved-space counterexample.
tests/unit/manifolds/test_geodesic_distance_dispatch.py	Renames test classes/methods to reflect geodesic_distance.
tests/unit/charts/test_jit_parameterized_paths.py	Renames the JIT test for geodesic_distance.
src/coordinax/manifolds/lorentzian.py	Clarifies interval-sign discussion for non-Lorentzian signatures.
src/coordinax/_src/manifolds/interval.py	Updates internal commentary to distinguish norm(diff) vs geodesic_distance.
packages/coordinaxs.api/src/coordinaxs/api/manifolds.py	Updates abstract API docstrings for geodesic_distance and interval.

Suppressed comments (7)

tests/unit/manifolds/test_interval.py:70

• In the new curved-space counterexample, sep2 still carries the old "separation" naming. Renaming it to gd2 (or similar) would make it clear this is geodesic_distance(...)**2.

        ds2 = float(cxm.interval(cxc.sph2, a, b).ustrip("rad2"))
        sep2 = float(cxm.geodesic_distance(cxc.sph2, a, b).ustrip("rad")) ** 2
        assert ds2 < sep2
        assert ds2 == pytest.approx(0.7335, abs=1e-3)
        assert sep2 == pytest.approx(0.8430, abs=1e-3)

tests/unit/vectors/test_point.py:293

• This docstring still uses the old term "Separation" after the geodesic_distance rename. Updating it keeps the test documentation consistent with the current API name.

    def test_geodesic_distance_is_chart_invariant(self):
        """Separation does not depend on the chart of either operand."""
        p = cx.Point.from_([3.0, 0.0, 0.0], "m")
        q = cx.Point.from_([0.0, 4.0, 0.0], "m").cconvert(cxc.sph3d)
        assert bool(qnp.isclose(cx.geodesic_distance(p, q).ustrip("m"), 5.0))

tests/unit/vectors/test_point.py:299

• This docstring still says "Separation" even though the test is now about geodesic_distance.

    def test_geodesic_distance_is_unit_invariant(self):
        """Separation does not depend on the component units."""
        p = cx.Point.from_([3.0, 0.0, 0.0], "m")
        q = cx.Point.from_([0.0, 0.004, 0.0], "km")
        assert bool(qnp.isclose(cx.geodesic_distance(p, q).ustrip("m"), 5.0))

tests/unit/vectors/test_point.py:313

• This docstring still references separation_3d, which is tied to the removed/renamed API. Consider rephrasing to avoid the old separation terminology.

    def test_geodesic_distance_dimensionality_follows_manifold(self):
        """2-D points give a 2-D distance -- no separate ``separation_3d``."""
        p = cx.Point.from_([3.0, 0.0], "m")
        q = cx.Point.from_([0.0, 4.0], "m")
        assert bool(qnp.isclose(cx.geodesic_distance(p, q).ustrip("m"), 5.0))

tests/unit/vectors/test_point.py:319

• This docstring still uses the old term "Separation" even though the test now targets geodesic_distance.

    def test_geodesic_distance_different_frames_raises(self):
        """Separation across frames is undefined without alignment."""
        p = cx.Point.from_([1.0, 0.0, 0.0], "m", cxf.alice)
        q = cx.Point.from_([0.0, 1.0, 0.0], "m", cxf.noframe)
        with pytest.raises(ValueError, match="frame"):

tests/unit/vectors/test_point.py:333

• This docstring still uses "Separation" terminology; updating it keeps test docs consistent with geodesic_distance.

    def test_geodesic_distance_unitless_components(self):
        """Separation works for vectors with plain (unitless) array leaves."""
        p = cx.Point.from_({"x": 3.0, "y": 0.0, "z": 0.0}, cxc.cart3d)
        q = cx.Point.from_({"x": 0.0, "y": 4.0, "z": 0.0}, cxc.cart3d)
        assert bool(qnp.isclose(cx.geodesic_distance(p, q), 5.0))

tests/unit/vectors/test_point.py:305

• This docstring still uses the old term "Separation" after renaming the test to geodesic_distance.

    def test_geodesic_distance_elementwise_over_batch(self):
        """Separation is evaluated element-wise over the batch."""
        p = cx.Point.from_([[3.0, 0, 0], [1, 0, 0]], "m")
        q = cx.Point.from_([[0.0, 4, 0], [0, 1, 0]], "m")
        d = cx.geodesic_distance(p, q)

---

💡 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 (19bc065) to head (94493ad).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #724   +/-   ##
=======================================
  Coverage   96.55%   96.55%           
=======================================
  Files         265      265           
  Lines        8793     8793           
=======================================
  Hits         8490     8490           
  Misses        303      303           

☔ 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 8 out of 8 changed files in this pull request and generated no new comments.