UnitSystem

class gala.units.UnitSystem(units, *args)

Bases: object

Represents a system of units.

At minimum, this consists of a set of length, time, mass, and angle units, but may also contain preferred representations for composite units. For example, the base unit system could be {kpc, Myr, Msun, radian}, but you can also specify a preferred velocity unit, such as km/s.

This class behaves like a dictionary with keys set by physical types. 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.

Parameters:

unitsUnit or astropy.units.Quantity

The first unit that defines the unit system (e.g., length).

*argsUnit or Quantity

Additional units that define the unit system (e.g., time, mass, angle, and any preferred composite units). At minimum, you must specify length, time, mass, and angle units, in any order.

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:

>>> usys = UnitSystem(u.m, u.s, u.kg, u.radian)
>>> usys['energy']
Unit("kg m2 / s2")

However, custom representations for composite units can also be specified when initializing:

>>> usys = UnitSystem(u.m, u.s, u.kg, u.radian, u.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 given in km/s:

>>> usys = UnitSystem(u.kpc, u.Myr, u.Msun, u.radian, u.km/u.s)
>>> usys['velocity']
Unit("km / s")

Methods Summary

decompose(q)	A thin wrapper around astropy.units.Quantity.decompose() that knows how to handle Quantities with physical types with non-default representations.
from_string(name)	Create a UnitSystem instance from a name.
get_constant(name)	Retrieve a constant with specified name in this unit system.
to_dict()	Return a dictionary representation of the unit system with keys set by the physical types and values set by the unit objects.

Methods Documentation

decompose(q)

A thin wrapper around astropy.units.Quantity.decompose() that knows how to handle Quantities with physical types with non-default representations.

Parameters:

qQuantity

An instance of an astropy Quantity object.

Returns:

qQuantity

A new quantity, decomposed to be represented in this unit system.

classmethod from_string(name: str) → UnitSystem

Create a UnitSystem instance from a name.

Parameters:

namestr

The name of the unit system. Examples of valid names are ‘galactic’, ‘solarsystem’, and ‘dimensionless’.

Returns:

usysUnitSystem

The corresponding unit system instance.

Examples

Create the galactic unit system from its name:

>>> usys = UnitSystem.from_string('galactic')
>>> usys['length']
Unit("kpc")

get_constant(name)

Retrieve a constant with specified name in this unit system.

Parameters:

namestr

The name of the constant, e.g., G.

Returns:

constfloat

The value of the constant represented in this unit system.

Examples

We will get the value of the speed of light in a custom unit system:

>>> usys = UnitSystem(u.kpc, u.Myr, u.Msun, u.radian)
>>> usys.get_constant('c')
306.6013937855506

to_dict()

Return a dictionary representation of the unit system with keys set by the physical types and values set by the unit objects.