quantity_return¶
- astronat.units.quantity_return_(res: Any, unit: Union[None, utilipy.utils.typing.UnitableType] = None, to_value: bool = False, equivalencies: list = [], decompose: Union[bool, Sequence] = False)[source]¶
Control function return of
Quantity
.- Parameters
- res: :class:`~astropy.units.Quantity`, optional
the result unit:
Unit
, optional sets the unit for the returned value. if None, returns value unchanged, unlessto_value
is used if blank string, decomposes- to_value: bool, optional
whether to return
.to_value(unit)
seeastropy.units.Quantity.to_value
- equivalencies: list, optional
equivalencies for
.to()
and.to_value()
only used ifunit
toto_value
are not None/False- decompose: bool or list, optional
Unit decomposition. Default, False.
bool: True, False for decomposing.
list: bases for
.decompose(bases=[])
. Will first decompose, then applyunit
,to_value
,equivalencies
.
Decomposing then converting wastes time, since
.to(unit, equivalencies)
internally does conversions. The only use for combiningdecompose
with otherquantity_return_
parameters is withunit=None, to_value=True, equivalencies=[]
since this will decompose to desired bases then return the value in those bases
Note
experimental feature: for things which are not (
Unit
), tries wrapping inUnit()
. This would normally return an error, but now allows for conversions such as:>>> x = 10 * u.km * u.s >>> bases = [u.Unit(2 * u.km), u.s] >>> x.decompose(bases=bases) <Quantity 5.0 2 km s>
- Returns
- res:
function output, converted / decomposed / evaluated to desired units
- Raises
ValueError
if unit not astropy compatible
UnitConversionError
if conversion not legit
Examples
How to apply in a function directly
>>> def example_function(x, **kw): ... return quantity_return_(x, unit=kw.get('unit', None), ... to_value=kw.get('to_value', False), ... equivalencies=kw.get('equivalencies', []), ... decompose=kw.get('decompose', [])) >>> example_function(10*u.km, unit=u.m, to_value=True) 10000.0