Skip to content

Commit

Permalink
solvers
Browse files Browse the repository at this point in the history
  • Loading branch information
@ddemidov
ddemidov committed Jan 14, 2016
1 parent 62eb9e2 commit 059fa5f
Show file tree
Hide file tree
Showing 9 changed files with 186 additions and 117 deletions.
46 changes: 23 additions & 23 deletions amgcl/solver/bicgstab.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,11 +39,12 @@ THE SOFTWARE.
namespace amgcl {
namespace solver {

/// BiCGStab iterative solver.
/**
* \param Backend Backend for temporary structures allocation.
* \ingroup solvers
* \sa \cite Barrett1994
/** BiConjugate Gradient Stabilized (BiCGSTAB) method.
* \rst
* The BiConjugate Gradient Stabilized method (Bi-CGSTAB) was developed to
* solve nonsymmetric linear systems while avoiding the often irregular
* convergence patterns of the Conjugate Gradient [Barr94]_.
* \endrst
*/
template <
class Backend,
Expand Down Expand Up @@ -87,7 +88,7 @@ class bicgstab {
}
};

/// \copydoc amgcl::solver::cg::cg
/// Preallocates necessary data structures for the system of size \p n.
bicgstab(
size_t n,
const params &prm = params(),
Expand All @@ -106,19 +107,17 @@ class bicgstab {
inner_product(inner_product)
{ }

/// 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.
* 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 Matrix, class Precond, class Vec1, class Vec2>
boost::tuple<size_t, scalar_type> operator()(
Expand Down Expand Up @@ -198,11 +197,12 @@ class bicgstab {
return boost::make_tuple(iter, res / norm_rhs);
}

/// Solves the linear system for the same matrix that was used for the AMG preconditioner construction.
/**
* \param P AMG 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
44 changes: 21 additions & 23 deletions amgcl/solver/bicgstabl.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,10 @@ THE SOFTWARE.
namespace amgcl {
namespace solver {

/// BiCGStab(L) iterative solver.
/**
* \param Backend Backend for temporary structures allocation.
* \ingroup solvers
* \sa \cite Sleijpen1993
/** BiCGStab(L) method.
* \rst
* Generalization of BiCGStab method [SlDi93]_.
* \endrst
*/
template <
class Backend,
Expand Down Expand Up @@ -96,7 +95,7 @@ class bicgstabl {
}
};

/// \copydoc amgcl::solver::cg::cg
/// Preallocates necessary data structures for the system of size \p n.
bicgstabl(
size_t n,
const params &prm = params(),
Expand All @@ -117,19 +116,17 @@ class bicgstabl {
}
}

/// 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.
* 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 Matrix, class Precond, class Vec1, class Vec2>
boost::tuple<size_t, scalar_type> operator()(
Expand Down Expand Up @@ -249,11 +246,12 @@ class bicgstabl {
return boost::make_tuple(iter, res_norm / norm_rhs);
}

/// Solves the linear system for the same matrix that was used for the AMG preconditioner construction.
/**
* \param P AMG 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
49 changes: 21 additions & 28 deletions amgcl/solver/cg.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,11 +53,10 @@ namespace solver {
*/


/// Conjugate Gradients iterative solver.
/**
* \param Backend Backend for temporary structures allocation.
* \ingroup solvers
* \sa \cite Barrett1994
/** Conjugate Gradients method.
* \rst
* An effective method for symmetric positive definite systems [Barr94]_.
* \endrst
*/
template <
class Backend,
Expand Down Expand Up @@ -100,12 +99,7 @@ class cg {
}
};

/// Preallocates necessary data structures
/**
* \param n The system size.
* \param prm Solver parameters.
* \param backend_prm Backend parameters.
*/
/// Preallocates necessary data structures for the system of size \p n.
cg(
size_t n,
const params &prm = params(),
Expand All @@ -119,19 +113,17 @@ class cg {
inner_product(inner_product)
{ }

/// 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.
* 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 Matrix, class Precond, class Vec1, class Vec2>
boost::tuple<size_t, scalar_type> operator()(
Expand Down Expand Up @@ -190,11 +182,12 @@ class cg {
return boost::make_tuple(iter, res_norm / norm_rhs);
}

/// Solves the linear system for the same matrix that was used for the AMG preconditioner construction.
/**
* \param P AMG 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
45 changes: 22 additions & 23 deletions amgcl/solver/gmres.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,11 @@ THE SOFTWARE.
namespace amgcl {
namespace solver {

/// GMRES iterative solver.
/**
* \param Backend Backend for temporary structures allocation.
* \ingroup solvers
* \sa \cite Barrett1994
/** Generalized Minimal Residual (GMRES) method.
* \rst
* The Generalized Minimal Residual method is an extension of MINRES (which is
* only applicable to symmetric systems) to unsymmetric systems [Barr94]_.
* \endrst
*/
template <
class Backend,
Expand Down Expand Up @@ -97,7 +97,7 @@ class gmres {
}
};

/// \copydoc amgcl::solver::cg::cg
/// Preallocates necessary data structures for the system of size \p n.
gmres(
size_t n,
const params &prm = params(),
Expand All @@ -116,19 +116,17 @@ class gmres {
v.push_back( Backend::create_vector(n, backend_prm) );
}

/// 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.
* 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 Matrix, class Precond, class Vec1, class Vec2>
boost::tuple<size_t, scalar_type> operator()(
Expand Down Expand Up @@ -169,11 +167,12 @@ class gmres {
return boost::make_tuple(iter, res_norm / norm_rhs);
}

/// Solves the linear system for the same matrix that was used for the AMG preconditioner construction.
/**
* \param P AMG 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
34 changes: 19 additions & 15 deletions docs/adapters.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,13 @@ example of creating an adapter is provided in :doc:`custom_adapter`.
Boost tuple adapter
########################

``#include`` `\<amgcl/adapter/crs_tuple.hpp>`_

The Boost tuple adapter allows to use a ``boost::tuple`` of a matrix size and
its three CRS_ format components (row pointer array, column indices array, and
values array) as input matrix to AMGCL solvers. The arrays are allowed to be in
any format recognized by the Boost.Range_ library as a random access range.
Common examples are STL vectors and Boost `iterator ranges`_. The adapter is
defined in `amgcl/adapter/crs_tuple.hpp`_
Common examples are STL vectors and Boost `iterator ranges`_.

Example:

Expand All @@ -34,9 +35,11 @@ Example:
Boost.uBLAS adapter
###################

The Boost.uBLAS_ adapter (`amgcl/adapter/ublas.hpp`_) allows to use uBLAS
sparse matrices as input to AMGCL solvers. It also allows to use uBLAS dense
vectors with :cpp:class:`amgcl::backend::builtin`.
``#include`` `\<amgcl/adapter/ublas.hpp>`_

The Boost.uBLAS_ adapter allows to use uBLAS sparse matrices as input to AMGCL
solvers. It also allows to use uBLAS dense vectors with
:cpp:class:`amgcl::backend::builtin`.

Example:

Expand All @@ -55,17 +58,18 @@ Example:
Zero copy adapter
#################

``#include`` `\<amgcl/adapter/zero_copy.hpp>`_

In general, AMGCL copies the adapted input matrix into its internal structures,
so that the matrix may be safely destroyed or reused as soon as the solver
setup is complete. However, the memory overhead of the copying may be too
large, especially for large problems that eat up almost all of available RAM.
The zero copy adapter (`amgcl/adapter/zero_copy.hpp`_) allows to use raw
pointers to CRS arrays as input matrix for MAGCL solvers. The data from the
arrays is never copied during setup, and the user has to make sure the arrays
stay alive long enough. However, unless the backend used is
:cpp:class:`amgcl::backend::builtin`, the input matrix will be copied into the
backend structures when the setup is finished. This would still allow to save
some memory in case of GPGPU backends.
The zero copy adapter allows to use raw pointers to CRS arrays as input matrix
for MAGCL solvers. The data from the arrays is never copied during setup, and
the user has to make sure the arrays stay alive long enough. However, unless
the backend used is :cpp:class:`amgcl::backend::builtin`, the input matrix will
be copied into the backend structures when the setup is finished. This would
still allow to save some memory in case of GPGPU backends.

The one requirement is that the integer types stored in row pointers and column
indices arrays have to be binary compatible with ``ptrdiff_t``, and the value
Expand All @@ -83,6 +87,6 @@ Example:
.. _iterator ranges: http://www.boost.org/doc/libs/release/libs/range/doc/html/range/reference/utilities/iterator_range.html
.. _Boost.uBLAS: http://www.boost.org/doc/libs/release/libs/numeric/ublas/

.. _amgcl/adapter/crs_tuple.hpp: https://github.com/ddemidov/amgcl/blob/master/amgcl/adapter/crs_tuple.hpp
.. _amgcl/adapter/ublas.hpp: https://github.com/ddemidov/amgcl/blob/master/amgcl/adapter/ublas.hpp
.. _amgcl/adapter/zero_copy.hpp: https://github.com/ddemidov/amgcl/blob/master/amgcl/adapter/zero_copy.hpp
.. _\<amgcl/adapter/crs_tuple.hpp>: https://github.com/ddemidov/amgcl/blob/master/amgcl/adapter/crs_tuple.hpp
.. _\<amgcl/adapter/ublas.hpp>: https://github.com/ddemidov/amgcl/blob/master/amgcl/adapter/ublas.hpp
.. _\<amgcl/adapter/zero_copy.hpp>: https://github.com/ddemidov/amgcl/blob/master/amgcl/adapter/zero_copy.hpp

0 comments on commit 059fa5f

Please sign in to comment.