tutorial

amgcl/make_solver.hpp

@@ -109,12 +109,14 @@ class make_solver {
          * \param rhs Right-hand side.
          * \param x   Solution vector.
          *
+         * \rst
          * 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.
+         * [DeSh12]_.
+         * \endrst
          */
         template <class Matrix, class Vec1, class Vec2>
         boost::tuple<size_t, scalar_type> operator()(

docs/Doxyfile

@@ -228,7 +228,8 @@ TAB_SIZE               = 8
 # "Side Effects:". You can put \n's in the value part of an alias to insert
 # newlines.
 
-ALIASES                =
+ALIASES                = "rst=\verbatim embed:rst:leading-asterisks"
+ALIASES               += "endrst=\endverbatim"
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"

docs/_static/custom.css

@@ -4,4 +4,5 @@
 
 table.citation td {
     float: left;
+    max-width: 85%;
 }

docs/bibliography.rst

@@ -1,6 +1,7 @@
 Bibliography
 ============
 
+.. [DeSh12] Demidov, D. E., and Shevchenko, D. V. "Modification of algebraic multigrid for effective GPGPU-based solution of nonstationary hydrodynamics problems." Journal of Computational Science 3.6 (2012): 460-462.
 .. [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.

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': 'yeti'}
+html_theme_options = { 'bootswatch_theme': 'yeti' }
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []

docs/index.rst

@@ -27,6 +27,7 @@ Contents:
 
     tutorial
     components
+    runtime
     examples
     bibliography
     api

docs/runtime.rst

@@ -0,0 +1,2 @@
+Runtime interface
+=================

docs/tutorial.rst

@@ -78,9 +78,10 @@ residual:
     double error;
     boost::tie(iters, error) = solve(rhs, x);
 
-That's it! Vector `x` contains the solution of our problem now.
+That's it! Vector ``x`` contains the solution of our problem now.
 
-.. rubric:: Some notes
+Input formats
+-------------
 
 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
@@ -103,3 +104,40 @@ into a `boost::iterator_range`_:
 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.
+
+Setting parameters
+------------------
+
+Any component in AMGCL defines its own parameters by declaring a ``param``
+subtype. When a class wraps several subclasses, it includes parameters of its
+children into its own ``param``. For example, parameters for the
+:cpp:class:`amgcl::make_solver\<Precond, Solver>` are declared as
+
+.. code-block:: cpp
+
+    struct params {
+        typename Precond::params precond;
+        typename Solver::params solver;
+    };
+
+Knowing that, we can easily set the parameters for individual components. For
+example, we can set the desired tolerance for the iterative solver in the above
+example like this:
+
+.. code-block:: cpp
+
+    Solver::params prm;
+    prm.solver.tol = 1e-3;
+    Solver solve( boost::tie(n, ptr, col, val), prm );
+
+Parameters may also be initialized with a `boost::property_tree::ptree`_. This
+is especially convenient when :doc:`runtime` is used, and the exact structure
+of the parameters is not known at compile time:
+
+.. code-block:: cpp
+
+    boost::property_tree::ptree prm;
+    prm.put("solver.tol", 1e-3);
+    Solver solve( boost::tie(n, ptr, col, val), prm );
+
+.. _`boost::property_tree::ptree`: http://www.boost.org/doc/libs/release/doc/html/property_tree.html