Skip to main content
`Ctrl`+`K`

# StructuredUnit

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

  Bases: `object`

  Container for units for a structured Quantity.

  Parameters:
    units astropy:unit-like, `python: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.

    names `python:tuple` of `python:str`, `python: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
      astropy.units.structured.Structure((astropy.units.structured.Structure((PhysicalType('length'), PhysicalType({'speed', 'velocity'})), dtype=[('f0', 'O'), ('f1', 'O')]), PhysicalType('time')), dtype=[('f0', 'O'), ('f1', 'O')])
      >>> 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.
  `get_converter`(other[, equivalencies]) | Create a function that converts values from this unit to another.
  `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:
      bases python: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 `UnitsError` if it’s not possible to do so.

    Returns:
      `StructuredUnit`

        With the unit for each field containing only irreducible units.

  get_converter(other, equivalencies=[])

    Create a function that converts values from this unit to another.

    Parameters:
      other astropy:unit-like

        The unit to convert to.

      equivalencies `python:list` of `python:tuple`

        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:
      func `python:callable()`

        A callable that takes an array-like argument and returns it converted from units of self to units of other.

    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.

  is_equivalent(other, equivalencies=[])

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

    Parameters:
      other `StructuredUnit`

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

      equivalencies `python:list` of `python: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:
      other `StructuredUnit`

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

      value numpy:array_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.

      equivalencies `python:list` of `python: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:
      values scalar 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:
      format `astropy.units.format.Base` subclass or `python:str`

        The name of a format or a formatter class. 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()