Tutorial

README.md

@@ -4,7 +4,7 @@
 [![Build status](https://ci.appveyor.com/api/projects/status/r0s4lbln4qf9r8aq/branch/master?svg=true)](https://ci.appveyor.com/project/ddemidov/amgcl/branch/master)
 [![codecov.io](https://codecov.io/github/ddemidov/amgcl/coverage.svg?branch=master)](https://codecov.io/github/ddemidov/amgcl?branch=master)
 [![Coverity Scan Build Status](https://scan.coverity.com/projects/5301/badge.svg)](https://scan.coverity.com/projects/5301)
-[![Documentation Status](https://readthedocs.org/projects/amgcl/badge/?version=improve-docs)](http://amgcl.readthedocs.org/en/improve-docs/?badge=improve-docs)
+[![Documentation Status](https://readthedocs.org/projects/amgcl/badge/?version=latest)](http://amgcl.readthedocs.org/en/latest/?badge=latest)
 
 AMGCL is a header-only C++ library for solving large sparse linear systems with
 algebraic multigrid (AMG) method. AMG is one of the most effective methods for

docs/api.rst

@@ -0,0 +1,4 @@
+API Reference
+=============
+
+.. doxygenclass:: amgcl::make_solver

docs/bibliography.rst

@@ -1,7 +1,7 @@
 Bibliography
 ============
 
+.. [Saad03] Saad, Yousef. Iterative methods for sparse linear systems. Siam, 2003.
 .. [Stue99] Stüben, Klaus. Algebraic multigrid (AMG): an introduction with applications. GMD-Forschungszentrum Informationstechnik, 1999.
 .. [TrOS01] Trottenberg, U., Oosterlee, C., and Schüller, A. Multigrid. Academic Press, London, 2001.
-.. [Saad03] Saad, Yousef. Iterative methods for sparse linear systems. Siam, 2003.
 

docs/conf.py

@@ -131,7 +131,7 @@
 # a list of builtin themes.
 html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 html_theme = 'bootstrap'
-html_theme_options = {'bootswatch_theme': 'cosmo'}
+html_theme_options = {'bootswatch_theme': 'yeti'}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []

docs/examples.rst

@@ -0,0 +1,6 @@
+Examples
+========
+
+.. toctree::
+
+    poisson

docs/index.rst

@@ -3,13 +3,12 @@ AMGCL documentation
 
 AMGCL is a header-only C++ library for solving large sparse linear systems with
 algebraic multigrid (AMG) method. AMG is one of the most effective methods for
-solution of large sparse unstructured systems of equations, arising, for
-example, from discretization of PDEs on unstructured grids [Stue99]_,
-[TrOS01]_. The method can be used as a black-box solver for various
-computational problems, since it does not require any information about the
-underlying geometry. AMG is often used not as a standalone solver but as a
-preconditioner within an iterative solver (e.g. Conjugate Gradients, BiCGStab,
-or GMRES).
+solution of systems of equations, arising, for example, from discretizing PDEs
+on unstructured grids [Stue99]_, [TrOS01]_. The method can be used as a
+black-box solver for various computational problems, since it does not require
+any information about the underlying geometry. AMG is often used not as a
+standalone solver but as a preconditioner within an iterative solver (e.g.
+Conjugate Gradients, BiCGStab, or GMRES).
 
 AMGCL builds the AMG hierarchy on a CPU and then transfers it to one of the
 provided backends. This allows for transparent acceleration of the solution
@@ -28,6 +27,7 @@ Contents:
 
     tutorial
     components
-    poisson
+    examples
     bibliography
+    api
     indices

docs/poisson.rst

@@ -1,11 +1,8 @@
-Appendix
-========
-
-Poisson equation
-----------------
+Assembling matrix for Poisson's equation
+----------------------------------------
 
 The section provides an example of assembling the system matrix and the right
-hand side for a Poisson equation in a unit square
+hand side for a Poisson's equation in a unit square
 :math:`\Omega=[0,1]\times[0,1]`:
 
 .. math::
@@ -39,7 +36,7 @@ grid:
 
     #include <vector>
 
-    // Assembles Poisson problem with homogeneous boundary conditions on a n x n 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.
@@ -51,7 +48,7 @@ grid:
         std::vector<double> &rhs
         )
     {
-        int    n2 = n * n;        // Number of points in our grid.
+        int    n2 = n * n;        // Number of points in the grid.
         double h = 1.0 / (n - 1); // Grid spacing.
 
         ptr.clear(); ptr.reserve(n2 + 1); ptr.push_back(0);

docs/tutorial.rst

@@ -5,64 +5,101 @@ The easiest way to solve a problem with AMGCL is to use the
 :cpp:class:`amgcl::make_solver` class. It has two
 template parameters: the first one specifies a :doc:`preconditioner
 <preconditioners>` to use, and the second chooses an :doc:`iterative solver
-<solvers>`. The class :cpp:func:`constructor <amgcl::make_solver::make_solver>`
-takes the system matrix in one of supported :doc:`formats <adapters>` and
-parameters for the chosen algorithms and for the :doc:`backend <backends>`.
+<solvers>`. The class constructor takes the system matrix in one of supported
+:doc:`formats <adapters>` and parameters for the chosen algorithms and for the
+:doc:`backend <backends>`.
 
-Solving Poisson problem
------------------------
+Solving Poisson's equation
+------------------------
 
-Lets consider a simple example of :doc:`Poisson equation <poisson>` in a unit
-square.  Here is how the problem may be solved with AMGCL. We will use BiCGStab
-solver preconditioned with smoothed aggregation multigrid with SPAI(0) for
-relaxation (smoothing). First, we include the necessary headers:
+Let us consider a simple example of `Poisson's equation`_ in a unit square.
+Here is how the problem may be solved with AMGCL. We will use BiCGStab solver
+preconditioned with smoothed aggregation multigrid with SPAI(0) for relaxation
+(smoothing). First, we include the necessary headers. Each of those brings in
+the corresponding component of the method:
+
+.. _Poisson's equation: https://en.wikipedia.org/wiki/Poisson%27s_equation
 
 .. code-block:: cpp
 
     #include <amgcl/make_solver.hpp>
+    #include <amgcl/solver/bicgstab.hpp>
     #include <amgcl/amg.hpp>
     #include <amgcl/coarsening/smoothed_aggregation.hpp>
     #include <amgcl/relaxation/spai0.hpp>
-    #include <amgcl/solver/bicgstab.hpp>
     #include <amgcl/adapter/crs_tuple.hpp>
 
-Next, we construct the solver and apply it to the right hand side to get the
-solution:
+Next, we assemble sparse matrix for the Poisson's equation on a uniform
+1000x1000 grid. See :doc:`poisson` for the source code of the
+:cpp:func:`poisson` function:
 
 .. code-block:: cpp
 
     std::vector<int>    ptr, col;
     std::vector<double> val, rhs;
-
-    // Assemble the matrix for 100x1000 grid:
     int n = poisson(1000, ptr, col, val, rhs);
 
-    // Use builtin backend (parallelized with OpenMP):
+For this example, we select the :cpp:class:`builtin <amgcl::backend::builtin>`
+backend with double precision numbers as value type:
+
+.. code-block:: cpp
+
     typedef amgcl::backend::builtin<double> Backend;
 
-    // Construct the solver.
-    // We use convenient crs_tuple as matrix adapter:
+Now we can construct the solver for our system matrix. We use the convenient
+adapter for boost tuples here and just tie together the matrix size and its CRS
+components:
+
+.. code-block:: cpp
+
     typedef amgcl::make_solver<
         // Use AMG as preconditioner:
         amgcl::amg<
             Backend,
             amgcl::coarsening::smoothed_aggregation,
             amgcl::relaxation::spai0
             >,
-        // And BiCGStab as solver:
+        // And BiCGStab as iterative solver:
         amgcl::solver::bicgstab<Backend>
         > Solver;
 
     Solver solve( boost::tie(n, ptr, col, val) );
 
-    // Solve the system for the given right hand side with zero as initial approximation:
+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
+residual:
+
+.. code-block:: cpp
+
     std::vector<double> x(n, 0.0);
-    solve(rhs, x);
+    int    iters;
+    double error;
+    boost::tie(iters, error) = solve(rhs, x);
 
+That's it! Vector `x` contains the solution of our problem now.
 
+.. rubric:: Some notes
+
+We used STL vectors to store the matrix components in the above axample. This
+may seem too restrictive if you want to use AMGCL with your own types.  But the
+`crs_tuple` adapter will take anything that the Boost.Range_ library recognizes
+as a random access range. For example, you can wrap raw pointers to your data
+into a `boost::iterator_range`_:
+
+.. _Boost.Range: http://www.boost.org/doc/libs/release/libs/range/
+.. _`boost::iterator_range`: http://www.boost.org/doc/libs/release/libs/range/doc/html/range/reference/utilities/iterator_range.html
+
+.. code-block:: cpp
 
-The `make_solver` class
------------------------
+    Solver solve( boost::tie(
+        n,
+        boost::make_iterator_range(ptr.data(), ptr.data() + ptr.size()),
+        boost::make_iterator_range(col.data(), col.data() + col.size()),
+        boost::make_iterator_range(val.data(), val.data() + val.size())
+        ) );
 
-.. doxygenclass:: amgcl::make_solver
-    :members: make_solver, operator(), precond, solver, system_matrix
+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.