path: root/unsupported/Eigen/MatrixFunctions

// This file is part of Eigen, a lightweight C++ template library
// for linear algebra.
//
// Copyright (C) 2009 Jitse Niesen <jitse@maths.leeds.ac.uk>
//
// Eigen is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 3 of the License, or (at your option) any later version.
//
// Alternatively, you can redistribute it and/or
// modify it under the terms of the GNU General Public License as
// published by the Free Software Foundation; either version 2 of
// the License, or (at your option) any later version.
//
// Eigen is distributed in the hope that it will be useful, but WITHOUT ANY
// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
// FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License or the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License and a copy of the GNU General Public License along with
// Eigen. If not, see <http://www.gnu.org/licenses/>.

#ifndef EIGEN_MATRIX_FUNCTIONS
#define EIGEN_MATRIX_FUNCTIONS

#include <list>
#include <functional>
#include <iterator>

#include <Eigen/Core>
#include <Eigen/LU>
#include <Eigen/Eigenvalues>

namespace Eigen {

/** \ingroup Unsupported_modules
  * \defgroup MatrixFunctions_Module Matrix functions module
  * \brief This module aims to provide various methods for the computation of
  * matrix functions. 
  *
  * To use this module, add 
  * \code
  * #include <unsupported/Eigen/MatrixFunctions>
  * \endcode
  * at the start of your source file.
  *
  * This module defines the following MatrixBase methods.
  *  - \ref matrixbase_cos "MatrixBase::cos()", for computing the matrix cosine
  *  - \ref matrixbase_cosh "MatrixBase::cosh()", for computing the matrix hyperbolic cosine
  *  - \ref matrixbase_exp "MatrixBase::exp()", for computing the matrix exponential
  *  - \ref matrixbase_matrixfunction "MatrixBase::matrixFunction()", for computing general matrix functions
  *  - \ref matrixbase_sin "MatrixBase::sin()", for computing the matrix sine
  *  - \ref matrixbase_sinh "MatrixBase::sinh()", for computing the matrix hyperbolic sine
  *
  * These methods are the main entry points to this module. 
  *
  * %Matrix functions are defined as follows.  Suppose that \f$ f \f$
  * is an entire function (that is, a function on the complex plane
  * that is everywhere complex differentiable).  Then its Taylor
  * series
  * \f[ f(0) + f'(0) x + \frac{f''(0)}{2} x^2 + \frac{f'''(0)}{3!} x^3 + \cdots \f]
  * converges to \f$ f(x) \f$. In this case, we can define the matrix
  * function by the same series:
  * \f[ f(M) = f(0) + f'(0) M + \frac{f''(0)}{2} M^2 + \frac{f'''(0)}{3!} M^3 + \cdots \f]
  *
  */

#include "src/MatrixFunctions/MatrixExponential.h"
#include "src/MatrixFunctions/MatrixFunction.h"



/** 
\page matrixbaseextra MatrixBase methods defined in the MatrixFunctions module
\ingroup MatrixFunctions_Module

The remainder of the page documents the following MatrixBase methods
which are defined in the MatrixFunctions module.



\section matrixbase_cos MatrixBase::cos()

Compute the matrix cosine.

\code
const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::cos() const
\endcode

\param[in]  M  a square matrix.
\returns  expression representing \f$ \cos(M) \f$.

This function calls \ref matrixbase_matrixfunction "matrixFunction()" with StdStemFunctions::cos().

\sa \ref matrixbase_sin "sin()" for an example.



\section matrixbase_cosh MatrixBase::cosh()

Compute the matrix hyberbolic cosine.

\code
const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::cosh() const
\endcode

\param[in]  M  a square matrix.
\returns  expression representing \f$ \cosh(M) \f$

This function calls \ref matrixbase_matrixfunction "matrixFunction()" with StdStemFunctions::cosh().

\sa \ref matrixbase_sinh "sinh()" for an example.



\section matrixbase_exp MatrixBase::exp()

Compute the matrix exponential.

\code
const MatrixExponentialReturnValue<Derived> MatrixBase<Derived>::exp() const
\endcode

\param[in]  M  matrix whose exponential is to be computed.
\returns    expression representing the matrix exponential of \p M.

The matrix exponential of \f$ M \f$ is defined by
\f[ \exp(M) = \sum_{k=0}^\infty \frac{M^k}{k!}. \f]
The matrix exponential can be used to solve linear ordinary
differential equations: the solution of \f$ y' = My \f$ with the
initial condition \f$ y(0) = y_0 \f$ is given by
\f$ y(t) = \exp(M) y_0 \f$.

The cost of the computation is approximately \f$ 20 n^3 \f$ for
matrices of size \f$ n \f$. The number 20 depends weakly on the
norm of the matrix.

The matrix exponential is computed using the scaling-and-squaring
method combined with Pad&eacute; approximation. The matrix is first
rescaled, then the exponential of the reduced matrix is computed
approximant, and then the rescaling is undone by repeated
squaring. The degree of the Pad&eacute; approximant is chosen such
that the approximation error is less than the round-off
error. However, errors may accumulate during the squaring phase.

Details of the algorithm can be found in: Nicholas J. Higham, "The
scaling and squaring method for the matrix exponential revisited,"
<em>SIAM J. %Matrix Anal. Applic.</em>, <b>26</b>:1179&ndash;1193,
2005.

Example: The following program checks that
\f[ \exp \left[ \begin{array}{ccc}
      0 & \frac14\pi & 0 \\
      -\frac14\pi & 0 & 0 \\
      0 & 0 & 0
    \end{array} \right] = \left[ \begin{array}{ccc}
      \frac12\sqrt2 & -\frac12\sqrt2 & 0 \\
      \frac12\sqrt2 & \frac12\sqrt2 & 0 \\
      0 & 0 & 1
    \end{array} \right]. \f]
This corresponds to a rotation of \f$ \frac14\pi \f$ radians around
the z-axis.

\include MatrixExponential.cpp
Output: \verbinclude MatrixExponential.out

\note \p M has to be a matrix of \c float, \c double,
\c complex<float> or \c complex<double> .



\section matrixbase_matrixfunction MatrixBase::matrixFunction()

Compute a matrix function.

\code
const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::matrixFunction(typename ei_stem_function<typename ei_traits<Derived>::Scalar>::type f) const
\endcode

\param[in]  M  argument of matrix function, should be a square matrix.
\param[in]  f  an entire function; \c f(x,n) should compute the n-th
derivative of f at x.
\returns  expression representing \p f applied to \p M.

Suppose that \p M is a matrix whose entries have type \c Scalar. 
Then, the second argument, \p f, should be a function with prototype
\code 
ComplexScalar f(ComplexScalar, int) 
\endcode
where \c ComplexScalar = \c std::complex<Scalar> if \c Scalar is
real (e.g., \c float or \c double) and \c ComplexScalar =
\c Scalar if \c Scalar is complex. The return value of \c f(x,n)
should be \f$ f^{(n)}(x) \f$, the n-th derivative of f at x.

This routine uses the algorithm described in:
Philip Davies and Nicholas J. Higham, 
"A Schur-Parlett algorithm for computing matrix functions", 
<em>SIAM J. %Matrix Anal. Applic.</em>, <b>25</b>:464&ndash;485, 2003.

The actual work is done by the MatrixFunction class.

Example: The following program checks that
\f[ \exp \left[ \begin{array}{ccc} 
      0 & \frac14\pi & 0 \\ 
      -\frac14\pi & 0 & 0 \\
      0 & 0 & 0 
    \end{array} \right] = \left[ \begin{array}{ccc}
      \frac12\sqrt2 & -\frac12\sqrt2 & 0 \\
      \frac12\sqrt2 & \frac12\sqrt2 & 0 \\
      0 & 0 & 1
    \end{array} \right]. \f]
This corresponds to a rotation of \f$ \frac14\pi \f$ radians around
the z-axis. This is the same example as used in the documentation
of \ref matrixbase_exp "exp()".

\include MatrixFunction.cpp
Output: \verbinclude MatrixFunction.out

Note that the function \c expfn is defined for complex numbers 
\c x, even though the matrix \c A is over the reals. Instead of
\c expfn, we could also have used StdStemFunctions::exp:
\code
A.matrixFunction(StdStemFunctions<std::complex<double> >::exp, &B);
\endcode



\section matrixbase_sin MatrixBase::sin()

Compute the matrix sine.

\code
const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::sin() const
\endcode

\param[in]  M  a square matrix.
\returns  expression representing \f$ \sin(M) \f$.

This function calls \ref matrixbase_matrixfunction "matrixFunction()" with StdStemFunctions::sin().

Example: \include MatrixSine.cpp
Output: \verbinclude MatrixSine.out



\section matrixbase_sinh const MatrixBase::sinh()

Compute the matrix hyperbolic sine.

\code
MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::sinh() const
\endcode

\param[in]  M  a square matrix.
\returns  expression representing \f$ \sinh(M) \f$

This function calls \ref matrixbase_matrixfunction "matrixFunction()" with StdStemFunctions::sinh().

Example: \include MatrixSinh.cpp
Output: \verbinclude MatrixSinh.out

*/

}

#endif // EIGEN_MATRIX_FUNCTIONS