`ezarpack/solver_complex.hpp` - general complex eigenproblems¶

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

Main solver class wrapping the Implicitly Restarted Arnoldi Method (IRAM) for general complex eigenproblems.

This specialization of arpack_solver calls ARPACK-NG routines znaupd() and zneupd() to compute approximations to a few eigenpairs of a complex linear operator \( \hat O \) with respect to a semi-inner product defined by a Hermitian positive semi-definite matrix \( \hat B \).

Note

If both \( \hat O \) and \( \hat B\) are real and symmetric, then arpack_solver<Symmetric, Backend> should be used instead.

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 complex_vector_t = typename storage::complex_vector_type¶: One-dimensional data array (vector) of complex numbers.

using complex_matrix_t = typename storage::complex_matrix_type¶: Two-dimensional data array (matrix) of complex numbers.

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

using complex_vector_view_t = typename storage::complex_vector_view_type¶: Partial view (slice) of a complex vector.

using complex_vector_const_view_t = typename storage::complex_vector_const_view_type¶: Partial constant view (slice) of a complex vector.

using complex_matrix_const_view_t = typename storage::complex_matrix_const_view_type¶: Partial constant view (slice) of a complex matrix.

using vector_const_view_t = complex_vector_const_view_t ¶: Storage-specific view type to expose complex 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 = complex_vector_view_t ¶: Storage-specific view type to expose complex 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 M \) is Hermitian 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 M \) is Hermitian 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< Complex, 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 Arnoldi 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 IRA iteration.
ezarpack::maxiter_reached – Maximum number of IRA 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 znaupd() and zneupd().

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_const_view_t in, vector_view_t out)
```
op is expected to act on the vector view in and write the result into the vector view out, out = op*in. Given an instance as of the arpack_solver< Complex, 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())as
```
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 Arnoldi 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 IRA iteration.
ezarpack::maxiter_reached – Maximum number of IRA 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 znaupd() and zneupd().

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 complex_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 complex_vector_const_view_t eigenvalues() const¶: Returns a constant view of a list of nconv() converged eigenvalues.

Note

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

inline complex_matrix_const_view_t eigenvectors() const¶

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

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

inline complex_matrix_const_view_t schur_vectors() const¶

Returns a view of a matrix, whose nconv() columns are Schur basis vectors.

Throws:: std::runtime_error – Schur vectors have not been computed in the last IRAM run.

inline complex_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 IRAM iteration?

inline complex_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 IRAM 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_complex.hpp` - general complex eigenproblems¶

Table of Contents

This Page

ezarpack/solver_complex.hpp - general complex eigenproblems¶

`ezarpack/solver_complex.hpp` - general complex eigenproblems¶