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

#include <SymEigsSolver.h>

Inheritance diagram for Spectra::SymEigsSolver< Scalar, SelectionRule, OpType >:

## Public Member Functions

SymEigsSolver (OpType *op, int nev, int ncv)

virtual ~SymEigsSolver ()

void init (const Scalar *init_resid)

void init ()

int compute (int maxit=1000, Scalar tol=1e-10, int sort_rule=LARGEST_ALGE)

int info () const

int num_iterations () const

int num_operations () const

Vector eigenvalues () const

virtual Matrix eigenvectors (int nvec) const

virtual Matrix eigenvectors () const

## Detailed Description

### template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseSymMatProd<double>> class Spectra::SymEigsSolver< Scalar, SelectionRule, OpType >

This class implements the eigen solver for real symmetric matrices, i.e., to solve $$Ax=\lambda x$$ where $$A$$ is symmetric.

Spectra is designed to calculate a specified number ( $$k$$) of eigenvalues of a large square matrix ( $$A$$). Usually $$k$$ is much less than the size of the matrix ( $$n$$), so that only a few eigenvalues and eigenvectors are computed.

Rather than providing the whole $$A$$ matrix, the algorithm only requires the matrix-vector multiplication operation of $$A$$. Therefore, users of this solver need to supply a class that computes the result of $$Av$$ for any given vector $$v$$. The name of this class should be given to the template parameter OpType, and instance of this class passed to the constructor of SymEigsSolver.

If the matrix $$A$$ is already stored as a matrix object in Eigen, for example Eigen::MatrixXd, then there is an easy way to construct such matrix operation class, by using the built-in wrapper class DenseSymMatProd which wraps an existing matrix object in Eigen. This is also the default template parameter for SymEigsSolver. For sparse matrices, the wrapper class SparseSymMatProd can be used similarly.

If the users need to define their own matrix-vector multiplication operation class, it should implement all the public member functions as in DenseSymMatProd.

Template Parameters
 Scalar The element type of the matrix. Currently supported types are float, double and long double. SelectionRule An 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. OpType The name of the matrix operation class. Users could either use the wrapper classes such as DenseSymMatProd and SparseSymMatProd, or define their own that impelemnts all the public member functions as in DenseSymMatProd.

Below is an example that demonstrates the usage of this class.

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

And here is an example for user-supplied matrix operation class.

#include <Eigen/Core>
#include <SymEigsSolver.h>
#include <iostream>
using namespace Spectra;
// M = diag(1, 2, ..., 10)
class MyDiagonalTen
{
public:
int rows() { return 10; }
int cols() { return 10; }
// y_out = M * x_in
void perform_op(double *x_in, double *y_out)
{
for(int i = 0; i < rows(); i++)
{
y_out[i] = x_in[i] * (i + 1);
}
}
};
int main()
{
MyDiagonalTen op;
eigs.init();
eigs.compute();
if(eigs.info() == SUCCESSFUL)
{
Eigen::VectorXd evalues = eigs.eigenvalues();
// Will get (10, 9, 8)
std::cout << "Eigenvalues found:\n" << evalues << std::endl;
}
return 0;
}

Definition at line 156 of file SymEigsSolver.h.

## ◆ SymEigsSolver()

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseSymMatProd<double>>
 Spectra::SymEigsSolver< Scalar, SelectionRule, OpType >::SymEigsSolver ( 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 DenseSymMatProd, or define their own that impelements all the public member functions as in DenseSymMatProd. nev Number of eigenvalues requested. This should satisfy $$1\le nev \le n-1$$, 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 < ncv \le n$$, and is advised to take $$ncv \ge 2\cdot nev$$.

Definition at line 505 of file SymEigsSolver.h.

## ◆ ~SymEigsSolver()

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

Virtual destructor

Definition at line 527 of file SymEigsSolver.h.

## ◆ init() [1/2]

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

Initializes the solver by providing an initial residual vector.

Parameters
 init_resid Pointer 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 538 of file SymEigsSolver.h.

## ◆ init() [2/2]

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseSymMatProd<double>>
 void Spectra::SymEigsSolver< 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 589 of file SymEigsSolver.h.

## ◆ compute()

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

Conducts the major computation procedure.

Parameters
 maxit Maximum number of iterations allowed in the algorithm. tol Precision parameter for the calculated eigenvalues. sort_rule Rule to sort the eigenvalues and eigenvectors. Supported values are Spectra::LARGEST_ALGE, Spectra::LARGEST_MAGN, Spectra::SMALLEST_ALGE and Spectra::SMALLEST_MAGN, for example LARGEST_ALGE indicates that largest eigenvalues 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 SymEigsSolver.
Returns
Number of converged eigenvalues.

Definition at line 614 of file SymEigsSolver.h.

## ◆ info()

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseSymMatProd<double>>
 int Spectra::SymEigsSolver< 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 643 of file SymEigsSolver.h.

## ◆ num_iterations()

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

Returns the number of iterations used in the computation.

Definition at line 648 of file SymEigsSolver.h.

## ◆ num_operations()

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

Returns the number of matrix operations used in the computation.

Definition at line 653 of file SymEigsSolver.h.

## ◆ eigenvalues()

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseSymMatProd<double>>
 Vector Spectra::SymEigsSolver< Scalar, SelectionRule, OpType >::eigenvalues ( ) const
inline

Returns the converged eigenvalues.

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

Definition at line 662 of file SymEigsSolver.h.

## ◆ eigenvectors() [1/2]

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseSymMatProd<double>>
 virtual Matrix Spectra::SymEigsSolver< Scalar, SelectionRule, OpType >::eigenvectors ( int nvec ) const
inlinevirtual

Returns the eigenvectors associated with the converged eigenvalues.

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

Definition at line 692 of file SymEigsSolver.h.

## ◆ eigenvectors() [2/2]

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseSymMatProd<double>>
 virtual Matrix Spectra::SymEigsSolver< Scalar, SelectionRule, OpType >::eigenvectors ( ) const
inlinevirtual

Returns all converged eigenvectors.

Definition at line 720 of file SymEigsSolver.h.

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