From 196e3f9663c061be8437ee4fbfc5843c61109964 Mon Sep 17 00:00:00 2001
From: Laura Messio <laura.messio@cea.fr>
Date: Thu, 1 Aug 2013 14:13:21 +0200
Subject: [PATCH] doc: det_manip, link towards the cookbook added, explanations
 added

---
 doc/reference/c++/contents.rst                |  1 -
 doc/reference/c++/det_manip/behind.rst        | 55 +++++++++++++++++++
 doc/reference/c++/det_manip/contents.rst      | 12 ++--
 .../{cookbook.rst => cookbook/basic.rst}      |  4 +-
 .../c++/det_manip/cookbook/contents.rst       |  9 +++
 5 files changed, 71 insertions(+), 10 deletions(-)
 create mode 100644 doc/reference/c++/det_manip/behind.rst
 rename doc/reference/c++/det_manip/{cookbook.rst => cookbook/basic.rst} (97%)
 create mode 100644 doc/reference/c++/det_manip/cookbook/contents.rst

diff --git a/doc/reference/c++/contents.rst b/doc/reference/c++/contents.rst
index 39daf1da..0e7632ae 100644
--- a/doc/reference/c++/contents.rst
+++ b/doc/reference/c++/contents.rst
@@ -18,4 +18,3 @@ C++
    det_manip/contents
    parameters/parameters
    utilities/contents
-
diff --git a/doc/reference/c++/det_manip/behind.rst b/doc/reference/c++/det_manip/behind.rst
new file mode 100644
index 00000000..7ff79a8d
--- /dev/null
+++ b/doc/reference/c++/det_manip/behind.rst
@@ -0,0 +1,55 @@
+.. highlight:: c
+
+How does it work ?
+###################
+
+Cofactors
+==========
+
+For any :math:`n\times n` matrix :math:`A`:
+
+.. math:: A\,{\rm Cof}(A^T) = {\rm Det}A\, I_n.
+
+where :math:`\rm{Cof}` means the matrix of the cofactors. 
+
+.. math::    {\rm Cof}(A)_{i,j}
+             =(-1)^{i+j}{\rm Det}\begin{pmatrix}
+             a_{1,1}   & \dots & a_{1,j-1}   & a_{1,j+1}  & \dots & a_{1,n}   \\
+             \vdots    &       & \vdots      & \vdots     &       & \vdots    \\
+             a_{i-1,1} & \dots & a_{i-1,j-1} & a_{i-1,j+1}& \dots & a_{i-1,n} \\
+             a_{i+1,1} & \dots & a_{i+1,j-1} & a_{i+1,j+1}& \dots & a_{i+1,n} \\
+             \vdots    &       & \vdots      & \vdots     &       & \vdots    \\
+             a_{n,1}   & \dots & a_{n,j-1}   & a_{n,j+1}  & \dots & a_{n,n}   \end{pmatrix}.
+
+    
+Change in the determinant when one adds a line and a column
+============================================================
+
+:math:`A` is an inversible :math:`n\times n` matrix. :math:`A'` is a :math:`(n+1)\times (n+1)` matrix obtained by adding a line and a column to :math:`A`:
+
+.. math:: A'=\begin{pmatrix} 
+          A & B \\ 
+          C & D \end{pmatrix}.
+
+Using the previous formula with the cofactors, we get
+
+.. math::  \frac{{\rm Det}A'}{{\rm Det}A}=C A^{-1} B+D. 
+
+
+Change in the inverse when one adds a line and a column
+==========================================================
+
+Using the following variables:
+
+.. math:: \xi=D-C  A^{-1} B, \qquad B'=A^{-1}B, \qquad C'=CA^{-1}, 
+
+We get the inverse of the new matrix as:
+
+.. math:: (A')^{-1}=
+          \begin{pmatrix}
+            A^{-1}+\xi B'C' & -\xi B'\\
+            -\xi C'         &  \xi
+          \end{pmatrix}
+
+
+
diff --git a/doc/reference/c++/det_manip/contents.rst b/doc/reference/c++/det_manip/contents.rst
index 82da1ccb..1c2637ff 100644
--- a/doc/reference/c++/det_manip/contents.rst
+++ b/doc/reference/c++/det_manip/contents.rst
@@ -1,4 +1,4 @@
-.. highlight:: c
+.. _det_manip:
 
 Manipulations of determinants
 =============================
@@ -7,11 +7,10 @@ Manipulations of determinants
 
    This library is stable, but documentation is still a bit spartan ...
 
-The purpose of this little class is to regroup standard block manipulations on determinant, used in several 
-QMC.
+The purpose of this little class is to regroup standard block manipulations on determinant, used in several algorithms.
 
 Given a function :math:`F(x,y)`, and two sets of values :math:`x_i,y_i \ 0\leq i < N`,
-we can define the square :math:`N\times N` matrix 
+we can define the :math:`N\times N` square matrix 
 
 .. math:: 
    
@@ -21,7 +20,7 @@ When adding/removing a line and column (i.e. a value of x, y),
 :math:`M^{-1}` and :math:`det M` can be fast updated using standard block matrix computations.
 This class implements these general operations. It contains : 
 
-* Data : 
+* Datas : 
 
   * :math:`M^{-1}` and :math:`det M`
   * a vector containing  :math:`x_i,y_i \ 0\leq i \leq N`
@@ -38,4 +37,5 @@ This class implements these general operations. It contains :
    :maxdepth: 2
 
    det_manip
-   cookbook
+   behind
+   cookbook/contents
diff --git a/doc/reference/c++/det_manip/cookbook.rst b/doc/reference/c++/det_manip/cookbook/basic.rst
similarity index 97%
rename from doc/reference/c++/det_manip/cookbook.rst
rename to doc/reference/c++/det_manip/cookbook/basic.rst
index f89b9536..87e3d7c6 100644
--- a/doc/reference/c++/det_manip/cookbook.rst
+++ b/doc/reference/c++/det_manip/cookbook/basic.rst
@@ -1,6 +1,3 @@
-Cookbook
-========
-
 Basics
 ------
 
@@ -66,5 +63,6 @@ Here, an exemple of creation of a class det_manip, of use of insert and remove.
 
 
 
+Learn more in the full reference, see :ref:`det_manip`
 
 
diff --git a/doc/reference/c++/det_manip/cookbook/contents.rst b/doc/reference/c++/det_manip/cookbook/contents.rst
new file mode 100644
index 00000000..4e7d8482
--- /dev/null
+++ b/doc/reference/c++/det_manip/cookbook/contents.rst
@@ -0,0 +1,9 @@
+.. highlight:: c
+
+Det_manip cookbook
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   basic