unxt.quantity

Contents

unxt.quantity#

Quantities in JAX.

This module provides JAX-compatible quantity types with automatic unit handling, conversions, and a rich set of mathematical operations that preserve dimensional correctness.

## Core Classes

  • `Quantity`: The main quantity class with dimension parametrization and full unit checking. Aliased as Q for convenience.

  • `StaticQuantity`: Parametric quantity with static NumPy values for JAX static arguments.

  • `BareQuantity`: Lightweight quantity without dimension parametrization.

  • `Angle`: Specialized quantity type for angular measurements with wrapping support.

## Key Functions

  • `uconvert`: Convert a quantity to different units.

  • `ustrip`: Extract the numerical value from a quantity.

  • `is_unit_convertible`: Check if two units are convertible to each other.

  • `wrap_to`: Wrap angular quantities to a specified range.

## Examples

### Creating quantities with units:

>>> import unxt as u
>>> import jax
>>> import jax.numpy as jnp

>>> distance = u.Quantity(100, "m")
>>> distance
Quantity(Array(100, dtype=int32, ...), unit='m')

Create from arrays

>>> velocities = u.Quantity([10, 20, 30], "m/s")
>>> velocities
Quantity(Array([10, 20, 30], dtype=int32), unit='m / s')

Unit conversions and arithmetic:

Convert units

>>> distance_km = u.uconvert("km", distance)
>>> distance_km
Quantity(Array(0.1, dtype=float32, ...), unit='km')

Arithmetic preserves units.

>>> time = u.Q(5, "s")  # use Quantity alias
>>> velocity = distance / time
>>> velocity
Quantity(Array(20., dtype=float32, ...), unit='m / s')

Strip units for numerical operations

>>> u.ustrip("m", distance)
Array(100, dtype=int32, ...)

### Working with angles:

Create angle quantities

>>> theta = u.Angle(180, "deg")
>>> theta
Angle(Array(180, dtype=int32, ...), unit='deg')

Convert to radians

>>> theta_rad = u.uconvert("rad", theta)
>>> theta_rad
Angle(Array(3.1415927, dtype=float32, ...), unit='rad')

Wrap angles to a range

>>> angle = u.Angle(450, "deg")
>>> wrapped = u.quantity.wrap_to(angle, u.Angle(0, "deg"), u.Angle(360, "deg"))
>>> wrapped
Angle(Array(90, dtype=int32, ...), unit='deg')

### Advanced usage with JAX transformations:

Quantities work with JAX transformations

>>> def kinetic_energy(mass, velocity):
...     return 0.5 * mass * velocity**2

>>> mass = u.Q(2.0, "kg")
>>> vel = u.Q(10.0, "m/s")
>>> energy = kinetic_energy(mass, vel)
>>> energy
Quantity(Array(100., dtype=float32, ...), unit='m2 kg / s2')

Convert to standard energy units

>>> u.uconvert("J", energy)
Quantity(Array(100., dtype=float32, ...), unit='m2 kg / s2')

JIT compilation works seamlessly

>>> @jax.jit
... def compute_force(mass, accel):
...     return mass * accel
>>> force = compute_force(u.Q(5.0, "kg"), u.Q(9.8, "m/s^2"))
>>> force
Quantity(Array(49., dtype=float32, ...), unit='kg m / s2')
class unxt.quantity.Quantity(value: Any, unit: Any)#

Bases: Quantity

Arrays with associated units.

This class is parametrized by the dimensions of the units.

short_name#

Short name ‘Q’ used for compact wadler-lindig printing.

Type:

str

Examples

>>> import unxt as u

From an integer:

>>> u.Quantity(1, "m")
Quantity(Array(1, dtype=int32, ...), unit='m')

From a float:

>>> u.Q(1.0, "m")
Quantity(Array(1., dtype=float32, ...), unit='m')

From a list:

>>> u.Quantity([1, 2, 3], "m")
Quantity(Array([1, 2, 3], dtype=int32), unit='m')

From a tuple:

>>> u.Quantity((1, 2, 3), "m")
Quantity(Array([1, 2, 3], dtype=int32), unit='m')

From a numpy.ndarray:

>>> import numpy as np
>>> u.Quantity(np.array([1, 2, 3]), "m")
Quantity(Array([1, 2, 3], dtype=int32), unit='m')

From a jax.Array:

>>> import jax.numpy as jnp
>>> u.Quantity(jnp.array([1, 2, 3]), "m")
Quantity(Array([1, 2, 3], dtype=int32), unit='m')

The unit can also be given as a units object:

>>> u.Quantity(1, u.unit("m"))
Quantity(Array(1, dtype=int32, ...), unit='m')

In the previous examples, the dimension parameter was inferred from the values. It can also be given explicitly:

>>> u.Quantity["length"](1, "m")
Quantity(Array(1, dtype=int32, ...), unit='m')

This can be used for runtime checking of the input dimension!

>>> try:
...     u.Quantity["length"](1, "s")
... except Exception as e:
...     print(e)
Physical type mismatch.

The dimension can also be given as a dimension object:

>>> dims = u.dimension("length")
>>> dims
PhysicalType('length')
>>> u.Quantity[dims](1.0, "m")
Quantity(Array(1., dtype=float32, ...), unit='m')

Or as a unit:

>>> u.Quantity[u.unit("m")](1.0, "m")
Quantity(Array(1., dtype=float32, ...), unit='m')

Some tricky cases are when the physical type is unknown:

>>> unit = u.unit("m2 / (kg s2)")
>>> u.dimension_of(unit)
PhysicalType('unknown')

The dimension can be given as a string in all cases, but is necessary when the physical type is unknown:

>>> print(u.Quantity["m2 kg-1 s-2"](1.0, unit))  # to show the [dim]
Quantity['m2 kg-1 s-2'](1., unit='m2 / (kg s2)')
Parameters:
property T: AbstractQuantity#

Transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.T
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
argmax(*args: Any, **kwargs: Any)#

Return the indices of the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmax()
Array(2, dtype=int32)
Parameters:
Return type:

Array

argmin(*args: Any, **kwargs: Any)#

Return the indices of the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmin()
Array(0, dtype=int32)
Parameters:
Return type:

Array

astype(*args: Any, **kwargs: Any)#

Copy the array and cast to a specified dtype.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.dtype
dtype('int32')

>>> q.astype(float)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property at: _QuantityIndexUpdateHelper#

Helper property for index update functionality.

The at property provides a functionally pure equivalent of in-place array modifications.

In particular:

Alternate syntax

Equivalent In-place expression

x = x.at[idx].set(y)

x[idx] = y

x = x.at[idx].add(y)

x[idx] += y

x = x.at[idx].subtract(y)

x[idx] -= y

x = x.at[idx].multiply(y)

x[idx] *= y

x = x.at[idx].divide(y)

x[idx] /= y

x = x.at[idx].power(y)

x[idx] **= y

x = x.at[idx].min(y)

x[idx] = minimum(x[idx], y)

x = x.at[idx].max(y)

x[idx] = maximum(x[idx], y)

x = x.at[idx].apply(ufunc)

ufunc.at(x, idx)

x = x.at[idx].get()

x = x[idx]

None of the x.at expressions modify the original x; instead they return a modified copy of x. However, inside a jit() compiled function, expressions like x = x.at[idx].set(y) are guaranteed to be applied in-place.

Unlike NumPy in-place operations such as x[idx] += y, if multiple indices refer to the same location, all updates will be applied (NumPy would only apply the last update, rather than applying all updates.) The order in which conflicting updates are applied is implementation-defined and may be nondeterministic (e.g., due to concurrency on some hardware platforms).

By default, JAX assumes that all indices are in-bounds. Alternative out-of-bound index semantics can be specified via the mode parameter (see below).

Parameters:

  • mode –

    string specifying out-of-bound indexing mode. Options are:

    • "promise_in_bounds": (default) The user promises that indices are in bounds. No additional checking will be performed. In practice, this means that out-of-bounds indices in get() will be clipped, and out-of-bounds indices in set(), add(), etc. will be dropped.

    • "clip": clamp out of bounds indices into valid range.

    • "drop": ignore out-of-bound indices.

    • "fill": alias for "drop". For get(), the optional fill_value argument specifies the value that will be returned.

    See jax.lax.GatherScatterMode for more details.

  • wrap_negative_indices – If True (default) then negative indices indicate position from the end of the array, similar to Python and NumPy indexing. If False, then negative indices are considered out-of-bounds and behave according to the mode parameter.

  • fill_value – Only applies to the get() method: the fill value to return for out-of-bounds slices when mode is 'fill'. Ignored otherwise. Defaults to NaN for inexact types, the largest negative value for signed types, the largest positive value for unsigned types, and True for booleans.

  • indices_are_sorted – If True, the implementation will assume that the (normalized) indices passed to at[] are sorted in ascending order, which can lead to more efficient execution on some backends. If True but the indices are not actually sorted, the output is undefined.

  • unique_indices – If True, the implementation will assume that the (normalized) indices passed to at[] are unique, which can result in more efficient execution on some backends. If True but the indices are not actually unique, the output is undefined.

Examples

>>> x = jnp.arange(5.0)
>>> x
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[2].get()
Array(2., dtype=float32)
>>> x.at[2].add(10)
Array([ 0.,  1., 12.,  3.,  4.], dtype=float32)

By default, out-of-bound indices are ignored in updates, but this behavior can be controlled with the mode parameter:

>>> x.at[10].add(10)  # dropped
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[20].add(10, mode='clip')  # clipped
Array([ 0.,  1.,  2.,  3., 14.], dtype=float32)

For get(), out-of-bound indices are clipped by default:

>>> x.at[20].get()  # out-of-bounds indices clipped
Array(4., dtype=float32)
>>> x.at[20].get(mode='fill')  # out-of-bounds indices filled with NaN
Array(nan, dtype=float32)
>>> x.at[20].get(mode='fill', fill_value=-1)  # custom fill value
Array(-1., dtype=float32)

Negative indices count from the end of the array, but this behavior can be disabled by setting wrap_negative_indices = False:

>>> x.at[-1].set(99)
Array([ 0.,  1.,  2.,  3., 99.], dtype=float32)
>>> x.at[-1].set(99, wrap_negative_indices=False, mode='drop')  # dropped!
Array([0., 1., 2., 3., 4.], dtype=float32)
block_until_ready()#

Block until the array is ready.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.block_until_ready() is q
True
decompose(bases: Sequence[Unit | UnitBase | CompositeUnit | str], /)#

Decompose the quantity into the given bases.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.decompose(["cm", "s"])
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

bases (Sequence[Unit | UnitBase | CompositeUnit | str])

Return type:

AbstractQuantity

property device: Device#

Device where the array is located.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").device
CpuDevice(id=0)
devices()#

Return the devices where the array is located.

Return type:

set[Device]

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.devices()
{CpuDevice(id=0)}
property dtype: dtype#

Data type of the array.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").dtype
dtype('int32')
flatten()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.flatten()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
classmethod from_(cls: type[AbstractQuantity], *args: Any, **kwargs: Any)#
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a unxt.Quantity from an array-like value and a unit.

Parameters:

  • value – The array-like value.

  • unit – The unit of the value.

  • dtype – The data type of the array (keyword-only).

  • args (Any)

  • kwargs (Any)

Return type:

