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 explicit residual \(\|r_k\|_2 = \|b - A x_k\|_2\).

  • ImplicitResidualNorm — uses the residual-norm estimate the solver maintains internally (typically the square root of an inner product that is already computed each iteration), avoiding the extra matrix-vector product and global reduction at the cost of a quantity that can drift from the true residual norm on long runs.

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.