# Runtime interface¶

The compile-time configuration of the solvers used in AMGCL is not always convenient, especially if the solvers are used inside a software package or another library. That is why AMGCL provides runtime interface, which allows to postpone the configuration until, well, runtime. The classes inside amgcl::runtime namespace correspond to their compile-time alternatives, but the only template parameter they have is the backend to use.

Since there is no way of knowing the parameter structure at compile time, the runtime classes accept parameters only in form of boost::property_tree::ptree. The actual components of the method are set through the parameter tree as well. The runtime interface provides some enumerations for this purpose. For example, to select smoothed aggregation for coarsening, we could do this:

boost::property_tree::ptree prm;
prm.put("precond.coarsening.type", amgcl::runtime::coarsening::smoothed_aggregation);


The enumerations provide functions for converting to/from strings, so the following would work as well:

prm.put("precond.coarsening.type", "smoothed_aggregation");


Here is an example of using a runtime-configurable solver:

#include <amgcl/backend/builtin.hpp>
#include <amgcl/runtime.hpp>

...

boost::property_tree::ptree prm;
prm.put("precond.coarsening.type", amgcl::runtime::coarsening::smoothed_aggregation);
prm.put("precond.relaxation.type", amgcl::runtime::relaxation::spai0);
prm.put("solver.type",             amgcl::runtime::solver::gmres);

amgcl::make_solver<
amgcl::runtime::amg<Backend>,
amgcl::runtime::iterative_solver<Backend>
> solve(A, prm);


## Classes¶

### AMG preconditioner¶

template <class Backend>
class amgcl::runtime::amg

Runtime-configurable AMG preconditioner.

Inherits from noncopyable

Public Functions

template <class Matrix>
amg(const Matrix &A, params prm = params(), const backend_params &backend_prm = backend_params())

Constructs the AMG hierarchy for the system matrix A.

prm is an instance of boost::property_tree::ptree class. The property tree may contain parameters “coarsening.type” and “relax.type”. Default values are amgcl::runtime::coarsening::smoothed_aggregation and runtime::relaxation::spai0. The rest of the property tree should copy the structure of the corresponding amgcl::amg::params struct. For example, when smoothed aggregation is selected for coarsening, one could:

prm.put("coarsening.aggr.eps_strong", 1e-2);


Note

Any parameters that are not relevant to the selected AMG components are silently ignored.

template <class Vec1, class Vec2>
void cycle(const Vec1 &rhs, Vec2 &x) const

Performs single V-cycle for the given right-hand side rhs and solution x.

template <class Vec1, class Vec2>
void apply(const Vec1 &rhs, Vec2 &x) const

Performs single V-cycle for the given right-hand side rhs after clearing x. This is intended for use as a preconditioning procedure.

const matrix &system_matrix() const

Returns the system matrix in the backend format

size_t size() const

Returns the problem size at the finest level.

Friends

std::ostream &operator<<(std::ostream &os, const amg &a)

Prints some info about the AMG hierarchy to the output stream.

enum amgcl::runtime::coarsening::type

Values:

ruge_stuben

Ruge-Stueben coarsening.

aggregation

Aggregation.

smoothed_aggregation

Smoothed aggregation.

smoothed_aggr_emin

Smoothed aggregation with energy minimization.

enum amgcl::runtime::relaxation::type

Relaxation schemes.

Values:

gauss_seidel

Gauss-Seidel smoothing.

ilu0

Incomplete LU with zero fill-in.

iluk

Level-based incomplete LU.

ilut

Incomplete LU with thresholding.

damped_jacobi

Damped Jacobi.

spai0

Sparse approximate inverse of 0th order.

spai1

Sparse approximate inverse of 1st order.

chebyshev

Chebyshev relaxation.

### Iterative solver¶

template <class Backend, class InnerProduct = amgcl::solver::detail::default_inner_product>
class amgcl::runtime::iterative_solver

This is runtime wrapper around AMGCL iterative solver types. Allows to select the actual solver at runtime.

Public Functions

iterative_solver(size_t n, params prm = params(), const backend_params &bprm = backend_params(), const InnerProduct &inner_product = InnerProduct())

Constructs the iterative solver for the problem size n.

The property tree solver_prm may contain “type” entry that would determine the actual type of the iterative solver. Default value: amgcl::runtime::solver::bicgstab.

Note

Any parameters that are not relevant to the selected solver are silently ignored.

template <class Matrix, class Precond, class Vec1, class Vec2>
boost::tuple<size_t, scalar_type> operator()(Matrix const &A, Precond const &P, Vec1 const &rhs, Vec2 &&x) const

Computes the solution for the given system matrix A and the right-hand side rhs. Returns the number of iterations made and the achieved residual as a boost::tuple. The solution vector x provides initial approximation in input and holds the computed solution on output.

The system matrix may differ from the matrix used during initialization. This may be used for the solution of non-stationary problems with slowly changing coefficients. There is a strong chance that a preconditioner built for a time step will act as a reasonably good preconditioner for several subsequent time steps [DeSh12].

template <class Precond, class Vec1, class Vec2>
boost::tuple<size_t, scalar_type> operator()(Precond const &P, Vec1 const &rhs, Vec2 &&x) const

Computes the solution for the given right-hand side rhs. The system matrix is the same that was used for the setup of the preconditioner P. Returns the number of iterations made and the achieved residual as a boost::tuple. The solution vector x provides initial approximation in input and holds the computed solution on output.

enum amgcl::runtime::solver::type

Values:

cg

bicgstab

bicgstabl

BiCGStab(ell)

gmres

GMRES.

lgmres

LGMRES.

fgmres

FGMRES.

idrs

IDR(s)