gko::stop::ResidualNorm#

Residual-norm tolerance criteria. The baseline factory parameter picks how the threshold is interpreted (relative to the right-hand side, relative to the initial residual, or absolute); see the class docstring for the three modes.

Two flavours:

  • ResidualNorm: uses the 2-norm of the residual, taken from the norm the solver provides or computed from the solver’s residual vector with one global reduction per check. Solvers that pass neither (MINRES, Multigrid) make it compute \(b - A x\), an extra SpMV per check.

  • ImplicitResidualNorm: uses the squared-norm estimate the solver maintains internally (typically an inner product that is already computed each iteration), avoiding that reduction at the cost of a quantity that can drift from the true residual norm on long runs.

Helper functions build these criteria without spelling out the value type: relative_residual_norm(tol) (baseline rhs_norm), initial_residual_norm(tol) (initial_resnorm), absolute_residual_norm(tol) (absolute), and relative_implicit_residual_norm, initial_implicit_residual_norm and absolute_implicit_residual_norm for ImplicitResidualNorm.

template<typename ValueType = default_precision>
class ResidualNorm #

Inherits from

Stopping criterion based on the explicit residual norm \( \| r_k \| = \| b - A x_k \| \). The iteration halts once \( \| r_k \| \le \tau \cdot \beta \), where \(\tau\) is the factory parameter reduction_factor and the baseline \(\beta\) is selected by the baseline factory parameter:

  • mode::rhs_norm (default) — relative to the right-hand side: \( \beta = \| b \| \), so the condition is \( \| r_k \| \le \tau \| b \| \).

  • mode::initial_resnorm — relative to the initial residual: \( \beta = \| r_0 \| \), so the condition is \( \| r_k \| \le \tau \| r_0 \| \).

  • mode::absolute — absolute threshold: \( \beta = 1 \), so the condition is \( \| r_k \| \le \tau \).

Per-iteration, the criterion prefers a pre-computed residual norm passed by the solver (via Updater::residual_norm); otherwise it falls back to computing the 2-norm of the residual vector itself (via Updater::residual), which costs one global reduction. When even cheaper checks are needed and the solver maintains an internal squared-norm estimate, use ImplicitResidualNorm instead.

Note

Baseline prerequisites at construction time:

  • mode::rhs_norm requires the right-hand side \( b \).

  • mode::initial_resnorm requires either the initial residual \( r_0 \) explicitly, or the triple \( (A, b, x_0) \) from which it is computed as \( r_0 = b - A x_0 \).

  • mode::absolute requires \( b \) as well — to determine the number of right-hand sides; its baseline is then filled with ones. If the required arguments are missing, ::gko::NotSupported() is thrown.

struct parameters_type#

Public Members

remove_complex<ValueType> reduction_factor{5 * std::numeric_limits<remove_complex<ValueType>>::epsilon()}#

Residual norm reduction factor

mode baseline#

The quantity the reduction is relative to. Choices include “mode::rhs_norm”, “mode::initial_resnorm” and “mode::absolute”

template<typename ValueType = default_precision>
class ImplicitResidualNorm #

Inherits from

Stopping criterion based on a solver-maintained squared residual-norm estimate \( \rho_k^2 \approx \| r_k \|^2 \). Several Krylov methods (CG, BiCGSTAB, …) already compute this quantity per iteration as a by-product of their inner-product recurrences, so the criterion can check convergence without computing a norm of its own — saving the global reduction the explicit ResidualNorm form needs when the solver only passes \( r_k \). The iteration halts once \( \rho_k \le \tau \cdot \beta \), with the same reduction_factor and baseline factory parameters as ResidualNorm:

  • mode::rhs_norm (default) — \( \rho_k \le \tau \| b \| \).

  • mode::initial_resnorm — \( \rho_k \le \tau \| r_0 \| \).

  • mode::absolute — \( \rho_k \le \tau \).

Because \( \rho_k^2 \) is updated by short recurrences rather than recomputed from \( b - A x_k \) each step, it can drift from the true residual norm on long runs in finite precision; pair this criterion with an Iteration cap when that matters.

Note

The solver must pass the squared estimate through Updater::implicit_sq_residual_norm on every check — there is no fallback path. If it is missing, ::gko::NotSupported() is thrown at check time.

Note

Baseline prerequisites at construction time mirror ResidualNorm:

  • mode::rhs_norm requires \( b \).

  • mode::initial_resnorm requires either \( r_0 \) explicitly or the triple \( (A, b, x_0) \) to derive it.

  • mode::absolute requires \( b \) for sizing the per-RHS baseline. If the required arguments are missing, ::gko::NotSupported() is thrown.

