fix #23

docs/html/md_pages_components_rom_lspg_hypred.html

@@ -97,13 +97,14 @@ <h1>
 
 <span class="n">problem</span> <span class="o">=</span> <span class="n">lspg</span><span class="o">.</span><span class="n">unsteady</span><span class="o">.</span><span class="n">PrecHypredProblem</span><span class="p">(</span><span class="n">scheme</span><span class="p">,</span> <span class="n">fom_adapter</span><span class="p">,</span> <span class="n">decoder</span><span class="p">,</span> \
                                           <span class="n">rom_state</span><span class="p">,</span> <span class="n">fom_ref_state</span><span class="p">,</span> \
-                                          <span class="n">sampleToStencilIndexing</span><span class="p">,</span> <span class="n">preconditioner</span><span class="p">)</span></pre><ul><li><code>scheme</code>:<ul><li>value from the <code>ode.stepscheme</code> enum setting the desired stepping scheme</li><li>requires an <a href="md_pages_components_ode_steppers_implicit.html">implicit value</a></li></ul></li><li><code>fom_adapter</code>:<ul><li>instance of your adapter class specifying the FOM problem.<br /></li><li>must be admissible to unsteady LSPG, see <a href="./md_pages_components_rom_fom_apis.html">API list</a></li></ul></li><li><code>decoder</code>:<ul><li>decoder object</li><li>must satify the requirements listed <a href="md_pages_components_rom_decoder.html">here</a></li></ul></li><li><code>rom_state</code>:<ul><li>currently, must be a rank-1 <code>numpy.array</code></li></ul></li><li><code>fom_ref_state</code>:<ul><li>your FOM reference state that is used when reconstructing the FOM state</li><li>must be a rank-1 <code>numpy.array</code></li></ul></li><li><code>stencilToSampleIndexing</code>:<ul><li>an object that knows the mapping from sample to stancil operators</li><li>can be constructed as:<br /> <code class="m-code"><span class="n">mapper</span> <span class="o">=</span> <span class="n">rom</span><span class="o">.</span><span class="n">lspg</span><span class="o">.</span><span class="n">unsteady</span><span class="o">.</span><span class="n">StencilToSampleIndexing</span><span class="p">(</span><span class="n">list_of_ints</span><span class="p">)</span></code> &nbsp;</li><li>see section below for more details</li></ul></li><li><code>preconditioner</code>:<ul><li>functor needed to precondition the ROM operators</li><li><p>must be a functor with a specific API:</p><pre class="m-code"><span class="k">class</span> <span class="nc">Prec</span><span class="p">:</span>
+                                          <span class="n">sampleToStencilIndexing</span><span class="p">,</span> <span class="n">preconditioner</span><span class="p">)</span></pre><ul><li><code>scheme</code>:<ul><li>value from the <code>ode.stepscheme</code> enum setting the desired stepping scheme</li><li>requires an <a href="md_pages_components_ode_steppers_implicit.html">implicit value</a></li></ul></li><li><code>fom_adapter</code>:<ul><li>instance of your adapter class specifying the FOM problem.<br /></li><li>must be admissible to unsteady LSPG, see <a href="./md_pages_components_rom_fom_apis.html">API list</a></li></ul></li><li><code>decoder</code>:<ul><li>decoder object</li><li>must satify the requirements listed <a href="md_pages_components_rom_decoder.html">here</a></li></ul></li><li><code>rom_state</code>:<ul><li>currently, must be a rank-1 <code>numpy.array</code></li></ul></li><li><code>fom_ref_state</code>:<ul><li>your FOM reference state that is used when reconstructing the FOM state</li><li>must be a rank-1 <code>numpy.array</code></li></ul></li><li><code>stencilToSampleIndexing</code>:<ul><li>an object that knows the mapping from sample to stancil operators</li><li><p>can be constructed as:<br /></p><pre class="m-code"><span class="n">mapper</span> <span class="o">=</span> <span class="n">rom</span><span class="o">.</span><span class="n">lspg</span><span class="o">.</span><span class="n">unsteady</span><span class="o">.</span><span class="n">StencilToSampleIndexing</span><span class="p">(</span><span class="n">list_of_ints</span><span class="p">,</span> \
+                                                   <span class="n">num_vars_per_cell</span><span class="p">)</span></pre> &nbsp;</li><li>see section below for more details</li><li>where <code>num_vars_per_cell</code> is the number of variables for each cell. For example, for 1d Euler equations in conservative form one has density, momentum and energy.</li></ul></li><li><code>preconditioner</code>:<ul><li>functor needed to precondition the ROM operators</li><li><p>must be a functor with a specific API:</p><pre class="m-code"><span class="k">class</span> <span class="nc">Prec</span><span class="p">:</span>
   <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fom_state</span><span class="p">,</span> <span class="n">time</span><span class="p">,</span> <span class="n">operand</span><span class="p">):</span>
     <span class="c1"># given the current FOM state,</span>
     <span class="c1"># apply your preconditioner to the operand.</span>
     <span class="c1"># Ensure that you overwrite the data in the operand.</span>
     <span class="c1"># As an example, a trivial preconditioner that does nothing:</span>
