Skip to content

Commit

Permalink
runtime
Browse files Browse the repository at this point in the history
  • Loading branch information
@ddemidov
ddemidov committed Jan 15, 2016
1 parent ec62069 commit cf1c1a4
Show file tree
Hide file tree
Showing 3 changed files with 100 additions and 69 deletions.
117 changes: 58 additions & 59 deletions amgcl/runtime.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -474,25 +474,26 @@ class amg : boost::noncopyable {

typedef boost::property_tree::ptree params;

/// Constructs the AMG hierarchy.
/**
* \param A The system matrix.
* \param prm Parameters.
/** Constructs the AMG hierarchy for the system matrix \p A.
* \rst
* ``prm`` is an instance of ``boost::property_tree::ptree`` class.
* The property tree may contain parameters "coarsening.type" and
* "relaxation.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:
*
* \note The prm argument is an instance of boost::property_tree::ptree
* class. The structure of the property tree should copy the structure
* of amgcl::AMG::params struct. E.g., one could
\code
prm.put("coarsening.aggr.eps_strong", 1e-2);
\endcode
* .. code-block:: cpp
*
* Additionally, the property tree may contain parameters
* "coarsening.type" and "relaxation.type". If those are missing,
* default values of runtime::coarsening::smoothed_aggregation and
* runtime::relaxation::spai0 will be selected.
* prm.put("coarsening.aggr.eps_strong", 1e-2);
*
* Any parameters that are not relevant to the current AMG class, are
* silently ignored.
* .. note::
*
* Any parameters that are not relevant to the selected AMG
* components are silently ignored.
* \endrst
*/
template <class Matrix>
amg(
Expand All @@ -510,26 +511,24 @@ class amg : boost::noncopyable {
);
}

/// Destructor.
// Destructor.
~amg() {
runtime::detail::process_amg<Backend>(
coarsening, relaxation,
runtime::detail::amg_destroy(handle)
);
}

/// Fills the property tree with the actual parameters used.
// Fills the property tree with the actual parameters used.
void get_params(boost::property_tree::ptree &p) const {
runtime::detail::process_amg<Backend>(
coarsening, relaxation,
runtime::detail::amg_get_params(handle, p)
);
}

/// Performs single V-cycle for the given right-hand side and solution.
/**
* \param rhs Right-hand side vector.
* \param x Solution vector.
/** Performs single V-cycle for the given right-hand side \p rhs and
* solution \p x.
*/
template <class Vec1, class Vec2>
void cycle(const Vec1 &rhs, Vec2 &x) const {
Expand All @@ -539,12 +538,9 @@ class amg : boost::noncopyable {
);
}

/// Performs single V-cycle after clearing x.
/**
* This is intended for use as a preconditioning procedure.
*
* \param rhs Right-hand side vector.
* \param x Solution vector.
/** Performs single V-cycle for the given right-hand side \p rhs after
* clearing \p x. This is intended for use as a preconditioning
* procedure.
*/
template <class Vec1, class Vec2>
void apply(const Vec1 &rhs, Vec2 &x) const {
Expand All @@ -554,7 +550,7 @@ class amg : boost::noncopyable {
);
}

/// Returns the system matrix from the finest level.
/** Returns the system matrix in the backend format */
const matrix& system_matrix() const {
runtime::detail::amg_system_matrix<matrix> top(handle);
runtime::detail::process_amg<Backend>(
Expand All @@ -563,12 +559,12 @@ class amg : boost::noncopyable {
return *top.matrix;
}

/// Returns problem size at the finest level.
/** Returns the problem size at the finest level. */
size_t size() const {
return backend::rows( system_matrix() );
}

/// Sends information about the AMG hierarchy to output stream.
/// Prints some info about the AMG hierarchy to the output stream.
friend std::ostream& operator<<(std::ostream &os, const amg &a)
{
runtime::detail::process_amg<Backend>(
Expand Down Expand Up @@ -750,6 +746,9 @@ struct solver_solve {

} // namespace detail

/** This is runtime wrapper around AMGCL iterative solver types. Allows to
* select the actual solver at runtime.
*/
template <
class Backend,
class InnerProduct = amgcl::solver::detail::default_inner_product
Expand All @@ -765,18 +764,17 @@ class iterative_solver {

typedef typename math::scalar_of<value_type>::type scalar_type;

/// Constructs the iterative solver.
/**
* \param n System size.
* \param solver_prm Solver parameters.
* \param backend_prm Backend parameters.
/** Constructs the iterative solver for the problem size \p n.
* \rst
* 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``.
*
* The solver_prm property tree may contain "type" entry that would be
* used for determination of iterative solver type. When left
* unspecified, runtime::solver::bicgstab would be used by default.
* .. note::
*
* Any parameters that are not relevant to the current solver classes
* are silently ignored.
* Any parameters that are not relevant to the selected solver are
* silently ignored.
* \endrst
*/
iterative_solver(
size_t n,
Expand All @@ -794,27 +792,27 @@ class iterative_solver {
);
}

/// Destructor.
// Destructor.
~iterative_solver() {
runtime::detail::process_solver<Backend, InnerProduct>(
solver,
runtime::detail::solver_destroy(handle)
);
}

/// Solves the linear system for the given system matrix.
/**
* \param A System matrix.
* \param P Preconditioner.
* \param rhs Right-hand side.
* \param x Solution vector.
/** Computes the solution for the given system matrix \p A and the
* right-hand side \p rhs. Returns the number of iterations made and
* the achieved residual as a ``boost::tuple``. The solution vector
* \p x provides initial approximation in input and holds the computed
* solution on output.
*
* The system matrix may differ from the matrix used for the AMG
* preconditioner construction. This may be used for the solution of
* non-stationary problems with slowly changing coefficients. There is
* a strong chance that AMG built for one time step will act as a
* reasonably good preconditioner for several subsequent time steps
* \cite Demidov2012.
* \rst
* 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]_.
* \endrst
*/
template <class Matrix, class Precond, class Vec1, class Vec2>
boost::tuple<size_t, scalar_type> operator()(
Expand All @@ -840,11 +838,12 @@ class iterative_solver {
return boost::make_tuple(iters, resid);
}

/// Solves the linear system for the same matrix that was used for the preconditioner construction.
/**
* \param P Preconditioner.
* \param rhs Right-hand side.
* \param x Solution vector.
/** Computes the solution for the given right-hand side \p rhs. The
* system matrix is the same that was used for the setup of the
* preconditioner \p P. Returns the number of iterations made and the
* achieved residual as a ``boost::tuple``. The solution vector \p x
* provides initial approximation in input and holds the computed
* solution on output.
*/
template <class Precond, class Vec1, class Vec2>
boost::tuple<size_t, scalar_type> operator()(
Expand Down
12 changes: 5 additions & 7 deletions docs/_static/custom.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,16 @@ table.citation td {
max-width: 80%;
}

pre {
box-shadow: 0px 1px 6px 0px lightgray;
pre, dl.class, dl.type {
box-shadow: 0px 1px 6px 1px lightgray;
}

dl.class {
dl.class, dl.type {
padding: 5px;
box-shadow: 0px 1px 6px 0px lightgray;
}

dl.type {
padding: 5px;
box-shadow: 0px 1px 6px 0px lightgray;
.breathe-sectiondef {
width: auto;
}

pre {
Expand Down
40 changes: 37 additions & 3 deletions docs/runtime.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,27 @@ another library. That is why AMGCL provides runtime interface, which allows to
postpone the configuration until, well, runtime. The classes inside
:cpp:any:`amgcl::runtime` namespace correspond to their compile-time
alternatives, but the only template parameter they have is the backend to use.
The runtime classes accept parameters only as ``boost::property_tree::ptree``
for obvious reasons. Here is an example of using a runtime-configurable
solver:

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:

.. code-block:: cpp
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:

.. code-block:: cpp
prm.put("precond.coarsening.type", "smoothed_aggregation");
Here is an example of using a runtime-configurable solver:

.. code-block:: cpp
Expand All @@ -28,8 +46,24 @@ solver:
amgcl::runtime::iterative_solver<Backend>
> solve(A, prm);
Classes
-------

AMG preconditioner
##################

.. doxygenclass:: amgcl::runtime::amg
:members:

.. doxygenenum:: amgcl::runtime::coarsening::type

.. doxygenenum:: amgcl::runtime::relaxation::type

Iterative solver
################

.. doxygenclass:: amgcl::runtime::iterative_solver
:members:

.. doxygenenum:: amgcl::runtime::solver::type

0 comments on commit cf1c1a4

Please sign in to comment.