UnitBase

class astropy.units.core.UnitBase [edit on github][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

physical_type Return the physical type on the unit.

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 the specified unit.
get_converter(other[, equivalencies]) Return the conversion function to convert values from self to the specified unit.
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.
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

physical_type[source]

Return the physical type on the unit.

Examples

>>> u.m.physical_type
'length'

Methods Documentation

compose(equivalencies=[], units=None, max_depth=2, include_prefix_units=False) [edit on github][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 of equivalence pairs, optional

A list of equivalence pairs to also list. See Equivalencies.

units : set 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_depth : int, optional

The maximum recursion depth to use when composing into composite units.

include_prefix_units : bool, optional

When True, include prefixed units in the result. Default is False.

Returns :

units : list 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=set([])) [edit on github][source]

Return a unit object composed of only irreducible units.

Parameters :

bases : sequence 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 UnitsException if it’s not possible to do so.

Returns :

unit : CompositeUnit object

New object containing only irreducible unit objects.

find_equivalent_units(equivalencies=[], units=None, include_prefix_units=False) [edit on github][source]

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

Parameters :

u : Unit instance or string

The Unit to find similar units to.

equivalencies : list of equivalence pairs, optional

A list of equivalence pairs to also list. See Equivalencies.

units : set 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_units : bool, optional

When True, include prefixed units in the result. Default is False.

Returns :

units : list 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.

get_converter(other, equivalencies=[]) [edit on github][source]

Return the conversion function to convert values from self to the specified unit.

Parameters :

other : unit object or string

The unit to convert to.

equivalencies : list of equivalence pairs, optional

A list of equivalence pairs to try if the units are not directly convertible. See Equivalencies.

Returns :

func : callable

A callable that normally expects a single argument that is a scalar value or an array of values (or anything that may be converted to an array).

Raises :

UnitsException :

If units are inconsistent

in_units(other, value=1.0, equivalencies=[]) [edit on github][source]

Alias for to for backward compatibility with pynbody.

is_equivalent(other, equivalencies=[]) [edit on github][source]

Returns True if this unit is equivalent to other.

Parameters :

other : unit object or string

The unit to convert to.

equivalencies : list of equivalence pairs, optional

A list of equivalence pairs to try if the units are not directly convertible. See Equivalencies.

Returns :

bool :

to(other, value=1.0, equivalencies=[]) [edit on github][source]

Return the converted values in the specified unit.

Parameters :

other : unit object or string

The unit to convert to.

value : scalar int or float, or sequence that can be converted to array, optional

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

equivalencies : list of equivalence pairs, optional

A list of equivalence pairs to try if the units are not directly convertible. See Equivalencies.

Returns :

values : scalar or array

Converted value(s). Input value sequences are returned as numpy arrays.

Raises :

UnitException :

If units are inconsistent

to_string(format=u'generic') [edit on github][source]

Output the unit in the given format as a string.

Parameters :

format : astropy.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) [edit on github][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 :

system : module

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 :

units : list of CompositeUnit

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

Page Contents