14 parcel::krylov::pcagmres
This is the class of the communication-avoiding generalized minimal residual method (CA-GMRES). Whether the orthonormal basis is formed explicitly is selected with set_explicit_q(). The case where is not formed (CAGMRES_Q_IMPLICIT) is described in “Without forming Q” later in this chapter.
14.1 pcagmres (class)
Description Preconditioned communication-avoiding generalized minimal residual method. Generates basis vectors at once and orthogonalizes them by a QR factorization.
Synopsis
template< class Tspmv = parcel_double, class Tprecon = parcel_double,
class Taxpy = parcel_double, class Tdot = parcel_double >
class pcagmres : public krylov_param;Notes With FP16 data or arithmetic precision, do not use the Cholesky QR variants (CAGMRES_Q_IMPLICIT and QR_CAGMRES_CHOLESKYQR): they give NaN or do not converge for any , (not checked). The variants that form work with the default (“Known Limits at Low Precision” in the User Guide). The class can be excluded from the build with -DPARCEL_ENABLE_PCAGMRES=0 (the whole class is excluded regardless of how is formed).
See Also Convergence check and breakdown, set_restart(), set_qr_algo(), set_explicit_q(), the “Linear Solvers” chapter
14.2 solver()
Description Solves .
Synopsis
template< class Tmat, class Tvecx, class Tvecb, class Tvec = parcel_double,
class Tprecon_mat = parcel_double, class Tprecon_vec = parcel_double,
class Tbasis = parcel_double, class TcalcQR = parcel_double,
class THessenberg = parcel_double,
class Todd_basis = Tbasis, class Teven_basis = Tbasis >
void solver(parcel::matrix<Tmat> &Mat, parcel::vector<Tvecx> &x0, parcel::vector<Tvecb> &b0);Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
Tbasis |
In (template) | PARCEL data type | Data precision of the basis vectors. With CAGMRES_Q_IMPLICIT, the data precision of the input and output of the preconditioner (the work vectors built from the basis), and the default of Todd_basis and Teven_basis |
parcel_double |
TcalcQR |
In (template) | PARCEL data type | Arithmetic precision of the QR factorization (with CAGMRES_Q_IMPLICIT, of the Gram matrix) |
parcel_double |
THessenberg |
In (template) | PARCEL data type | Precision of the Hessenberg matrix (with CAGMRES_Q_IMPLICIT, also used to store the Gram matrix) |
parcel_double |
Todd_basis |
In (template) | PARCEL data type | Storage precision of the odd-numbered basis vectors. Used only with CAGMRES_Q_IMPLICIT |
Tbasis |
Teven_basis |
In (template) | PARCEL data type | Storage precision of the even-numbered basis vectors. Used only with CAGMRES_Q_IMPLICIT |
Tbasis |
Mat, x0, b0 |
Same as solver() of pcg |
none |
The arguments from Tmat to Tprecon_vec are the same as in “Template arguments of solver()”.
Requirements Satisfy the common requirements (an in-order queue, a registered matrix, and the queues and lengths of the vectors). The combination of the Q mode and the QR factorization satisfies the rules of set_explicit_q() (checked at the entry; on violation, all ranks throw std::invalid_argument). get_max_iteration() (not checked). If , the solver returns as pcg does.
Return Value None.
MPI Collective. All ranks must call it with the same settings.
Example
parcel::krylov::pcagmres<> ca;
ca.solver(A, x, b); // all precisions that cannot be deduced are parcel_double14.3 set_restart() / get_restart_s() / get_restart_t()
Description Sets or gets the number of vectors generated in one basis generation step and the number of basis generation steps before a restart. The restart length is .
Synopsis
void set_restart(PARCEL_INT cagmres_s, PARCEL_INT cagmres_t);
PARCEL_INT get_restart_s() const;
PARCEL_INT get_restart_t() const;Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
cagmres_s |
In | PARCEL_INT |
8 | |
cagmres_t |
In | PARCEL_INT |
4 |
Requirements Both 1 or greater. 0 or less throws std::invalid_argument.
MPI Local operation. Give the same value on all ranks.
Notes With CAGMRES_Q_IMPLICIT, the orthogonality error of the Cholesky QR method grows with the square of the condition number of the basis, so a large can degrade convergence.
Example
ca.set_restart(8, 1);14.4 set_qr_algo() / get_qr_algo()
Description Sets or gets the QR factorization method for the basis.
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), QR_MGS (1), QR_CHOLESKYQR (2), QR_CAGMRES_CHOLESKYQR (202, moment method; only with CAGMRES_Q_IMPLICIT) |
QR_MGS (QR_CHOLESKYQR with CAGMRES_Q_IMPLICIT if not called) |
Requirements One of the four values above. Any other value throws std::invalid_argument. The combination with set_explicit_q() is checked at the entry of solver().
Return Value get_qr_algo() returns the value actually used by solver() (QR_CHOLESKYQR with CAGMRES_Q_IMPLICIT if this function has not been called).
MPI Local operation. Give the same value on all ranks.
See Also The “QR Factorization” chapter, Without forming Q
Example
ca.set_qr_algo(parcel::qr::QR_MGS);14.5 set_explicit_q() / get_explicit_q()
Description Sets or gets whether the orthonormal basis is formed explicitly.
Synopsis
const PARCEL_INT parcel::krylov::CAGMRES_Q_AUTO = 0;
const PARCEL_INT parcel::krylov::CAGMRES_Q_EXPLICIT = 1;
const PARCEL_INT parcel::krylov::CAGMRES_Q_IMPLICIT = 2;
void set_explicit_q(PARCEL_INT mode);
PARCEL_INT get_explicit_q() const;Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
mode |
In | PARCEL_INT |
One of the constants in the table below | CAGMRES_Q_AUTO |
Constant (parcel::krylov::) |
Value | Behavior |
|---|---|---|
CAGMRES_Q_AUTO |
0 | is not formed only with QR_CHOLESKYQR and ; otherwise is formed |
CAGMRES_Q_EXPLICIT |
1 | is always formed (also with QR_CHOLESKYQR and ) |
CAGMRES_Q_IMPLICIT |
2 | is not formed for any . The QR factorization is limited to the Cholesky QR methods (QR_CHOLESKYQR or QR_CAGMRES_CHOLESKYQR) (Without forming Q) |
Requirements One of the three values above. Any other value throws std::invalid_argument. The combination with set_qr_algo() is checked at the entry of solver(), so that it does not depend on the order in which the setting functions are called, and std::invalid_argument is thrown in the following cases (all ranks make the same judgment).
QR_CGSorQR_MGSis set explicitly withCAGMRES_Q_IMPLICIT(ifset_qr_algo()has not been called,QR_CHOLESKYQRis used).QR_CAGMRES_CHOLESKYQRis combined withCAGMRES_Q_AUTOorCAGMRES_Q_EXPLICIT.- With
QR_CAGMRES_CHOLESKYQR, preconditioning is not none (PRECON_NONE), or is not an even number of 2 or greater.
QR_CAGMRES_CHOLESKYQR is limited to a symmetric . This is not checked; for a nonsymmetric , a wrong is used and wrong results are returned.
Return Value get_explicit_q() returns the value set.
MPI Local operation. Give the same value on all ranks.
Notes CAGMRES_Q_AUTO and CAGMRES_Q_EXPLICIT perform the same computation except for QR_CHOLESKYQR with . CAGMRES_Q_IMPLICIT computes in a different order, so even with the same , , and QR factorization, the results differ within rounding error.
See Also Without forming Q, the “QR Factorization” chapter
Example
ca.set_explicit_q(parcel::krylov::CAGMRES_Q_IMPLICIT); // QR_CHOLESKYQR unless the QR factorization is specified14.6 CAGMRES_Q_IMPLICIT (without forming Q)
Description With set_explicit_q(CAGMRES_Q_IMPLICIT), the same CA-GMRES(s,t) is solved without forming the orthonormal basis explicitly. Only is obtained, from the Cholesky factorization of the Gram matrix of the basis , and the solution is updated with . The storage precision of the basis can be chosen separately for the odd- and even-numbered vectors (the type arguments Todd_basis and Teven_basis of solver()).
Requirements The QR factorization is limited to the Cholesky QR methods (QR_CHOLESKYQR or QR_CAGMRES_CHOLESKYQR (moment method)). The rules for the combinations are given in set_explicit_q().
Notes The convergence check, the convergence state, and the handling of a lucky breakdown are the same as when is formed. The true relative residual is computed at the end and returned by get_true_residual().
See Also Convergence check and breakdown, the section on CA-GMRES without forming Q in the “Linear Solvers” chapter, the moment method in the “QR Factorization” chapter, set_explicit_q()
Example
parcel::krylov::pcagmres<> cq;
cq.set_explicit_q(parcel::krylov::CAGMRES_Q_IMPLICIT);
cq.set_restart(8, 1);
cq.set_qr_algo(parcel::qr::QR_CAGMRES_CHOLESKYQR); // only for a symmetric A without preconditioning; QR_CHOLESKYQR if omitted
cq.solver(A, x, b);