Improved the documentation, especially the control

doc/gen_doxygen.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+function watch_dir {
+    while inotifywait -e modify $1; do
+        echo "$1 has changed, working..."
+        doxygen 
+        # ./gen_sphx.sh pdf
+        ./gen_sphx.sh
+    done
+}
+
+# watch_dir ../src &
+watch_dir ./source &
+watch_dir ../include
+

doc/gen_sphx.sh

@@ -5,14 +5,17 @@ export SB="/usr/bin/env sphinx-build"
 function do_job {
   $SB -b html -E -j2 source build/html
   $SB -b latex -E -j2 source build/latex
-  # cd build/latex
-  # make
-  # cd -
+  if [ "$1" == "pdf" ]
+      then
+        cd build/latex
+        make
+        cd -
+  fi
 }
 
-do_job
+do_job $1
 
-while inotifywait -e modify ./source; do
-    echo "has changed, working..."
-    do_job
-done
+# while inotifywait -e modify ./source; do
+    # echo "has changed, working..."
+    # do_job $1
+# done

doc/old_doxygen/gen_doxygen.sh

@@ -6,14 +6,14 @@ function watch_dir {
     while inotifywait -e modify ./; do
         echo "$1 has changed, working..."
         doxygen &>> /tmp/log_doxygen_abcd
-        cp latex_stuffs/* ../doc_output/doxy/latex
-        cd ../doc_output/doxy/latex
-        make
-        cd $dir        
+        #cp latex_stuffs/* ../doc_output/doxy/latex
+        #cd ../doc_output/doxy/latex
+        #make
+        #cd $dir        
     done
 }
 
-# watch_dir ../src &
-# watch_dir ../include &
-watch_dir ../doc
+watch_dir ../src &
+watch_dir ../include &
+# watch_dir ../doc
 

doc/source/algorithm.rst

@@ -3,8 +3,10 @@ The Algorithm
 =============
 
 The package `ABCD Solver` is a distributed hybrid (iterative/direct)
-solver for sparse linear systems :math:`Ax = b` where :math:`A` is a double
-precision matrix with. `ABCD Solver` uses two methods to solve the linear system:
+solver for sparse linear systems :math:`Ax = b` where :math:`A` is a
+double precision matrix :math:`m \times n`, :math:`x` an
+:math:`n`-vector and :math:`b` an :math:`m`-vector.
+`ABCD Solver` uses two methods to solve the linear system:
 
 - *Regular Block Cimmino*: A block-projection technique that iterates
    to solve the linear system. During the iterations it solves a set

doc/source/api.rst

@@ -0,0 +1,10 @@
+**********************************************
+API (work in progress)
+**********************************************
+
+.. doxygenclass:: abcd
+    :project: abcd
+    :members: 
+
+.. doxygenfile:: defaults.h
+   :project: abcd

doc/source/conf.py

@@ -36,14 +36,14 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'breathe',
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
     'sphinxcontrib.tikz',
-    'breathe',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -67,9 +67,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.1a1'
+version = '0.1'
 # The full version, including alpha/beta/rc tags.
-release = '0.1a1'
+release = '0.1 beta'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -114,7 +114,9 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'nature'
+# html_theme = 'sphinxdoc'
+html_theme = 'haiku'
+# html_theme = 'agogo'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -209,6 +211,8 @@
 \\usepackage{tikz}
 \\usepackage{pgfplots}
 \\usetikzlibrary{shapes,arrows,calc}
+\\renewcommand{\\labelitemi}{$\\bullet$~}
+\\renewcommand{\\labelitemii}{$\\triangleright$~}
 ''',
 }
 
@@ -279,3 +283,7 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
+
+
+# to have the Todo list
+todo_include_todos = True

doc/source/index.rst

@@ -13,15 +13,5 @@ The Augmented Block Cimmino Distributed Solver
    algorithm
    installation
    usage_cpp
-
-.. doxygenclass:: abcd
-   :project: abcd
-   :members:
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+   api
+   todo

doc/source/todo.rst

@@ -0,0 +1,16 @@
+**********************************************
+TODO
+**********************************************
+
+Implementation TODO List
+========================
+
+* Make it possible to call ``job_id = 2`` after a call to ``job_id = 3``. This should give more power to ther user on the direct solver.
+  Possible use cases:
+  - Change the number of workers the direct solver has on a precise node
+  - Change some ``MUMPS`` control parameters related to the Analysis and Factorization phases.
+
+
+Documentation TODO List
+=======================
+.. todolist::

doc/source/usage_cpp.rst

@@ -168,98 +168,22 @@ Moreover, due to the similarities between the ``C++`` code and the
 ``C`` one, we provide only the ``C++`` snippets unless there is a
 major difference.
 
+In the following, the syntax ``ctl = = val`` means that the enum variable ``ctl`` can be replaced by ``val``, its numerical value.
+
 The integer control array
 #########################
 
-* ``icntl[nbparts]`` or ``icntl[1]`` defines the number of partitions in our linear system, can be from ``1`` to ``m`` (the number of rows in the matrix)
-
-    .. code-block:: cpp
-
-        // we have 8 partitions
-        obj.icntl[nbparts] = 8;
-
-* ``icntl[part_type]`` or ``icntl[2]`` defines the partitioning type. It can have the values:
-
-    - ``1``, manual partitioning, the *nbparts* partitions can be provided into the STL vector ``obj.nbrows[]``. Example:
-
-        .. code-block:: cpp
-
-
-            // use manual partitioning
-            obj.icntl[part_type] = 1;
-            // say that we want 20 rows per partition
-            obj.nrows.assign(obj.icntl[nbparts], 20);
-
-            // or 
-            obj.nrows.resize(obj.icntl[nbparts]);
-            obj.nrows[0] = 20;
-            obj.nrows[1] = 20;
-            //...
-
-        For ``C``:
-
-        .. code-block:: cpp
-
-
-            // use manual partitioning
-            obj->icntl[part_type] = 1;
-
-            obj->nrows =  (int*) malloc(sizeof(int)*(obj->icntl[nbparts]));
-
-            obj->nrows[0] = 20;
-            obj->nrows[1] = 20;
-            //...
+.. doxygenenum:: icontrols
+    :project: abcd
 
-    - ``2`` (*default*), automatic uniform partitioning, creates *nbparts* partitions of similar size.
-
-        .. code-block:: cpp
-
-            // use patoh partitioning
-            obj.icntl[part_type] = 2;
-
-    - ``3``, automatic hypergraph partitioning, creates *nbparts* partitions using the hypergraph partitioner ``PaToH``. The imbalance between the partitions is handled using ``obj.dcntl[part_imbalance]``. Example:
-
-      .. code-block:: cpp
-
-            // use patoh partitioning
-            obj.icntl[part_type] = 3;
-            // say that we want an imbalance of 0.3 between the partitions
-            obj.dcntl[part_imbalance] = 0.3;
-
-* ``icntl[part_guess]`` or ``icntl[4]`` asks the solver to guess the appropriate number of partitions and overrides the defined *nbparts*. 
-
-    - ``0`` **default**, no guess
-    - ``1``, guess
-
-* ``icntl[scaling]`` or ``icntl[5]`` defines the type of scaling to be used.
-
-    - ``0``, no scaling
-    - ``1``, infinity norm ``MC77`` based scaling
-    - ``2`` **default**, combination of one norm and two norm ``MC77`` based scaling
-* ``icntl[itmax]`` or ``icntl[6]`` defines the maximum number of iterations in block-CG acceleration, default is ``1000``
-* ``icntl[block_size]`` or ``icntl[7]`` defines the block-size to be used by the block-CG acceleration, default is ``1`` for classical CG acceleration
-* ``icntl[verbose_level]`` or ``icntl[8]`` defines how verbose the solver has to be. 
-* ``icntl[aug_type]`` or ``icntl[10]`` defines the augmentation type.
-
-    - ``0`` **default**, no augmentation. This makes the solver run in
-    **regular block Cimmino** mode.
-
-    - ``1``, makes the solver run in **Augmented Block Cimmino** mode
-    with an augmentation of the matrix using the :math:`C_{ij}/-I`
-    technique. For numerical stability, this augmentation technique
-    has to be used with a scaling.
-
-    - ``2``, makes the solver run in **Augmented Block Cimmino** mode
-    with an augmentation of the matrix using the :math:`A_{ij}/-A_{ji}`
-    technique. This is the prefered augmentation technique.
-
-* ``icntl[aug_blocking]`` or ``icntl[11]`` defines the blocking factor
-  when building the auxiliary matrix :math:`S`, default is ``128``.
-* ``icntl[aug_analysis]`` or ``icntl[12]``, when set to a value different than ``0``, analyses the number of columns in the augmentation.
-* ``icntl[13]`` to ``icntl[16]`` are for development and testing purposes only.
+.. todo:: Talk about Work-In-Progress control parameters              
 
 The double precision control array
 ##################################
+
+.. doxygenenum:: dcontrols
+    :project: abcd
+
 * ``dcntl[part_imbalance]`` or ``obj.dcntl[1]`` defines the imbalance between the partitions when using ``PaToH`` (``icntl[part_imbalance] = 3``).
 * ``obj.dcntl[threshold]`` or ``dcntl[2]`` defines the stopping threshold for the block-CG acceleration, default is ``1e-12``.