# Release Notes

## Version 0.3.1

### Highlights

Version 0.3.1 is a compatibility release that makes ``saiunit.Quantity``
work with Matplotlib out of the box. Plotting a ``Quantity`` no longer
requires any setup — the unit converter is registered automatically when
``saiunit`` is imported and Matplotlib is installed, so ``ax.plot``,
``ax.scatter``, axis limits, reference lines, histograms, error bars,
box/violin plots, stack plots, hex bins, and pie charts accept
quantities directly and label axes with their units.

### New features

- **Quantity-aware ``errorbar``, ``boxplot``, ``violinplot``,
  ``stackplot``, ``hexbin``, and ``pie``.** These Axes methods coerce
  their inputs to arrays *before* Matplotlib's unit converter runs, so a
  bare ``Quantity`` previously raised. ``enable_matplotlib_support()`` now
  wraps each one: Quantity arguments are converted to plain magnitudes via
  the public API and the relevant axis is labeled with the unit, while
  calls without any ``Quantity`` pass through untouched. Error-bar
  magnitudes (``xerr``/``yerr``) and stacked series are rescaled into the
  axis unit; ``pie`` wedge sizes and ``hexbin`` ``C`` colour values, which
  have no axis-unit meaning, are reduced to their magnitudes. If a future
  Matplotlib release changes one of these method signatures, the affected
  wrapper raises a clear error naming the version the first time it is
  called with a ``Quantity`` (other functions and ``import saiunit`` are
  unaffected).

### Bug fixes

- **Matplotlib support is now enabled automatically on import.** Earlier
  releases registered the ``Quantity`` converter only when the caller
  invoked ``enable_matplotlib_support()`` explicitly; the documented
  ``examples/matplotlib_quantity_basics.py`` omitted that call and raised
  ``TypeError: Only dimensionless quantities can be converted to NumPy
  arrays``. The converter now registers at import time. Calling
  ``enable_matplotlib_support()`` remains supported for re-registering
  after the registry is cleared or for targeting a custom units module.
- **Scalar (0-d) quantities work as axis limits and reference lines.**
  ``Quantity.__iter__`` now raises eagerly on 0-d inputs, so
  ``numpy.iterable`` reports ``False`` exactly as it does for a 0-d
  ``ndarray``. This unblocks ``ax.set_xlim``/``ax.set_ylim``,
  ``ax.axhline``, and ``ax.axvline`` with scalar quantities, which
  previously crashed inside Matplotlib's ``_is_natively_supported`` check.
- **``ax.hist`` accepts quantities and keeps their units.** Histogram and
  other functions coerce their data with ``matplotlib.cbook._reshape_2D``
  *before* the unit converter runs. ``enable_matplotlib_support()`` now
  wraps that helper so ``Quantity`` data (single arrays or lists of
  per-dataset arrays) flows through to unit processing instead of failing
  the ``numpy.asanyarray`` coercion, and the histogram axis is labeled
  with the quantity's unit.
- **``ax.axhspan``/``ax.axvspan`` accept quantity bounds.** The converter
  now passes plain (non-Quantity) values through unchanged, fixing the
  double-conversion ``ConversionError`` raised when Matplotlib re-converts
  already-scaled patch coordinates. This also lets callers mix bare numbers
  onto a unit-bearing axis, matching Matplotlib's own semantics.

### Known limitations

- Two-dimensional scalar-field functions (``imshow``, ``contourf``,
  ``pcolormesh``, ``quiver``) treat a ``Quantity`` as colour/magnitude
  data rather than an axis coordinate, and Matplotlib offers no unit hook
  there. Pass ``.to_decimal(unit)`` and label the colour bar manually.

### Tests

- Expanded the Matplotlib compatibility suite to 43 tests covering
  auto-registration, ``plot``/``scatter`` axis-unit inference, scalar
  axis limits and reference lines, ``axhspan``/``axvspan`` and
  plain-number passthrough, cross-unit conversion and incompatible-unit
  errors, JAX-backed quantities, ``hist`` unit preservation, the
  ``errorbar``/``boxplot``/``violinplot``/``stackplot``/``hexbin``/``pie``
  wrappers, non-Quantity identity, and the fail-loud signature guard.
- **Closed test-coverage gaps across the public surface.** Added colocated
  test files for previously untested modules and functions: ``linalg``
  ``svdvals``/``eigvals`` unit propagation; ``math`` ``frexp``,
  ``promote_dtypes``, ``iscomplexobj``, the ``alltrue``/``sometrue``/
  ``cumproduct`` aliases, and ``einshape`` parsing; the ``jax_only``
  decorator guard; ``is_unit_equal``; 15 previously-untested physical
  constants; every unit shortcut and ``_alias`` re-export; and smoke tests
  for the ``_jax_compat``, ``_compatible_import``, and ``_typing`` shims.

## Version 0.3.0

### Highlights

Version 0.3.0 completes the multi-backend transition started in 0.2.2. The
entire public surface of ``saiunit.math``, ``saiunit.linalg``, ``saiunit.fft``,
and ``Quantity`` (including ``Quantity.at`` and every scatter operation) now
dispatches through the array-API standard, so the same source code runs
unchanged on ``numpy``, ``jax``, ``cupy``, ``torch``, ``dask``, and
``ndonnx``. A centralized argument-adaptation layer handles the
per-backend signature differences that previously produced ``TypeError``
on calls that the underlying operation supported.

