Update documentation

TomographicImaging · Nov 8, 2023 · 7fd8c0a · 7fd8c0a
1 parent 540cbe4
commit 7fd8c0a
Show file tree

Hide file tree

Showing 10 changed files with 325 additions and 227 deletions.
diff --git a/nightly/.doctrees/environment.pickle b/nightly/.doctrees/environment.pickle
diff --git a/nightly/.doctrees/framework.doctree b/nightly/.doctrees/framework.doctree
diff --git a/nightly/.doctrees/optimisation.doctree b/nightly/.doctrees/optimisation.doctree
diff --git a/nightly/_modules/cil/optimisation/operators/BlockOperator.html b/nightly/_modules/cil/optimisation/operators/BlockOperator.html
diff --git a/nightly/_modules/cil/optimisation/operators/Operator.html b/nightly/_modules/cil/optimisation/operators/Operator.html
@@ -265,7 +265,28 @@ <h1>Source code for cil.optimisation.operators.Operator</h1><div class="highligh
 
 <div class="viewcode-block" id="Operator.set_norm"><a class="viewcode-back" href="../../../../optimisation.html#cil.optimisation.operators.Operator.set_norm">[docs]</a>    <span class="k">def</span> <span class="nf">set_norm</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">norm</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
 <span class="w">        </span><span class="sd">&#39;&#39;&#39;Sets the norm of the operator to a custom value.</span>
+
+<span class="sd">        Parameters</span>
+<span class="sd">        ---------</span>
+<span class="sd">        norm: float, optional</span>
+<span class="sd">            Positive real valued number or `None`</span>
+
+
+<span class="sd">        Note</span>
+<span class="sd">        ----</span>
+<span class="sd">        The passed values are cached so that when self.norm() is called, the saved value will be returned and not calculated via the power method. </span>
+<span class="sd">        If `None` is passed, the cache is cleared prompting the function to call the power method to calculate the norm the next time self.norm() is called. </span>
 <span class="sd">        &#39;&#39;&#39;</span>
+
+        <span class="k">if</span> <span class="n">norm</span> <span class="ow">is</span> <span class="ow">not</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="n">norm</span><span class="p">,</span> <span class="n">Number</span><span class="p">):</span>
+                <span class="k">if</span> <span class="n">norm</span> <span class="o">&lt;=</span> <span class="mi">0</span><span class="p">:</span>
+                    <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
+                        <span class="s2">&quot;Norm must be a positive real valued number or None, got </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">norm</span><span class="p">))</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span>
+                    <span class="s2">&quot;Norm must be a number or None, got </span><span class="si">{}</span><span class="s2"> of type </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">norm</span><span class="p">,</span> <span class="nb">type</span><span class="p">(</span><span class="n">norm</span><span class="p">)))</span>
+
         <span class="bp">self</span><span class="o">.</span><span class="n">_norm</span> <span class="o">=</span> <span class="n">norm</span></div>
 
 <div class="viewcode-block" id="Operator.calculate_norm"><a class="viewcode-back" href="../../../../optimisation.html#cil.optimisation.operators.Operator.calculate_norm">[docs]</a>    <span class="k">def</span> <span class="nf">calculate_norm</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
@@ -545,10 +566,16 @@ <h1>Source code for cil.optimisation.operators.Operator</h1><div class="highligh
 <span class="sd">    of the result of direct and adjoint of the operator with the scalar.</span>
 <span class="sd">    For the rest it behaves like the operator it holds.</span>
 
-<span class="sd">    :param operator: a Operator or LinearOperator</span>
-<span class="sd">    :param scalar: a scalar multiplier</span>
+<span class="sd">    Parameters</span>
+<span class="sd">    ----------</span>
+<span class="sd">    operator: a Operator or LinearOperator</span>
+
+<span class="sd">    scalar: a scalar multiplier</span>
+
 
