Merge pull request #3 from daavid00/developing

Updating the documentation

Author: daavid00

README.md

@@ -4,16 +4,23 @@
 [![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/pycopm.gif" width="900" height="200">
 
-# pycopm: An open-source coarsening framework for OPM Flow
+# pycopm: An open-source coarsening framework for OPM Flow geological models
 
-This repository contains runscripts to create coarser models from given input decks. 
-Here we use the [_OPM-Flow_](https://opm-project.org/?page_id=19) simulator.
+## Main feature
+Creation of coarser models from given input decks. 
 
 ## Installation
 You will first need to install
 * Flow (https://opm-project.org, Release 2024.04 or current master branches)
 
-You can install the Python requirements in a virtual environment with the following commands:
+To install the _pycopm_ executable in an existing Python environment: 
+
+```bash
+pip install git+https://github.com/cssr-tools/pycopm.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:
 
 ```bash
 # Clone the repo
@@ -32,7 +39,7 @@ pip install -e .
 pip install -r dev-requirements.txt
 ``` 
 
-See the [_CI.yml_](https://github.com/OPM/pycopm/blob/main/.github/workflows/CI.yml) script  for installation of OPM Flow (binary packages) and the pycopm 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 (you first need to install the [_OPM-Flow-prerequisites_](https://opm-project.org/?page_id=239)). 
+See the [_CI.yml_](https://github.com/OPM/pycopm/blob/main/.github/workflows/CI.yml) script for installation of OPM Flow (binary packages) and the pycopm 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 (you first need to install the [_OPM-Flow-prerequisites_](https://opm-project.org/?page_id=239)). 
 
 For macOS users, use at least a Python version of 3.10 (due to resdata), and run the `./build_opm-flow_macOS.bash` to build OPM Flow (the [_OPM-Flow-prerequisites_](https://opm-project.org/?page_id=239) can be installed via brew or macports).
 
@@ -44,9 +51,4 @@ pycopm -i some_input -o some_output_folder
 Run `pycopm --help` to see all possible command line argument options.
 
 ## Getting started
-See the [_documentation_](https://cssr-tools.github.io/pycopm/introduction.html).
-
-## Citing
-If you use _pycopm_ in your research, please cite the following publication:
-
-Sandve, T.H., Lorentzen, R.J., Landa-Marbán, D., Fossum, K., 2024. Closed-loop reservoir management using fast data-calibrated coarse models. In: ECMOR 2024, 1. European Association of Geoscientists & Engineers, 1–14.
+See the [_examples_](https://cssr-tools.github.io/pycopm/examples.html) in the [_documentation_](https://cssr-tools.github.io/pycopm/introduction.html).

docs/_images/contents.png

@@ -5,6 +5,6 @@ About pycopm
 .. image:: ./figs/droganim.gif
     :scale: 65%
 
-The **pycopm** tool for coarsening geological models is being funded by the `Center for Sustainable Subsurface Resources (CSSR) <https://cssr.no>`_ [project no. 331841].
+**pycopm**, a tool for coarsening OPM Flow geological models, is being funded by the `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/_images/output_generic.png

@@ -1,6 +1,14 @@
 ==================
 Configuration file
 ==================
+.. Note::
+    The configuration files allow to set the integrated studies (coarsening and history matching)
+    only for the drogon and norne model. To use **pycopm** in any given OPM Flow geological model
+    to generate the coarser files, this can be achieve without a configuration file, but setting
+    the parameters via command lines (see the :ref:`overview` or run `pycopm -h` for the definition 
+    of the argument options, and the :doc:`examples <./examples>`.)
+
+
 Here we use as an example one of the configuration files used in the tests
 (see `ert.txt <https://github.com/crrs-tools/pycopm/blob/main/tests/configs/ert.txt>`_).
 The first input parameter is:

docs/_images/plopm.png

@@ -2,9 +2,12 @@
 Examples
 ********
 
-==================
-Configuration file 
-==================
+=======================
+Via configuration files
+=======================
+
+Drogon
+------
 
 The `examples <https://github.com/cssr-tools/pycopm/blob/main/examples>`_ folder contains configuration files
 to perform HM studies in drogon and norne. For example, by executing inside the `example folder for drogon <https://github.com/cssr-tools/pycopm/blob/main/examples/drogon>`_:
@@ -18,16 +21,59 @@ The following are the drogon model from `opm-tests <https://github.com/OPM/opm-t
 .. figure:: figs/drogon_coarser.png
 
 
-==========
-Input deck 
-==========
+==================
+Via OPM Flow decks 
+==================
+
+SPE10
+-----
 
 See/run the `test_generic_deck.py <https://github.com/cssr-tools/pycopm/blob/main/tests/test_generic_deck.py>`_ 
 for an example where **pycopm** is used to coarse the 
-`SPE10_MODEL2 model <https://github.com/OPM/opm-data/tree/master/spe10model2>`_ by downloading the files and running:
+`SPE10_MODEL2 model <https://github.com/OPM/opm-data/tree/master/spe10model2>`_ by downloading the OPM files and running:
 
 .. code-block:: bash
 
     pycopm -i SPE10_MODEL2.DATA -o coarser -c 4,8,2
 
-.. figure:: figs/spe10_model2_coarser.png
+.. figure:: figs/spe10_model2_coarser.png
+
+    Porosity values for the (left) original and (right) coarsed SPE10 model.
+
+Smeaheia
+--------
+
+By downloading the `Smeaheia simulation model <https://co2datashare.org/dataset/smeaheia-dataset>`_,
+then:
+
+.. code-block:: bash
+
+    pycopm -i Statoil_Feasibility_sim_model_with_depletion_KROSS_INJ_SECTOR_20.DATA -o . -c 5,4,3 -a mode -j 1000
+
+will generate a coarser model 5 times in the x direction, 4 in the y direction, and 3 in the z direction, where the mode is 
+used to decide if a coarser cell should be active or inactive. The jump (-j) is set to a higher value (1000) to avoid removal
+of grid connections (this is a tunning value to remove generated connections between neighbours in the coarse model).
+
+We can execute a dry run of OPM Flow to generate the grid and static variables of the coarser model:
+
+.. code-block:: bash
+
+    flow STATOIL_FEASIBILITY_SIM_MODEL_WITH_DEPLETION_KROSS_INJ_SECTOR_20_PYCOPM.DATA --enable-dry-run=true
+
+We use our `plopm <https://github.com/cssr-tools/plopm>`_ friend to generate PNG figures:
+
+.. code-block:: bash
+
+    plopm -i STATOIL_FEASIBILITY_SIM_MODEL_WITH_DEPLETION_KROSS_INJ_SECTOR_20_PYCOPM -s ,,0
+
+.. figure:: figs/smeia.png
+
+    Porosity values for the (left) original and (right) coarsed model.
+
+.. tip::
+    You can install plopm by executing in the terminal: pip install git+https://github.com/cssr-tools/plopm.git.
+
+.. note::
+    In the current implementation of the **pycopm** tool, the handling of properties that require definitions of i,j,k indices 
+    (e.g., FAULTS, WELLSPECS) are assumed to be define in the main .DATA deck. Then, in order to use **pycopm** for simulation models 
+    where these properties are define via include files, replace those includes in the .DATA deck with the actual content of the include files.

docs/_images/smeia.png

@@ -5,20 +5,22 @@ Introduction
 .. image:: ./figs/pycopm.gif
 
 This documentation describes the content of the **pycopm** package.
-The numerical studies are performed using the `Flow <https://opm-project.org/?page_id=19>`_ simulator. 
 
 Concept
 -------
-Simplified and flexible framework for coarsening geological models. The initial implementation
-included two available models in `opm-tests <https://github.com/OPM/opm-tests>`_: `norne <https://github.com/OPM/opm-tests/tree/master/norne>`_ 
+Simplified and flexible framework to create coarser OPM Flow geological models.
+
+Roadmap
+-------
+In the initial development of the framework, the focus was two available models in `opm-tests <https://github.com/OPM/opm-tests>`_: `norne <https://github.com/OPM/opm-tests/tree/master/norne>`_ 
 and `drogon <https://github.com/OPM/opm-tests/tree/master/drogon>`_, where the coarser models are used to perform history matching studies using
-the Ensemble based reservoir tool `ERT <https://ert.readthedocs.io/en/latest/>`_, via a :doc:`configuration file <./configuration_file>`. The current
-available options for parameters to HM are the saturation functions using the LET model and permeabilities. The plan is to extend the functionality to
-set up history matching/optimization studies using either `ERT <https://ert.readthedocs.io/en/latest/>`_, `PET <https://python-ensemble-toolbox.github.io/PET/>`_, 
-or `everest <https://github.com/equinor/everest>`_.
+the Ensemble based reservoir tool `ERT <https://ert.readthedocs.io/en/latest/>`_, via a :doc:`configuration file <./configuration_file>`.
+
+The current development of **pycopm** focuses on only creating coarser models (i.e., all needed input files to run OPM Flow) by only giving the OPM Flow input files
+(i.e., avoiding the manual work to create templates as it was done for drogon and norne). This allows for flexibility to adapt the generated coarser decks in your
+favourite history matching/optimization tool (e.g., `ERT <https://ert.readthedocs.io/en/latest/>`_, `PET <https://python-ensemble-toolbox.github.io/PET/>`_, `everest <https://github.com/equinor/everest>`_).
 
-In addition, current work focuces on creating coarser grids by only giving the input files
-(i.e., avoiding the manual work to create templates as done for drogon and norne); see the :doc:`examples <./examples>`.
+.. _overview:
 
 Overview
 --------
@@ -30,14 +32,27 @@ The current implementation supports the following executable with the argument o
 
 where 
 
-- \-i, \-input: The base name of the :doc:`configuration file <./configuration_file>` or the name of the deck (`input.txt` by default).
-- \-o, \-output: The base name of the :doc:`output folder <./output_folder>` (`output` by default).
-- \-f, \-flow: Path to OPM Flow (`flow` by default).
-- \-c, \-coarsening: Level of coarsening in the x, y, and z dir (`2,2,2` by default)
+- \-i: The base name of the :doc:`configuration file <./configuration_file>` or the name of the deck (`input.txt` by default).
+- \-o: The base name of the :doc:`output folder <./output_folder>` (`output` by default).
+- \-f: OPM Flow full path to executable or just `flow` (`flow` by default).
+- \-c: Level of coarsening in the x, y, and z dir (`2,2,2` by default).
+- \-a: Use min, max, or mode to scale the actnum (`min` by default).
+- \-j: Tunning parameter to avoid creation of nnc on the structural faults (`2.` by default).
+- \-x: Vector of x-coarsening (`` by default).
+- \-y: Vector of y-coarsening (`` by default).
+- \-z: Vector of z-coarsening (`` by default).
+- \-e: Use `utf8` or `ISO-8859-1` encoding to read the deck (`ISO-8859-1` by default).
 
 Installation
 ------------
 See the `Github page <https://github.com/cssr-tools/pycopm>`_.
 
 .. tip::
     Check the `CI.yml <https://github.com/cssr-tools/pycopm/blob/main/.github/workflows/CI.yml>`_ file.
+
+Getting started
+---------------
+See the :doc:`examples <./examples>`.
+
+.. tip::
+    Check the `tests <https://github.com/cssr-tools/pycopm/blob/main/tests>`_.

docs/_sources/about.rst.txt

@@ -2,13 +2,31 @@
 Output folder
 =============
 
-The following screenshot shows the generated ERT configuration file and folders in the selected output folder after executing **pycopm**.
+Via configuration files 
+-----------------------
+As described in the :doc:`introduction <./introduction>`, in the early development of **pycopm** 
+the focus was on history matching studies using `ERT <https://ert.readthedocs.io/en/latest/>`_ for the 
+`norne <https://github.com/OPM/opm-tests/tree/master/norne>`_  and `drogon <https://github.com/OPM/opm-tests/tree/master/drogon>`_ geological models
+via a :doc:`configuration file <./configuration_file>`.
+
+The following screenshot shows the generated ERT configuration file and folders in the selected output folder after executing **pycopm**
+on the drogon model.
 
 .. figure:: figs/output.png
 
     (Left) example of generated files after executing **pycopm** and (right) some of the figures in the postprocessing folder.
 
 The generate ert.ert file can be run directly calling ERT for further studies, and some useful plots and files
-are generated in the postprocessing folder. The OPM simulation results can be visualized using `ResInsight <https://resinsight.org>`_ .
-Then after running **pycopm**, one could modify the generated OPM coarser related files in the preprocessing folder to adapt to
-further existing frameworks (e.g., `PET <https://python-ensemble-toolbox.github.io/PET/>`_, `everest <https://github.com/equinor/everest>`_).
+are generated in the postprocessing folder. The OPM simulation results can be visualized using `ResInsight <https://resinsight.org>`_.
+
+Via an OPM Flow input deck
+--------------------------
+The current development of **pycopm** focuces on only creating coarser models (i.e., all needed input files to run OPM Flow) by only giving the OPM Flow input files.
+
+The following screenshot shows the input deck and generated files in the selected output folder (coarser for this example) after executing **pycopm** on the SPE10 model (see the 
+`test_generic_deck.py <https://github.com/cssr-tools/pycopm/blob/main/tests/test_generic_deck.py>`_) file.
+
+.. figure:: figs/output_generic.png
+
+Then, after running **pycopm**, one could adapt the generated files with the coarser geological model in your
+favourite history matching/optimization tool (e.g., `ERT <https://ert.readthedocs.io/en/latest/>`_, `PET <https://python-ensemble-toolbox.github.io/PET/>`_, `everest <https://github.com/equinor/everest>`_).