Update documentation

TomographicImaging · Feb 26, 2024 · 6c478b5 · 6c478b5
1 parent d4619c1
commit 6c478b5
Show file tree

Hide file tree

Showing 12 changed files with 77 additions and 22 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/functions/Function/index.html b/nightly/_modules/cil/optimisation/functions/Function/index.html
@@ -460,6 +460,7 @@ <h1>Source code for cil.optimisation.functions.Function</h1><div class="highligh
 <span class="kn">from</span> <span class="nn">numbers</span> <span class="kn">import</span> <span class="n">Number</span>
 <span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
 <span class="kn">from</span> <span class="nn">functools</span> <span class="kn">import</span> <span class="n">reduce</span>
+<span class="kn">from</span> <span class="nn">cil.utilities.errors</span> <span class="kn">import</span> <span class="n">InPlaceError</span>
 
 
 <div class="viewcode-block" id="Function"><a class="viewcode-back" href="../../../../../optimisation/#cil.optimisation.functions.Function">[docs]</a><span class="k">class</span> <span class="nc">Function</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
@@ -562,6 +563,9 @@ <h1>Source code for cil.optimisation.functions.Function</h1><div class="highligh
 <span class="sd">        DataContainer, the value of the proximal operator of the convex conjugate at point :math:`x` for scalar :math:`\tau` or None if `out`. </span>
 
 <span class="sd">        &quot;&quot;&quot;</span>
+        <span class="k">if</span> <span class="nb">id</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="o">==</span><span class="nb">id</span><span class="p">(</span><span class="n">out</span><span class="p">):</span>
+            <span class="k">raise</span> <span class="n">InPlaceError</span><span class="p">(</span><span class="n">message</span><span class="o">=</span> <span class="s2">&quot;The proximal_conjugate of a CIL function cannot be used in place&quot;</span><span class="p">)</span>
+
         <span class="k">try</span><span class="p">:</span>
             <span class="n">tmp</span> <span class="o">=</span> <span class="n">x</span>
             <span class="n">x</span><span class="o">.</span><span class="n">divide</span><span class="p">(</span><span class="n">tau</span><span class="p">,</span> <span class="n">out</span><span class="o">=</span><span class="n">tmp</span><span class="p">)</span>
@@ -777,8 +781,12 @@ <h1>Source code for cil.optimisation.functions.Function</h1><div class="highligh
 
 <span class="sd">        &quot;&quot;&quot;</span>
 
-        <span class="k">if</span> <span class="n">out</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-            <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">f</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">functions</span><span class="p">):</span>
+        <span class="k">if</span> <span class="n">out</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="nb">id</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="o">==</span><span class="nb">id</span><span class="p">(</span><span class="n">out</span><span class="p">):</span>
+            <span class="k">raise</span> <span class="n">InPlaceError</span>
+
+        <span class="k">if</span> <span class="n">out</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>            
+            <span class="k">for</span> <span class="n">i</span><span class="p">,</span><span class="n">f</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">functions</span><span class="p">):</span>
+
                 <span class="k">if</span> <span class="n">i</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
                     <span class="n">ret</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">gradient</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
                 <span class="k">else</span><span class="p">:</span>
@@ -965,6 +973,9 @@ <h1>Source code for cil.optimisation.functions.Function</h1><div class="highligh
 <span class="sd">        DataContainer, the proximal conjugate operator for the function evaluated at :math:`x` and :math:`\tau` or `None` if `out`.</span>
 
 <span class="sd">        &quot;&quot;&quot;</span>
+        <span class="k">if</span> <span class="n">out</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="nb">id</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="o">==</span><span class="nb">id</span><span class="p">(</span><span class="n">out</span><span class="p">):</span>
+            <span class="k">raise</span> <span class="n">InPlaceError</span>
+
         <span class="k">try</span><span class="p">:</span>
             <span class="n">tmp</span> <span class="o">=</span> <span class="n">x</span>
             <span class="n">x</span><span class="o">.</span><span class="n">divide</span><span class="p">(</span><span class="n">tau</span><span class="p">,</span> <span class="n">out</span><span class="o">=</span><span class="n">tmp</span><span class="p">)</span>