struct parameters_type#

Public Members

remove_complex<ValueType> reduction_factor{5 * std::numeric_limits<remove_complex<ValueType>>::epsilon()}#

Implicit Residual norm goal

mode baseline#

The quantity the reduction is relative to. Choices include “mode::rhs_norm”, “mode::initial_resnorm” and “mode::absolute”

template<typename ValueType>
class ResidualNormBase #

Inherits from

The ResidualNormBase class provides a framework for stopping criteria related to the residual norm. These criteria differ in the way they initialize starting_tau_, so in the value they compare the residual norm against. The provided check_impl uses the actual residual to check for convergence.

deferred_factory_parameter<CriterionFactory> gko::stop::relative_residual_norm(
double tolerance,
)#

Creates the precursor to a ResidualNorm stopping criterion factory, to be used in conjunction with .with_criteria(...) function calls when building a solver factory. This stopping criterion will stop the iteration after the residual norm has decreased below the specified value or by the specified amount.

Full usage example: Stop after 100 iterations or when the absolute residual norm is below \(10^{-10}\), whichever happens first. 

auto factory = gko::solver::Cg<double>::build()
                   .with_criteria(
gko::stop::max_iters(100),
gko::stop::absolute_residual_norm(1e-10))
                   .on(exec);

Parameters:

tolerance – the value the residual norm needs to be below. With residual \(r\), initial guess \(x_0\), right-hand side \(b\) and matrix \(A\), absolute means the exact value of the norm \(||r||\), relative means the norm relative to the right-hand side \(||r||/||b||\), initial means the norm relative to the initial residual \(||r||/||b - A x_0||\). An implicit stopping criterion is only available with some solvers, and refers to either the energy norm \(||r||_A\) in short-recurrence solvers like Cg or the euclidian norm \(||r||\) in solvers like GMRES. Implicit residual norms are cheaper to compute, but may be less precise due to accumulating rounding errors.

Returns:

a deferred_factory_parameter that can be passed to the with_criteria function when building a solver.

deferred_factory_parameter<CriterionFactory> gko::stop::initial_residual_norm(
double tolerance,
)#

Creates the precursor to a ResidualNorm stopping criterion factory, to be used in conjunction with .with_criteria(...) function calls when building a solver factory. This stopping criterion will stop the iteration after the residual norm has decreased below the specified value or by the specified amount.

Full usage example: Stop after 100 iterations or when the absolute residual norm is below \(10^{-10}\), whichever happens first. 

auto factory = gko::solver::Cg<double>::build()
                   .with_criteria(
gko::stop::max_iters(100),
gko::stop::absolute_residual_norm(1e-10))
                   .on(exec);

Parameters:

tolerance – the value the residual norm needs to be below. With residual \(r\), initial guess \(x_0\), right-hand side \(b\) and matrix \(A\), absolute means the exact value of the norm \(||r||\), relative means the norm relative to the right-hand side \(||r||/||b||\), initial means the norm relative to the initial residual \(||r||/||b - A x_0||\). An implicit stopping criterion is only available with some solvers, and refers to either the energy norm \(||r||_A\) in short-recurrence solvers like Cg or the euclidian norm \(||r||\) in solvers like GMRES. Implicit residual norms are cheaper to compute, but may be less precise due to accumulating rounding errors.

Returns:

a deferred_factory_parameter that can be passed to the with_criteria function when building a solver.

deferred_factory_parameter<CriterionFactory> gko::stop::absolute_residual_norm(
double tolerance,
)#

Creates the precursor to a ResidualNorm stopping criterion factory, to be used in conjunction with .with_criteria(...) function calls when building a solver factory. This stopping criterion will stop the iteration after the residual norm has decreased below the specified value or by the specified amount.

Full usage example: Stop after 100 iterations or when the absolute residual norm is below \(10^{-10}\), whichever happens first. 

auto factory = gko::solver::Cg<double>::build()
                   .with_criteria(
gko::stop::max_iters(100),
gko::stop::absolute_residual_norm(1e-10))
                   .on(exec);

Parameters:

tolerance – the value the residual norm needs to be below. With residual \(r\), initial guess \(x_0\), right-hand side \(b\) and matrix \(A\), absolute means the exact value of the norm \(||r||\), relative means the norm relative to the right-hand side \(||r||/||b||\), initial means the norm relative to the initial residual \(||r||/||b - A x_0||\). An implicit stopping criterion is only available with some solvers, and refers to either the energy norm \(||r||_A\) in short-recurrence solvers like Cg or the euclidian norm \(||r||\) in solvers like GMRES. Implicit residual norms are cheaper to compute, but may be less precise due to accumulating rounding errors.

