Ginkgo: Linear Operators

| Ginkgo Generated from branch based on main. Ginkgo version 1.11.0 A numerical linear algebra library targeting many-core architectures

Loading...
Searching...
No Matches
Linear Operators

A module dedicated to the implementation and usage of the Linear operators in Ginkgo. More...

Collaboration diagram for Linear Operators:

## Topics
| Factorizations
| A module dedicated to the implementation and usage of the Factorizations in Ginkgo.
| SpMV employing different Matrix formats
| A module dedicated to the implementation and usage of the various Matrix Formats in Ginkgo.
| Preconditioners
| A module dedicated to the implementation and usage of the Preconditioners in Ginkgo.
| Solvers
| A module dedicated to the implementation and usage of the Solvers in Ginkgo.

## Classes
class | gko::Combination< ValueType >
| The Combination class can be used to construct a linear combination of multiple linear operators c1 * op1 + c2 * op2 + ... + ck * opk. More...
class | gko::Composition< ValueType >
| The Composition class can be used to compose linear operators op1, op2, ..., opn and obtain the operator op1 * op2 * ... * opn. More...
class | gko::LinOpFactory
| A LinOpFactory represents a higher order mapping which transforms one linear operator into another. More...
class | gko::ReadableFromMatrixData< ValueType, IndexType >
| A LinOp implementing this interface can read its data from a matrix_data structure. More...
class | gko::WritableToMatrixData< ValueType, IndexType >
| A LinOp implementing this interface can write its data to a matrix_data structure. More...
class | gko::Preconditionable
| A LinOp implementing this interface can be preconditioned. More...
class | gko::DiagonalLinOpExtractable
| The diagonal of a LinOp can be extracted. More...
class | gko::DiagonalExtractable< ValueType >
| The diagonal of a LinOp implementing this interface can be extracted. More...
class | gko::EnableAbsoluteComputation< AbsoluteLinOp >
| The EnableAbsoluteComputation mixin provides the default implementations of compute_absolute_linop and the absolute interface. More...
class | gko::EnableLinOp< ConcreteLinOp, PolymorphicBase >
| The EnableLinOp mixin can be used to provide sensible default implementations of the majority of the LinOp and PolymorphicObject interface. More...
class | gko::Perturbation< ValueType >
| The Perturbation class can be used to construct a LinOp to represent the operation (identity + scalar * basis * projector). More...
class | gko::experimental::distributed::preconditioner::Schwarz< ValueType, LocalIndexType, GlobalIndexType >
| A Schwarz preconditioner is a simple domain decomposition preconditioner that generalizes the Block Jacobi preconditioner, incorporating options for different local subdomain solvers and overlaps between the subdomains. More...
class | gko::experimental::distributed::Vector< ValueType >
| Vector is a format which explicitly stores (multiple) distributed column vectors in a dense storage format. More...
class | gko::factorization::Ic< ValueType, IndexType >
| Represents an incomplete Cholesky factorization (IC(0)) of a sparse matrix. More...
class | gko::factorization::Ilu< ValueType, IndexType >
| Represents an incomplete LU factorization – ILU(0) – of a sparse matrix. More...
class | gko::factorization::ParIc< ValueType, IndexType >
| ParIC is an incomplete Cholesky factorization which is computed in parallel. More...
class | gko::factorization::ParIct< ValueType, IndexType >
| ParICT is an incomplete threshold-based Cholesky factorization which is computed in parallel. More...
class | gko::factorization::ParIlu< ValueType, IndexType >
| ParILU is an incomplete LU factorization which is computed in parallel. More...
class | gko::factorization::ParIlut< ValueType, IndexType >
| ParILUT is an incomplete threshold-based LU factorization which is computed in parallel. More...
class | gko::matrix::Coo< ValueType, IndexType >
| COO stores a matrix in the coordinate matrix format. More...
class | gko::matrix::Csr< ValueType, IndexType >
| CSR is a matrix format which stores only the nonzero coefficients by compressing each row of the matrix (compressed sparse row format). More...
class | gko::matrix::Dense< ValueType >
| Dense is a matrix format which explicitly stores all values of the matrix. More...
class | gko::matrix::Diagonal< ValueType >
| This class is a utility which efficiently implements the diagonal matrix (a linear operator which scales a vector row wise). More...
class | gko::matrix::Ell< ValueType, IndexType >
| ELL is a matrix format where stride with explicit zeros is used such that all rows have the same number of stored elements. More...
class | gko::matrix::Fbcsr< ValueType, IndexType >
| Fixed-block compressed sparse row storage matrix format. More...
class | gko::matrix::Fft
| This LinOp implements a 1D Fourier matrix using the FFT algorithm. More...
class | gko::matrix::Fft2
| This LinOp implements a 2D Fourier matrix using the FFT algorithm. More...
class | gko::matrix::Fft3
| This LinOp implements a 3D Fourier matrix using the FFT algorithm. More...
class | gko::matrix::Hybrid< ValueType, IndexType >
| HYBRID is a matrix format which splits the matrix into ELLPACK and COO format. More...
class | gko::matrix::Identity< ValueType >
| This class is a utility which efficiently implements the identity matrix (a linear operator which maps each vector to itself). More...
class | gko::matrix::IdentityFactory< ValueType >
| This factory is a utility which can be used to generate Identity operators. More...
class | gko::matrix::Permutation< IndexType >
| Permutation is a matrix format that represents a permutation matrix, i.e. More...
class | gko::matrix::RowGatherer< IndexType >
| RowGatherer is a matrix "format" which stores the gather indices arrays which can be used to gather rows to another matrix. More...
class | gko::matrix::ScaledPermutation< ValueType, IndexType >
| ScaledPermutation is a matrix combining a permutation with scaling factors. More...
class | gko::matrix::Sellp< ValueType, IndexType >
| SELL-P is a matrix format similar to ELL format. More...
class | gko::matrix::SparsityCsr< ValueType, IndexType >
| SparsityCsr is a matrix format which stores only the sparsity pattern of a sparse matrix by compressing each row of the matrix (compressed sparse row format). More...
class | gko::multigrid::FixedCoarsening< ValueType, IndexType >
| FixedCoarsening is a very simple coarse grid generation algorithm. More...
class | gko::multigrid::Pgm< ValueType, IndexType >
| Parallel graph match (Pgm) is the aggregate method introduced in the paper M. More...
class | gko::preconditioner::Ic< LSolverTypeOrValueType, IndexType >
| The Incomplete Cholesky (IC) preconditioner solves the equation for a given lower triangular matrix L and the right hand side b (can contain multiple right hand sides). More...
class | gko::preconditioner::Ilu< LSolverTypeOrValueType, USolverTypeOrValueType, ReverseApply, IndexType >
| The Incomplete LU (ILU) preconditioner solves the equation for a given lower triangular matrix L, an upper triangular matrix U and the right hand side b (can contain multiple right hand sides). More...
class | gko::preconditioner::Isai< IsaiType, ValueType, IndexType >
| The Incomplete Sparse Approximate Inverse (ISAI) Preconditioner generates an approximate inverse matrix for a given square matrix A, lower triangular matrix L, upper triangular matrix U or symmetric positive (spd) matrix B. More...
class | gko::preconditioner::Jacobi< ValueType, IndexType >
| A block-Jacobi preconditioner is a block-diagonal linear operator, obtained by inverting the diagonal blocks of the source operator. More...
class | gko::solver::Bicg< ValueType >
| BICG or the Biconjugate gradient method is a Krylov subspace solver. More...
class | gko::solver::Bicgstab< ValueType >
| BiCGSTAB or the Bi-Conjugate Gradient-Stabilized is a Krylov subspace solver. More...
class | gko::solver::CbGmres< ValueType >
| CB-GMRES or the compressed basis generalized minimal residual method is an iterative type Krylov subspace method which is suitable for nonsymmetric linear systems. More...
class | gko::solver::Cg< ValueType >
| CG or the conjugate gradient method is an iterative type Krylov subspace method which is suitable for symmetric positive definite methods. More...
class | gko::solver::Cgs< ValueType >
| CGS or the conjugate gradient square method is an iterative type Krylov subspace method which is suitable for general systems. More...
class | gko::solver::Chebyshev< ValueType >
| Chebyshev iteration is an iterative method for solving nonsymmetric problems based on some knowledge of the spectrum of the (preconditioned) system matrix. More...
class | gko::solver::Fcg< ValueType >
| FCG or the flexible conjugate gradient method is an iterative type Krylov subspace method which is suitable for symmetric positive definite methods. More...
class | gko::solver::Gcr< ValueType >
| GCR or the generalized conjugate residual method is an iterative type Krylov subspace method similar to GMRES which is suitable for nonsymmetric linear systems. More...
class | gko::solver::Gmres< ValueType >
| GMRES or the generalized minimal residual method is an iterative type Krylov subspace method which is suitable for nonsymmetric linear systems. More...
class | gko::solver::Idr< ValueType >
| IDR(s) is an efficient method for solving large nonsymmetric systems of linear equations. More...
class | gko::solver::Minres< ValueType >
| Minres is an iterative type Krylov subspace method, which is suitable for indefinite and full-rank symmetric/hermitian operators. More...
class | gko::solver::Multigrid
| Multigrid methods have a hierarchy of many levels, whose corase level is a subset of the fine level, of the problem. More...
class | gko::solver::PipeCg< ValueType >
| PIPE_CG or the pipelined conjugate gradient method is an iterative type Krylov subspace method which is suitable for symmetric positive definite methods. More...
class | gko::solver::EnableSolverBase< DerivedType, MatrixType >
| A LinOp deriving from this CRTP class stores a system matrix. More...
class | gko::solver::IterativeBase
| A LinOp implementing this interface stores a stopping criterion factory. More...
class | gko::solver::EnableIterativeBase< DerivedType >
| A LinOp deriving from this CRTP class stores a stopping criterion factory and allows applying with a guess. More...
class | gko::solver::EnablePreconditionedIterativeSolver< ValueType, DerivedType >
| A LinOp implementing this interface stores a system matrix and stopping criterion factory. More...
class | gko::solver::LowerTrs< ValueType, IndexType >
| LowerTrs is the triangular solver which solves the system L x = b, when L is a lower triangular matrix. More...
class | gko::solver::UpperTrs< ValueType, IndexType >
| UpperTrs is the triangular solver which solves the system U x = b, when U is an upper triangular matrix. More...

