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, unless to_value is used if blank string, decomposes

to_value: bool, optional

whether to return .to_value(unit) see astropy.units.Quantity.to_value

equivalencies: list, optional

equivalencies for .to() and .to_value() only used if unit to to_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 apply unit, to_value, equivalencies.

Decomposing then converting wastes time, since .to(unit, equivalencies) internally does conversions. The only use for combining decompose with other quantity_return_ parameters is with

unit=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 in Unit(). 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