UnitBase#

class astropy.units.UnitBase[source]#

Bases: object

Abstract base class for units.

Most of the arithmetic operations on units are defined in this base class.

Should not be instantiated by users directly.

Attributes Summary

`aliases`	Returns the alias (long) names for this unit.
`bases`	Return the bases of the unit.
`cgs`	Returns a copy of the current `Unit` instance with CGS units.
`name`	Returns the canonical (short) name associated with this unit.
`names`	Returns all of the names associated with this unit.
`physical_type`	Physical type(s) dimensionally compatible with the unit.
`powers`	Return the powers of the unit.
`scale`	Return the scale of the unit.
`si`	Returns a copy of the current `Unit` instance in SI units.

Methods Summary

`compose`([equivalencies, units, max_depth, ...])	Return the simplest possible composite unit(s) that represent the given unit.
`decompose`([bases])	Return a unit object composed of only irreducible units.
`find_equivalent_units`([equivalencies, ...])	Return a list of all the units that are the same type as `self`.
`in_units`(other[, value, equivalencies])	Alias for `to` for backward compatibility with pynbody.
`is_equivalent`(other[, equivalencies])	Returns `True` if this unit is equivalent to `other`.
`is_unity`()	Returns `True` if the unit is unscaled and dimensionless.
`to`(other[, value, equivalencies])	Return the converted values in the specified unit.
`to_string`([format])	Output the unit in the given format as a string.
`to_system`(system)	Converts this unit into ones belonging to the given system.

Attributes Documentation

aliases#: Returns the alias (long) names for this unit.

bases#: Return the bases of the unit.

cgs#: Returns a copy of the current Unit instance with CGS units.

name#: Returns the canonical (short) name associated with this unit.

names#: Returns all of the names associated with this unit.

physical_type#

Physical type(s) dimensionally compatible with the unit.

Returns:

PhysicalType: A representation of the physical type(s) of a unit.

Examples

>>> from astropy import units as u
>>> u.m.physical_type
PhysicalType('length')
>>> (u.m ** 2 / u.s).physical_type
PhysicalType({'diffusivity', 'kinematic viscosity'})

Physical types can be compared to other physical types (recommended in packages) or to strings.

>>> area = (u.m ** 2).physical_type
>>> area == u.m.physical_type ** 2
True
>>> area == "area"
True

PhysicalType objects can be used for dimensional analysis.

>>> number_density = u.m.physical_type ** -3
>>> velocity = (u.m / u.s).physical_type
>>> number_density * velocity
PhysicalType('particle flux')

powers#: Return the powers of the unit.

scale#: Return the scale of the unit.

si#: Returns a copy of the current Unit instance in SI units.

Methods Documentation

compose(equivalencies=[], units=None, max_depth=2, include_prefix_units=None)[source]#

Return the simplest possible composite unit(s) that represent the given unit. Since there may be multiple equally simple compositions of the unit, a list of units is always returned.

Parameters:

equivalencieslist of tuple: A list of equivalence pairs to also list. See Equivalencies. This list is in addition to possible global defaults set by, e.g., set_enabled_equivalencies. Use None to turn off all equivalencies.
unitsset of Unit, optional: If not provided, any known units may be used to compose into. Otherwise, units is a dict, module or sequence containing the units to compose into.
max_depthint, optional: The maximum recursion depth to use when composing into composite units.
include_prefix_unitsbool, optional: When True, include prefixed units in the result. Default is True if a sequence is passed in to units, False otherwise.

Returns:

unitslist of CompositeUnit: A list of candidate compositions. These will all be equally simple, but it may not be possible to automatically determine which of the candidates are better.

decompose(bases={})[source]#

Return a unit object composed of only irreducible units.

Parameters:

basessequence of UnitBase, optional: The bases to decompose into. When not provided, decomposes down to any irreducible units. When provided, the decomposed result will only contain the given units. This will raises a UnitsError if it’s not possible to do so.

Returns:

unitCompositeUnit: New object containing only irreducible unit objects.

find_equivalent_units(equivalencies=[], units=None, include_prefix_units=False)[source]#

Return a list of all the units that are the same type as self.

Parameters:

equivalencieslist of tuple: A list of equivalence pairs to also list. See Equivalencies. Any list given, including an empty one, supersedes global defaults that may be in effect (as set by set_enabled_equivalencies)
unitsset of Unit, optional: If not provided, all defined units will be searched for equivalencies. Otherwise, may be a dict, module or sequence containing the units to search for equivalencies.
include_prefix_unitsbool, optional: When True, include prefixed units in the result. Default is False.

Returns:

unitslist of UnitBase: A list of unit objects that match u. A subclass of list (EquivalentUnitsList) is returned that pretty-prints the list of units when output.

in_units(other, value=1.0, equivalencies=[])[source]#: Alias for to for backward compatibility with pynbody.

is_equivalent(other, equivalencies=[])[source]#

Returns True if this unit is equivalent to other.

Parameters:

otherUnit, str, or tuple: The unit to convert to. If a tuple of units is specified, this method returns true if the unit matches any of those in the tuple.
equivalencieslist of tuple: A list of equivalence pairs to try if the units are not directly convertible. See Equivalencies. This list is in addition to possible global defaults set by, e.g., set_enabled_equivalencies. Use None to turn off all equivalencies.

Returns:

bool

is_unity()[source]#: Returns True if the unit is unscaled and dimensionless.

to(other, value=1.0, equivalencies=[])[source]#

Return the converted values in the specified unit.

Parameters:

otherastropy:unit-like: The unit to convert to.
valueint, float, or scalar array_like, optional: Value(s) in the current unit to be converted to the specified unit. If not provided, defaults to 1.0
equivalencieslist of tuple: A list of equivalence pairs to try if the units are not directly convertible. See Equivalencies. This list is in addition to possible global defaults set by, e.g., set_enabled_equivalencies. Use None to turn off all equivalencies.

Returns:

valuesscalar or array: Converted value(s). Input value sequences are returned as numpy arrays.

Raises:

UnitsError: If units are inconsistent

to_string(format=<class 'astropy.units.format.generic.Generic'>, **kwargs)[source]#

Output the unit in the given format as a string.

Parameters:

formatastropy.units.format.Base instance or str

The name of a format or a formatter object. If not provided, defaults to the generic format.

**kwargs

Further options forwarded to the formatter. Currently recognized is fraction, which can take the following values:

False : display unit bases with negative powers as they are;
‘inline’ or True : use a single-line fraction;
‘multiline’ : use a multiline fraction (available for the ‘latex’, ‘console’ and ‘unicode’ formats only).

Raises:

TypeError: If format is of the wrong type.
ValueError: If format or fraction are not recognized.

Examples

>>> import astropy.units as u
>>> kms = u.Unit('km / s')
>>> kms.to_string()  # Generic uses fraction='inline' by default
'km / s'
>>> kms.to_string('latex')  # Latex uses fraction='multiline' by default
'$\\mathrm{\\frac{km}{s}}$'
>>> print(kms.to_string('unicode', fraction=False))
km s⁻¹
>>> print(kms.to_string('unicode', fraction='inline'))
km / s
>>> print(kms.to_string('unicode', fraction='multiline'))
km
──
s

to_system(system)[source]#

Converts this unit into ones belonging to the given system. Since more than one result may be possible, a list is always returned.

Parameters:

systemmodule

The module that defines the unit system. Commonly used ones include astropy.units.si and astropy.units.cgs.

To use your own module it must contain unit objects and a sequence member named bases containing the base units of the system.

Returns:

unitslist of CompositeUnit: The list is ranked so that units containing only the base units of that system will appear first.