Update documentation

TomographicImaging · Dec 21, 2023 · 29a3ee9 · 29a3ee9
1 parent 9a35e16
commit 29a3ee9
Show file tree

Hide file tree

Showing 6 changed files with 96 additions and 46 deletions.
diff --git a/nightly/.doctrees/environment.pickle b/nightly/.doctrees/environment.pickle
diff --git a/nightly/.doctrees/optimisation.doctree b/nightly/.doctrees/optimisation.doctree
diff --git a/nightly/_modules/cil/optimisation/algorithms/FISTA.html b/nightly/_modules/cil/optimisation/algorithms/FISTA.html
@@ -212,6 +212,7 @@ <h1>Source code for cil.optimisation.algorithms.FISTA</h1><div class="highlight"
 <span class="c1"># CIL Developers, listed at: https://github.com/TomographicImaging/CIL/blob/master/NOTICE.txt</span>
 
 <span class="kn">from</span> <span class="nn">cil.optimisation.algorithms</span> <span class="kn">import</span> <span class="n">Algorithm</span>
+<span class="kn">from</span> <span class="nn">cil.optimisation.functions</span> <span class="kn">import</span> <span class="n">ZeroFunction</span>
 <span class="kn">import</span> <span class="nn">numpy</span>
 <span class="kn">import</span> <span class="nn">warnings</span>
 <span class="kn">import</span> <span class="nn">logging</span>
@@ -250,15 +251,20 @@ <h1>Source code for cil.optimisation.algorithms.FISTA</h1><div class="highlight"
 <span class="sd">    initial : DataContainer</span>
 <span class="sd">              Initial guess of ISTA.</span>
 <span class="sd">    f : Function</span>
-<span class="sd">        Differentiable function</span>
-<span class="sd">    g : Function</span>
-<span class="sd">        Convex function with *simple* proximal operator</span>
+<span class="sd">        Differentiable function. If `None` is passed, the algorithm will use the ZeroFunction.</span>
+<span class="sd">    g : Function or `None`</span>
+<span class="sd">        Convex function with *simple* proximal operator. If `None` is passed, the algorithm will use the ZeroFunction.</span>
 <span class="sd">    step_size : positive :obj:`float`, default = None</span>
 <span class="sd">                Step size for the gradient step of ISTA.</span>
-<span class="sd">                The default :code:`step_size` is :math:`\frac{0.99 * 2}{L}.`</span>
+<span class="sd">                The default :code:`step_size` is :math:`\frac{1}{L}` or 1 if `f=None`.</span>
 <span class="sd">    kwargs: Keyword arguments</span>
 <span class="sd">        Arguments from the base class :class:`.Algorithm`.</span>
 
+<span class="sd">    Note</span>
+<span class="sd">    -----</span>
+<span class="sd">    If the function `g` is set to `None` or to the `ZeroFunction` then the ISTA algorithm is equivalent to Gradient Descent. </span>
+<span class="sd">    </span>
+<span class="sd">    If the function `f` is set to `None` or to the `ZeroFunction` then the ISTA algorithm is equivalent to a Proximal Point Algorithm. </span>
 
 <span class="sd">    Examples</span>
 <span class="sd">    --------</span>
@@ -292,11 +298,17 @@ <h1>Source code for cil.optimisation.algorithms.FISTA</h1><div class="highlight"
 <div class="viewcode-block" id="ISTA.set_step_size"><a class="viewcode-back" href="../../../../optimisation.html#cil.optimisation.algorithms.ISTA.set_step_size">[docs]</a>    <span class="k">def</span> <span class="nf">set_step_size</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">step_size</span><span class="p">):</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot; Set default step size.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
+
         <span class="k">if</span> <span class="n">step_size</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="o">.</span><span class="n">L</span><span class="p">,</span> <span class="n">Number</span><span class="p">):</span>
+            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="p">,</span> <span class="n">ZeroFunction</span><span class="p">):</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">_step_size</span> <span class="o">=</span> <span class="mi">1</span>
+
+            <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="o">.</span><span class="n">L</span><span class="p">,</span> <span class="n">Number</span><span class="p">):</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_step_size</span> <span class="o">=</span> <span class="mf">0.99</span><span class="o">*</span><span class="mf">2.0</span><span class="o">/</span><span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="o">.</span><span class="n">L</span>
+
             <span class="k">else</span><span class="p">:</span>
                 <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Function f is not differentiable&quot;</span><span class="p">)</span>
+
         <span class="k">else</span><span class="p">:</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_step_size</span> <span class="o">=</span> <span class="n">step_size</span>            </div>
 
@@ -315,13 +327,23 @@ <h1>Source code for cil.optimisation.algorithms.FISTA</h1><div class="highlight"
         <span class="c1"># set up ISTA      </span>
         <span class="bp">self</span><span class="o">.</span><span class="n">initial</span> <span class="o">=</span> <span class="n">initial</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">x_old</span> <span class="o">=</span> <span class="n">initial</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">initial</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>           
