StructuredUnit

class astropy.units.StructuredUnit(units, names=None)

Bases: object

Container for units for a structured Quantity.

Parameters:

unitsastropy:unit-like, tuple of astropy:unit-like, or StructuredUnit

Tuples can be nested. If a StructuredUnit is passed in, it will be returned unchanged unless different names are requested.

namestuple of str, tuple or list; dtype; or StructuredUnit, optional

Field names for the units, possibly nested. Can be inferred from a structured dtype or another StructuredUnit. For nested tuples, by default the name of the upper entry will be the concatenation of the names of the lower levels. One can pass in a list with the upper-level name and a tuple of lower-level names to avoid this. For tuples, not all levels have to be given; for any level not passed in, default field names of ‘f0’, ‘f1’, etc., will be used.

Notes

It is recommended to initialize the class indirectly, using Unit. E.g., u.Unit('AU,AU/day').

When combined with a structured array to produce a structured Quantity, array field names will take precedence. Generally, passing in names is needed only if the unit is used unattached to a Quantity and one needs to access its fields.

Examples

Various ways to initialize a StructuredUnit:

>>> import astropy.units as u
>>> su = u.Unit('(AU,AU/day),yr')
>>> su
Unit("((AU, AU / d), yr)")
>>> su.field_names
(['f0', ('f0', 'f1')], 'f1')
>>> su['f1']
Unit("yr")
>>> su2 = u.StructuredUnit(((u.AU, u.AU/u.day), u.yr), names=(('p', 'v'), 't'))
>>> su2 == su
True
>>> su2.field_names
(['pv', ('p', 'v')], 't')
>>> su3 = u.StructuredUnit((su2['pv'], u.day), names=(['p_v', ('p', 'v')], 't'))
>>> su3.field_names
(['p_v', ('p', 'v')], 't')
>>> su3.keys()
('p_v', 't')
>>> su3.values()
(Unit("(AU, AU / d)"), Unit("d"))

Structured units share most methods with regular units:

>>> su.physical_type
((PhysicalType('length'), PhysicalType({'speed', 'velocity'})), PhysicalType('time'))
>>> su.si
Unit("((1.49598e+11 m, 1.73146e+06 m / s), 3.15576e+07 s)")

Attributes Summary

cgs	The StructuredUnit instance in cgs units.
field_names	Possibly nested tuple of the field names of the parts.
physical_type	Physical types of all the fields.
si	The StructuredUnit instance in SI units.

Methods Summary

decompose([bases])	The StructuredUnit composed of only irreducible units.
is_equivalent(other[, equivalencies])	True if all fields are equivalent to the other's fields.
items()
keys()
to(other[, value, equivalencies])	Return values converted to the specified unit.
to_string([format])	Output the unit in the given format as a string.
values()

Attributes Documentation

cgs

The StructuredUnit instance in cgs units.

field_names

Possibly nested tuple of the field names of the parts.

physical_type

Physical types of all the fields.

si

The StructuredUnit instance in SI units.

Methods Documentation

decompose(bases={})

The StructuredUnit 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:

StructuredUnit

With the unit for each field containing only irreducible units.

is_equivalent(other, equivalencies=[])

True if all fields are equivalent to the other’s fields.

Parameters:

otherStructuredUnit

The structured unit to compare with, or what can initialize one.

equivalencieslist of tuple, optional

A list of equivalence pairs to try if the units are not directly convertible. See Equivalencies. The list will be applied to all fields.

Returns:

bool

items()

keys()

to(other, value=<no value>, equivalencies=[])

Return values converted to the specified unit.

Parameters:

otherStructuredUnit

The unit to convert to. If necessary, will be converted to a StructuredUnit using the dtype of value.

valuearray_like, optional

Value(s) in the current unit to be converted to the specified unit. If a sequence, the first element must have entries of the correct type to represent all elements (i.e., not have, e.g., a float where other elements have complex). If not given, assumed to have 1. in all fields.

equivalencieslist of tuple, 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).

Raises:

UnitsError

If units are inconsistent

to_string(format='generic')

Output the unit in the given format as a string.

Units are separated by commas.

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.

Notes

Structured units can be written to all formats, but can be re-read only with ‘generic’.

values()