`ezarpack/solver_symmetric.hpp` - symmetric real eigenproblems¶

template<typename Backend> class arpack_solver<Symmetric, Backend>¶

Main solver class wrapping the Implicitly Restarted Lanczos Method (IRLM) for real symmetric eigenproblems.

This specialization of arpack_solver calls ARPACK-NG routines dsaupd() and dseupd() to compute approximations to a few eigenpairs of a linear operator \( \hat O \) that is real and symmetric with respect to a real positive semi-definite symmetric matrix \( \hat B \). In other words,

\[ \langle \mathbf{x},\hat O \mathbf{y} \rangle = \langle \hat O \mathbf{x}, \mathbf{y} \rangle \]

for all vectors \( \mathbf{x} \), \( \mathbf{y} \) and with the scalar product defined as

\[ \langle \mathbf{x}, \mathbf{y} \rangle = \mathbf{x}^T \hat B \mathbf{y}. \]

A variant of the Lanczos algorithm is internally used instead of the Arnoldi iteration for this class of problems.

Template Parameters:: Backend – Tag type specifying what storage backend (matrix/vector algebra library) must be used by arpack_solver. The storage backend determines types of internally stored data arrays and input/output view objects returned by methods of the class.

Backend-specific array and view types

using real_vector_t = typename storage::real_vector_type¶: One-dimensional data array (vector) of real numbers.

using real_matrix_t = typename storage::real_matrix_type¶: Two-dimensional data array (matrix) of real numbers.

using int_vector_t = typename storage::int_vector_type¶: One-dimensional data array (vector) of integers.

using real_vector_view_t = typename storage::real_vector_view_type¶: Partial view (slice) of a real vector.

using real_vector_const_view_t = typename storage::real_vector_const_view_type¶: Partial constant view (slice) of a real vector.

using real_matrix_const_view_t = typename storage::real_matrix_const_view_type¶: Partial constant view (slice) of a real matrix.

using vector_const_view_t = real_vector_const_view_t ¶: Storage-specific view type to expose real input vectors \( \mathbf{x} \). An argument of this type is passed as input to callable objects representing linear operators \( \hat O \) and \( \hat B \).

using vector_view_t = real_vector_view_t ¶: Storage-specific view type to expose real output vectors \( \mathbf{y} \). An argument of this type receives output from callable objects representing linear operators \( \hat O \) and \( \hat B \).

Public Types

enum Mode¶

Computational modes for generalized eigenproblems.

Values:

enumerator Inverse¶

Regular inverse mode.

Solve a generalized eigenproblem \( \hat A\mathbf{x} = \lambda \hat M\mathbf{x} \) by reduction to the canonical form with \( \hat O = \hat M^{-1} \hat A \) and \( \hat B = \hat M \), where \( \hat A \) is symmetric and \( \hat M \) is symmetric positive-definite.

enumerator ShiftAndInvert¶

Shift-and-Invert mode.

Solve a generalized eigenproblem \( \hat A\mathbf{x} = \lambda \hat M\mathbf{x} \) by reduction to the canonical form with \( \hat O = (\hat A - \sigma\hat M)^{-1} \hat M \) and \( \hat B = \hat M \), where \( \hat A \) is symmetric and \( \hat M \) is symmetric positive semi-definite.

enumerator Buckling¶

Buckling mode.

Solve a generalized eigenproblem \( \hat K\mathbf{x} = \lambda \hat K_G\mathbf{x} \) by reduction to the canonical form with \( \hat O = (\hat K - \sigma\hat K_G)^{-1} \hat K \) and \( \hat B = \hat K \), where \( \hat K \) is symmetric positive semi-definite and \( \hat K_G \) is symmetric indefinite.

enumerator Cayley¶

Cayley mode.

Solve a generalized eigenproblem \( \hat A\mathbf{x} = \lambda \hat M\mathbf{x} \) by reduction to the canonical form with \(\hat O = (\hat A -\sigma\hat M)^{-1}(\hat A +\sigma M)\) and \( \hat B = \hat M \), where \( \hat A \) is symmetric and \( \hat M \) is symmetric positive semi-definite.

Public Functions

inline arpack_solver(unsigned int N)¶

Constructs a solver object and allocates internal data buffers to be used by ARPACK-NG.

Parameters:: N – Dimension of the eigenproblem.

template<typename A, typename ShiftsF = exact_shifts_f> inline void operator()(A &&a, params_t const &params, ShiftsF shifts_f = {})¶

Solve a standard eigenproblem \( \hat A\mathbf{x} = \lambda\mathbf{x}\).

Parameters:

