update the documentation of the proximal_gradient module to the Docstring NumpyDoc format

src/source_localization/proximal_gradient.py

@@ -2,43 +2,66 @@ import numpy as np
 
 
 def proximal_gradient(x0, fun1, proximal_fun2, args=(), options=None, callback=None):
+    r"""
+    Minimize a function of the shape :math:`f(x)+g(x)` using the proximal gradient method,
+    with :math:`f` a differentiable function and :math:`g` a function whose proximal operator is known,
+    e.g. a LASSO or group-LASSO regularization term).
+
+    The proximal gradient method, also refered to as ISTA, combines the gradient-descent step for the differentiable part
+    with the proximal step for the non-differentiable part as following:
+
+        - Initialization: Starting from an initial point :math:`x_0`.
+        - For each iteration :math:`k`:
+
+            1. compute the gradient of the function :math:`\nabla f(x_k)` at the current point :math:`x_k`,
+            2. Update the estimate of :math:`x` using the rule :math:`x_{k+1} = \text{prox}^g_\alpha(x_k - \alpha \nabla f(x_k))`
+               where :math:`\text{prox}^g_\lambda` is the proximal operator of :math:`g`
+               and :math:`\alpha` is the step size of the gradient descent step.
+        - Convergence Check: the algorithm stops
+          when the maximum number of iterations is reached.
+
+    An accelerated version, called FISTA, incorporates an inertial term,
+    that takes into account not only :math:`x_k` but also :math:`x_{k-1}`, to speed up convergence.
+
+    Parameters
+    ----------
+    x0 : ~numpy.ndarray
+        Initial point :math:`x_0` from which the iterative optimization algorithm starts.
+    fun1 : callable
+        Method that, given :math:`x`, returns the evaluation of the function :math:`f(x)` and its gradient :math:`\nabla f(x)`.
+    proximal_fun2 : callable
+        Method that, given :math:`x` and a parameter :math:`\lambda`,
+        returns the evaluation of the function :math:`\text{prox}^g_\lambda(x)`.
+    args : tuple, optional
+        Arguments that should be given to the callable :meth:`fun1` besides the array containing the current value of :math:`x`.
+    options : dict, optional, default: `None`
+        Dictionary containing several options to customize the proximal gradient method and its stopping criteria.
+        These options include:
+
+        - 'algorithm': str, default: `'ISTA`', the type of algorithm used (`'ISTA'` or `'FISTA'`).
+        - 'step_size': float, default: `1`,  the step size of the gradient descent.
+        - 'nit_max': int, default: `50`, the maximal number of iterations.
+
+    callback : callable, optional
+        Method called at each optimization iteration.
+        The method should take as sole input the array containing the current value of :math:`x`.
+
+    Returns
+    -------
+    x: ~numpy.ndarray
+        Optimal value :math:`x^*`.
+    f: float
+        Evaluation of the function :math:`f` at the optimal value :math:`f(x^*)`.
+    df: ~numpy.ndarray
+        Evaluation of the gradient of the function :math:`f` at the optimal value :math:`\nabla f(x^*)`.
+    nit: int
+        The number of iterations needed to converge.
+
     """
-    Uses accelerated proximal gradient (FISTA) to solve :
-    argmin f(x) + g(x)
-    with f a differentiable function and g a fonction whose proximal operator is known
-    in the present context :
-    f is the L2 norm terms of the cost function (cost of the observations and Tikhonov regularization terms)
-    g is the LASSO or group-LASSO regularization term
-
-    - TO DO:
-        * improve stopping criteria, add ftol and gtol,
-        * add exceptions to check inputs type
-    - input:
-        * x0:
-            | array,
-            | the initial point from which the iterative optimization algorithm will starts
-        * fun1:
-            | callable,
-            | method that given an x return the evaluation of the differentiable function f and its gradient
-        * proximal_fun2:
-            | callable,
-            | method that given an x return the evaluation of proximal operator of the function g
-        * args:
-            | tuple,
-            | arguments that should be given to the callable fun1 besides x
-        * options:
-            | dictionnary, None by default,
-            | contains several options that can be given to customize the gradient descent method and its stopping criteria
-            | these options are:
-            | 'algorithm': string, the type of algorithm ('ISTA' or 'FISTA') used, 'ISTA' by default
-            | 'step_size': float, the step size of the gradient descent, step_size=1 by default,
-            | 'nit_max': integer, the maximal number of iteration, nit_max=50 by default,
-    - output:
-        * the optimal value of x
-        * the evaluation of the function f at the optimal value of x
-        * the evaluation of the gradient of the function f at the optimal value of x
-        * the number of iteration needed to converge
-    """
+
+    # TO DO
+    # Improve stopping criteria, add ftol and gtol.
+    # Add exceptions to check input types.
 
     if not isinstance(args, tuple):
         args = (args,)