This release also lands a static-typing pass — ``mypy saiunit/`` reports
zero errors across 111 source files, the new ``type_check`` CI job blocks
regressions, and the package ships a PEP 561 ``py.typed`` marker so
downstream type checkers honor the inline annotations.

### Breaking changes

- **Removed the ``compatible_with_equinox`` toggle and the
  ``compat_with_equinox`` global.** The Equinox compatibility shim, the
  Equinox branch in ``Quantity.__pow__``, and the associated tests, docs,
  and mypy overrides have been deleted. Equinox now works against saiunit
  via the same path as every other consumer.
- **Removed the ``promote_integers`` keyword from ``saiunit.math.sum`` and
  ``saiunit.math.prod``** (and the ``**kwargs`` catch-all that smuggled it
  through). This argument is JAX-only; forwarding it raised ``TypeError``
  on every non-JAX backend. Callers that need it should call
  ``jax.numpy.sum`` / ``jax.numpy.prod`` directly.
- **``Quantity(np.ndarray)`` no longer silently lifts to JAX** in code
  paths that previously did so. ``Quantity(mantissa, dtype=...)``, the
  ``Quantity.mantissa`` setter, and ``Quantity([q1, q2, ...])`` all now
  honor the active backend (or the input's existing backend) instead of
  defaulting to JAX whenever JAX is installed.
- **``Quantity.strides`` / ``.flat`` / ``.T`` / ``.mT`` raise
  ``BackendError`` on lazy mantissas** (``dask``, ``ndonnx``) instead of
  silently calling ``.compute()`` / ``.unwrap_numpy()``.
- **``Quantity.at`` on ``ndonnx`` mantissas raises ``BackendError``.**
  ndonnx builds a symbolic ONNX graph and has no notion of a functional
  in-place update; call ``.to_numpy()`` first to materialize.

### New features

#### Multi-backend ``Quantity.at`` and scatter dispatch

- **All nine ``.at[idx].<op>(...)`` operations** — ``get``, ``set``,
  ``add``, ``multiply``/``mul``, ``divide``/``div``, ``power``, ``min``,
  ``max``, ``apply`` — now work on ``numpy``, ``jax``, ``cupy``, ``torch``,
  and ``dask``. Unit-tracking semantics are unchanged: the same
  dimension/magnitude checks fire regardless of backend, and the result
  preserves the original mantissa backend.
- **Unified scatter dispatch (``saiunit._scatter``).** ``Quantity.at`` and
  ``Quantity.__setitem__`` / ``scatter_add`` / ``scatter_mul`` /
  ``scatter_div`` / ``scatter_max`` / ``scatter_min`` all route through
  one backend-aware module. ``CustomArray.__setitem__`` shares the same
  path, so user subclasses with non-JAX mantissas work without a JAX
  install.
- **Emulated ``mode`` and ``fill_value`` on non-JAX backends.** JAX's
  ``mode`` (``'promise_in_bounds'``/``'clip'``/``'drop'``/``'fill'``) and
  ``fill_value`` arguments are emulated on ``numpy``/``cupy``/``torch``
  for scalar-int and 1D-integer-array indices, so
  ``x.at[20].get(mode='fill', fill_value=-1 * u.mV)`` runs unchanged
  across backends.

#### Complete multi-backend coverage for ``saiunit.math`` / ``linalg`` / ``fft``

- Every direct ``jnp.*`` / ``jax.tree.*`` / ``jax.lax.*`` call in
  ``saiunit/math/_fun_{change,keep,remove,array_creation,accept}_unit.py``,
  ``saiunit/_misc.py``, ``saiunit/fft/``, and ``saiunit/linalg/`` now goes
  through ``get_backend()`` + ``_resolve_op()`` so the same code path
  works on numpy/torch/dask/ndonnx in addition to JAX.
- Mechanical replacements where backends diverge: ``remove_diag`` uses
  ``~xp.eye`` instead of ``jnp.fill_diagonal`` (which numpy implements
  in-place returning ``None``); ``meshgrid`` uses
  ``xp.broadcast_to`` + ``reshape`` instead of ``jax.lax.broadcast_in_dim``;
  ``compress`` / ``extract`` / ``unique`` / ``where(cond)`` /
  ``searchsorted`` drop JAX-only kwargs (``size``, ``fill_value``,
  ``method``) when the backend doesn't accept them.

#### Centralized dispatch layer

- **New ``_dispatch_call`` pipeline in
  ``saiunit.math._fun_keep_unit``** combines two adaptation layers:
  ``_filter_unsupported_kwargs`` (signature introspection) and
  ``_safe_call`` (``TypeError``-message parsing for C-bindings such as
  torch). All dispatch helpers (``_fun_keep_unit_*``,
  ``_fun_change_unit_*``, ``_fun_remove_unit_*``, ``_fun_logic_*``,
  ``_fun_accept_unitless_*``, ``_fun_unitless_binary``) route through it,
  and the ``_fun_array_creation`` call sites use a matching
  ``_safe_call_xp`` shim.
- **Centralized ``None``-kwarg stripping (``_strip_none_kwargs``)** in
  the same dispatch helpers — wrapper call sites pass kwargs naturally
  instead of inline ``_drop_none(...)`` plumbing.
- **Per-wrapper signature fixes** so the generated backend-support
  matrix reports zero ``TypeError``-style argument mismatches:
  ``split`` / ``array_split`` forward ``indices_or_sections``
  positionally; ``transpose`` / ``swapaxes`` / ``tile`` /
  ``expand_dims`` / ``squeeze`` pass axis arguments in the form each
  backend accepts; ``cumsum`` / ``nancumsum`` / ``cumprod`` /
  ``nancumprod`` emulate numpy's ``axis=None`` flatten semantics via a
  new ``_maybe_flatten`` helper so torch's array-API binding stays
  happy; ``histogram`` / ``take`` / ``select`` / ``unique`` rewritten to
  use ``_strip_none_kwargs`` + dispatch helper; ``corrcoef`` / ``cov``
  dispatch unary when ``y is None``; ``nan_to_num`` routes per-block via
  numpy on dask; ``eye`` / ``tri`` pass ``k`` as a keyword and
  materialize a default dtype for dask auto-chunking; ``bincount`` only
  forwards JAX's ``length=`` when set.
- **Backend-aware dtype translation (``_translate_dtype``)** in
  ``saiunit/_backend.py`` maps numpy dtype objects to each backend's
  native attribute, fixing ``arange``, ``astype``, ``tril_indices``,
  ``triu_indices``, and the ``Quantity.astype`` method on torch and
  ndonnx (both of which reject numpy dtypes).

#### Consolidated typing module

- **New ``saiunit/_typing.py`` module** with ``Array``, ``ArrayLike``,
  ``ScalarOrArrayLike``, ``DTypeLike``, ``Shape``, ``Axis``, ``Axes``,
  and ``PyTree``. Every ``jax.Array`` / ``jax.typing.DTypeLike``
  reference in production code (annotations and docstrings) now uses
  these aliases. ``saiunit.typing`` re-exports the module so the public
  import path is unchanged.
- The new ``ArrayLike`` is narrow — it deliberately excludes bare Python
  scalars (``bool``/``int``/``float``/``complex``) so that
  ``.shape`` / ``.ndim`` / ``.dtype`` reads do not produce union-attr
  false positives. Approximately 658 ``jax.typing.ArrayLike`` references
  across ``lax`` / ``math`` / ``fft`` / ``linalg`` / ``sparse`` have
  been migrated.

### Improvements

#### ``Quantity`` core

- ``Quantity(mantissa, dtype=...)`` honors ``dtype`` on
  cupy / torch / dask / ndonnx mantissas (previously silently ignored).
- ``Quantity.mantissa`` setter coerces the new value to the *existing*
  backend of the ``Quantity`` rather than silently lifting
  torch / cupy / dask / ndonnx arrays to JAX.
- ``_check_units_and_collect_values`` (the helper behind
  ``Quantity([q1, q2, ...])``) honors ``set_default_backend()`` /
  ``using_backend()`` instead of always landing on JAX when JAX is
  installed.
- ``Quantity.shape`` prefers ``m.shape`` for ``array_api_compat`` backends
  that do not expose ``xp.shape``; ``Quantity.repeat``, ``round``,
  ``argmax``, ``argmin``, ``take``, ``nanprod``, ``expand_dims``, and
  ``unsqueeze`` resolve their backend at call time via ``_xp_attr`` and
  pick the calling form each backend accepts.

#### Activation functions

- ``relu``, ``sigmoid``, ``softplus``, ``gelu``, … now guard with
  ``require_jax_backend`` and raise a clean ``BackendError`` on non-JAX
  inputs (instead of crashing with
  ``AttributeError: 'NoneType' object has no attribute 'relu'``).
  ``leaky_relu`` is implemented via ``where`` and remains
  backend-agnostic.
- ``Quantity.at`` docstring now ships a per-backend repeated-index
  semantics table.

#### Lazy / symbolic backends

- ``isnan`` / ``isinf`` / ``isfinite`` / ``isreal`` / ``gradient`` route
  through ``get_backend(...)`` rather than hard-coded ``jnp.*``, so
  non-JAX arrays no longer hit a numpy-only path.
- ``saiunit.fft.fftn`` / ``ifftn`` / ``rfftn`` / ``irfftn`` no longer
  force Python-scalar / list inputs through ``jnp.asarray`` for the
  input-ndim probe.

### Backend-specific notes

- **NumPy / CuPy:** repeated-index updates under ``Quantity.at`` use
  ``np.<op>.at`` / ``cupy.<op>.at`` so the JAX "all-updates-applied"
  semantics carry over.
- **PyTorch:** ``add`` uses ``index_put_(accumulate=True)`` and matches
  JAX for repeated indices. ``multiply`` / ``divide`` / ``min`` / ``max``
  / ``apply`` use gather + op + scatter and follow last-write-wins
  semantics for repeated indices (one of the rare places torch's native
  semantics differ from JAX).
- **Dask:** ``Quantity.at`` updates are expressed via ``da.where`` over
  a positional boolean mask, so the task graph stays lazy and chunked.
  Supported index types: scalar int, 1D integer array, slice, ellipsis,
  and same-shape boolean mask.
- **ndonnx:** ``Quantity.at[...].set/get/...`` raises ``BackendError``;
  ``saiunit.fft.tril_indices`` / ``triu_indices`` use a static numpy
  fallback wrapped with ``xp.asarray`` (ndonnx exposes no native
  ``tril_indices``).

### Known limitations

- ``mode`` emulation on ``.at[...]`` is best-effort on non-JAX backends
  for scalar-int and 1D-integer-array indices only.
  Slice/boolean/ellipsis indices ignore ``mode`` because they cannot go
  out of bounds against a same-shape source.
- ``dask`` does not yet support multi-dim fancy integer indexing under
  ``.at``; use ``.to_numpy()`` for those patterns.
- After the dispatch sweep, every remaining non-pass cell in the
  function-level support matrix traces to a genuine missing-attribute or
  ``NotImplementedError`` on the backend rather than a saiunit-side
  argument mismatch. The 11 remaining ndonnx fails are real backend
  limitations (no ``complex128``; ``NotImplementedError`` for
  ``copysign`` / ``expm1`` / ``hypot`` / ``log1p`` / ``nextafter`` /
  ``signbit``).

### Documentation

- **Function-level backend support matrix.** New generated rst page
  (``docs/backends/feature_support_matrix.rst``) documents per-(function,
  backend) support across the five locally-installed backends, covering
  294 mapped + 47 non-dispatched entries in ``saiunit.math``, all 35 in
  ``saiunit.linalg``, all 16 in ``saiunit.fft``, and 78/79 ``Quantity``
  methods. Companion tooling (``dev/backend_support_sweep.py``,
  ``dev/backend_support_render.py``,
  ``dev/backend_support_data.json``) produces a byte-deterministic,
  reproducible sweep.
- **Installation guide rewrite** (``docs/getting_started/installation.rst``).
  Full reference covering requirements, quick install, per-extra
  options, combining rules, source/editable install, install
  verification, upgrade/uninstall, troubleshooting (``BackendError``,
  CUDA mismatch, CuPy runtime, PyTorch wheel pitfalls), and BrainX
  ecosystem install. The landing page (``index.rst``) keeps only the
  two most common install commands and links out to the full reference.
- Per-backend Jupyter notebooks (``numpy``, ``jax``, ``torch``, ``dask``,
  ``ndonnx``, ``overview``) refreshed with updated outputs and
  markdown formatting.
- Chaobrain ecosystem documentation links (``brainmodeling``,
  ``brainstate``, ``brainpy-state``, ``brainunit``, ``braincell``,
  ``brainmass``, ``brainevent``, ``braintrace``, ``braintools``)
  redirected from ``*.readthedocs.io`` to the new
  ``brainx.chaobrain.com`` domain. Third-party RTD links remain
  intact.
- BrainUnit README header / Sphinx logo serves
  ``brainunit.webp`` from ``brainx.chaobrain.com`` (~91% bandwidth
  saving). The top-level SAIUnit README continues to use its local
  ``logo.png`` identity.

### Type checking

- **``mypy saiunit/`` reports zero errors** across 111 source files
  (down from 2,019 before the cleanup). The new ``type_check`` CI job
  blocks any regression on PRs.
- Targeted ``# type: ignore`` comments are limited to documented stub
  gaps (``jax.lax`` ``Array`` vs the narrow ``ArrayLike``,
  ``absl-py`` ``parameterized.product`` limitations in tests, missing
  third-party stubs for ``brainstate`` / ``cupy`` / ``opt_einsum`` /
  ``jax.util``).
- ``[[tool.mypy.overrides]]`` in ``pyproject.toml`` carries
  ``ignore_missing_imports = true`` for optional backend libraries so
  the CI ``type_check`` job does not need to install ~1 GB of extras.

### Packaging

- **PEP 561 ``py.typed`` marker** shipped in both ``saiunit`` and
  ``brainunit`` package roots and declared in package-data, so
  downstream type checkers (mypy, pyright) honor the inline
  annotations.
- ``setuptools.packages.find`` now excludes the ``brainunit*`` subtree
  from the ``saiunit`` wheel — the wheel drops from ~180 to 130 entries
  with no brainunit references, while ``saiunit/py.typed`` still ships.

### CI

- **Five per-backend isolation jobs** (``test_pure_numpy``,
  ``test_pure_jax``, ``test_pure_torch``, ``test_pure_dask``,
  ``test_pure_ndonnx``) on ``CI.yml``. Each installs exactly one array
  backend on top of ``requirements.txt`` and runs the full suite with
  ``SAIUNIT_DEFAULT_BACKEND`` set, verifying that
  ``pip install saiunit[<backend>]`` works end-to-end and that no other
  backend library leaks in. ``cupy`` is intentionally excluded —
  GitHub free runners have no GPU.
- ``conftest.py`` reads ``SAIUNIT_DEFAULT_BACKEND`` at session start,
  calls ``set_default_backend``, and skip-collects any test file that
  imports ``jax`` at module level when ``HAS_JAX`` is ``False`` so the
  no-jax CI variants don't crash during collection.
- ``test_pure_jax`` installs the in-tree ``brainunit`` over the
  PyPI-pinned copy via ``make_brainunit_setup.py`` +
  ``--force-reinstall --no-deps`` so the checkout's API surface (after
  the Equinox-shim removal) is the one being tested.