a – A callable object representing the linear operator \( \hat A \). It must take two arguments,
```
a(vector_const_view_t in, vector_view_t out)
```
a is expected to act on the vector view in and write the result into the vector view out, out = a*in. Given an instance as of the arpack_solver< Symmetric, Backend > class, in is also indirectly accessible as
```
as.workspace_vector(as.in_vector_n())
```
and out is accessible as
```
as.workspace_vector(as.out_vector_n())
```
params – Set of input parameters for the Implicitly Restarted Lanczos Method.
shifts_f – Functor that implements a shift selection strategy for the implicit restarts. For the expected signature of the functor, see exact_shifts_f::operator()(). When this argument is omitted, the default “Exact Shift Strategy” is used, which is the right choice in most cases.

Throws:

ezarpack::ncv_insufficient – No shifts could be applied during a cycle of the IRL iteration.
ezarpack::maxiter_reached – Maximum number of IRL iterations has been reached. All possible eigenvalues of \( \hat O \) have been found.
std::runtime_error – Invalid input parameters and other errors reported by ARPACK-NG routines dsaupd() and dseupd().

template<typename OP, typename B, typename ShiftsF = exact_shifts_f> inline void operator()(OP &&op, B &&b, Mode mode, params_t const &params, ShiftsF shifts_f = {})¶

Solve a generalized eigenproblem \( \hat A\mathbf{x} = \lambda\hat M\mathbf{x}\).

Operators \( \hat O \) and \( \hat B \) mentioned below are related to \( \hat A \) and \( \hat M \) via a Mode -dependent spectral transformation.

Parameters:

op – A callable object representing the linear operator \( \hat O \). It must take two arguments,
```
op(vector_view_t in, vector_view_t out)
```
In all computational modes except for Inverse, op is expected to act on the vector view in and write the result into the vector view out, out = op*in. In the Inverse mode, however, op must do the following, in = op*in, out = M^{-1}*in. Given an instance as of the arpack_solver< Symmetric, Backend > class, in is also indirectly accessible as
```
as.workspace_vector(as.in_vector_n())
```
and out is accessible as
```
as.workspace_vector(as.out_vector_n())
```
b – A callable object representing the linear operator \( \hat B \). It must take two arguments,
```
b(vector_const_view_t in, vector_view_t out)
```
b is expected to act on the vector view in and write the result into the vector view out, out = b*in.
mode – Computational mode to be used.
params – Set of input parameters for the Implicitly Restarted Lanczos Method.
shifts_f – Functor that implements a shift selection strategy for the implicit restarts. For the expected signature of the functor, see exact_shifts_f::operator()(). When this argument is omitted, the default “Exact Shift Strategy” is used, which is the right choice in most cases.

Throws:

ezarpack::ncv_insufficient – No shifts could be applied during a cycle of the IRL iteration.
ezarpack::maxiter_reached – Maximum number of IRL iterations has been reached. All possible eigenvalues of \( \hat O \) have been found.
std::runtime_error – Invalid input parameters and other errors reported by ARPACK-NG routines dsaupd() and dseupd().

inline int dim() const¶: Returns dimension of the eigenproblem.

inline int in_vector_n() const¶: Returns the index of the workspace vector, which is currently expected to be acted upon by linear operator \( \hat O \) or \( \hat B \).

inline int out_vector_n() const¶: Returns the index of the workspace vector, which is currently expected to receive result from application of linear operator \( \hat O \) or \( \hat B \).

inline real_vector_view_t workspace_vector(int n)¶

Returns a view of a vector within ARPACK-NG’s workspace array.

Parameters:: n – Index of the workspace vector. Valid values are 0, 1 and 2.
Throws:: std::runtime_error – Invalid index value.

inline unsigned int nconv() const¶: Number of “converged” Ritz values.

inline real_vector_const_view_t eigenvalues() const¶

Returns a constant view of a list of nconv() eigenvalues.

The values in the list are in ascending order.

Note

In the generalized eigenproblem modes, this method always returns eigenvalues of the original problem.

inline real_matrix_const_view_t eigenvectors() const¶

Returns a constant view of a matrix, whose nconv() columns are converged Ritz basis vectors (eigenvectors).

Throws:: std::runtime_error – Ritz vectors have not been computed in the last IRLM run.

inline real_vector_view_t residual_vector()¶

Returns a view of the current residual vector.

When params_t::random_residual_vector is set to false, the view returned by this accessor can be used to set the initial residual vector.

inline bool Bx_available() const¶: Has \( \hat B\mathbf{x} \) already been computed at the current IRLM iteration?

inline real_vector_const_view_t Bx_vector() const¶: Returns a constant view of the most recently computed vector \( \hat B\mathbf{x} \).

inline stats_t stats() const¶: Returns computation statistics from the last IRLM run.

template<> struct exact_shifts_f¶

If this functor is used to provide shifts for implicit restart, then the default ARPACK-NG’s shift strategy (Exact Shift Strategy) will be employed.

`ezarpack/solver_symmetric.hpp` - symmetric real eigenproblems¶

Table of Contents

This Page

ezarpack/solver_symmetric.hpp - symmetric real eigenproblems¶

`ezarpack/solver_symmetric.hpp` - symmetric real eigenproblems¶