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

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 KK of the iteration in the linear solvers, and the KK in AK−1AK^{-1} 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 mm (s×ts \times t 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 AA 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 ∥b−Ax∥/∥b∥\|b - Ax\|/\|b\|. 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 later

Arguments

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