Utility Functions
-----------------

Basic Functions
^^^^^^^^^^^^^^^

real()
""""""

.. py:function:: real(object)

The same as ``object.real()``.

imag()
""""""

.. py:function:: imag(object)

The same as ``object.imag()``.

trace()
"""""""

.. py:function:: trace(object)

The same as ``object.trace()``.

conj()
""""""

.. py:function:: conj(object)

The same as ``object.conj()``.

norm()
""""""

.. py:function:: norm(object)

The same as ``object.norm()``.

delta()
"""""""

.. py:function:: delta(object)

The same as ``object.delta()``.

inverse()
"""""""""

.. py:function:: inverse(object[,module])

The same as ``object.inverse([module])``.

unitary()
"""""""""

.. py:function:: unitary(object)

The same as ``object.unitary()``.

sqrt()
""""""

.. py:function:: sqrt(object)

The same as ``object.sqrt()`` (see [1]_ and [2]_ for details on roots extraction). 

croot()
"""""""

.. py:function:: croot(object)

The same as ``object.croot()`` (see [1]_ and [2]_ for details on roots extraction).

Additional Functions
^^^^^^^^^^^^^^^^^^^^

QuaternionToRotation()
""""""""""""""""""""""

.. py:function:: QuaternionToRotation(object)

The same as ``object.QuaternioinToRotation()``.

RotationToQuaternion()
""""""""""""""""""""""

.. py:function:: RotationToQuaternion(angle,vector)

Converts a pair angle-vector into a quaternion.

StringToQuaternion()
""""""""""""""""""""

.. py:function:: StringToQuaternion(string)

Converts a string into a quaternion.

MatrixToEuler()
"""""""""""""""

.. py:function:: MatrixToEuler(matrix)

Converts a 3X3 (numpy) matrix into a vector having Euler angles as components.

EulerToQuaternion()
"""""""""""""""""""

.. py:function:: EulerToQuaternion(list)

Converts a vector whose components are Euler angles into a quaternion.
    
identity()
""""""""""

.. py:function:: identity()

Returns 1 as a quaternion.

 >>> qmath.identity()
 (1.0)

zero()
""""""

.. py:function:: zero(object)

Returns 0 as a quaternion.
 >>> qmath.zero()
 (0.0)

dot()
"""""

.. py:function:: dot(object_1,object_2)

Returns the dot product of two quaternions.

 >>> a = qmath.quaternion('1+2i-2k')
 >>> b = qmath.quaternion('3-2i+8j')
 >>> qmath.dot(a,b)
 -1.0

CrossRatio()
""""""""""""

.. py:function:: CrossRatio(a,b,c,d)

Returns the cross ratio of four quaternions.

If ``a`` and ``d`` or ``b`` and ``c`` are equal, returns the string ``'Infinity'``.

The arguments of ``CrossRatio`` can be passed as a tuple.

 >>> a = qmath.quaternion([1,0,1,0])
 >>> b = qmath.quaternion([0,1,0,1])
 >>> c = qmath.quaternion([-1,0,-1,0])
 >>> d = qmath.quaternion([0,-1,0,-1])
 >>> qmath.CrossRatio(a,b,c,d)
 (2.0)
 >>> tpl = a,b,c,d
 >>> qmath.CrossRatio(tpl)
 (2.0)
 >>> qmath.CrossRatio(a,b,b,d)
 'Infinity'
 >>> qmath.CrossRatio(a,a,a,d)
 (1.0)
 >>> qmath.CrossRatio(a,b,a,b)
 (0.0)

Moebius()
"""""""""

.. py:function:: Moebius(z,a,b,c,d)

Returns the Moebius transformation with parameters a,b,c and d.

If ``c * z + d == 0`` returns the string ``'Infinity'``. 

The arguments of ``Moebius`` can be passed as a tuple.

 >>> a = qmath.quaternion([1,1,1,0])
 >>> b = qmath.quaternion([-2,1,0,1])
 >>> c = qmath.quaternion([1,0,0,0])
 >>> d = qmath.quaternion([0,-1,-3,-4])
 >>> z = qmath.quaternion([1,1,3,4])
 >>> qmath.Moebius(z,a,b,c,d)
 (-5.0+7.0i+7.0k)
 >>> d = - z
 >>> z = qmath.Moebius(z,a,b,c,d)
 >>> z
 'Infinity'
 >>> qmath.Moebius(z,a,b,c,d)
 (1.0+1.0i+1.0j)

.. rubric:: References

.. [1] M. Abrate, `Quadratic Formulas for Generalized Quaternions <http://www.worldscinet.com/jaa/08/0803/S0219498809003308.html>`_, The Journal of Algebra and its Applications, Vol. 8, Issue 3 (2009), pp. 289-306.

.. [2] M. Abrate `The Roots of a Generalized Quaternion`, Congressus Numeratium, Vol. 201 (2010), pp. 179-186, Kluwer Academic Publishers.