solver_asymmetric.hpp` - general real eigenproblems¶

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

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

This specialization of arpack_solver calls ARPACK-NG routines pdnaupd() and pdneupd() to compute approximations to a few eigenpairs of a real linear operator \( \hat O \) with respect to an inner product defined by a real symmetric positive semi-definite matrix \( \hat B \).

Note

If the linear operator \( \hat O \) is symmetric with respect to \( \hat B\), 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 real_matrix_t = typename storage::real_matrix_type¶: Two-dimensional data array (matrix) 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 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 M \) is symmetric positive-definite.

enumerator ShiftAndInvertReal¶

Complex Shift-and-Invert mode in real arithmetic I.

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

Note

In this computational mode, ARPACK-NG only finds eigenvalues \( \mu \) of \( \hat O \) that are related to \( \lambda \) via

\[ \mu = \frac{1}{2}\left[ \frac{1}{\lambda-\sigma} + \frac{1}{\lambda-\sigma^*} \right]. \]

Calling eigenvalues() to retrieve \( \lambda \) after a calculation in this mode will throw std::runtime_error. Instead, one should call eigenvalues(A &&a), which computes \( \lambda \) as Rayleigh quotients \( \frac{\mathbf{x}^\dagger \hat A \mathbf{x}}{ \mathbf{x}^\dagger \hat M \mathbf{x}} \).

enumerator ShiftAndInvertImag¶

Complex Shift-and-Invert mode in real arithmetic II.

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

Note

In this computational mode, ARPACK-NG only finds eigenvalues \( \mu \) of \( \hat O \) that are related to \( \lambda \) via

\[ \mu = \frac{1}{2i}\left[ \frac{1}{\lambda-\sigma} - \frac{1}{\lambda-\sigma^*} \right]. \]

Calling eigenvalues() to retrieve \( \lambda \) after a calculation in this mode will throw std::runtime_error. Instead, one should call eigenvalues(A &&a), which computes \( \lambda \) as Rayleigh quotients \( \frac{\mathbf{x}^\dagger \hat A \mathbf{x}}{ \mathbf{x}^\dagger \hat M \mathbf{x}} \).

Public Functions

inline arpack_solver(unsigned int N, MPI_Comm const &comm)¶

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

This constructor partitions N-dimensional vectors into blocks and distributes those blocks among all MPI ranks in a communicator in the most even way.

Parameters:

N – Dimension of the eigenproblem.
comm – MPI communicator.

inline arpack_solver(std::vector<unsigned int> const &block_sizes, MPI_Comm const &comm)¶

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

This constructor accepts a list of sizes of MPI rank-local vector blocks.

Parameters:

block_sizes – Sizes of MPI rank-local vector blocks, one element per MPI rank.
comm – MPI communicator.

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. Both in and out are MPI rank-local blocks of their respective N-dimensional vectors. If a has matrix elements connecting blocks stored on different MPI ranks, it is user’s duty to pass data between those ranks and to appropriately update out on all ranks. Given an instance as of the arpack_solver< Asymmetric, 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 pdnaupd() and pdneupd().

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. Both in and out are MPI rank-local blocks of their respective N-dimensional vectors. If op has matrix elements connecting blocks stored on different MPI ranks, it is user’s duty to pass data between those ranks and to appropriately update out on all ranks. Given an instance as of the arpack_solver< Asymmetric, 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. Both in and out are MPI rank-local blocks of their respective N-dimensional vectors. If b has matrix elements connecting blocks stored on different MPI ranks, it is user’s duty to pass data between those ranks and to appropriately update out on all ranks.
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 pdnaupd() and pdneupd().

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

inline MPI_Comm mpi_comm() const¶: Returns MPI communicator used to construct this solver.

inline int local_block_start() const¶: Returns the index of the first vector element in the local block.

inline int local_block_size() const¶: Returns the size of the local block.

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 an MPI rank-local block 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_t eigenvalues() const¶

Returns a list of nconv() eigenvalues.

Cannot be used in the ShiftAndInvertReal and ShiftAndInvertImag modes.

Throws:: std::runtime_error – The last IRAM run was performed in the ShiftAndInvertReal or ShiftAndInvertImag mode.

template<typename A> inline complex_vector_t eigenvalues(A &&a) const¶

Returns a list of nconv() eigenvalues computed as Rayleigh quotients \( \frac{\mathbf{x}^\dagger \hat A \mathbf{x}}{ \mathbf{x}^\dagger \hat M \mathbf{x}} \).

This method requires availability of the Ritz vectors \( \mathbf{x} \) (params_t::compute_vectors has been set to params_t::Ritz in the last run) and is primarily intended for use in the ShiftAndInvertReal and ShiftAndInvertImag modes.

Parameters:: a – A callable object representing the linear operator \( \hat A \).
Throws:: std::runtime_error – Ritz vectors have not been computed in the last IRAM run.

inline complex_matrix_t eigenvectors() const¶

Returns a matrix, whose nconv() columns are MPI rank-local blocks of converged Ritz vectors (eigenvectors).

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

inline real_matrix_const_view_t schur_vectors() const¶

Returns a view of a matrix, whose nconv() columns are MPI rank-local blocks of Schur basis vectors.

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

inline real_vector_view_t residual_vector()¶

Returns a view of the MPI rank-local block 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 real_vector_const_view_t Bx_vector() const¶: Returns a constant view of the MPI rank-local block of the most recently computed vector \( \hat B\mathbf{x} \).

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

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/mpi/solver_asymmetric.hpp` - general real eigenproblems¶

Table of Contents

This Page

ezarpack/mpi/solver_asymmetric.hpp - general real eigenproblems¶

`ezarpack/mpi/solver_asymmetric.hpp` - general real eigenproblems¶