finishing backends

amgcl/backend/builtin.hpp

@@ -335,7 +335,7 @@ struct builtin {
     typedef std::vector<value_type>        matrix_diagonal;
     typedef solver::skyline_lu<value_type> direct_solver;
 
-    /// Backend parameters.
+    /// The backend has no parameters.
     struct params {
         params() {}
         params(const boost::property_tree::ptree&) {}
@@ -344,32 +344,30 @@ struct builtin {
 
     static std::string name() { return "builtin"; }
 
-    /// Copy matrix.
-    /** This is a noop for builtin backend. */
+    // Copy matrix. This is a noop for builtin backend.
     static boost::shared_ptr<matrix>
     copy_matrix(boost::shared_ptr<matrix> A, const params&)
     {
         return A;
     }
 
-    /// Copy vector to builtin backend.
+    // Copy vector to builtin backend.
     template <class T>
     static boost::shared_ptr< std::vector<T> >
     copy_vector(const std::vector<T> &x, const params&)
     {
         return boost::make_shared< std::vector<T> >(x);
     }
 
-    /// Copy vector to builtin backend.
-    /** This is a noop for builtin backend. */
+    // Copy vector to builtin backend. This is a noop for builtin backend.
     template <class T>
     static boost::shared_ptr< std::vector<T> >
     copy_vector(boost::shared_ptr< std::vector<T> > x, const params&)
     {
         return x;
     }
 
-    /// Create vector of the specified size.
+    // Create vector of the specified size.
     static boost::shared_ptr<vector>
     create_vector(size_t size, const params&)
     {
@@ -402,7 +400,7 @@ struct builtin {
         }
     };
 
-    /// Create direct solver for coarse level
+    // Create direct solver for coarse level
     static boost::shared_ptr<direct_solver>
     create_solver(boost::shared_ptr<matrix> A, const params&) {
         return boost::make_shared<direct_solver>(*A);

amgcl/backend/vexcl.hpp

@@ -65,10 +65,10 @@ struct vexcl {
 
     struct provides_row_iterator : boost::false_type {};
 
-    /// Backend parameters.
+    /// The VexCL backend parameters.
     struct params {
-        /// Command queues that identify compute devices to use with VexCL.
-        std::vector< vex::backend::command_queue > q;
+
+        std::vector< vex::backend::command_queue > q; ///< Command queues that identify compute devices to use with VexCL.
 
         params() {}
 
@@ -93,7 +93,7 @@ struct vexcl {
 
     static std::string name() { return "vexcl"; }
 
-    /// Copy matrix from builtin backend.
+    // Copy matrix from builtin backend.
     static boost::shared_ptr<matrix>
     copy_matrix(boost::shared_ptr< typename builtin<real>::matrix > A, const params &prm)
     {
@@ -108,7 +108,7 @@ struct vexcl {
         return boost::make_shared<matrix>(prm.context(), rows(*A), cols(*A), Aptr, Acol, Aval);
     }
 
-    /// Copy vector from builtin backend.
+    // Copy vector from builtin backend.
     static boost::shared_ptr<vector>
     copy_vector(typename builtin<real>::vector const &x, const params &prm)
     {
@@ -117,14 +117,14 @@ struct vexcl {
         return boost::make_shared<vector>(prm.context(), x);
     }
 
-    /// Copy vector from builtin backend.
+    // Copy vector from builtin backend.
     static boost::shared_ptr<vector>
     copy_vector(boost::shared_ptr< typename builtin<real>::vector > x, const params &prm)
     {
         return copy_vector(*x, prm);
     }
 
-    /// Create vector of the specified size.
+    // Create vector of the specified size.
     static boost::shared_ptr<vector>
     create_vector(size_t size, const params &prm)
     {
@@ -166,7 +166,7 @@ struct vexcl {
     };
 
 
-    /// Create direct solver for coarse level
+    // Create direct solver for coarse level
     static boost::shared_ptr<direct_solver>
     create_solver(boost::shared_ptr< typename builtin<real>::matrix > A, const params &prm)
     {

amgcl/make_solver.hpp

@@ -58,8 +58,7 @@ class make_solver {
 
         typedef typename math::scalar_of<value_type>::type scalar_type;
 
-        /**
-         * Combined parameters of the bundled preconditioner and the iterative
+        /** Combined parameters of the bundled preconditioner and the iterative
          * solver.
          */
         struct params {
@@ -106,9 +105,8 @@ class make_solver {
             S(backend::rows(*A), prm.solver, bprm)
         {}
 
-        /**
-         * Computes the solution for the given system matrix \p A and the
-         * right hand side \p rhs.  Returns the number of iterations made and
+        /** 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.
@@ -135,7 +133,7 @@ class make_solver {
             return S(A, P, rhs, x);
         }
 
-        /** Computes the solution for the given right hand side \p rhs.
+        /** Computes the solution for the given 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.
@@ -153,8 +151,8 @@ class make_solver {
             return S(P, rhs, x);
         }
 
-        /** Acts as a preconditioner. That is, applies the solver to the right
-         * hand side \p rhs to get the solution \p x with zero initial
+        /** Acts as a preconditioner. That is, applies the solver to the
+         * right-hand side \p rhs to get the solution \p x with zero initial
          * approximation.  Iterative methods usually use estimated residual for
          * exit condition.  For some problems the value of the estimated
          * residual can get too far from the true residual due to round-off

docs/backends.rst

@@ -10,8 +10,74 @@ construction. The solution phase then uses types and operations defined in the
 backend. This enables transparent acceleration of the solution phase with
 OpenMP, OpenCL, CUDA, or any other technologies.
 
-In order to use a backend, users must include its definition from the
-corresponding file inside `amgcl/backend/`_ folder.
+In order to use a backend, user must include its definition from the
+corresponding file inside `amgcl/backend/`_ folder. On the user side of things,
+only the types of the right-hand side and the solution vectors should be
+affected by the choice of AMGCL backend. Here is an example of using the
+:cpp:struct:`builtin <amgcl::backend::builtin>` backend. First, we need to
+include the appropriate header:
+
+.. code-block:: cpp
+
+    #include <amgcl/backend/builtin.hpp>
+
+Then, we need to construct the solver and apply it to the vector types
+supported by the backend:
+
+.. code-block:: cpp
+
+    typedef amgcl::backend::builtin<double> Backend;
+
+    typedef amgcl::make_solver<
+        amgcl::amg<Backend, amgcl::coarsening::aggregation, amgcl::relaxation::spai0>,
+        amgcl::solver::gmres<Backend>
+        > Solver;
+
+    Solver solve(A);
+
+    std::vector<double> rhs, x; // Initialized elsewhere
+
+    solve(rhs, x);
+
+Now, if we want to switch to a different backend, for example, in order to
+accelerate the solution phase with a powerful GPU, we just need to include
+another backend header, and change the definitions of ``Backend``, ``rhs``,
+and ``x``. Here is an example of what needs to be done to use the
+:cpp:struct:`VexCL <amgcl::backend::vexcl>` backend.
+
+Include the correct header:
+
+.. code-block:: cpp
+
+    #include <amgcl/backend/builtin.hpp>
+
+Change the definition of ``Backend``:
+
+.. code-block:: cpp
+
+    typedef amgcl::backend::vexcl<double> Backend;
+
+Change the definition of the vectors:
+
+.. code-block:: cpp
+
+    vex::vector<double> rhs, x;
+
+That's it! Well, almost. In case the backend requires some parameters, we also
+need to provide those. In particular, the VexCL backend should know what
+VexCL context to use:
+
+.. code-block:: cpp
+
+    // Initialize VexCL context on a single GPU:
+    vex::Context ctx(vex::Filter::GPU && vex::Filter::Count(1));
+
+    // Create backend parameters:
+    Backend::params backend_prm;
+    backend_prm.q = ctx;
+
+    // Pass the parameters to the solver constructor:
+    Solver solve(A, Solver::params(), backend_prm);
 
 .. _`amgcl/backend/`: https://github.com/ddemidov/amgcl/blob/master/amgcl/backend/
 .. _`amgcl/backend/interface.hpp`: https://github.com/ddemidov/amgcl/blob/master/amgcl/backend/interface.hpp
@@ -20,9 +86,10 @@ Builtin
 -------
 
 .. doxygenstruct:: amgcl::backend::builtin
+    :members:
 
 VexCL
 -----
 
 .. doxygenstruct:: amgcl::backend::vexcl
-
+    :members:

docs/poisson.rst

@@ -1,8 +1,8 @@
 Assembling matrix for Poisson's equation
 ----------------------------------------
 
-The section provides an example of assembling the system matrix and the right
-hand side for a Poisson's equation in a unit square
+The section provides an example of assembling the system matrix and the
+right-hand side for a Poisson's equation in a unit square
 :math:`\Omega=[0,1]\times[0,1]`:
 
 .. math::
@@ -39,7 +39,7 @@ grid:
     // Assembles matrix for Poisson's equation with homogeneous boundary conditions on a n x n grid.
     // Returns number of rows in the assembled matrix.
     // The matrix is returned in the CRS components ptr, col, and val.
-    // The right hand side is returned in rhs.
+    // The right-hand side is returned in rhs.
     int poisson(
         int n,
         std::vector<int>    &ptr,

docs/tutorial.rst

@@ -65,7 +65,7 @@ components:
 
     Solver solve( boost::tie(n, ptr, col, val) );
 
-Once the solver is constructed, we can apply it to the right hand side to
+Once the solver is constructed, we can apply it to the right-hand side to
 obtain the solution. This may be repeated multiple times for different
 right-hand sides. Here we start with a zero initial approximation. The solver
 returns a boost tuple with number of iterations and norm of the achieved
@@ -101,7 +101,7 @@ into a `boost::iterator_range`_:
         boost::make_iterator_range(val.data(), val.data() + val.size())
         ) );
 
-Same applies to the right hand side and the solution vectors. And if that is
+Same applies to the right-hand side and the solution vectors. And if that is
 still not general enough, you can provide your own adapter for your matrix
 type. See :doc:`adapters` for further information on this.