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

14 parcel::krylov::pcagmres

This is the class of the communication-avoiding generalized minimal residual method (CA-GMRES). Whether the orthonormal basis QQ is formed explicitly is selected with set_explicit_q(). The case where QQ 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 ss 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 ss, tt (not checked). The variants that form QQ work with the default (s,t)(s, t) (“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 QQ 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 Ax=bAx = b.

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() ≥s×t\geq s \times t (not checked). If b=0b = 0, the solver returns x=0x = 0 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_double

14.3 set_restart() / get_restart_s() / get_restart_t()

Description Sets or gets the number of vectors ss generated in one basis generation step and the number tt of basis generation steps before a restart. The restart length is s×ts \times t.

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 ss 8
cagmres_t In PARCEL_INT tt 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 ss 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 QQ 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 QQ is not formed only with QR_CHOLESKYQR and t=1t = 1; otherwise QQ is formed
CAGMRES_Q_EXPLICIT 1 QQ is always formed (also with QR_CHOLESKYQR and t=1t = 1)
CAGMRES_Q_IMPLICIT 2 QQ is not formed for any tt. 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_CAGMRES_CHOLESKYQR is limited to a symmetric AA. This is not checked; for a nonsymmetric AA, a wrong RR 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 t=1t = 1. CAGMRES_Q_IMPLICIT computes in a different order, so even with the same ss, tt, 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 specified

14.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 QQ explicitly. Only RR is obtained, from the Cholesky factorization of the Gram matrix of the basis VV, and the solution is updated with V(R−1y)V(R^{-1}y). 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 QQ 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);