- ``deploy-docs.yml`` drops the ``push:main`` build-only trigger:
  ``release:released`` and ``workflow_dispatch`` both build and deploy
  the docs; the redundant build-only path on push is gone.

### Removed

- The ``compatible_with_equinox`` toggle, ``compat_with_equinox``
  global, the Equinox branch in ``Quantity.__pow__``, the associated
  tests, the docs reference, and the mypy ignore overrides for the
  Equinox path.
- The ``promote_integers`` keyword and ``**kwargs`` catch-all from
  ``saiunit.math.sum`` and ``saiunit.math.prod`` (see *Breaking
  changes*).

## Version 0.2.2

### Highlights

This release turns saiunit into a multi-backend library. ``Quantity`` can now
wrap NumPy, JAX, CuPy, PyTorch, Dask, and ndonnx arrays, with operations
dispatched via the array API standard (``array_api_compat``). JAX is now an
**optional** dependency — the core package installs and runs on NumPy alone.
This release also lands a 22-issue audit of ``Unit`` naming, display, hashing,
and parsing, and tightens correctness in ``Quantity``'s hash/equality and
tracer interactions.

### Breaking Changes

- **JAX is no longer a mandatory dependency.** Install with ``pip install
  saiunit`` for the NumPy-only build, or ``pip install "saiunit[jax]"`` (or
  ``[cpu]``/``[cuda12]``/``[cuda13]``/``[tpu]``) to enable JAX. Without JAX,
  the default backend auto-selects ``"numpy"`` and JAX-only modules
  (``saiunit.autograd``, ``saiunit.lax``, ``saiunit.sparse``) raise
  ``BackendError`` on import with an install hint.
