Updates before the v2024.10 release

.gitignore

@@ -163,24 +163,13 @@ cython_debug/
 .DS_Store
 
 # Tests
+examples/output
 examples/spe11b_fipnum_*,1,*_t5.png
 examples/spe11b_permx_*,1,*_t5.png
 examples/spe11b_permz_*,1,*_t5.png
 examples/spe11b_poro_*,1,*_t5.png
 examples/spe11b_porv_*,1,*_t5.png
 examples/spe11b_satnum_*,1,*_t5.png
-examples/spe11b_sgas_*,1,*_t4.png
-examples/spe11b_rsw_*,1,*_t5.png
-examples/spe11b_sgas_*,1,*_t5.png
-examples/subfigs_summary.png
-examples/spe11b_xco2l.gif
-examples/fgip.png
-examples/SPE11B-*.vtu
-examples/SPE11B.pvd
-examples/pres_diff.png
-examples/pres_incr.png
-examples/tco2m_alongx.png
-examples/tco2m_alongz.png
 tests/generic_deck
 
 # Python environment

CONTRIBUTING.md

@@ -1,16 +1,35 @@
 # Contributing
 
-Hola hola :).
-The following is a set of guidelines for contributing to plopm.
+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
 
-1. We use Black code formatting
-1. We use Pylint
-1. We document our code
+- We use Black code formatting
+- We use Pylint
+- We document our code
 
-## Pull Request Process
+## Contribute to the software
 
 1. Work on your own fork of the main repo