## Macros
#define | GKO_CREATE_FACTORY_PARAMETERS(_parameters_name, _factory_name)
| This Macro will generate a new type containing the parameters for the factory _factory_name.
#define | GKO_ENABLE_BUILD_METHOD(_factory_name)
| Defines a build method for the factory, simplifying its construction by removing the repetitive typing of factory's name.
#define | GKO_FACTORY_PARAMETER(_name, ...)
| Creates a factory parameter in the factory parameters structure.
#define | GKO_FACTORY_PARAMETER_SCALAR(_name, _default)
| Creates a scalar factory parameter in the factory parameters structure.
#define | GKO_FACTORY_PARAMETER_VECTOR(_name, ...)
| Creates a vector factory parameter in the factory parameters structure.
#define | GKO_ENABLE_LIN_OP_FACTORY(_lin_op, _parameters_name, _factory_name)
| This macro will generate a default implementation of a LinOpFactory for the LinOp subclass it is defined in.

## Typedefs
template<typename ConcreteFactory, typename ConcreteLinOp, typename ParametersType, typename PolymorphicBase = LinOpFactory>
using | gko::EnableDefaultLinOpFactory
| This is an alias for the EnableDefaultFactory mixin, which correctly sets the template parameters to enable a subclass of LinOpFactory.