- ``Quantity(np.ndarray(...))`` now preserves the mantissa as ``np.ndarray``
  instead of implicitly converting to ``jax.Array``. Call ``.to_jax()`` or
  use ``with using_backend("jax"):`` to restore the previous behaviour.
- ``Quantity`` is now **unhashable** (``__hash__ = None``). ``Quantity.__eq__``
  returns an array, so any hash implementation would violate the hash/eq
  invariant. This matches NumPy/JAX array semantics across all backends.
- ``Unit(dim, base=B)`` with ``B != 10`` now raises ``ValueError``. Previously
  the non-decimal base was silently folded into ``factor`` and then forgotten.
  Encode non-decimal scales directly in ``factor``.
- ``Unit("symbol", scale=..., factor=..., name=..., ...)`` now raises
  ``TypeError`` when extra construction kwargs are combined with a string
  ``dim``. Previously the extras were silently dropped.
- ``Unit(dim, factor=...)`` now raises ``ValueError`` for NaN or infinite
  factors instead of constructing a poisoned unit that propagated NaN through
  all subsequent arithmetic.
- ``Quantity + Unit`` and ``Unit + Quantity`` now both raise ``TypeError``
  symmetrically. Previously the former silently promoted the bare Unit to
  ``Quantity(1, unit)`` while the latter raised — making ``q + metre`` and
  ``metre + q`` produce different results.

