8 Items Common to All Solvers
This chapter gives the items common to the C++ solver classes (precision template arguments, settings and exceptions, names of the constants). The symbols and terms are given in “Symbols and Terms” in Common Items.
8.1 Class Template Arguments (Arithmetic Precision)
All solver classes specify the arithmetic precision of each operation through the following template arguments. When omitted, each defaults to parcel_double.
| Argument | Description | Default |
|---|---|---|
Tspmv |
Arithmetic precision of the sparse matrix-vector product (SpMV) | parcel_double |
Tprecon |
Arithmetic precision of the preconditioner | parcel_double |
Taxpy |
Arithmetic precision of vector operations (axpy (), etc.) | parcel_double |
Tdot |
Arithmetic precision of reductions (inner products and norms) | parcel_double |
template< class Tspmv = parcel_double, class Tprecon = parcel_double,
class Taxpy = parcel_double, class Tdot = parcel_double >
class pcg; // likewise for pbicgstab, pgmres, pcagmres, power, inverse_power, ks_arnoldiAll seven solver classes have these four arguments.
8.2 Template Arguments of solver() (Data Precision)
The template arguments of the solver() function specify the precision in which each piece of data is stored. Solver-specific arguments are given in the entry for each class. Arguments that can be deduced from the actual arguments can be omitted, and those that cannot be deduced default to parcel_double. Therefore, to use double precision throughout, you can write parcel::krylov::pcg<> s; s.solver(A, x, b); (for the eigenvalue solvers, s.solver(A, ev, evec)). To specify them explicitly, give them in order from the first.
| Argument | Description | Default |
|---|---|---|
Tmat |
Data precision of the coefficient matrix (must match the type of parcel::matrix<Tmat>) |
deduced from the argument |
Tvecx / Tvecb |
Data precision of the solution vector / right-hand side vector (linear solvers) | deduced from the argument |
Teigen_val / Teigen_vec |
Data precision of the eigenvalues / eigenvectors (eigenvalue solvers) | deduced from the argument |
Tvec |
Data precision of the vectors internal to the solver (not present in ks_arnoldi) |
parcel_double |
Tprecon_mat |
Data precision of the preconditioner matrix | parcel_double (ks_arnoldi: Teigen_vec) |
Tprecon_vec |
Data precision of the preconditioner vectors | parcel_double (ks_arnoldi: Teigen_vec) |
8.3 Handling of Settings and Exceptions
- The solver setting functions (
set_*) are local operations that only record values in the object. The settings are used whensolver()is called and are retained until they are changed again.solver()may be called repeatedly on the same object. - The following setting functions check the value and throw
std::invalid_argumentif it is out of range (the stored value is not changed). Since the setting functions are meant to be called with the same arguments on all ranks, all ranks throw in the same way.
| Function | Accepted values |
|---|---|
set_tolerance(), set_linsolve_tolerance() |
Finite positive value (0 or less, NaN, and Inf are rejected) |
set_max_iteration(), set_linsolve_max_iteration(), set_linsolve_restart(), ks_arnoldi: |
1 or greater |
set_precon_algo(), set_linsolve_precon_algo() |
PRECON_NONE, PRECON_POINTJACOBI, PRECON_BLOCKJACOBI, PRECON_JACOBI |
set_jacobi(), set_linsolve_jacobi() |
1 or greater |
set_blockjacobi(), set_linsolve_blockjacobi() |
1 or greater (not exceeding the number of locally owned rows is not checked) |
set_linsolve_algo() |
LINSOLVE_PGMRES, LINSOLVE_PCG |
pgmres::set_restart() |
1 or greater |
pgmres::set_qr_algo() |
QR_CGS, QR_MGS |
pcagmres::set_restart() |
and both 1 or greater |
pcagmres::set_qr_algo() |
QR_CGS, QR_MGS, QR_CHOLESKYQR, QR_CAGMRES_CHOLESKYQR |
pcagmres::set_explicit_q() |
CAGMRES_Q_AUTO, CAGMRES_Q_EXPLICIT, CAGMRES_Q_IMPLICIT |
ks_arnoldi::set_ks_subspace() |
|
ks_arnoldi::set_qr_algo() |
QR_CGS, QR_MGS |
- At the entry of
solver(), the following are checked, andstd::invalid_argumentis thrown on violation. In every case, all ranks throw on the same judgment before any collective communication.- The SYCL queue is in-order (all solvers;
set_crsMat()as well). The check can be disabled with-DPARCEL_REQUIRE_IN_ORDER=0. ks_arnoldi: , the number of elements ofEigenVec, and that ofEigenValue. Since the numbers of elements may differ between ranks, the judgments are gathered withMPI_Allreducebefore all ranks throw.pcagmres: the combination of the way is built and the QR factorization (set_explicit_q()).
- The SYCL queue is in-order (all solvers;
solver()also has the following requirements (referred to as the “common requirements” in the Requirements field of each solver).Matis a matrix registered withset_crsMat(). For a matrix that has not been registered (including one registered withset_diaMat()),std::runtime_erroris thrown.- The vectors (
x0,b0,EigenValue,EigenVec) are allocated with the same queue asMat(not checked;solver()uses only the queue ofMat). - The local length is taken from the number of elements of
x0for the linear solvers and ofEigenVecforpowerandinverse_power(ks_arnoldiusesMat.n_local()). If it differs from the number of locally owned rows, the behavior is undefined (not checked).
- If an unknown preconditioner type is encountered when the preconditioner is applied,
std::invalid_argumentis also thrown (this does not normally happen, because the setting functions check the value). - If a CRS built by a preconditioner (such as the L and U factors of block Jacobi) has more nonzeros than the original matrix and exceeds the range of
PARCEL_LINT,std::overflow_erroris thrown when the preconditioner is built. This check is per rank, and only the ranks that exceed the range throw (it happens only when the original matrix is close to the limit). Rebuild with-DPARCEL_LOCAL_INT64. - If device memory is insufficient when allocating a
parcel::vector, inset_crsMat(), or when allocating the work area ofsolver(),util_sycl::device_bad_alloc(derived fromstd::bad_alloc) is thrown.what()gives the requested number of bytes and the place of the allocation. In many cases only some ranks fail to allocate, and the other ranks keep waiting in the next collective communication. If you catch it, do not continue processing; stop the whole job withMPI_Abort()or similar. - Anything else (lengths of
vectors, the contents of the matrix, etc.) is not checked. See the Requirements field of each function. solver()is a collective operation (MPI_Barrier,MPI_Allreducefor inner products, and halo exchange in SpMV). All ranks of the communicator with which the matrix was registered must call it with the same settings. If the settings differ between ranks, the iteration counts may diverge and cause a deadlock (Settings and MPI in Common Items).- The convergence status (
get_converged_reason(), etc.) is reset on entry tosolver()and set on exit. The values are the same on all ranks. solver()throws no exception and returns no error even if it does not converge. Check withis_converged()or similar before using the result.
8.4 Constants
The constants passed to the setting functions and the convergence state constants are in the following namespaces. All have the type const PARCEL_INT. Their meanings are given in the common constants and Convergence Status.
| Namespace | Constants (values) | Used with |
|---|---|---|
parcel:: |
PRECON_NONE (0), PRECON_POINTJACOBI (1), PRECON_BLOCKJACOBI (2), PRECON_JACOBI (4) |
set_precon_algo(), set_linsolve_precon_algo() |
parcel::qr:: |
QR_CGS (0), QR_MGS (1), QR_CHOLESKYQR (2), QR_CAGMRES_CHOLESKYQR (202) |
pgmres::set_qr_algo(), pcagmres::set_qr_algo(), ks_arnoldi::set_qr_algo() |
parcel::krylov:: |
LINSOLVE_PGMRES (0), LINSOLVE_PCG (1) |
set_linsolve_algo() |
parcel::krylov:: |
CAGMRES_Q_AUTO (0), CAGMRES_Q_EXPLICIT (1), CAGMRES_Q_IMPLICIT (2) |
set_explicit_q() |
parcel::krylov:: |
CONVERGED_RTOL (1), ITERATING (0), DIVERGED_ITS (-1), DIVERGED_NANORINF (-2), DIVERGED_BREAKDOWN (-3) |
get_converged_reason(), converged_reason_name() |