## Functions
template<typename Matrix, typename... TArgs>
std::unique_ptr< Matrix > | gko::initialize (size_type stride, std::initializer_list< typename Matrix::value_type > vals, std::shared_ptr< const Executor > exec, TArgs &&... create_args)
| Creates and initializes a column-vector.
template<typename Matrix, typename... TArgs>
std::unique_ptr< Matrix > | gko::initialize (std::initializer_list< typename Matrix::value_type > vals, std::shared_ptr< const Executor > exec, TArgs &&... create_args)
| Creates and initializes a column-vector.
template<typename Matrix, typename... TArgs>
std::unique_ptr< Matrix > | gko::initialize (size_type stride, std::initializer_list< std::initializer_list< typename Matrix::value_type > > vals, std::shared_ptr< const Executor > exec, TArgs &&... create_args)
| Creates and initializes a matrix.
template<typename Matrix, typename... TArgs>
std::unique_ptr< Matrix > | gko::initialize (std::initializer_list< std::initializer_list< typename Matrix::value_type > > vals, std::shared_ptr< const Executor > exec, TArgs &&... create_args)
| Creates and initializes a matrix.
bool | gko::solver::apply_uses_initial_guess () const override
| Iterative refinement (IR) is an iterative method that uses another coarse method to approximate the error of the current solution via the current residual.