### New Features

#### Multi-backend support

- **NumPy backend.** ``Quantity`` can wrap ``np.ndarray`` directly; math,
  linalg, and fft operations dispatch through ``array_api_compat``.
- **CuPy backend** (``saiunit[cupy]``). GPU arrays via the CuPy array API,
  with ``Quantity.to_cupy(device=None)`` for conversion.
- **PyTorch backend** (``saiunit[torch]``). Torch tensors with
  ``Quantity.to_torch(device=None, dtype=None)``.
- **Dask backend** (``saiunit[dask]``). Lazy chunked arrays via
  ``Quantity.to_dask(chunks='auto')``; ``__repr__`` and other materializing
  methods are lazy-safe and guarded to avoid implicit computation.
- **ndonnx backend** (``saiunit[ndonnx]``). Symbolic ONNX-graph arrays via
  ``Quantity.to_ndonnx()`` for export-oriented workflows.
- ``saiunit[all]`` meta-extra installs every optional backend.

#### Backend control API

- ``Quantity.backend`` property reporting the active backend name
  (``'numpy'``, ``'jax'``, ``'cupy'``, ``'torch'``, ``'dask'``, ``'ndonnx'``).
- ``Quantity.to_numpy()`` / ``.to_jax()`` / ``.to_cupy()`` / ``.to_torch()``
  / ``.to_dask()`` / ``.to_ndonnx()`` conversion methods.
- ``saiunit.set_default_backend()``, ``saiunit.get_default_backend()``, and
  ``saiunit.using_backend()`` context manager for controlling the default
  backend when input backend is ambiguous (Python scalars, list inputs).
- ``saiunit.is_numpy_array()``, ``is_jax_array()``, ``is_cupy_array()``,
  ``is_torch_array()``, ``is_dask_array()``, and ``is_ndonnx_array()``
  detector helpers.
