17 parcel::krylov::ks_arnoldi
17.1 ks_arnoldi (class)
Description Eigenvalue solver based on the Arnoldi process with Krylov-Schur restarting. It also handles nonsymmetric matrices, and computes several eigenpairs simultaneously at the large-magnitude end of the spectrum of ( when set_precon_spectrum(true) is set), or near in shift-invert mode.
Synopsis
template< class Tspmv = parcel_double, class Tprecon = parcel_double,
class Taxpy = parcel_double, class Tdot = parcel_double >
class ks_arnoldi : public eigen_param;Notes set_tolerance() applies to the relative residual of the Ritz pairs (symbols). set_max_iteration() is not used. The convergence check and breakdowns are described in Convergence by Solver.
17.2 solver()
Description Computes eigenpairs. The convergence check applies to the leading pairs.
Synopsis
template< class Tmat, class Teigen_val, class Teigen_vec,
class Tprecon_mat = Teigen_vec, class Tprecon_vec = Teigen_vec >
void solver(parcel::matrix<Tmat> &Mat,
parcel::vector<Teigen_val> &EigenValue, parcel::vector<Teigen_vec> &EigenVec,
parcel::matrix<Tmat> *ShiftMat = nullptr);Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
Mat |
In | parcel::matrix<Tmat> & |
Coefficient matrix | none |
EigenValue |
Out | parcel::vector<Teigen_val> & |
Eigenvalues. elements (real and imaginary parts stored alternately) | none |
EigenVec |
In/Out | parcel::vector<Teigen_vec> & |
Eigenvectors. At least elements ( is the number of locally owned rows, Mat.n_local(); column holds the -th vector). vectors are written ( vectors if the size is at least ). On input, the first elements are used as the initial vector |
none |
ShiftMat |
In | parcel::matrix<Tmat> * |
used for shift-invert (for its handling, see set_shift()). If set_shift() has not been called, it is not used even if passed (not checked) |
nullptr |
Requirements The following are checked at the entry, and std::invalid_argument is thrown on violation. Since a violation may differ between ranks, the judgments are gathered with MPI_Allreduce before all ranks throw.
- An in-order queue (common requirements).
- ( is the sum of the numbers of locally owned rows over all ranks).
- The number of elements of
EigenVecis at least , and that ofEigenValueat least ( isMat.n_local()).
The following are not checked.
- Among the common requirements, the queues of the vectors.
ShiftMatis registered withset_crsMat()from arrays separate from those ofMat(see the notes of set_crsMat()).
If the norm of the initial vector (first elements) is 0 or non-finite, it is replaced by the default initial vector (built from the global row indices, as in solver() of power), and rank 0 prints a message.
Return Value None.
MPI Collective. All ranks must call it with the same settings.
Notes When eigenvalues form a complex conjugate pair, the corresponding eigenvector is stored as two vectors, the real part and the imaginary part. If the Arnoldi process reaches an invariant subspace, convergence is confirmed with the true residual; if it cannot be confirmed, the process continues in a random direction (the “Eigenvalue Solvers” chapter). If the solver ends with an effective dimension smaller than , the missing eigenpairs are returned as 0. An eigenvalue for which in the back transformation of shift-invert is returned as . The dense-matrix LAPACK computations are done on rank 0, and the results are distributed to all ranks.
See Also set_ks_subspace(), set_shift(), get_ks_nconv(), the “Eigenvalue Solvers” chapter
Example
parcel::krylov::ks_arnoldi<> ks;
ks.solver(A, eval, evec);
ks.solver(A, eval, evec, &As); // shift-invert (As = A - σI)17.3 set_ks_subspace() / get_ks_m() / get_ks_k_keep() / get_ks_nev()
Description Sets or gets the maximum dimension of the Krylov subspace, the number of vectors kept after a restart, and the number of eigenpairs sought.
Synopsis
void set_ks_subspace(PARCEL_INT m, PARCEL_INT k_keep, PARCEL_INT nev);
PARCEL_INT get_ks_m() const;
PARCEL_INT get_ks_k_keep() const;
PARCEL_INT get_ks_nev() const;Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
m |
In | PARCEL_INT |
Maximum dimension of the Krylov subspace | 30 |
k_keep |
In | PARCEL_INT |
Number of Ritz pairs kept after a restart. This is the number of eigenpairs returned by solver() |
10 |
nev |
In | PARCEL_INT |
Number of eigenpairs subject to the convergence check | 4 |
Requirements . If does not hold, std::invalid_argument is thrown (the stored values are not changed). needs the matrix and is checked at the entry of solver().
MPI Local operation. Give the same value on all ranks.
Example
ks.set_ks_subspace(30, 10, 4);17.4 set_ks_max_restart() / get_ks_max_restart()
Description Sets or gets the maximum number of restarts.
Synopsis
void set_ks_max_restart(PARCEL_INT R);
PARCEL_INT get_ks_max_restart() const;Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
R |
In | PARCEL_INT |
Maximum number of restarts | 200 |
Requirements 1 or greater. 0 or less throws std::invalid_argument.
MPI Local operation. Give the same value on all ranks.
Example
ks.set_ks_max_restart(200);17.5 set_qr_algo() / get_qr_algo()
Description Sets or gets the orthogonalization method of the Arnoldi process. The constants are the same as for pgmres; ks_arnoldi applies either method twice.
Synopsis
void set_qr_algo(PARCEL_INT qrdecomposition_algo);
PARCEL_INT get_qr_algo() const;Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
qrdecomposition_algo |
In | PARCEL_INT |
parcel::qr::QR_CGS (0, classical Gram-Schmidt twice = CGS2) or QR_MGS (1, modified Gram-Schmidt twice = MGS2) |
QR_CGS. QR_MGS when the library is built with the macro PARCEL_KS_ORTHO_DEFAULT=mgs (“Default Orthogonalization of ks_arnoldi” in the User Guide) |
Requirements QR_CGS or QR_MGS. Other values (including QR_CHOLESKYQR) throw std::invalid_argument.
MPI Local operation. Give the same value on all ranks.
Notes The accuracy of the eigenvalues is equivalent; only the speed differs. MGS2 can be faster on CPU configurations with few local rows per rank, and CGS2 on CPUs with many local rows and on GPUs. The environment variable PARCEL_KS_ORTHO is not read (if it is set, rank 0 prints a one-line warning to standard error at the first solver()).
See Also ks_arnoldi in Convergence of Each Solver, the “QR Factorization” chapter
Example
ks.set_qr_algo(parcel::qr::QR_MGS); // MGS217.6 set_shift() / disable_shift()
Description Enables / disables shift-invert mode. When enabled, the Arnoldi process is applied to ( when set_precon_spectrum(true) is set), and the eigenvalues near are returned as ( is a Ritz value).
Synopsis
void set_shift(double sigma);
void disable_shift();Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
sigma |
In | double |
Shift | disabled |
Requirements does not coincide with an eigenvalue (not checked).
MPI Local operation. Give the same value on all ranks.
Notes The tolerance, maximum number of iterations, and restart length of the inner pgmres are set with set_linsolve_* (for the defaults, see the common settings). The preconditioner of the inner pgmres is determined by set_precon_spectrum() and the fourth argument ShiftMat of solver() as follows.
set_precon_spectrum(false)withShiftMat() passed: is built once fromShiftMataccording to the settings ofset_linsolve_precon_algo(),set_linsolve_blockjacobi(), andset_linsolve_jacobi().set_precon_spectrum(false)withShiftMatomitted: is solved from and the shift (there is no need to assemble ), and is fixed to .set_linsolve_precon_algo()and related settings are not used (rank 0 prints a note if a preconditioner other than none was set explicitly; no note is printed when the default Jacobi preconditioning is left as is). To speed up the inner iteration with a preconditioner, passShiftMat.set_precon_spectrum(true): is solved, and the preconditioner is (built from ).ShiftMatandset_linsolve_precon_algo()and related settings are not used.
Example
ks.set_shift(-13.0);17.7 get_ks_nconv()
Description Returns the number of eigenpairs that satisfied the tolerance at the last convergence check.
Synopsis
PARCEL_INT get_ks_nconv() const;Return Value The number, among the pairs, whose Ritz residual is less than or equal to the value set by set_tolerance() (NaN is not counted; if convergence was confirmed with the true residual, for example at an invariant subspace, that number). Equals on convergence.
MPI Local operation. The value is the same on all ranks.
Example
std::printf("converged pairs = %d / %d\n", (int)ks.get_ks_nconv(), (int)ks.get_ks_nev());17.8 set_shift_linsolve_tolerance() / set_shift_linsolve_max_iteration() / set_shift_linsolve_restart() (deprecated)
Description Old names of set_linsolve_tolerance(), set_linsolve_max_iteration(), and set_linsolve_restart(). Kept for compatibility.
Synopsis
void set_shift_linsolve_tolerance(double t);
void set_shift_linsolve_max_iteration(PARCEL_INT n);
void set_shift_linsolve_restart(PARCEL_INT r);Arguments Same as the corresponding set_linsolve_* functions (for the defaults, see the common settings).
Notes New programs should use set_linsolve_*.
See Also set_linsolve_tolerance()