## Detailed Description

A module dedicated to the implementation and usage of the Linear operators in Ginkgo.

Below we elaborate on one of the most important concepts of Ginkgo, the linear operator. The linear operator (LinOp) is a base class for all linear algebra objects in Ginkgo. The main benefit of having a single base class for the entire collection of linear algebra objects (as opposed to having separate hierarchies for matrices, solvers and preconditioners) is the generality it provides.

# Advantages of this approach and usage

A common interface often allows for writing more generic code. If a user's routine requires only operations provided by the LinOp interface, the same code can be used for any kind of linear operators, independent of whether these are matrices, solvers or preconditioners. This feature is also extensively used in Ginkgo itself. For example, a preconditioner used inside a Krylov solver is a LinOp. This allows the user to supply a wide variety of preconditioners: either the ones which were designed to be used in this scenario (like ILU or block-Jacobi), a user-supplied matrix which is known to be a good preconditioner for the specific problem, or even another solver (e.g., if constructing a flexible GMRES solver).

For example, a matrix free implementation would require the user to provide an apply implementation and instead of passing the generated matrix to the solver, they would have to provide their apply implementation for all the executors needed and no other code needs to be changed. See The custom-matrix-format program example for more details.

# Linear operator as a concept

The linear operator (LinOp) is a base class for all linear algebra objects in Ginkgo. The main benefit of having a single base class for the entire collection of linear algebra objects (as opposed to having separate hierarchies for matrices, solvers and preconditioners) is the generality it provides.

First, since all subclasses provide a common interface, the library users are exposed to a smaller set of routines. For example, a matrix-vector product, a preconditioner application, or even a system solve are just different terms given to the operation of applying a certain linear operator to a vector. As such, Ginkgo uses the same routine name, LinOp::apply() for each of these operations, where the actual operation performed depends on the type of linear operator involved in the operation.

Second, a common interface often allows for writing more generic code. If a user's routine requires only operations provided by the LinOp interface, the same code can be used for any kind of linear operators, independent of whether these are matrices, solvers or preconditioners. This feature is also extensively used in Ginkgo itself. For example, a preconditioner used inside a Krylov solver is a LinOp. This allows the user to supply a wide variety of preconditioners: either the ones which were designed to be used in this scenario (like ILU or block-Jacobi), a user-supplied matrix which is known to be a good preconditioner for the specific problem, or even another solver (e.g., if constructing a flexible GMRES solver).

A key observation for providing a unified interface for matrices, solvers, and preconditioners is that the most common operation performed on all of them can be expressed as an application of a linear operator to a vector:

