clean a bit the ILUT code

2 files changed, 281 insertions, 228 deletions

diff --git a/Eigen/IterativeLinearSolvers b/Eigen/IterativeLinearSolvers
index 8f2c13eb8..3bd298729 100644
--- a/Eigen/IterativeLinearSolvers
+++ b/Eigen/IterativeLinearSolvers
@@ -2,6 +2,7 @@
 #define EIGEN_ITERATIVELINEARSOLVERS_MODULE_H
 
 #include "SparseCore"
+#include "OrderingMethods"
 
 #include "src/Core/util/DisableStupidWarnings.h"
 
@@ -15,6 +16,11 @@ namespace Eigen {
   *  - ConjugateGradient for selfadjoint (hermitian) matrices,
   *  - BiCGSTAB for general square matrices.
   *
+  * These iterative solvers are associated with some preconditioners:
+  *  - IdentityPreconditioner - not really useful
+  *  - DiagonalPreconditioner - also called JAcobi preconditioner, work very well on diagonal dominant matrices.
+  *  - IncompleteILUT - incomplete LU factorization with dual thresholding
+  *
   * Such problems can also be solved using the direct sparse decomposition modules: SparseCholesky, CholmodSupport, UmfPackSupport, SuperLUSupport.
   *
   * \code
diff --git a/Eigen/src/IterativeLinearSolvers/IncompleteLUT.h b/Eigen/src/IterativeLinearSolvers/IncompleteLUT.h
index e8bde24b0..3f136cc4a 100644
--- a/Eigen/src/IterativeLinearSolvers/IncompleteLUT.h
+++ b/Eigen/src/IterativeLinearSolvers/IncompleteLUT.h
@@ -24,15 +24,13 @@
 
 #ifndef EIGEN_INCOMPLETE_LUT_H
 #define EIGEN_INCOMPLETE_LUT_H
-#include <bench/btl/generic_bench/utils/utilities.h>
-#include <Eigen/src/OrderingMethods/Amd.h>
 
 /**
  * \brief Incomplete LU factorization with dual-threshold strategy
  * During the numerical factorization, two dropping rules are used :
- *  1) any element whose magnitude is less than some tolerance  is dropped. 
+ *  1) any element whose magnitude is less than some tolerance is dropped.
  *    This tolerance is obtained by multiplying the input tolerance @p droptol 
- *    by the  average magnitude of all the original elements in the current row.
+ *    by the average magnitude of all the original elements in the current row.
  *  2) After the elimination of the row, only the @p fill largest elements in 
  *    the L part and the @p fill largest elements in the U part are kept 
  *    (in addition to the diagonal element ). Note that @p fill is computed from 
@@ -63,11 +61,15 @@ class IncompleteLUT
   public:
     typedef Matrix<Scalar,Dynamic,Dynamic> MatrixType;
     
-    IncompleteLUT() : m_droptol(NumTraits<Scalar>::dummy_precision()),m_fillfactor(10),m_analysisIsOk(false),m_factorizationIsOk(false),m_isInitialized(false) {}
+    IncompleteLUT()
+      : m_droptol(NumTraits<Scalar>::dummy_precision()), m_fillfactor(10),
+        m_analysisIsOk(false), m_factorizationIsOk(false), m_isInitialized(false)
+    {}
     
     template<typename MatrixType>
-    IncompleteLUT(const MatrixType& mat, RealScalar droptol, int fillfactor) 
-    : m_droptol(droptol),m_fillfactor(fillfactor),m_analysisIsOk(false),m_factorizationIsOk(false),m_isInitialized(false)
+    IncompleteLUT(const MatrixType& mat, RealScalar droptol=NumTraits<Scalar>::dummy_precision(), int fillfactor = 10)
+      : m_droptol(droptol),m_fillfactor(fillfactor),
+        m_analysisIsOk(false),m_factorizationIsOk(false),m_isInitialized(false)
     {
       eigen_assert(fillfactor != 0);
       compute(mat); 
@@ -76,205 +78,23 @@ class IncompleteLUT
     Index rows() const { return m_lu.rows(); }
     
     Index cols() const { return m_lu.cols(); }
-    
-    template<typename MatrixType>
-    void analyzePattern(const MatrixType& amat)
+
+    /** \brief Reports whether previous computation was successful.
+      *
+      * \returns \c Success if computation was succesful,
+      *          \c NumericalIssue if the matrix.appears to be negative.
+      */
+    ComputationInfo info() const
     {
-      /* Compute the Fill-reducing permutation */
-      SparseMatrix<Scalar,ColMajor, Index> mat1 = amat;
-      SparseMatrix<Scalar,ColMajor, Index> mat2 = amat.transpose();
-      SparseMatrix<Scalar,ColMajor, Index> AtA = mat2 * mat1; /* Symmetrize the pattern */
-      AtA.prune(keep_diag());
-      internal::minimum_degree_ordering<Scalar, Index>(AtA, m_P);  /* Then compute the AMD ordering... */
-      
-      m_Pinv  = m_P.inverse(); /* ... and the inverse permutation */
-      m_analysisIsOk = true; 
+      eigen_assert(m_isInitialized && "IncompleteLUT is not initialized.");
+      return m_info;
     }
     
     template<typename MatrixType>
-    void  factorize(const MatrixType& amat)
-    {
-      eigen_assert((amat.rows() == amat.cols()) && "The factorization should be done on a square matrix");
-      int n = amat.cols();  /* Size of the matrix */
-      m_lu.resize(n,n); 
-      int fill_in; /* Number of largest elements to keep in each row */
-      int nnzL, nnzU; /* Number of largest nonzero elements to keep in the L and the U part of the current row */
-      /* Declare Working vectors and variables */
-      int sizeu; /*  number of nonzero elements in the upper part of the current row */
-      int sizel; /*  number of nonzero elements in the lower part of the current row */
-      Vector u(n) ; /* real values of the row -- maximum size is n --  */
-      VectorXi ju(n); /*column position of the values in u -- maximum size  is n*/
-      VectorXi jr(n); /* Indicate the position of the nonzero elements in the vector u -- A zero location is indicated by -1*/
-      int j, k, jj, jpos, minrow, len;
-      Scalar fact, prod;
-      RealScalar rownorm;
-
-      /* Apply the fill-reducing permutation */
-      
-      eigen_assert(m_analysisIsOk && "You must first call analyzePattern()");
-      SparseMatrix<Scalar,RowMajor, Index> mat;
-      mat = amat.twistedBy(m_Pinv);  
-      
-      /* Initialization */
-      fact = 0;
-      jr.fill(-1); 
-      ju.fill(0);
-      u.fill(0);
-      fill_in =   static_cast<int> (amat.nonZeros()*m_fillfactor)/n+1;
-      if (fill_in > n) fill_in = n;
-      nnzL = fill_in/2; 
-      nnzU = nnzL;
-      m_lu.reserve(n * (nnzL + nnzU + 1)); 
-      for (int ii = 0; ii < n; ii++) 
-      { /* global loop over the rows of the sparse matrix */
-      
-        /* Copy the lower and the upper part of the row i of mat in the working vector u */
-        sizeu = 1;
-        sizel = 0;
-        ju(ii) = ii;
-        u(ii) = 0; 
-        jr(ii) = ii;
-        rownorm = 0; 
-        
-        typename FactorType::InnerIterator j_it(mat, ii); /* Iterate through the current row ii */
-        for (; j_it; ++j_it)
-        {
-          k = j_it.index(); 
-          if (k < ii) 
-          { /* Copy the lower part */
-            ju(sizel) = k; 
-            u(sizel) = j_it.value();
-            jr(k) = sizel; 
-            ++sizel;
-          }
-          else if (k == ii)
-          {
-            u(ii) = j_it.value();
-          } 
-          else
-          { /* Copy the upper part */
-            jpos = ii + sizeu;
-            ju(jpos) = k;
-            u(jpos) = j_it.value();
-            jr(k) = jpos; 
-            ++sizeu; 
-          }
-          rownorm += internal::abs2(j_it.value());
-        } /* end copy of the row */
-        /* detect possible zero row */
-        if (rownorm == 0) eigen_internal_assert(false); 
-        rownorm = std::sqrt(rownorm); /* Take the 2-norm of the current row as a relative tolerance */
-        
-        /* Now, eliminate the previous nonzero rows */
-        jj = 0; len = 0; 
-        while (jj < sizel) 
-        { /* In order to eliminate in the correct order, we must select first the smallest column index among  ju(jj:sizel) */
-        
-          minrow = ju.segment(jj,sizel-jj).minCoeff(&k); /* k est relatif au segment */
-          k += jj;
-          if (minrow != ju(jj)) { /* swap the two locations */ 
-            j = ju(jj);
-            std::swap(ju(jj), ju(k));  
-            jr(minrow) = jj;   jr(j) = k; 
-            std::swap(u(jj), u(k)); 
-          }      
-          /* Reset this location to zero */
-          jr(minrow) = -1;
-          
-          /* Start elimination */
-          typename FactorType::InnerIterator ki_it(m_lu, minrow);   
-          while (ki_it && ki_it.index() < minrow) ++ki_it;  
-          if(ki_it && ki_it.col()==minrow) fact = u(jj) / ki_it.value();
-          else { eigen_internal_assert(false); }
-          if( std::abs(fact) <= m_droptol ) {
-            jj++;
-            continue ; /* This element is been dropped */
-          }
-          /* linear combination of the current row ii and the row minrow */
-          ++ki_it;
-          for (; ki_it; ++ki_it) {
-            prod = fact * ki_it.value();
-            j = ki_it.index();
-            jpos =  jr(j); 
-            if (j >= ii) { /* Dealing with the upper part */
-              if (jpos == -1) { /* Fill-in element */ 
-                int newpos = ii + sizeu;
-                ju(newpos) = j;
-                u(newpos) = - prod;
-                jr(j) = newpos;
-                sizeu++;
-                if (sizeu > n) { eigen_internal_assert(false);}
-              }
-              else { /* Not a fill_in element */
-                u(jpos) -= prod;
-              }
-            }
-            else { /* Dealing with the lower part */
-              if (jpos == -1) { /* Fill-in element */
-                ju(sizel) = j;
-                jr(j) = sizel;
-                u(sizel) = - prod;
-                sizel++;
-                if(sizel > n) { eigen_internal_assert(false);}
-              }
-              else {
-                u(jpos) -= prod;
-              }
-            }
-          }
-          /* Store the pivot element */
-          u(len) = fact;
-          ju(len) = minrow;
-          ++len; 
-          
-          jj++; 
-        } /* End While loop -- end of the elimination on the row ii*/
-        /* Reset the upper part of the pointer jr to zero */
-        for (k = 0; k <sizeu; k++){
-          jr(ju(ii+k)) = -1;
-        }
-        /* Sort the L-part of the row --use Quicksplit()*/
-        sizel = len; 
-        len = std::min(sizel, nnzL ); 
-        typename Vector::SegmentReturnType ul(u.segment(0, len)); 
-        typename VectorXi::SegmentReturnType jul(ju.segment(0, len));
-        QuickSplit(ul, jul, len); 
-        
-        
-        /* Store the  largest  m_fill elements of the L part  */
-        m_lu.startVec(ii);
-        for (k = 0; k < len; k++){
-          m_lu.insertBackByOuterInnerUnordered(ii,ju(k)) = u(k);
-        }
-        
-        /* Store the diagonal element */
-        if (u(ii) == Scalar(0)) 
-          u(ii) = std::sqrt(m_droptol ) * rownorm ;  /* NOTE This is used to avoid a zero pivot, because we are doing an incomplete factorization  */
-        m_lu.insertBackByOuterInnerUnordered(ii, ii) = u(ii);
-        /* Sort the U-part of the row -- Use Quicksplit() */
-        len = 0; 
-        for (k = 1; k < sizeu; k++) { /* First, drop any element that is below a relative tolerance */
-          if ( std::abs(u(ii+k)) > m_droptol * rownorm ) {
-            ++len; 
-            u(ii + len) = u(ii + k); 
-            ju(ii + len) = ju(ii + k); 
-          }
-        }
-        sizeu = len + 1; /* To take into account the diagonal element */
-        len = std::min(sizeu, nnzU);
-        typename Vector::SegmentReturnType uu(u.segment(ii+1, sizeu-1)); 
-        typename VectorXi::SegmentReturnType juu(ju.segment(ii+1, sizeu-1));
-        QuickSplit(uu, juu, len); 
-        /* Store the largest <fill> elements of the U part */
-        for (k = ii + 1; k < ii + len; k++){
-          m_lu.insertBackByOuterInnerUnordered(ii,ju(k)) = u(k);
-        }
-      } /* End global for-loop */
-      m_lu.finalize();
-      m_lu.makeCompressed(); /* NOTE To save the extra space */
-      
-      m_factorizationIsOk = true; 
-    }
+    void analyzePattern(const MatrixType& amat);
+    
+    template<typename MatrixType>
+    void factorize(const MatrixType& amat);
     
     /**
     * Compute an incomplete LU factorization with dual threshold on the matrix mat
@@ -291,19 +111,15 @@ class IncompleteLUT
       return *this;
     }
 
-    
     void setDroptol(RealScalar droptol); 
     void setFillfactor(int fillfactor); 
     
-    
-    
-    
     template<typename Rhs, typename Dest>
     void _solve(const Rhs& b, Dest& x) const
     {
       x = m_Pinv * b;  
-      x = m_lu.template triangularView<UnitLower>().solve(x);/* Compute L*x = P*b for x */
-      x = m_lu.template triangularView<Upper>().solve(x); /* Compute U * z  = y for z */
+      x = m_lu.template triangularView<UnitLower>().solve(x);
+      x = m_lu.template triangularView<Upper>().solve(x);
       x = m_P * x; 
     }
 
