unxt.unitsystems

unxt.unitsystems#

Systems of units.

A unit system is a collection of units that are used together. In a unit system there are base units and derived units. Base units are the fundamental units of the system and derived units are constructed from the base units. For example, in the SI system, the base units are the meter, kilogram, second, ampere, kelvin, mole, and candela. Derived units are constructed from these base units, for example, the newton is a derived unit of force.

unxt provides powerful tools for defining and working with unit systems. Unit systems can be statically defined (useful for many tools and development environments) or dynamically defined (useful for interactive environments and Python’s general dynamism). Unit systems can be extended, compared, and used for decomposing units on quantities. There are many more features and tools for working with unit systems in unxt.

unxt.unitsystems.unitsystem(usys: AbstractUnitSystem, /)#

Convert a UnitSystem to a UnitSystem.

Examples

>>> from unxt.unitsystems import unitsystem
>>> usys = unitsystem("kpc", "Myr", "Msun", "radian")
>>> usys
unitsystem(kpc, Myr, solMass, rad)

>>> unitsystem(usys) is usys
True
unxt.unitsystems.unitsystem(seq: Sequence[Any], /) → AbstractUnitSystem
Parameters:

usys (AbstractUnitSystem)

Return type:

AbstractUnitSystem

Convert a UnitSystem or tuple of arguments to a UnitSystem.

Examples

>>> import unxt as u

>>> u.unitsystem(())
DimensionlessUnitSystem()

>>> u.unitsystem(("kpc", "Myr", "Msun", "radian"))
unitsystem(kpc, Myr, solMass, rad)

>>> u.unitsystem(["kpc", "Myr", "Msun", "radian"])
unitsystem(kpc, Myr, solMass, rad)
unxt.unitsystems.unitsystem(_: NoneType, /) → DimensionlessUnitSystem
Parameters:

usys (AbstractUnitSystem)

Return type:

AbstractUnitSystem

Dimensionless unit system from None.

Examples

>>> from unxt.unitsystems import unitsystem
>>> unitsystem(None)
DimensionlessUnitSystem()
unxt.unitsystems.unitsystem(*args: Any) → AbstractUnitSystem
Parameters:

usys (AbstractUnitSystem)

Return type:

AbstractUnitSystem

Convert a set of arguments to a UnitSystem.

Examples

>>> from unxt.unitsystems import unitsystem

>>> unitsystem("kpc", "Myr", "Msun", "radian")
unitsystem(kpc, Myr, solMass, rad)
unxt.unitsystems.unitsystem(name: str, /) → AbstractUnitSystem
Parameters:

usys (AbstractUnitSystem)

Return type:

AbstractUnitSystem

Return unit system from name.

Examples

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

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

>>> unitsystem("dimensionless")
DimensionlessUnitSystem()
unxt.unitsystems.unitsystem(usys: AbstractUnitSystem, *args: Any) → AbstractUnitSystem
Parameters:

usys (AbstractUnitSystem)

Return type:

AbstractUnitSystem

Create a unit system from an existing unit system and additional units.

Examples

We can add a new unit definition to an existing unit system:

>>> from unxt.unitsystems import unitsystem
>>> usys = unitsystem("galactic")
>>> unitsystem(usys, "km/s")
LengthTimeMassAngleSpeedUnitSystem(length=Unit("kpc"), time=Unit("Myr"), mass=Unit("solMass"), angle=Unit("rad"), speed=Unit("km / s"))

We can also override the base unit of an existing unit system:

>>> new_usys = unitsystem(usys, "pc")
>>> new_usys
TimeMassAngleLengthUnitSystem(time=Unit("Myr"), mass=Unit("solMass"), angle=Unit("rad"), length=Unit("pc"))
unxt.unitsystems.unitsystem(flag: type[AbstractUSysFlag], *_: Any) → AbstractUnitSystem
Parameters:

usys (AbstractUnitSystem)

Return type:

AbstractUnitSystem

Raise an exception since the flag is abstract.

unxt.unitsystems.unitsystem(flag: type[StandardUSysFlag], *args: Any) → AbstractUnitSystem
Parameters:

usys (AbstractUnitSystem)

Return type:

AbstractUnitSystem

Create a standard unit system using the inputted units.

Examples

>>> from unxt import unitsystem, unitsystems
>>> unitsystem(unitsystems.StandardUSysFlag, "kpc", "Myr", "Msun")
LengthTimeMassUnitSystem(length=Unit("kpc"), time=Unit("Myr"), mass=Unit("solMass"))
unxt.unitsystems.unitsystem(flag: type[DynamicalSimUSysFlag], *args: Any, G: float | int = 1.0) → AbstractUnitSystem
Parameters:

usys (AbstractUnitSystem)

Return type:

AbstractUnitSystem

Make a dynamical unit system.

Examples

>>> from unxt.unitsystems import unitsystem, DynamicalSimUSysFlag

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

usys (AbstractUnitSystem)

Return type:

AbstractUnitSystem

unxt.unitsystems.unitsystem_of(obj: Any, /)#

Return the unit system of an object.

unxt.unitsystems.unitsystem_of(obj: Any, /) → DimensionlessUnitSystem
Parameters:

obj (Any)

Return type:

Any

Return the unit system of the object.

Examples

>>> from unxt.unitsystems import unitsystem_of

>>> unitsystem_of(1)
DimensionlessUnitSystem()
unxt.unitsystems.unitsystem_of(obj: AbstractUnitSystem, /) → AbstractUnitSystem
Parameters:

