List available backends in the documentation

amgcl/backend/blaze.hpp

@@ -44,7 +44,7 @@ namespace backend {
 /// Blaze backend
 /**
  * This is a backend that uses types defined in the Blaze library
- * (https://code.google.com/p/blaze-lib).
+ * (https://bitbucket.org/blaze-lib/blaze/src).
  *
  * \param real Value type.
  * \ingroup backends

docs/components.rst

@@ -1,37 +1,16 @@
 Components
 ==========
 
-AMGCL provides the following components:
+AMGCL defines the following algorithmic components:
 
-* **Backends** -- classes that define matrix and vector types and operations
-  necessary during the solution phase of the algorithm. When an AMG hierarchy
-  is constructed, it is moved to the specified backend. The approach enables
-  transparent acceleration of the solution phase with OpenMP_, OpenCL_, or
-  CUDA_ technologies, and also makes tight integration with user-defined data
-  structures possible.
-* **Value types** -- enable transparent solution of complex or non-scalar
-  systems. Most often, a value type is simply a ``double``, but it is possible
-  to use small statically-sized matrices as value type, which may increase
-  cache-locality, or convergence ratio, or both, when the system matrix has a
-  block structure. 
-* **Matrix adapters** -- allow AMGCL to construct a solver from some common
-  matrix formats. Internally, the CRS_ format is used, but it is easy to adapt
-  any matrix format that allows row-wise iteration over its non-zero elements.
-* **Coarsening strategies** -- various options for creating coarse systems in
-  the AMG hierarchy. A coarsening strategy takes the system matrix :math:`A` at
-  the current level, and returns prolongation operator :math:`P` and the
-  corresponding restriction operator :math:`R`.
-* **Relaxation methods** -- or smoothers, that are used on each level of the
-  AMG hierarchy during solution phase.
-* **Preconditioners** -- aside from the AMG, AMGCL implements preconditioners
-  for some common problem types. For example, there is a Schur complement
-  pressure correction preconditioner for Navie-Stokes type problems, or CPR
-  preconditioner for reservoir simulations. Also, it is possible to use single
-  level relaxation method as a preconditioner.
-* **Iterative solvers** -- Krylov subspace methods that may be combined with
-  the AMG (or other) preconditioners in order to solve the linear system.
+.. toctree::
+    :maxdepth: 2
 
-.. _OpenMP: https://www.openmp.org/
-.. _OpenCL: https://www.khronos.org/opencl/
-.. _CUDA: https://developer.nvidia.com/cuda-toolkit
-.. _CRS: http://netlib.org/linalg/html_templates/node91.html
+    components/backends
+    components/valuetypes
+    components/adapters
+    components/solvers
+    components/itersolvers
+    components/preconditioners
+    components/relaxation
+    components/coarsening

docs/components/adapters.rst

@@ -0,0 +1,8 @@
+Matrix Adapters
+===============
+
+A matrix adapter allows AMGCL to construct a solver from some common matrix
+formats. Internally, the CRS_ format is used, but it is easy to adapt any
+matrix format that allows row-wise iteration over its non-zero elements.
+
+.. _CRS: http://netlib.org/linalg/html_templates/node91.html

docs/components/backends.rst

@@ -0,0 +1,162 @@
+Backends
+========
+
+A backend in AMGCL is a class that binds datatypes like matrix and vector with
+parallel primitives like matrix-vector product, linear combination of vectors,
+or inner product computation. The backend system is implemented using free
+functions and partial template specializations, which allows to decouple the
+implementation of common parallel primitives from the specific datatypes used
+in the supported backends. This makes it possible to adopt third-party or
+user-defined datatypes for use within AMGCL without any modification of the
+core library code. 
+
+Algorithm setup in AMGCL is performed using internal data structures. As soon
+as the setup is completed, the necessary objects (mostly matrices and vectors)
+are transferred to the backend datatypes. Solution phase of the algorithms is
+expressed in terms of the predefined parallel primitives which makes it
+possible to switch parallelization technology (such as OpenMP_, CUDA_, or
+OpenCL_) simply by changing the backend template parameter of the algorithm.
+For example, the norm of the residual :math:`\epsilon = ||f - Ax||` in AMGCL is
+computed with ``amgcl::backend::residual()`` and
+``amgcl::backend::inner_product()`` primitives:
+
+.. code-block:: cpp
+
+    backend::residual(f, A, x, r);
+    auto e = sqrt(backend::inner_product(r, r));
+
+.. _OpenMP: https://www.openmp.org/
+.. _OpenCL: https://www.khronos.org/opencl/
+.. _CUDA: https://developer.nvidia.com/cuda-toolkit
+
+The backends currenly supported by AMGCL are listed below.
+
+OpenMP (builtin) backend
+------------------------
+
+
+.. cpp:struct:: template <class ValueType> \
+                amgcl::backend::builtin
+
+    Include ``<amgcl/backend/builtin.hpp>``.
+
+    This is the bultin backend that does not have any external dependencies and
+    uses OpenMP_-parallelization for its primitives. As with any backend in
+    AMGCL, it is defined with a :doc:`value type <valuetypes>` template
+    parameter, which specifies the type of the system matrix elements. The
+    backend is also used internally by AMGCL during construction phase, and so
+    moving the constructed datatypes (matrices and vectors) to the backend has
+    no overhead.  The backend has no parameters (the ``params`` subtype is an
+    empty struct).
+
+    .. cpp:struct:: params
+
+NVIDIA CUDA backend
+-------------------
+
+.. cpp:struct:: template <class ValueType> \
+                amgcl::backend::cuda
+
+   Include ``<amgcl/backend/cuda.hpp>``.
+
+   The backend uses the NVIDIA CUDA_ technology for the parallelization of its
+   primitives. It depends on the Thrust_ and cuSPARSE_ libraries. The code
+   using the backend has to be compiled with NVIDIA's nvcc_ compiler. The user
+   needs to initialize the cuSPARSE_ library with a call to the
+   `cusparseCreate()` function and pass the returned handle to AMGCL in the
+   backend parameters.
+
+   .. cpp:struct:: params
+
+      .. cpp:member:: cusparseHandle_t cusparse_handle         
+
+         cuSPARSE_ handle created with the `cusparseCreate()`_ function.
+
+.. _Thrust: https://docs.nvidia.com/cuda/thrust/index.html
+.. _cuSPARSE: https://docs.nvidia.com/cuda/cusparse/index.html
+.. _nvcc: https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html
+.. _cusparseCreate(): https://docs.nvidia.com/cuda/cusparse/index.html#cusparseCreate
+
+VexCL backend
+-------------
+
+.. cpp:struct:: template <class ValueType> \
+                amgcl::backend::vexcl
+
+   Include ``<amgcl/backend/vexcl.hpp>``.
+
+   The backend uses the VexCL_ library for the implementation of its
+   primitives. VexCL_ provides OpenMP, OpenCL, or CUDA parallelization,
+   selected at compile time with a preprocessor definition. The user has to
+   initialize the VexCL_ context and pass it to AMGCL via the backend
+   parameter.
+
+   .. cpp:struct:: params
+
+      .. cpp:member:: std::vector<vex::backend::command_queue> q
+
+         VexCL command queues identifying the compute devices in the compute
+         context.
+
+      .. cpp:member:: bool fast_matrix_setup = true
+
+         Transform the CSR matrices into the internal VexCL format on the
+         GPU. This is faster, but temporarily requires more memory on the GPU.
+
+.. _VexCL: https://github.com/ddemidov/vexcl
+
+ViennaCL backend
+----------------
+
+.. cpp:struct:: template <class Matrix> \
+                amgcl::backend::viennacl
+
+   Include ``<amgcl/backend/viennacl.hpp>``.
+
+   The backend uses the ViennaCL_ library for the implementation of its
+   primitives. ViennaCL_ is a free open-source linear algebra library for
+   computations on many-core architectures (GPUs, MIC) and multi-core CPUs. The
+   library is written in C++ and supports CUDA, OpenCL, and OpenMP (including
+   switches at runtime). The template parameter for the backend specifies
+   ViennaCL_ matrix class to use.  Possible choices are
+   ``viannacl::compressed_matrix<T>``, ``viennacl::ell_matrix<T>``, and
+   ``viennacl::hyb_matrix<T>``. The backend has no runtime parameters.
+
+   .. cpp:struct:: params
+
+.. _ViennaCL: http://viennacl.sourceforge.net/
+
+Eigen backend
+-------------
+
+.. cpp:struct:: template <class ValueType> \
+                amgcl::backend::eigen
+
+   Include ``<amgcl/backend/eigen.hpp>``.
+
+   The backend uses Eigen_ library datatypes for implementation of its
+   primitives. It could be useful in case the user already works with the
+   Eigen_ library, for example, to assemble the linear system to be solved with
+   AMGCL. AMGCL also provides an Eigen :doc:`matrix adapter <adapters>`, so
+   that Eigen matrices may be transparently used with AMGCL solvers.
+
+   .. cpp:struct:: params
+
+.. _Eigen: http://eigen.tuxfamily.org
+
+Blaze backend
+-------------
+
+.. cpp:struct:: template <class ValueType> \
+                amgcl::backend::blaze
+
+   Include ``<amgcl/backend/blaze.hpp>``.
+
+   The backend uses Blaze_ library datatypes for implementation of its
+   primitives. It could be useful in case the user already works with the
+   Blaze_ library, for example, to assemble the linear system to be solved with
+   AMGCL.
+
+   .. cpp:struct:: params
+
+.. _Blaze: https://bitbucket.org/blaze-lib/blaze

docs/components/coarsening.rst

@@ -0,0 +1,7 @@
+Coarsening Strategies
+=====================
+
+A coarsening strategy defines various options for creating coarse systems in
+the AMG hierarchy. A coarsening strategy takes the system matrix :math:`A` at
+the current level, and returns prolongation operator :math:`P` and the
+corresponding restriction operator :math:`R`.

docs/components/itersolvers.rst

@@ -0,0 +1,6 @@
+Iterative solvers
+=================
+
+An Iterative solver is a Krylov subspace method that may be combined with the
+AMG (or other) preconditioners in order to solve the linear system.
+

docs/components/preconditioners.rst

@@ -0,0 +1,9 @@
+Preconditioners
+===============
+
+Aside from the AMG, AMGCL implements preconditioners for some common problem
+types. For example, there is a Schur complement pressure correction
+preconditioner for Navie-Stokes type problems, or CPR preconditioner for
+reservoir simulations. Also, it is possible to use single level relaxation
+method as a preconditioner.
+

docs/components/relaxation.rst

@@ -0,0 +1,6 @@
+Relaxation
+==========
+
+A relaxation method or a smoother is used on each level of the AMG hierarchy
+during solution phase.
+

docs/components/solvers.rst

@@ -0,0 +1,2 @@
+Preconditioned Solvers
+======================

docs/components/valuetypes.rst

@@ -0,0 +1,9 @@
+Value Types
+===========
+
+A value type enables transparent solution of complex or non-scalar systems.
+Most often, a value type is simply a ``double``, but it is possible to use
+small statically-sized matrices as value type, which may increase
+cache-locality, or convergence ratio, or both, when the system matrix has a
+block structure. 
+