Spectra
Spectra::GenEigsSolver< Scalar, SelectionRule, OpType > Class Template Reference

#include <GenEigsSolver.h>

Inheritance diagram for Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >:
Spectra::GenEigsComplexShiftSolver< Scalar, SelectionRule, OpType > Spectra::GenEigsRealShiftSolver< Scalar, SelectionRule, OpType >

Public Member Functions

 GenEigsSolver (OpType *op_, int nev_, int ncv_)
 
virtual ~GenEigsSolver ()
 
void init (const Scalar *init_resid)
 
void init ()
 
int compute (int maxit=1000, Scalar tol=1e-10, int sort_rule=LARGEST_MAGN)
 
int info () const
 
int num_iterations () const
 
int num_operations () const
 
ComplexVector eigenvalues () const
 
ComplexMatrix eigenvectors (int nvec) const
 
ComplexMatrix eigenvectors () const
 

Detailed Description

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
class Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >

This class implements the eigen solver for general real matrices, i.e., to solve \(Ax=\lambda x\) for a possibly non-symmetric \(A\) matrix.

Most of the background information documented in the SymEigsSolver class also applies to the GenEigsSolver class here, except that the eigenvalues and eigenvectors of a general matrix can now be complex-valued.

Template Parameters
ScalarThe element type of the matrix. Currently supported types are float, double and long double.
SelectionRuleAn enumeration value indicating the selection rule of the requested eigenvalues, for example LARGEST_MAGN to retrieve eigenvalues with the largest magnitude. The full list of enumeration values can be found in Enumerations.
OpTypeThe name of the matrix operation class. Users could either use the wrapper classes such as DenseGenMatProd and SparseGenMatProd, or define their own that impelemnts all the public member functions as in DenseGenMatProd.

An example that illustrates the usage of GenEigsSolver is give below:

#include <Eigen/Core>
#include <GenEigsSolver.h> // Also includes <MatOp/DenseGenMatProd.h>
#include <iostream>
using namespace Spectra;
int main()
{
// We are going to calculate the eigenvalues of M
Eigen::MatrixXd M = Eigen::MatrixXd::Random(10, 10);
// Construct matrix operation object using the wrapper class
// Construct eigen solver object, requesting the largest
// (in magnitude, or norm) three eigenvalues
// Initialize and compute
eigs.init();
int nconv = eigs.compute();
// Retrieve results
Eigen::VectorXcd evalues;
if(eigs.info() == SUCCESSFUL)
evalues = eigs.eigenvalues();
std::cout << "Eigenvalues found:\n" << evalues << std::endl;
return 0;
}

And also an example for sparse matrices:

#include <Eigen/Core>
#include <Eigen/SparseCore>
#include <GenEigsSolver.h>
#include <MatOp/SparseGenMatProd.h>
#include <iostream>
using namespace Spectra;
int main()
{
// A band matrix with 1 on the main diagonal, 2 on the below-main subdiagonal,
// and 3 on the above-main subdiagonal
const int n = 10;
Eigen::SparseMatrix<double> M(n, n);
M.reserve(Eigen::VectorXi::Constant(n, 3));
for(int i = 0; i < n; i++)
{
M.insert(i, i) = 1.0;
if(i > 0)
M.insert(i - 1, i) = 3.0;
if(i < n - 1)
M.insert(i + 1, i) = 2.0;
}
// Construct matrix operation object using the wrapper class SparseGenMatProd
// Construct eigen solver object, requesting the largest three eigenvalues
// Initialize and compute
eigs.init();
int nconv = eigs.compute();
// Retrieve results
Eigen::VectorXcd evalues;
if(eigs.info() == SUCCESSFUL)
evalues = eigs.eigenvalues();
std::cout << "Eigenvalues found:\n" << evalues << std::endl;
return 0;
}

Definition at line 137 of file GenEigsSolver.h.

Constructor & Destructor Documentation

◆ GenEigsSolver()

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >::GenEigsSolver ( OpType *  op_,
int  nev_,
int  ncv_ 
)
inline

Constructor to create a solver object.

