PARCEL SYCL v1.2 / API Reference User Guide API Reference Search Download 日本語

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 AA (AK−1AK^{-1} when set_precon_spectrum(true) is set), or near σ\sigma 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 ∥Opx−θx∥/(|θ|∥x∥)\|\mathrm{Op}\,x-\theta x\|/(|\theta|\|x\|) of the Ritz pairs (θ,x)(\theta, x) (symbols). set_max_iteration() is not used. The convergence check and breakdowns are described in Convergence by Solver.

17.2 solver()

Description Computes kkeepk_{keep} eigenpairs. The convergence check applies to the leading nevnev 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. 2×kkeep2 \times k_{keep} elements (real and imaginary parts stored alternately) none
EigenVec In/Out parcel::vector<Teigen_vec> & Eigenvectors. At least nlocal×nevn_{local} \times nev elements (nlocaln_{local} is the number of locally owned rows, Mat.n_local(); column jj holds the jj-th vector). min⁡(kkeep,size/nlocal)\min(k_{keep}, \text{size}/n_{local}) vectors are written (kkeepk_{keep} vectors if the size is at least nlocal×kkeepn_{local} \times k_{keep}). On input, the first nlocaln_{local} elements are used as the initial vector none
ShiftMat In parcel::matrix<Tmat> * A−σIA - \sigma I 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.

The following are not checked.

If the norm of the initial vector (first nlocaln_{local} 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 kkeepk_{keep}, the missing eigenpairs are returned as 0. An eigenvalue for which |θ|2≤10−300|\theta|^2 \leq 10^{-300} in the back transformation of shift-invert is returned as +∞+\infty. 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 mm of the Krylov subspace, the number kkeepk_{keep} of vectors kept after a restart, and the number nevnev 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 1≤nev≤kkeep<m≤nglobal1 \leq nev \leq k_{keep} < m \leq n_{global}. If 1≤nev≤kkeep<m1 \leq nev \leq k_{keep} < m does not hold, std::invalid_argument is thrown (the stored values are not changed). m≤nglobalm \leq n_{global} 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);   // MGS2

17.6 set_shift() / disable_shift()

Description Enables / disables shift-invert mode. When enabled, the Arnoldi process is applied to (A−σI)−1(A - \sigma I)^{-1} ((AK−1−σI)−1(AK^{-1} - \sigma I)^{-1} when set_precon_spectrum(true) is set), and the eigenvalues near σ\sigma are returned as λ=σ+1/θ\lambda = \sigma + 1/\theta (θ\theta is a Ritz value).

Synopsis

void set_shift(double sigma);
void disable_shift();

Arguments

Name In/Out Type Description Default
sigma In double Shift σ\sigma disabled

Requirements σ\sigma 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.

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 nevnev 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 nevnev 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()