gko::preconditioner::Ic#

Incomplete Cholesky preconditioner. Given an incomplete Cholesky factor \(L\) (computed externally or via gko::factorization::Ic / gko::factorization::ParIc), apply(b, x) solves \(L L^H x = b\) by chaining a lower-triangular solve with its conjugate-transpose. Used to precondition symmetric positive-definite systems.

template<typename ValueType = default_precision, typename IndexType = int32>
class Ic #

Inherits from

The Incomplete Cholesky (IC) preconditioner solves the equation \(LL^H*x = b\) for a given lower triangular matrix L and the right hand side b (can contain multiple right hand sides).

It allows setting the solver for L, defaulting to solver::LowerTrs, which is a direct triangular solvers. The solver for L^H is the conjugate-transposed solver for L, ensuring that the preconditioner is symmetric and positive-definite. For this L solver, a factory can be provided (using with_l_solver) to have more control over their behavior. In particular, it is possible to use an iterative method for solving the triangular systems.

An object of this class can be created with a matrix or a gko::Composition containing two matrices. If created with a matrix, it is factorized before creating the solver. If a gko::Composition (containing two matrices) is used, the first operand will be taken as the L matrix, the second will be considered the L^H matrix, which helps to avoid the otherwise necessary transposition of L inside the solver. ParIc can be directly used, since it orders the factors in the correct way.

Note

When providing a gko::Composition, the first matrix must be the lower matrix ( \(L\)), and the second matrix must be its conjugate-transpose ( \(L^H\)). If they are swapped, solving might crash or return the wrong result.

Note

Do not use symmetric solvers (like CG) for the L solver since both matrices (L and L^H) are, by design, not symmetric.

Note

This class is not thread safe (even a const object is not) because it uses an internal cache to accelerate multiple (sequential) applies. Using it in parallel can lead to segmentation faults, wrong results and other unwanted behavior.

Note

The default template during parse is <ValueType, IndexType> not <LowerTrs, IndexType>. Only the variants with ValueType are supported in parse.

Template Parameters:

  • ValueType – the value type used for the L matrix.

  • IndexType – type of the indices when ParIc is used to generate the L and L^H factors. Irrelevant otherwise.

Public Functions

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

Returns the solver which is used for the provided L matrix.

Returns:

the solver which is used for the provided L matrix

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

Returns the solver which is used for the L^H matrix.

Returns:

the solver which is used for the L^H matrix

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

Ic &operator=(const Ic &other)#

Copy-assigns an IC preconditioner. Preserves the executor, shallow-copies the solvers and parameters. Creates a clone of the solvers if they are on the wrong executor.

Ic &operator=(Ic &&other)#

Move-assigns an IC preconditioner. Preserves the executor, moves the solvers and parameters. Creates a clone of the solvers if they are on the wrong executor. The moved-from object is empty (0x0 with nullptr solvers and default parameters)

Ic(const Ic &other)#

Copy-constructs an IC preconditioner. Inherits the executor, shallow-copies the solvers and parameters.

Ic(Ic &&other)#

Move-constructs an IC preconditioner. Inherits the executor, moves the solvers and parameters. The moved-from object is empty (0x0 with nullptr solvers and default parameters)

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<value_type, index_type>(),
)#

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.

Note

only support the following when using <ValueType, IndexType> not <LSolverType, IndexType> variants

Parameters:

  • config – the property tree for setting

  • context – the registry

  • td_for_child – the type descriptor for children configs. The default uses the value/index type of this class. When l_solver_type uses LinOp not concrete type, it will use the default_precision in ginkgo.

Returns:

parameters

struct parameters_type #

Inherits from

Public Functions

inline parameters_type &with_l_solver(
deferred_factory_parameter<const LinOpFactory> solver,
)#

When LSolverTypeOrValueType is a concrete solver type, this only accepts the factory from the same concrete solver type. When LSolverTypeOrValueType is a value type, it accepts any LinOpFactory.

Public Members

std::shared_ptr<const LinOpFactory> l_solver_factory = {}#

Factory for the L solver

std::shared_ptr<const LinOpFactory> factorization_factory = {}#

Factory for the factorization