- the sparse matrix-vector product with a matrix is a linear operator application ;
- the application of a preconditioner is a linear operator application , where is an approximation of the original system matrix (thus a preconditioner represents an "approximate inverse" operator ).
- the system solve can be viewed as linear operator application (it goes without saying that the implementation of linear system solves does not follow this conceptual idea), so a linear system solver can be viewed as a representation of the operator .

Finally, direct manipulation of LinOp objects is rarely required in simple scenarios. As an illustrative example, one could construct a fixed-point iteration routine as follows:

std::unique_ptr<matrix::Dense<>> calculate_fixed_point(
int iters, const LinOp *L, const matrix::Dense<> *x0
const matrix::Dense<> *b)
{
auto x = gko::clone(x0);
auto tmp = gko::clone(x0);
auto one = Dense<>::create(L->get_executor(), {1.0,});
for (int i = 0; i < iters; ++i) {
L->apply(tmp, x);
x->add_scaled(one, b);
tmp->copy_from(x);
}
return x;
}
gko::one
constexpr T one()
Returns the multiplicative identity for T.
Definition math.hpp:654
gko::clone
detail::cloned_type< Pointer > clone(const Pointer &p)
Creates a unique clone of the object pointed to by p.
Definition utils_helper.hpp:173

Here, if is a matrix, LinOp::apply() refers to the matrix vector product, and L->apply(a, b) computes . x->add_scaled(one, b) is the axpy vector update .

The interesting part of this example is the apply() routine at line 4 of the function body. Since this routine is part of the LinOp base class, the fixed-point iteration routine can calculate a fixed point not only for matrices, but for any type of linear operator.

Linear Operators

## Macro Definition Documentation

## ◆ GKO_CREATE_FACTORY_PARAMETERS

#define GKO_CREATE_FACTORY_PARAMETERS | ( |  | _parameters_name,
|  |  | _factory_name )

Value:
public: \
class _factory_name; \
struct _parameters_name##_type \
: public ::gko::enable_parameters_type<_parameters_name##_type, \
_factory_name>
gko::enable_parameters_type
The enable_parameters_type mixin is used to create a base implementation of the factory parameters st...
Definition abstract_factory.hpp:211

This Macro will generate a new type containing the parameters for the factory _factory_name.

For more details, see GKO_ENABLE_LIN_OP_FACTORY(). It is required to use this macro before calling the macro GKO_ENABLE_LIN_OP_FACTORY(). It is also required to use the same names for all parameters between both macros.

Parameters

  _parameters_name | name of the parameters member in the class
  _factory_name | name of the generated factory type

## ◆ GKO_ENABLE_BUILD_METHOD

#define GKO_ENABLE_BUILD_METHOD | ( |  | _factory_name | ) |

Value:
static auto build()->decltype(_factory_name::create()) \
{ \
return _factory_name::create(); \
} \
static_assert(true, \
"This assert is used to counter the false positive extra " \
"semi-colon warnings")

Defines a build method for the factory, simplifying its construction by removing the repetitive typing of factory's name.

Parameters

  _factory_name | the factory for which to define the method

## ◆ GKO_ENABLE_LIN_OP_FACTORY

#define GKO_ENABLE_LIN_OP_FACTORY | ( |  | _lin_op,
|  |  | _parameters_name,
|  |  | _factory_name )

This macro will generate a default implementation of a LinOpFactory for the LinOp subclass it is defined in.

It is required to first call the macro GKO_CREATE_FACTORY_PARAMETERS() before this one in order to instantiate the parameters type first.

The list of parameters for the factory should be defined in a code block after the macro definition, and should contain a list of GKO_FACTORY_PARAMETER_* declarations. The class should provide a constructor with signature _lin_op(const _factory_name *, std::shared_ptr<const LinOp>) which the factory will use a callback to construct the object.

A minimal example of a linear operator is the following:

