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 Return the physical type on 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. 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

Return the physical type on the unit.

Examples

>>> from astropy import units as u
>>> print(u.m.physical_type)
length

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 equivalence pairs, optional

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 units to compose to, 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 object

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 equivalence pairs, optional

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 units to search in, 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 object or string 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 equivalence pairs, optional

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
otherunit object or string

The unit to convert to.

valuescalar int or float, or sequence convertible to array, optional

Value(s) in the current unit to be converted to the specified unit. If not provided, defaults to 1.0

equivalencieslist of equivalence pairs, optional

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'>)[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.

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.