🐛 fix(quantity): __array__ must not silently strip units

[nstarman]

A dimensionful Quantity handed to np.asarray / jnp.asarray came back as a bare number in whatever unit it happened to carry:

>>> np.asarray(u.Q(1.5, "km"))    # -> 1.5
>>> np.asarray(u.Q(1500, "m"))    # -> 1500      the same length
>>> np.asarray(u.Q(90.0, "deg"))  # -> 90.0      read as radians, a 57x error

The consumer gets a number whose meaning depends on a unit it never saw, and nothing anywhere raises. That is the one outcome a units library must not produce.

Why now

__array__ is reached implicitly. np.asarray has always used it; jax.numpy.asarray began doing so in jax 0.10, where it previously raised TypeError. Isolated with clean venvs:

unxt	jax	jnp.asarray(Q(1.5,"km"))
2.0.0	0.7.2	TypeError
2.0.0	0.10.0	Array(1.5) — stripped
2.0.1	0.7.2	TypeError
2.0.1	0.10.0	Array(1.5) — stripped

So the trigger is the jax upgrade and the bug predates 2.0.1 — but the cause is here, and jax is entitled to honour __array__.

This is not new knowledge in the codebase. base.py already documents __array__ silently dropping units for astropy operands and works around it for that one case:

quax would materialise it via __array__ -- stripping it to a bare array in its own unit -- so *// silently dropped its unit

This closes the general case.

The change

__array__ refuses a dimensionful quantity with UnitConversionError, naming ustrip as the explicit route. Dimensionless still converts — there is nothing to lose.

UnitConversionError rather than TypeError is deliberate: try: np.asarray(x) except TypeError: is a common shape, and a TypeError here would be swallowed into some other silent fallback. A units error will not be mistaken for "not array-like".

Angles raise too. rad/deg are dimension angle, not dimensionless, and Q(90, "deg") -> 90.0 is precisely the hazard.

One real consumer relied on the strip

Dataset.unxt.quantify() broke on any dataset with a unitful dimension coordinate — time in seconds, say. It was attaching a Quantity to a dimension coordinate and letting xarray's pandas.Index coercion discard it: the anti-pattern itself.

It now skips dimension coordinates explicitly. Identical result, chosen deliberately rather than left to __array__. The guide's "Dimension Coordinates Cannot Hold Quantities" section described the silent loss and now describes the refusal.

Verification

• Full suite: 4058 passed, 49 skipped, 20 xfailed
• Blast radius before fixing consumers was 3 of 4054, and all three were the fix working
• New regression test pins m/km/deg/rad across both np.asarray and jax.numpy.asarray, with the 57° hazard recorded so it is not quietly re-loosened

Release

Worth backporting to versions/v2.0.x. The previous behaviour was the defect rather than an interface anyone could correctly depend on, so this belongs in a patch rather than waiting on a minor.

Found from downstream: GalacticDynamics/coordinax#720 had five jnp.asarray(<Quantity>) call sites that passed on new jax only because units were being discarded.

🤖 Generated with Claude Code

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.86%. Comparing base (c5a9d8d) to head (40f2b7f).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##              main     #892      +/-   ##
===========================================
- Coverage   100.00%   99.86%   -0.14%     
===========================================
  Files            4       50      +46     
  Lines           25     2916    +2891     
  Branches         0      207     +207     
===========================================
+ Hits            25     2912    +2887     
- Misses           0        2       +2     
- Partials         0        2       +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 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (3)

packages/unxts.interop.xarray/src/unxts/interop/xarray/_src/conversion.py:433

• This comment still refers to Quantity.__array__ “discard[ing] silently”, but in this PR Quantity.__array__ now raises for dimensionful quantities. The rationale here is to avoid triggering that refusal and to keep dimension coordinates plain to match xarray’s indexing model; updating the wording will prevent future confusion.

        # Quantity there cannot survive, so do not attach one: skipping is the
        # same outcome xarray would reach anyway, but chosen here rather than
        # left to `Quantity.__array__` to discard silently. See "Dimension
        # Coordinates Cannot Hold Quantities" in the guide.

src/unxt/_src/quantity/mixins.py:232

• The docstring says “Dimensionless quantities convert”, but the implementation only permits the unscaled dimensionless unit (dimensionless_unscaled / unit string ""). Scaled dimensionless units like "percent" will still raise unless explicitly converted, so the docstring should be more precise to avoid misleading API users.

        Dimensionless quantities convert, because there is nothing to lose.

packages/unxts.interop.xarray/src/unxts/interop/xarray/_src/conversion.py:372

• This comment still refers to Quantity.__array__ “discard[ing] silently”, but in this PR Quantity.__array__ now raises for dimensionful quantities. The rationale here is to avoid triggering that refusal and to keep dimension coordinates plain to match xarray’s indexing model; updating the wording will prevent future confusion.

This issue also appears on line 430 of the same file.

        # Quantity there cannot survive, so do not attach one: skipping is the
        # same outcome xarray would reach anyway, but chosen here rather than
        # left to `Quantity.__array__` to discard silently. See "Dimension
        # Coordinates Cannot Hold Quantities" in the guide.