-<span class="sd">    Example:</span>
+
+<span class="sd">    Example</span>
+<span class="sd">    -------</span>
 <span class="sd">       The scaled operator behaves like the following:</span>
 
 <span class="sd">    .. code-block:: python</span>
@@ -563,11 +590,6 @@ <h1>Source code for cil.optimisation.operators.Operator</h1><div class="highligh
 <span class="sd">    &#39;&#39;&#39;</span>
 
 <div class="viewcode-block" id="ScaledOperator.__init__"><a class="viewcode-back" href="../../../../optimisation.html#cil.optimisation.operators.ScaledOperator.__init__">[docs]</a>    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">operator</span><span class="p">,</span> <span class="n">scalar</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
-<span class="w">        </span><span class="sd">&#39;&#39;&#39;creator</span>
-
-<span class="sd">        :param operator: a Operator or LinearOperator</span>
-<span class="sd">        :param scalar: a scalar multiplier</span>
-<span class="sd">        :type scalar: Number&#39;&#39;&#39;</span>
 
         <span class="nb">super</span><span class="p">(</span><span class="n">ScaledOperator</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="n">domain_geometry</span><span class="o">=</span><span class="n">operator</span><span class="o">.</span><span class="n">domain_geometry</span><span class="p">(),</span>
                                              <span class="n">range_geometry</span><span class="o">=</span><span class="n">operator</span><span class="o">.</span><span class="n">range_geometry</span><span class="p">())</span>
@@ -604,9 +626,7 @@ <h1>Source code for cil.optimisation.operators.Operator</h1><div class="highligh
         <span class="k">return</span> <span class="n">numpy</span><span class="o">.</span><span class="n">abs</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">scalar</span><span class="p">)</span> <span class="o">*</span> <span class="bp">self</span><span class="o">.</span><span class="n">operator</span><span class="o">.</span><span class="n">norm</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span></div>
 
 <div class="viewcode-block" id="ScaledOperator.is_linear"><a class="viewcode-back" href="../../../../optimisation.html#cil.optimisation.operators.ScaledOperator.is_linear">[docs]</a>    <span class="k">def</span> <span class="nf">is_linear</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<span class="w">        </span><span class="sd">&#39;&#39;&#39;returns whether the operator is linear</span>
-
-<span class="sd">        :returns: boolean &#39;&#39;&#39;</span>
+<span class="w">        </span><span class="sd">&#39;&#39;&#39;returns a `boolean` indicating whether the operator is linear &#39;&#39;&#39;</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">operator</span><span class="o">.</span><span class="n">is_linear</span><span class="p">()</span></div></div>
 
 

diff --git a/nightly/framework.html b/nightly/framework.html
@@ -787,7 +787,7 @@ <h3>DataContainer<a class="headerlink" href="#datacontainer" title="Permalink to
 
 <dl class="py method">
 <dt id="cil.framework.DataContainer.sapyb">
-<code class="sig-name descname"><span class="pre">sapyb</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">num_threads</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/cil/framework/framework.html#DataContainer.sapyb"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#cil.framework.DataContainer.sapyb" title="Permalink to this definition">#</a></dt>
+<code class="sig-name descname"><span class="pre">sapyb</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">num_threads</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/cil/framework/framework.html#DataContainer.sapyb"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#cil.framework.DataContainer.sapyb" title="Permalink to this definition">#</a></dt>
 <dd><p>performs a*self + b * y. Can be done in-place</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
@@ -1038,7 +1038,7 @@ <h3>AcquisitionData<a class="headerlink" href="#acquisitiondata" title="Permalin
 
 <dl class="py method">
 <dt id="cil.framework.AcquisitionData.sapyb">
-<code class="sig-name descname"><span class="pre">sapyb</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">num_threads</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#cil.framework.AcquisitionData.sapyb" title="Permalink to this definition">#</a></dt>
+<code class="sig-name descname"><span class="pre">sapyb</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">num_threads</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#cil.framework.AcquisitionData.sapyb" title="Permalink to this definition">#</a></dt>
 <dd><p>performs a*self + b * y. Can be done in-place</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
