Units

Units Overview

Celest provides the ability to handle different units of measurement and is accomplished through the use of units an quantities. The following sections describe the different units available, how to use them, and how to convert between them via the Quantity class.

Handling Units

Initialized units are accessed from the units module which can be imported by the following:

from celest import units as u

Primary Units

Primary units can then be accessed using a dot notation.

u.m  # Meter measure.
u.s  # Second measure.
u.deg # Degree measure.

The following table lists all primary units, their code call sign, and their measure type.

Available Units

Unit

Code Label

Type

Millimeter

u.mm

Length

Centimeter

u.cm

Length

Meter

u.m

Length

Kilometer

u.km

Length

Inch

u.inch

Length

Feet

u.ft

Length

Yard

u.yd

Length

Mile

u.mi

Length

Second

u.s

Time

Minute

u.min

Time

Hour

u.hr

Time

Day

u.dy

Time

JD2000

u.jd2000

Date

Degree

u.deg

Angle

Radian

u.rad

Angle

Seconds of Arc

u.arcsec

Angle

Minutes of Arc

u.arcmin

Angle

Hour Angle

u.hourangle

Angle

Primary units are instances of the Unit class and can be used to create new units.

class Unit(short_name, long_name, namespace=None, base_units=None)

Bases: NamedUnit, BaseUnit

The Unit class is the main unit object that is associated with a namespace and has a name.

Parameters

  • short_name (str) –

    The short name of the unit.

    The short name of the unit is used as its namespace identifier.

  • long_name (str) – The long name of the unit.

  • namespace (dict, optional) – The namespace to insert the unit into.

  • base_units (BaseUnit, optional) –

    The base units of the unit. That is, how the new unit relates to a base SI unit.

    For example, a kilometer unit has the base units of 1000 * u.m.

is_unity()

Return True if the unit is unity.

Return type

bool

property bases: list

Return the list of bases of the unit.

property dimension: str

Return the dimension string of the unit.

property long_name: str

Return the long name of the unit.

property powers: list

Return the list of powers of the unit.

property scale: float

Return the scale of the unit.

property short_name: str

Return the short name of the unit.

Compound Units

Primary units can be combined with others through multiplication or division to create compound units.

velocity_unit = u.m / u.s  # Meter per second.
acceleration_unit = u.m / u.s ^ 2  # Meter per second squared.

Compound units are instances of the CompoundUnit class and can be used to create new units.

class CompoundUnit(scale, bases, powers)

Bases: BaseUnit

The CompoundUnit class handles more complicated units that are combinations of multiple Unit objects.

Parameters

  • scale (float) – The scale of the unit.

  • bases (list) – The list of bases of the unit.

  • powers (list) – The list of powers of the unit.

is_unity()

Return True if the unit is unity.

Return type

bool

property bases: list

Return the list of bases of the unit.

property dimension: str

Return the dimension string of the unit.

property powers: list

Return the list of powers of the unit.

property scale: float

Return the scale of the unit.

Passing Units into Celest

Units are typically passed into Celest’s class constructors, methods, and functions as a parameter to specify the data measure. Internally, the data and units get stored together in a Quantity object that may be returned from a class property, method, or function. The Quantity object deals with the conversions between units and is discussed the Measures with Units section.

Measures with Units

To allow for unit conversions, Celest uses the Quantity class to store data and units together. This class is typically initialized internally by a class constructor, method, or function and returned to users. The Quantity class documentation follows.

class Quantity(data, unit)

Bases: object

Data with a unit.

The Quantity class holds both data and a unit together to allow for easy unit conversions.

Parameters

  • data (Any) –

    The data to be stored in the Quantity object.

    To allow for unit conversions, the data object must have the multiplication operations defined.

  • unit (Unit, CompoundUnit) – The unit associated with the data.

convert_to(new_unit)

Return a new Quantity object with the new unit.

Parameters

new_unit (Unit, CompoundUnit) – New unit with the same dimension as the current unit.

Returns

A new Quantity object with the new unit.

Return type

Quantity

Examples

Initialize the Quantity object:

>>> quantity_in_meters = Quantity(5, u.m)

Convert to kilometers:

>>> quantity_in_kilometers = quantity_in_meters.convert_to(u.km)
to(new_unit)

Return the Quantity data in the new unit.

Parameters

new_unit (Unit, CompoundUnit) – New unit with the same dimension as the current unit.

Returns

The Quantity data in the new unit.

Return type

Any

Examples

>>> quantity_in_meters = Quantity(5, u.m)
>>> quantity_in_meters.to(u.km)
0.005
property data: Any

Return the data of the quantity.

property dimension: str

Return the dimension string of the quantity.

property unit: Union[Unit, CompoundUnit]

Return the unit of the quantity.