helpers
=======

.. py:module:: helpers


Attributes
----------

.. autoapisummary::

   helpers.PathOptionsType
   helpers.T


Classes
-------

.. autoapisummary::

   helpers.LoadingParameters
   helpers.ConsistentValue


Functions
---------

.. autoapisummary::

   helpers.make_uniform_path
   helpers.get_triangular
   helpers.dip_sep
   helpers.random_trajid_assigner


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

.. py:data:: PathOptionsType

.. py:class:: LoadingParameters

   Class to hold certain parameters required at loading time at various points in the reading/
   import pipeline


   .. 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:  shnitsel.core.typedefs.StateTypeSpecifier | List[shnitsel.core.typedefs.StateTypeSpecifier] | Callable[[xarray.Dataset], xarray.Dataset] | None
      :value: None



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



   .. py:attribute:: logger
      :type:  logging.Logger | 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
   :rtype: pathlib.Path|None

   :raises ValueError: If path was `None` or could not be converted


.. py:data:: T

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

   Bases: :py:obj:`Generic`\ [\ :py:obj:`T`\ ]


   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: If an inconsistent value is assigned to this instance, i.e. two different values have been assigned.


   .. 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: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
   :type original_array: np.ndarray

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


.. 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.
   :type dipoles: np.ndarray

   :returns: * **dip_perm** (*np.ndarray*) -- 2D numpy array of shape (nstates, 3)
             * **dip_trans** (*np.ndarray*) -- 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:: 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