gko::solver::Ir#

Iterative refinement. Approximately solves the residual equation \(A e = r\) with an inner solver, then updates the iterate with the relaxation factor \(\alpha\). With \(\alpha = 1\) this is classical iterative refinement; with \(\alpha \ne 1\) and the identity inner solver it is Richardson iteration.

template<typename ValueType = default_precision>
class Ir #

Inherits from

  • public gko::EnableLinOp<Ir<default_precision>>

  • public gko::solver::EnableSolverBase<Ir<default_precision>>

  • public gko::solver::EnableIterativeBase<Ir<default_precision>>

  • public gko::solver::EnableApplyWithInitialGuess<Ir<default_precision>>

  • public gko::Transposable

Iterative refinement (IR) is an iterative method that uses another coarse method to approximate the error of the current solution via the current residual. Moreover, it can be also considered as preconditioned Richardson iteration with relaxation factor = 1.

For any approximation of the solution solution to the system Ax = b, the residual is defined as: residual = b - A solution. The error in solution, e = x - solution (with x being the exact solution) can be obtained as the solution to the residual equation Ae = residual, since A e = Ax - A solution = b - A solution = residual. Then, the real solution is computed as x = relaxation_factor * solution + e. Instead of accurately solving the residual equation \( A e = r \), the solution of the system \( e \) can be approximated to obtain the approximation error using a coarse method solver, which is used to update solution, and the entire process is repeated with the updated solution. This yields the iterative refinement method:

solution = initial_guess
while not converged:
    residual = b - A solution
    error = solver(A, residual)
    solution = solution + relaxation_factor * error

With relaxation_factor equal to 1 (default), the solver is Iterative Refinement, with relaxation_factor equal to a value other than 1, the solver is a Richardson iteration, with possibility for additional preconditioning.

Assuming that solver has accuracy \( c \), i.e. \( \| e - \tilde{e} \| \le c \, \| e \| \), iterative refinement will converge with a convergence rate of \( c \). Indeed, from \( e - \tilde{e} = x - x_k - \tilde{e} = x - x_{k+1} \) (where \( x_{k+1} \) denotes the value stored in solution after the update) and \( e = A^{-1} r = A^{-1} b - A^{-1} A x_k = x - x_k \) it follows that \( \| x - x_{k+1} \| \le c \, \| x - x_k \| \).

Unless otherwise specified via the solver factory parameter, this implementation uses the identity operator (i.e. the solver that approximates the solution of a system \( A x = b \) by setting \( x := b \)) as the default inner solver. Such a setting results in a relaxation method known as the Richardson iteration with parameter 1, which is guaranteed to converge for matrices whose spectrum is strictly contained within the unit disc around 1 — i.e. all eigenvalues \( \lambda \) must satisfy \( |\, \alpha \, \lambda - 1 \,| < 1 \), where \( \alpha \) is the relaxation factor.

Template Parameters:

ValueType – precision of matrix elements

Public Functions

virtual std::unique_ptr<LinOp> transpose() const override#

Returns a LinOp representing the transpose of the Transposable object.

Returns:

a pointer to the new transposed object

virtual std::unique_ptr<LinOp> conj_transpose() const override#

Returns a LinOp representing the conjugate transpose of the Transposable object.

Returns:

a pointer to the new conjugate transposed object

inline bool apply_uses_initial_guess() const override#

Return true as iterative solvers use the data in x as an initial guess.

Returns:

true as iterative solvers use the data in x as an initial guess.

inline std::shared_ptr<const LinOp> get_solver() const#

Returns the solver operator used as the inner solver.

Returns:

the solver operator used as the inner solver

void set_solver(std::shared_ptr<const LinOp> new_solver)#

Sets the solver operator used as the inner solver.

Parameters:

new_solver – the new inner solver

Ir &operator=(const Ir&)#

Copy-assigns an IR solver. Preserves the executor, shallow-copies inner solver, stopping criterion and system matrix. If the executors mismatch, clones inner solver, stopping criterion and system matrix onto this executor.

Ir &operator=(Ir&&)#

Move-assigns an IR solver. Preserves the executor, moves inner solver, stopping criterion and system matrix. If the executors mismatch, clones inner solver, stopping criterion and system matrix onto this executor. The moved-from object is empty (0x0 and nullptr inner solver, stopping criterion and system matrix)

Ir(const Ir&)#

Copy-constructs an IR solver. Inherits the executor, shallow-copies inner solver, stopping criterion and system matrix.

Ir(Ir&&)#

Move-constructs an IR solver. Preserves the executor, moves inner solver, stopping criterion and system matrix. The moved-from object is empty (0x0 and nullptr inner solver, stopping criterion and system matrix)

Public Static Functions

static parameters_type parse(
const config::pnode &config,
const config::registry &context,
const config::type_descriptor &td_for_child = config::make_type_descriptor<ValueType>(),
)#

Create the parameters from the property_tree. Because this is directly tied to the specific type, the value/index type settings within config are ignored and type_descriptor is only used for children configs.

Parameters:

  • config – the property tree for setting

  • context – the registry

  • td_for_child – the type descriptor for children configs. The default uses the value type of this class.

Returns:

parameters

struct parameters_type #

Inherits from

  • public gko::solver::enable_iterative_solver_factory_parameters<parameters_type, Factory>

Public Members

std::shared_ptr<const LinOpFactory> solver#

Inner solver factory.

std::shared_ptr<const LinOp> generated_solver#

Already generated solver. If one is provided, the factory solver will be ignored.

ValueType relaxation_factor#

Relaxation factor for Richardson iteration

initial_guess_mode default_initial_guess#

Default initial guess mode. The available options are under initial_guess_mode.