@@ -1247,6 +1258,10 @@ <h1>Source code for cil.optimisation.functions.Function</h1><div class="highligh
 <span class="sd">        -------</span>
 <span class="sd">        DataContainer, the gradient of the translated function evaluated at :math:`x` or `None` if `out`.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
+
+        <span class="k">if</span> <span class="nb">id</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="o">==</span><span class="nb">id</span><span class="p">(</span><span class="n">out</span><span class="p">):</span>
+            <span class="k">raise</span> <span class="n">InPlaceError</span>
+
         <span class="k">try</span><span class="p">:</span>
             <span class="n">x</span><span class="o">.</span><span class="n">subtract</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">center</span><span class="p">,</span> <span class="n">out</span><span class="o">=</span><span class="n">x</span><span class="p">)</span>
             <span class="n">tmp</span> <span class="o">=</span> <span class="n">x</span>
@@ -1280,8 +1295,11 @@ <h1>Source code for cil.optimisation.functions.Function</h1><div class="highligh
 <span class="sd">        Returns</span>
 <span class="sd">        -------</span>
 <span class="sd">        DataContainer, the proximal operator of the translated function at :math:`x` and :math:`\tau` or `None` if `out`.</span>
-
 <span class="sd">        &quot;&quot;&quot;</span>
+
+        <span class="k">if</span> <span class="nb">id</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="o">==</span><span class="nb">id</span><span class="p">(</span><span class="n">out</span><span class="p">):</span>
+            <span class="k">raise</span> <span class="n">InPlaceError</span>
+
         <span class="k">try</span><span class="p">:</span>
             <span class="n">x</span><span class="o">.</span><span class="n">subtract</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">center</span><span class="p">,</span> <span class="n">out</span><span class="o">=</span><span class="n">x</span><span class="p">)</span>
             <span class="n">tmp</span> <span class="o">=</span> <span class="n">x</span>

diff --git a/nightly/_modules/cil/optimisation/functions/IndicatorBox/index.html b/nightly/_modules/cil/optimisation/functions/IndicatorBox/index.html
@@ -614,9 +614,9 @@ <h1>Source code for cil.optimisation.functions.IndicatorBox</h1><div class="high
         <span class="k">if</span> <span class="n">should_return</span><span class="p">:</span>
             <span class="k">return</span> <span class="n">out</span></div>
 
-<div class="viewcode-block" id="IndicatorBox.gradient"><a class="viewcode-back" href="../../../../../optimisation/#cil.optimisation.functions.IndicatorBox.gradient">[docs]</a>    <span class="k">def</span> <span class="nf">gradient</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
+<div class="viewcode-block" id="IndicatorBox.gradient"><a class="viewcode-back" href="../../../../../optimisation/#cil.optimisation.functions.IndicatorBox.gradient">[docs]</a>    <span class="k">def</span> <span class="nf">gradient</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">out</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
 <span class="w">        </span><span class="sd">&#39;&#39;&#39;IndicatorBox is not differentiable, so calling gradient will raise a ``ValueError``&#39;&#39;&#39;</span>
-        <span class="k">return</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;Not Differentiable&#39;</span><span class="p">)</span></div>
+        <span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">(</span><span class="s1">&#39;The IndicatorBox is not differentiable&#39;</span><span class="p">)</span></div>
 
     <span class="k">def</span> <span class="nf">_proximal</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">outarr</span><span class="p">):</span>
         <span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">(</span><span class="s1">&#39;Implement this in the derived class&#39;</span><span class="p">)</span>

