Merge pull request #99 from daavid00/docUpdates

Updating the docs

CONTRIBUTING.md

@@ -17,7 +17,7 @@ Contributions are more than welcome using the fork and pull request approach 
     1. **pylint src/ tests/** (this analyses the code, and might rise issues that need to be fixed before the pull request)
     1. **mypy --ignore-missing-imports src/ tests/** (this is a static checker, and might rise issues that need to be fixed before the pull request)
     1. **pytest --cov=pyopmspe11 --cov-report term-missing tests/** (this runs locally the tests, and might rise issues that need to be fixed before the pull request)
-    1. **pushd docs & make html** (this generates the documentation, and might rise issues that need to be fixed before the pull request; if the build succeeds and if the contribution changes the documentation, then copy all content from the docs/_build/html/ folder and replace the files in the [_docs_](https://github.com/cssr-tools/pyopmspe11/tree/main/docs) folder)
+    1. **pushd docs & make html** (this generates the documentation, and might rise issues that need to be fixed before the pull request; if the build succeeds and if the contribution changes the documentation, then delete all content from the [_docs_](https://github.com/cssr-tools/pyopmspe11/tree/main/docs) folder except [_Makefile_](https://github.com/OPM/pyopmspe11/blob/main/docs/Makefile), [_text_](https://github.com/OPM/pyopmspe11/blob/main/docs/text), and [_.nojekyll_](https://github.com/OPM/pyopmspe11/blob/main/docs/.nojekyll), after copy all contents from the docs/_build/html/ folder, and finally paste them in the [_docs_](https://github.com/cssr-tools/pyopmspe11/tree/main/docs) folder)
     * Tip: See the [_CI.yml_](https://github.com/cssr-tools/pyopmspe11/blob/main/.github/workflows/CI.yml) script and the [_Actions_](https://github.com/cssr-tools/pyopmspe11/actions) for installation of pyopmspe11, OPM Flow (binary packages), and dependencies, as well as the execution of the six previous steps in Ubuntu 24.10.
 1. Squash your commits into a single commit (see this [_nice tutorial_](https://gist.github.com/lpranam/4ae996b0a4bc37448dc80356efbca7fa) if you are not familiar with this)
 1. Push your commit and make a pull request

docs/_sources/about.rst.txt

@@ -7,5 +7,9 @@ About pyopmspe11
 
 This **pyopmspe11** package is being funded by the `HPC Simulation Software for the Gigatonne Storage Challenge project <https://www.norceresearch.no/en/projects/hpc-simulation-software-for-the-gigatonne-storage-challenge>`_ 
 [project number 622059] and `Center for Sustainable Subsurface Resources (CSSR) <https://cssr.no>`_ [project no. 331841].
-This is work in progress. `Here <https://www.spe.org/en/csp/>`_ is the link to the spe11 details.
-Contributions are more than welcome using the fork and pull request approach.
+
+`Here <https://www.spe.org/en/csp/>`_ is the link to the spe11 details.
+
+Contributions are more than welcome using the fork and pull request approach.
+
+For a new feature, please request this by raising an issue.

docs/_sources/benchmark.rst.txt

@@ -145,9 +145,9 @@ Spatial maps
 
     .. code-block:: bash
 
-        plopm -v xco2l -i 'r1_Cart_1cm/flow/R1_CART_1CM r2_Cart_1cm_capmax2500Pa/flow/R2_CART_1CM_CAPMAX2500PA r3_cp_1cmish_capmax2500Pa/flow/R3_CP_1CMISH_CAPMAX2500PA r4_Cart_1mm_capmax2500Pa/flow/R4_CART_1MM_CAPMAX2500PA' -dpi 2000 -c cet_diverging_protanopic_deuteranopic_bwy_60_95_c32 -cnum 3 -xlnum 8 -clabel 'SPE11A: CO$_2$ mass fraction (liquid phase) after 1 day' -d 16,6.5 -t "r1 Cart 1cm  r2 Cart 1cm capmax 2500 Pa  r3 cp 1cmish capmax 2500 Pa  r4 Cart 1mm capmax 2500 Pa" -yunits cm -xunits cm -yformat .0f -xformat .0f -r 29 -save massfracta -cformat .2e -mask satnum -maskthr 7e-5 -suptitle 0 -subfigs 2,2 -cbsfax 0.35,0.97,0.3,0.02
-        plopm -v xco2l -i "r1_Cart_10m/flow/R1_CART_10M r2_cp_10mish/flow/R2_CP_10MISH r3_cp_10mish_convective/flow/R3_CP_10MISH_CONVECTIVE r4_Cart_1m/flow/R4_CART_1M" -dpi 2000 -c cet_diverging_protanopic_deuteranopic_bwy_60_95_c32 -cnum 3 -xlnum 8 -clabel 'SPE11B: CO$_2$ mass fraction (liquid phase) after 500 years' -d 16,3 -t "r1 Cart 10m  r2 cp 10mish  r3 cp 10mish convective  r4 Cart 1m" -yunits km -xunits km -yformat .1f -xformat .1f -r 98 -save massfractb -cformat .2e -mask satnum -maskthr 5e-3 -suptitle 0 -subfigs 2,2 -cbsfax 0.35,0.97,0.3,0.02
-        plopm -v xco2l -i "r1_Cart_50m-50m-10m/flow/R1_CART_50M-50M-10M r2_cp_50m-50m-8mish/flow/R2_CP_50M-50M-8MISH r3_cp_50m-50m-8mish_convective/flow/R3_CP_50M-50M-8MISH_CONVECTIVE r4_cp_8m-8mish-8mish/flow/R4_CP_8M-8MISH-8MISH" -dpi 2000 -c cet_diverging_protanopic_deuteranopic_bwy_60_95_c32 -cnum 3 -xlnum 8 -clabel 'SPE11C: CO$_2$ mass fraction (liquid phase) after 1000 years (y=2.5 [km])' -d 16,3 -t "r1 Cart [50m,50m,10m]  r2 cp [50m,50m,8mish]  r3 cp [50m,50m,8mish] convective  r4 cp [8m,8mish,8mish]" -yunits km -xunits km -yformat .1f -xformat .1f -r 27 -save massfractc -cformat .2e -mask satnum -maskthr 1e-4 -suptitle 0 -subfigs 2,2 -cbsfax 0.30,0.97,0.4,0.02 -s ',51, ,51, ,51, ,304,' -u opm
+        plopm -v xco2l -i 'r1_Cart_1cm/flow/R1_CART_1CM r2_Cart_1cm_capmax2500Pa/flow/R2_CART_1CM_CAPMAX2500PA r3_cp_1cmish_capmax2500Pa/flow/R3_CP_1CMISH_CAPMAX2500PA r4_Cart_1mm_capmax2500Pa/flow/R4_CART_1MM_CAPMAX2500PA' -dpi 300 -c cet_diverging_protanopic_deuteranopic_bwy_60_95_c32 -cnum 3 -xlnum 8 -clabel 'SPE11A: CO$_2$ mass fraction (liquid phase) after 1 day' -d 16,6.5 -t "r1 Cart 1cm  r2 Cart 1cm capmax 2500 Pa  r3 cp 1cmish capmax 2500 Pa  r4 Cart 1mm capmax 2500 Pa" -yunits cm -xunits cm -yformat .0f -xformat .0f -r 29 -save massfracta -cformat .2e -mask satnum -maskthr 7e-5 -suptitle 0 -subfigs 2,2 -cbsfax 0.35,0.97,0.3,0.02
+        plopm -v xco2l -i "r1_Cart_10m/flow/R1_CART_10M r2_cp_10mish/flow/R2_CP_10MISH r3_cp_10mish_convective/flow/R3_CP_10MISH_CONVECTIVE r4_Cart_1m/flow/R4_CART_1M" -dpi 300 -c cet_diverging_protanopic_deuteranopic_bwy_60_95_c32 -cnum 3 -xlnum 8 -clabel 'SPE11B: CO$_2$ mass fraction (liquid phase) after 500 years' -d 16,3 -t "r1 Cart 10m  r2 cp 10mish  r3 cp 10mish convective  r4 Cart 1m" -yunits km -xunits km -yformat .1f -xformat .1f -r 98 -save massfractb -cformat .2e -mask satnum -maskthr 5e-3 -suptitle 0 -subfigs 2,2 -cbsfax 0.35,0.97,0.3,0.02
+        plopm -v xco2l -i "r1_Cart_50m-50m-10m/flow/R1_CART_50M-50M-10M r2_cp_50m-50m-8mish/flow/R2_CP_50M-50M-8MISH r3_cp_50m-50m-8mish_convective/flow/R3_CP_50M-50M-8MISH_CONVECTIVE r4_cp_8m-8mish-8mish/flow/R4_CP_8M-8MISH-8MISH" -dpi 300 -c cet_diverging_protanopic_deuteranopic_bwy_60_95_c32 -cnum 3 -xlnum 8 -clabel 'SPE11C: CO$_2$ mass fraction (liquid phase) after 1000 years (y=2.5 [km])' -d 16,3 -t "r1 Cart [50m,50m,10m]  r2 cp [50m,50m,8mish]  r3 cp [50m,50m,8mish] convective  r4 cp [8m,8mish,8mish]" -yunits km -xunits km -yformat .1f -xformat .1f -r 27 -save massfractc -cformat .2e -mask satnum -maskthr 1e-4 -suptitle 0 -subfigs 2,2 -cbsfax 0.30,0.97,0.4,0.02 -s ',51, ,51, ,51, ,304,' -u opm
 
 .. tip::
     You can install `plopm <https://github.com/cssr-tools/plopm>`_ by executing in the terminal: pip install git+https://github.com/cssr-tools/plopm.git.

docs/_sources/contributing.rst.txt

@@ -0,0 +1,52 @@
+************
+Contributing
+************
+
+Contributions are more than welcome using the fork and pull request approach 🙂 (if you are not familiar with this approach, 
+please visit `GitHub Docs PRs <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests>`_ for an extended 
+documentation about collaborating with pull request; also, looking at previous merged pull requests helps to get familiar with this).
+
+============
+Ground Rules 
+============
+
+- We use Black code formatting
+- We use Pylint
+- We document our code
+
+==========================
+Contribute to the software
+==========================
+
+#. Work on your own fork of the main repo
+#. In the main repo execute:
+
+    #. **pip install -r dev-requirements.txt** (this installs the `dev-requirements.txt <https://github.com/cssr-tools/pyopmspe11/blob/main/dev-requirements.txt>`_; in addition, both opm Python and LaTeX are required, then for not macOs users run **pip install opm** and **sudo apt-get install texlive-fonts-recommended texlive-fonts-extra dvipng cm-super**, or else follow the instructions in `macOS installation <https://cssr-tools.github.io/pyopmspe11/installation.html#source-build-in-macos>`_)
+    #. **black src/ tests/** (this formats the code)
+    #. **pylint src/ tests/** (this analyses the code, and might rise issues that need to be fixed before the pull request)
+    #. **mypy --ignore-missing-imports src/ tests/** (this is a static checker, and might rise issues that need to be fixed before the pull request)
+    #. **pytest --cov=pyopmspe11 --cov-report term-missing tests/** (this runs locally the tests, and might rise issues that need to be fixed before the pull request; to save the files, add the flag **--basetemp=test_outputs**)
+    #. **pushd docs & make html** (this generates the documentation, and might rise issues that need to be fixed before the pull request; if the build succeeds and if the contribution changes the documentation, then delete all content from the `docs <https://github.com/cssr-tools/pyopmspe11/tree/main/docs>`_ folder except `Makefile <https://github.com/OPM/pyopmspe11/blob/main/docs/Makefile>`_, `text <https://github.com/OPM/pyopmspe11/blob/main/docs/text>`_, and `.nojekyll <https://github.com/OPM/pyopmspe11/blob/main/docs/.nojekyll>`_, after copy all contents from the docs/_build/html/ folder, and finally paste them in the `docs <https://github.com/cssr-tools/pyopmspe11/tree/main/docs>`_ folder)
+
+    .. tip::
+        See the `CI.yml <https://github.com/cssr-tools/pyopmspe11/blob/main/.github/workflows/CI.yml>`_ script and the `Actions <https://github.com/cssr-tools/pyopmspe11/actions>`_ for installation of pyopmspe11, OPM Flow (binary packages), and dependencies, as well as the execution of the six previous steps in Ubuntu 24.10.
+
+#. Squash your commits into a single commit (see this `nice tutorial <https://gist.github.com/lpranam/4ae996b0a4bc37448dc80356efbca7fa>`_ if you are not familiar with this)
+#. Push your commit and make a pull request
+#. The maintainers will review the pull request, and if the contribution is accepted, then it will be merge to the main repo
+
+============================
+Reporting issues or problems
+============================
+
+#.  Issues or problems can be raised by creating a `new issue <https://github.com/cssr-tools/pyopmspe11/issues>`_ in the repository GitHub page (if you are not familiar with this approach, please visit `GitHub Docs Issues <https://docs.github.com/en/issues/tracking-your-work-with-issues>`_).
+#.  We will try to answer as soon as possible, but also any user is more than welcome to answer.
+
+============
+Seek support
+============
+
+#.  The preferred approach to seek support is to raise an Issue as described in the previous lines.
+#.  We will try to answer as soon as possible, but also any user is more than welcome to answer.
+
+- An alternative approach is to send an email to any of the `mantainers <https://github.com/cssr-tools/pyopmspe11/blob/main/pyproject.toml>`_.

docs/_sources/examples.rst.txt

@@ -7,14 +7,15 @@ Hello world
 ===========
 
 The `examples/hello_world <https://github.com/OPM/pyopmspe11/blob/main/examples/hello_world>`_ folder contains configuration files
-with low grid resolution and shorter injetion times (for initial testing of the framework). For example, by executing:
+with low grid resolution and shorter injection times (for initial testing of the framework). For example, by executing:
 
 .. code-block:: bash
 
     pyopmspe11 -i spe11b.txt -o spe11b -m all -g all -t 5 -r 50,1,15 -w 1
 
-The following is one of the figures generated related to the CO2 mass in the domain over time (i.e., the simulations results from
-the corner-point grid mapped to the equidistance reporting grid of 50 x 15 as defined by the -r flag):
+The following is the figure `spe11b_tco2_2Dmaps`, which shows the CO2 mass in the domain over time (i.e., the simulations results from
+the corner-point grid mapped to the equidistance reporting grid of 50 x 15 as defined by the -r flag). You can
+compare your example results to this figure to evaluate if your example ran correctly:
 
 .. figure:: figs/spe11b_tco2_2Dmaps.png
 
@@ -155,4 +156,4 @@ SPE11C
 
 .. figure:: figs/spe11c_sparse_data_new.png
 
-.. image:: ./figs/animationspe11c.gif
+.. image:: ./figs/animationspe11c.gif

docs/_sources/index.rst.txt

@@ -13,6 +13,7 @@ Welcome to pyopmspe11's documentation!
    benchmark
    api
    output_folder
+   contributing
    related
    about
 

docs/_sources/installation.rst.txt

@@ -2,16 +2,22 @@
 Installation
 ============
 
+The following steps work installing the dependencies in Linux via apt-get or in macOS using brew or macports.
+While using packages managers such as Anaconda, Miniforge, or Mamba might work, these are not tested.
+In addition, the current supported Python versions for macOS are 3.10 to 3.12 and for Linux 3.8 to 3.12.
+We will update the documentation when Python3.13 is supported (e.g., the resdata Python package is not yet available
+via pip install in Python 3.13).
+
 Python package
 --------------
 
-To install the **pyopmspe11** executable in an existing Python environment: 
+To install the **pyopmspe11** executable from the development version: 
 
 .. code-block:: bash
 
     pip install git+https://github.com/opm/pyopmspe11.git
 
-If you are interested in modifying the source code, then you can clone the repository and 
+If you are interested in a specific version (e.g., v2024.04) or in modifying the source code, then you can clone the repository and 
 install the Python requirements in a virtual environment with the following commands:
 
 .. code-block:: console
@@ -20,7 +26,9 @@ install the Python requirements in a virtual environment with the following comm
     git clone https://github.com/opm/pyopmspe11.git
     # Get inside the folder
     cd pyopmspe11
-    # Create virtual environment
+    # For a specific version (e.g., v2024.04), or skip this step (i.e., edge version)
+    git checkout v2024.04
+    # Create virtual environment (to specific Python, python3.12 -m venv vpyopmspe11)
     python3 -m venv vpyopmspe11
     # Activate virtual environment
     source vpyopmspe11/bin/activate
@@ -31,27 +39,39 @@ install the Python requirements in a virtual environment with the following comm
     # For contributions/testing/linting, install the dev-requirements
     pip install -r dev-requirements.txt
 
+.. tip::
+
+    Typing **git tag -l** writes all available specific versions.
+
 .. note::
 
-    Regarding the reading of OPM Flow output files (i.e., .EGRID, .INIT, .UNRST), it is possible to use the OPM python library instead of resdata (e.g., it seems the OPM Python library 
-    is faster than resdata to read large simulation files). For not macOS users, to install the Python OPM package, execute in the terminal **pip install opm**.
-    For macOS, see :ref:`macOS`.
+    For not macOS users, to install the Python opm package (this is an alternative
+    to `resdata <https://github.com/equinor/resdata>`_, both are use to read OPM output files; while resdata is easier to
+    install in macOS, opm seems to be faster), execute in the terminal
+
+    **pip install opm**
+
+    For not macOS users, to install the dependencies used for the figure's LaTeX formatting, execute 
+
+    **sudo apt-get install texlive-fonts-recommended texlive-fonts-extra dvipng cm-super**
+
+    For macOS users, see :ref:`macOS`.
 
 OPM Flow
 --------
 You also need to install:
 
-* OPM Flow (https://opm-project.org, Release 2024.04 or current master branches)
+* OPM Flow (https://opm-project.org, Release 2024.10 or current master branches)
 
 .. tip::
 
     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 in Linux. 
+    for installation of OPM Flow (binary packages) and the pyopmspe11 package in Ubuntu. 
 
 Source build in Linux/Windows
 +++++++++++++++++++++++++++++
 If you are a Linux user (including the Windows subsystem for Linux), then you could try to build Flow (after installing the `prerequisites <https://opm-project.org/?page_id=239>`_) from the master branches with mpi support by running
-in the terminal the following lines (which in turn should build flow in the folder ./build/opm-simulators/bin/flow.): 
+in the terminal the following lines (which in turn should build flow in the folder ./build/opm-simulators/bin/flow): 
 
 .. code-block:: console
 
@@ -132,6 +152,8 @@ package (see the `prerequisites <https://opm-project.org/?page_id=239>`_, which
 
 This builds OPM Flow as well as the OPM Python library, and it exports the required PYTHONPATH. Then after execution, deactivate and activate the Python virtual environment.
 
-Regarding the resdata Python package, it might not be available depending on the Python version (e.g., it is not found using Python 3.9, but it is installed using Python 3.10).
-Then, it is recommended to use a Python version equal or higher than 3.10; otherwise, remove resdata from the requirements in the `pyproject.toml <https://github.com/opm/pyopmspe11/blob/main/pyproject.toml>`_,
-and when executing **pyopmspe11** always set the flag **-u opm** (resdata is the default package for reading the simulation files, see the :ref:`overview`).
+Regarding the resdata Python package, it might not be available depending on the Python version (e.g., it is not found using Python 3.9, but it is installed using Python 3.10). 
+Then, for macOS users, you need to use a Python version equal or higher than 3.10.
+
+For macOS, the LaTeX dependency can be installed from https://www.tug.org/mactex/. If after installation you still face an error due to LaTeX 
+when executing pyopmspe11, then add the flag **-l 0** to pyopmspe11.

docs/_sources/introduction.rst.txt

@@ -42,3 +42,5 @@ where
 -u  Using the 'opm' or 'resdata' python package ('resdata' by default).
 -w  Time interval for the sparse and performance data (spe11a [h]; spe11b/c [y]) ('0.1' by default).
 -c  Generate a common plot for the current folders for 'spe11a', 'spe11b', or 'spe11c' ('' by default).
+-s  Set to 1 to show Python warnings ('0' by default).
+-l  Set to 0 to not use LaTeX formatting ('1' by default).

docs/_sources/pyopmspe11.rst.txt

@@ -9,6 +9,7 @@ Subpackages
 
    pyopmspe11.core
    pyopmspe11.utils
+   pyopmspe11.visualization
 
 Module contents
 ---------------

docs/_sources/pyopmspe11.visualization.data.rst.txt

@@ -0,0 +1,8 @@
+pyopmspe11.visualization.data module
+====================================
+
+.. automodule:: pyopmspe11.visualization.data
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/_sources/pyopmspe11.visualization.plotting.rst.txt

@@ -0,0 +1,8 @@
+pyopmspe11.visualization.plotting module
+========================================
+
+.. automodule:: pyopmspe11.visualization.plotting
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/_sources/pyopmspe11.visualization.rst.txt

@@ -0,0 +1,20 @@
+pyopmspe11.visualization package
+================================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pyopmspe11.visualization.data
+   pyopmspe11.visualization.plotting
+
+Module contents
+---------------
+
+.. automodule:: pyopmspe11.visualization
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/_sources/related.rst.txt

@@ -37,7 +37,7 @@ expreccs
 .. image:: ./figs/expreccs.gif
     :scale: 50%
 
-`Expansion of ResourCes for CO2 Storage on the Horda Platform <https://github.com/cssr-tools/expreccs>`_.
+`A Python framework using OPM Flow to simulate regional and site reservoirs for CO2 storage <https://github.com/cssr-tools/expreccs>`_.
 
 *******
 ad-micp

docs/_static/basic.css

@@ -1,12 +1,5 @@
 /*
- * basic.css
- * ~~~~~~~~~
- *
  * Sphinx stylesheet -- basic theme.
- *
- * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 /* -- main layout ----------------------------------------------------------- */
@@ -115,15 +108,11 @@ img {
 /* -- search page ----------------------------------------------------------- */
 
 ul.search {
-    margin: 10px 0 0 20px;
-    padding: 0;
+    margin-top: 10px;
 }
 
 ul.search li {
-    padding: 5px 0 5px 20px;
-    background-image: url(file.png);
-    background-repeat: no-repeat;
-    background-position: 0 7px;
+    padding: 5px 0;
 }
 
 ul.search li a {