@@ -315,19 +131,13 @@ class IncompleteLUT
                 && "IncompleteLUT::solve(): invalid number of rows of the right hand side matrix b");
       return internal::solve_retval<IncompleteLUT, Rhs>(*this, b.derived());
     }
-    
+
 protected:
-    FactorType m_lu;
-    RealScalar m_droptol;
-    int m_fillfactor;   
-    bool m_analysisIsOk;
-    bool m_factorizationIsOk;
-    bool m_isInitialized;
-    template <typename VectorV, typename VectorI> 
-    int QuickSplit(VectorV &row, VectorI &ind, int ncut); 
-    PermutationMatrix<Dynamic,Dynamic,Index> m_P; /* Fill-reducing permutation */
-    PermutationMatrix<Dynamic,Dynamic,Index> m_Pinv; /* Inverse permutation */ 
-    
+
+    template <typename VectorV, typename VectorI>
+    int QuickSplit(VectorV &row, VectorI &ind, int ncut);
+
+
     /** keeps off-diagonal entries; drops diagonal entries */
     struct keep_diag {
       inline bool operator() (const Index& row, const Index& col, const Scalar&) const
@@ -335,6 +145,18 @@ protected:
         return row!=col;
       }
     };
+
+protected:
+
+    FactorType m_lu;
+    RealScalar m_droptol;
+    int m_fillfactor;
+    bool m_analysisIsOk;
+    bool m_factorizationIsOk;
+    bool m_isInitialized;
+    ComputationInfo m_info;
+    PermutationMatrix<Dynamic,Dynamic,Index> m_P;     // Fill-reducing permutation
+    PermutationMatrix<Dynamic,Dynamic,Index> m_Pinv;  // Inverse permutation
 };
 
 /**
@@ -371,8 +193,9 @@ template <typename Scalar>
 template <typename VectorV, typename VectorI>
 int IncompleteLUT<Scalar>::QuickSplit(VectorV &row, VectorI &ind, int ncut)
 {
+  using std::swap;
   int mid;
-  int n = row.size(); /* lenght of the vector */
+  int n = row.size(); /* length of the vector */
   int first, last ; 
   
   ncut--; /* to fit the zero-based indices */
