shnitsel.units.conversion
=========================

.. py:module:: shnitsel.units.conversion


Attributes
----------

.. autoapisummary::

   shnitsel.units.conversion.convert_energy
   shnitsel.units.conversion.convert_force
   shnitsel.units.conversion.convert_dipole
   shnitsel.units.conversion.convert_length
   shnitsel.units.conversion.convert_time
   shnitsel.units.conversion.convert_nacs
   shnitsel.units.conversion.convert_socs
   shnitsel.units.conversion.convert_charge
   shnitsel.units.conversion.convert_velocity
   shnitsel.units.conversion._CONVERTERS


Classes
-------

.. autoapisummary::

   shnitsel.units.conversion.Converter


Functions
---------

.. autoapisummary::

   shnitsel.units.conversion.convert_all_units_to_shnitsel_defaults
   shnitsel.units.conversion.convert_datarray_with_unitdim_to_shnitsel_defaults


Module Contents
---------------

.. py: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.


   .. py:attribute:: __name__
      :value: 'convert_Uninferable'



   .. py:attribute:: quantity_name


   .. py:attribute:: conversions


   .. py:attribute:: case_sensitive_mapping


   .. py:attribute:: targets


   .. py:method:: __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.

      :param da: The input DataArray whose data should be converted
      :type da: xr.DataArray
      :param to: The unit to which the data should be converted
      :type to: str
      :param convert_from: The Unit from which conversion should be started if `da` does not have a `units` attribute. Defaults to None.
      :type convert_from: str | None, optional

      :raises KeyError: Raised if the convert_from parameter is not set and the `da` input has no `units` attribute set.
      :raises ValueError: Raised if the target unit `to` is not known in the conversions dictionary.
      :raises 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.
      :rtype: xr.DataArray



   .. py:method:: convert_value(value, convert_from, to)


.. py:data:: convert_energy

.. py:data:: convert_force

.. py:data:: convert_dipole

.. py:data:: convert_length

.. py:data:: convert_time

.. py:data:: convert_nacs

.. py:data:: convert_socs

.. py:data:: convert_charge

.. py:data:: convert_velocity

.. py:function:: convert_all_units_to_shnitsel_defaults(data)

.. py:data:: _CONVERTERS
   :type:  Dict[str, Callable[[xarray.DataArray, str], xarray.DataArray]]

.. py:function:: convert_datarray_with_unitdim_to_shnitsel_defaults(data)