struct MyLinOp : public EnableLinOp<MyLinOp> {
GKO_ENABLE_LIN_OP_FACTORY(MyLinOp, my_parameters, Factory) {
// a factory parameter named "my_value", of type int and default
// value of 5
int GKO_FACTORY_PARAMETER_SCALAR(my_value, 5);
// a factory parameter named `my_pair` of type `std::pair<int,int>`
// and default value {5, 5}
std::pair<int, int> GKO_FACTORY_PARAMETER_VECTOR(my_pair, 5, 5);
};
// constructor needed by EnableLinOp
explicit MyLinOp(std::shared_ptr<const Executor> exec) {
: EnableLinOp<MyLinOp>(exec) {}
// constructor needed by the factory
explicit MyLinOp(const Factory *factory,
std::shared_ptr<const LinOp> matrix)
: EnableLinOp<MyLinOp>(factory->get_executor()), matrix->get_size()),
// store factory's parameters locally
my_parameters_{factory->get_parameters()},
{
int value = my_parameters_.my_value;
// do something with value
}
GKO_FACTORY_PARAMETER_SCALAR
#define GKO_FACTORY_PARAMETER_SCALAR(_name, _default)
Creates a scalar factory parameter in the factory parameters structure.
Definition abstract_factory.hpp:445
GKO_ENABLE_LIN_OP_FACTORY
#define GKO_ENABLE_LIN_OP_FACTORY(_lin_op, _parameters_name, _factory_name)
This macro will generate a default implementation of a LinOpFactory for the LinOp subclass it is defi...
Definition lin_op.hpp:1017
GKO_FACTORY_PARAMETER_VECTOR
#define GKO_FACTORY_PARAMETER_VECTOR(_name,...)
Creates a vector factory parameter in the factory parameters structure.
Definition abstract_factory.hpp:461
gko::log::profile_event_category::factory
@ factory
LinOpFactory events.
Definition profiler_hook.hpp:32

MyLinOp can then be created as follows:

auto exec = gko::ReferenceExecutor::create();
// create a factory with default `my_value` parameter
auto fact = MyLinOp::build().on(exec);
// create a operator using the factory:
auto my_op = fact->generate(gko::matrix::Identity::create(exec, 2));
std::cout << my_op->get_my_parameters().my_value; // prints 5
// create a factory with custom `my_value` parameter
auto fact = MyLinOp::build().with_my_value(0).on(exec);
// create a operator using the factory:
auto my_op = fact->generate(gko::matrix::Identity::create(exec, 2));
std::cout << my_op->get_my_parameters().my_value; // prints 0
gko::matrix::Identity::create
static std::unique_ptr< Identity > create(std::shared_ptr< const Executor > exec, dim< 2 > size)
Creates an Identity matrix of the specified size.

Note
  It is possible to combine both the #GKO_CREATE_FACTORY_PARAMETER_*() macros with this one in a unique macro for class templates (not with regular classes). Splitting this into two distinct macros allows to use them in all contexts. See https://stackoverflow.com/q/50202718/9385966 for more details.

Parameters

  _lin_op | concrete operator for which the factory is to be created [CRTP parameter]
  _parameters_name | name of the parameters member in the class (its type is <_parameters_name>_type, the protected member's name is <_parameters_name>_, and the public getter's name is get_<_parameters_name>())
  _factory_name | name of the generated factory type

## ◆ GKO_FACTORY_PARAMETER

#define GKO_FACTORY_PARAMETER | ( |  | _name,
|  |  | ... )

Value:
_name{__VA_ARGS__}; \
\
template <typename... Args> \
auto with_##_name(Args&&... _value) \
->std::decay_t<decltype(*(this->self()))>& \
{ \
using type = decltype(this->_name); \
this->_name = type{std::forward<Args>(_value)...}; \
return *(this->self()); \
} \
static_assert(true, \
"This assert is used to counter the false positive extra " \
"semi-colon warnings")