Returns:

a deferred_factory_parameter that can be passed to the with_criteria function when building a solver.

deferred_factory_parameter<CriterionFactory> gko::stop::relative_implicit_residual_norm(
double tolerance,
)#

Creates the precursor to a ResidualNorm stopping criterion factory, to be used in conjunction with .with_criteria(...) function calls when building a solver factory. This stopping criterion will stop the iteration after the residual norm has decreased below the specified value or by the specified amount.

Full usage example: Stop after 100 iterations or when the absolute residual norm is below \(10^{-10}\), whichever happens first. 

auto factory = gko::solver::Cg<double>::build()
                   .with_criteria(
gko::stop::max_iters(100),
gko::stop::absolute_residual_norm(1e-10))
                   .on(exec);

Parameters:

tolerance – the value the residual norm needs to be below. With residual \(r\), initial guess \(x_0\), right-hand side \(b\) and matrix \(A\), absolute means the exact value of the norm \(||r||\), relative means the norm relative to the right-hand side \(||r||/||b||\), initial means the norm relative to the initial residual \(||r||/||b - A x_0||\). An implicit stopping criterion is only available with some solvers, and refers to either the energy norm \(||r||_A\) in short-recurrence solvers like Cg or the euclidian norm \(||r||\) in solvers like GMRES. Implicit residual norms are cheaper to compute, but may be less precise due to accumulating rounding errors.

Returns:

a deferred_factory_parameter that can be passed to the with_criteria function when building a solver.

deferred_factory_parameter<CriterionFactory> gko::stop::initial_implicit_residual_norm(
double tolerance,
)#

Creates the precursor to a ResidualNorm stopping criterion factory, to be used in conjunction with .with_criteria(...) function calls when building a solver factory. This stopping criterion will stop the iteration after the residual norm has decreased below the specified value or by the specified amount.

Full usage example: Stop after 100 iterations or when the absolute residual norm is below \(10^{-10}\), whichever happens first. 

auto factory = gko::solver::Cg<double>::build()
                   .with_criteria(
gko::stop::max_iters(100),
gko::stop::absolute_residual_norm(1e-10))
                   .on(exec);

Parameters:

tolerance – the value the residual norm needs to be below. With residual \(r\), initial guess \(x_0\), right-hand side \(b\) and matrix \(A\), absolute means the exact value of the norm \(||r||\), relative means the norm relative to the right-hand side \(||r||/||b||\), initial means the norm relative to the initial residual \(||r||/||b - A x_0||\). An implicit stopping criterion is only available with some solvers, and refers to either the energy norm \(||r||_A\) in short-recurrence solvers like Cg or the euclidian norm \(||r||\) in solvers like GMRES. Implicit residual norms are cheaper to compute, but may be less precise due to accumulating rounding errors.

Returns:

a deferred_factory_parameter that can be passed to the with_criteria function when building a solver.

deferred_factory_parameter<CriterionFactory> gko::stop::absolute_implicit_residual_norm(
double tolerance,
)#

Creates the precursor to a ResidualNorm stopping criterion factory, to be used in conjunction with .with_criteria(...) function calls when building a solver factory. This stopping criterion will stop the iteration after the residual norm has decreased below the specified value or by the specified amount.

Full usage example: Stop after 100 iterations or when the absolute residual norm is below \(10^{-10}\), whichever happens first. 

auto factory = gko::solver::Cg<double>::build()
                   .with_criteria(
gko::stop::max_iters(100),
gko::stop::absolute_residual_norm(1e-10))
                   .on(exec);

Parameters:

tolerance – the value the residual norm needs to be below. With residual \(r\), initial guess \(x_0\), right-hand side \(b\) and matrix \(A\), absolute means the exact value of the norm \(||r||\), relative means the norm relative to the right-hand side \(||r||/||b||\), initial means the norm relative to the initial residual \(||r||/||b - A x_0||\). An implicit stopping criterion is only available with some solvers, and refers to either the energy norm \(||r||_A\) in short-recurrence solvers like Cg or the euclidian norm \(||r||\) in solvers like GMRES. Implicit residual norms are cheaper to compute, but may be less precise due to accumulating rounding errors.

Returns:

a deferred_factory_parameter that can be passed to the with_criteria function when building a solver.