@@ -386,23 +209,247 @@ int IncompleteLUT<Scalar>::QuickSplit(VectorV &row, VectorI &ind, int ncut)
     for (int j = first + 1; j <= last; j++) {
       if ( std::abs(row(j)) > abskey) {
         ++mid;
-        std::swap(row(mid), row(j));
-        std::swap(ind(mid), ind(j));
+        swap(row(mid), row(j));
+        swap(ind(mid), ind(j));
       }
     }
     /* Interchange for the pivot element */
-    std::swap(row(mid), row(first));
-    std::swap(ind(mid), ind(first));
+    swap(row(mid), row(first));
+    swap(ind(mid), ind(first));
     
     if (mid > ncut) last = mid - 1;
     else if (mid < ncut ) first = mid + 1; 
   } while (mid != ncut );
   
-  
-  return 0; /* mid is equal to ncut */
-  
+  return 0; /* mid is equal to ncut */ 
 }
 
+template <typename Scalar>
+template<typename _MatrixType>
+void IncompleteLUT<Scalar>::analyzePattern(const _MatrixType& amat)
+{
+  // Compute the Fill-reducing permutation
+  SparseMatrix<Scalar,ColMajor, Index> mat1 = amat;
+  SparseMatrix<Scalar,ColMajor, Index> mat2 = amat.transpose();
+  // Symmetrize the pattern
+  // FIXME for a matrix with nearly symmetric pattern, mat2+mat1 is the appropriate choice.
+  //       on the other hand for a really non-symmetric pattern, mat2*mat1 should be prefered...
+  SparseMatrix<Scalar,ColMajor, Index> AtA = mat2 + mat1;
+  AtA.prune(keep_diag());
+  internal::minimum_degree_ordering<Scalar, Index>(AtA, m_P);  // Then compute the AMD ordering...
+
+  m_Pinv  = m_P.inverse(); // ... and the inverse permutation
+
+  m_analysisIsOk = true;
+}
+
+template <typename Scalar>
+template<typename _MatrixType>
+void IncompleteLUT<Scalar>::factorize(const _MatrixType& amat)
+{
+  using std::sqrt;
+  using std::swap;
+  using std::abs;
+
+  eigen_assert((amat.rows() == amat.cols()) && "The factorization should be done on a square matrix");
+  int n = amat.cols();  // Size of the matrix
+  m_lu.resize(n,n);
+  // Declare Working vectors and variables
+  Vector u(n) ;     // real values of the row -- maximum size is n --
+  VectorXi ju(n);   // column position of the values in u -- maximum size  is n
+  VectorXi jr(n);   // Indicate the position of the nonzero elements in the vector u -- A zero location is indicated by -1
+
+  // Apply the fill-reducing permutation
+  eigen_assert(m_analysisIsOk && "You must first call analyzePattern()");
+  SparseMatrix<Scalar,RowMajor, Index> mat;
+  mat = amat.twistedBy(m_Pinv);
+
+  // Initialization
+  jr.fill(-1);
+  ju.fill(0);
+  u.fill(0);
+
+  // number of largest elements to keep in each row:
+  int fill_in =   static_cast<int> (amat.nonZeros()*m_fillfactor)/n+1;
+  if (fill_in > n) fill_in = n;
+
+  // number of largest nonzero elements to keep in the L and the U part of the current row:
+  int nnzL = fill_in/2;
+  int nnzU = nnzL;
+  m_lu.reserve(n * (nnzL + nnzU + 1));
+
+  // global loop over the rows of the sparse matrix
+  for (int ii = 0; ii < n; ii++)
+  {
+    // 1 - copy the lower and the upper part of the row i of mat in the working vector u
+
+    int sizeu = 1; // number of nonzero elements in the upper part of the current row
+    int sizel = 0; // number of nonzero elements in the lower part of the current row
+    ju(ii)    = ii;
+    u(ii)     = 0;
+    jr(ii)    = ii;
+    RealScalar rownorm = 0;
+
+    typename FactorType::InnerIterator j_it(mat, ii); // Iterate through the current row ii
+    for (; j_it; ++j_it)
+    {
+      int k = j_it.index();
+      if (k < ii)
+      {
+        // copy the lower part
+        ju(sizel) = k;
+        u(sizel) = j_it.value();
+        jr(k) = sizel;
+        ++sizel;
+      }
+      else if (k == ii)
+      {
+        u(ii) = j_it.value();
+      }
+      else
+      {
+        // copy the upper part
+        int jpos = ii + sizeu;
+        ju(jpos) = k;
+        u(jpos) = j_it.value();
+        jr(k) = jpos;
+        ++sizeu;
+      }
+      rownorm += internal::abs2(j_it.value());
+    }
+
+    // 2 - detect possible zero row
+    if(rownorm==0)
+    {
+      m_info = NumericalIssue;
+      return;
+    }
+    // Take the 2-norm of the current row as a relative tolerance
+    rownorm = sqrt(rownorm);
+
+    // 3 - eliminate the previous nonzero rows
+    int jj = 0;
+    int len = 0;
+    while (jj < sizel)
+    {
+      // In order to eliminate in the correct order,
+      // we must select first the smallest column index among  ju(jj:sizel)
+      int k;
+      int minrow = ju.segment(jj,sizel-jj).minCoeff(&k); // k is relative to the segment
+      k += jj;
+      if (minrow != ju(jj))
+      {
+        // swap the two locations
+        int j = ju(jj);
+        swap(ju(jj), ju(k));
+        jr(minrow) = jj;   jr(j) = k;
+        swap(u(jj), u(k));
+      }
+      // Reset this location
+      jr(minrow) = -1;
+
+      // Start elimination
+      typename FactorType::InnerIterator ki_it(m_lu, minrow);
+      while (ki_it && ki_it.index() < minrow) ++ki_it;
+      eigen_internal_assert(ki_it && ki_it.col()==minrow);
+      Scalar fact = u(jj) / ki_it.value();
+
+      // drop too small elements
+      if(abs(fact) <= m_droptol)
+      {
+        jj++;
+        continue;
+      }
+
+      // linear combination of the current row ii and the row minrow
+      ++ki_it;
+      for (; ki_it; ++ki_it)
+      {
+        Scalar prod = fact * ki_it.value();
+        int j       = ki_it.index();
+        int jpos    = jr(j);
+        if (jpos == -1) // fill-in element
+        {
+          int newpos;
+          if (j >= ii) // dealing with the upper part
+          {
+            newpos = ii + sizeu;
+            sizeu++;
+            eigen_internal_assert(sizeu<=n);
+          }
+          else // dealing with the lower part
+          {
+            newpos = sizel;
+            sizel++;
+            eigen_internal_assert(sizel<ii);
+          }
+          ju(newpos) = j;
+          u(newpos) = -prod;
+          jr(j) = newpos;
+        }
+        else
+          u(jpos) -= prod;
+      }
+      // store the pivot element
+      u(len) = fact;
+      ju(len) = minrow;
+      ++len;
+
+      jj++;
+    } // end of the elimination on the row ii
+
+    // reset the upper part of the pointer jr to zero
+    for(int k = 0; k <sizeu; k++) jr(ju(ii+k)) = -1;
+
+    // 4 - partially sort and insert the elements in the m_lu matrix
+
+    // sort the L-part of the row
+    sizel = len;
+    len = (std::min)(sizel, nnzL);
+    typename Vector::SegmentReturnType ul(u.segment(0, sizel));
+    typename VectorXi::SegmentReturnType jul(ju.segment(0, sizel));
+    QuickSplit(ul, jul, len);
+
+    // store the largest m_fill elements of the L part
+    m_lu.startVec(ii);
+    for(int k = 0; k < len; k++)
+      m_lu.insertBackByOuterInnerUnordered(ii,ju(k)) = u(k);
+
+    // store the diagonal element
+    // apply a shifting rule to avoid zero pivots (we are doing an incomplete factorization)
+    if (u(ii) == Scalar(0))
+      u(ii) = sqrt(m_droptol) * rownorm;
+    m_lu.insertBackByOuterInnerUnordered(ii, ii) = u(ii);
+
+    // sort the U-part of the row
+    // apply the dropping rule first
+    len = 0;
+    for(int k = 1; k < sizeu; k++)
+    {
+      if(abs(u(ii+k)) > m_droptol * rownorm )
+      {
+        ++len;
+        u(ii + len)  = u(ii + k);
+        ju(ii + len) = ju(ii + k);
+      }
+    }
+    sizeu = len + 1; // +1 to take into account the diagonal element
+    len = (std::min)(sizeu, nnzU);
+    typename Vector::SegmentReturnType uu(u.segment(ii+1, sizeu-1));
+    typename VectorXi::SegmentReturnType juu(ju.segment(ii+1, sizeu-1));
+    QuickSplit(uu, juu, len);
+
+    // store the largest elements of the U part
+    for(int k = ii + 1; k < ii + len; k++)
+      m_lu.insertBackByOuterInnerUnordered(ii,ju(k)) = u(k);
+  }
+
+  m_lu.finalize();
+  m_lu.makeCompressed();
+
+  m_factorizationIsOk = true;
+  m_info = Success;
+}
 
 namespace internal {