From bbd20ce87a8e5f9bd21d5e3c72a00588d13544fc Mon Sep 17 00:00:00 2001
From: Francois Coppens <francois.coppens@uvsq.fr>
Date: Wed, 1 Sep 2021 16:06:51 +0200
Subject: [PATCH] More documentation added.

---
 org/qmckl_sherman_morrison_woodbury.org | 57 ++++++++++++++++---------
 1 file changed, 38 insertions(+), 19 deletions(-)

diff --git a/org/qmckl_sherman_morrison_woodbury.org b/org/qmckl_sherman_morrison_woodbury.org
index c9526f0..8b3c56c 100644
--- a/org/qmckl_sherman_morrison_woodbury.org
+++ b/org/qmckl_sherman_morrison_woodbury.org
@@ -216,9 +216,9 @@ This function performce better for cycles with 1 rank-1 update and with a high f
    It will exit with an error code of the denominator is too close to zero.
 
    The formula that is applied is
-   \begin{equation}
+   \[
     (S + uv^T)^{-1} = S^{-1} - \frac{S^{-1} uv^T S^{-1}}{1 + v^T S^{-1} u}
-   \end{equation}
+   \]
 
    where
    $S$ is the Slater-matrix,
@@ -415,11 +415,9 @@ rc = qmckl_sherman_morrison_c(context, Dim, N_updates, Updates, Updates_index, b
 assert(rc == QMCKL_SUCCESS);
      #+end_src
 
-
+     
 * Woodbury 2x2
 
-This is the Woodbury 3x3 kernel.
-  
 ** ~qmckl_woodbury_2~
    :PROPERTIES:
    :Name:     qmckl_woodbury_2
@@ -427,11 +425,19 @@ This is the Woodbury 3x3 kernel.
    :FRetType: qmckl_exit_code
    :END:
 
-   This is the simplest of the available Sherman-Morrison-Woodbury
-   kernels in QMCkl. It applies rank-1 updates one by one in the order
-   that is given. It only checks if the denominator in the
-   Sherman-Morrison formula is not too close to zero (and exit with an
-   error if it does) during the application of an update.
+   The simplest version of the generalised Sherman-Morrison-Woodbury kernels. It is used to apply two
+   rank-1 updates at once. The formula used in this algorithm is called the Woodbury Matrix Identity
+   \[
+     (S + U V)^{-1}  =  S^{-1} - C B^{-1} D
+   \]
+   where
+   $S$ is the Slater-matrix
+   $U$ and $V$ are the matrices containing the updates and the canonical basis matrix
+   $S^{-1}$ is the inverse of the Slater-matrix
+   $C:= S^{-1}U$, a Dim $\times 2$ matrix
+   $B := 1 + VC$, the $2 \times 2$ matrix that is going to be inverted
+   $D := VS^{-1}$, a $2 \times Dim$ matrix
+   
 
    #+NAME: qmckl_woodbury_2_args
    | qmckl_context | context             | in    | Global state                                    |
@@ -443,7 +449,12 @@ This is the Woodbury 3x3 kernel.
 
 *** Requirements
 
-      Add description of the input variables. (see for e.g. qmckl_distance.org)
+    - ~context~ is not ~qmckl_null_context~
+    - ~dim >= 2~
+    - ~updates~ is allocated with at least $2 \times 2 \times 8$ bytes
+    - ~updates_index~ is allocated with $2 \times 8$ bytes
+    - ~breakdown~ is a small number such that $0 < breakdown << 1$
+    - ~slater_inv~ is allocated with at least $dim \times dim \times 8$ bytes
 
 *** C header
 
@@ -559,6 +570,8 @@ qmckl_exit_code qmckl_woodbury_2_c(const qmckl_context context,
     
 *** Performance
 
+    This function is most efficient when used in cases where there are only 2 rank-1 updates
+    
 ** C interface                                                     :noexport:
 
    #+CALL: generate_c_interface(table=qmckl_woodbury_2_args,rettyp=get_value("FRetType"),fname=get_value("Name"))
@@ -629,8 +642,6 @@ assert(rc == QMCKL_SUCCESS);
 
 
 * Woodbury 3x3
-
-This is the Woodbury 3x3 kernel.
   
 ** ~qmckl_woodbury_3~
    :PROPERTIES:
@@ -639,11 +650,12 @@ This is the Woodbury 3x3 kernel.
    :FRetType: qmckl_exit_code
    :END:
 
-   This is the simplest of the available Sherman-Morrison-Woodbury
-   kernels in QMCkl. It applies rank-1 updates one by one in the order
-   that is given. It only checks if the denominator in the
-   Sherman-Morrison formula is not too close to zero (and exit with an
-   error if it does) during the application of an update.
+   The 3x3 version of the Woodbury 2x2 kernel. It is used to apply three
+   rank-1 updates at once. The formula used in this kernel is the same as for Woodbury 2x2, with the exception of
+
+   $C:= S^{-1}U$, a Dim $\times 3$ matrix
+   $B := 1 + VC$, the $3 \times 3$ matrix that is going to be inverted
+   $D := VS^{-1}$, a $3 \times Dim$ matrix
 
    #+NAME: qmckl_woodbury_3_args
    | qmckl_context | context             | in    | Global state                                    |
@@ -655,7 +667,6 @@ This is the Woodbury 3x3 kernel.
 
 *** Requirements
 
-      Add description of the input variables. (see for e.g. qmckl_distance.org)
 
 *** C header
 
@@ -784,6 +795,14 @@ qmckl_exit_code qmckl_woodbury_3_c(const qmckl_context context,
 
 *** Performance...
 
+    - ~context~ is not ~qmckl_null_context~
+    - ~dim >= 2~
+    - ~updates~ is allocated with at least $3 \times 2 \times 8$ bytes
+    - ~updates_index~ is allocated with $3 \times 8$ bytes
+    - ~breakdown~ is a small number such that $0 < breakdown << 1$
+    - ~slater_inv~ is allocated with at least $dim \times dim \times 8$ bytes
+
+
 ** C interface                                                     :noexport:
 
    #+CALL: generate_c_interface(table=qmckl_woodbury_3_args,rettyp=get_value("FRetType"),fname=get_value("Name"))