Creates a factory parameter in the factory parameters structure.

Parameters

  _name | name of the parameter
  __VA_ARGS__ | default value of the parameter

See also
  GKO_ENABLE_LIN_OP_FACTORY for more details, and usage example

## ◆ GKO_FACTORY_PARAMETER_SCALAR

#define GKO_FACTORY_PARAMETER_SCALAR | ( |  | _name,
|  |  | _default )

Value:
GKO_FACTORY_PARAMETER(_name, _default)
GKO_FACTORY_PARAMETER
#define GKO_FACTORY_PARAMETER(_name,...)
Creates a factory parameter in the factory parameters structure.
Definition abstract_factory.hpp:417

Creates a scalar factory parameter in the factory parameters structure.

Scalar in this context means that the constructor for this type only takes a single parameter.

Parameters

  _name | name of the parameter
  _default | default value of the parameter

See also
  GKO_ENABLE_LIN_OP_FACTORY for more details, and usage example

## ◆ GKO_FACTORY_PARAMETER_VECTOR

#define GKO_FACTORY_PARAMETER_VECTOR | ( |  | _name,
|  |  | ... )

Value:
GKO_FACTORY_PARAMETER(_name, __VA_ARGS__)

Creates a vector factory parameter in the factory parameters structure.

Vector in this context means that the constructor for this type takes multiple parameters.

Parameters

  _name | name of the parameter
  _default | default value of the parameter

See also
  GKO_ENABLE_LIN_OP_FACTORY for more details, and usage example

## Typedef Documentation

## ◆ EnableDefaultLinOpFactory

template<typename ConcreteFactory, typename ConcreteLinOp, typename ParametersType, typename PolymorphicBase = LinOpFactory>

using gko::EnableDefaultLinOpFactory

Initial value:
EnableDefaultFactory<ConcreteFactory, ConcreteLinOp, ParametersType,
PolymorphicBase>
gko::EnableDefaultFactory
This mixin provides a default implementation of a concrete factory.
Definition abstract_factory.hpp:126

This is an alias for the EnableDefaultFactory mixin, which correctly sets the template parameters to enable a subclass of LinOpFactory.

Template Parameters

  ConcreteFactory | the concrete factory which is being implemented [CRTP parameter]
  ConcreteLinOp | the concrete LinOp type which this factory produces, needs to have a constructor which takes a const ConcreteFactory *, and an std::shared_ptr<const LinOp> as parameters.
  ParametersType | a subclass of enable_parameters_type template which defines all of the parameters of the factory
  PolymorphicBase | parent of ConcreteFactory in the polymorphic hierarchy, has to be a subclass of LinOpFactory

## Function Documentation

## ◆ apply_uses_initial_guess()

