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
Returns the alias (long) names for this unit.
Return the bases of the unit.
Returns a copy of the current
Unit
instance with CGS units.Returns the canonical (short) name associated with this unit.
Returns all of the names associated with this unit.
Physical type(s) dimensionally compatible with the unit.
Return the powers of the unit.
Return the scale of the unit.
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
.get_converter
(other[, equivalencies])Create a function that converts values from this unit to another.
in_units
(other[, value, equivalencies])Alias for
to
for backward compatibility with pynbody.is_equivalent
(other[, equivalencies])Returns
True
if this unit is equivalent toother
.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.
- 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.
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:
- equivalencies
list
oftuple
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
. UseNone
to turn off all equivalencies.- units
set
ofUnit
, 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_depth
int
, 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 isTrue
if a sequence is passed in tounits
,False
otherwise.
- equivalencies
- Returns:
- units
list
ofCompositeUnit
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.
- units
- 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.
- basessequence of
- Returns:
- unit
CompositeUnit
New object containing only irreducible unit objects.
- unit
- 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:
- equivalencies
list
oftuple
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
)- units
set
ofUnit
, 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 isFalse
.
- equivalencies
- Returns:
- get_converter(other, equivalencies=[])[source]#
Create a function that converts values from this unit to another.
- Parameters:
- otherastropy:unit-like
The unit to convert to.
- equivalencies
list
oftuple
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
. UseNone
to turn off all equivalencies.
- Returns:
- func
callable()
A callable that takes an array-like argument and returns it converted from units of self to units of other.
- func
- Raises:
UnitsError
If the units cannot be converted to each other.
Notes
This method is used internally in
Quantity
to convert to different units. Note that the function returned takes and returns values, not quantities.
- 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 toother
.- Parameters:
- other
Unit
,str
, ortuple
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.
- equivalencies
list
oftuple
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
. UseNone
to turn off all equivalencies.
- other
- Returns:
- to(other, value=1.0, equivalencies=[])[source]#
Return the converted values in the specified unit.
- Parameters:
- otherastropy:unit-like
The unit to convert to.
- value
int
,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
- equivalencies
list
oftuple
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
. UseNone
to turn off all equivalencies.
- Returns:
- 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:
- format
astropy.units.format.Base
subclass orstr
The name of a format or a formatter class. 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:
- format
- Raises:
TypeError
If
format
is of the wrong type.ValueError
If
format
orfraction
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
andastropy.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:
- units
list
ofCompositeUnit
The list is ranked so that units containing only the base units of that system will appear first.
- units