src/IterativeLinearSolvers/IncompleteLUT.h

0001 // This file is part of Eigen, a lightweight C++ template library
0002 // for linear algebra.
0003 //
0004 // Copyright (C) 2012 Désiré Nuentsa-Wakam <desire.nuentsa_wakam@inria.fr>
0005 // Copyright (C) 2014 Gael Guennebaud <gael.guennebaud@inria.fr>
0006 //
0007 // This Source Code Form is subject to the terms of the Mozilla
0008 // Public License v. 2.0. If a copy of the MPL was not distributed
0009 // with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
0010
0011 #ifndef EIGEN_INCOMPLETE_LUT_H
0012 #define EIGEN_INCOMPLETE_LUT_H
0013
0014
0015 namespace RivetEigen {
0016
0017 namespace internal {
0018
0019 /** \internal
0020   * Compute a quick-sort split of a vector
0021   * On output, the vector row is permuted such that its elements satisfy
0022   * abs(row(i)) >= abs(row(ncut)) if i<ncut
0023   * abs(row(i)) <= abs(row(ncut)) if i>ncut
0024   * \param row The vector of values
0025   * \param ind The array of index for the elements in @p row
0026   * \param ncut  The number of largest elements to keep
0027   **/
0028 template <typename VectorV, typename VectorI>
0029 Index QuickSplit(VectorV &row, VectorI &ind, Index ncut)
0030 {
0031   typedef typename VectorV::RealScalar RealScalar;
0032   using std::swap;
0033   using std::abs;
0034   Index mid;
0035   Index n = row.size(); /* length of the vector */
0036   Index first, last ;
0037
0038   ncut--; /* to fit the zero-based indices */
0039   first = 0;
0040   last = n-1;
0041   if (ncut < first || ncut > last ) return 0;
0042
0043   do {
0044     mid = first;
0045     RealScalar abskey = abs(row(mid));
0046     for (Index j = first + 1; j <= last; j++) {
0047       if ( abs(row(j)) > abskey) {
0048         ++mid;
0049         swap(row(mid), row(j));
0050         swap(ind(mid), ind(j));
0051       }
0052     }
0053     /* Interchange for the pivot element */
0054     swap(row(mid), row(first));
0055     swap(ind(mid), ind(first));
0056
0057     if (mid > ncut) last = mid - 1;
0058     else if (mid < ncut ) first = mid + 1;
0059   } while (mid != ncut );
0060
0061   return 0; /* mid is equal to ncut */
0062 }
0063
0064 }// end namespace internal
0065
0066 /** \ingroup IterativeLinearSolvers_Module
0067   * \class IncompleteLUT
0068   * \brief Incomplete LU factorization with dual-threshold strategy
0069   *
0070   * \implsparsesolverconcept
0071   *
0072   * During the numerical factorization, two dropping rules are used :
0073   *  1) any element whose magnitude is less than some tolerance is dropped.
0074   *    This tolerance is obtained by multiplying the input tolerance @p droptol
0075   *    by the average magnitude of all the original elements in the current row.
0076   *  2) After the elimination of the row, only the @p fill largest elements in
0077   *    the L part and the @p fill largest elements in the U part are kept
0078   *    (in addition to the diagonal element ). Note that @p fill is computed from
0079   *    the input parameter @p fillfactor which is used the ratio to control the fill_in
0080   *    relatively to the initial number of nonzero elements.
0081   *
0082   * The two extreme cases are when @p droptol=0 (to keep all the @p fill*2 largest elements)
0083   * and when @p fill=n/2 with @p droptol being different to zero.
0084   *
0085   * References : Yousef Saad, ILUT: A dual threshold incomplete LU factorization,
0086   *              Numerical Linear Algebra with Applications, 1(4), pp 387-402, 1994.
0087   *
0088   * NOTE : The following implementation is derived from the ILUT implementation
0089   * in the SPARSKIT package, Copyright (C) 2005, the Regents of the University of Minnesota
0090   *  released under the terms of the GNU LGPL:
0091   *    http://www-users.cs.umn.edu/~saad/software/SPARSKIT/README
0092   * However, Yousef Saad gave us permission to relicense his ILUT code to MPL2.
0093   * See the Eigen mailing list archive, thread: ILUT, date: July 8, 2012:
0094   *   http://listengine.tuxfamily.org/lists.tuxfamily.org/eigen/2012/07/msg00064.html
0095   * alternatively, on GMANE:
0096   *   http://comments.gmane.org/gmane.comp.lib.eigen/3302
0097   */
0098 template <typename _Scalar, typename _StorageIndex = int>
0099 class IncompleteLUT : public SparseSolverBase<IncompleteLUT<_Scalar, _StorageIndex> >
0100 {
0101   protected:
0102     typedef SparseSolverBase<IncompleteLUT> Base;
0103     using Base::m_isInitialized;
0104   public:
0105     typedef _Scalar Scalar;
0106     typedef _StorageIndex StorageIndex;
0107     typedef typename NumTraits<Scalar>::Real RealScalar;
0108     typedef Matrix<Scalar,Dynamic,1> Vector;
0109     typedef Matrix<StorageIndex,Dynamic,1> VectorI;
0110     typedef SparseMatrix<Scalar,RowMajor,StorageIndex> FactorType;
0111
0112     enum {
0113       ColsAtCompileTime = Dynamic,
0114       MaxColsAtCompileTime = Dynamic
0115     };
0116
0117   public:
0118
0119     IncompleteLUT()
0120       : m_droptol(NumTraits<Scalar>::dummy_precision()), m_fillfactor(10),
0121         m_analysisIsOk(false), m_factorizationIsOk(false)
0122     {}
0123
0124     template<typename MatrixType>
0125     explicit IncompleteLUT(const MatrixType& mat, const RealScalar& droptol=NumTraits<Scalar>::dummy_precision(), int fillfactor = 10)
0126       : m_droptol(droptol),m_fillfactor(fillfactor),
0127         m_analysisIsOk(false),m_factorizationIsOk(false)
0128     {
0129       eigen_assert(fillfactor != 0);
0130       compute(mat);
0131     }
0132
0133     EIGEN_CONSTEXPR Index rows() const EIGEN_NOEXCEPT { return m_lu.rows(); }
0134
0135     EIGEN_CONSTEXPR Index cols() const EIGEN_NOEXCEPT { return m_lu.cols(); }
0136
0137     /** \brief Reports whether previous computation was successful.
0138       *
0139       * \returns \c Success if computation was successful,
0140       *          \c NumericalIssue if the matrix.appears to be negative.
0141       */
0142     ComputationInfo info() const
0143     {
0144       eigen_assert(m_isInitialized && "IncompleteLUT is not initialized.");
0145       return m_info;
0146     }
0147
0148     template<typename MatrixType>
0149     void analyzePattern(const MatrixType& amat);
0150
0151     template<typename MatrixType>
0152     void factorize(const MatrixType& amat);
0153
0154     /**
0155       * Compute an incomplete LU factorization with dual threshold on the matrix mat
0156       * No pivoting is done in this version
0157       *
0158       **/
0159     template<typename MatrixType>
0160     IncompleteLUT& compute(const MatrixType& amat)
0161     {
0162       analyzePattern(amat);
0163       factorize(amat);
0164       return *this;
0165     }
0166
0167     void setDroptol(const RealScalar& droptol);
0168     void setFillfactor(int fillfactor);
0169
0170     template<typename Rhs, typename Dest>
0171     void _solve_impl(const Rhs& b, Dest& x) const
0172     {
0173       x = m_Pinv * b;
0174       x = m_lu.template triangularView<UnitLower>().solve(x);
0175       x = m_lu.template triangularView<Upper>().solve(x);
0176       x = m_P * x;
0177     }
0178
0179 protected:
0180
0181     /** keeps off-diagonal entries; drops diagonal entries */
0182     struct keep_diag {
0183       inline bool operator() (const Index& row, const Index& col, const Scalar&) const
0184       {
0185         return row!=col;
0186       }
0187     };
0188
0189 protected:
0190
0191     FactorType m_lu;
0192     RealScalar m_droptol;
0193     int m_fillfactor;
0194     bool m_analysisIsOk;
0195     bool m_factorizationIsOk;
0196     ComputationInfo m_info;
0197     PermutationMatrix<Dynamic,Dynamic,StorageIndex> m_P;     // Fill-reducing permutation
0198     PermutationMatrix<Dynamic,Dynamic,StorageIndex> m_Pinv;  // Inverse permutation
0199 };
0200
0201 /**
0202  * Set control parameter droptol
0203  *  \param droptol   Drop any element whose magnitude is less than this tolerance
0204  **/
0205 template<typename Scalar, typename StorageIndex>
0206 void IncompleteLUT<Scalar,StorageIndex>::setDroptol(const RealScalar& droptol)
0207 {
0208   this->m_droptol = droptol;
0209 }
0210
0211 /**
0212  * Set control parameter fillfactor
0213  * \param fillfactor  This is used to compute the  number @p fill_in of largest elements to keep on each row.
0214  **/
0215 template<typename Scalar, typename StorageIndex>
0216 void IncompleteLUT<Scalar,StorageIndex>::setFillfactor(int fillfactor)
0217 {
0218   this->m_fillfactor = fillfactor;
0219 }
0220
0221 template <typename Scalar, typename StorageIndex>
0222 template<typename _MatrixType>
0223 void IncompleteLUT<Scalar,StorageIndex>::analyzePattern(const _MatrixType& amat)
0224 {
0225   // Compute the Fill-reducing permutation
0226   // Since ILUT does not perform any numerical pivoting,
0227   // it is highly preferable to keep the diagonal through symmetric permutations.
0228   // To this end, let's symmetrize the pattern and perform AMD on it.
0229   SparseMatrix<Scalar,ColMajor, StorageIndex> mat1 = amat;
0230   SparseMatrix<Scalar,ColMajor, StorageIndex> mat2 = amat.transpose();
0231   // FIXME for a matrix with nearly symmetric pattern, mat2+mat1 is the appropriate choice.
0232   //       on the other hand for a really non-symmetric pattern, mat2*mat1 should be preferred...
0233   SparseMatrix<Scalar,ColMajor, StorageIndex> AtA = mat2 + mat1;
0234   AMDOrdering<StorageIndex> ordering;
0235   ordering(AtA,m_P);
0236   m_Pinv  = m_P.inverse(); // cache the inverse permutation
0237   m_analysisIsOk = true;
0238   m_factorizationIsOk = false;
0239   m_isInitialized = true;
0240 }
0241
0242 template <typename Scalar, typename StorageIndex>
0243 template<typename _MatrixType>
0244 void IncompleteLUT<Scalar,StorageIndex>::factorize(const _MatrixType& amat)
0245 {
0246   using std::sqrt;
0247   using std::swap;
0248   using std::abs;
0249   using internal::convert_index;
0250
0251   eigen_assert((amat.rows() == amat.cols()) && "The factorization should be done on a square matrix");
0252   Index n = amat.cols();  // Size of the matrix
0253   m_lu.resize(n,n);
0254   // Declare Working vectors and variables
0255   Vector u(n) ;     // real values of the row -- maximum size is n --
0256   VectorI ju(n);   // column position of the values in u -- maximum size  is n
0257   VectorI jr(n);   // Indicate the position of the nonzero elements in the vector u -- A zero location is indicated by -1
0258
0259   // Apply the fill-reducing permutation
0260   eigen_assert(m_analysisIsOk && "You must first call analyzePattern()");
0261   SparseMatrix<Scalar,RowMajor, StorageIndex> mat;
0262   mat = amat.twistedBy(m_Pinv);
0263
0264   // Initialization
0265   jr.fill(-1);
0266   ju.fill(0);
0267   u.fill(0);
0268
0269   // number of largest elements to keep in each row:
0270   Index fill_in = (amat.nonZeros()*m_fillfactor)/n + 1;
0271   if (fill_in > n) fill_in = n;
0272
0273   // number of largest nonzero elements to keep in the L and the U part of the current row:
0274   Index nnzL = fill_in/2;
0275   Index nnzU = nnzL;
0276   m_lu.reserve(n * (nnzL + nnzU + 1));
0277
0278   // global loop over the rows of the sparse matrix
0279   for (Index ii = 0; ii < n; ii++)
0280   {
0281     // 1 - copy the lower and the upper part of the row i of mat in the working vector u
0282
0283     Index sizeu = 1; // number of nonzero elements in the upper part of the current row
0284     Index sizel = 0; // number of nonzero elements in the lower part of the current row
0285     ju(ii)    = convert_index<StorageIndex>(ii);
0286     u(ii)     = 0;
0287     jr(ii)    = convert_index<StorageIndex>(ii);
0288     RealScalar rownorm = 0;
0289
0290     typename FactorType::InnerIterator j_it(mat, ii); // Iterate through the current row ii
0291     for (; j_it; ++j_it)
0292     {
0293       Index k = j_it.index();
0294       if (k < ii)
0295       {
0296         // copy the lower part
0297         ju(sizel) = convert_index<StorageIndex>(k);
0298         u(sizel) = j_it.value();
0299         jr(k) = convert_index<StorageIndex>(sizel);
0300         ++sizel;
0301       }
0302       else if (k == ii)
0303       {
0304         u(ii) = j_it.value();
0305       }
0306       else
0307       {
0308         // copy the upper part
0309         Index jpos = ii + sizeu;
0310         ju(jpos) = convert_index<StorageIndex>(k);
0311         u(jpos) = j_it.value();
0312         jr(k) = convert_index<StorageIndex>(jpos);
0313         ++sizeu;
0314       }
0315       rownorm += numext::abs2(j_it.value());
0316     }
0317
0318     // 2 - detect possible zero row
0319     if(rownorm==0)
0320     {
0321       m_info = NumericalIssue;
0322       return;
0323     }
0324     // Take the 2-norm of the current row as a relative tolerance
0325     rownorm = sqrt(rownorm);
0326
0327     // 3 - eliminate the previous nonzero rows
0328     Index jj = 0;
0329     Index len = 0;
0330     while (jj < sizel)
0331     {
0332       // In order to eliminate in the correct order,
0333       // we must select first the smallest column index among  ju(jj:sizel)
0334       Index k;
0335       Index minrow = ju.segment(jj,sizel-jj).minCoeff(&k); // k is relative to the segment
0336       k += jj;
0337       if (minrow != ju(jj))
0338       {
0339         // swap the two locations
0340         Index j = ju(jj);
0341         swap(ju(jj), ju(k));
0342         jr(minrow) = convert_index<StorageIndex>(jj);
0343         jr(j) = convert_index<StorageIndex>(k);
0344         swap(u(jj), u(k));
0345       }
0346       // Reset this location
0347       jr(minrow) = -1;
0348
0349       // Start elimination
0350       typename FactorType::InnerIterator ki_it(m_lu, minrow);
0351       while (ki_it && ki_it.index() < minrow) ++ki_it;
0352       eigen_internal_assert(ki_it && ki_it.col()==minrow);
0353       Scalar fact = u(jj) / ki_it.value();
0354
0355       // drop too small elements
0356       if(abs(fact) <= m_droptol)
0357       {
0358         jj++;
0359         continue;
0360       }
0361
0362       // linear combination of the current row ii and the row minrow
0363       ++ki_it;
0364       for (; ki_it; ++ki_it)
0365       {
0366         Scalar prod = fact * ki_it.value();
0367         Index j     = ki_it.index();
0368         Index jpos  = jr(j);
0369         if (jpos == -1) // fill-in element
0370         {
0371           Index newpos;
0372           if (j >= ii) // dealing with the upper part
0373           {
0374             newpos = ii + sizeu;
0375             sizeu++;
0376             eigen_internal_assert(sizeu<=n);
0377           }
0378           else // dealing with the lower part
0379           {
0380             newpos = sizel;
0381             sizel++;
0382             eigen_internal_assert(sizel<=ii);
0383           }
0384           ju(newpos) = convert_index<StorageIndex>(j);
0385           u(newpos) = -prod;
0386           jr(j) = convert_index<StorageIndex>(newpos);
0387         }
0388         else
0389           u(jpos) -= prod;
0390       }
0391       // store the pivot element
0392       u(len)  = fact;
0393       ju(len) = convert_index<StorageIndex>(minrow);
0394       ++len;
0395
0396       jj++;
0397     } // end of the elimination on the row ii
0398
0399     // reset the upper part of the pointer jr to zero
0400     for(Index k = 0; k <sizeu; k++) jr(ju(ii+k)) = -1;
0401
0402     // 4 - partially sort and insert the elements in the m_lu matrix
0403
0404     // sort the L-part of the row
0405     sizel = len;
0406     len = (std::min)(sizel, nnzL);
0407     typename Vector::SegmentReturnType ul(u.segment(0, sizel));
0408     typename VectorI::SegmentReturnType jul(ju.segment(0, sizel));
0409     internal::QuickSplit(ul, jul, len);
0410
0411     // store the largest m_fill elements of the L part
0412     m_lu.startVec(ii);
0413     for(Index k = 0; k < len; k++)
0414       m_lu.insertBackByOuterInnerUnordered(ii,ju(k)) = u(k);
0415
0416     // store the diagonal element
0417     // apply a shifting rule to avoid zero pivots (we are doing an incomplete factorization)
0418     if (u(ii) == Scalar(0))
0419       u(ii) = sqrt(m_droptol) * rownorm;
0420     m_lu.insertBackByOuterInnerUnordered(ii, ii) = u(ii);
0421
0422     // sort the U-part of the row
0423     // apply the dropping rule first
0424     len = 0;
0425     for(Index k = 1; k < sizeu; k++)
0426     {
0427       if(abs(u(ii+k)) > m_droptol * rownorm )
0428       {
0429         ++len;
0430         u(ii + len)  = u(ii + k);
0431         ju(ii + len) = ju(ii + k);
0432       }
0433     }
0434     sizeu = len + 1; // +1 to take into account the diagonal element
0435     len = (std::min)(sizeu, nnzU);
0436     typename Vector::SegmentReturnType uu(u.segment(ii+1, sizeu-1));
0437     typename VectorI::SegmentReturnType juu(ju.segment(ii+1, sizeu-1));
0438     internal::QuickSplit(uu, juu, len);
0439
0440     // store the largest elements of the U part
0441     for(Index k = ii + 1; k < ii + len; k++)
0442       m_lu.insertBackByOuterInnerUnordered(ii,ju(k)) = u(k);
0443   }
0444   m_lu.finalize();
0445   m_lu.makeCompressed();
0446
0447   m_factorizationIsOk = true;
0448   m_info = Success;
0449 }
0450
0451 } // end namespace RivetEigen
0452
0453 #endif // EIGEN_INCOMPLETE_LUT_H