📝 docs(spec): specify the embedding and metric-representation verbs

[nstarman]

Four public verbs that had no spec entry: metric_representation, pt_embed, pt_project, embedded_twosphere.

Placed with the machinery they belong to rather than in the verb cluster — metric_representation right after metric_matrix, whose sibling it is, and the embedding trio after EmbeddedManifold. That also keeps this diff clear of #732/#733/#734, which all insert near the verbs.

metric_representation

The one most worth writing down, because the name invites the wrong reading. It returns a class, not a populated matrix, and takes no base point:

>>> cxm.metric_representation(cxm.R3, cxc.cart3d).__name__
'DiagonalMetric'
>>> cxm.metric_representation(cxm.embedded_twosphere(radius=u.Q(2.0, "km")), cxc.sph2).__name__
'DenseMetric'

Sparsity structure belongs to the (manifold, chart) pair, not to where you stand on it. That is what lets metric_matrix keep the $O(n)$ diagonal path (#686) instead of contracting a full einsum — and why an EmbeddedManifold declares dense: a pullback through an arbitrary embedding has no reason to be diagonal even when the intrinsic chart is orthogonal.

pt_embed / pt_project

Recorded that pt_project is a genuine projection, not merely an inverse — defined on all of the ambient, round-tripping exactly only for points already on the surface. That is why it carries overloads pt_embed does not, including a HyperSphericalManifold pair and a Point one: projecting onto a sphere is meaningful without an EmbeddedManifold to hand, while embedding from one is not.

One inconsistency found — recorded, not smoothed over

The container of a projected angle tracks the ambient chart:

ambient	pt_project(...)["theta"]
Spherical3D	Angle(1.04719755, 'rad')
Cart3D	Q(1.04719755, 'rad')

Same value, same unit, different container. Written down as observed behaviour with a note that an angle is an element of $S^1$ and the container is what carries that, so the ambient chart arguably should not decide it. If that's a bug rather than a quirk, this is the line to change.

Two things this cost, both worth naming

• The pt_embed Cartesian example first used the equator, which routes through cos(pi/2) and puts 1.2246468e-16 in the output. Moved to the north pole, where the same route is exact. Same trap as in ✅ test(spec): put docs/spec.md examples under CI #733 — the Cartesian ambient is a reliable source of float noise.
• A !!! warning admonition with a nested ```pycon block made sybil fail at collection, not as a test failure: ValueError: <Region ...> overlaps <Region ...>. The outer indented block and the inner fence both parse as doctests. Flattened to prose plus a plain example. Worth knowing before anyone else nests one.

Verification

All 24 examples verified under pytest docs/spec.md — the harness that sets JAX_ENABLE_X64, so the literals are the ones CI will compare against. 0 failures inside the four added sections, checked by mapping every reported failure line against the section ranges rather than eyeballing.

prek run --all-files clean; uv run --frozen nox -s docs succeeds with warnings as errors.

The 17 pre-existing failures elsewhere in docs/spec.md are untouched — they are #733's subject.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds missing specification entries to the authoritative docs/spec.md for four public manifold/embedding verbs (metric_representation, pt_embed, pt_project, embedded_twosphere), documenting their intent, dispatch shapes, and doctested examples in the sections where the underlying machinery is described.

Changes:

• Specify metric_representation as a structural query returning the metric-matrix container class (not an evaluated matrix).
• Specify embedding/projection behavior via pt_embed / pt_project, including examples for spherical vs Cartesian ambient charts.
• Specify the embedded_twosphere convenience constructor and its relationship to EmbeddedManifold.

Suppressed comments (3)

docs/spec.md:4537

• The listed coordinax.vectors.Point overload is too broad and drops the usys kwarg. In code the Point overload is specifically (Point, HyperSphericalManifold, *, usys=None) (and it returns a Point, not a CDict). The signature list should reflect the actual dispatch.

    cxm.pt_project(p, chart, M, /, *, usys=None)                 # HyperSphericalManifold
    cxm.pt_project(p, M, /)                                      # coordinax.vectors.Point

docs/spec.md:4542

• pt_project does not always return a CDict: when called with a coordinax.vectors.Point, the Point overload returns a Point with its data/chart updated. The Return section should document this so callers know what to expect.

    **Return:**

    - A `CDict` in the intrinsic chart's components.

docs/spec.md:4592

• The embedded_twosphere signature shows ambient=cxc.spherical3d, but there is no coordinax.charts.spherical3d symbol in the codebase; the default ambient chart is cxc.sph3d (a Spherical3D instance). This signature should match the actual default.

    cxm.embedded_twosphere(radius, ambient=cxc.spherical3d)

---

💡 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.59%. Comparing base (4020513) to head (a467ed6).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #735   +/-   ##
=======================================
  Coverage   96.59%   96.59%           
=======================================
  Files         266      266           
  Lines        8934     8934           
=======================================
  Hits         8630     8630           
  Misses        304      304           

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