bool gko::solver::apply_uses_initial_guess | ( |  | ) | const
| override

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 Ae = residual, 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
gko::solver
The ginkgo Solve namespace.
Definition bicg.hpp:28

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 - error | <= c | e |, iterative refinement will converge with a convergence rate of c. Indeed, from e - error = x - solution - error = x - solution* (where solution* denotes the value stored in solution after the update) and e = inv(A) residual = inv(A)b - inv(A) A solution = x - solution it follows that | x - solution* | <= c | x - solution |.

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 Ax = 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 its eigenvalues lambda have to satisfy the equation `|relaxation_factor * lambda - 1| < 1).

Template Parameters

  ValueType | precision of matrix elements

*/ template <typename ValueType = default_precision>> class Ir : public EnableLinOp<Ir<ValueType>>, public EnableSolverBase<Ir<ValueType>>, public EnableIterativeBase<Ir<ValueType>>, public EnableApplyWithInitialGuess<Ir<ValueType>>, public Transposable { friend class EnableLinOp<Ir>; friend class EnablePolymorphicObject<Ir, LinOp>; friend class EnableApplyWithInitialGuess<Ir>; static_assert(::gko::detail::is_supported_value_type<ValueType>::value, "Unsupported value type") ;

public: using value_type = ValueType; using transposed_type = Ir<ValueType>;

std::unique_ptr<LinOp> transpose() const override;

std::unique_ptr<LinOp> conj_transpose() 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.

References provided.

## ◆ initialize() [1/4]

template<typename Matrix, typename... TArgs>

std::unique_ptr< Matrix > gko::initialize | ( | size_type | stride,
|  | std::initializer_list< std::initializer_list< typename Matrix::value_type > > | vals,
|  | std::shared_ptr< const Executor > | exec,
|  | TArgs &&... | create_args )

Creates and initializes a matrix.

This function first creates a temporary Dense matrix, fills it with passed in values, and then converts the matrix to the requested type.

Template Parameters

  Matrix | matrix type to initialize (Dense has to implement the ConvertibleTo<Matrix> interface)
  TArgs | argument types for Matrix::create method (not including the implied Executor as the first argument)

Parameters

  stride | row stride for the temporary Dense matrix
  vals | values used to initialize the matrix
  exec | Executor associated to the matrix
  create_args | additional arguments passed to Matrix::create, not including the Executor, which is passed as the first argument

## ◆ initialize() [2/4]

template<typename Matrix, typename... TArgs>

std::unique_ptr< Matrix > gko::initialize | ( | size_type | stride,
|  | std::initializer_list< typename Matrix::value_type > | vals,
|  | std::shared_ptr< const Executor > | exec,
|  | TArgs &&... | create_args )

Creates and initializes a column-vector.

This function first creates a temporary Dense matrix, fills it with passed in values, and then converts the matrix to the requested type.

Template Parameters

  Matrix | matrix type to initialize (Dense has to implement the ConvertibleTo<Matrix> interface)
  TArgs | argument types for Matrix::create method (not including the implied Executor as the first argument)

Parameters

  stride | row stride for the temporary Dense matrix
  vals | values used to initialize the vector
  exec | Executor associated to the vector
  create_args | additional arguments passed to Matrix::create, not including the Executor, which is passed as the first argument

Referenced by gko::log::ProfilerHook::create_tau(), initialize(), and initialize().

## ◆ initialize() [3/4]

template<typename Matrix, typename... TArgs>

std::unique_ptr< Matrix > gko::initialize | ( | std::initializer_list< std::initializer_list< typename Matrix::value_type > > | vals,
|  | std::shared_ptr< const Executor > | exec,
|  | TArgs &&... | create_args )

Creates and initializes a matrix.

This function first creates a temporary Dense matrix, fills it with passed in values, and then converts the matrix to the requested type. The stride of the intermediate Dense matrix is set to the number of columns of the initializer list.

Template Parameters

  Matrix | matrix type to initialize (Dense has to implement the ConvertibleTo<Matrix> interface)
  TArgs | argument types for Matrix::create method (not including the implied Executor as the first argument)

Parameters

  vals | values used to initialize the matrix
  exec | Executor associated to the matrix
  create_args | additional arguments passed to Matrix::create, not including the Executor, which is passed as the first argument

References initialize().

## ◆ initialize() [4/4]

template<typename Matrix, typename... TArgs>

std::unique_ptr< Matrix > gko::initialize | ( | std::initializer_list< typename Matrix::value_type > | vals,
|  | std::shared_ptr< const Executor > | exec,
|  | TArgs &&... | create_args )

Creates and initializes a column-vector.

This function first creates a temporary Dense matrix, fills it with passed in values, and then converts the matrix to the requested type. The stride of the intermediate Dense matrix is set to 1.

Template Parameters

  Matrix | matrix type to initialize (Dense has to implement the ConvertibleTo<Matrix> interface)
  TArgs | argument types for Matrix::create method (not including the implied Executor as the first argument)

Parameters

  vals | values used to initialize the vector
  exec | Executor associated to the vector
  create_args | additional arguments passed to Matrix::create, not including the Executor, which is passed as the first argument

References initialize().