- ``Quantity.__array_ufunc__`` so calls like ``np.sin(quantity)`` and
  ``np.add(q1, q2)`` preserve units instead of stripping them.
- ``saiunit.BackendError`` exception type (subclass of ``TypeError``) raised
  by JAX-only modules (``saiunit.lax``, ``saiunit.sparse``,
  ``saiunit.autograd``, and the custom ``exprel`` primitive) when given a
  non-JAX backend, with a clear ``"call .to_jax() first"`` (or install)
  hint.

#### Unit additions

- SI-prefixed kelvin variants (``ykelvin`` through ``Ykelvin``, including
  ``mK``, ``uK``, ``nK``, ``kK``, ``MK``), bringing kelvin in line with
  every other base unit. ``parse_unit("mK")`` now succeeds.

### Improvements

#### Unit display, hashing, and parsing (22-issue audit)

- **Compound-exponent normalization.** ``metre * metre2`` now displays as
  ``m^3`` instead of ``m * m^2``; display parts are merged after compound
  arithmetic.
- **Eager standard-name resolution.** Compound results from
  ``__mul__``/``__div__``/``__pow__`` now write the resolved standard-unit
  name into ``self._name``/``self._dispname`` at construction time, keeping
  ``unit.name``, ``unit.dispname``, and ``str(unit)`` in sync. Display
  parts survive ``copy``, ``deepcopy``, and pickle round-trips.
- **Hash/eq invariant restored.** ``Unit.__hash__`` no longer folds in
  spelling fields (``name``/``dispname``), so aliases like ``metre`` and
  ``meter`` hash and compare consistently — sets and dicts no longer hold
  silent duplicates. ``Unit.__eq__`` now compares
  ``(dim, scale, base, factor, _canonical_str())``, with a new
  ``is_unit_equal_math()`` helper for name-agnostic math equivalence;
  ``has_same_unit()`` delegates to it.
- **Built-in units win over user aliases.** ``add_standard_unit`` now
  stamps a monotonic registration index; built-ins (registered during
  import) outrank user-added aliases, so registering
  ``Unit(metre.dim, name="aaaa_meter")`` no longer hijacks the canonical
  metre display. Alphabetical order remains the tie-breaker for
  same-batch registrations.
- **Named-dimensionless identity preserved.** ``radian * UNITLESS``,
  ``radian ** 1``, and ``UNITLESS * radian`` now render as ``rad`` instead
  of collapsing to bare ``Unit("1")``; ``radian * radian`` → ``rad^2``;
  ``radian / radian`` → ``1`` (genuine cancellation).
- **Parser improvements.** ``parse_unit`` now accepts parenthesised
  sub-expressions in numerators (``(m * s) / A``), and numeric-base tokens
  like ``"2^3"`` are encoded as ``Unit(DIMENSIONLESS, factor=8.0)`` rather
  than raising. Anonymous ``Unit`` instances (constructed without a
  ``name``) now render with parser-compatible grammar, so
  ``parse_unit(repr(u))`` round-trips for any anonymous unit.

#### Core correctness

- **Tracer safety.** ``Quantity.update_mantissa()`` and ``__setitem__`` now
  raise a clear ``RuntimeError`` when called on a traced mantissa, instead
  of producing silently wrong state.
- **JIT-safe reductions.** New ``_reduction_count_from_shape`` and
  ``_is_concrete_zero`` helpers ensure reductions stay JIT-safe, and the
  "0 is dimensionless" convention only applies to concrete zeros — never
  tracers.
- **Foreign-tensor rejection.** ``require_jax_backend`` now names the
  offending backend and rejects foreign tensors (CuPy, Torch, Dask,
  ndonnx) at JAX-only entry points.

### Documentation

- New multi-backend user-guide sections covering NumPy, CuPy, PyTorch,
  Dask (lazy semantics), and ndonnx (symbolic execution).
- Per-backend Jupyter notebooks demonstrating end-to-end workflows.
- Updated installation docs covering the new extras layout (``jax``,
  ``cpu``, ``cuda12``, ``cuda13``, ``tpu``, ``cupy``, ``torch``, ``dask``,
  ``ndonnx``, ``all``).
- Sphinx ``conf.py`` gates brainx header injection on ``TARGET=brainunit``;
  docs build/deploy split (deploy on release, build-only on main push).

### Dependencies

- New mandatory runtime dependencies: ``array_api_compat>=1.9`` and
  ``opt_einsum``.
- ``jax`` moved to the ``[jax]`` optional extra. Install with
  ``pip install "saiunit[jax]"`` (or ``[cpu]`` / ``[cuda12]`` / ``[cuda13]``
  / ``[tpu]``) to enable JAX-backed features.
- New optional extras: ``[cupy]``, ``[torch]``, ``[dask]``, ``[ndonnx]``,
  and the ``[all]`` meta-extra.

### Internal / CI

- New ``_jax_compat`` module centralizes safely-degradable JAX symbols
  (sentinel classes, no-op decorators, NumPy fallbacks for
  ``dtypes``/``result_type``/tree-ops) when JAX is missing.