@@ -1244,7 +1244,7 @@ <h3>ImageData<a class="headerlink" href="#imagedata" title="Permalink to this he
 
 <dl class="py method">
 <dt id="cil.framework.ImageData.sapyb">
-<code class="sig-name descname"><span class="pre">sapyb</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">num_threads</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#cil.framework.ImageData.sapyb" title="Permalink to this definition">#</a></dt>
+<code class="sig-name descname"><span class="pre">sapyb</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">num_threads</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#cil.framework.ImageData.sapyb" title="Permalink to this definition">#</a></dt>
 <dd><p>performs a*self + b * y. Can be done in-place</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
@@ -1429,7 +1429,7 @@ <h3>VectorData<a class="headerlink" href="#vectordata" title="Permalink to this
 
 <dl class="py method">
 <dt id="cil.framework.VectorData.sapyb">
-<code class="sig-name descname"><span class="pre">sapyb</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">num_threads</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#cil.framework.VectorData.sapyb" title="Permalink to this definition">#</a></dt>
+<code class="sig-name descname"><span class="pre">sapyb</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">num_threads</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#cil.framework.VectorData.sapyb" title="Permalink to this definition">#</a></dt>
 <dd><p>performs a*self + b * y. Can be done in-place</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
@@ -1615,7 +1615,7 @@ <h3>BlockDataContainer<a class="headerlink" href="#blockdatacontainer" title="Pe
 
 <dl class="py method">
 <dt id="cil.framework.BlockDataContainer.sapyb">
-<code class="sig-name descname"><span class="pre">sapyb</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">num_threads</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/cil/framework/BlockDataContainer.html#BlockDataContainer.sapyb"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#cil.framework.BlockDataContainer.sapyb" title="Permalink to this definition">#</a></dt>
+<code class="sig-name descname"><span class="pre">sapyb</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">num_threads</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/cil/framework/BlockDataContainer.html#BlockDataContainer.sapyb"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#cil.framework.BlockDataContainer.sapyb" title="Permalink to this definition">#</a></dt>
 <dd><p>performs axpby element-wise on the BlockDataContainer containers</p>
 <p>Does the operation .. math:: a*x+b*y and stores the result in out, where x is self</p>
 <dl class="field-list simple">
@@ -1642,7 +1642,7 @@ <h3>BlockDataContainer<a class="headerlink" href="#blockdatacontainer" title="Pe
 
 <dl class="py method">
 <dt id="cil.framework.BlockDataContainer.axpby">
-<code class="sig-name descname"><span class="pre">axpby</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="pre">a</span></em>, <em class="sig-param"><span class="pre">b</span></em>, <em class="sig-param"><span class="pre">y</span></em>, <em class="sig-param"><span class="pre">out</span></em>, <em class="sig-param"><span class="pre">dtype=&lt;class</span> <span class="pre">'numpy.float32'&gt;</span></em>, <em class="sig-param"><span class="pre">num_threads=1</span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/cil/framework/BlockDataContainer.html#BlockDataContainer.axpby"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#cil.framework.BlockDataContainer.axpby" title="Permalink to this definition">#</a></dt>
+<code class="sig-name descname"><span class="pre">axpby</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="pre">a</span></em>, <em class="sig-param"><span class="pre">b</span></em>, <em class="sig-param"><span class="pre">y</span></em>, <em class="sig-param"><span class="pre">out</span></em>, <em class="sig-param"><span class="pre">dtype=&lt;class</span> <span class="pre">'numpy.float32'&gt;</span></em>, <em class="sig-param"><span class="pre">num_threads=2</span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/cil/framework/BlockDataContainer.html#BlockDataContainer.axpby"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#cil.framework.BlockDataContainer.axpby" title="Permalink to this definition">#</a></dt>
 <dd><p>Deprecated method. Alias of sapyb</p>
 </dd></dl>