Parameters
op_Pointer to the matrix operation object, which should implement the matrix-vector multiplication operation of \(A\): calculating \(Av\) for any vector \(v\). Users could either create the object from the wrapper class such as DenseGenMatProd, or define their own that impelemnts all the public member functions as in DenseGenMatProd.
nev_Number of eigenvalues requested. This should satisfy \(1\le nev \le n-2\), where \(n\) is the size of matrix.
ncv_Parameter that controls the convergence speed of the algorithm. Typically a larger ncv_ means faster convergence, but it may also result in greater memory use and more matrix operations in each iteration. This parameter must satisfy \(nev+2 \le ncv \le n\), and is advised to take \(ncv \ge 2\cdot nev + 1\).

Definition at line 480 of file GenEigsSolver.h.

◆ ~GenEigsSolver()

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
virtual Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >::~GenEigsSolver ( )
inlinevirtual

Virtual destructor

Definition at line 501 of file GenEigsSolver.h.

Member Function Documentation

◆ init() [1/2]

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
void Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >::init ( const Scalar *  init_resid)
inline

Initializes the solver by providing an initial residual vector.

Parameters
init_residPointer to the initial residual vector.

Spectra (and also ARPACK) uses an iterative algorithm to find eigenvalues. This function allows the user to provide the initial residual vector.

Definition at line 512 of file GenEigsSolver.h.

◆ init() [2/2]

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
void Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >::init ( )
inline

Initializes the solver by providing a random initial residual vector.

This overloaded function generates a random initial residual vector (with a fixed random seed) for the algorithm. Elements in the vector follow independent Uniform(-0.5, 0.5) distribution.

Definition at line 555 of file GenEigsSolver.h.

◆ compute()

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
int Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >::compute ( int  maxit = 1000,
Scalar  tol = 1e-10,
int  sort_rule = LARGEST_MAGN 
)
inline

Conducts the major computation procedure.

Parameters
maxitMaximum number of iterations allowed in the algorithm.
tolPrecision parameter for the calculated eigenvalues.
sort_ruleRule to sort the eigenvalues and eigenvectors. Supported values are Spectra::LARGEST_MAGN, Spectra::LARGEST_REAL, Spectra::LARGEST_IMAG, Spectra::SMALLEST_MAGN, Spectra::SMALLEST_REAL and Spectra::SMALLEST_IMAG, for example LARGEST_MAGN indicates that eigenvalues with largest magnitude come first. Note that this argument is only used to sort the final result, and the selection rule (e.g. selecting the largest or smallest eigenvalues in the full spectrum) is specified by the template parameter SelectionRule of GenEigsSolver.
Returns
Number of converged eigenvalues.

Definition at line 582 of file GenEigsSolver.h.

◆ info()

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
int Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >::info ( ) const
inline

Returns the status of the computation. The full list of enumeration values can be found in Enumerations.

Definition at line 611 of file GenEigsSolver.h.

◆ num_iterations()

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
int Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >::num_iterations ( ) const
inline

Returns the number of iterations used in the computation.

Definition at line 616 of file GenEigsSolver.h.

◆ num_operations()

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
int Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >::num_operations ( ) const
inline

Returns the number of matrix operations used in the computation.

Definition at line 621 of file GenEigsSolver.h.

◆ eigenvalues()

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
ComplexVector Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >::eigenvalues ( ) const
inline

Returns the converged eigenvalues.

Returns
A complex-valued vector containing the eigenvalues. Returned vector type will be Eigen::Vector<std::complex<Scalar>, ...>, depending on the template parameter Scalar defined.

Definition at line 630 of file GenEigsSolver.h.

◆ eigenvectors() [1/2]

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
ComplexMatrix Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >::eigenvectors ( int  nvec) const
inline

Returns the eigenvectors associated with the converged eigenvalues.

Parameters
nvecThe number of eigenvectors to return.
Returns
A complex-valued matrix containing the eigenvectors. Returned matrix type will be Eigen::Matrix<std::complex<Scalar>, ...>, depending on the template parameter Scalar defined.

Definition at line 660 of file GenEigsSolver.h.

◆ eigenvectors() [2/2]

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
ComplexMatrix Spectra::GenEigsSolver< Scalar, SelectionRule, OpType >::eigenvectors ( ) const
inline

Returns all converged eigenvectors.

Definition at line 688 of file GenEigsSolver.h.


The documentation for this class was generated from the following file: