shnitsel.units.conversion#

Attributes#

convert_energy

convert_force

convert_dipole

convert_length

convert_time

convert_nacs

convert_socs

convert_charge

convert_velocity

_CONVERTERS

Classes#

Converter

Implements a generic Callable object to convert DataArrays between different units.

Functions#

convert_all_units_to_shnitsel_defaults(data)

Helper function to convert all variables and coordinates with units in the dataset to

convert_to_target_units(data, unit_map)

Helper function to convert units of variables and coordinates on a dataset to

convert_datarray_with_unitdim_to_shnitsel_defaults(data)

Helper function to convert a data array to default values for

convert_datarray_with_unitdim(data[, target_unit])

Helper function to convert a dataarray with a unit dimension to

Module Contents#

class Converter(quantity_name, conversions)#

Implements a generic Callable object to convert DataArrays between different units.

See documentation of the __call__ method for details on the implementation of the conversion.

Parameters:
__name__ = 'convert_Uninferable'#
quantity_name#
conversions#
case_sensitive_mapping#
targets#
__call__(da, to, convert_from=None)#

Function to convert an xr.DataArray between two different units.

The function needs to be provided with a target unit to as well as with either an attribute units of the input data array or by setting the input unit convert_from. A new datarray with converted units will be returned, if successful. The resulting array will have the new unit set as its units attribute and if no prior conversion has happened, the previous unit will be set to the original_units attribute.

Parameters:

  • da (xr.DataArray) – The input DataArray whose data should be converted

  • to (str) – The unit to which the data should be converted

  • convert_from (str | None, optional) – The Unit from which conversion should be started if da does not have a units attribute. Defaults to None.

Raises:

  • KeyError – Raised if the convert_from parameter is not set and the da input has no units attribute set.

  • ValueError – Raised if the target unit to is not known in the conversions dictionary.

  • ValueError – Raised if the original unit convert_from or da.attr[‘units’] is not known in the conversions dictionary.

Returns:

The array containing the unit-converted data out of da with a new units and potentially original_units attribute set.

Return type:

xr.DataArray

convert_value(value, convert_from, to)#
Parameters:
Return type:

float

convert_energy#
convert_force#
convert_dipole#
convert_length#
convert_time#
convert_nacs#
convert_socs#
convert_charge#
convert_velocity#
convert_all_units_to_shnitsel_defaults(data)#

Helper function to convert all variables and coordinates with units in the dataset to shnitsel defaults.

Parameters:

data (xr.Dataset) – The dataset to convert to defaults.

Returns:

The converted dataset.

Return type:

xr.Dataset

Raises:

ValueError – If conversion is performed on a multi-index, an error may occur if the index does not support the replacement of its levels.

convert_to_target_units(data, unit_map)#

Helper function to convert units of variables and coordinates on a dataset to target units.

If no target units are specified, will convert to the units set as default by shnitsel tools.

Parameters:

  • data (xr.Dataset) – The dataset to perform the conversion on.

  • units (str | Mapping[str, str] | None) – Either a unit to convert all variables to or a mapping between variables that should be converted and their target unit. Set a target unit of None to convert to shnitsel default.

  • unit_map (str | Mapping[str, str | None] | None)

Returns:

The resulting dataset after conversion.

Return type:

xr.Dataset

Raises:

  • ValueError – If conversion of a multi-index level fails.

  • ValueError – If a global target unit could not be applied to all arrays in the Dataset.

_CONVERTERS: Dict[str, Callable[[xarray.DataArray, str], xarray.DataArray]]#
convert_datarray_with_unitdim_to_shnitsel_defaults(data)#

Helper function to convert a data array to default values for shnitsel units.

Parameters:

data (xr.DataArray) – The array to convert

Returns:

The converted or untouched array if no conversion was necessary

Return type:

xr.DataArray

convert_datarray_with_unitdim(data, target_unit=None)#

Helper function to convert a dataarray with a unit dimension to either a target unit or a shnitsel default unit.

Parameters:

  • data (xr.DataArray) – The array to convert

  • target_unit (str | None, optional) – The target unit, by default None which applies shnitsel default units

Returns:

The converted or untouched array if no conversion was necessary

Return type:

xr.DataArray