Merge pull request #12 from daavid00/dev

Updating to toml and documentation

.github/workflows/CI.yml

@@ -48,9 +48,9 @@ jobs:
         
     - name: Check code style and linting 
       run: |
-        black --check src/ tests/ setup.py
-        pylint src/ tests/ setup.py
-        mypy --ignore-missing-imports src/ tests/ setup.py
+        black --check src/ tests/
+        pylint src/ tests/
+        mypy --ignore-missing-imports src/ tests/
       
     - name: Run the tests
       run: |

README.md

@@ -1,5 +1,5 @@
 [![Build Status](https://github.com/cssr-tools/plopm/actions/workflows/CI.yml/badge.svg)](https://github.com/cssr-tools/plopm/actions/workflows/CI.yml)
-<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.8%20|%203.9%20|%203.10%20|%203.11%20|%203.12-blue.svg"></a>
+<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.8%20to%203.12-blue.svg"></a>
 [![Code style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 <img src="docs/text/figs/plopm.png" width="1100" height="300">
@@ -16,8 +16,7 @@ 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 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
@@ -36,6 +35,8 @@ 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.
+
 ## Running plopm
 You can run _plopm_ as a single command line:
 ```
@@ -45,3 +46,9 @@ Run `plopm --help` to see all possible command line argument options.
 
 ## Getting started
 See the [_examples_](https://cssr-tools.github.io/plopm/examples.html) in the [_documentation_](https://cssr-tools.github.io/plopm/introduction.html).
+
+## 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) 
+[project no. 331841].
+This is work in progress.
+Contributions are more than welcome using the fork and pull request approach.

docs/_sources/about.rst.txt

@@ -5,6 +5,7 @@ About plopm
 .. image:: ./figs/about.png
     :scale: 25%
 
-The **plopm** tool for plotting OPM Flow geological models is being funded by the `Center for Sustainable Subsurface Resources (CSSR) <https://cssr.no>`_ [project no. 331841].
+This **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>`_ [project no. 331841].
 This is work in progress.
 Contributions are more than welcome using the fork and pull request approach.

docs/_sources/examples.rst.txt

@@ -117,3 +117,23 @@ To changue the colormap and setting the clorbar limits manually, this can be ach
     plopm -i spe11b/SPE11B,spe11b_larger_inj/SPE11B -v sgas -r 3 -c tab20c -b '[-0.8,0]'
 
 .. image:: ./figs/sgas_diff_edit.png
+
+==============
+Convert to VTK 
+==============
+Inside the `examples folder <https://github.com/cssr-tools/plopm/blob/main/examples>`_, then we can create VTKs from the
+OPM Flow simulation results (i.e., .EGRID, .INIT, .UNRST). For example, to create VTKS for the temperature from the restart 
+files from the initial (0) to the number 5 restart, using a OPM Flow build from source in a given path, this can be achieved by:
+
+.. code-block:: bash
+    
+    plopm -i SPE11B -v temp -r 0,5 -m vtk -p /Users/dmar/build/opm-simulators/bin/flow
+
+.. figure:: ./figs/vtk_temp.png
+
+    Visualization using paraview of the grid and temperature after 25 years of CO2 injection.
+
+.. note::
+
+    It is possible to write directly VTKs from OPM Flow simulations by adding the flag **--enable-vtk-output=true**.
+    However, there are quantities that are not written (e.g., fipnum, flores). This is when **plopm** can be helpful.

docs/_sources/index.rst.txt

@@ -7,6 +7,7 @@ Welcome to plopm's documentation!
    :maxdepth: 4
 
    introduction
+   installation
    examples
    api
    related

docs/_sources/installation.rst.txt

@@ -0,0 +1,139 @@
+============
+Installation
+============
+
+Python package
+--------------
+
+To install the **plopm** executable 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 
+install the Python requirements in a virtual environment with the following commands:
+
+.. code-block:: console
+
+    # Clone the repo
+    git clone https://github.com/cssr-tools/plopm.git
+    # Get inside the folder
+    cd plopm
+    # Create virtual environment
+    python3 -m venv vplopm
+    # Activate virtual environment
+    source vplopm/bin/activate
+    # Upgrade pip, setuptools, and wheel
+    pip install --upgrade pip setuptools wheel
+    # Install the plopm package
+    pip install -e .
+    # For contributions/testing/linting, install the dev-requirements
+    pip install -r dev-requirements.txt
+
+.. note::
+
+    For not macOS users, to install the Python opm package, execute in the terminal **pip install opm**.
+    For macOS, 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)
+
+.. 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. 
+
+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.): 
+
+.. code-block:: console
+
+    CURRENT_DIRECTORY="$PWD"
+
+    for repo in common grid models simulators
+    do
+        git clone https://github.com/OPM/opm-$repo.git
+    done
+
+    mkdir build
+
+    for repo in common grid models
+    do
+        mkdir build/opm-$repo
+        cd build/opm-$repo
+        cmake -DUSE_MPI=1 -DWITH_NDEBUG=1 -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="$CURRENT_DIRECTORY/build/opm-common;$CURRENT_DIRECTORY/build/opm-grid" $CURRENT_DIRECTORY/opm-$repo
+        make -j5 opm$repo
+        cd ../..
+    done    
+
+    mkdir build/opm-simulators
+    cd build/opm-simulators
+    cmake -DUSE_MPI=1 -DWITH_NDEBUG=1 -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="$CURRENT_DIRECTORY/build/opm-common;$CURRENT_DIRECTORY/build/opm-grid;$CURRENT_DIRECTORY/build/opm-models" $CURRENT_DIRECTORY/opm-simulators
+    make -j5 flow
+    cd ../..
+
+
+.. tip::
+
+    You can create a .sh file (e.g., build_opm_mpi.sh), copy the previous lines, and run in the terminal **source build_opm_mpi.sh**
+
+Regarding the reading of from OPM Flow output files (i.e., .EGRID, .INIT, .UNRST), it is possible to use the opm python package instead of resdata (e.g., it seems the opm Python package
+is faster than resdata to read large simulation files). To use opm, you first need to install it, by executing in the terminal **pip install opm**.  
+
+.. _macOS:
+
+Source build in macOS
++++++++++++++++++++++
+For macOS, there are no available binary packages, so OPM Flow needs to be built from source, in addition to the dune libraries and the opm Python
+package (see the `prerequisites <https://opm-project.org/?page_id=239>`_, which can be installed using macports or brew). This can be achieved by the following lines:
+
+.. code-block:: console
+
+    CURRENT_DIRECTORY="$PWD"
+
+    for module in common geometry grid istl
+    do   git clone https://gitlab.dune-project.org/core/dune-$module.git --branch v2.9.1
+    done
+    for module in common geometry grid istl
+    do   ./dune-common/bin/dunecontrol --only=dune-$module cmake -DCMAKE_DISABLE_FIND_PACKAGE_MPI=1
+         ./dune-common/bin/dunecontrol --only=dune-$module make -j5
+    done
+
+    for repo in common grid models simulators
+    do
+        git clone https://github.com/OPM/opm-$repo.git
+    done
+
+    source vplopm/bin/activate
+
+    mkdir build
+
+    for repo in common grid models
+    do
+        mkdir build/opm-$repo
+        cd build/opm-$repo
+        cmake -DPYTHON_EXECUTABLE=$(which python) -DWITH_NDEBUG=1 -DUSE_MPI=0 -DOPM_ENABLE_PYTHON=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="$CURRENT_DIRECTORY/dune-common/build-cmake;$CURRENT_DIRECTORY/dune-grid/build-cmake;$CURRENT_DIRECTORY/dune-geometry/build-cmake;$CURRENT_DIRECTORY/dune-istl/build-cmake;$CURRENT_DIRECTORY/build/opm-common;$CURRENT_DIRECTORY/build/opm-grid" $CURRENT_DIRECTORY/opm-$repo
+        make -j5
+        cd ../..
+    done    
+
+    mkdir build/opm-simulators
+    cd build/opm-simulators
+    cmake -DUSE_MPI=0 -DWITH_NDEBUG=1 -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="$CURRENT_DIRECTORY/dune-common/build-cmake;$CURRENT_DIRECTORY/dune-grid/build-cmake;$CURRENT_DIRECTORY/dune-geometry/build-cmake;$CURRENT_DIRECTORY/dune-istl/build-cmake;$CURRENT_DIRECTORY/build/opm-common;$CURRENT_DIRECTORY/build/opm-grid;$CURRENT_DIRECTORY/build/opm-models" $CURRENT_DIRECTORY/opm-simulators
+    make -j5 flow
+    cd ../..
+
+    echo "export PYTHONPATH=\$PYTHONPATH:$CURRENT_DIRECTORY/build/opm-common/python" >> $CURRENT_DIRECTORY/vplopm/bin/activate
+
+
+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`).

docs/_sources/introduction.rst.txt

@@ -8,14 +8,15 @@ This documentation describes the content of the **plopm** tool.
 
 Concept
 -------
-Simplified and flexible framework for quick visualization of OPM Flow geological models.
+Simplified and flexible framework for quick visualization of `OPM Flow <https://www.paraview.org>`_ geological models.
 The approach is the generation of PNG figures from static (e.g, porosity, pore volume fluid in place numbers)
 and dynamic (e.g., pressure, fluid saturations) properties given any 2D slide (e.g., the middle part of a reservoir in the xy plane),
 as well as plotting any given summary vector (e.g., field gas in place a.k.a fgip). 
 
 The **plopm** tool can be useful for quick inspection of geological models, as well as for generation of nice
-figures for papers/presentations. In addition, **plopm** can plot summary results from different simulation cases in the same figure,
-as well as the difference between given dynamic variables (e.g., pressure) for two different simulations cases. 
+figures for papers/presentations. Also, **plopm** can plot summary results from different simulation cases in the same figure,
+as well as the difference between given dynamic variables (e.g., pressure) for two different simulations cases. In addition, **plopm** can
+convert OPM Flow output files to vtk, which allows to use other visualization/postprocessing tools (e.g., `paraview <https://www.paraview.org>`_)
 
 .. _overview:
 
@@ -49,17 +50,5 @@ where
 - \-d: Specify the dimensions  of the Figure (e.g., '5,5') ('8,16' by default).
 - \-t: Specify the figure title (e.g., 'Final saturation map') ('' by default, i.e., set by plopm).
 - \-r: Restart number to plot the dynamic variable, where 1 corresponds to the initial one ('-1' by default, i.e., the last restart file).
-
-Installation
-------------
-See the `Github page <https://github.com/cssr-tools/plopm>`_.
-
-.. tip::
-    Check the `CI.yml <https://github.com/cssr-tools/plopm/blob/main/.github/workflows/CI.yml>`_ file.
-
-Getting started
----------------
-See the :doc:`examples <./examples>`.
-
-.. tip::
-    Check the `tests <https://github.com/cssr-tools/plopm/blob/main/tests>`_.
+- \-p: Path to flow (e.g., '\home\build\bin\flow'). This is used to generate the grid for the vtk files ('flow' by default).
+- \-m: Generate 'png' or 'vtk' files ('png' by default).

docs/_static/searchtools.js

@@ -178,7 +178,7 @@ const Search = {
 
   htmlToText: (htmlString, anchor) => {
     const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html');
-    for (const removalQuery of [".headerlinks", "script", "style"]) {
+    for (const removalQuery of [".headerlink", "script", "style"]) {
       htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() });
     }
     if (anchor) {
@@ -328,13 +328,14 @@ const Search = {
     for (const [title, foundTitles] of Object.entries(allTitles)) {
       if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) {
         for (const [file, id] of foundTitles) {
-          let score = Math.round(100 * queryLower.length / title.length)
+          const score = Math.round(Scorer.title * queryLower.length / title.length);
+          const boost = titles[file] === title ? 1 : 0;  // add a boost for document titles
           normalResults.push([
             docNames[file],
             titles[file] !== title ? `${titles[file]} > ${title}` : title,
             id !== null ? "#" + id : "",
             null,
-            score,
+            score + boost,
             filenames[file],
           ]);
         }

docs/about.html

@@ -47,6 +47,7 @@
         </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
               <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li>
+<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="related.html">Related</a></li>
@@ -80,7 +81,8 @@
   <section id="about-plopm">
 <h1>About plopm<a class="headerlink" href="#about-plopm" title="Link to this heading"></a></h1>
 <a class="reference internal image-reference" href="_images/about.png"><img alt="_images/about.png" src="_images/about.png" style="width: 575.5px; height: 541.0px;" /></a>
-<p>The <strong>plopm</strong> tool for plotting OPM Flow geological models is being funded by the <a class="reference external" href="https://cssr.no">Center for Sustainable Subsurface Resources (CSSR)</a> [project no. 331841].
+<p>This <strong>plopm</strong> package is being funded by the <a class="reference external" href="https://www.norceresearch.no/en/projects/hpc-simulation-software-for-the-gigatonne-storage-challenge">HPC Simulation Software for the Gigatonne Storage Challenge project</a>
+[project number 622059] and <a class="reference external" href="https://cssr.no">Center for Sustainable Subsurface Resources (CSSR)</a> [project no. 331841].
 This is work in progress.
 Contributions are more than welcome using the fork and pull request approach.</p>
 </section>

docs/api.html

@@ -48,6 +48,7 @@
         </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
               <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li>
+<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 current"><a class="current reference internal" href="#">plopm Python API</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#plopm">plopm</a><ul>