unxts.parametric

unxts.parametric provides ParametricQuantity (alias PQ): a quantity that encodes its physical dimension in its type. It is the opt-in counterpart to the lightweight, non-parametric default unxt.Quantity.

ParametricQuantity used to be the default Quantity in unxt v1. As of v2 the non-parametric class is the default and the parametric class lives here, in its own package. See the migration guide for the full mapping.

Install

uv

uv add unxts.parametric

pip

pip install unxts.parametric

Throughout these pages we import unxt as u and unxts.parametric as up (so ParametricQuantity is up.PQ):

>>> import unxt as u
>>> import unxts.parametric as up

At a glance

ParametricQuantity is used just like Quantity, but it encodes the physical dimension in its type — and can check it at construction:

>>> up.PQ(1.0, "m")  # dimension inferred from the unit
ParametricQuantity(Array(1., dtype=float32, ...), unit='m')

>>> up.PQ["length"](1.0, "m")  # dimension checked against the unit
ParametricQuantity(Array(1., dtype=float32, ...), unit='m')

Should you use it?

Reach for ParametricQuantity only when you need one of its two extra features:

1. Runtime dimension checking — up.PQ["length"](1, "s") raises; the default u.Q["length"](1, "s") accepts the subscript for compatibility but does not check it.

2. Dispatch on specific dimensions — up.PQ["length"] is a real type usable in plum dispatch annotations; u.Q["length"] is just Quantity.

Everything else — arithmetic, unit conversion, JAX transforms, interop — works identically with either class. The cost of the parametric class, and why the non-parametric one became the default, is set out in the core docs under Why Quantity is not parametric; the comparison table against StaticQuantity is in the sharp bits.

Pages

Tutorial

• Let the type system catch a unit mistake — start here: watch a wrong unit get rejected at construction, then write a function that dispatches on physical dimension.

Reference

• ParametricQuantity — construction, runtime dimension checking, dimension-specific dispatch, promotion with the default Quantity, and dimension_of on a parametrized class.

• Configuration — the include_params display option.

How-to

• How to check dimensions at runtime — dimension annotations enforced by jaxtyping.

Discussion

• The parametric sharp bits — pytree-type proliferation and StaticValue equality.

Public API

unxts.parametric exposes:

• ParametricQuantity — the dimension-parametrized quantity (alias PQ).

• AbstractParametricQuantity — its abstract base.

• config — the unxts.parametric.config singleton (see Configuration).

Importing unxts.parametric also registers, as import side effects, the promotion rules, plum conversions, and JAX primitive rules that let ParametricQuantity interoperate with the rest of unxt.