✨ feat(curveframes): infer tau_unit from the parameter instead of requiring it

[nstarman]

Follow-up to #756, as flagged in its description.

Why

#756 removed a bad default by making tau_unit required. This removes it a second way, which costs no migration and is strictly safer: a Quantity parameter already states its unit, so the builders read it off the parameter instead of asking the caller to declare it again.

BishopBuilder(curve)(u.Q(2.0, "Gyr"))   # tau_unit inferred: Gyr
BishopBuilder(curve, "Gyr")             # still accepted, unchanged

A declaration is an independent second statement of a fact the parameter already carries, and two statements can disagree. Removing the second statement leaves nothing to disagree.

What the required unit was actually protecting

Narrower than #756 assumed, and worth stating precisely because it decides the design.

unxt.experimental.jacfwd strips with ustrip(unit, arg) — a conversion, not a reinterpretation. Q(2.0, "Gyr") declared as "s" reaches the curve as Q(6.3e16, "s"); the curve's own ustrip("Gyr") converts it back. Measured on a Gyr/kpc helix, declared-"s" and declared-"Gyr" builders return bit-identical rotation_matrix, tangent and location.

The declaration is load-bearing in exactly two cases, both now covered by tests:

curve style	wrong declared unit	inferred
tau.ustrip("Gyr") — converts	harmless, absorbed	same answer
tau.value — reads the magnitude	silently wrong	correct by construction
raw, unitless parameter	required	TypeError naming both fixes

For the .value curve only tangent fails quietly — the parallel-transport ODE gives up outright on a curve made 3.15e16× stiffer, which is why the test pins tangent rather than rotation_matrix.

Inference cannot be wrong in the .value case: it hands the curve back exactly the numbers the caller passed.

Nothing is given up

• Should BishopBuilder/FrenetSerretBuilder also require tau_unit rather than defaulting to "s"? #718's dimension guard still fires. With no declaration there is nothing to check at construction, so it runs on the inferred unit at the first call that supplies a parameter — still before any wrong number is returned. BishopBuilder(ArcLength(c, "s"))(u.Q(1.0, "s")) raises exactly as BishopBuilder(ArcLength(c, "s"), "s") does.
• The explicit form is untouched. Inference is a default, not a removal.
• 💥 refactor(curveframes): require tau_unit on the frame builders #756's docs sweep stands. Every example still states its unit; that was always about the reader, not the compiler.

Where a declaration is still required

ArcLength/LagrangianArcLength keep a required tau_unit. Their $\tau$ is internal — generated by the reparametrisation ODE, never passed in — so nothing at call time carries it. This is a real asymmetry, not an oversight.

TubularChart.coord_dimensions is structural and has no call parameter, so it reads tau_bounds[0], a required field that carries $\tau$'s unit anyway. nearest_tau likewise reads its bounds. Neither needs the builder to declare anything.

The one cost

BishopBuilder.__post_init__ still materialises tau_0 when the unit is declared, so the default tau_0 stays a differentiable pytree leaf. When the unit is inferred it cannot — the unit is not known until a parameter arrives — so an inferring builder's default tau_0 is not a leaf. Pass tau_0 explicitly to differentiate through it; that also declares its unit.

Found by 5 failing tests that were right to fail, and confined to the new opt-in path.

Verification

• 976 coordinaxs.curveframes tests pass
• prek run clean on all touched files, including ty
• new tests pin: declared ≡ inferred for both builders; the compatible-mismatch absorption; the .value failure; the unitless TypeError; the guard on an inferred unit

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR makes tau_unit optional for BishopBuilder and FrenetSerretBuilder (and their from_curve constructors) by inferring it from the Quantity parameter passed at call time, while keeping explicit tau_unit declarations supported. It also updates curveframe utilities/docs/spec and adds tests to pin the intended unit-inference behavior and guard semantics.

Changes:

• Add AbstractCurveFrameBuilder._tau_unit_at(...) plus supporting converters/messages to resolve a declared unit or infer it from a call-time Quantity.
• Update Bishop/Frenet-Serret builders and call sites (nearest_tau, TubularChart) to use _tau_unit_at rather than assuming builder.tau_unit is always present.
• Expand unit-behavior tests and update curveframes spec/docs to reflect the new default.

Reviewed changes

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

Show a summary per file

File	Description
packages/coordinaxs.curveframes/tests/unit/test_builder_curve_arity.py	Adds tests for inferred vs declared units, mismatch absorption, and unitless-parameter error paths.
packages/coordinaxs.curveframes/src/coordinaxs/curveframes/_src/nearest.py	Derives tau unit from bounds instead of requiring a declared builder unit.
packages/coordinaxs.curveframes/src/coordinaxs/curveframes/_src/frenetserret.py	Makes tau_unit optional and resolves derivative units via _tau_unit_at.
packages/coordinaxs.curveframes/src/coordinaxs/curveframes/_src/chart.py	Computes tau dimension/unit via bounds/parameter rather than assuming declared tau_unit.
packages/coordinaxs.curveframes/src/coordinaxs/curveframes/_src/bishop.py	Makes tau_unit optional and defers default tau_0 materialization when inferring units.
packages/coordinaxs.curveframes/src/coordinaxs/curveframes/_src/base.py	Introduces _tau_unit_at, unit_or_none, and shifts dimension checks to declared-or-inferred resolution time.
packages/coordinaxs.curveframes/src/coordinaxs/curveframes/init.py	Updates top-level docs snippet to reflect optional tau_unit.
packages/coordinaxs.curveframes/docs/spec.md	Updates package spec to document `tau_unit: AbstractUnit

Suppressed comments (1)

packages/coordinaxs.curveframes/src/coordinaxs/curveframes/_src/frenetserret.py:224

• Same issue as in rotation_matrix: tangent calls .astype(float) before _tau_unit_at, so a unitless scalar parameter can raise AttributeError instead of the intended _MSG_TAU_UNIT_UNINFERABLE TypeError. Resolve the unit from the original parameter first, then cast.

        b, p = self._resolve(tau)
        g = b._param(p).astype(float)
        dcurve = u.experimental.jacfwd(b.curve, units=(b._tau_unit_at(g),))
        return u.Q(_normalize(dcurve(g)).value, "")

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.