Skip to main content
`Ctrl`+`K`

# def_unit

astropy.units.def_unit(s, represents=None, doc=None, format=None, prefixes=False, exclude_prefixes=(), namespace=None)

  Define a new unit.

  This function differs from creating units directly with `Unit` or `IrreducibleUnit` because it can also automatically generate prefixed units in the given namespace.

  Parameters:
    s `python:str` or `python:list` of `python:str`

      The name of the unit. If a list, the first element is the canonical (short) name, and the rest of the elements are aliases.

    represents astropy:unit-like, optional

      The unit that this named unit represents. If not provided, a new `IrreducibleUnit` is created.

    doc `python:str`, optional

      A docstring describing the unit.

    format `python:dict`, optional

      A mapping to format-specific representations of this unit. For example, for the `Ohm` unit, it might be nice to have it displayed as `\Omega` by the `latex` formatter. In that case, `format` argument should be set to:

          {'latex': r'\Omega'}

    prefixes bool or python:iterable of `UnitPrefix`, optional

      When `True`, generate all of the SI prefixed versions of the unit as well. For example, for a given unit `m`, will generate `mm`, `cm`, `km`, etc. If only a few prefixed versions should be created then an iterable of `UnitPrefix` instances can be specified instead. Default is `False`, which means no prefixed versions will be generated.

      This function always returns the base unit object, even if multiple scaled versions of the unit were created.

    exclude_prefixes `Collection` of `python:str`, optional

      If any of the SI prefixes need to be excluded, they may be listed here. For example, when defining the prefixes for `a`, `exclude_prefixes` should be set to `["P"]` so that `Pa` would still refer to the pascal.

      If a bare `str` is used then the prefixes that will be excluded are the substrings of the `str`, not just its individual characters.

    namespace `python:dict`, optional

      When provided, inject the unit (and all of its aliases and prefixes), into the given namespace dictionary.

  Returns:
    unit `NamedUnit`

      The newly-defined unit, or a matching unit that was already defined.

  Raises:
    `ValueError`

      If `represents` cannot be parsed as a unit, e.g., because it is a malformed string or a |Quantity| that is not a scalar.