shnitsel.io.helpers
===================

.. py:module:: shnitsel.io.helpers


Attributes
----------

.. autoapisummary::

   shnitsel.io.helpers.KindType
   shnitsel.io.helpers.PathOptionsType
   shnitsel.io.helpers.__atnum2symbol__
   shnitsel.io.helpers.__symbol2atnum__


Classes
-------

.. autoapisummary::

   shnitsel.io.helpers.LoadingParameters
   shnitsel.io.helpers.ConsistentValue


Functions
---------

.. autoapisummary::

   shnitsel.io.helpers.make_uniform_path
   shnitsel.io.helpers.get_atom_number_from_symbol
   shnitsel.io.helpers.get_symbol_from_atom_number
   shnitsel.io.helpers.get_triangular
   shnitsel.io.helpers.dip_sep
   shnitsel.io.helpers.default_state_type_assigner
   shnitsel.io.helpers.default_state_name_assigner
   shnitsel.io.helpers.random_trajid_assigner


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

.. py:data:: KindType

.. py:data:: PathOptionsType

.. py:class:: LoadingParameters

   .. py:attribute:: input_units
      :type:  Dict[str, str] | None
      :value: None



   .. py:attribute:: error_reporting
      :type:  Literal['log', 'raise']
      :value: 'log'



   .. py:attribute:: trajectory_id
      :type:  Dict[str, int] | Callable[[pathlib.Path], int] | None
      :value: None



   .. py:attribute:: state_types
      :type:  List[int] | Callable[[xarray.Dataset], xarray.Dataset] | None
      :value: None



   .. py:attribute:: state_names
      :type:  List[str] | Callable[[xarray.Dataset], xarray.Dataset] | None
      :value: None



.. py:function:: make_uniform_path(path)

   Unify the path options to alyways yield a pathlib.Path object

   :param path: path input of arbitrary type
   :type path: str | os.PathLike | pathlib.Path | None

   :returns: The converted path or None
   :rtype: pathlib.Path|None


.. py:class:: ConsistentValue(name='ConsistentValue', weak=False, ignore_none=False)

   Class to keep track of a value that may only be assigned once and not overwritten afterwards.

   Can be used to check consistency of a value across multiple datasets.
   The value is written to and read from the property `v` of the object.

   :raises AttributeError: Will be raised if the value is read before first assignment if the object has not been created with ``weak=true``.
   :raises ValueError: _description_


   .. py:attribute:: name
      :type:  str
      :value: 'ConsistentValue'



   .. py:attribute:: defined
      :type:  bool
      :value: False



   .. py:attribute:: _weak
      :type:  bool
      :value: False



   .. py:attribute:: _val
      :type:  T | None
      :value: None



   .. py:attribute:: _ignore_none
      :type:  bool
      :value: False



   .. py:property:: v
      :type: T | None



.. py:data:: __atnum2symbol__

.. py:data:: __symbol2atnum__

.. py:function:: get_atom_number_from_symbol(symbol)

.. py:function:: get_symbol_from_atom_number(number)

.. py:function:: get_triangular(original_array)

   get_triangular - get the upper triangle of a (nstat1 x nstat2 x natoms x 3) matrix

   This function takes in a 4-dimensional numpy array (original_array) and returns a 3-dimensional numpy array (upper_tril)
   which is the upper triangle of the input matrix, obtained by excluding the diagonal elements.
   The number of steps (k) to move the diagonal above the leading diagonal is 1.
   The returned matrix has shape (len(cols), natoms, 3)

   :param original_array: 4D numpy array of shape (nstat1, nstat2, natoms, 3) representing the input matrix

   :returns: 3D numpy array of shape (len(cols), natoms, 3) representing the upper triangle of the input matrix
   :rtype: upper_tril


.. py:function:: dip_sep(dipoles)

   Separates a complete matrix of dipoles into permanent
   and transitional dipoles, removing redundancy in the process.

   :param dipoles: 3D numpy array of shape (nstates, nstates, 3) where
                   the first axis represents state before transition,
                   the second axis represents state after transition and
                   the third axis contains x, y and z coordinates.

   :returns: * *dip_perm* -- 2D numpy array of shape (nstates, 3)
             * *dip_trans* -- 2D numpy array of shape (math.comb(nstates, 2), 3)
               in the order e.g. (for nstates = 4)
               0->1, 0->2, 0->3, 1->2, 1->3, 2->3
               where 0->1 is the transitional dipole between
               state 0 and state 1.


.. py:function:: default_state_type_assigner(dataset)

   Function to assign default state types to states.

   :param dataset: The dataset to assign the states to
   :type dataset: xr.Dataset

   :returns: The dataset after the assignment
   :rtype: xr.Dataset


.. py:function:: default_state_name_assigner(dataset)

   Function to assign default state names to states.

   :param dataset: The dataset to assign the states to
   :type dataset: xr.Dataset

   :returns: The dataset after the assignment
   :rtype: xr.Dataset


.. py:function:: random_trajid_assigner(path)

   Function to generate a random id for a path.

   :param path: Unused: the path we are generating for
   :type path: pathlib.Path

   :returns: the chosen trajectory id
   :rtype: int