Unit Systems (`gala.units`)#

Introduction#

This module contains a class for handling systems of units, and provides a few pre-defined unit systems that are useful for galactic dynamics.

For the examples below, I assume the following imports have already been executed:

>>> import astropy.units as u
>>> import numpy as np
>>> from gala.units import UnitSystem

Unit Systems#

A unit system is defined by a set of base units that specify length, time, mass, and angle units. A UnitSystem object is created by passing in units with (at least) these four required physical types:

>>> usys = UnitSystem(u.cm, u.millisecond, u.degree, u.gram)
>>> usys
<UnitSystem (cm, ms, g, deg)>

Astropy Quantity objects can be decomposed into this unit system using decompose():

>>> a = 15 * u.km/u.s
>>> a.decompose(usys)
<Quantity 1500. cm / ms>

UnitSystem objects can also act as a dictionary to look up a unit for a given physical type. For example, if we want to know what a ‘velocity’ unit is in a given unit system, pass the key 'speed' or 'velocity':

>>> usys['speed']
Unit("cm / ms")

This works for the base unit physical types and for more complex physical types:

>>> usys['length']
Unit("cm")
>>> usys['pressure']
Unit("g / (cm ms2)")

In Astropy version 4.3 and later, units from UnitSystem objects can also be retrieved by passing in Astropy PhysicalType instances as keys, for example:

>>> ptype = u.get_physical_type('length')**2 / u.get_physical_type('time')
>>> usys[ptype]
Unit("cm2 / ms")

Creating unit systems with scaled base units#

It is sometimes useful to construct a unit system with base units that are scaled versions of units. For example, you may want to create a unit system with the base units (10 kpc, 200 Myr, 1000 Msun). To construct a UnitSystem with scaled base units, pass in Quantity objects. For example:

>>> usys = UnitSystem(10 * u.kpc, 200 * u.Myr, 1000 * u.Msun, u.radian)
>>> usys
<UnitSystem (10.0 kpc, 200.0 Myr, 1000.0 solMass, rad)>
>>> q = 15.7 * u.kpc
>>> q.decompose(usys)
<Quantity 1.57 10.0 kpc>

Or, to create a unit system in which G=1, given length and mass units:

>>> from astropy.constants import G
>>> L_unit = 1 * u.kpc
>>> M_unit = 1e6 * u.Msun
>>> T_unit = np.sqrt((L_unit**3) / (G * M_unit))
>>> usys = UnitSystem(L_unit, M_unit, T_unit.to(u.Myr), u.radian)
>>> np.round(usys.get_constant('G'), 5)  
1.0

Custom display units#

It is sometimes useful to have default display units for physical types that are not simple compositions of base units. For example, for kinematics within the Milky Way, a common base unit system consists of (kpc, Myr, Msun), but velocities are often expressed or displayed in km/s. To change the default display unit of a composite unit, specify the preferred unit on creation:

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

For unit systems with specified composite units (e.g., usys2 above), the Astropy decompose() method will fail because it only uses the base units:

>>> q = 150 * u.pc/u.Myr
>>> q.decompose(usys2)
<Quantity 0.15 kpc / Myr>

Because we specified a unit for quantities with a physical type = ‘velocity’, we can instead use the decompose method of the UnitSystem object to retrieve the object in the desired display unit:

>>> usys2.decompose(q)
<Quantity 146.66883325 km / s>

API#

gala.units Module#

Classes#

`UnitSystem`(units, *args)	Represents a system of units.
`DimensionlessUnitSystem`()	Represents a system of units.

Unit Systems (gala.units)#