-    <span class="c1"># operand[:] *= 1.</span></pre> <p><br /></p></li></ul></li></ul></section><section id="autotoc_md90"><h2><a href="#autotoc_md90">Stencil to sample indexing</a></h2><p>When working with a hyper-reduced problem, pressio4py has to manipulate objects that have different sizes/distributions. For such problem, in fact, some operators are naturally defined on the what we refer to as &quot;sample mesh&quot; while some are defined on what we call the &quot;stencil mesh&quot;.</p><p>As explained <a href="https://pressio.github.io/algos/hyper/">here</a>, recall that:</p><ol><li><strong>sample mesh</strong>: a disjoint collection of elements where the velocity (or residual) operator is computed.</li><li><strong>stencil mesh</strong>: the set of all nodes or elements needed to compute the velocity or residual on the sample mesh.</li><li>Typically, the sample mesh is a subset of the stencil mesh.</li></ol><div class="m-note m-info"><p>The sample to stencil indexing is a list of indices that you need to provide such that pressio4py knows how to properly combine operands defined on stencil and sample mesh.</p></div><section id="autotoc_md91"><h3><a href="#autotoc_md91">Explain it to me better!</a></h3><p>Suppose that your FOM problem involves a 2D problem and that your FOM numerical method needs at every cell information from the nearest neighbors. For the sake of explanation, <em>it does not matter what problem we are solving</em>, only what we just said. Now, suppose that you want to try hyper-reduced LSPG on it. You come up with a sample and stencil mesh for your problem (read <a href="https://pressio.github.io/algos/hyper/">this page</a> for some information about how to select sample mesh cells), and let&#x27;s say it looks like this:</p><img class="m-image" src="lspg_sample_mesh1.png" alt="Image" style="width: 400px;" /><p>The stencil mesh is the set of <em>all</em> cells shown, while the sample mesh is the <em>subset</em> color-coded yellow. We have added an arbitrary enumeration scheme to uniquely assign a global index to each cell. The enumeration order does not matter, this is just for demonstration purposes. You have an adapter class for your problem that is able to compute the FOM right-hand-side <svg class="m-math" style="width: 0.734em; height: 1.107em;" viewBox="0 -8.302191 7.046437 10.626798">
+    <span class="c1"># operand[:] *= 1.</span></pre> <p><br /></p></li></ul></li></ul></section><section id="autotoc_md90"><h2><a href="#autotoc_md90">Stencil to sample indexing</a></h2><p>When working with a hyper-reduced problem, pressio4py has to manipulate objects that have different sizes/distributions. For such problem, in fact, some operators are naturally defined on the what we refer to as &quot;sample mesh&quot; while some are defined on what we call the &quot;stencil mesh&quot;.</p><p>As explained <a href="https://pressio.github.io/algos/hyper/">here</a>, recall that:</p><ol><li><strong>sample mesh</strong>: a disjoint collection of elements where the velocity (or residual) operator is computed.</li><li><strong>stencil mesh</strong>: the set of all nodes or elements needed to compute the velocity or residual on the sample mesh.</li><li>Typically, the sample mesh is a subset of the stencil mesh.</li></ol><div class="m-note m-info"><p>The sample to stencil indexing is a list of indices that you need to provide such that pressio4py knows how to properly combine operands defined on stencil and sample mesh.</p></div><section id="autotoc_md91"><h3><a href="#autotoc_md91">Explain it to me better!</a></h3><p>Suppose that your FOM problem involves a 2D problem and that your FOM numerical method needs at every cell information from the nearest neighbors. Also, for the sake of explanation, suppose that your problem stores 1 quantity at each cell. For example, you are solving a heat equation for the temperature field. Now, suppose that you want to try hyper-reduced LSPG on it. You come up with a sample and stencil mesh for your problem (read <a href="https://pressio.github.io/algos/hyper/">this page</a> for some information about how to select sample mesh cells), and let&#x27;s say it looks like this:</p><img class="m-image" src="lspg_sample_mesh1.png" alt="Image" style="width: 400px;" /><p>The stencil mesh is the set of <em>all</em> cells shown, while the sample mesh is the <em>subset</em> color-coded yellow. We have added an arbitrary enumeration scheme to uniquely assign a global index to each cell. The enumeration order does not matter, this is just for demonstration purposes. You have an adapter class for your problem that is able to compute the FOM right-hand-side <svg class="m-math" style="width: 0.734em; height: 1.107em;" viewBox="0 -8.302191 7.046437 10.626798">
 <title>
 $f$
 </title>
@@ -124,11 +125,13 @@ <h1>
 <use x='0' y='0' xlink:href='#eq2-g0-121'/>
 </g>
 </svg> on the stencil mesh.</p><p>For this example, you then would do this:</p><pre class="m-code"><span class="c1"># ...</span>
+<span class="c1"># we assume here you only have 1 variable per cell</span>
+<span class="n">numVarsPerCell</span> <span class="o">=</span> <span class="mi">1</span>
 <span class="n">mylist</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">9</span><span class="p">,</span><span class="mi">14</span><span class="p">,</span><span class="mi">18</span><span class="p">,</span><span class="mi">24</span><span class="p">,</span><span class="mi">25</span><span class="p">,</span><span class="mi">31</span><span class="p">,</span><span class="mi">37</span><span class="p">,</span><span class="mi">40</span><span class="p">,</span><span class="mi">47</span><span class="p">,</span><span class="mi">50</span><span class="p">,</span><span class="mi">53</span><span class="p">,</span><span class="mi">62</span><span class="p">,</span><span class="mi">65</span><span class="p">,</span><span class="mi">70</span><span class="p">]</span>
-<span class="n">indexing</span> <span class="o">=</span> <span class="n">rom</span><span class="o">.</span><span class="n">lspg</span><span class="o">.</span><span class="n">unsteady</span><span class="o">.</span><span class="n">StencilToSampleIndexing</span><span class="p">(</span><span class="n">mylist</span><span class="p">)</span>
+<span class="n">indexing</span> <span class="o">=</span> <span class="n">rom</span><span class="o">.</span><span class="n">lspg</span><span class="o">.</span><span class="n">unsteady</span><span class="o">.</span><span class="n">StencilToSampleIndexing</span><span class="p">(</span><span class="n">mylist</span><span class="p">,</span> <span class="n">numVarsPerCell</span><span class="p">)</span>
 <span class="n">scheme</span> <span class="o">=</span> <span class="n">ode</span><span class="o">.</span><span class="n">stepscheme</span><span class="o">.</span><span class="n">BDF1</span>
 <span class="n">lspgProblem</span> <span class="o">=</span> <span class="n">rom</span><span class="o">.</span><span class="n">lspg</span><span class="o">.</span><span class="n">unsteady</span><span class="o">.</span><span class="n">HypredProblem</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">indexing</span><span class="p">)</span>
-<span class="c1"># ...</span></pre><aside class="m-block m-info"><h3>Note that:</h3><ul><li>how you enumerate the cells does not matter. You are free to do whatever you want, as long as your adapter object is consistent with the chosen enumeration scheme and handles things accordingly.</li><li>This indexing notion seamlessly extends to 1D and 3D problems.</li></ul></aside></section></section>
+<span class="c1"># ...</span></pre><aside class="m-block m-info"><h3>Note that:</h3><ul><li>how you enumerate the cells does not matter. You are free to do whatever you want, as long as your adapter object is consistent with the chosen enumeration scheme and handles things accordingly.</li><li>This indexing notion seamlessly extends to 1D and 3D problems.</li><li>If you have multiple quantities per cell, then you need to set <code>numVarsPerCell</code> accordingly</li></ul></aside></section></section>
       </div>
     </div>
   </div>

docs/latex/md_pages_components_rom_lspg_hypred.tex

@@ -49,11 +49,13 @@
 \item can be constructed as\+: ~\newline
 
 \begin{DoxyCode}{0}
-\DoxyCodeLine{mapper = rom.lspg.unsteady.StencilToSampleIndexing(list\_of\_ints)}
+\DoxyCodeLine{mapper = rom.lspg.unsteady.StencilToSampleIndexing(list\_of\_ints, \(\backslash\)}
+\DoxyCodeLine{                                                   num\_vars\_per\_cell)}
 
 \end{DoxyCode}
  ~
 \item see section below for more details
+\item where {\ttfamily num\+\_\+vars\+\_\+per\+\_\+cell} is the number of variables for each cell. For example, for 1d Euler equations in conservative form one has density, momentum and energy.
 \end{DoxyItemize}
 \item {\ttfamily preconditioner}\+:
 \begin{DoxyItemize}
@@ -87,7 +89,7 @@
 
 
 The sample to stencil indexing is a list of indices that you need to provide such that pressio4py knows how to properly combine operands defined on stencil and sample mesh. \hypertarget{md_pages_components_rom_lspg_hypred_autotoc_md91}{}\doxysubsection{Explain it to me better!}\label{md_pages_components_rom_lspg_hypred_autotoc_md91}
-Suppose that your FOM problem involves a 2D problem and that your FOM numerical method needs at every cell information from the nearest neighbors. For the sake of explanation, {\itshape it does not matter what problem we are solving}, only what we just said. Now, suppose that you want to try hyper-\/reduced LSPG on it. You come up with a sample and stencil mesh for your problem (read \href{https://pressio.github.io/algos/hyper/}{\texttt{ this page}} for some information about how to select sample mesh cells), and let\textquotesingle{}s say it looks like this\+: 
+Suppose that your FOM problem involves a 2D problem and that your FOM numerical method needs at every cell information from the nearest neighbors. Also, for the sake of explanation, suppose that your problem stores 1 quantity at each cell. For example, you are solving a heat equation for the temperature field. Now, suppose that you want to try hyper-\/reduced LSPG on it. You come up with a sample and stencil mesh for your problem (read \href{https://pressio.github.io/algos/hyper/}{\texttt{ this page}} for some information about how to select sample mesh cells), and let\textquotesingle{}s say it looks like this\+: 
 
 The stencil mesh is the set of {\itshape all} cells shown, while the sample mesh is the {\itshape subset} color-\/coded yellow. We have added an arbitrary enumeration scheme to uniquely assign a global index to each cell. The enumeration order does not matter, this is just for demonstration purposes. You have an adapter class for your problem that is able to compute the FOM right-\/hand-\/side $f$ on the yellow cells, for a given FOM state $y$ on the stencil mesh.
 
@@ -96,8 +98,10 @@
 
 \begin{DoxyCode}{0}
 \DoxyCodeLine{\textcolor{comment}{\# ...}}
+\DoxyCodeLine{\textcolor{comment}{\# we assume here you only have 1 variable per cell}}
+\DoxyCodeLine{numVarsPerCell = 1}
 \DoxyCodeLine{mylist = [1,4,9,14,18,24,25,31,37,40,47,50,53,62,65,70]}
-\DoxyCodeLine{indexing = rom.lspg.unsteady.StencilToSampleIndexing(mylist)}
+\DoxyCodeLine{indexing = rom.lspg.unsteady.StencilToSampleIndexing(mylist, numVarsPerCell)}
 \DoxyCodeLine{scheme = ode.stepscheme.BDF1}
 \DoxyCodeLine{lspgProblem = rom.lspg.unsteady.HypredProblem(..., indexing)}
 \DoxyCodeLine{\textcolor{comment}{\# ...}}
@@ -111,6 +115,7 @@
 
 \begin{DoxyItemize}
 \item how you enumerate the cells does not matter. You are free to do whatever you want, as long as your adapter object is consistent with the chosen enumeration scheme and handles things accordingly.
-\item This indexing notion seamlessly extends to 1D and 3D problems. 
+\item This indexing notion seamlessly extends to 1D and 3D problems.
+\item If you have multiple quantities per cell, then you need to set {\ttfamily num\+Vars\+Per\+Cell} accordingly
 \end{DoxyItemize}
 \end{DoxyParagraph}

docs/pages/components/rom_lspg_hypred.md

@@ -45,10 +45,13 @@ problem = lspg.unsteady.PrecHypredProblem(scheme, fom_adapter, decoder, \
   - an object that knows the mapping from sample to stancil operators
   - can be constructed as: <br/>
   ```py
-  mapper = rom.lspg.unsteady.StencilToSampleIndexing(list_of_ints)
+  mapper = rom.lspg.unsteady.StencilToSampleIndexing(list_of_ints, \
+                                                     num_vars_per_cell)
   ```
   &nbsp;
   - see section below for more details
+  - where `num_vars_per_cell` is the number of variables for each cell.
+    For example, for 1d Euler equations in conservative form one has density, momentum and energy.
 
 - `preconditioner`:
   - functor needed to precondition the ROM operators
@@ -95,8 +98,8 @@ pressio4py knows how to properly combine operands defined on stencil and sample
 
 Suppose that your FOM problem involves a 2D problem and that your FOM numerical
 method needs at every cell information from the nearest neighbors.
-For the sake of explanation, *it does not matter what problem we are solving*,
-only what we just said.
+Also, for the sake of explanation, suppose that your problem stores 1 quantity at each cell.
+For example, you are solving a heat equation for the temperature field.
 Now, suppose that you want to try hyper-reduced LSPG on it.
 You come up with a sample and stencil mesh for your problem
 (read [this page](https://pressio.github.io/algos/hyper/) for some information about
@@ -115,8 +118,10 @@ For this example, you then would do this:
 
 ```py
 # ...
+# we assume here you only have 1 variable per cell
+numVarsPerCell = 1
 mylist = [1,4,9,14,18,24,25,31,37,40,47,50,53,62,65,70]
-indexing = rom.lspg.unsteady.StencilToSampleIndexing(mylist)
+indexing = rom.lspg.unsteady.StencilToSampleIndexing(mylist, numVarsPerCell)
 scheme = ode.stepscheme.BDF1
 lspgProblem = rom.lspg.unsteady.HypredProblem(..., indexing)
 # ...
@@ -130,6 +135,9 @@ lspgProblem = rom.lspg.unsteady.HypredProblem(..., indexing)
   consistent with the chosen enumeration scheme and handles things accordingly.
 
 - This indexing notion seamlessly extends to 1D and 3D problems.
+
+- If you have multiple quantities per cell, then you need to set `numVarsPerCell` accordingly
+
 @endparblock