unitconvert

Functions and attributes

atomman.unitconvert.build_unit()

Saves numericalunits attributes to global dictionary unit so the values can be retrieved by their string names.

atomman.unitconvert.error_unit(term: dict) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Reads numerical error from dictionary containing ‘error’ and ‘unit’ keys.

Parameters:

term (dict) – Dictionary containing ‘error’ and ‘unit’ keys.

Returns:

The result of calling set_in_units() by passing the dictionary keys ‘error’ and ‘unit’ as parameters.

Return type:

float or numpy.ndarray

atomman.unitconvert.get_in_units(value: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], units: str) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Convert value from working units to specified units.

Parameters:

  • value (array-like object) – A numerical value or list/array of values.

  • units (str) – The units to convert value to (from working units).

Returns:

The given value converted to the specified units from working units.

Return type:

float or numpy.ndarray

atomman.unitconvert.model(value: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], units: str | None = None, error: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None) → DataModelDict

Generates DataModelDict representation of data.

Parameters:

  • value (array-like object) – A numerical value or list/array of values.

  • units (str, optional) – The units to convert value to (from working units).

  • error (array-like object or None, optional) – A value error to include. If given, must be the same size/shape as value.

Returns:

Model representation of the value(s).

Return type:

DataModelDict

atomman.unitconvert.parse(units: str | None) → float

Convert units as strings (or None) into scaling numbers. This function allows for complex unit definitions with operators:

  • ‘()’ for defining order of operations

  • ‘*’ for multiplication.

  • ‘/’ for division.

  • ‘^’ for powers.

Parameters:

units (str or None) – String consisting of defined unit names, operators, and numerical values to interpret.

Returns:

The scaling factor for converting numbers in the given units to working units. If units is None or == ‘scaled’, then this value is 1.0.

Return type:

float

atomman.unitconvert.reset_units(seed: int | None = None, **kwargs)

Extends numericalunits.reset_units() by allowing for working units to be defined. If no working units are specified, then random working units are used just like the default numericalunits behavior. Otherwise, use the specified working units and SI.

Parameters:

  • seed (int, optional) – random number seed to use in generating random working units. seed=’SI’ will use SI units. Cannot be given with the other parameters.

  • length (str, optional) – Unit of length to use for the working units.

  • mass (str, optional) – Unit of mass to use for the working units.

  • time (str, optional) – Unit of time to use for the working units.

  • energy (str, optional) – Unit of energy to use for the working units.

  • charge (str, optional) – Unit of charge to use for the working units.

Raises:

ValueError – If seed is given with any other parameters, or if more than four of the working unit parameters are given.

atomman.unitconvert.set_in_units(value: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], units: str) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Convert value from specified units to working units.

Parameters:

  • value (array-like object) – A numerical value or list/array of values.

  • units (str) – The units that value is in.

Returns:

The given value converted from the specified units to working units.

Return type:

float or numpy.ndarray

atomman.unitconvert.set_literal(term: str) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Convert string ‘value unit’ to numbers in working units.

Parameters:

term (str) – String containing value and associated unit. If unit is not given, then the value is converted to a float and assumed to be in working units.

Returns:

The numerical value of term in working units.

Return type:

float or numpy.ndarray

Raises:

ValueError – If no valid float value can be parsed.

atomman.unitconvert.value_unit(term: dict) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Reads numerical value from dictionary containing ‘value’ and ‘unit’ keys.

Parameters:

term (dict) – Dictionary containing ‘value’ and ‘unit’ keys.

Returns:

The result of calling set_in_units() by passing the dictionary keys ‘value’ and ‘unit’ as parameters.

Return type:

float or numpy.ndarray