filtlan.h

Go to the documentation of this file.

#ifndef FILTLAN_H
#define FILTLAN_H

#include "laneig.h"
#include "polyfilt.h"

#ifdef USE_NAMESPACE
using namespace MATKIT;
namespace MATKIT {
#endif

class Vector;
class Matrix;
class SparseMatrix;

#ifdef USE_NAMESPACE
}  // end of namespace MATKIT
#endif


// an instance of this class, taken by FilteredLanczosEigenSolver(), is a collection of options for the filtered Lanczos procedure to solve symmetric eigenvalue problems
struct FilteredLanczosOptions: public LanczosOptions {

    // this parameter tells whether eigenvalues are wanted or not (default true)
    // note that the filtered Lanczos procedure computes the eigenvectors first
    // the computation of eigenvalues is unnecessary if only the invariant subspace is required
    // note that the option wantEigVec inherited from LanczosOptions is no longer effective in the filtered Lanczos procedure
    bool wantEigVal;

    // neigWanted is the number of eigenvalues/eigenvectors desired
    // if nev == 0 is given (the default), then it means that all eigenvalues/eigenvectors in the requested interval are to be sought
    // otherwise, let nev be the number of eigenvalues in the requested interval
    //    if nev <= neigWanted, then the iteration continues until all nev eigenvalues/eigenvectors in the requested interval converge
    //    if nev >  neigWanted, then the iteration stops when neigWanted eigenvalues in the requested interval converge
    mkIndex neigWanted;

    // number of Lanczos iterations to determine an interval which (tightly) contains all eigenvalues (default 30)
    // the filtered Lanczos procedure requires an interval which (tightly) contains all eigenvalues
    // if it is not provided, then we use a standard Lanczos procedure with numIterForEigenRange iterations to compute one
    // the higher the numIterForEigenRange, the tighter the interval
    mkIndex numIterForEigenRange;

    // a collection of options to determine the intervals
    IntervalOptions intervalOpts;

    // a constructor to set default options
    FilteredLanczosOptions() {
        wantEigVal = true;          // filtered Lanczos computes eigenvectors first;
                                    // if only the invariant subspace is wanted, then the computation of eigenvalues is not required,
                                    // in which case wantEigVal can be set false
        neigWanted = 0;             // means to compute all eigenvalues in the given range
                                    // if neigWanted > 0, then quit the Lanczos loop when neigWanted eigenvalues are found in the specified range,
                                    //                    or when all ( < neigWanted ) eigenvalues are found in the specified range
        numIterForEigenRange = 30;  // number of Lanczos iterations to determine the eigen-range
        extraIter = 20;             // laneig has the default extraIter==60
                                    // filtlan requires less extraIter for comparable accuracy of eigenvalues
        defaultMinIterFactor = 2;   // likewise, filtlan can have less defaultMinIterFactor,
        defaultMaxIterFactor = 30;  // and also defaultMaxIterFactor than laneig
    }
};

// FilteredLanczosEigenSolver() returns an instance of this class which gives the information of the filtered Lanczos procedure
struct FilteredLanczosInfo: public LanczosInfo {
    // information about the Lanczos procedure to determine the range of eigenvalues by approximating the largest eigenvalue and the smallest eigenvalue, if this range is not provided
    LanczosInfo forEigenRangeInfo;
    // CPU time (in seconds) to determine the range of eigenvalues, if this range is not provided
    Real forEigenRangeCpuTime;

    // the range of eigenvalues is partitioned into intervals which determine the base filter approximated by a polynomial filter
    // the j-th interval is [intervals(j),intervals(j+1))
    Vector intervals;
};



// this routine computes the eigenvalues in the requested window and the corresponding eigenvectors
// the window can contain the largest or smallest eigenvalues, in which case the requested are the extreme eigenvalues
// the window can also be well inside the range of the spectrum, in which case it is often referred to as an interior eigenvalue problem
// eigVal is a vector which contains the computed eigenvalues (if opts.wantEigVal==true)
// eigVec is a matrix whose columns are computed eigenvectors
//     more precisely, eigVec(:,j) is the eigenvector corresponding to the eigenvalue eigVal(j)
// S is the sparse matrix whose eigenvalues / eigenvectors are to be sought
// frame is a vector of 2 or 4 elements
//     if frame consists of 2 elements, then [frame(1),frame(2)] is the interval in which the eigenvalues are sought
//     if frame consists of 4 elements, then [frame(2),frame(3)] is the interval in which the eigenvalues are sought, and
//                                           [frame(1),frame(4)] is the interval which (tightly) contains all eigenvalues
//     in the former case, an interval which contains (tightly) all eigenvalues is not given, and will be determined by a standard Lanczos procedure 
// polyDegree is the degree of s(z), with z*s(z) the polynomial filter
// baseDegree is the left-and-right degree of the base filter for each interval
// opts is a collection of options for the filtered Lanczos procedure
// the return FilteredLanczosInfo gives the information of the filtered Lanczos procedure
FilteredLanczosInfo FilteredLanczosEigenSolver(Vector &eigVal, Matrix &eigVec,
                                       const SparseMatrix &S, Vector &frame,
                                       mkIndex polyDegree, mkIndex baseDegree, FilteredLanczosOptions &opts);
  // end of group_filtlan


#endif