- New ``test_no_jax`` CI job installs without JAX and verifies imports
  plus ``BackendError`` gates; ``_no_jax_test.py`` smoke suite added.
- CI now installs CPU-only PyTorch wheels (``--index-url
  https://download.pytorch.org/whl/cpu``) to avoid multi-GB CUDA pulls on
  GPU-less runners.
- CI matrix extended to install ``cupy``/``torch``/``dask``/``ndonnx`` on
  all platforms so the new backends are exercised in regression tests.
- ``brainunit`` legacy package now re-exports the new backend API
  (``BackendError``, ``is_unit_equal_math``, ``set_default_backend``,
  ``using_backend``, backend detectors).
- Dependency bumps: ``actions/checkout`` 4→6, ``actions/setup-python``
  5→6, ``actions/download-artifact`` 5→8, ``appleboy/ssh-action``
  1.2.0→1.2.5, ``appleboy/scp-action`` 0.1.7→1.0.0, ``sphinx`` ≥8.1.3,
  ``sphinx-book-theme`` ≥1.1, ``sphinx-copybutton`` ≥0.5.2,
  ``jupyter-sphinx`` ≥0.5.3.

## Version 0.2.1

### Breaking Changes

- **Removed `BlockCSR` and `BlockELL` sparse classes**: These experimental
  block-sparse matrix implementations (along with their benchmarks and tests)
  have been removed. Users should use `COO`, `CSR`, or `CSC` instead.
- **`SparseMatrix` no longer inherits from `JAXSparse`**: The base class is now
  standalone, with its own `shape`, `size`, `ndim`, `T`, `block_until_ready`,
  `tree_flatten`, `tree_unflatten`, `transpose`, and `todense` interface.

### Improvements

- **Forward-compatible `**kwargs` across all wrapped functions**: All unit-aware
  wrapper functions in `math`, `lax`, `linalg`, and `fft` modules now accept
  and forward `**kwargs` to the underlying JAX functions. This ensures
  compatibility with new keyword arguments added in future JAX releases without
  requiring saiunit updates.
  - `saiunit.math`: `concatenate`, `stack`, `vstack`, `hstack`, `dstack`,
    `column_stack`, `block`, `append`, `split`, `array_split`, `dsplit`,
    `hsplit`, `vsplit`, `tile`, `repeat`, `sort`, `argsort`, `unique`,
    `searchsorted`, `where`, `clip`, `interp`, and many more
  - `saiunit.lax`: `cond`, `switch`, `scan`, `while_loop`, `fori_loop`,
    `sort`, `top_k`, `broadcasted_iota`, `concatenate`, `conv`, `pad`,
    `slice`, `dynamic_slice`, `gather`, `scatter`, and many more
  - `saiunit.linalg`: `svd`, `cholesky`, `eig`, `eigh`, `eigvalsh`, `qr`,
    `lu`, `solve`, `det`, `norm`, `matrix_power`, `cross`, `tensordot`, etc.
  - `saiunit.fft`: `fft`, `ifft`, `fft2`, `ifft2`, `fftn`, `ifftn`, `rfft`,
    `irfft`, `rfft2`, `irfft2`, `rfftn`, `irfftn`, `fftshift`, `ifftshift`
- **Standalone `SparseMatrix` base class**: Decoupled from
  `jax.experimental.sparse.JAXSparse` to reduce external coupling and provide a
  self-contained sparse matrix interface with properties (`size`, `ndim`, `nse`,
  `dtype`) and methods (`__repr__`, `__len__`, `block_until_ready`).
- **Improved validation in sparse classes**: Replaced `assert` statements with
  descriptive `ValueError` exceptions in `COO.with_data`, `CSR.with_data`, and
  `CSC.with_data` for shape, dtype, and unit mismatches.
- **Broader sparse type checking**: `isinstance` checks in binary and matmul
  operations now accept both `JAXSparse` and `SparseMatrix`, ensuring correct
  behavior after the inheritance change.
- **Fixed `CSC.tree_unflatten` error message**: Corrected the error message from
  `"CSR.tree_unflatten"` to `"CSC.tree_unflatten"`.
- **Explicit attribute assignment in `tree_unflatten`**: `CSR` and `CSC` now set
  `shape`, `indices`, and `indptr` explicitly instead of using
  `__dict__.update`, improving clarity and avoiding potential issues.

---

## Version 0.2.0

### Highlights

This release introduces unit-aware type annotations, string-based unit parsing,
enhanced Matplotlib integration, and a comprehensive overhaul of error handling
and unit display semantics.

### New Features

- **Unit-aware type annotations** (`saiunit.typing`): Added `QuantityLike`,
  `UnitLike`, and related type aliases using `typing.Annotated` (PEP 593) for
  expressing physical-unit constraints in Python type hints.
- **String-based unit parsing**: `Quantity` now accepts string unit
  specifications during initialization (e.g., `Quantity(1.0, "meter")`).
- **Matplotlib `QuantityConverter`**: Full integration with Matplotlib's unit
  conversion framework, enabling direct plotting of `Quantity` objects with
  automatic axis labeling and unit display.
- **`unit_to_scale` parameter for activation functions**: Activation functions
  now accept an optional `unit_to_scale` parameter for explicit unit conversion.
- **`symmetrize_input` parameter**: Added to `cholesky`, `eigvalsh`, and `svd`
  for optional input symmetrization before decomposition.
- **`amu` alias**: Added `amu` as an alias for `atomic_mass` / `u` / `um_u`.
- **`concrete_or_error` shim**: Compatibility shim for `jax.core.concrete_or_error`
  to maintain support across JAX versions.
- **FFT `shape` parameter**: `_calculate_fftn_dimension` now supports a `shape`
  parameter for explicit output shape specification.

### Improvements

- **Unified unit display format**: Refactored `display_in_unit` and unit
  representation methods for consistent, human-readable output. Normalized
  exponent representation and improved formatting for dimensionless units.
  Removed the `python_code` parameter in favor of unified display.
- **Error handling overhaul**: Replaced `assert` statements with proper
  `TypeError` and `ValueError` exceptions across the codebase (`Quantity`,
  einops, lax, FFT, and unit-related functions) for clearer, more informative
  error messages.
- **Updated physical constants** (CODATA 2018): `atomic_mass`, `electron_volt`,
  `light_year`, `atmosphere`, `acre`, `fluid_ounce_imp`, `Btu_th`,
  `speed_of_sound`, and `IMF` now use more accurate conversion factors.
- **Improved display names**: `survey_foot` / `survey_mile` now show
  `"US survey ft"` / `"US survey mi"`; `gallon_imp` shows `"imp gal"`;
  `fluid_ounce_imp` shows `"imp fl oz"`; `month` shows `"mon"`;
  `Btu_IT` shows `"Btu"`.
- **Unit preference scoring**: Standard unit retrieval now uses preference
  scoring for aliases, ensuring compound unit representations maintain grouping.
- **Removed `iscompound` attribute** from the `Unit` class, simplifying the
  internal representation.
- **Cumulative product functions**: Enhanced handling for unit-aware quantities.
- **Jacobian and vector gradient**: Refactored to use `_argnums_partial` for
  improved multi-argument handling; added tests for list-style `argnums`.
- **Sparse matrix improvements**: Refactored unit handling in `BlockCSR` and
  `BlockELL`; added `transpose` method.
- **Module organization**: Restructured imports across `__init__.py` and
  submodules for consistency; defined `__all__` for decorators and constants.
- **Type annotations modernized**: Updated `Union[A, B]` to `A | B` syntax
  throughout the codebase.
- **Documentation**: Updated docstrings with examples for unit-aware functions;
  added installation instructions for CUDA and TPU; refreshed all Jupyter
  notebook examples.
- **Copyright updated** to BrainX Ecosystem Limited.

### Bug Fixes

- Fixed issue #17 (unit display edge case).
- Fixed cumulative product operations for unit-aware quantities.
- Fixed error handling in tests: corrected expected exception types from
  `AssertionError` to `TypeError` for invalid input cases.

### Internal / CI

- Refactored version handling and updated main entry point structure.
- Removed deprecated JAX version testing from CI configuration.
- Added `brainstate` to optional testing dependencies.
- Updated CI configurations to include BrainUnit installation steps.
- Removed `sys.version_info` checks for Python version compatibility.

---

## Version 0.1.4

- Added numerically stable `exprel` function with comprehensive test coverage
- Updated lax array creation to use `jax.numpy` for zero initialization
- Updated CI JAX version for improved compatibility
- Improved code quality and removed redundant tests

## Version 0.1.3

- Compatible with `jax>=0.8.2`


## Version 0.1.2

- Renamed ``CustomArray.value`` to ``CustomArray.data`` for API consistency
- Streamlined math unwrapping for improved performance
- Refactored math module for better Quantity/CustomArray support
- Added dtype aliases for convenience
- Fixed matplotlib convert for zero-sized inputs
- Registered Array class as a PyTree node for JAX compatibility
- Added support for Python 3.14
- Updated CI configuration and dependencies

## Version 0.1.1

- Fixed dimension and unit checks in convert method to handle empty input
- Bug fixes and stability improvements

## Version 0.1.0

- Introduced ``CustomArray`` class and integrated it across saiunit modules
- Added ``Array`` class inheriting from ``CustomArray``
- Added ``maybe_custom_array`` and ``maybe_custom_array_tree`` utilities for type checking
- Added comprehensive unit tests for CustomArray integration
- Improved support for einops, activation functions, FFT, and linear algebra operations
- Enhanced Celsius conversion functions with CustomArray compatibility
- Added tutorial and documentation for CustomArray

## Version 0.0.19

- Added ``CustomArray`` class as the foundation for custom array types
- Refactored activation functions to support CustomArray
- Added ``gather`` function
- Refined ``math``, ``linalg``, ``autograd``, and constants modules
- Enabled Quantity hashing with ``__hash__`` method
- Fixed interp function and adjusted unit handling in output
- Moved metadata from setup.py to pyproject.toml

## Version 0.0.2

The new version of ``saiunit``, which separates the ``Quantity`` into the ``mantissa`` and the ``unit``.

This design is more flexible and allows for more complex operations, enabling to represent the very
large or very small values.

## Version 0.0.1

The first release of the project.