#include <SymEigsSolver.h>

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

Public Member Functions
	SymEigsSolver (OpType *op_, int nev_, int ncv_)

void	init (Scalar *init_resid)

void	init ()

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

int	num_iterations ()

int	num_operations ()

Vector	eigenvalues ()

Matrix	eigenvectors (int nvec)

Matrix	eigenvectors ()

Detailed Description

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
class SymEigsSolver< Scalar, SelectionRule, OpType >

This class implements the eigen solver for real symmetric matrices.

ARPACK-Armadillo 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.

This class implements the eigen solver of a real symmetric matrix, but rather than providing the whole 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 Armadillo, for example arma::mat, then there is an easy way to construct such matrix operation class, by using the built-in wrapper class DenseGenMatProd which wraps an existing matrix object in Armadillo. This is also the default template parameter for SymEigsSolver.

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

Template Parameters

Scalar	The element type of the matrix. Currently supported types are `float` and `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 SelectionRule.h .
OpType	The name of the matrix operation class. Users could either use the DenseGenMatProd wrapper class, or define their own that impelemnts all the public member functions as in DenseGenMatProd.

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

#include <armadillo>
#include <SymEigsSolver.h>  // Also includes <MatOp/DenseGenMatProd.h>
int main()
{
    // We are going to calculate the eigenvalues of M
    arma::mat A = arma::randu(10, 10);
    arma::mat M = A + A.t();
    // Construct matrix operation object using the wrapper class DenseGenMatProd
    DenseGenMatProd<double> op(M);
    // Construct eigen solver object, requesting the largest three eigenvalues
    SymEigsSolver< double, LARGEST_ALGE, DenseGenMatProd<double> > eigs(&op, 3, 6);
    // Initialize and compute
    eigs.init();
    int nconv = eigs.compute();
    // Retrieve results
    arma::vec evalues;
    if(nconv > 0)
        evalues = eigs.eigenvalues();
    evalues.print("Eigenvalues found:");
    return 0;
}

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

#include <armadillo>
#include <SymEigsSolver.h>
// 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;
    SymEigsSolver<double, LARGEST_ALGE, MyDiagonalTen> eigs(&op, 3, 6);
    eigs.init();
    eigs.compute();
    arma::vec evalues = eigs.eigenvalues();
    evalues.print("Eigenvalues found:");
    return 0;
}

Definition at line 140 of file SymEigsSolver.h.

Constructor & Destructor Documentation

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>

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 \(Ay\) for any vector \(y\). Users could either create the object from the DenseGenMatProd wrapper class, 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-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 216 of file SymEigsSolver.h.

Member Function Documentation

template<typename Scalar , int SelectionRule, typename OpType >

void SymEigsSolver< Scalar, SelectionRule, OpType >::init ( Scalar * init_resid )

inline

Providing the initial residual vector for the algorithm.

Parameters

init_resid Pointer to the initial residual vector.

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

Definition at line 203 of file SymEigsSolver_Impl.h.

template<typename Scalar , int SelectionRule, typename OpType >

void SymEigsSolver< Scalar, SelectionRule, OpType >::init ( )

inline

Providing a random initial residual vector.

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

Definition at line 236 of file SymEigsSolver_Impl.h.

template<typename Scalar , int SelectionRule, typename OpType >

int SymEigsSolver< Scalar, SelectionRule, OpType >::compute	(	int	maxit = `1000`,
		Scalar	tol = `1e-10`
	)

inline

Conducting the major computation procedure.

Parameters

maxit	Maximum number of iterations allowed in the algorithm.
tol	Precision parameter for the calculated eigenvalues.

Returns: Number of converged eigenvalues.

Definition at line 247 of file SymEigsSolver_Impl.h.

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>

int SymEigsSolver< Scalar, SelectionRule, OpType >::num_iterations ( )

inline

Returning the number of iterations used in the computation.

Definition at line 265 of file SymEigsSolver.h.

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>

int SymEigsSolver< Scalar, SelectionRule, OpType >::num_operations ( )

inline

Returning the number of matrix operations used in the computation.

Definition at line 270 of file SymEigsSolver.h.

template<typename Scalar , int SelectionRule, typename OpType >

SymEigsSolver< Scalar, SelectionRule, OpType >::Vector SymEigsSolver< Scalar, SelectionRule, OpType >::eigenvalues ( )

inline

Returning the converged eigenvalues.

Returns: A vector containing the eigenvalues. Returned vector type will be arma::vec or arma::fvec, depending on the template parameter Scalar defined.

Definition at line 275 of file SymEigsSolver_Impl.h.

template<typename Scalar , int SelectionRule, typename OpType >

SymEigsSolver< Scalar, SelectionRule, OpType >::Matrix SymEigsSolver< Scalar, SelectionRule, OpType >::eigenvectors ( int nvec )

inline

Returning 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 arma::mat or arma::fmat, depending on the template parameter Scalar defined.

Definition at line 300 of file SymEigsSolver_Impl.h.

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>

Matrix SymEigsSolver< Scalar, SelectionRule, OpType >::eigenvectors ( )

inline

Returning all converged eigenvectors.

Definition at line 294 of file SymEigsSolver.h.

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

Public Member Functions

Detailed Description

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>> class SymEigsSolver< Scalar, SelectionRule, OpType >

Constructor & Destructor Documentation

Member Function Documentation

template<typename Scalar = double, int SelectionRule = LARGEST_MAGN, typename OpType = DenseGenMatProd<double>>
class SymEigsSolver< Scalar, SelectionRule, OpType >