AbstractQuantity

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> u.Quantity.from_(x, "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_([1.0, 2, 3], "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_((1.0, 2, 3), "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], /, *, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Make a unxt.AbstractQuantity from an array-like value and a unit kwarg.

Examples

For this example we’ll use the unxt.Quantity class. The same applies to any subclass of unxt.AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_([1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], *, value: Any, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a AbstractQuantity from value and unit kwargs.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_(value=[1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], mapping: Mapping[str, Any]) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from a Mapping.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> q = u.Quantity.from_({"value": x, "unit": "m"})
>>> q
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_({"value": q, "unit": "km"})
Quantity(Array([0.001, 0.002, 0.003], dtype=float32), unit='km')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, "cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: NoneType, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, None)
Quantity(Array(1, dtype=int32, ...), unit='m')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, /, *, unit: Any | None = None, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity, with no unit change.

from_(cls: type[AbstractQuantity], value: Quantity, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"))
Quantity(Array(1., dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: Quantity, u: Any, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"), "cm")
Quantity(Array(100., dtype=float32), unit='cm')
Parameters:
Return type:

AbstractQuantity

property mT: AbstractQuantity#

Matrix transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.mT
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
max(*args: Any, **kwargs: Any)#

Return the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.max()
Quantity(Array(3, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

mean(*args: Any, **kwargs: Any)#

Return the mean value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.mean()
Quantity(Array(2., dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

min(*args: Any, **kwargs: Any)#

Return the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.min()
Quantity(Array(1, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

property ndim: int#

Number of dimensions.

Examples

>>> import unxt as u
>>> q = u.Quantity([[1]], "m")
>>> q.ndim
2
ravel()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.ravel()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
reshape(*args: Any, order: str = 'C')#

Return a reshaped version of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3, 4], "m")
>>> q.reshape(2, 2)
Quantity(Array([[1, 2],
                          [3, 4]], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

round(*args: Any, **kwargs: Any)#

Round the array to the given number of decimals.

Examples

>>> import unxt as u
>>> q = u.Quantity([1.1, 2.2, 3.3], "m")
>>> q.round(0)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property shape: tuple[int, ...]#

Shape of the array.

property sharding: Any#

Return the sharding configuration of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.sharding
SingleDeviceSharding(device=..., memory_kind=...)
short_name: ClassVar[str] = 'Q'#

Short name for compact printing.

property size: int#

Total number of elements.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.size
3
squeeze(*args: Any, **kwargs: Any)#

Return the array with all single-dimensional entries removed.

Examples

>>> import unxt as u
>>> q = u.Quantity([[[1], [2], [3]]], "m")
>>> q.squeeze()
Quantity(Array([1, 2, 3], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

to(u: Any, /)#

Convert the quantity to the given units.

See unxt.quantity.AbstractQuantity.uconvert.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

to_device(device: None | Device = None)#

Move the array to a new device.

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.to_device(None)
Quantity(Array(1, dtype=int32, weak_type=True), unit='m')
Parameters:

device (None | Device)

Return type:

AbstractQuantity

to_value(u: Any, /)#

Return the value in the given units.

See unxt.AbstractQuantity.ustrip.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to_value("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Union[Array, ndarray, bool, number, bool, int, float, complex, ArrayLike]

uconvert(u: Any, /)#

Convert the quantity to the given units.

See also

None

convert a quantity to a new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.uconvert("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

ustrip(u: Any, /)#

Return the value in the given units.

See also

None

strip the units from a quantity.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.ustrip("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Array

value: Shaped[Array, '*shape'] | StaticValue#

The value of the AbstractQuantity.

unit: AbstractUnit#

The unit associated with this value.

unxt.quantity.Q#

alias of Quantity

class unxt.quantity.StaticQuantity(value: Any, unit: Any)#

Bases: StaticQuantity

Static quantities with associated units.

This class is parametrized by the dimensions of the units, just like {class}`~unxt.quantity.Quantity`, but its value is always stored as a static NumPy array. It accepts Python scalars and array-like inputs that can be converted to NumPy arrays, and it rejects JAX arrays.

Examples

>>> import numpy as np
>>> import unxt as u

Basic construction:

>>> q = u.StaticQuantity(np.array([1.0, 2.0]), "m")
>>> q
StaticQuantity(array([1., 2.]), unit='m')

Values are static and hashable:

>>> isinstance(hash(q), int)
True

JAX arrays are rejected:

>>> import jax.numpy as jnp
>>> try:
...     u.StaticQuantity(jnp.array([1.0, 2.0]), "m")
... except TypeError as e:
...     print(e)
StaticQuantity does not accept JAX arrays. Use Quantity for traced values.

The Wadler-Lindig representation hides the internal static wrapper:

>>> import wadler_lindig as wl
>>> wl.pprint(q, short_arrays=False)
StaticQuantity(array([1., 2.]), unit='m')
Parameters:
property T: AbstractQuantity#

Transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.T
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
argmax(*args: Any, **kwargs: Any)#

Return the indices of the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmax()
Array(2, dtype=int32)
Parameters:
Return type:

Array

argmin(*args: Any, **kwargs: Any)#

Return the indices of the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmin()
Array(0, dtype=int32)
Parameters:
Return type:

Array

astype(*args: Any, **kwargs: Any)#

Copy the array and cast to a specified dtype.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.dtype
dtype('int32')

>>> q.astype(float)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property at: _QuantityIndexUpdateHelper#

Helper property for index update functionality.

The at property provides a functionally pure equivalent of in-place array modifications.

In particular:

Alternate syntax

Equivalent In-place expression

x = x.at[idx].set(y)

x[idx] = y

x = x.at[idx].add(y)

x[idx] += y

x = x.at[idx].subtract(y)

x[idx] -= y

x = x.at[idx].multiply(y)

x[idx] *= y

x = x.at[idx].divide(y)

x[idx] /= y

x = x.at[idx].power(y)

x[idx] **= y

x = x.at[idx].min(y)

x[idx] = minimum(x[idx], y)

x = x.at[idx].max(y)

x[idx] = maximum(x[idx], y)

x = x.at[idx].apply(ufunc)

ufunc.at(x, idx)

x = x.at[idx].get()

x = x[idx]

None of the x.at expressions modify the original x; instead they return a modified copy of x. However, inside a jit() compiled function, expressions like x = x.at[idx].set(y) are guaranteed to be applied in-place.

Unlike NumPy in-place operations such as x[idx] += y, if multiple indices refer to the same location, all updates will be applied (NumPy would only apply the last update, rather than applying all updates.) The order in which conflicting updates are applied is implementation-defined and may be nondeterministic (e.g., due to concurrency on some hardware platforms).

By default, JAX assumes that all indices are in-bounds. Alternative out-of-bound index semantics can be specified via the mode parameter (see below).

Parameters:

  • mode –

    string specifying out-of-bound indexing mode. Options are:

    • "promise_in_bounds": (default) The user promises that indices are in bounds. No additional checking will be performed. In practice, this means that out-of-bounds indices in get() will be clipped, and out-of-bounds indices in set(), add(), etc. will be dropped.

    • "clip": clamp out of bounds indices into valid range.

    • "drop": ignore out-of-bound indices.

    • "fill": alias for "drop". For get(), the optional fill_value argument specifies the value that will be returned.

    See jax.lax.GatherScatterMode for more details.

  • wrap_negative_indices – If True (default) then negative indices indicate position from the end of the array, similar to Python and NumPy indexing. If False, then negative indices are considered out-of-bounds and behave according to the mode parameter.

  • fill_value – Only applies to the get() method: the fill value to return for out-of-bounds slices when mode is 'fill'. Ignored otherwise. Defaults to NaN for inexact types, the largest negative value for signed types, the largest positive value for unsigned types, and True for booleans.

  • indices_are_sorted – If True, the implementation will assume that the (normalized) indices passed to at[] are sorted in ascending order, which can lead to more efficient execution on some backends. If True but the indices are not actually sorted, the output is undefined.

  • unique_indices – If True, the implementation will assume that the (normalized) indices passed to at[] are unique, which can result in more efficient execution on some backends. If True but the indices are not actually unique, the output is undefined.

Examples

>>> x = jnp.arange(5.0)
>>> x
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[2].get()
Array(2., dtype=float32)
>>> x.at[2].add(10)
Array([ 0.,  1., 12.,  3.,  4.], dtype=float32)

By default, out-of-bound indices are ignored in updates, but this behavior can be controlled with the mode parameter:

>>> x.at[10].add(10)  # dropped
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[20].add(10, mode='clip')  # clipped
Array([ 0.,  1.,  2.,  3., 14.], dtype=float32)

For get(), out-of-bound indices are clipped by default:

>>> x.at[20].get()  # out-of-bounds indices clipped
Array(4., dtype=float32)
>>> x.at[20].get(mode='fill')  # out-of-bounds indices filled with NaN
Array(nan, dtype=float32)
>>> x.at[20].get(mode='fill', fill_value=-1)  # custom fill value
Array(-1., dtype=float32)

Negative indices count from the end of the array, but this behavior can be disabled by setting wrap_negative_indices = False:

>>> x.at[-1].set(99)
Array([ 0.,  1.,  2.,  3., 99.], dtype=float32)
>>> x.at[-1].set(99, wrap_negative_indices=False, mode='drop')  # dropped!
Array([0., 1., 2., 3., 4.], dtype=float32)
block_until_ready()#

Block until the array is ready.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.block_until_ready() is q
True
decompose(bases: Sequence[Unit | UnitBase | CompositeUnit | str], /)#

Decompose the quantity into the given bases.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.decompose(["cm", "s"])
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

bases (Sequence[Unit | UnitBase | CompositeUnit | str])

Return type:

AbstractQuantity

property device: Device#

Device where the array is located.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").device
CpuDevice(id=0)
devices()#

Return the devices where the array is located.

Return type:

set[Device]

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.devices()
{CpuDevice(id=0)}
property dtype: dtype#

Data type of the array.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").dtype
dtype('int32')
flatten()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.flatten()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
classmethod from_(cls: type[AbstractQuantity], *args: Any, **kwargs: Any)#
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a unxt.Quantity from an array-like value and a unit.

Parameters:

  • value – The array-like value.

  • unit – The unit of the value.

  • dtype – The data type of the array (keyword-only).

  • args (Any)

  • kwargs (Any)

Return type:

AbstractQuantity

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> u.Quantity.from_(x, "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_([1.0, 2, 3], "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_((1.0, 2, 3), "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], /, *, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Make a unxt.AbstractQuantity from an array-like value and a unit kwarg.

Examples

For this example we’ll use the unxt.Quantity class. The same applies to any subclass of unxt.AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_([1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], *, value: Any, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a AbstractQuantity from value and unit kwargs.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_(value=[1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], mapping: Mapping[str, Any]) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from a Mapping.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> q = u.Quantity.from_({"value": x, "unit": "m"})
>>> q
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_({"value": q, "unit": "km"})
Quantity(Array([0.001, 0.002, 0.003], dtype=float32), unit='km')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, "cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: NoneType, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, None)
Quantity(Array(1, dtype=int32, ...), unit='m')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, /, *, unit: Any | None = None, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity, with no unit change.

from_(cls: type[AbstractQuantity], value: Quantity, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"))
Quantity(Array(1., dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: Quantity, u: Any, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"), "cm")
Quantity(Array(100., dtype=float32), unit='cm')
Parameters:
Return type:

AbstractQuantity

property mT: AbstractQuantity#

Matrix transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.mT
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
max(*args: Any, **kwargs: Any)#

Return the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.max()
Quantity(Array(3, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

mean(*args: Any, **kwargs: Any)#

Return the mean value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.mean()
Quantity(Array(2., dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

min(*args: Any, **kwargs: Any)#

Return the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.min()
Quantity(Array(1, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

property ndim: int#

Number of dimensions.

Examples

>>> import unxt as u
>>> q = u.Quantity([[1]], "m")
>>> q.ndim
2
ravel()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.ravel()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
reshape(*args: Any, order: str = 'C')#

Return a reshaped version of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3, 4], "m")
>>> q.reshape(2, 2)
Quantity(Array([[1, 2],
                          [3, 4]], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

round(*args: Any, **kwargs: Any)#

Round the array to the given number of decimals.

Examples

>>> import unxt as u
>>> q = u.Quantity([1.1, 2.2, 3.3], "m")
>>> q.round(0)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property shape: tuple[int, ...]#

Shape of the array.

property sharding: Any#

Return the sharding configuration of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.sharding
SingleDeviceSharding(device=..., memory_kind=...)
property size: int#

Total number of elements.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.size
3
squeeze(*args: Any, **kwargs: Any)#

Return the array with all single-dimensional entries removed.

Examples

>>> import unxt as u
>>> q = u.Quantity([[[1], [2], [3]]], "m")
>>> q.squeeze()
Quantity(Array([1, 2, 3], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

to(u: Any, /)#

Convert the quantity to the given units.

See unxt.quantity.AbstractQuantity.uconvert.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

to_device(device: None | Device = None)#

Move the array to a new device.

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.to_device(None)
Quantity(Array(1, dtype=int32, weak_type=True), unit='m')
Parameters:

device (None | Device)

Return type:

AbstractQuantity

to_value(u: Any, /)#

Return the value in the given units.

See unxt.AbstractQuantity.ustrip.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to_value("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Union[Array, ndarray, bool, number, bool, int, float, complex, ArrayLike]

uconvert(u: Any, /)#

Convert the quantity to the given units.

See also

None

convert a quantity to a new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.uconvert("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

ustrip(u: Any, /)#

Return the value in the given units.

See also

None

strip the units from a quantity.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.ustrip("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Array

value: StaticValue#

The static value of the AbstractQuantity.

unit: AbstractUnit#

The unit associated with this value.

class unxt.quantity.StaticValue(array: ndarray, /)#

Bases: object

Immutable static value wrapper for StaticQuantity.

This stores a read-only NumPy array and is used to keep the value static while avoiding Equinox’s static-array warnings. Arithmetic operations degrade to the wrapped array unless both operands are StaticValue, in which case a StaticValue is returned.

Note that since the array is immutable, hashing is supported. The hash is computed from the array’s dtype, shape, and bytes.

Parameters:

array (ndarray)

property array: ndarray#

Return the contained NumPy array.

classmethod from_(cls: type[StaticValue], *args: Any, **kwargs: Any)#

Create a StaticValue from given arguments.

from_(cls: type[StaticValue], value: object, /) → StaticValue
Parameters:
Return type:

StaticValue

Convert a value for StaticQuantity.

from_(cls: type[StaticValue], value: StaticValue, /) → StaticValue
Parameters:
Return type:

StaticValue

Convert a value for StaticQuantity.

from_(cls: type[StaticValue], value: Array | jax._src.core.Tracer, /) → StaticValue
Parameters:
Return type:

StaticValue

Reject JAX arrays for StaticQuantity.

from_(cls: StaticValue, value: AbstractQuantity, /) → StaticValue
Parameters:
Return type:

StaticValue

Disallow conversion of AbstractQuantity to a value.

Parameters:
Return type:

StaticValue

class unxt.quantity.AbstractQuantity#

Bases: AstropyQuantityCompatMixin, NumPyCompatMixin, IPythonReprMixin, ArrayValue, NumpyBinaryOpsMixin[Any, AbstractQuantity], NumpyComparisonMixin[Any, Bool[Array, '*shape']], NumpyUnaryMixin[AbstractQuantity], NumpyRoundMixin[AbstractQuantity], NumpyTruncMixin[AbstractQuantity], NumpyFloorMixin[AbstractQuantity], NumpyCeilMixin[AbstractQuantity], LaxLenMixin, LaxLengthHintMixin

Represents a Quantity with a unit.

short_name#

Optional short name for the class used in wadler-lindig printing when use_short_name=True. Defaults to None.

Type:

str | None

Examples

>>> import unxt as u

From an integer:

>>> u.Quantity(1, "m")
Quantity(Array(1, dtype=int32, ...), unit='m')

From a float:

>>> u.Quantity(1.0, "m")
Quantity(Array(1., dtype=float32, ...), unit='m')

From a list:

>>> u.Quantity([1, 2, 3], "m")
Quantity(Array([1, 2, 3], dtype=int32), unit='m')

From a tuple:

>>> u.Quantity((1, 2, 3), "m")
Quantity(Array([1, 2, 3], dtype=int32), unit='m')

From a numpy.ndarray:

>>> import numpy as np
>>> u.Quantity(np.array([1, 2, 3]), "m")
Quantity(Array([1, 2, 3], dtype=int32), unit='m')

From a jax.Array:

>>> import jax.numpy as jnp
>>> u.Quantity(jnp.array([1, 2, 3]), "m")
Quantity(Array([1, 2, 3], dtype=int32), unit='m')

The unit can also be given as a astropy.units.Unit:

>>> import astropy.units as apyu
>>> u.Quantity(1, apyu.m)
Quantity(Array(1, dtype=int32, ...), unit='m')
property T: AbstractQuantity#

Transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.T
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
argmax(*args: Any, **kwargs: Any)#

Return the indices of the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmax()
Array(2, dtype=int32)
Parameters:
Return type:

Array

argmin(*args: Any, **kwargs: Any)#

Return the indices of the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmin()
Array(0, dtype=int32)
Parameters:
Return type:

Array

astype(*args: Any, **kwargs: Any)#

Copy the array and cast to a specified dtype.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.dtype
dtype('int32')

>>> q.astype(float)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property at: _QuantityIndexUpdateHelper#

Helper property for index update functionality.

The at property provides a functionally pure equivalent of in-place array modifications.

In particular:

Alternate syntax

Equivalent In-place expression

x = x.at[idx].set(y)

x[idx] = y

x = x.at[idx].add(y)

x[idx] += y

x = x.at[idx].subtract(y)

x[idx] -= y

x = x.at[idx].multiply(y)

x[idx] *= y

x = x.at[idx].divide(y)

x[idx] /= y

x = x.at[idx].power(y)

x[idx] **= y

x = x.at[idx].min(y)

x[idx] = minimum(x[idx], y)

x = x.at[idx].max(y)

x[idx] = maximum(x[idx], y)

x = x.at[idx].apply(ufunc)

ufunc.at(x, idx)

x = x.at[idx].get()

x = x[idx]

None of the x.at expressions modify the original x; instead they return a modified copy of x. However, inside a jit() compiled function, expressions like x = x.at[idx].set(y) are guaranteed to be applied in-place.

Unlike NumPy in-place operations such as x[idx] += y, if multiple indices refer to the same location, all updates will be applied (NumPy would only apply the last update, rather than applying all updates.) The order in which conflicting updates are applied is implementation-defined and may be nondeterministic (e.g., due to concurrency on some hardware platforms).

By default, JAX assumes that all indices are in-bounds. Alternative out-of-bound index semantics can be specified via the mode parameter (see below).

Parameters:

  • mode –

    string specifying out-of-bound indexing mode. Options are:

    • "promise_in_bounds": (default) The user promises that indices are in bounds. No additional checking will be performed. In practice, this means that out-of-bounds indices in get() will be clipped, and out-of-bounds indices in set(), add(), etc. will be dropped.

    • "clip": clamp out of bounds indices into valid range.

    • "drop": ignore out-of-bound indices.

    • "fill": alias for "drop". For get(), the optional fill_value argument specifies the value that will be returned.

    See jax.lax.GatherScatterMode for more details.

  • wrap_negative_indices – If True (default) then negative indices indicate position from the end of the array, similar to Python and NumPy indexing. If False, then negative indices are considered out-of-bounds and behave according to the mode parameter.

  • fill_value – Only applies to the get() method: the fill value to return for out-of-bounds slices when mode is 'fill'. Ignored otherwise. Defaults to NaN for inexact types, the largest negative value for signed types, the largest positive value for unsigned types, and True for booleans.

  • indices_are_sorted – If True, the implementation will assume that the (normalized) indices passed to at[] are sorted in ascending order, which can lead to more efficient execution on some backends. If True but the indices are not actually sorted, the output is undefined.

  • unique_indices – If True, the implementation will assume that the (normalized) indices passed to at[] are unique, which can result in more efficient execution on some backends. If True but the indices are not actually unique, the output is undefined.

Examples

>>> x = jnp.arange(5.0)
>>> x
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[2].get()
Array(2., dtype=float32)
>>> x.at[2].add(10)
Array([ 0.,  1., 12.,  3.,  4.], dtype=float32)

By default, out-of-bound indices are ignored in updates, but this behavior can be controlled with the mode parameter:

>>> x.at[10].add(10)  # dropped
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[20].add(10, mode='clip')  # clipped
Array([ 0.,  1.,  2.,  3., 14.], dtype=float32)

For get(), out-of-bound indices are clipped by default:

>>> x.at[20].get()  # out-of-bounds indices clipped
Array(4., dtype=float32)
>>> x.at[20].get(mode='fill')  # out-of-bounds indices filled with NaN
Array(nan, dtype=float32)
>>> x.at[20].get(mode='fill', fill_value=-1)  # custom fill value
Array(-1., dtype=float32)

Negative indices count from the end of the array, but this behavior can be disabled by setting wrap_negative_indices = False:

>>> x.at[-1].set(99)
Array([ 0.,  1.,  2.,  3., 99.], dtype=float32)
>>> x.at[-1].set(99, wrap_negative_indices=False, mode='drop')  # dropped!
Array([0., 1., 2., 3., 4.], dtype=float32)
block_until_ready()#

Block until the array is ready.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.block_until_ready() is q
True
decompose(bases: Sequence[Unit | UnitBase | CompositeUnit | str], /)#

Decompose the quantity into the given bases.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.decompose(["cm", "s"])
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

bases (Sequence[Unit | UnitBase | CompositeUnit | str])

Return type:

AbstractQuantity

property device: Device#

Device where the array is located.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").device
CpuDevice(id=0)
devices()#

Return the devices where the array is located.

Return type:

set[Device]

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.devices()
{CpuDevice(id=0)}
property dtype: dtype#

Data type of the array.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").dtype
dtype('int32')
flatten()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.flatten()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
classmethod from_(cls: type[AbstractQuantity], *args: Any, **kwargs: Any)#
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a unxt.Quantity from an array-like value and a unit.

Parameters:

  • value – The array-like value.

  • unit – The unit of the value.

  • dtype – The data type of the array (keyword-only).

  • args (Any)

  • kwargs (Any)

Return type:

AbstractQuantity

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> u.Quantity.from_(x, "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_([1.0, 2, 3], "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_((1.0, 2, 3), "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], /, *, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Make a unxt.AbstractQuantity from an array-like value and a unit kwarg.

Examples

For this example we’ll use the unxt.Quantity class. The same applies to any subclass of unxt.AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_([1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], *, value: Any, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a AbstractQuantity from value and unit kwargs.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_(value=[1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], mapping: Mapping[str, Any]) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from a Mapping.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> q = u.Quantity.from_({"value": x, "unit": "m"})
>>> q
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_({"value": q, "unit": "km"})
Quantity(Array([0.001, 0.002, 0.003], dtype=float32), unit='km')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, "cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: NoneType, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, None)
Quantity(Array(1, dtype=int32, ...), unit='m')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, /, *, unit: Any | None = None, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity, with no unit change.

from_(cls: type[AbstractQuantity], value: Quantity, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"))
Quantity(Array(1., dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: Quantity, u: Any, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"), "cm")
Quantity(Array(100., dtype=float32), unit='cm')
Parameters:
Return type:

AbstractQuantity

property mT: AbstractQuantity#

Matrix transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.mT
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
max(*args: Any, **kwargs: Any)#

Return the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.max()
Quantity(Array(3, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

mean(*args: Any, **kwargs: Any)#

Return the mean value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.mean()
Quantity(Array(2., dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

min(*args: Any, **kwargs: Any)#

Return the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.min()
Quantity(Array(1, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

property ndim: int#

Number of dimensions.

Examples

>>> import unxt as u
>>> q = u.Quantity([[1]], "m")
>>> q.ndim
2
ravel()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.ravel()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
reshape(*args: Any, order: str = 'C')#

Return a reshaped version of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3, 4], "m")
>>> q.reshape(2, 2)
Quantity(Array([[1, 2],
                          [3, 4]], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

round(*args: Any, **kwargs: Any)#

Round the array to the given number of decimals.

Examples

>>> import unxt as u
>>> q = u.Quantity([1.1, 2.2, 3.3], "m")
>>> q.round(0)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property shape: tuple[int, ...]#

Shape of the array.

property sharding: Any#

Return the sharding configuration of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.sharding
SingleDeviceSharding(device=..., memory_kind=...)
property size: int#

Total number of elements.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.size
3
squeeze(*args: Any, **kwargs: Any)#

Return the array with all single-dimensional entries removed.

Examples

>>> import unxt as u
>>> q = u.Quantity([[[1], [2], [3]]], "m")
>>> q.squeeze()
Quantity(Array([1, 2, 3], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

to(u: Any, /)#

Convert the quantity to the given units.

See unxt.quantity.AbstractQuantity.uconvert.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

to_device(device: None | Device = None)#

Move the array to a new device.

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.to_device(None)
Quantity(Array(1, dtype=int32, weak_type=True), unit='m')
Parameters:

device (None | Device)

Return type:

AbstractQuantity

to_value(u: Any, /)#

Return the value in the given units.

See unxt.AbstractQuantity.ustrip.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to_value("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Union[Array, ndarray, bool, number, bool, int, float, complex, ArrayLike]

uconvert(u: Any, /)#

Convert the quantity to the given units.

See also

None

convert a quantity to a new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.uconvert("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

ustrip(u: Any, /)#

Return the value in the given units.

See also

None

strip the units from a quantity.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.ustrip("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Array

value: AbstractVar[Union[Shaped[Array, '*shape'], Shaped[StaticValue, '*shape']]]#

The value of the AbstractQuantity.

unit: AbstractVar[Unit | UnitBase | CompositeUnit]#

The unit associated with this value.

class unxt.quantity.BareQuantity(value: Any, unit: Any)#

Bases: AbstractQuantity

A fast implementation of the Quantity class.

This class is not parametrized by its dimensionality.

Parameters:
property T: AbstractQuantity#

Transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.T
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
argmax(*args: Any, **kwargs: Any)#

Return the indices of the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmax()
Array(2, dtype=int32)
Parameters:
Return type:

Array

argmin(*args: Any, **kwargs: Any)#

Return the indices of the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmin()
Array(0, dtype=int32)
Parameters:
Return type:

Array

astype(*args: Any, **kwargs: Any)#

Copy the array and cast to a specified dtype.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.dtype
dtype('int32')

>>> q.astype(float)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property at: _QuantityIndexUpdateHelper#

Helper property for index update functionality.

The at property provides a functionally pure equivalent of in-place array modifications.

In particular:

Alternate syntax

Equivalent In-place expression

x = x.at[idx].set(y)

x[idx] = y

x = x.at[idx].add(y)

x[idx] += y

x = x.at[idx].subtract(y)

x[idx] -= y

x = x.at[idx].multiply(y)

x[idx] *= y

x = x.at[idx].divide(y)

x[idx] /= y

x = x.at[idx].power(y)

x[idx] **= y

x = x.at[idx].min(y)

x[idx] = minimum(x[idx], y)

x = x.at[idx].max(y)

x[idx] = maximum(x[idx], y)

x = x.at[idx].apply(ufunc)

ufunc.at(x, idx)

x = x.at[idx].get()

x = x[idx]

None of the x.at expressions modify the original x; instead they return a modified copy of x. However, inside a jit() compiled function, expressions like x = x.at[idx].set(y) are guaranteed to be applied in-place.

Unlike NumPy in-place operations such as x[idx] += y, if multiple indices refer to the same location, all updates will be applied (NumPy would only apply the last update, rather than applying all updates.) The order in which conflicting updates are applied is implementation-defined and may be nondeterministic (e.g., due to concurrency on some hardware platforms).

By default, JAX assumes that all indices are in-bounds. Alternative out-of-bound index semantics can be specified via the mode parameter (see below).

Parameters:

  • mode –

    string specifying out-of-bound indexing mode. Options are:

    • "promise_in_bounds": (default) The user promises that indices are in bounds. No additional checking will be performed. In practice, this means that out-of-bounds indices in get() will be clipped, and out-of-bounds indices in set(), add(), etc. will be dropped.

    • "clip": clamp out of bounds indices into valid range.

    • "drop": ignore out-of-bound indices.

    • "fill": alias for "drop". For get(), the optional fill_value argument specifies the value that will be returned.

    See jax.lax.GatherScatterMode for more details.

  • wrap_negative_indices – If True (default) then negative indices indicate position from the end of the array, similar to Python and NumPy indexing. If False, then negative indices are considered out-of-bounds and behave according to the mode parameter.

  • fill_value – Only applies to the get() method: the fill value to return for out-of-bounds slices when mode is 'fill'. Ignored otherwise. Defaults to NaN for inexact types, the largest negative value for signed types, the largest positive value for unsigned types, and True for booleans.

  • indices_are_sorted – If True, the implementation will assume that the (normalized) indices passed to at[] are sorted in ascending order, which can lead to more efficient execution on some backends. If True but the indices are not actually sorted, the output is undefined.

  • unique_indices – If True, the implementation will assume that the (normalized) indices passed to at[] are unique, which can result in more efficient execution on some backends. If True but the indices are not actually unique, the output is undefined.

Examples

>>> x = jnp.arange(5.0)
>>> x
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[2].get()
Array(2., dtype=float32)
>>> x.at[2].add(10)
Array([ 0.,  1., 12.,  3.,  4.], dtype=float32)

By default, out-of-bound indices are ignored in updates, but this behavior can be controlled with the mode parameter:

>>> x.at[10].add(10)  # dropped
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[20].add(10, mode='clip')  # clipped
Array([ 0.,  1.,  2.,  3., 14.], dtype=float32)

For get(), out-of-bound indices are clipped by default:

>>> x.at[20].get()  # out-of-bounds indices clipped
Array(4., dtype=float32)
>>> x.at[20].get(mode='fill')  # out-of-bounds indices filled with NaN
Array(nan, dtype=float32)
>>> x.at[20].get(mode='fill', fill_value=-1)  # custom fill value
Array(-1., dtype=float32)

Negative indices count from the end of the array, but this behavior can be disabled by setting wrap_negative_indices = False:

>>> x.at[-1].set(99)
Array([ 0.,  1.,  2.,  3., 99.], dtype=float32)
>>> x.at[-1].set(99, wrap_negative_indices=False, mode='drop')  # dropped!
Array([0., 1., 2., 3., 4.], dtype=float32)
block_until_ready()#

Block until the array is ready.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.block_until_ready() is q
True
decompose(bases: Sequence[Unit | UnitBase | CompositeUnit | str], /)#

Decompose the quantity into the given bases.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.decompose(["cm", "s"])
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

bases (Sequence[Unit | UnitBase | CompositeUnit | str])

Return type:

AbstractQuantity

property device: Device#

Device where the array is located.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").device
CpuDevice(id=0)
devices()#

Return the devices where the array is located.

Return type:

set[Device]

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.devices()
{CpuDevice(id=0)}
property dtype: dtype#

Data type of the array.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").dtype
dtype('int32')
flatten()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.flatten()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
classmethod from_(cls: type[AbstractQuantity], *args: Any, **kwargs: Any)#
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a unxt.Quantity from an array-like value and a unit.

Parameters:

  • value – The array-like value.

  • unit – The unit of the value.

  • dtype – The data type of the array (keyword-only).

  • args (Any)

  • kwargs (Any)

Return type:

AbstractQuantity

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> u.Quantity.from_(x, "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_([1.0, 2, 3], "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_((1.0, 2, 3), "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], /, *, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Make a unxt.AbstractQuantity from an array-like value and a unit kwarg.

Examples

For this example we’ll use the unxt.Quantity class. The same applies to any subclass of unxt.AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_([1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], *, value: Any, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a AbstractQuantity from value and unit kwargs.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_(value=[1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], mapping: Mapping[str, Any]) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from a Mapping.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> q = u.Quantity.from_({"value": x, "unit": "m"})
>>> q
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_({"value": q, "unit": "km"})
Quantity(Array([0.001, 0.002, 0.003], dtype=float32), unit='km')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, "cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: NoneType, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, None)
Quantity(Array(1, dtype=int32, ...), unit='m')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, /, *, unit: Any | None = None, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity, with no unit change.

from_(cls: type[AbstractQuantity], value: Quantity, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"))
Quantity(Array(1., dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: Quantity, u: Any, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"), "cm")
Quantity(Array(100., dtype=float32), unit='cm')
Parameters:
Return type:

AbstractQuantity

property mT: AbstractQuantity#

Matrix transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.mT
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
max(*args: Any, **kwargs: Any)#

Return the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.max()
Quantity(Array(3, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

mean(*args: Any, **kwargs: Any)#

Return the mean value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.mean()
Quantity(Array(2., dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

min(*args: Any, **kwargs: Any)#

Return the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.min()
Quantity(Array(1, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

property ndim: int#

Number of dimensions.

Examples

>>> import unxt as u
>>> q = u.Quantity([[1]], "m")
>>> q.ndim
2
ravel()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.ravel()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
reshape(*args: Any, order: str = 'C')#

Return a reshaped version of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3, 4], "m")
>>> q.reshape(2, 2)
Quantity(Array([[1, 2],
                          [3, 4]], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

round(*args: Any, **kwargs: Any)#

Round the array to the given number of decimals.

Examples

>>> import unxt as u
>>> q = u.Quantity([1.1, 2.2, 3.3], "m")
>>> q.round(0)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property shape: tuple[int, ...]#

Shape of the array.

property sharding: Any#

Return the sharding configuration of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.sharding
SingleDeviceSharding(device=..., memory_kind=...)
property size: int#

Total number of elements.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.size
3
squeeze(*args: Any, **kwargs: Any)#

Return the array with all single-dimensional entries removed.

Examples

>>> import unxt as u
>>> q = u.Quantity([[[1], [2], [3]]], "m")
>>> q.squeeze()
Quantity(Array([1, 2, 3], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

to(u: Any, /)#

Convert the quantity to the given units.

See unxt.quantity.AbstractQuantity.uconvert.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

to_device(device: None | Device = None)#

Move the array to a new device.

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.to_device(None)
Quantity(Array(1, dtype=int32, weak_type=True), unit='m')
Parameters:

device (None | Device)

Return type:

AbstractQuantity

to_value(u: Any, /)#

Return the value in the given units.

See unxt.AbstractQuantity.ustrip.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to_value("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Union[Array, ndarray, bool, number, bool, int, float, complex, ArrayLike]

uconvert(u: Any, /)#

Convert the quantity to the given units.

See also

None

convert a quantity to a new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.uconvert("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

ustrip(u: Any, /)#

Return the value in the given units.

See also

None

strip the units from a quantity.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.ustrip("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Array

value: Union[Shaped[Array, '*shape'], Shaped[StaticValue, '*shape']]#

The value of the AbstractQuantity.

unit: Unit | UnitBase | CompositeUnit#

The unit associated with this value.

class unxt.quantity.AbstractAngle#

Bases: AbstractQuantity

Angular Quantity.

See also

None

a concrete implementation of this class.

Examples

For this example, we will use the concrete implementation of unxt.AbstractAngle, unxt.Angle.

>>> from unxt import Angle

>>> Angle(90, "deg")
Angle(Array(90, dtype=int32, ...), unit='deg')

Angles have to have dimensions of angle.

>>> try:
...     Angle(90, "m")
... except ValueError as e:
...     print(e)
Angle must have units with angular dimensions.
property T: AbstractQuantity#

Transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.T
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
argmax(*args: Any, **kwargs: Any)#

Return the indices of the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmax()
Array(2, dtype=int32)
Parameters:
Return type:

Array

argmin(*args: Any, **kwargs: Any)#

Return the indices of the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmin()
Array(0, dtype=int32)
Parameters:
Return type:

Array

astype(*args: Any, **kwargs: Any)#

Copy the array and cast to a specified dtype.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.dtype
dtype('int32')

>>> q.astype(float)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property at: _QuantityIndexUpdateHelper#

Helper property for index update functionality.

The at property provides a functionally pure equivalent of in-place array modifications.

In particular:

Alternate syntax

Equivalent In-place expression

x = x.at[idx].set(y)

x[idx] = y

x = x.at[idx].add(y)

x[idx] += y

x = x.at[idx].subtract(y)

x[idx] -= y

x = x.at[idx].multiply(y)

x[idx] *= y

x = x.at[idx].divide(y)

x[idx] /= y

x = x.at[idx].power(y)

x[idx] **= y

x = x.at[idx].min(y)

x[idx] = minimum(x[idx], y)

x = x.at[idx].max(y)

x[idx] = maximum(x[idx], y)

x = x.at[idx].apply(ufunc)

ufunc.at(x, idx)

x = x.at[idx].get()

x = x[idx]

None of the x.at expressions modify the original x; instead they return a modified copy of x. However, inside a jit() compiled function, expressions like x = x.at[idx].set(y) are guaranteed to be applied in-place.

Unlike NumPy in-place operations such as x[idx] += y, if multiple indices refer to the same location, all updates will be applied (NumPy would only apply the last update, rather than applying all updates.) The order in which conflicting updates are applied is implementation-defined and may be nondeterministic (e.g., due to concurrency on some hardware platforms).

By default, JAX assumes that all indices are in-bounds. Alternative out-of-bound index semantics can be specified via the mode parameter (see below).

Parameters:

  • mode –

    string specifying out-of-bound indexing mode. Options are:

    • "promise_in_bounds": (default) The user promises that indices are in bounds. No additional checking will be performed. In practice, this means that out-of-bounds indices in get() will be clipped, and out-of-bounds indices in set(), add(), etc. will be dropped.

    • "clip": clamp out of bounds indices into valid range.

    • "drop": ignore out-of-bound indices.

    • "fill": alias for "drop". For get(), the optional fill_value argument specifies the value that will be returned.

    See jax.lax.GatherScatterMode for more details.

  • wrap_negative_indices – If True (default) then negative indices indicate position from the end of the array, similar to Python and NumPy indexing. If False, then negative indices are considered out-of-bounds and behave according to the mode parameter.

  • fill_value – Only applies to the get() method: the fill value to return for out-of-bounds slices when mode is 'fill'. Ignored otherwise. Defaults to NaN for inexact types, the largest negative value for signed types, the largest positive value for unsigned types, and True for booleans.

  • indices_are_sorted – If True, the implementation will assume that the (normalized) indices passed to at[] are sorted in ascending order, which can lead to more efficient execution on some backends. If True but the indices are not actually sorted, the output is undefined.

  • unique_indices – If True, the implementation will assume that the (normalized) indices passed to at[] are unique, which can result in more efficient execution on some backends. If True but the indices are not actually unique, the output is undefined.

Examples

>>> x = jnp.arange(5.0)
>>> x
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[2].get()
Array(2., dtype=float32)
>>> x.at[2].add(10)
Array([ 0.,  1., 12.,  3.,  4.], dtype=float32)

By default, out-of-bound indices are ignored in updates, but this behavior can be controlled with the mode parameter:

>>> x.at[10].add(10)  # dropped
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[20].add(10, mode='clip')  # clipped
Array([ 0.,  1.,  2.,  3., 14.], dtype=float32)

For get(), out-of-bound indices are clipped by default:

>>> x.at[20].get()  # out-of-bounds indices clipped
Array(4., dtype=float32)
>>> x.at[20].get(mode='fill')  # out-of-bounds indices filled with NaN
Array(nan, dtype=float32)
>>> x.at[20].get(mode='fill', fill_value=-1)  # custom fill value
Array(-1., dtype=float32)

Negative indices count from the end of the array, but this behavior can be disabled by setting wrap_negative_indices = False:

>>> x.at[-1].set(99)
Array([ 0.,  1.,  2.,  3., 99.], dtype=float32)
>>> x.at[-1].set(99, wrap_negative_indices=False, mode='drop')  # dropped!
Array([0., 1., 2., 3., 4.], dtype=float32)
block_until_ready()#

Block until the array is ready.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.block_until_ready() is q
True
decompose(bases: Sequence[Unit | UnitBase | CompositeUnit | str], /)#

Decompose the quantity into the given bases.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.decompose(["cm", "s"])
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

bases (Sequence[Unit | UnitBase | CompositeUnit | str])

Return type:

AbstractQuantity

property device: Device#

Device where the array is located.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").device
CpuDevice(id=0)
devices()#

Return the devices where the array is located.

Return type:

set[Device]

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.devices()
{CpuDevice(id=0)}
property dtype: dtype#

Data type of the array.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").dtype
dtype('int32')
flatten()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.flatten()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
classmethod from_(cls: type[AbstractQuantity], *args: Any, **kwargs: Any)#
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a unxt.Quantity from an array-like value and a unit.

Parameters:

  • value – The array-like value.

  • unit – The unit of the value.

  • dtype – The data type of the array (keyword-only).

  • args (Any)

  • kwargs (Any)

Return type:

AbstractQuantity

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> u.Quantity.from_(x, "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_([1.0, 2, 3], "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_((1.0, 2, 3), "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], /, *, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Make a unxt.AbstractQuantity from an array-like value and a unit kwarg.

Examples

For this example we’ll use the unxt.Quantity class. The same applies to any subclass of unxt.AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_([1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], *, value: Any, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a AbstractQuantity from value and unit kwargs.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_(value=[1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], mapping: Mapping[str, Any]) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from a Mapping.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> q = u.Quantity.from_({"value": x, "unit": "m"})
>>> q
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_({"value": q, "unit": "km"})
Quantity(Array([0.001, 0.002, 0.003], dtype=float32), unit='km')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, "cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: NoneType, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, None)
Quantity(Array(1, dtype=int32, ...), unit='m')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, /, *, unit: Any | None = None, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity, with no unit change.

from_(cls: type[AbstractQuantity], value: Quantity, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"))
Quantity(Array(1., dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: Quantity, u: Any, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"), "cm")
Quantity(Array(100., dtype=float32), unit='cm')
Parameters:
Return type:

AbstractQuantity

property mT: AbstractQuantity#

Matrix transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.mT
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
max(*args: Any, **kwargs: Any)#

Return the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.max()
Quantity(Array(3, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

mean(*args: Any, **kwargs: Any)#

Return the mean value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.mean()
Quantity(Array(2., dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

min(*args: Any, **kwargs: Any)#

Return the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.min()
Quantity(Array(1, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

property ndim: int#

Number of dimensions.

Examples

>>> import unxt as u
>>> q = u.Quantity([[1]], "m")
>>> q.ndim
2
ravel()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.ravel()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
reshape(*args: Any, order: str = 'C')#

Return a reshaped version of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3, 4], "m")
>>> q.reshape(2, 2)
Quantity(Array([[1, 2],
                          [3, 4]], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

round(*args: Any, **kwargs: Any)#

Round the array to the given number of decimals.

Examples

>>> import unxt as u
>>> q = u.Quantity([1.1, 2.2, 3.3], "m")
>>> q.round(0)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property shape: tuple[int, ...]#

Shape of the array.

property sharding: Any#

Return the sharding configuration of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.sharding
SingleDeviceSharding(device=..., memory_kind=...)
property size: int#

Total number of elements.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.size
3
squeeze(*args: Any, **kwargs: Any)#

Return the array with all single-dimensional entries removed.

Examples

>>> import unxt as u
>>> q = u.Quantity([[[1], [2], [3]]], "m")
>>> q.squeeze()
Quantity(Array([1, 2, 3], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

to(u: Any, /)#

Convert the quantity to the given units.

See unxt.quantity.AbstractQuantity.uconvert.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

to_device(device: None | Device = None)#

Move the array to a new device.

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.to_device(None)
Quantity(Array(1, dtype=int32, weak_type=True), unit='m')
Parameters:

device (None | Device)

Return type:

AbstractQuantity

to_value(u: Any, /)#

Return the value in the given units.

See unxt.AbstractQuantity.ustrip.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to_value("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Union[Array, ndarray, bool, number, bool, int, float, complex, ArrayLike]

uconvert(u: Any, /)#

Convert the quantity to the given units.

See also

None

convert a quantity to a new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.uconvert("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

ustrip(u: Any, /)#

Return the value in the given units.

See also

None

strip the units from a quantity.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.ustrip("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Array

wrap_to(min: AbstractQuantity, max: AbstractQuantity)#

Wrap the angle to the range [min, max).

Parameters:
Return type:

AbstractAngle

See also

None

functional version of this method.

Examples

>>> import unxt as u
>>> angle = u.Angle(370, "deg")
>>> angle.wrap_to(min=u.Q(0, "deg"), max=u.Q(360, "deg"))
Angle(Array(10, dtype=int32, ...), unit='deg')
value: AbstractVar[Union[Shaped[Array, '*shape'], Shaped[StaticValue, '*shape']]]#

The value of the unxt.AbstractQuantity.

unit: AbstractVar[Unit | UnitBase | CompositeUnit]#

The unit associated with this value.

class unxt.quantity.Angle(value: Any, unit: Any)#

Bases: AbstractAngle

Angular quantity.

Examples

>>> import unxt as u

Create an Angle:

>>> q = u.Angle(1, "rad")
>>> q
Angle(Array(1, dtype=int32, ...), unit='rad')

Wrap an Angle to a range:

>>> q = u.Angle(370, "deg")
>>> q.wrap_to(u.Q(0, "deg"), u.Q(360, "deg"))
Angle(Array(10, dtype=int32, ...), unit='deg')

Create an Angle array:

>>> q = u.Angle([1, 2, 3], "deg")
>>> q
Angle(Array([1, 2, 3], dtype=int32), unit='deg')

Do math on an Angle:

>>> 2 * q
Angle(Array([2, 4, 6], dtype=int32), unit='deg')

>>> q % u.Q(4, "deg")
Angle(Array([1, 2, 3], dtype=int32), unit='deg')
Parameters:
property T: AbstractQuantity#

Transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.T
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
argmax(*args: Any, **kwargs: Any)#

Return the indices of the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmax()
Array(2, dtype=int32)
Parameters:
Return type:

Array

argmin(*args: Any, **kwargs: Any)#

Return the indices of the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmin()
Array(0, dtype=int32)
Parameters:
Return type:

Array

astype(*args: Any, **kwargs: Any)#

Copy the array and cast to a specified dtype.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.dtype
dtype('int32')

>>> q.astype(float)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property at: _QuantityIndexUpdateHelper#

Helper property for index update functionality.

The at property provides a functionally pure equivalent of in-place array modifications.

In particular:

Alternate syntax

Equivalent In-place expression

x = x.at[idx].set(y)

x[idx] = y

x = x.at[idx].add(y)

x[idx] += y

x = x.at[idx].subtract(y)

x[idx] -= y

x = x.at[idx].multiply(y)

x[idx] *= y

x = x.at[idx].divide(y)

x[idx] /= y

x = x.at[idx].power(y)

x[idx] **= y

x = x.at[idx].min(y)

x[idx] = minimum(x[idx], y)

x = x.at[idx].max(y)

x[idx] = maximum(x[idx], y)

x = x.at[idx].apply(ufunc)

ufunc.at(x, idx)

x = x.at[idx].get()

x = x[idx]

None of the x.at expressions modify the original x; instead they return a modified copy of x. However, inside a jit() compiled function, expressions like x = x.at[idx].set(y) are guaranteed to be applied in-place.

Unlike NumPy in-place operations such as x[idx] += y, if multiple indices refer to the same location, all updates will be applied (NumPy would only apply the last update, rather than applying all updates.) The order in which conflicting updates are applied is implementation-defined and may be nondeterministic (e.g., due to concurrency on some hardware platforms).

By default, JAX assumes that all indices are in-bounds. Alternative out-of-bound index semantics can be specified via the mode parameter (see below).

Parameters:

  • mode –

    string specifying out-of-bound indexing mode. Options are:

    • "promise_in_bounds": (default) The user promises that indices are in bounds. No additional checking will be performed. In practice, this means that out-of-bounds indices in get() will be clipped, and out-of-bounds indices in set(), add(), etc. will be dropped.

    • "clip": clamp out of bounds indices into valid range.

    • "drop": ignore out-of-bound indices.

    • "fill": alias for "drop". For get(), the optional fill_value argument specifies the value that will be returned.

    See jax.lax.GatherScatterMode for more details.

  • wrap_negative_indices – If True (default) then negative indices indicate position from the end of the array, similar to Python and NumPy indexing. If False, then negative indices are considered out-of-bounds and behave according to the mode parameter.

  • fill_value – Only applies to the get() method: the fill value to return for out-of-bounds slices when mode is 'fill'. Ignored otherwise. Defaults to NaN for inexact types, the largest negative value for signed types, the largest positive value for unsigned types, and True for booleans.

  • indices_are_sorted – If True, the implementation will assume that the (normalized) indices passed to at[] are sorted in ascending order, which can lead to more efficient execution on some backends. If True but the indices are not actually sorted, the output is undefined.

  • unique_indices – If True, the implementation will assume that the (normalized) indices passed to at[] are unique, which can result in more efficient execution on some backends. If True but the indices are not actually unique, the output is undefined.

Examples

>>> x = jnp.arange(5.0)
>>> x
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[2].get()
Array(2., dtype=float32)
>>> x.at[2].add(10)
Array([ 0.,  1., 12.,  3.,  4.], dtype=float32)

By default, out-of-bound indices are ignored in updates, but this behavior can be controlled with the mode parameter:

>>> x.at[10].add(10)  # dropped
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[20].add(10, mode='clip')  # clipped
Array([ 0.,  1.,  2.,  3., 14.], dtype=float32)

For get(), out-of-bound indices are clipped by default:

>>> x.at[20].get()  # out-of-bounds indices clipped
Array(4., dtype=float32)
>>> x.at[20].get(mode='fill')  # out-of-bounds indices filled with NaN
Array(nan, dtype=float32)
>>> x.at[20].get(mode='fill', fill_value=-1)  # custom fill value
Array(-1., dtype=float32)

Negative indices count from the end of the array, but this behavior can be disabled by setting wrap_negative_indices = False:

>>> x.at[-1].set(99)
Array([ 0.,  1.,  2.,  3., 99.], dtype=float32)
>>> x.at[-1].set(99, wrap_negative_indices=False, mode='drop')  # dropped!
Array([0., 1., 2., 3., 4.], dtype=float32)
block_until_ready()#

Block until the array is ready.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.block_until_ready() is q
True
decompose(bases: Sequence[Unit | UnitBase | CompositeUnit | str], /)#

Decompose the quantity into the given bases.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.decompose(["cm", "s"])
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

bases (Sequence[Unit | UnitBase | CompositeUnit | str])

Return type:

AbstractQuantity

property device: Device#

Device where the array is located.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").device
CpuDevice(id=0)
devices()#

Return the devices where the array is located.

Return type:

set[Device]

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.devices()
{CpuDevice(id=0)}
property dtype: dtype#

Data type of the array.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").dtype
dtype('int32')
flatten()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.flatten()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
classmethod from_(cls: type[AbstractQuantity], *args: Any, **kwargs: Any)#
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a unxt.Quantity from an array-like value and a unit.

Parameters:

  • value – The array-like value.

  • unit – The unit of the value.

  • dtype – The data type of the array (keyword-only).

  • args (Any)

  • kwargs (Any)

Return type:

AbstractQuantity

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> u.Quantity.from_(x, "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_([1.0, 2, 3], "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_((1.0, 2, 3), "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], /, *, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Make a unxt.AbstractQuantity from an array-like value and a unit kwarg.

Examples

For this example we’ll use the unxt.Quantity class. The same applies to any subclass of unxt.AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_([1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], *, value: Any, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a AbstractQuantity from value and unit kwargs.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_(value=[1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], mapping: Mapping[str, Any]) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from a Mapping.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> q = u.Quantity.from_({"value": x, "unit": "m"})
>>> q
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_({"value": q, "unit": "km"})
Quantity(Array([0.001, 0.002, 0.003], dtype=float32), unit='km')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, "cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: NoneType, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, None)
Quantity(Array(1, dtype=int32, ...), unit='m')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, /, *, unit: Any | None = None, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity, with no unit change.

from_(cls: type[AbstractQuantity], value: Quantity, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"))
Quantity(Array(1., dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: Quantity, u: Any, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"), "cm")
Quantity(Array(100., dtype=float32), unit='cm')
Parameters:
Return type:

AbstractQuantity

property mT: AbstractQuantity#

Matrix transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.mT
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
max(*args: Any, **kwargs: Any)#

Return the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.max()
Quantity(Array(3, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

mean(*args: Any, **kwargs: Any)#

Return the mean value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.mean()
Quantity(Array(2., dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

min(*args: Any, **kwargs: Any)#

Return the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.min()
Quantity(Array(1, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

property ndim: int#

Number of dimensions.

Examples

>>> import unxt as u
>>> q = u.Quantity([[1]], "m")
>>> q.ndim
2
ravel()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.ravel()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
reshape(*args: Any, order: str = 'C')#

Return a reshaped version of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3, 4], "m")
>>> q.reshape(2, 2)
Quantity(Array([[1, 2],
                          [3, 4]], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

round(*args: Any, **kwargs: Any)#

Round the array to the given number of decimals.

Examples

>>> import unxt as u
>>> q = u.Quantity([1.1, 2.2, 3.3], "m")
>>> q.round(0)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property shape: tuple[int, ...]#

Shape of the array.

property sharding: Any#

Return the sharding configuration of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.sharding
SingleDeviceSharding(device=..., memory_kind=...)
property size: int#

Total number of elements.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.size
3
squeeze(*args: Any, **kwargs: Any)#

Return the array with all single-dimensional entries removed.

Examples

>>> import unxt as u
>>> q = u.Quantity([[[1], [2], [3]]], "m")
>>> q.squeeze()
Quantity(Array([1, 2, 3], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

to(u: Any, /)#

Convert the quantity to the given units.

See unxt.quantity.AbstractQuantity.uconvert.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

to_device(device: None | Device = None)#

Move the array to a new device.

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.to_device(None)
Quantity(Array(1, dtype=int32, weak_type=True), unit='m')
Parameters:

device (None | Device)

Return type:

AbstractQuantity

to_value(u: Any, /)#

Return the value in the given units.

See unxt.AbstractQuantity.ustrip.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to_value("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Union[Array, ndarray, bool, number, bool, int, float, complex, ArrayLike]

uconvert(u: Any, /)#

Convert the quantity to the given units.

See also

None

convert a quantity to a new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.uconvert("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

ustrip(u: Any, /)#

Return the value in the given units.

See also

None

strip the units from a quantity.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.ustrip("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Array

wrap_to(min: AbstractQuantity, max: AbstractQuantity)#

Wrap the angle to the range [min, max).

Parameters:
Return type:

AbstractAngle

See also

None

functional version of this method.

Examples

>>> import unxt as u
>>> angle = u.Angle(370, "deg")
>>> angle.wrap_to(min=u.Q(0, "deg"), max=u.Q(360, "deg"))
Angle(Array(10, dtype=int32, ...), unit='deg')
value: Union[Real[Array, '*shape'], Real[StaticValue, '*shape']]#

The value of the unxt.AbstractQuantity.

unit: Unit | UnitBase | CompositeUnit#

The unit associated with this value.

class unxt.quantity.AbstractParametricQuantity#

Bases: AbstractParametricQuantity

Arrays with associated units.

This class is parametrized by the dimensions of the units.

property T: AbstractQuantity#

Transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.T
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
argmax(*args: Any, **kwargs: Any)#

Return the indices of the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmax()
Array(2, dtype=int32)
Parameters:
Return type:

Array

argmin(*args: Any, **kwargs: Any)#

Return the indices of the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.argmin()
Array(0, dtype=int32)
Parameters:
Return type:

Array

astype(*args: Any, **kwargs: Any)#

Copy the array and cast to a specified dtype.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.dtype
dtype('int32')

>>> q.astype(float)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property at: _QuantityIndexUpdateHelper#

Helper property for index update functionality.

The at property provides a functionally pure equivalent of in-place array modifications.

In particular:

Alternate syntax

Equivalent In-place expression

x = x.at[idx].set(y)

x[idx] = y

x = x.at[idx].add(y)

x[idx] += y

x = x.at[idx].subtract(y)

x[idx] -= y

x = x.at[idx].multiply(y)

x[idx] *= y

x = x.at[idx].divide(y)

x[idx] /= y

x = x.at[idx].power(y)

x[idx] **= y

x = x.at[idx].min(y)

x[idx] = minimum(x[idx], y)

x = x.at[idx].max(y)

x[idx] = maximum(x[idx], y)

x = x.at[idx].apply(ufunc)

ufunc.at(x, idx)

x = x.at[idx].get()

x = x[idx]

None of the x.at expressions modify the original x; instead they return a modified copy of x. However, inside a jit() compiled function, expressions like x = x.at[idx].set(y) are guaranteed to be applied in-place.

Unlike NumPy in-place operations such as x[idx] += y, if multiple indices refer to the same location, all updates will be applied (NumPy would only apply the last update, rather than applying all updates.) The order in which conflicting updates are applied is implementation-defined and may be nondeterministic (e.g., due to concurrency on some hardware platforms).

By default, JAX assumes that all indices are in-bounds. Alternative out-of-bound index semantics can be specified via the mode parameter (see below).

Parameters:

  • mode –

    string specifying out-of-bound indexing mode. Options are:

    • "promise_in_bounds": (default) The user promises that indices are in bounds. No additional checking will be performed. In practice, this means that out-of-bounds indices in get() will be clipped, and out-of-bounds indices in set(), add(), etc. will be dropped.

    • "clip": clamp out of bounds indices into valid range.

    • "drop": ignore out-of-bound indices.

    • "fill": alias for "drop". For get(), the optional fill_value argument specifies the value that will be returned.

    See jax.lax.GatherScatterMode for more details.

  • wrap_negative_indices – If True (default) then negative indices indicate position from the end of the array, similar to Python and NumPy indexing. If False, then negative indices are considered out-of-bounds and behave according to the mode parameter.

  • fill_value – Only applies to the get() method: the fill value to return for out-of-bounds slices when mode is 'fill'. Ignored otherwise. Defaults to NaN for inexact types, the largest negative value for signed types, the largest positive value for unsigned types, and True for booleans.

  • indices_are_sorted – If True, the implementation will assume that the (normalized) indices passed to at[] are sorted in ascending order, which can lead to more efficient execution on some backends. If True but the indices are not actually sorted, the output is undefined.

  • unique_indices – If True, the implementation will assume that the (normalized) indices passed to at[] are unique, which can result in more efficient execution on some backends. If True but the indices are not actually unique, the output is undefined.

Examples

>>> x = jnp.arange(5.0)
>>> x
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[2].get()
Array(2., dtype=float32)
>>> x.at[2].add(10)
Array([ 0.,  1., 12.,  3.,  4.], dtype=float32)

By default, out-of-bound indices are ignored in updates, but this behavior can be controlled with the mode parameter:

>>> x.at[10].add(10)  # dropped
Array([0., 1., 2., 3., 4.], dtype=float32)
>>> x.at[20].add(10, mode='clip')  # clipped
Array([ 0.,  1.,  2.,  3., 14.], dtype=float32)

For get(), out-of-bound indices are clipped by default:

>>> x.at[20].get()  # out-of-bounds indices clipped
Array(4., dtype=float32)
>>> x.at[20].get(mode='fill')  # out-of-bounds indices filled with NaN
Array(nan, dtype=float32)
>>> x.at[20].get(mode='fill', fill_value=-1)  # custom fill value
Array(-1., dtype=float32)

Negative indices count from the end of the array, but this behavior can be disabled by setting wrap_negative_indices = False:

>>> x.at[-1].set(99)
Array([ 0.,  1.,  2.,  3., 99.], dtype=float32)
>>> x.at[-1].set(99, wrap_negative_indices=False, mode='drop')  # dropped!
Array([0., 1., 2., 3., 4.], dtype=float32)
block_until_ready()#

Block until the array is ready.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.block_until_ready() is q
True
decompose(bases: Sequence[Unit | UnitBase | CompositeUnit | str], /)#

Decompose the quantity into the given bases.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.decompose(["cm", "s"])
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

bases (Sequence[Unit | UnitBase | CompositeUnit | str])

Return type:

AbstractQuantity

property device: Device#

Device where the array is located.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").device
CpuDevice(id=0)
devices()#

Return the devices where the array is located.

Return type:

set[Device]

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.devices()
{CpuDevice(id=0)}
property dtype: dtype#

Data type of the array.

Examples

>>> import unxt as u
>>> u.Quantity(1, "m").dtype
dtype('int32')
flatten()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.flatten()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
classmethod from_(cls: type[AbstractQuantity], *args: Any, **kwargs: Any)#
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a unxt.Quantity from an array-like value and a unit.

Parameters:

  • value – The array-like value.

  • unit – The unit of the value.

  • dtype – The data type of the array (keyword-only).

  • args (Any)

  • kwargs (Any)

Return type:

AbstractQuantity

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> u.Quantity.from_(x, "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_([1.0, 2, 3], "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_((1.0, 2, 3), "m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: ArrayLike | list[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, '']] | tuple[Shaped[Array, ''] | Shaped[ndarray, ''] | bool | number | bool | int | float | complex | Shaped[ArrayLike, ''], ...], /, *, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Make a unxt.AbstractQuantity from an array-like value and a unit kwarg.

Examples

For this example we’ll use the unxt.Quantity class. The same applies to any subclass of unxt.AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_([1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], *, value: Any, unit: Any, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a AbstractQuantity from value and unit kwargs.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import unxt as u
>>> u.Quantity.from_(value=[1.0, 2, 3], unit="m")
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], mapping: Mapping[str, Any]) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from a Mapping.

Examples

For this example we’ll use the Quantity class. The same applies to any subclass of AbstractQuantity.

>>> import jax.numpy as jnp
>>> import unxt as u

>>> x = jnp.array([1.0, 2, 3])
>>> q = u.Quantity.from_({"value": x, "unit": "m"})
>>> q
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')

>>> u.Quantity.from_({"value": q, "unit": "km"})
Quantity(Array([0.001, 0.002, 0.003], dtype=float32), unit='km')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: Any, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, "cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, unit: NoneType, /, *, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> u.Quantity.from_(q, None)
Quantity(Array(1, dtype=int32, ...), unit='m')
from_(cls: type[AbstractQuantity], value: AbstractQuantity, /, *, unit: Any | None = None, dtype: Any = None) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity, with no unit change.

from_(cls: type[AbstractQuantity], value: Quantity, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"))
Quantity(Array(1., dtype=float32), unit='m')
from_(cls: type[AbstractQuantity], value: Quantity, u: Any, /, **kwargs: Any) → AbstractQuantity
Parameters:
Return type:

AbstractQuantity

Construct a Quantity from another Quantity.

The value is converted to the new unit.

Examples

>>> import unxt as u
>>> import astropy.units as apyu

>>> u.Quantity.from_(apyu.Quantity(1, "m"), "cm")
Quantity(Array(100., dtype=float32), unit='cm')
Parameters:
Return type:

AbstractQuantity

property mT: AbstractQuantity#

Matrix transpose of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([[0, 1], [1, 2]], "m")
>>> q.mT
Quantity(Array([[0, 1],
                          [1, 2]], dtype=int32), unit='m')
max(*args: Any, **kwargs: Any)#

Return the maximum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.max()
Quantity(Array(3, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

mean(*args: Any, **kwargs: Any)#

Return the mean value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.mean()
Quantity(Array(2., dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

min(*args: Any, **kwargs: Any)#

Return the minimum value.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.min()
Quantity(Array(1, dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

property ndim: int#

Number of dimensions.

Examples

>>> import unxt as u
>>> q = u.Quantity([[1]], "m")
>>> q.ndim
2
ravel()#

Return a flattened version of the array.

Return type:

AbstractQuantity

Examples

>>> import unxt as u
>>> q = u.Quantity([[1, 2], [3, 4]], "m")
>>> q.ravel()
Quantity(Array([1, 2, 3, 4], dtype=int32), unit='m')
reshape(*args: Any, order: str = 'C')#

Return a reshaped version of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3, 4], "m")
>>> q.reshape(2, 2)
Quantity(Array([[1, 2],
                          [3, 4]], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

round(*args: Any, **kwargs: Any)#

Round the array to the given number of decimals.

Examples

>>> import unxt as u
>>> q = u.Quantity([1.1, 2.2, 3.3], "m")
>>> q.round(0)
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
Parameters:
Return type:

AbstractQuantity

property shape: tuple[int, ...]#

Shape of the array.

property sharding: Any#

Return the sharding configuration of the array.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.sharding
SingleDeviceSharding(device=..., memory_kind=...)
property size: int#

Total number of elements.

Examples

>>> import unxt as u
>>> q = u.Quantity([1, 2, 3], "m")
>>> q.size
3
squeeze(*args: Any, **kwargs: Any)#

Return the array with all single-dimensional entries removed.

Examples

>>> import unxt as u
>>> q = u.Quantity([[[1], [2], [3]]], "m")
>>> q.squeeze()
Quantity(Array([1, 2, 3], dtype=int32), unit='m')
Parameters:
Return type:

AbstractQuantity

to(u: Any, /)#

Convert the quantity to the given units.

See unxt.quantity.AbstractQuantity.uconvert.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

to_device(device: None | Device = None)#

Move the array to a new device.

Examples

>>> import unxt as u
>>> q = u.Quantity(1, "m")
>>> q.to_device(None)
Quantity(Array(1, dtype=int32, weak_type=True), unit='m')
Parameters:

device (None | Device)

Return type:

AbstractQuantity

to_value(u: Any, /)#

Return the value in the given units.

See unxt.AbstractQuantity.ustrip.

Examples

>>> from unxt import Quantity

>>> q = Quantity(1, "m")
>>> q.to_value("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Union[Array, ndarray, bool, number, bool, int, float, complex, ArrayLike]

uconvert(u: Any, /)#

Convert the quantity to the given units.

See also

None

convert a quantity to a new unit.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.uconvert("cm")
Quantity(Array(100., dtype=float32, ...), unit='cm')
Parameters:

u (Any)

Return type:

AbstractQuantity

ustrip(u: Any, /)#

Return the value in the given units.

See also

None

strip the units from a quantity.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> q.ustrip("cm")
Array(100., dtype=float32, weak_type=True)
Parameters:

u (Any)

Return type:

Array

value: eqx.AbstractVar[Shaped[Array | StaticValue, '*shape']]#

The value of the AbstractQuantity.

unit: eqx.AbstractVar[AbstractUnit]#

The unit associated with this value.

unxt.quantity.uconvert_value(uto: Any, ufrom: Any, x: Any, /)#

Convert the value from specified units to specified units.

General signature: (to_unit, from_unit, value) -> converted_value. Other signatures are defined via method dispatch. See uconvert_value.methods for details.

Examples

>>> import unxt as u  # implements `unxt_api.uconvert_value`

>>> u.uconvert_value(u.unit("m"), u.unit("km"), 1)
1000.0

>>> u.uconvert_value("m", "km", 1)
1000.0

For further examples, see the other method dispatches.

unxt.quantity.uconvert_value(tousys: AbstractUnitSystem, ufrom: Unit | UnitBase | CompositeUnit, x: ArrayLike, /) → ArrayLike
Parameters:
Return type:

Any

Convert the value from units to a unitsystem’s preferred units.

Examples

>>> import unxt as u
>>> u.uconvert_value(u.unitsystems.galactic, u.unit("km"), 1e17)  # kpc
3.2407792894443648

>>> u.unitsystems.galactic[u.dimension("length")]  # checking the units
Unit("kpc")
unxt.quantity.uconvert_value(tousys: AbstractUnitSystem, ufrom: str, x: ArrayLike, /) → ArrayLike
Parameters:
Return type:

Any

Convert the value from units to a unitsystem’s preferred units.

Examples

>>> import unxt as u
>>> u.uconvert_value(u.unitsystems.galactic, "km", 1e17)  # in kpc
3.2407792894443648

>>> u.unitsystems.galactic[u.dimension("length")]  # checking the units
Unit("kpc")
unxt.quantity.uconvert_value(uto: str, ufrom: str, x: ArrayLike, /) → ArrayLike
Parameters:
Return type:

Any

Convert the value to the specified units.

Examples

>>> import unxt as u

>>> u.uconvert_value("m", "km", 1)
1000.0
unxt.quantity.uconvert_value(uto: Any, ufrom: Any, x: AbstractQuantity, /) → AbstractQuantity
Parameters:
Return type:

Any

Convert the quantity to the specified units.

This is a convenience dispatch so that users can use the lower-level function with Quantity and not break their code. This dispatch simply calls uconvert, checking first that the units are convertible.

Examples

>>> import unxt as u

>>> q = u.Q(1, "km")
>>> u.uconvert_value("m", "km", q)
Quantity(Array(1000., dtype=float32, ...), unit='m')
unxt.quantity.uconvert_value(uto: UnitBase | Unit | FunctionUnitBase | StructuredUnit, ufrom: UnitBase | Unit | FunctionUnitBase | StructuredUnit, x: ArrayLike, /) → ArrayLike
Parameters:
Return type:

Any

Convert the value to the specified units.

Examples

>>> import astropy.units as apyu
>>> import unxt as u

>>> u.uconvert_value(apyu.Unit("km"), apyu.Unit("m"), 1000)
1.0
Parameters:
Return type:

Any

unxt.quantity.uconvert(u: Any, x: Any, /)#

Convert the quantity to the specified units.

General signature: (to_unit, quantity) -> converted_quantity. Other signatures are defined via method dispatch. See uconvert.methods for details.

Internally, {func}`unxt_api.uconvert` often calls to {func}`unxt_api.uconvert_value` to perform the numerical conversion on the Quantity’s value.

Examples

>>> import unxt as u  # implements `unxt_api.uconvert`

>>> q = u.Quantity(1, "km")
>>> u.uconvert(u.unit("m"), q)
Quantity(Array(1000., dtype=float32, ...), unit='m')

>>> u.uconvert("m", q)
Quantity(Array(1000., dtype=float32, ...), unit='m')

For further examples, see the other method dispatches.

unxt.quantity.uconvert(ustr: str, x: AbstractQuantity, /) → AbstractQuantity
Parameters:
Return type:

Any

Convert the quantity to the specified units.

Examples

>>> from unxt import Quantity, units

>>> x = Quantity(1000, "m")
>>> uconvert("km", x)
Quantity(Array(1., dtype=float32, ...), unit='km')
unxt.quantity.uconvert(usys: AbstractUnitSystem, x: AbstractQuantity, /) → AbstractQuantity
Parameters:
Return type:

Any

Convert the quantity to the specified units.

Examples

>>> from unxt import Quantity, units
>>> from unxt.unitsystems import galactic

>>> q = Quantity(1e17, "km")
>>> uconvert(galactic, q)
Quantity(Array(3.2407792, dtype=float32, ...), unit='kpc')
unxt.quantity.uconvert(u: UnitBase | Unit | FunctionUnitBase | StructuredUnit, x: AbstractQuantity, /) → AbstractQuantity
Parameters:
Return type:

Any

Convert the quantity to the specified units.

Examples

>>> import astropy.units as apyu
>>> import unxt as u

>>> x = u.Quantity(1000, "m")
>>> u.uconvert(u.unit("km"), x)
Quantity(Array(1., dtype=float32, ...), unit='km')

>>> x = u.Quantity([1, 2, 3], "Kelvin")
>>> with apyu.add_enabled_equivalencies(apyu.temperature()):
...     y = x.uconvert("deg_C")
>>> y
Quantity( Array([-272.15, -271.15, -270.15], dtype=float32, ...), unit='deg_C' )

>>> x = Quantity([1, 2, 3], "radian")
>>> with apyu.add_enabled_equivalencies(apyu.dimensionless_angles()):
...     y = x.uconvert("")
>>> y
Quantity(Array([1., 2., 3.], dtype=float32, ...), unit='')
Parameters:
Return type:

Any

unxt.quantity.ustrip(*args: Any)#

Strip the units from the quantity, first converting if necessary.

General signature: (to_unit, quantity) -> value_array. Other signatures are defined via method dispatch. See ustrip.methods for details.

Examples

>>> import unxt as u  # implements `unxt_api.ustrip`

>>> q = u.Quantity(1, "km")
>>> ustrip(u.unit("m"), q)
Array(1000., dtype=float32, ...)

>>> u.ustrip("m", q)
Array(1000., dtype=float32, ...)

For further examples, see the other method dispatches.

unxt.quantity.ustrip(flag: type[AllowValue], unit: Any, x: Any, /) → Any
Parameters:

args (Any)

Return type:

Any

Strip the units from a value. This is a no-op.

Examples

>>> import jax.numpy as jnp
>>> import unxt as u
>>> from unxt.quantity import AllowValue

>>> x = jnp.array(1)
>>> y = u.ustrip(AllowValue, "km", x)
>>> y is x
True

>>> x = 1_000
>>> y = u.ustrip(AllowValue, "km", x)
>>> y is x
True

>>> x = "hello"
>>> y = u.ustrip(AllowValue, "km", x)
>>> y is x
True
unxt.quantity.ustrip(flag: type[AllowValue], x: Any, /) → Any
Parameters:

args (Any)

Return type:

Any

Strip the units from a value. This is a no-op.

Examples

>>> import jax.numpy as jnp
>>> import unxt as u
>>> from unxt.quantity import AllowValue

>>> x = jnp.array(1)
>>> y = u.ustrip(AllowValue, x)
>>> y is x
True

>>> x = 1_000
>>> y = u.ustrip(AllowValue, x)
>>> y is x
True

>>> x = "hello"
>>> y = u.ustrip(AllowValue, x)
>>> y is x
True
unxt.quantity.ustrip(flag: type[AllowValue], unit: Any, x: AbstractQuantity, /) → Any
Parameters:

args (Any)

Return type:

Any

Strip the units from a quantity.

Examples

>>> import unxt as u
>>> from unxt.quantity import AllowValue
>>> q = u.Q(1000, "m")
>>> u.ustrip(AllowValue, "km", q)
Array(1., dtype=float32, ...)
unxt.quantity.ustrip(flag: type[AllowValue], x: AbstractQuantity, /) → Any
Parameters:

args (Any)

Return type:

Any

Strip the units from a quantity.

Examples

>>> import jax.numpy as jnp
>>> import unxt as u
>>> from unxt.quantity import AllowValue

>>> x = u.Q(1, "kpc")
>>> y = u.ustrip(AllowValue, x)
>>> not isinstance(y, u.Quantity)
True
>>> y == 1
Array(True, dtype=bool, ...)
unxt.quantity.ustrip(x: StaticQuantity, /) → ndarray
Parameters:

args (Any)

Return type:

Any

Strip the units from a static quantity.

unxt.quantity.ustrip(x: AbstractQuantity, /) → Array | ndarray
Parameters:

args (Any)

Return type:

Any

Strip the units from the quantity.

Examples

>>> import unxt as u

>>> q = u.Q(1000, "m")
>>> u.ustrip(q)
Array(1000, dtype=int32, weak_type=True)

>>> u.ustrip(q) is q.value
True
unxt.quantity.ustrip(u: Unit | UnitBase | CompositeUnit, x: AbstractQuantity, /) → Array | ndarray
Parameters:

args (Any)

Return type:

Any

Strip the units from the quantity.

Examples

>>> import unxt as u

>>> q = u.Q(1000, "m")
>>> u.ustrip(u.unit("km"), q)
Array(1., dtype=float32, ...)
unxt.quantity.ustrip(u: str, x: AbstractQuantity, /) → Array | ndarray
Parameters:

args (Any)

Return type:

Any

Strip the units from the quantity.

Examples

>>> import unxt as u

>>> q = u.Q(1000, "m")
>>> u.ustrip("km", q)
Array(1., dtype=float32, ...)
unxt.quantity.ustrip(u: AbstractUnitSystem, x: AbstractQuantity, /) → Array | ndarray
Parameters:

args (Any)

Return type:

Any

Strip the units from the quantity.

Examples

>>> import unxt as u
>>> from unxt.unitsystems import galactic

>>> q = u.Q(1e17, "km")
>>> u.ustrip(galactic, q)
Array(3.2407792, dtype=float32, weak_type=True)
unxt.quantity.ustrip(u: Any, x: Quantity) → Any
Parameters:

args (Any)

Return type:

Any

Strip the units from the quantity.

Examples

>>> import astropy.units as apyu
>>> import unxt as u

>>> x = apyu.Quantity(1000, "m")
>>> float(u.ustrip(u.unit("m"), x))
1000.0
unxt.quantity.ustrip(flag: type[AllowValue], u: Any, x: Quantity, /) → Any
Parameters:

args (Any)

Return type:

Any

Strip the units from a quantity.

Examples

>>> import unxt as u
>>> q = u.Quantity(1000, "m")
>>> u.ustrip(AllowValue, "km", q)
Array(1., dtype=float32, ...)
Parameters:

args (Any)

Return type:

Any

unxt.quantity.is_unit_convertible(to_unit: Any, from_: Any, /)#

Check if the units are convertible.

General signature is (to_unit, from_unit) -> bool. Other signatures are defined via method dispatch. See is_unit_convertible.methods for details.

Examples

>>> import unxt as u  # implements `unxt_api.is_unit_convertible`
>>> u.is_unit_convertible(u.unit("m"), u.unit("km"))
True

>>> u.is_unit_convertible(u.unit("m"), u.unit("s"))
False
unxt.quantity.is_unit_convertible(to_unit: Any, from_: Any, /) → bool
Parameters:
Return type:

bool

Check if a unit can be converted to another unit.

Parameters:

  • to_unit (Any) – The unit to convert to. Converted to a unit object using unxt.unit.

  • from (Any) – The unit to convert from. Converted to a unit object using unxt.unit, Note this means it also support Quantity objects and many others.

  • from_ (Any)

Return type:

bool

Examples

>>> from unxt import is_unit_convertible
>>> is_unit_convertible("cm", "m")
True

>>> is_unit_convertible("m", "Gyr")
False
unxt.quantity.is_unit_convertible(to_unit: Any, from_: AbstractQuantity, /) → bool
Parameters:
Return type:

bool

Check if a Quantity can be converted to another unit.

Examples

>>> from unxt import Quantity, is_unit_convertible
>>> q = Quantity(1, "m")

>>> is_unit_convertible("cm", q)
True

>>> is_unit_convertible("Gyr", q)
False
Parameters:
Return type:

bool

unxt.quantity.wrap_to(x: Any, min: Any, max: Any, /)#

Wrap to the range [min, max).

General signature: (x, min, max) -> wrapped_x. Other signatures are defined via method dispatch. See wrap_to.methods for details.

Examples

>>> import unxt as u
>>>
>>> angle = u.Angle(370, "deg")
>>> min, max = u.Q(0, "deg"), u.Q(360, "deg")
>>>
>>> u.quantity.wrap_to(angle, min, max)
Angle(Array(10, dtype=int32, ...), unit='deg')
>>>
>>> u.quantity.wrap_to(angle, min=min, max=max)
Angle(Array(10, dtype=int32, ...), unit='deg')
unxt.quantity.wrap_to(x: Any, /, *, min: Any, max: Any) → Any
Parameters:
Return type:

Any

Wrap to the range [min, max).

unxt.quantity.wrap_to(angle: AbstractQuantity, min: AbstractQuantity, max: AbstractQuantity, /) → AbstractQuantity
Parameters:
Return type:

Any

Wrap to the range [min, max).

Examples

>>> import unxt as u

>>> angle = u.Angle(370, "deg")
>>> u.quantity.wrap_to(angle, min=u.Q(0, "deg"), max=u.Q(360, "deg"))
Angle(Array(10, dtype=int32, ...), unit='deg')
Parameters:
Return type:

Any

unxt.quantity.is_any_quantity(obj: Any, /)#

Check if an object is an instance of unxt.quantity.AbstractQuantity.

Examples

>>> import unxt as u

>>> q = u.Quantity(1, "m")
>>> is_any_quantity(q)
True
Parameters:

obj (Any)

Return type:

TypeGuard[AbstractQuantity]

unxt.quantity.convert_to_quantity_value(obj: Any, /)#

Convert for the value field of an AbstractQuantity subclass.

unxt.quantity.convert_to_quantity_value(obj: StaticValue, /) → StaticValue
Parameters:

obj (Any)

Return type:

Any

Allow static values in Quantity-like classes.

unxt.quantity.convert_to_quantity_value(obj: ArrayValue, /) → Any
Parameters:

obj (Any)

Return type:

Any

Convert a quax.ArrayValue for the value field.

>>> import warnings
>>> import jax
>>> import jax.numpy as jnp
>>> from jaxtyping import Array
>>> from quax import ArrayValue

>>> class MyArray(ArrayValue):
...     value: Array
...
...     def aval(self):
...         return jax.core.ShapedArray(self.value.shape, self.value.dtype)
...
...     def materialise(self):
...         return self.value

>>> x = MyArray(jnp.array([1, 2, 3]))
>>> with warnings.catch_warnings(record=True, action="always") as w:
...     y = convert_to_quantity_value(x)
>>> y
MyArray(value=i32[3])
>>> print(f"Warning caught: {w[-1].message}")
Warning caught: 'quax.ArrayValue' subclass 'MyArray' ...
unxt.quantity.convert_to_quantity_value(obj: ArrayLike | list[Any] | tuple[Any, ...], /) → Array
Parameters:

obj (Any)

Return type:

Any

Convert an array-like object to a jax.numpy.ndarray.

>>> import jax.numpy as jnp
>>> from unxt.quantity import convert_to_quantity_value

>>> convert_to_quantity_value([1, 2, 3])
Array([1, 2, 3], dtype=int32)
unxt.quantity.convert_to_quantity_value(obj: AbstractQuantity, /) → NoReturn
Parameters:

obj (Any)

Return type:

Any

Disallow conversion of AbstractQuantity to a value.

>>> import unxt as u
>>> from unxt.quantity import convert_to_quantity_value

>>> try:
...     convert_to_quantity_value(u.Quantity(1, "m"))
... except TypeError as e:
...     print(e)
Cannot convert 'Quantity[PhysicalType('length')]' to a value.
For a Quantity, use the `.from_` constructor instead.
unxt.quantity.convert_to_quantity_value(obj: Quantity, /) → NoReturn
Parameters:

obj (Any)

Return type:

Any

Disallow conversion of AstropyQuantity to a value.

>>> import astropy.units as apyu
>>> from unxt.quantity import convert_to_quantity_value

>>> try:
...     convert_to_quantity_value(apyu.Quantity(1, "m"))
... except TypeError as e:
...     print(e)
Cannot convert 'Quantity' to a value.
For a Quantity, use the `.from_` constructor instead.
Parameters:

obj (Any)

Return type:

Any

class unxt.quantity.AllowValue#

Bases: object

A flag to allow a value to be passed through unxt.ustrip.

Examples

>>> import jax.numpy as jnp
>>> import unxt as u
>>> from unxt.quantity import AllowValue

>>> x = jnp.array(1)
>>> y = u.ustrip(AllowValue, "km", x)
>>> y is x
True

>>> u.ustrip(AllowValue, "km", u.Q(1000, "m"))
Array(1., dtype=float32, ...)

This is a flag, so it cannot be instantiated.

>>> try:
...     AllowValue()
... except TypeError as e:
...     print(e)
Cannot instantiate AllowValue
Return type:

NoReturn

Contents