9 Common Member Functions
These functions are provided by all solver classes. The functions for the convergence check and the convergence status are inherited from parcel::krylov::krylov_param, and the preconditioner functions from parcel::precon_param. The preconditioner settings (from set_precon_algo() to set_scaling_vector()) determine the preconditioner matrix of the iteration in the linear solvers, and the in when set_precon_spectrum(true) is set in the eigenvalue solvers. They are not used by the eigenvalue solvers when set_precon_spectrum(false) (the default) is set.
In the examples, cg, bi, gm, ca, pw, ip, and ks are objects of parcel::krylov::pcg<>, pbicgstab<>, pgmres<>, pcagmres<>, power<>, inverse_power<>, and ks_arnoldi<>, respectively (created as in parcel::krylov::pcg<> cg;).
9.1 set_tolerance() / get_tolerance()
Description Sets or gets the convergence tolerance.
Synopsis
void set_tolerance(double tol);
double get_tolerance();Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
tol |
In | double |
Convergence tolerance | 1.0e-8 |
Requirements A finite positive value. 0 or less, NaN, and Inf throw std::invalid_argument.
Return Value get_tolerance() returns the value set.
MPI Local operation. Give the same value on all ranks.
See Also set_max_iteration(), get_residual()
Example
cg.set_tolerance(1.0e-9);9.2 set_max_iteration() / get_max_iteration()
Description Sets or gets the maximum number of iterations.
Synopsis
void set_max_iteration(PARCEL_INT itrmax);
PARCEL_INT get_max_iteration();Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
itrmax |
In | PARCEL_INT |
Maximum number of iterations. In pgmres / pcagmres it is the upper limit on the total number of inner iterations, and in power / inverse_power the upper limit on the outer iterations |
10000 |
Requirements 1 or greater. 0 or less throws std::invalid_argument. In pgmres / pcagmres, it need not be a multiple of ( for pcagmres). Only the last restart uses a fractional number of columns (itrmax minus the number of iterations so far), and the solver iterates exactly up to the limit (convergence check of pgmres).
Return Value get_max_iteration() returns the value set.
MPI Local operation. Give the same value on all ranks.
Notes ks_arnoldi does not use this value (the maximum number of restarts is specified with set_ks_max_restart()).
Example
cg.set_max_iteration(10000);9.3 set_precon_algo() / get_precon_algo()
Description Sets or gets the type of preconditioner.
Synopsis
void set_precon_algo(PARCEL_INT precon_algo);
PARCEL_INT get_precon_algo();Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
precon_algo |
In | PARCEL_INT |
Preconditioner type. parcel::PRECON_NONE (0, no preconditioning), PRECON_POINTJACOBI (1), PRECON_BLOCKJACOBI (2), PRECON_JACOBI (4) |
PRECON_NONE |
Requirements One of the four values above. Any other value (such as 3) throws std::invalid_argument.
Return Value get_precon_algo() returns the value set.
MPI Local operation. Give the same value on all ranks.
Notes The block Jacobi preconditioner is slow on GPUs; on GPUs the Jacobi preconditioner (4) is recommended. For the types of preconditioners, see the “Preconditioners” chapter.
The handling of the matrix by the Jacobi preconditioner (do not destroy or modify during the solve, -DPARCEL_JACOBI_ONTHEFLY=0) is described in “Notes on the Preconditioners” in Common Items. When passing a built preconditioner to external_precon of pgmres, do not destroy or modify the matrix used to build it until you finish using it.
See Also set_jacobi(), set_blockjacobi(), set_scaling_matrix()
Example
cg.set_precon_algo(parcel::PRECON_JACOBI);9.4 set_jacobi() / get_jacobi()
Description Sets or gets the number of iterations of the Jacobi preconditioner (PRECON_JACOBI).
Synopsis
void set_jacobi(PARCEL_INT iter);
PARCEL_INT get_jacobi();Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
iter |
In | PARCEL_INT |
Number of Jacobi iterations | 1 |
Requirements 1 or greater. 0 or less throws std::invalid_argument.
MPI Local operation. Give the same value on all ranks.
Notes Not used except with PRECON_JACOBI.
Example
cg.set_jacobi(2);9.5 set_blockjacobi() / get_blockjacobi()
Description Sets or gets the number of blocks per rank of the block Jacobi preconditioner (PRECON_BLOCKJACOBI).
Synopsis
void set_blockjacobi(PARCEL_INT nblock);
PARCEL_INT get_blockjacobi();Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
nblock |
In | PARCEL_INT |
Number of blocks. Equal to the degree of parallelism of the application kernel | If not called, automatic (common items) |
Requirements 1 or greater, and no greater than the number of locally owned rows. 0 or less throws std::invalid_argument. Not exceeding the number of locally owned rows is not checked.
Return Value get_blockjacobi() returns the value set. If the function has not been called, it returns 1, but the value actually used is the automatically determined one (it is printed when the environment variable PARCEL_PRECON_VERBOSE is set).
MPI Local operation. Give the same value on all ranks.
Notes The finer the blocks, the weaker the preconditioner. Not used except with PRECON_BLOCKJACOBI.
Example
cg.set_blockjacobi(20);9.6 set_scaling_matrix() / set_scaling_vector() / get_scaling_matrix() / get_scaling_vector()
Description Sets or gets whether the preconditioner matrix / preconditioner vector is scaled. Scaling divides the matrix and the residual by their maximum values so that they fit within the representable range of half precision.
Synopsis
void set_scaling_matrix(bool flag);
void set_scaling_vector(bool flag);
bool get_scaling_matrix();
bool get_scaling_vector();Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
flag |
In | bool |
Scaling. false: off, true: on | If not called, automatic (common items) |
Return Value get_scaling_*() returns the value set. If the function has not been called, it returns false, but the value actually used is the automatically determined one.
MPI Local operation. Give the same value on all ranks.
Notes Not used with the point Jacobi preconditioner or without preconditioning.
Example
cg.set_scaling_matrix(true); cg.set_scaling_vector(true);9.7 get_converged_reason()
Description Returns the convergence status of the most recent solver() call.
Synopsis
PARCEL_INT get_converged_reason() const;Return Value One of the convergence status constants (meanings). A positive value means convergence, a negative value means failure, and 0 means that solver() has not been called.
MPI Local operation. The value is the same on all ranks.
See Also is_converged(), converged_reason_name()
Example
if (cg.get_converged_reason() == parcel::krylov::DIVERGED_ITS) { /* iteration limit reached */ }9.8 is_converged()
Description Returns whether the most recent solver() call converged.
Synopsis
bool is_converged() const;Return Value true when get_converged_reason() > 0.
MPI Local operation. The value is the same on all ranks.
Example
if (!cg.is_converged()) MPI_Abort(MPI_COMM_WORLD, 1);9.9 get_iterations()
Description Returns the number of iterations of the most recent solver() call.
Synopsis
PARCEL_INT get_iterations() const;Return Value Number of iterations. How iterations are counted differs from solver to solver (see “Meaning of the Iteration Count and Residuals” in Common Items).
MPI Local operation. The value is the same on all ranks.
9.10 get_residual()
Description Returns the relative value used for the convergence check in the most recent solver() call.
Synopsis
double get_residual() const;Return Value The relative value compared with the value of set_tolerance() (see “Meaning of the Iteration Count and Residuals” in Common Items). NaN if it has not been computed. If pgmres ended at the iteration limit, it is the value after the last update (= get_true_residual()).
MPI Local operation. The value is the same on all ranks.
9.11 get_true_residual()
Description Returns the true relative residual at the end of a linear solver.
Synopsis
double get_true_residual() const;Return Value . This is the value computed by the linear solver at the end; this function performs no additional SpMV. NaN for the eigenvalue solvers.
MPI Local operation. The value is the same on all ranks.
Notes The get_residual() of pcg / pbicgstab is the residual from the recurrence, so it may deviate from the true residual because of rounding errors. Use this function to check the accuracy of the solution.
9.12 converged_reason_name()
Description Converts a convergence status value to the string of the constant name (this is a function in the namespace parcel::krylov, not a member function).
Synopsis
const char *parcel::krylov::converged_reason_name(PARCEL_INT r);Arguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
r |
In | PARCEL_INT |
Value of get_converged_reason() |
none |
Return Value One of "CONVERGED_RTOL", "ITERATING", "DIVERGED_ITS", "DIVERGED_NANORINF", "DIVERGED_BREAKDOWN". "UNKNOWN" for an undefined value.
MPI Local operation.
Example
std::printf("pcg: %s after %d iterations (residual %.3e)\n",
parcel::krylov::converged_reason_name(cg.get_converged_reason()),
(int)cg.get_iterations(), cg.get_residual());9.13 version_string() / get_version() / PARCEL_VERSION_*
Description Returns the version of PARCEL (functions in the namespace parcel and macros; defined in Include/parcel_version.hpp, which parcel_sycl.hpp includes).
Synopsis
const char *parcel::version_string() noexcept;
void parcel::get_version(int *major, int *minor, int *patch) noexcept;
#define PARCEL_VERSION_MAJOR 1
#define PARCEL_VERSION_MINOR 2
#define PARCEL_VERSION_PATCH 0
#define PARCEL_VERSION_STRING "1.2.0"
#define PARCEL_VERSION_NUMBER (MAJOR * 10000 + MINOR * 100 + PATCH) // 10200
#define PARCEL_VERSION_GE(a, b, c) // 1 if the version is a.b.c or laterArguments
| Name | In/Out | Type | Description | Default |
|---|---|---|---|---|
major, minor, patch |
Out | int * |
Version numbers. Arguments given as nullptr are not written |
none |
Return Value version_string() returns the same string as PARCEL_VERSION_STRING (static storage).
MPI Local operation. Can be called before MPI is initialized.
Example
#if PARCEL_VERSION_GE(1, 2, 0)
std::printf("PARCEL %s\n", parcel::version_string());
#endif