obj (Any)

Return type:

Any

Return the unit system from the unit system.

Examples

>>> from unxt.unitsystems import galactic, unitsystem_of

>>> unitsystem_of(galactic) is galactic
True
Parameters:

obj (Any)

Return type:

Any

class unxt.unitsystems.AbstractUnitSystem#

Bases: object

Represents a system of units.

This class behaves like a dictionary with keys set by physical types (i.e. “length”, “velocity”, “energy”, etc.). If a unit for a particular physical type is not specified on creation, a composite unit will be created with the base units. See the examples below for some demonstrations.

Examples

If only base units are specified, any physical type specified as a key to this object will be composed out of the base units:

>>> from unxt import unitsystem
>>> usys = unitsystem("m", "s", "kg", "radian")
>>> usys
unitsystem(m, s, kg, rad)

>>> usys["velocity"]
Unit("m / s")

This unit system defines energy:

>>> usys = unitsystem("m", "s", "kg", "radian", "erg")
>>> usys["energy"]
Unit("erg")

This is useful for Galactic dynamics where lengths and times are usually given in terms of kpc and Myr, but velocities are often specified in km/s:

>>> usys = unitsystem("kpc", "Myr", "Msun", "radian", "km / s")
>>> usys["velocity"]
Unit("km / s")

Unit systems can be hashed:

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

And iterated over:

>>> [x for x in usys]
[Unit("kpc"), Unit("Myr"), Unit("solMass"), Unit("rad"), Unit("km / s")]

With length equal to the number of base units

>>> len(usys)
5
property base_dimensions: tuple[PhysicalType, ...]#

Dimensions required for the unit system.

property base_units: tuple[Unit | UnitBase | CompositeUnit, ...]#

List of core units.

class unxt.unitsystems.DimensionlessUnitSystem(dimensionless: Annotated[UnitBase, PhysicalType('dimensionless')] = Unit(dimensionless))#

Bases: SingletonMixin, AbstractUnitSystem

A unit system with only dimensionless units.

This is a singleton class.

Examples

>>> from unxt.unitsystems import DimensionlessUnitSystem
>>> dims1 = DimensionlessUnitSystem()
>>> dims2 = DimensionlessUnitSystem()
>>> dims1 is dims2
True
Parameters:

dimensionless (UnitBase)

dimensionless: Annotated[UnitBase]#

The dimensionless unit.

property base_dimensions: tuple[PhysicalType, ...]#

Dimensions required for the unit system.

property base_units: tuple[Unit | UnitBase | CompositeUnit, ...]#

List of core units.

class unxt.unitsystems.LTMAUnitSystem(length: Annotated[UnitBase, PhysicalType('length')], time: Annotated[UnitBase, PhysicalType('time')], mass: Annotated[UnitBase, PhysicalType('mass')], angle: Annotated[UnitBase, PhysicalType('angle')])#

Bases: AbstractUnitSystem

Length, time, mass, angle unit system.

Parameters:
length: Annotated[UnitBase]#

Units for the length dimension.

time: Annotated[UnitBase]#

Units for the time dimension.

mass: Annotated[UnitBase]#

Units for the mass dimension.

angle: Annotated[UnitBase]#

Units for the angle ‘dimension’.

property base_dimensions: tuple[PhysicalType, ...]#

Dimensions required for the unit system.

property base_units: tuple[Unit | UnitBase | CompositeUnit, ...]#

List of core units.

class unxt.unitsystems.AbstractUSysFlag(*_, **__)#

Bases: object

Abstract class for unit system flags to provide dispatch control.

Unit system flags are used to indicate the type of unit system being defined. They are not intended to be instantiated and are used to provide dispatch control for defining unit systems.

Raises:

ValueError – If an attempt is made to instantiate a unit system flag class.

Parameters:

See also

None

Function to define a unit system. The AbstractUSysFlag can be provided as the first argument to indicate the type of unit system being defined. This is useful for multiple-dispatching to the correct constructor.

Examples

For this example we will use the unxt.unitsystems.StandardUSysFlag, which indicates the standard construction of a unit system directly from the set of base units. Flags like unxt.unitsystems.DynamicalSimUSysFlag can be used to create a unit system where the gravitational constant G is unit-less and units are defined accordingly.

>>> import unxt

Define a unit system with the standard flag:

>>> unxt.unitsystem(unxt.unitsystems.StandardUSysFlag, "m", "kg", "s")
LengthMassTimeUnitSystem(length=Unit("m"), mass=Unit("kg"), time=Unit("s"))
class unxt.unitsystems.StandardUSysFlag(*_, **__)#

Bases: AbstractUSysFlag

Flag to indicate a standard unit system with no additional arguments.

Examples

>>> from unxt.unitsystems import unitsystem, StandardUSysFlag

Define a unit system with the standard flag:

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

Further examples may be found in the unitsystem docs.

Parameters:
class unxt.unitsystems.DynamicalSimUSysFlag(*_, **__)#

Bases: AbstractUSysFlag

Flag to indicate a unit system with optional definition of G.

Examples

>>> from unxt.unitsystems import unitsystem, DynamicalSimUSysFlag

Define a unit system with the dynamical simulation flag:

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

Further examples may be found in the unitsystem docs.

Parameters:
unxt.unitsystems.equivalent(a: AbstractUnitSystem, b: AbstractUnitSystem, /)#

Check if two unit systems are equivalent.

Parameters:
Return type:

bool