From ed9d18b25dc21bd74d348414969531ec3487bd8a Mon Sep 17 00:00:00 2001
From: "Fernando P. Panadero" <fernando.p@csic.es>
Date: Thu, 30 Nov 2023 12:18:11 +0100
Subject: [PATCH] Solvers documentation

---
 docs/make.jl        |  1 +
 docs/src/solvers.md | 86 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 docs/src/solvers.md

diff --git a/docs/make.jl b/docs/make.jl
index d1856c2..f17a9fd 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -11,5 +11,6 @@ makedocs(sitename="LatticeGPU", modules=[LatticeGPU], doctest=true,
              "Groups and algebras" => "groups.md",
              "Fields" => "fields.md"
              "Dirac" => "dirac.md"
+             "Solvers" => "solvers.md"
              ], 
          repo = "https://igit.ific.uv.es/alramos/latticegpu.jl")
diff --git a/docs/src/solvers.md b/docs/src/solvers.md
new file mode 100644
index 0000000..b6fc606
--- /dev/null
+++ b/docs/src/solvers.md
@@ -0,0 +1,86 @@
+
+# Solvers
+
+The module `Solvers` contains the functions to invert the Dirac
+operator as well as functions to obtain specific propagators.
+
+
+## CG.jl
+
+The function [`CG!`](@ref) implements the Conjugate gradient 
+algorith for the operator A
+
+```@docs
+CG!
+```
+
+where the tolerance is normalized with respect to $$|$$``si``$$|^2$$.
+The operator A must have the same input structure as all the Dirac
+operators. If the maximum number of iterations `maxiter` is reached,
+the function will throw an error. The estimation for $$A^{-1}x$$ is
+stored in ``si``, and the number of iterations is returned.
+
+
+Note that all the fermion field in ``dws`` are used
+inside the function and will be modified. In particular, the final residue
+is given by $$|$$``dws.sr``$$|^2$$.
+
+
+
+## Propagators.jl
+
+In this file, we define a couple of useful functions to obtain certain
+propagators.
+
+```@docs
+propagator!
+```
+
+Internally, this function solves the equation 
+
+```math
+    D_w^\dagger D_w \psi = \gamma_5 D_w \gamma_5 \eta
+```
+
+where $$\eta$$ is either a point-source with the specified color and spin
+or a random source in a time-slice and stores the value in ``pro``. 
+To solve this equation, the [`CG!`](@ref) function is used.
+
+
+For the case of SF boundary conditions, we have the boundary-to-bulk 
+propagator, implemented by the function [`bndpropagator!`](@ref)
+
+```@docs
+bndpropagator!
+```
+
+This propagator is defined by the equation:
+
+```math
+D_W S(x) = \frac{c_t}{\sqrt{V}} \delta_{x_0,1} U_0^\dagger(0,\vec{x}) P_+
+```
+
+The analog for the other boundary is implemented in the function [`Tbndpropagator!`](@ref)
+
+```@docs
+Tbndpropagator!
+```
+
+defined by the equation:
+
+```math
+D_W R(x) = \frac{c_t}{\sqrt{V}} \delta_{x_0,T-1} U_0(T-1,\vec{x}) P_-
+```
+
+Where $$P_\pm = (1 \pm \gamma_0)/2$$. The boundary-to-boundary 
+propagator
+
+```math
+    - \frac{c_t}{\sqrt{V}} \sum_\vec{x} U_0 ^\dagger (T-1,\vec{x}) P_+ S(T-1,\vec{x})
+```
+
+is computed by the function [`bndtobnd`](@ref)
+
+```@docs
+bndtobnd
+```