diff --git a/nightly/_modules/cil/optimisation/functions/KullbackLeibler/index.html b/nightly/_modules/cil/optimisation/functions/KullbackLeibler/index.html
@@ -460,7 +460,7 @@ <h1>Source code for cil.optimisation.functions.KullbackLeibler</h1><div class="h
 <span class="kn">from</span> <span class="nn">numbers</span> <span class="kn">import</span> <span class="n">Number</span>
 <span class="kn">import</span> <span class="nn">scipy.special</span>
 <span class="kn">import</span> <span class="nn">logging</span>
-
+<span class="kn">from</span> <span class="nn">cil.utilities.errors</span> <span class="kn">import</span> <span class="n">InPlaceError</span>
 <span class="k">try</span><span class="p">:</span>
     <span class="kn">from</span> <span class="nn">numba</span> <span class="kn">import</span> <span class="n">njit</span><span class="p">,</span> <span class="n">prange</span>
     <span class="n">has_numba</span> <span class="o">=</span> <span class="kc">True</span>
@@ -627,6 +627,8 @@ <h1>Source code for cil.optimisation.functions.KullbackLeibler</h1><div class="h
 <span class="sd">        :math:`\mathrm{prox}_{\tau F}(x) = \frac{1}{2}\bigg( (x - \eta - \tau) + \sqrt{ (x + \eta - \tau)^2 + 4\tau b} \bigg)`</span>
 <span class="sd">                            </span>
 <span class="sd">        &quot;&quot;&quot;</span>        
+        <span class="k">if</span>  <span class="nb">id</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="o">==</span><span class="nb">id</span><span class="p">(</span><span class="n">out</span><span class="p">):</span>
+            <span class="k">raise</span> <span class="n">InPlaceError</span><span class="p">(</span><span class="n">message</span><span class="o">=</span><span class="s2">&quot;KullbackLeibler.proximal cannot be used in place&quot;</span><span class="p">)</span>
 
         <span class="k">if</span> <span class="n">out</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>        
             <span class="k">return</span> <span class="mf">0.5</span> <span class="o">*</span><span class="p">(</span> <span class="p">(</span><span class="n">x</span> <span class="o">-</span> <span class="bp">self</span><span class="o">.</span><span class="n">eta</span> <span class="o">-</span> <span class="n">tau</span><span class="p">)</span> <span class="o">+</span> \

diff --git a/nightly/_modules/cil/optimisation/functions/L1Norm/index.html b/nightly/_modules/cil/optimisation/functions/L1Norm/index.html
@@ -456,7 +456,8 @@ <h1>Source code for cil.optimisation.functions.L1Norm</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.functions</span> <span class="kn">import</span> <span class="n">Function</span>    
-<span class="kn">from</span> <span class="nn">cil.framework</span> <span class="kn">import</span> <span class="n">BlockDataContainer</span>   
+<span class="kn">from</span> <span class="nn">cil.framework</span> <span class="kn">import</span> <span class="n">BlockDataContainer</span>
+<span class="kn">from</span> <span class="nn">cil.utilities.errors</span> <span class="kn">import</span> <span class="n">InPlaceError</span>
 <span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
 
 <span class="k">def</span> <span class="nf">soft_shrinkage</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">tau</span><span class="p">,</span> <span class="n">out</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
@@ -475,6 +476,8 @@ <h1>Source code for cil.optimisation.functions.L1Norm</h1><div class="highlight"
 <span class="sd">    --------</span>
 <span class="sd">    the value of the soft-shrinkage operator at x: DataContainer.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
+    <span class="k">if</span>  <span class="nb">id</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="o">==</span><span class="nb">id</span><span class="p">(</span><span class="n">out</span><span class="p">):</span>
+        <span class="k">raise</span> <span class="n">InPlaceError</span><span class="p">(</span><span class="n">message</span><span class="o">=</span><span class="s2">&quot;The soft_shrinkage function cannot be used in place&quot;</span> <span class="p">)</span>
 
     <span class="n">should_return</span> <span class="o">=</span> <span class="kc">False</span>
     <span class="k">if</span> <span class="n">out</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>