algebra
=======

.. py:module:: algebra


Functions
---------

.. autoapisummary::

   algebra.normalize
   algebra.dnorm
   algebra.dcross
   algebra.ddot
   algebra.angle_
   algebra.angle_cos_sin_
   algebra.normal


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

.. py:function:: normalize(a, dim='direction')

   Return vectors normalized along the `dim` dimension.

   :param a: The data array to normalize along the `dim` dimension.
   :type a: xr.DataArray | xr.Variable

   :returns: Resulting DataArray after calculation of the noramlized vectors in the dimension `dim`.
   :rtype: xr.DataArray | xr.Variable


.. py:function:: dnorm(a)

   Calculate the norm along the `direction` dimension. All other dimensions are maintaned

   :param a: The data array to perform the norming on
   :type a: xr.DataArray | xr.Variable

   :returns: Resulting dataarray after calculation of the norm in the dimension `direction.
   :rtype: xr.DataArray | xr.Variable


.. py:function:: dcross(a, b)

   Generalized cross vector product in the dimension of `direction`.

   :param a: The first array to use for the binary operation
   :type a: xr.DataArray | xr.Variable
   :param b: The second array to use for the binary operation
   :type b: xr.DataArray | xr.Variable

   :returns: The resulting array of the cross-product
   :rtype: xr.DataArray | xr.Variable


.. py:function:: ddot(a, b)

   Dot product in the dimension of `direction`.

   :param a: The first array to use for the binary operation
   :type a: xr.DataArray | xr.Variable
   :param b: The second array to use for the binary operation
   :type b: xr.DataArray | xr.Variable

   :returns: The resulting array of the dot-product still retaining all other dimensions except `direction`.
   :rtype: xr.DataArray | xr.Variable


.. py:function:: angle_(a, b)

   Helper function to calculate the angle between the entries in a and b based on their coordinates in the `direction` dimension.

   :param a: The first array to use for the binary operation
   :type a: xr.DataArray | xr.Variable
   :param b: The second array to use for the binary operation
   :type b: xr.DataArray | xr.Variable

   :returns: The resulting array of the angle calculation still retaining all other dimensions except `direction`.
   :rtype: xr.DataArray | xr.Variable


.. py:function:: angle_cos_sin_(a, b)

   Returns the cosine and sine of the angle between two vectors

   :param a: First vector
   :type a: DataArrayOrVar
   :param b: Second vector
   :type b: DataArrayOrVar

   :returns: First the vector of cosines, second the vector of sines.
   :rtype: tuple[DataArrayOrVar, DataArrayOrVar]


.. py:function:: normal(a, b, c)

   Calculate normal vectors on the planes through corresponding points in a, b and c.

   The normal vector will be calculated based on the position in `direction` dimension.

   :param a: The first array to use for the ternary operation
   :type a: xr.DataArray | xr.Variable
   :param b: The second array to use for the ternary operation
   :type b: xr.DataArray | xr.Variable
   :param c: The third array to use for the ternary operation
   :type c: xr.DataArray | xr.Variable

   :returns: An array with all dimensions equal to those of a, b, and c but holding normal vectors along the `direction` dimension.
   :rtype: xr.DataArray | xr.Variable