Write doc for positive power of a matrix with a semisimple zero eigenvalue.

1 files changed, 18 insertions, 1 deletions

diff --git a/unsupported/Eigen/MatrixFunctions b/unsupported/Eigen/MatrixFunctions
index 0bdd379d7..41dfab390 100644
--- a/unsupported/Eigen/MatrixFunctions
+++ b/unsupported/Eigen/MatrixFunctions
@@ -239,12 +239,29 @@ p . \f$ M^p \f$ simply evaluates into \f$ \exp(p \log(M)) \f$.
 Therefore, the matrix \f$ M \f$ should meet the conditions to be an
 argument of matrix logarithm.
 
-This function computes the matrix power using the Schur-Padé
+If \p p is real, it is casted into the real scalar type of \p M. Then
+this function computes the matrix power using the Schur-Padé
 algorithm as implemented by class MatrixPower. The exponent is split
 into integral part and fractional part, where the fractional part is
 in the interval \f$ (-1, 1) \f$. The main diagonal and the first
 super-diagonal is directly computed.
 
+If \p M is singular with a semisimple zero eigenvalue and \p p is
+positive, the Schur factor \f$ T \f$ is reordered with Givens
+rotations, i.e.
+
+\f[ T = \left[ \begin{array}{cc}
+      T_1 & T_2 \\
+      0   & 0
+    \end{array} \right] \f]
+
+where \f$ T_1 \f$ is invertible. Then \f$ T^p \f$ is given by
+
+\f[ T^p = \left[ \begin{array}{cc}
+      T_1^p & T_1^{-1} T_1^p T_2 \\
+      0     & 0
+    \end{array}. \right] \f]
+
 Details of the algorithm can be found in: Nicholas J. Higham and
 Lijing Lin, "A Schur-Padé algorithm for fractional powers of a
 matrix," <em>SIAM J. %Matrix Anal. Applic.</em>,