Units

Units are measures of dimensions. Some common units are meters for length or seconds for time or Joules for energy.

unxt has two primary functions for working with units: unit and unit_of.

>>> import unxt as u

>>> u.unit
<multiple-dispatch function unit (...)>

>>> u.unit_of
<multiple-dispatch function unit_of (...)>

The function unit is for creating a unit, while unit_of is for getting the unit of an object.

First let’s create some units:

>>> m = u.unit('m')  # from a str
>>> m
Unit("m")

>>> u.unit(m)  # from a unit object
Unit("m")

Now let’s get the units from objects:

>>> print(u.unit_of("m"))  # str have no units
None

>>> u.unit_of(m)  # from a unit object
Unit("m")

>>> q = u.Q(5, 'm')  # from a Quantity
>>> u.unit_of(q)
Unit("m")

See also

API Documentation for Units

Unit Systems

A unit system is a standardized collection of units used together, such as the International System of Units (SI), the Imperial system, and natural units like Planck or atomic units. Each system defines base units (e.g., meters, kilograms) and derived units (e.g., joules, newtons) for consistent expression of quantities.

unxt provides a sub-module for working with unit systems: unxt.unitsystems. Unit systems are implemented as subclasses of the base class AbstractUnitSystem, which can be used for statically defining unit systems. However this rarely needs to be used directly. Instead, unxt provides some built-in unit systems and their realizations, such as galactic and solarsystem. Also, unxt has the functions unitsystem and unitsystem_of for dynamically making the realization of a unit system or getting one from an object.

See also

API Documentation for Unit Systems

AbstractUnitSystem class

See also

This rarely needs to be used. See unxt.unitsystem.

>>> from typing import Annotated
>>> from astropy.units import UnitBase, get_physical_type
>>> from unxt.unitsystems import AbstractUnitSystem


>>> class MyUSys(AbstractUnitSystem):
...     energy: Annotated[UnitBase, get_physical_type("energy")]
...     frequency: Annotated[UnitBase, get_physical_type("frequency")]
...     luminance: Annotated[UnitBase, get_physical_type("luminance")]

Built-in Unit Systems

unxt provides several built-in unit systems.

>>> from unxt.unitsystems import si
>>> si
unitsystem(m, kg, s, mol, A, K, cd, rad)

>>> from unxt.unitsystems import cgs
>>> cgs
unitsystem(cm, g, s, dyn, erg, Ba, P, St, rad)

>>> from unxt.unitsystems import galactic
>>> galactic
unitsystem(kpc, Myr, solMass, rad)

>>> from unxt.unitsystems import solarsystem
>>> solarsystem
unitsystem(AU, yr, solMass, rad)

Functions for Unit Systems

unxt has two primary functions for working with units: unitsystem and unitsystem_of.

>>> from unxt.unitsystems import unitsystem, unitsystem_of

unitsystem can return named unit systems:

>>> unitsystem("si")
unitsystem(m, kg, s, mol, A, K, cd, rad)

>>> unitsystem("cgs")
unitsystem(cm, g, s, dyn, erg, Ba, P, St, rad)

>>> unitsystem("galactic")
unitsystem(kpc, Myr, solMass, rad)

>>> unitsystem("solarsystem")
unitsystem(AU, yr, solMass, rad)

Unit systems are statically defined, the “galactic” and “solarsystem” units are instances of LTMAUnitSystem (length-time-mass-angle). If passed a set of units with dimensions matching one of the pre-defined unit system classes unitsystem will recognize this and return an instance of that unit system.

>>> from unxt.unitsystems import LTMAUnitSystem

>>> usys = unitsystem("kpc", "Myr", "solMass", "degree")
>>> usys
unitsystem(kpc, Myr, solMass, deg)

>>> isinstance(usys, LTMAUnitSystem)
True

>>> usys == unitsystem("galactic")
False

If the set of units does not correspond to any pre-defined unit system class, unitsystem will dynamically define this class, cache it for reuse, and return an instance for the set of units.

>>> from unxt.unitsystems import LTMAUnitSystem

>>> usys = unitsystem("kpc", "Myr", "solMass", "degree", "candela")
>>> usys
LengthTimeMassAngleLuminousIntensityUnitSystem(length=Unit("kpc"), time=Unit("Myr"), mass=Unit("solMass"), angle=Unit("deg"), luminous_intensity=Unit("cd"))

>>> isinstance(usys, LTMAUnitSystem)
False

unxt.unitsystem can create a dimensionless unit system if given None.

>>> unitsystem(None)
DimensionlessUnitSystem()

The dimensionless unit system is not the only special unit system. unxt also supports creating dynamical unit systems, where \(G = 1\) (or some other constant) and one of the “length”, “time”, “mass” dimensions is adjusted to make the units consistent.

>>> from unxt.unitsystems import DynamicalSimUSysFlag

>>> unitsystem(DynamicalSimUSysFlag, "m", "kg")
LengthMassTimeUnitSystem(length=Unit("m"), mass=Unit("kg"), time=Unit("122404 s"))

The construction of these constrained unit systems requires passing an unxt.unitsystems.AbstractUSysFlag.

Also, unitsystem can replace a unit in a unit system or extend a unit system.

>>> usys = unitsystem("m", "kg", "s")

>>> unitsystem(usys) is usys
True

>>> unitsystem(usys, "deg")
LengthMassTimeAngleUnitSystem(length=Unit("m"), mass=Unit("kg"), time=Unit("s"), angle=Unit("deg"))

Note

unxt.unitsystem supports a wide range of inputs, only some of which were covered here. To see the full range of options, execute unxt.unitsystem in an interactive Python session.