Improving the code documentation

README.md

@@ -7,7 +7,7 @@
 
 <img src="docs/text/figs/animationspe11a.gif" width="830" height="360">
 
-This repository contains scripts to set up a workflow in python for the three cases in the SPE11 project.
+This repository contains scripts to set up a workflow in python for the three cases in the [_SPE11 project_](https://www.spe.org/en/csp/).
 Here we use the [_OPM-Flow_](https://opm-project.org/?page_id=19) simulator.
 
 ## Installation
@@ -33,7 +33,7 @@ pip install -e .
 pip install -r dev-requirements.txt
 ``` 
 
-See the [_CI.yml_](https://github.com/OPM/pyopmspe11/blob/main/.github/workflows/CI.yml) script  for installation of OPM Flow (binary packages) and the pyopmspe11 package. If you are a Linux user (including the windows subsystem for Linux), then you could try to build Flow from the master branches with mpi support, by running the script `./build_opm-flow_mpi.bash`, which in turn should build flow in the folder ./build/opm-simulators/bin/flow. 
+See the [_CI.yml_](https://github.com/OPM/pyopmspe11/blob/main/.github/workflows/CI.yml) script  for installation of OPM Flow (binary packages) and the pyopmspe11 package. If you are a Linux user (including the Windows subsystem for Linux), then you could try to build Flow from the master branches with mpi support, by running the script `./build_opm-flow_mpi.bash`, which in turn should build flow in the folder ./build/opm-simulators/bin/flow. 
 
 For macOS users with the latest chips (M1/M2, guessing also M3?), the resdata Python package might not available via pip install, depending on the Python version (e.g., it is not found using Python 3.9, but it is installed using Python 3.10). If you face this issue, then before installation, remove resdata from the `requirements.txt`, then proceed with the Python requirements installation, install the OPM Flow dependencies (using macports or brew), and once inside the vpyopmspe11 Python environment, run the `./build_opm-flow_macOS.bash`, and deactivate and activate the virtual environment (this script builds OPM Flow as well as the opm Python package, and it exports the required PYTHONPATH).
 

dev-requirements.txt

@@ -1,4 +1,5 @@
 black
+numpydoc
 mypy
 pylint
 pytest-cov

docs/_sources/introduction.rst.txt

@@ -5,20 +5,21 @@ Introduction
 .. image:: ./figs/animationspe11a.gif
 
 This documentation describes the content of the **pyopmspe11** package.
-The numerical studies are performed using the `Flow <https://opm-project.org/?page_id=19>`_ simulator. 
+The numerical studies are performed using the `OPM Flow simulator <https://opm-project.org/?page_id=19>`_. 
 
 Concept
 -------
-Simplified and flexible framework for the three cases in the SPE Comparative Solution Project
+Simplified and flexible framework for the three cases in the `SPE Comparative Solution Project <https://www.spe.org/en/csp/>`_
 via a :doc:`configuration file <./configuration_file>`:
 
 - Set the path to the OPM Flow simulator and simulator flags.
-- Set the grid type (cartesian, tensor, or corner-point grid) and the number of cells.
+- Set the grid type (Cartesian, tensor, or corner-point grid) and the number of cells.
 - Set the rock and fluid properties.
-- Set the well or sources locations and injection schedule.
-- After execution. generates the data in the same format as requested in the benchmark.
-- In addition, generates .png figures for quick inspection.
-- Also, generates figures for comparison between runs (i.e., to assess sensitivities).  
+- Set the wells or sources locations and define the injection schedule.
+- Select the functionality (e.g., generate only the input decks, run the whole framework).
+- The framework generates the data in the same format as requested in the benchmark.
+- In addition, it generates .png figures for quick inspection of the results.
+- Also, it generates figures for comparison between runs (i.e., to assess sensitivities).  
 
 Overview
 --------

docs/introduction.html

@@ -89,19 +89,20 @@
 <h1>Introduction<a class="headerlink" href="#introduction" title="Link to this heading"></a></h1>
 <img alt="_images/animationspe11a.gif" src="_images/animationspe11a.gif" />
 <p>This documentation describes the content of the <strong>pyopmspe11</strong> package.
-The numerical studies are performed using the <a class="reference external" href="https://opm-project.org/?page_id=19">Flow</a> simulator.</p>
+The numerical studies are performed using the <a class="reference external" href="https://opm-project.org/?page_id=19">OPM Flow simulator</a>.</p>
 <section id="concept">
 <h2>Concept<a class="headerlink" href="#concept" title="Link to this heading"></a></h2>
-<p>Simplified and flexible framework for the three cases in the SPE Comparative Solution Project
+<p>Simplified and flexible framework for the three cases in the <a class="reference external" href="https://www.spe.org/en/csp/">SPE Comparative Solution Project</a>
 via a <a class="reference internal" href="configuration_file.html"><span class="doc">configuration file</span></a>:</p>
 <ul class="simple">
 <li><p>Set the path to the OPM Flow simulator and simulator flags.</p></li>
-<li><p>Set the grid type (cartesian, tensor, or corner-point grid) and the number of cells.</p></li>
+<li><p>Set the grid type (Cartesian, tensor, or corner-point grid) and the number of cells.</p></li>
 <li><p>Set the rock and fluid properties.</p></li>
-<li><p>Set the well or sources locations and injection schedule.</p></li>
-<li><p>After execution. generates the data in the same format as requested in the benchmark.</p></li>
-<li><p>In addition, generates .png figures for quick inspection.</p></li>
-<li><p>Also, generates figures for comparison between runs (i.e., to assess sensitivities).</p></li>
+<li><p>Set the wells or sources locations and define the injection schedule.</p></li>
+<li><p>Select the functionality (e.g., generate only the input decks, run the whole framework).</p></li>
+<li><p>The framework generates the data in the same format as requested in the benchmark.</p></li>
+<li><p>In addition, it generates .png figures for quick inspection of the results.</p></li>
+<li><p>Also, it generates figures for comparison between runs (i.e., to assess sensitivities).</p></li>
 </ul>
 </section>
 <section id="overview">

docs/pyopmspe11.core.pyopmspe11.html

@@ -85,7 +85,7 @@
 
   <section id="module-pyopmspe11.core.pyopmspe11">
 <span id="pyopmspe11-core-pyopmspe11-module"></span><h1>pyopmspe11.core.pyopmspe11 module<a class="headerlink" href="#module-pyopmspe11.core.pyopmspe11" title="Link to this heading"></a></h1>
-<p>Main script</p>
+<p>Main script for pyopmspe11</p>
 <dl class="py function">
 <dt class="sig sig-object py" id="pyopmspe11.core.pyopmspe11.load_parser">
 <span class="sig-prename descclassname"><span class="pre">pyopmspe11.core.pyopmspe11.</span></span><span class="sig-name descname"><span class="pre">load_parser</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pyopmspe11.core.pyopmspe11.load_parser" title="Link to this definition"></a></dt>
@@ -101,7 +101,7 @@
 <dl class="py function">
 <dt class="sig sig-object py" id="pyopmspe11.core.pyopmspe11.pyopmspe11">
 <span class="sig-prename descclassname"><span class="pre">pyopmspe11.core.pyopmspe11.</span></span><span class="sig-name descname"><span class="pre">pyopmspe11</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pyopmspe11.core.pyopmspe11.pyopmspe11" title="Link to this definition"></a></dt>
-<dd><p>Main function</p>
+<dd><p>Main function for the pyopmspe11 executable</p>
 </dd></dl>
 
 </section>

docs/pyopmspe11.utils.inputvalues.html

@@ -89,44 +89,50 @@
 <dl class="py function">
 <dt class="sig sig-object py" id="pyopmspe11.utils.inputvalues.check_deck">
 <span class="sig-prename descclassname"><span class="pre">pyopmspe11.utils.inputvalues.</span></span><span class="sig-name descname"><span class="pre">check_deck</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dic</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyopmspe11.utils.inputvalues.check_deck" title="Link to this definition"></a></dt>
-<dd><p>Write unsupported features to the terminal if flow from release is used</p>
+<dd><p>Write unsupported features to the terminal if Flow from release is used</p>
+<dl class="simple">
+<dt>Args:</dt><dd><p>dic (dict): Global dictionary</p>
+</dd>
+<dt>Returns:</dt><dd><p>dic (dict): Modified global dictionary</p>
+</dd>
+</dl>
 </dd></dl>
 
 <dl class="py function">
 <dt class="sig sig-object py" id="pyopmspe11.utils.inputvalues.process_input">
 <span class="sig-prename descclassname"><span class="pre">pyopmspe11.utils.inputvalues.</span></span><span class="sig-name descname"><span class="pre">process_input</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dic</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">in_file</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyopmspe11.utils.inputvalues.process_input" title="Link to this definition"></a></dt>
-<dd><p>Function to process the input file</p>
-<dl class="simple">
-<dt>Args:</dt><dd><p>dic (dict): Global dictionary with required parameters
-in_file (str): Name of the input text file</p>
+<dd><p>Process the configuration file</p>
+<dl>
+<dt>Args:</dt><dd><p>dic (dict): Global dictionary</p>
+<p>in_file (str): Name of the input text file</p>
 </dd>
-<dt>Returns:</dt><dd><p>dic (dict): Global dictionary with new added parameters</p>
+<dt>Returns:</dt><dd><p>dic (dict): Modified global dictionary</p>
 </dd>
 </dl>
 </dd></dl>
 
 <dl class="py function">
 <dt class="sig sig-object py" id="pyopmspe11.utils.inputvalues.readthefirstpart">
 <span class="sig-prename descclassname"><span class="pre">pyopmspe11.utils.inputvalues.</span></span><span class="sig-name descname"><span class="pre">readthefirstpart</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lol</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dic</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyopmspe11.utils.inputvalues.readthefirstpart" title="Link to this definition"></a></dt>
-<dd><p>Function to process the lines from the flow executable and model parameters</p>
-<dl class="simple">
-<dt>Args:</dt><dd><p>lol (list): List of lines read from the input file
-dic (dict): Global dictionary with required parameters</p>
+<dd><p>Process the lines from the flow executable and model parameters</p>
+<dl>
+<dt>Args:</dt><dd><p>lol (list): List of lines read from the input file</p>
+<p>dic (dict): Global dictionary</p>
 </dd>
-<dt>Returns:</dt><dd><p>dic (dict): Global dictionary with new added parameters</p>
+<dt>Returns:</dt><dd><p>dic (dict): Modified global dictionary</p>
 </dd>
 </dl>
 </dd></dl>
 
 <dl class="py function">
 <dt class="sig sig-object py" id="pyopmspe11.utils.inputvalues.readthesecondpart">
 <span class="sig-prename descclassname"><span class="pre">pyopmspe11.utils.inputvalues.</span></span><span class="sig-name descname"><span class="pre">readthesecondpart</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lol</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dic</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyopmspe11.utils.inputvalues.readthesecondpart" title="Link to this definition"></a></dt>
-<dd><p>Function to process the lines from the saturation functions until the end</p>
-<dl class="simple">
-<dt>Args:</dt><dd><p>lol (list): List of lines read from the input file
-dic (dict): Global dictionary with required parameters</p>
+<dd><p>Process the lines from the saturation functions until the end</p>
+<dl>
+<dt>Args:</dt><dd><p>lol (list): List of lines read from the input file</p>
+<p>dic (dict): Global dictionary</p>
 </dd>
-<dt>Returns:</dt><dd><p>dic (dict): Global dictionary with new added parameters</p>
+<dt>Returns:</dt><dd><p>dic (dict): Modified global dictionary</p>
 </dd>
 </dl>
 </dd></dl>