unxts.linalg 2.0.0__tar.gz

unxts_linalg-2.0.0/.gitignore

@@ -0,0 +1,166 @@
+# -----------------------------------------------
+# Project-Specific
+
+# Version files
+_version.py
+
+
+# -----------------------------------------------
+# General
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/guides/perf.ipynb
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# ruff
+.ruff_cache/
+
+# OS specific stuff
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Common editor files
+*~
+*.swp
+/.codspeed

unxts_linalg-2.0.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: unxts.linalg
+Version: 2.0.0
+Summary: Heterogeneous-unit matrices and vectors for unxt (canonical: unxts.linalg)
+Project-URL: Bug Tracker, https://github.com/GalacticDynamics/unxt/issues
+Project-URL: Homepage, https://github.com/GalacticDynamics/unxt
+Author-email: GalacticDynamics <nstarman@users.noreply.github.com>, Nathaniel Starkman <nstarman@users.noreply.github.com>
+License: BSD-3-Clause
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: equinox>=0.11.8
+Requires-Dist: jaxtyping>=0.2.34
+Requires-Dist: plum-dispatch>=2.5.7
+Requires-Dist: quax>=0.2.0
+Requires-Dist: unxt
+Description-Content-Type: text/markdown
+
+# unxts.linalg
+
+Heterogeneous-unit matrices and vectors for [unxt](https://github.com/GalacticDynamics/unxt).
+
+This is the canonical package (`unxts.linalg`). It provides `QuantityMatrix` (alias `QM`): a quantity container whose elements may each carry a different unit, together with a static `UnitsMatrix` unit structure and unit-aware linear-algebra primitives (`det`, `inv`, the `matmul`/`matvec`/`vecmat`/`vecdot` products, and Quax-registered add/sub, mul/div, matmul, transpose, diag, and reduce-sum rules).
+
+## Install
+
+```bash
+pip install unxts.linalg
+```
+
+## Usage
+
+```python
+import jax.numpy as jnp
+import unxts.linalg as ul
+
+qv = ul.QuantityMatrix(jnp.array([1.0, 2.0, 3.0]), unit=("m", "s", "kg"))
+```

unxts_linalg-2.0.0/README.md

@@ -0,0 +1,20 @@
+# unxts.linalg
+
+Heterogeneous-unit matrices and vectors for [unxt](https://github.com/GalacticDynamics/unxt).
+
+This is the canonical package (`unxts.linalg`). It provides `QuantityMatrix` (alias `QM`): a quantity container whose elements may each carry a different unit, together with a static `UnitsMatrix` unit structure and unit-aware linear-algebra primitives (`det`, `inv`, the `matmul`/`matvec`/`vecmat`/`vecdot` products, and Quax-registered add/sub, mul/div, matmul, transpose, diag, and reduce-sum rules).
+
+## Install
+
+```bash
+pip install unxts.linalg
+```
+
+## Usage
+
+```python
+import jax.numpy as jnp
+import unxts.linalg as ul
+
+qv = ul.QuantityMatrix(jnp.array([1.0, 2.0, 3.0]), unit=("m", "s", "kg"))
+```

unxts_linalg-2.0.0/docs/index.md

@@ -0,0 +1,85 @@
+# `unxts.linalg`
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+quantity-matrix
+units-matrix
+linear-algebra
+tutorial-metric
+sharp-bits
+```
+
+`unxts.linalg` provides `QuantityMatrix` (alias `QM`): a quantity container whose elements may each carry a **different** unit. It is backed by a single JAX array plus a static `UnitsMatrix` describing the per-element units, and supports both 1-D (heterogeneous vector) and 2-D (heterogeneous matrix) structures.
+
+It is useful for objects whose entries have mixed physical dimensions — Jacobians, metric tensors, and coordinate change-of-basis matrices — where a single scalar unit (as on `unxt.Quantity`) is not expressive enough.
+
+## Install
+
+::::{tab-set}
+
+:::{tab-item} uv
+
+```bash
+uv add unxts.linalg
+```
+
+:::
+
+:::{tab-item} pip
+
+```bash
+pip install unxts.linalg
+```
+
+:::
+
+::::
+
+Throughout these guides we import `unxt` as `u` and `unxts.linalg` as `ul` (so `QuantityMatrix` is `ul.QM`):
+
+```{code-block} python
+>>> import jax.numpy as jnp
+>>> import unxt as u
+>>> import unxts.linalg as ul
+```
+
+## At a glance
+
+A 1-D `QuantityMatrix` is a vector whose entries each have their own unit:
+
+```{code-block} python
+>>> qv = ul.QuantityMatrix(jnp.array([1.0, 2.0, 3.0]), unit=("m", "s", "kg"))
+>>> qv.unit.to_string()
+'(m, s, kg)'
+>>> 2 * qv
+QuantityMatrix(Array([2., 4., 6.], dtype=float32), unit='(m, s, kg)')
+```
+
+Indexing a single element yields an ordinary `unxt.Quantity`:
+
+```{code-block} python
+>>> qv[0]
+Quantity(Array(1., dtype=float32), unit='m')
+```
+
+## Guides
+
+- [Quantity matrices](quantity-matrix.md) — constructing `QuantityMatrix`, indexing, unit conversion, and arithmetic.
+- [Units matrices](units-matrix.md) — the immutable, hashable `UnitsMatrix` unit structure.
+- [Linear algebra](linear-algebra.md) — matmul, transpose, `diag`, `det`, and `inv` with per-element unit tracking.
+- [Tutorial: a heterogeneous metric](tutorial-metric.md) — a worked end-to-end example.
+- [Sharp bits](sharp-bits.md) — the 1-D/2-D restriction and the uniform-unit requirements under `jax.jit`.
+
+## Public API
+
+`unxts.linalg` exposes:
+
+- `QuantityMatrix` — the heterogeneous-unit matrix/vector (alias `QM`).
+- `UnitsMatrix` — the immutable, hashable per-element unit structure.
+- `matmul`, `matvec`, `vecmat`, `vecdot` — the four Array-API matrix/vector products, each resolving the batched matrix-vs-vector ambiguity that `@` alone cannot.
+- `det`, `inv` — unit-tracking determinant and inverse (with their JAX primitives `det_p`, `inv_p`).
+- `cdict_units` — extract per-key units from a component dictionary.
+
+Importing `unxts.linalg` also registers, as import side effects, the Quax primitive rules (add/sub, mul/div, dot-general/matmul, transpose, gather/diag, reduce-sum) and the `plum` conversions/dispatch that let `QuantityMatrix` interoperate with the rest of `unxt`.

unxts_linalg-2.0.0/docs/linear-algebra.md

@@ -0,0 +1,124 @@
+# Linear algebra with unit tracking
+
+The whole point of `QuantityMatrix` is that linear-algebra operations carry the per-element units through the computation. `unxts.linalg` registers Quax rules for the underlying JAX primitives, so the [`quaxed`](https://github.com/GalacticDynamics/quaxed) drop-in `numpy` operators work directly on `QuantityMatrix` objects.
+
+```{code-block} python
+>>> import jax.numpy as jnp
+>>> import quax
+>>> import unxt as u
+>>> import unxts.linalg as ul
+```
+
+## Matrix and vector products
+
+`unxts.linalg` exposes the four NumPy / Array-API contraction functions, each of which contracts the shared axis and multiplies the corresponding per-element units:
+
+| Function          | Operands        | Result            |
+| ----------------- | --------------- | ----------------- |
+| `ul.matmul(A, B)` | matrix × matrix | matrix            |
+| `ul.matvec(A, v)` | matrix × vector | vector            |
+| `ul.vecmat(v, A)` | vector × matrix | vector            |
+| `ul.vecdot(a, b)` | vector · vector | scalar `Quantity` |
+
+`matmul` contracts the shared axis and multiplies the corresponding units — here a dimensionless identity leaves a vector's units untouched:
+
+```{code-block} python
+>>> A = ul.QuantityMatrix(jnp.eye(3),
+...                       unit=(("", "", ""), ("", "", ""), ("", "", "")))
+>>> v = ul.QuantityMatrix(jnp.array([1.0, 2.0, 3.0]), unit=("m", "m", "m"))
+>>> ul.matvec(A, v).value
+Array([1., 2., 3.], dtype=float32)
+```
+
+Units on the contracted axis are combined and converted to a common reference, so mixed units are handled correctly:
+
+```{code-block} python
+>>> A2 = ul.QuantityMatrix(jnp.array([[1.0, 2.0], [3.0, 4.0]]),
+...                        unit=(("m", "km"), ("m", "km")))
+>>> v2 = ul.QuantityMatrix(jnp.array([1.0, 1.0]), unit=("s", "s"))
+>>> ul.matvec(A2, v2).value
+Array([2001., 4003.], dtype=float32)
+```
+
+A plain JAX array or an ordinary `unxt.Quantity` on one side is treated as dimensionless / uniform-unit respectively.
+
+### Batches
+
+A `QuantityMatrix` carries its logical 1-D/2-D units in the _trailing_ axes and treats _leading_ axes of the value array as batch dimensions. All four products — and the `@` operator — broadcast those batch axes. The `@` operator dispatches on the _logical_ rank (matrix vs vector), so a batch of matrices applied to a batch of vectors "just works":
+
+```{code-block} python
+>>> # A batch of 2 matrices applied to a batch of 2 vectors.
+>>> Ab = ul.QuantityMatrix(
+...     jnp.array([[[1.0, 2.0], [3.0, 4.0]], [[5.0, 6.0], [7.0, 8.0]]]),
+...     unit=(("m", "m"), ("m", "m")),
+... )
+>>> vb = ul.QuantityMatrix(jnp.ones((2, 2)), unit=("s", "s"))
+>>> (Ab @ vb).value
+Array([[ 3.,  7.],
+       [11., 15.]], dtype=float32)
+```
+
+There is one subtlety inherited from NumPy: a batched vector's value `(B, K)` is shape-indistinguishable from a matrix, so the raw **function** forms `jnp.matmul` / `quaxed.numpy.matmul` cannot express a batched matrix-vector product (and `ul.matmul` rejects it with a pointer to `matvec`). Use `@`, `ul.matvec`, or `ul.vecmat` — all of which name the ranks explicitly.
+
+## Transpose and diagonal
+
+`.T` swaps both the values and the unit structure of a 2-D matrix:
+
+```{code-block} python
+>>> a = ul.QuantityMatrix(jnp.array([[1.0, 2.0], [3.0, 4.0]]),
+...                       unit=(("m", "s"), ("kg", "rad")))
+>>> a.T.unit.to_string()
+'((m, kg), (s, rad))'
+```
+
+`.diag()` extracts the diagonal as a 1-D `QuantityMatrix`, operating directly on the static unit structure so it works under `jax.jit`:
+
+```{code-block} python
+>>> M = ul.QuantityMatrix(jnp.diag(jnp.array([1.0, 2.0, 3.0])),
+...                       unit=(("m", "s", "kg"),
+...                             ("m", "s", "kg"),
+...                             ("m", "s", "kg")))
+>>> d = M.diag()
+>>> d.unit.to_string()
+'(m, s, kg)'
+>>> d.value
+Array([1., 2., 3.], dtype=float32)
+```
+
+## Determinant and inverse
+
+`unxts.linalg` provides custom `det` and `inv` primitives with full JAX transform support (JIT, autodiff, vmap). On plain arrays they behave like `jnp.linalg.det` / `jnp.linalg.inv`; on a `QuantityMatrix` (wrapped with `quax.quaxify`) they additionally track units.
+
+The determinant multiplies the main-diagonal units:
+
+```{code-block} python
+>>> from unxts.linalg import det, inv
+>>> G = ul.QuantityMatrix(jnp.array([[2.0, 0.0], [0.0, 3.0]]),
+...                       unit=(("m2", "m2"), ("m2", "m2")))
+>>> quax.quaxify(det)(G)
+Quantity(Array(6., dtype=float32), unit='m4')
+```
+
+The inverse carries the reciprocal units:
+
+```{code-block} python
+>>> B = ul.QuantityMatrix(jnp.array([[4.0, 0.0], [0.0, 1.0]]),
+...                       unit=(("m2", "m2"), ("m2", "m2")))
+>>> r = quax.quaxify(inv)(B)
+>>> r.unit.to_string()
+'((1 / m2, 1 / m2), (1 / m2, 1 / m2))'
+>>> r.value
+Array([[0.25, 0.  ],
+       [0.  , 1.  ]], dtype=float32)
+```
+
+Because `det` and `inv` are real JAX primitives, they compose with `jax.jit`, `jax.grad`, and `jax.vmap` on plain arrays:
+
+```{code-block} python
+>>> import jax
+>>> jax.jit(det)(jnp.array([[2.0, 0.0], [0.0, 3.0]]))
+Array(6., dtype=float32)
+>>> jax.grad(det)(jnp.array([[2.0, 0.0], [0.0, 3.0]]))
+Array([[3., 0.],
+       [0., 2.]], dtype=float32)
+```

unxts_linalg-2.0.0/docs/quantity-matrix.md

@@ -0,0 +1,132 @@
+# Quantity matrices
+
+`QuantityMatrix` (alias `QM`) stores one numeric JAX array together with a static [`UnitsMatrix`](units-matrix.md) that gives the unit of **each** logical element. The shape of the unit structure decides whether the object behaves as a heterogeneous vector (1-D) or matrix (2-D).
+
+```{code-block} python
+>>> import jax.numpy as jnp
+>>> import unxt as u
+>>> import unxts.linalg as ul
+```
+
+## Construction
+
+A 1-D `QuantityMatrix` takes a flat array and a tuple of units, one per element:
+
+```{code-block} python
+>>> qv = ul.QuantityMatrix(jnp.array([1.0, 2.0, 3.0]), unit=("m", "s", "kg"))
+>>> qv.value
+Array([1., 2., 3.], dtype=float32)
+>>> qv.unit.to_string()
+'(m, s, kg)'
+>>> qv.ndim, qv.shape
+(1, (3,))
+```
+
+A 2-D `QuantityMatrix` takes a 2-D array and a nested tuple of units:
+
+```{code-block} python
+>>> qm = ul.QuantityMatrix(jnp.ones((2, 2)), unit=(("m", "s"), ("kg", "rad")))
+>>> qm.unit.to_string()
+'((m, s), (kg, rad))'
+>>> qm.ndim, qm.shape
+(2, (2, 2))
+```
+
+Leading dimensions of the value array are treated as batch dimensions; only the trailing 1 or 2 axes are "logical" and must match the unit structure.
+
+`QM` is a short alias for `QuantityMatrix` (mirroring `u.Q` for `Quantity`):
+
+```{code-block} python
+>>> ul.QM is ul.QuantityMatrix
+True
+```
+
+### From a component dictionary
+
+`QuantityMatrix.from_cdict` packs a dict of quantities into a 1-D matrix, preserving each entry's unit:
+
+```{code-block} python
+>>> v = {"x": u.Q(1.0, "m"), "y": u.Q(2.0, "s"), "z": u.Q(3.0, "kg")}
+>>> ul.QuantityMatrix.from_cdict(v).unit.to_string()
+'(m, s, kg)'
+```
+
+You may select and reorder a subset of keys:
+
+```{code-block} python
+>>> ul.QuantityMatrix.from_cdict(v, keys=("z", "x")).unit.to_string()
+'(kg, m)'
+```
+
+## Indexing
+
+Indexing a 1-D `QuantityMatrix` returns an ordinary `unxt.Quantity` — the element and its scalar unit:
+
+```{code-block} python
+>>> qv[0]
+Quantity(Array(1., dtype=float32), unit='m')
+>>> qv[2]
+Quantity(Array(3., dtype=float32), unit='kg')
+```
+
+Indexing a row of a 2-D matrix returns a 1-D `QuantityMatrix`, while a full `[i, j]` index returns a scalar `Quantity`:
+
+```{code-block} python
+>>> qm2 = ul.QuantityMatrix(jnp.ones((2, 3)),
+...                         unit=(("m", "s", "kg"), ("rad", "deg", "m")))
+>>> qm2[0]
+QuantityMatrix(Array([1., 1., 1.], dtype=float32), unit='(m, s, kg)')
+>>> qm2[1, 2]
+Quantity(Array(1., dtype=float32), unit='m')
+```
+
+## Arithmetic and unit conversion
+
+Addition and subtraction convert each element of the right operand into the corresponding unit of the left operand before combining; the result adopts the left operand's units:
+
+```{code-block} python
+>>> import quaxed.numpy as qnp
+>>> a = ul.QuantityMatrix(jnp.ones(3), unit=("m", "s", "kg"))
+>>> b = ul.QuantityMatrix(jnp.ones(3), unit=("km", "ms", "g"))
+>>> result = qnp.add(a, b)
+>>> result.unit.to_string()
+'(m, s, kg)'
+>>> result.value
+Array([1001.   ,    1.001,    1.001], dtype=float32)
+```
+
+Scalar multiplication scales the values and leaves the units unchanged:
+
+```{code-block} python
+>>> (2 * a).value
+Array([2., 2., 2.], dtype=float32)
+```
+
+You can convert a whole `QuantityMatrix` to a compatible unit structure with `uconvert`:
+
+```{code-block} python
+>>> q = ul.QuantityMatrix(jnp.array([[1.0, 2.0], [3.0, 4.0]]),
+...                       unit=(("m", "rad"), ("m", "rad")))
+>>> target = u.unit((("km", "deg"), ("km", "deg")))
+>>> q.uconvert(target).unit.to_string()
+'((km, deg), (km, deg))'
+```
+
+When every element shares the same unit, a `QuantityMatrix` converts to a plain `unxt.Quantity`:
+
+```{code-block} python
+>>> import plum
+>>> uniform = ul.QuantityMatrix(jnp.array([1.0, 2.0, 3.0]), unit=("m", "m", "m"))
+>>> plum.convert(uniform, u.Q)
+Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
+```
+
+Mixed units make that conversion ambiguous, so it is rejected:
+
+```{code-block} python
+>>> try:
+...     plum.convert(qv, u.Q)
+... except ValueError as e:
+...     print(e)
+Cannot convert QuantityMatrix to Quantity unless all units are identical.
+```

unxts_linalg-2.0.0/docs/sharp-bits.md

@@ -0,0 +1,60 @@
+# Sharp bits
+
+`QuantityMatrix` covers the common heterogeneous-unit vector/matrix cases, but a few restrictions follow from its design. Keep these in mind.
+
+```{code-block} python
+>>> import jax.numpy as jnp
+>>> import quaxed.numpy as qnp
+>>> import unxt as u
+>>> import unxts.linalg as ul
+```
+
+## Only 1-D and 2-D structures
+
+The unit structure is limited to 1-D (vector) and 2-D (matrix); there is no support for higher-rank _logical_ structures. (Leading **batch** dimensions on the value array are fine — only the trailing one or two axes are logical.)
+
+```{code-block} python
+>>> from unxts.linalg import UnitsMatrix
+>>> try:
+...     UnitsMatrix(jnp.zeros((2, 2, 2)))
+... except (TypeError, ValueError) as e:
+...     print("rejected")
+rejected
+```
+
+## `det` and `inv` and their unit assumptions
+
+`det` uses the product of the **main-diagonal** units, and `inv` requires a **uniform** unit that it can reciprocate — it raises `ValueError` on a heterogeneous-unit matrix, because a matrix inverse mixes entries and the per-element reciprocal would be wrong. These are exactly right for diagonal metrics and for matrices whose cofactor products share one physical dimension (the common case for coordinate metrics), but they are not general heterogeneous-unit determinants/inverses. Both require a 2-D matrix:
+
+```{code-block} python
+>>> import quax
+>>> v = ul.QuantityMatrix(jnp.array([1.0, 2.0]), unit=("m", "s"))
+>>> try:
+...     quax.quaxify(ul.det)(v)
+... except ValueError as e:
+...     print("needs a 2-D matrix")
+needs a 2-D matrix
+```
+
+## `diag` under `jax.jit` needs uniform units
+
+The `.diag()` **method** operates on the static unit structure and works for heterogeneous units, even under `jit`:
+
+```{code-block} python
+>>> M = ul.QuantityMatrix(jnp.diag(jnp.array([1.0, 2.0, 3.0])),
+...                       unit=(("m", "s", "kg"),
+...                             ("m", "s", "kg"),
+...                             ("m", "s", "kg")))
+>>> M.diag().unit.to_string()
+'(m, s, kg)'
+```
+
+By contrast `qnp.diag` lowers to a `gather`, whose indices are traced under `jit`; there the unit of each output element cannot be resolved individually, so **all units must be equal**. Prefer the `.diag()` method for heterogeneous-unit matrices.
+
+## The `matmul` _function_ can't do a batched matrix-vector product
+
+A batched vector's value `(B, K)` is shape-indistinguishable from a matrix. The **`@` operator is fine** — `QuantityMatrix.__matmul__` dispatches on the logical rank, so `A @ v` correctly does a (batched) matrix-vector product. But the raw **function** forms `jnp.matmul` / `quaxed.numpy.matmul` infer their contraction from the value shapes and so cannot; they silently succeed only when the sizes coincide and otherwise raise. `unxts.linalg.matmul` refuses a batched vector operand outright, pointing you at `matvec`. Prefer `@`, `ul.matvec`, or `ul.vecmat`. See [Linear algebra](linear-algebra.md#batches).
+
+## It is a Quax type, not a materialisable array
+
+`QuantityMatrix` is a `quax` array-ish value: it flows through `quax.quaxify`-ed functions but refuses to _materialise_ into a plain array (its elements have no single dtype-plus-unit), so use `.value` / `.unit` to inspect it, and `plum.convert(..., u.Q)` only when every unit is identical (see [Quantity matrices](quantity-matrix.md)).