-1. Push your commits and make a pull request
-1. The changes are merged when your code has been approved
+1. In the main repo execute:
+    1. **pip install -r dev-requirements.txt** (this installs the [_dev-requirements.txt_](https://github.com/cssr-tools/plopm/blob/main/dev-requirements.txt))
+    1. **black src/ tests/** (this formats the code)
+    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=plopm --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/plopm/tree/main/docs) folder)
+    * Tip: See the [_CI.yml_](https://github.com/cssr-tools/plopm/blob/main/.github/workflows/CI.yml) script and the [_Actions_](https://github.com/cssr-tools/plopm/actions) for installation of plopm, 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
+1. 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
+
+1. Issues or problems can be raised by creating a [_new issue_](https://github.com/cssr-tools/plopm/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)).
+1. We will try to answer as soon as possible, but also any user is more than welcome to answer. 
+
+## Seek support
+
+1. The preferred approach to seek support is to raise an Issue as described in the previous lines.
+1. 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/plopm/blob/main/pyproject.toml). 

README.md

@@ -17,10 +17,10 @@ To install the _plopm_ executable in an existing Python environment:
 pip install git+https://github.com/cssr-tools/plopm.git
 ```
 
-If you are interested in modifying the source code, then you can clone the repository and install the Python requirements in a virtual environment with the following commands:
+If you are interested in a specific version (e.g., v2024.10) 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:
 
 ```bash
-# Clone the repo
+# Clone the repo (to get a specifc version, add the flag --branch, e.g., --branch v2024.10)
 git clone https://github.com/cssr-tools/plopm.git
 # Get inside the folder
 cd plopm
@@ -36,7 +36,7 @@ pip install -e .
 pip install -r dev-requirements.txt
 ``` 
 
-To use the conversion from OPM Flow output files (i.e., .EGRID, .INIT, .UNRST) to VTK (e.g, to use [_paraview_](https://www.paraview.org) for visualization/postprocessing), [_OPM Flow_](https://opm-project.org) is needed. Then see the [_installation_](https://cssr-tools.github.io/plopm/installation.html) for further details on installing binaries or building OPM Flow from the master branches in Linux, Windows, and macOS, as well as the opm Python package.
+To use the conversion from OPM Flow output files (i.e., .EGRID, .INIT, .UNRST) to VTK (e.g, to use [_paraview_](https://www.paraview.org) for visualization/postprocessing), [_OPM Flow_](https://opm-project.org) is needed. See the [_installation_](https://cssr-tools.github.io/plopm/installation.html) for further details on installing binaries or building OPM Flow from the master branches in Linux, Windows, and macOS, as well as the opm Python package and LaTeX dependencies. 
 
 ## Running plopm
 You can run _plopm_ as a single command line:
@@ -51,7 +51,7 @@ See the [_examples_](https://cssr-tools.github.io/plopm/examples.html) in the [_
 ## Citing
 If you would like to cite this repository:
 
-* Landa-Marbán, D. 2024. plopm: Quick generation of PNGs, GIFs, and VTKs from a OPM Flow type model. V2024.04. https://doi.org/10.5281/zenodo.13332415.
+* Landa-Marbán, D. 2024. plopm: Quick generation of PNGs, GIFs, and VTKs from a OPM Flow type model. v2024.04. https://doi.org/10.5281/zenodo.13332415.
 
 ## About plopm
 The _plopm_ 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) 

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/plopm/blob/main/dev-requirements.txt>`_)
+    #. **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=plopm --cov-report term-missing tests/** (this runs locally the tests, and might rise issues that need to be fixed before the pull request)
+    #. **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/plopm/tree/main/docs>`_ folder)
+
+    .. tip::
+        See the `CI.yml <https://github.com/cssr-tools/plopm/blob/main/.github/workflows/CI.yml>`_ script and the `Actions <https://github.com/cssr-tools/plopm/actions>`_ for installation of plopm, 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/plopm/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/plopm/blob/main/pyproject.toml>`_.

docs/_sources/index.rst.txt

@@ -10,6 +10,7 @@ Welcome to plopm's documentation!
    installation
    examples
    api
+   contributing
    related
    about
 

docs/_sources/installation.rst.txt

@@ -2,21 +2,24 @@
 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.
+
 Python package
 --------------
 
-To install the **plopm** executable in an existing Python environment: 
+To install the **plopm** executable from the development version in an existing Python environment: 
 
 .. code-block:: bash
 
     pip install git+https://github.com/cssr-tools/plopm.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.10) 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
 
-    # Clone the repo
+    # Clone the repo (to get a specifc version, add the flag --branch, e.g., --branch v2024.10)
     git clone https://github.com/cssr-tools/plopm.git
     # Get inside the folder
     cd plopm
@@ -33,20 +36,28 @@ install the Python requirements in a virtual environment with the following comm
 
 .. note::
 
-    For not macOS users, to install the Python opm package, execute in the terminal **pip install opm**.
-    In addition, to install the dependencies used for the figure's formatting, execute **sudo apt-get install texlive-fonts-recommended texlive-fonts-extra dvipng cm-super**.
-    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
 --------
 To use the convertion from OPM Flow output files (i.e., .EGRID, .INIT, .UNRST) to vtk, 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/cssr-tools/plopm/blob/main/.github/workflows/CI.yml>`_ script 
-    for installation of OPM Flow (binary packages) and the plopm package in Linux. 
+    for installation of OPM Flow (binary packages) and the plopm package in Ubuntu. 
 
 Source build in Linux/Windows
 +++++++++++++++++++++++++++++
@@ -136,5 +147,7 @@ package (see the `prerequisites <https://opm-project.org/?page_id=239>`_, which
 This builds OPM Flow as well as the opm Python package, 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/cssr-tools/plopm/blob/main/pyproject.toml>`_,
-and set the flag to use the opm Python package (see the :ref:`overview`).
+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 plopm, then  add the flag **-latex 0** to plopm.

docs/_sources/introduction.rst.txt

@@ -90,6 +90,8 @@ where
 -maskthr    Set the threshold for the variable to mask " "('1e-3' by default).
 -interval   Time for the frames in the GIF in milli second ('1000' by default).
 -loop       Set to 1 for infinity loop in the GIF ('0' by default).
+-warnings   Set to 1 to print warnings ('0' by default).
+-latex      Set to 0 to not use LaTeX formatting ('1' by default).
 
 .. tip::
 

docs/_sources/plopm.rst.txt

@@ -8,6 +8,7 @@ Subpackages
    :maxdepth: 4
 
    plopm.core
+   plopm.utils
 
 Module contents
 ---------------

docs/_sources/plopm.utils.initialization.rst.txt

@@ -0,0 +1,8 @@
+plopm.utils.initialization module
+=================================
+
+.. automodule:: plopm.utils.initialization
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/_sources/plopm.utils.mapping.rst.txt

@@ -0,0 +1,8 @@
+plopm.utils.mapping module
+==========================
+
+.. automodule:: plopm.utils.mapping
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/_sources/plopm.utils.readers.rst.txt

@@ -0,0 +1,8 @@
+plopm.utils.readers module
+==========================
+
+.. automodule:: plopm.utils.readers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/_sources/plopm.utils.rst.txt

@@ -0,0 +1,23 @@
+plopm.utils package
+===================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   plopm.utils.initialization
+   plopm.utils.mapping
+   plopm.utils.readers
+   plopm.utils.vtk
+   plopm.utils.write
+
+Module contents
+---------------
+
+.. automodule:: plopm.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/_sources/plopm.utils.vtk.rst.txt

@@ -0,0 +1,8 @@
+plopm.utils.vtk module
+======================
+
+.. automodule:: plopm.utils.vtk
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/_sources/plopm.utils.write.rst.txt

@@ -0,0 +1,8 @@
+plopm.utils.write module
+========================
+
+.. automodule:: plopm.utils.write
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/about.html

@@ -33,7 +33,7 @@
 
           <a href="index.html">
 
-              <img src="_static/permx_log.png" class="logo" alt="Logo"/>
+              <img src="_static/troll_faults.png" class="logo" alt="Logo"/>
           </a>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
@@ -48,6 +48,7 @@
 <li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">plopm Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="contributing.html">Contributing</a></li>
 <li class="toctree-l1"><a class="reference internal" href="related.html">Related</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">About plopm</a></li>
 </ul>

docs/api.html

@@ -34,7 +34,7 @@
 
           <a href="index.html">
 
-              <img src="_static/permx_log.png" class="logo" alt="Logo"/>
+              <img src="_static/troll_faults.png" class="logo" alt="Logo"/>
           </a>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
@@ -55,6 +55,7 @@
 </li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="contributing.html">Contributing</a></li>
 <li class="toctree-l1"><a class="reference internal" href="related.html">Related</a></li>
 <li class="toctree-l1"><a class="reference internal" href="about.html">About plopm</a></li>
 </ul>
@@ -98,6 +99,11 @@ <h2>plopm<a class="headerlink" href="#plopm" title="Link to this heading"></a
 <li class="toctree-l4"><a class="reference internal" href="plopm.core.html#module-plopm.core">Module contents</a></li>
 </ul>
 </li>
+<li class="toctree-l3"><a class="reference internal" href="plopm.utils.html">plopm.utils package</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="plopm.utils.html#submodules">Submodules</a></li>
+<li class="toctree-l4"><a class="reference internal" href="plopm.utils.html#module-plopm.utils">Module contents</a></li>
+</ul>
+</li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="plopm.html#module-plopm">Module contents</a></li>