* 🐛 fix(quantity): improve bitwise ops for dimensionful quantities (#791)

Bitwise/logical operations on dimensionful quantities previously leaked an
internal `UnitConversionError` from `ustrip`, producing the misleading
message that `'m'` and `''` were not convertible even when both operands
had the same unit.

Require bitwise operands to be dimensionless before dispatching to JAX and
raise a clear `ValueError` identifying the operation and the offending
units instead. Apply this consistently across all bitwise entry points,
including quantity/quantity, quantity/array (both operand orders), and
unary `not`. Bitwise operations on genuinely dimensionless quantities are
unchanged.

Expand the test suite to cover every dispatch path, verify the operation
name appears in the error message, and add regression coverage for the
dimensionless success cases.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: nstarman

src/unxt/_src/quantity/register_primitives.py

@@ -43,6 +43,27 @@ def _to_val_rad_or_one(q: ABCQ) -> ArrayLike:
     return ustrip(radian if is_unit_convertible(q.unit, radian) else one, q)
 
 
+def _require_dimensionless_bitwise(op_name: str, /, *operands: Any) -> None:
+    """Raise a clear error if a bitwise/logical op gets dimensionful operands.
+
+    These ops require dimensionless operands. Without this check ``ustrip(one, x)``
+    leaks astropy's confusing "<unit> and '' are not convertible" message -- which,
+    for ``Q(bool, "m") + Q(bool, "m")`` (JAX lowers a bool ``+`` to ``or_p``),
+    wrongly implies a dimensionless operand the user never wrote.
+
+    Guards every bitwise/logical entry point -- the two-quantity, quantity/array,
+    and unary overloads -- so the error is consistently clear regardless of which
+    operand carries the unit. A plain array operand (``unit_of`` returns ``None``)
+    is inherently dimensionless.
+    """
+    units = [unit_of(o) for o in operands]
+    if all(u is None or u.is_equivalent(one) for u in units):
+        return
+    got = " and ".join(repr("" if u is None else str(u)) for u in units)
+    msg = f"{op_name} requires dimensionless quantities, got units {got}"
+    raise ValueError(msg)
+
+
 def _as_dimensionless_like(q: ABCQ, value: ArrayLike) -> ABCQ:
     """Wrap a dimensionless-valued result as a dimensionless quantity like ``q``.
 
@@ -397,6 +418,7 @@ def and_p_aq(x1: ABCQ, x2: ABCQ, /) -> ABCQ:
     Quantity(Array(0, dtype=int32...), unit='')
 
     """
+    _require_dimensionless_bitwise("bitwise/logical and", x1, x2)
     return _as_dimensionless_like(x1, lax.and_p.bind(ustrip(one, x1), ustrip(one, x2)))
 
 
@@ -418,6 +440,7 @@ def and_p_qv(x1: ABCQ, x2: ArrayLike, /) -> ABCQ:
     Quantity(Array([ True, False, False], dtype=bool), unit='')
 
     """
+    _require_dimensionless_bitwise("bitwise/logical and", x1, x2)
     return _as_dimensionless_like(x1, lax.and_p.bind(ustrip(one, x1), x2))
 
 
@@ -438,6 +461,7 @@ def and_p_vq(x1: ArrayLike, x2: ABCQ, /) -> ABCQ:
     Quantity(Array([ True, False, False], dtype=bool), unit='')
 
     """
+    _require_dimensionless_bitwise("bitwise/logical and", x1, x2)
     return _as_dimensionless_like(x2, lax.and_p.bind(x1, ustrip(one, x2)))
 
 
@@ -3860,6 +3884,7 @@ def not_p(x: ABCQ, /) -> ABCQ:
     Quantity(Array(-2, dtype=int32...), unit='')
 
     """
+    _require_dimensionless_bitwise("bitwise/logical not", x)
     return _as_dimensionless_like(x, lax.bitwise_not(ustrip(one, x)))
 
 
@@ -3885,6 +3910,7 @@ def or_p_qq(x: ABCQ, y: ABCQ, /) -> ABCQ:
     Quantity(Array(3, dtype=int32...), unit='')
 
     """
+    _require_dimensionless_bitwise("bitwise/logical or", x, y)
     return _as_dimensionless_like(x, lax.bitwise_or(ustrip(one, x), ustrip(one, y)))
 
 
@@ -3907,6 +3933,7 @@ def or_p_qv(x: ABCQ, y: ArrayLike, /) -> ABCQ:
     Quantity(Array([ True, False,  True], dtype=bool), unit='')
 
     """
+    _require_dimensionless_bitwise("bitwise/logical or", x, y)
     return _as_dimensionless_like(x, lax.or_p.bind(ustrip(one, x), y))
 
 
@@ -3927,6 +3954,7 @@ def or_p_vq(x: ArrayLike, y: ABCQ, /) -> ABCQ:
     Quantity(Array([ True, False,  True], dtype=bool), unit='')
 
     """
+    _require_dimensionless_bitwise("bitwise/logical or", x, y)
     return _as_dimensionless_like(y, lax.or_p.bind(x, ustrip(one, y)))
 
 
@@ -5360,6 +5388,7 @@ def xor_p_qq(x: ABCQ, y: ABCQ, /) -> ABCQ:
     Quantity(Array(3, dtype=int32...), unit='')
 
     """
+    _require_dimensionless_bitwise("bitwise/logical xor", x, y)
     return _as_dimensionless_like(x, lax.bitwise_xor(ustrip(one, x), ustrip(one, y)))
 
 
@@ -5382,6 +5411,7 @@ def xor_p_qv(x: ABCQ, y: ArrayLike, /) -> ABCQ:
     Quantity(Array([False,  True,  True], dtype=bool), unit='')
 
     """
+    _require_dimensionless_bitwise("bitwise/logical xor", x, y)
     return _as_dimensionless_like(x, lax.xor_p.bind(ustrip(one, x), y))
 
 
@@ -5402,6 +5432,7 @@ def xor_p_vq(x: ArrayLike, y: ABCQ, /) -> ABCQ:
     Quantity(Array([False,  True,  True], dtype=bool), unit='')
 
     """
+    _require_dimensionless_bitwise("bitwise/logical xor", x, y)
     return _as_dimensionless_like(y, lax.xor_p.bind(x, ustrip(one, y)))
 
 

tests/unit/test_bitwise_dimensionless.py

@@ -0,0 +1,69 @@
+"""Bitwise/logical ops on quantities require dimensionless operands.
+
+The error must name the operation and both *actual* units, not leak astropy's
+misleading "'m' and '' are not convertible" (which implies a dimensionless
+operand the user never wrote).
+"""
+
+import jax.numpy as jnp
+import pytest
+
+import quaxed.numpy as qnp
+
+import unxt as u
+
+# (callable, op-name as it appears in the error message)
+BITWISE_OPS = [
+    (qnp.bitwise_or, "or"),
+    (qnp.bitwise_and, "and"),
+    (qnp.bitwise_xor, "xor"),
+]
+
+
+def test_bool_add_on_dimensionful_gives_clear_error():
+    """`Q(bool, 'm') + Q(bool, 'm')` (JAX lowers to or_p) names or and both 'm'."""
+    q = u.Q(jnp.array([True, False]), "m")
+    pattern = r"bitwise/logical or.*dimensionless.*'m'.*'m'"
+    with pytest.raises(ValueError, match=pattern):
+        _ = q + q
+
+
+@pytest.mark.parametrize(("op", "name"), BITWISE_OPS)
+def test_bitwise_qq_on_dimensionful_raises_clear_error(op, name):
+    """Two dimensionful quantities: the message names the op and both units."""
+    with pytest.raises(
+        ValueError, match=rf"bitwise/logical {name}.*dimensionless.*'m'.*'s'"
+    ):
+        _ = op(u.Q(1, "m"), u.Q(2, "s"))
+
+
+@pytest.mark.parametrize(("op", "name"), BITWISE_OPS)
+def test_bitwise_quantity_array_raises_clear_error(op, name):
+    """A dimensionful quantity mixed with a plain array is caught just as clearly.
+
+    Both operand orders route through the quantity/array overloads, which strip
+    to dimensionless too and would otherwise leak astropy's confusing message.
+    """
+    pattern = rf"bitwise/logical {name}.*dimensionless.*'m'"
+    with pytest.raises(ValueError, match=pattern):
+        _ = op(u.Q(jnp.array([1]), "m"), jnp.array([2]))
+    with pytest.raises(ValueError, match=pattern):
+        _ = op(jnp.array([2]), u.Q(jnp.array([1]), "m"))
+
+
+def test_bitwise_not_on_dimensionful_raises_clear_error():
+    """The unary `not_p` overload is guarded as well."""
+    with pytest.raises(ValueError, match=r"bitwise/logical not.*dimensionless.*'m'"):
+        _ = qnp.bitwise_not(u.Q(jnp.array([1]), "m"))
+
+
+@pytest.mark.parametrize(("op", "name"), BITWISE_OPS)
+def test_bitwise_on_dimensionless_still_works(op, name):
+    """The dimensionless path is unchanged, for both quantity/quantity and array."""
+    assert op(u.Q(6, ""), u.Q(3, "")).unit == u.unit("")
+    assert op(u.Q(jnp.array([1]), ""), jnp.array([2])).unit == u.unit("")
+    assert op(jnp.array([2]), u.Q(jnp.array([1]), "")).unit == u.unit("")
+
+
+def test_bitwise_not_on_dimensionless_still_works():
+    assert qnp.bitwise_not(u.Q(1, "")).unit == u.unit("")