+        <span class="bp">self</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">initial</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>    
+
+        <span class="k">if</span> <span class="n">f</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+            <span class="n">f</span> <span class="o">=</span> <span class="n">ZeroFunction</span><span class="p">()</span>
+
         <span class="bp">self</span><span class="o">.</span><span class="n">f</span> <span class="o">=</span> <span class="n">f</span>
+
+        <span class="k">if</span> <span class="n">g</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+            <span class="n">g</span> <span class="o">=</span> <span class="n">ZeroFunction</span><span class="p">()</span>
+
         <span class="bp">self</span><span class="o">.</span><span class="n">g</span> <span class="o">=</span> <span class="n">g</span>
+
+        <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">ZeroFunction</span><span class="p">)</span> <span class="ow">and</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">g</span><span class="p">,</span> <span class="n">ZeroFunction</span><span class="p">):</span>
+            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;You set both f and g to be the ZeroFunction and thus the iterative method will not update and will remain fixed at the initial value.&#39;</span><span class="p">)</span>
 
         <span class="c1"># set step_size</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">set_step_size</span><span class="p">(</span><span class="n">step_size</span><span class="o">=</span><span class="n">step_size</span><span class="p">)</span>
-
         <span class="bp">self</span><span class="o">.</span><span class="n">configured</span> <span class="o">=</span> <span class="kc">True</span>  
 
         <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">&quot;</span><span class="si">{}</span><span class="s2"> configured&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="vm">__name__</span><span class="p">,</span> <span class="p">))</span></div>
@@ -391,15 +413,20 @@ <h1>Source code for cil.optimisation.algorithms.FISTA</h1><div class="highlight"
 <span class="sd">    initial : DataContainer</span>
 <span class="sd">            Starting point of the algorithm</span>
 <span class="sd">    f : Function</span>
-<span class="sd">        Differentiable function</span>
-<span class="sd">    g : Function</span>
-<span class="sd">        Convex function with *simple* proximal operator</span>
+<span class="sd">        Differentiable function.  If `None` is passed, the algorithm will use the ZeroFunction.</span>
+<span class="sd">    g : Function or `None`</span>
+<span class="sd">        Convex function with *simple* proximal operator. If `None` is passed, the algorithm will use the ZeroFunction.</span>
 <span class="sd">    step_size : positive :obj:`float`, default = None</span>
 <span class="sd">                Step size for the gradient step of FISTA.</span>
-<span class="sd">                The default :code:`step_size` is :math:`\frac{1}{L}`.</span>
+<span class="sd">                The default :code:`step_size` is :math:`\frac{1}{L}` or 1 if `f=None`.</span>
 <span class="sd">    kwargs: Keyword arguments</span>
 <span class="sd">        Arguments from the base class :class:`.Algorithm`.</span>
 
+<span class="sd">    Note</span>
+<span class="sd">    -----</span>
+<span class="sd">    If the function `g` is set to `None` or to the `ZeroFunction` then the FISTA algorithm is equivalent to Accelerated Gradient Descent by Nesterov (:cite:`nesterov2003introductory` algorithm 2.2.9).</span>
+
+<span class="sd">    If the function `f` is set to `None` or to the `ZeroFunction` then the FISTA algorithm is equivalent to Guler&#39;s First Accelerated Proximal Point Method  (:cite:`guler1992new` sec 2).</span>
 
 <span class="sd">    Examples</span>
 <span class="sd">    --------</span>
@@ -424,11 +451,18 @@ <h1>Source code for cil.optimisation.algorithms.FISTA</h1><div class="highlight"
 
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;Set the default step size</span>
 <span class="sd">        &quot;&quot;&quot;</span>
+
         <span class="k">if</span> <span class="n">step_size</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="o">.</span><span class="n">L</span><span class="p">,</span> <span class="n">Number</span><span class="p">):</span>
+
+            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="p">,</span> <span class="n">ZeroFunction</span><span class="p">):</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">_step_size</span> <span class="o">=</span> <span class="mi">1</span>
+
+            <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="o">.</span><span class="n">L</span><span class="p">,</span> <span class="n">Number</span><span class="p">):</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_step_size</span> <span class="o">=</span> <span class="mf">1.</span><span class="o">/</span><span class="bp">self</span><span class="o">.</span><span class="n">f</span><span class="o">.</span><span class="n">L</span>
+
             <span class="k">else</span><span class="p">:</span>
                 <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Function f is not differentiable&quot;</span><span class="p">)</span>
+
         <span class="k">else</span><span class="p">:</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_step_size</span> <span class="o">=</span> <span class="n">step_size</span></div>