Merge topic 'LUDoc' into master

29bbbaf2 DOC: Describe how to get L and U out of the LU factorization.

Common/Core/vtkMath.h

@@ -657,11 +657,29 @@ public:
                           int *tmp1Size, double *tmp2Size);
 
   // Description:
-  // Factor linear equations Ax = b using LU decomposition A = LU where L is
-  // lower triangular matrix and U is upper triangular matrix. Input is
-  // square matrix A, integer array of pivot indices index[0->n-1], and size
-  // of square matrix n. Output factorization LU is in matrix A. If error is
-  // found, method returns 0.
+  // Factor linear equations Ax = b using LU decomposition into the form
+  // A = LU where L is a unit lower triangular matrix and U is upper triangular
+  // matrix.
+  // The input is a square matrix A, an integer array of pivot indices index[0->n-1],
+  // and the size, n, of the square matrix.
+  // The output is provided by overwriting the input A with a matrix of the same size as
+  // A containing all of the information about L and U. If the output matrix is
+  // \f$ A* = \left( \begin{array}{cc}
+  // a & b \\
+  // c & d \end{array} \right)\f$
+  // then L and U can be obtained as:
+  // \f$ L = \left( \begin{array}{cc}
+  // 1 & 0 \\
+  // c & 1 \end{array} \right)\f$
+  // \f$ U = \left( \begin{array}{cc}
+  // a & b \\
+  // 0 & d \end{array} \right)\f$
+  //
+  // That is, the diagonal of the resulting A* is the diagonal of U. The upper right
+  // triangle of A is the upper right triangle of U. The lower left triangle of A is
+  // the lower left triangle of L (and since L is unit lower triangular, the diagonal
+  // of L is all 1's).
+  // If an error is found, the function returns 0.
   static int LUFactorLinearSystem(double **A, int *index, int size);
 
   // Description: