Making FAIR the docs and adding CLI checks for illegal combinations

.github/workflows/CI.yml

@@ -24,7 +24,7 @@ jobs:
     - name: Install (optional but recommended) plotting (LaTeX) and ert dependencies
       run: |
         sudo apt-get install texlive-fonts-recommended texlive-fonts-extra dvipng cm-super
-        sudo apt-get install freeglut3-dev
+        sudo apt-get install freeglut3-dev libegl1
 
     - name: Install pofff and python requirements
       run: |

README.md

@@ -46,7 +46,7 @@ pip install --upgrade pip setuptools wheel
 pip install -e .
 # For contributions/testing/linting, install the dev-requirements
 pip install -r dev-requirements.txt
-``` 
+```
 
 See the [_installation_](https://cssr-tools.github.io/pofff/installation.html) for further details on building OPM Flow from the master branches in Linux, Windows (via [_WSL_](https://learn.microsoft.com/en-us/windows/wsl/)), and macOS.
 

docs/_sources/examples.rst.txt

@@ -17,6 +17,14 @@ The following is the figure `map_24h.png`. You can compare your example results
 
 .. figure:: figs/map_24h.png
 
+.. tip::
+
+    All previous commands can be executed as (`docs_hello_world.sh <https://github.com/cssr-tools/pofff/blob/main/tests/scripts/docs_hello_world.sh>`_):
+
+    .. code-block:: bash
+
+        . ./tests/scripts/docs_hello_world.sh
+
 ===================
 Adding your results 
 ===================
@@ -28,7 +36,7 @@ The `publication <https://github.com/cssr-tools/pofff/blob/main/publication>`_ f
 
     pofff -i results.toml -o YOURS -m single -t 24,48,72,96,120 -f all
 
-generates the figures in the paper in addition to the new simulation labeled as the name of the output folder ("YOURS" in this case), e.g., for the compare_all_time_series.png:
+This generates the figures in the paper in addition to the new simulation labeled as the name of the output folder ("YOURS" in this case), e.g., for the compare_all_time_series.png:
 
 .. figure:: figs/compare_all_time_series.png
 
@@ -38,6 +46,14 @@ generates the figures in the paper in addition to the new simulation labeled as
 
 We welcome pull request with your configuration files to the examples folder for cases with better results (less error in the error_table_satmin-0.01_conmin-0.1.csv).
 
+.. tip::
+
+    All previous commands can be executed as (`docs_adding_your_results.sh <https://github.com/cssr-tools/pofff/blob/main/tests/scripts/docs_adding_your_results.sh>`_):
+
+    .. code-block:: bash
+
+        . ./tests/scripts/docs_adding_your_results.sh
+
 .. note::
 
     One can always also generate the sparse_data.csv, time_series.csv, and spatial_map_Xh.csv files using other simulators and use the pofff tool to compare
@@ -112,6 +128,13 @@ Then the following GIF is generated by:
 
     The total simulation time for this GIF (five days of experiment) using eight CPUs for OPM Flow in a Mac is **LESS THAN TWO MINUTES!!!**
 
-
 
 See the `plopm online docmunetation <https://cssr-tools.github.io/plopm/>`_ for additional information of supported flag parameters to generate customized PNGs and GIFs.
+
+.. tip::
+
+    All previous commands can be executed as (`docs_visualization.sh <https://github.com/cssr-tools/pofff/blob/main/tests/scripts/docs_visualization.sh>`_):
+
+    .. code-block:: bash
+
+        . ./tests/scripts/docs_visualization.sh

docs/_sources/publication.rst.txt

@@ -112,37 +112,9 @@ in combination to Python commands, which gives flexibility to generate the diffe
 The Wasserstein distance (obtained from the generated error_table_satmin-0.01_conmin-0.1.csv) for the 
 base case and random seed for the sensitivity study regarding setup choices in Table 8 can be generated by executing the 
 `sensitivity.py <https://github.com/cssr-tools/pofff/blob/main/publication/sensitivity.py>`_ script (if you have a Mac as well, then execute the script in 
-there to see the sensitivity to the operative system). For example, the content of this Python script is the following:
-
-.. code-block:: python
-
-    import subprocess
-    from mako.template import Template
-
-    mytemplate = Template(filename="appendixc.mako")
-    for case, rng in zip(["base", "rng"], [7, 11]):
-        # Modify the number of cores according to your resources
-        var = {"cores": 64, "rng": rng, "cnv": 1e-2, "cnv_relaxed": 1}
-        filledtemplate = mytemplate.render(**var)
-        with open(
-            f"{case}.toml",
-            "w",
-            encoding="utf8",
-        ) as file:
-            file.write(filledtemplate)
-        subprocess.run(
-            [
-                "pofff",
-                "-i", f"{case}.toml",
-                "-o", case,
-                "-m", "everest",
-                "-t", "24,48,72,96,120",
-                "-f", "all",
-            ],
-            check=True,
-        )
-
-The values in Table 7 and Figure 8 can be generated by (increase or decrease the number of cores to adapt to your interest and computer limitations):
+there to see the sensitivity to the operative system).
+
+The values in Table 7 and Figure 12 can be generated by (increase or decrease the number of cores to adapt to your interest and computer limitations):
 
 .. code-block:: bash
 
@@ -157,3 +129,18 @@ Finally, for accuracy-time trade-off Table 9 you can run:
 .. warning::
 
     These scripts are set to run with 64 cores, then you should edit them if your machine has less available cpus.
+
+
+.. tip::
+
+    All previous commands can be executed as (`publication.sh <https://github.com/cssr-tools/pofff/blob/main/tests/scripts/publication.sh>`_):
+
+    .. code-block:: bash
+
+        . ./tests/scripts/publication.sh
+
+    This will run the cases with 64 cores. To run the case with 16 cores instead (in a coarser grid as well), run it as:
+
+    .. code-block:: bash
+
+        . ./tests/scripts/publication.sh 16

docs/examples.html

@@ -100,6 +100,13 @@ <h2>Hello world<a class="headerlink" href="#hello-world" title="Link to this hea
 <figure class="align-default">
 <img alt="_images/map_24h.png" src="_images/map_24h.png" />
 </figure>
+<div class="admonition tip">
+<p class="admonition-title">Tip</p>
+<p>All previous commands can be executed as (<a class="reference external" href="https://github.com/cssr-tools/pofff/blob/main/tests/scripts/docs_hello_world.sh">docs_hello_world.sh</a>):</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>.<span class="w"> </span>./tests/scripts/docs_hello_world.sh
+</pre></div>
+</div>
+</div>
 </section>
 <section id="adding-your-results">
 <h2>Adding your results<a class="headerlink" href="#adding-your-results" title="Link to this heading"></a></h2>
@@ -108,7 +115,7 @@ <h2>Adding your results<a class="headerlink" href="#adding-your-results" title="
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pofff<span class="w"> </span>-i<span class="w"> </span>results.toml<span class="w"> </span>-o<span class="w"> </span>YOURS<span class="w"> </span>-m<span class="w"> </span>single<span class="w"> </span>-t<span class="w"> </span><span class="m">24</span>,48,72,96,120<span class="w"> </span>-f<span class="w"> </span>all
 </pre></div>
 </div>
-<p>generates the figures in the paper in addition to the new simulation labeled as the name of the output folder (“YOURS” in this case), e.g., for the compare_all_time_series.png:</p>
+<p>This generates the figures in the paper in addition to the new simulation labeled as the name of the output folder (“YOURS” in this case), e.g., for the compare_all_time_series.png:</p>
 <figure class="align-default">
 <img alt="_images/compare_all_time_series.png" src="_images/compare_all_time_series.png" />
 </figure>
@@ -117,6 +124,13 @@ <h2>Adding your results<a class="headerlink" href="#adding-your-results" title="
 <p>One can always modify the plotting scripts to change the colors, line styles, font sizes, etc.</p>
 </div>
 <p>We welcome pull request with your configuration files to the examples folder for cases with better results (less error in the error_table_satmin-0.01_conmin-0.1.csv).</p>
+<div class="admonition tip">
+<p class="admonition-title">Tip</p>
+<p>All previous commands can be executed as (<a class="reference external" href="https://github.com/cssr-tools/pofff/blob/main/tests/scripts/docs_adding_your_results.sh">docs_adding_your_results.sh</a>):</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>.<span class="w"> </span>./tests/scripts/docs_adding_your_results.sh
+</pre></div>
+</div>
+</div>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>One can always also generate the sparse_data.csv, time_series.csv, and spatial_map_Xh.csv files using other simulators and use the pofff tool to compare
@@ -185,6 +199,13 @@ <h2>Visualization<a class="headerlink" href="#visualization" title="Link to this
 </figcaption>
 </figure>
 <p>See the <a class="reference external" href="https://cssr-tools.github.io/plopm/">plopm online docmunetation</a> for additional information of supported flag parameters to generate customized PNGs and GIFs.</p>
+<div class="admonition tip">
+<p class="admonition-title">Tip</p>
+<p>All previous commands can be executed as (<a class="reference external" href="https://github.com/cssr-tools/pofff/blob/main/tests/scripts/docs_visualization.sh">docs_visualization.sh</a>):</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>.<span class="w"> </span>./tests/scripts/docs_visualization.sh
+</pre></div>
+</div>
+</div>
 </section>
 </section>
 

docs/genindex.html

@@ -162,6 +162,8 @@ <h2 id="C">C</h2>
       <li><a href="pofff.config.config.html#pofff.config.config.PofffConfig.callback">callback (pofff.config.config.PofffConfig attribute)</a>
 </li>
       <li><a href="pofff.config.config.html#pofff.config.config.PofffConfig.cap">cap (pofff.config.config.PofffConfig attribute)</a>
+</li>
+      <li><a href="pofff.core.pofff.html#pofff.core.pofff.check_cmdargs">check_cmdargs() (in module pofff.core.pofff)</a>
 </li>
       <li><a href="pofff.utils.mapproperties.html#pofff.utils.mapproperties.classify_boxes">classify_boxes() (in module pofff.utils.mapproperties)</a>
 </li>
@@ -172,11 +174,11 @@ <h2 id="C">C</h2>
       <li><a href="pofff.utils.writefile.html#pofff.utils.writefile.compact_format">compact_format() (in module pofff.utils.writefile)</a>
 </li>
       <li><a href="pofff.jobs.data.html#pofff.jobs.data.compute_m_c">compute_m_c() (in module pofff.jobs.data)</a>
-</li>
-      <li><a href="pofff.visualization.everert.html#pofff.visualization.everert.Config">Config (class in pofff.visualization.everert)</a>
 </li>
   </ul></td>
   <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="pofff.visualization.everert.html#pofff.visualization.everert.Config">Config (class in pofff.visualization.everert)</a>
+</li>
       <li><a href="pofff.config.config.html#pofff.config.config.PofffConfig.constraints">constraints (pofff.config.config.PofffConfig attribute)</a>
 </li>
       <li><a href="pofff.visualization.everert.html#pofff.visualization.everert.copy_tree_contents">copy_tree_contents() (in module pofff.visualization.everert)</a>

docs/pofff.core.html

@@ -90,6 +90,7 @@ <h2>Submodules<a class="headerlink" href="#submodules" title="Link to this headi
 <div class="toctree-wrapper compound">
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="pofff.core.pofff.html">pofff.core.pofff module</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="pofff.core.pofff.html#pofff.core.pofff.check_cmdargs"><code class="docutils literal notranslate"><span class="pre">check_cmdargs()</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="pofff.core.pofff.html#pofff.core.pofff.cli_config"><code class="docutils literal notranslate"><span class="pre">cli_config()</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="pofff.core.pofff.html#pofff.core.pofff.generate_figures"><code class="docutils literal notranslate"><span class="pre">generate_figures()</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="pofff.core.pofff.html#pofff.core.pofff.main"><code class="docutils literal notranslate"><span class="pre">main()</span></code></a></li>

docs/pofff.core.pofff.html

@@ -87,6 +87,23 @@
   <section id="module-pofff.core.pofff">
 <span id="pofff-core-pofff-module"></span><h1>pofff.core.pofff module<a class="headerlink" href="#module-pofff.core.pofff" title="Link to this heading"></a></h1>
 <p>Main entry script for pofff.</p>
+<dl class="py function">
+<dt class="sig sig-object py" id="pofff.core.pofff.check_cmdargs">
+<span class="sig-prename descclassname"><span class="pre">pofff.core.pofff.</span></span><span class="sig-name descname"><span class="pre">check_cmdargs</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cmdargs</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Namespace</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="headerlink" href="#pofff.core.pofff.check_cmdargs" title="Link to this definition"></a></dt>
+<dd><p>Validate command-line arguments and incompatible operations.</p>
+<p>The checks cover input and output paths, evaluation times, saturation and
+concentration thresholds, options ignored by specialized workflows, and
+combinations that do not result in any operation.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters<span class="colon">:</span></dt>
+<dd class="field-odd"><p><strong>cmdargs</strong> – Parsed arguments returned by <a class="reference internal" href="#pofff.core.pofff.parse_args" title="pofff.core.pofff.parse_args"><code class="xref py py-func docutils literal notranslate"><span class="pre">parse_args()</span></code></a>.</p>
+</dd>
+<dt class="field-even">Raises<span class="colon">:</span></dt>
+<dd class="field-even"><p><strong>SystemExit</strong> – If an argument is invalid or an incompatible combination is requested.</p>
+</dd>
+</dl>
+</dd></dl>
+
 <dl class="py function">
 <dt class="sig sig-object py" id="pofff.core.pofff.cli_config">
 <span class="sig-prename descclassname"><span class="pre">pofff.core.pofff.</span></span><span class="sig-name descname"><span class="pre">cli_config</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Namespace</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">pofff_path</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Path</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="pofff.config.config.html#pofff.config.config.CliConfig" title="pofff.config.config.CliConfig"><span class="pre">CliConfig</span></a></span></span><a class="headerlink" href="#pofff.core.pofff.cli_config" title="Link to this definition"></a></dt>
@@ -101,13 +118,13 @@
 
 <dl class="py function">
 <dt class="sig sig-object py" id="pofff.core.pofff.main">
-<span class="sig-prename descclassname"><span class="pre">pofff.core.pofff.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="headerlink" href="#pofff.core.pofff.main" title="Link to this definition"></a></dt>
+<span class="sig-prename descclassname"><span class="pre">pofff.core.pofff.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">argv</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="headerlink" href="#pofff.core.pofff.main" title="Link to this definition"></a></dt>
 <dd><p>Main pofff execution routine.</p>
 </dd></dl>
 
 <dl class="py function">
 <dt class="sig sig-object py" id="pofff.core.pofff.parse_args">
-<span class="sig-prename descclassname"><span class="pre">pofff.core.pofff.</span></span><span class="sig-name descname"><span class="pre">parse_args</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pofff.core.pofff.parse_args" title="Link to this definition"></a></dt>
+<span class="sig-prename descclassname"><span class="pre">pofff.core.pofff.</span></span><span class="sig-name descname"><span class="pre">parse_args</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">argv</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Namespace</span></span></span><a class="headerlink" href="#pofff.core.pofff.parse_args" title="Link to this definition"></a></dt>
 <dd><p>Define and parse command-line arguments.</p>
 </dd></dl>
 

docs/pofff.html

@@ -103,6 +103,7 @@ <h2>Subpackages<a class="headerlink" href="#subpackages" title="Link to this hea
 <li class="toctree-l1"><a class="reference internal" href="pofff.core.html">pofff.core package</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="pofff.core.html#submodules">Submodules</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="pofff.core.pofff.html">pofff.core.pofff module</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="pofff.core.pofff.html#pofff.core.pofff.check_cmdargs"><code class="docutils literal notranslate"><span class="pre">check_cmdargs()</span></code></a></li>
 <li class="toctree-l4"><a class="reference internal" href="pofff.core.pofff.html#pofff.core.pofff.cli_config"><code class="docutils literal notranslate"><span class="pre">cli_config()</span></code></a></li>
 <li class="toctree-l4"><a class="reference internal" href="pofff.core.pofff.html#pofff.core.pofff.generate_figures"><code class="docutils literal notranslate"><span class="pre">generate_figures()</span></code></a></li>
 <li class="toctree-l4"><a class="reference internal" href="pofff.core.pofff.html#pofff.core.pofff.main"><code class="docutils literal notranslate"><span class="pre">main()</span></code></a></li>