Merge pull request #8 from daavid00/developing

Improvements and additional examples for generic decks

.gitignore

@@ -163,8 +163,8 @@ cython_debug/
 .DS_Store
 
 # Tests
-tests/configs/ert/
-tests/generic_deck
+tests/configs/ert
+tests/decks/coarser
 tests/configs/ert
 tests/configs/jobs
 tests/configs/logs

README.md

@@ -3,7 +3,7 @@
 [![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)
 [![DOI](https://zenodo.org/badge/815649176.svg)](https://zenodo.org/doi/10.5281/zenodo.12740838)
-<img src="docs/text/figs/pycopm.gif" width="900" height="200">
+<img src="docs/text/figs/pycopm.gif" width="900" height="300">
 
 # pycopm: An open-source coarsening framework for OPM Flow geological models
 
@@ -52,6 +52,11 @@ Run `pycopm --help` to see all possible command line argument options.
 ## Getting started
 See the [_examples_](https://cssr-tools.github.io/pycopm/examples.html) in the [_documentation_](https://cssr-tools.github.io/pycopm/introduction.html).
 
+## Publications
+The following is a list of manuscripts in which _pycopm_ is used:
+
+1. Sandve, T.H., Lorentzen, R.J., Landa-Marbán, D., Fossum, K., 2024. Closed-loop reservoir management using fast data-calibrated coarse models. European Association of Geoscientists & Engineers, ECMOR 2024, Volume 202, ISSN 2214-4609. https://doi.org/10.3997/2214-4609.202437071.
+
 ## About pycopm
 The _pycopm_ package is being funded by the [_Center for Sustainable Subsurface Resources (CSSR)_](https://cssr.no) 
 [project no. 331841].

docs/_sources/configuration_file.rst.txt

@@ -6,7 +6,7 @@ Configuration file
     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>`.)
+    of the argument options, as well as the examples in :ref:`generic`.)
 
 
 Here we use as an example one of the configuration files used in the tests

docs/_sources/examples.rst.txt

@@ -6,11 +6,8 @@ Examples
 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>`_:
+to perform HM studies in drogon and norne using `ERT <https://ert.readthedocs.io/en/latest/>`_. For example, by executing inside the `example folder for drogon <https://github.com/cssr-tools/pycopm/blob/main/examples/drogon>`_:
 
 .. code-block:: bash
 
@@ -20,17 +17,50 @@ The following are the drogon model from `opm-tests <https://github.com/OPM/opm-t
 
 .. figure:: figs/drogon_coarser.png
 
+For norne:
+
+.. code-block:: bash
+
+    pycopm -i input.txt -o norne_coarser
+
+The norne GIF in the :doc:`introduction <./introduction>` was generated using the generated coarse model. 
+
+.. _generic:
 
 ==================
 Via OPM Flow decks 
 ==================
 
+The current development of **pycopm** focuses on only creating coarser models (i.e., all needed input files to run OPM Flow) by using the input deck.
+
+Hello world
+-----------
+For the `HELLO_WORLD.DATA <https://github.com/cssr-tools/pycopm/blob/main/tests/decks/HELLO_WORLD.DATA>`_ deck, by executing:
+
+.. code-block:: bash
+
+    pycopm -i HELLO_WORLD.DATA -c 5,1,5 -m all
+
+This would generated the following:
+
+.. figure:: figs/hello_world_1.png
+
+    Dry run from the input cloned deck (left) and (right) coarsed model. Adding the flag -p 1 adds the remove pore volume to the neighbouring cells.
+
+To make active the coarse cell where there is only one active cell, this can be achieve by:
+
+.. code-block:: bash
+
+    pycopm -i HELLO_WORLD.DATA -c 5,1,5 -m all -a max
+
+.. figure:: figs/hello_world_2.png
+
+    Dry run from the input cloned deck (left) and (right) coarsed model. The region numbers by default are given by the mode, e.g., use the flag -n max to keep the maximum integer.
+
 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 OPM files and running:
+By downloading the `SPE10_MODEL2 model <https://github.com/OPM/opm-data/tree/master/spe10model2>`_, then:
 
 .. code-block:: bash
 
@@ -48,26 +78,20 @@ then:
 
 .. code-block:: bash
 
-    pycopm -i Statoil_Feasibility_sim_model_with_depletion_KROSS_INJ_SECTOR_20.DATA -o . -c 5,4,3 -a mode
-
-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.
+    pycopm -i Statoil_Feasibility_sim_model_with_depletion_KROSS_INJ_SECTOR_20.DATA -o . -c 5,4,3 -a min -m all
 
-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
+will generate a coarser model 5 times in the x direction, 4 in the y direction, and 3 in the z direction, where the coarse cell is
+made inactive if at least one cell is inactive (-a min).
 
 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
+    plopm -i ' STATOIL_FEASIBILITY_SIM_MODEL_WITH_DEPLETION_KROSS_INJ_SECTOR_20_PREP_PYCOPM_DRYRUN STATOIL_FEASIBILITY_SIM_MODEL_WITH_DEPLETION_KROSS_INJ_SECTOR_20_PYCOPM' -s ,,0 -v poro -subfigs 1,2 -save smeaheia -t 'Smeaheia  Coarsed smeaheia' -xunits km -xformat .0f -yunits km -yformat .0f -d 5,5.2 -suptitle 0 -c cet_rainbow_bgyrm_35_85_c69 -cbsfax 0.30,0.01,0.4,0.02 -cformat .2f
 
 .. figure:: figs/smeia.png
 
-    Porosity values for the (left) original and (right) coarsed model.
+    Top view of porosity values for the (left) original and (right) coarsed model (note that we also coarse on the z direction).
 
 .. tip::
     You can install plopm by executing in the terminal: pip install git+https://github.com/cssr-tools/plopm.git.
@@ -77,16 +101,16 @@ We use our `plopm <https://github.com/cssr-tools/plopm>`_ friend to generate PNG
     (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.
 
-Generic Drogon
---------------
+Drogon
+------
 Following the note above, then by downloading the `DROGON model <https://github.com/OPM/opm-tests/tree/master/drogon>`_, replacing the lines in
 `DROGON_HIST.DATA <https://github.com/OPM/opm-tests/blob/master/drogon/model/DROGON_HIST.DATA>`_ for the FAULTS (L127-128) and SCHEDULE (L242-243) with
 the actual content of those include files, then by executing:
 
 .. code-block:: bash
 
-    pycopm -i DROGON_HIST.DATA -o . -c 1,1,3 -a min -n max -p 1
-    pycopm -i DROGON_HIST_PYCOPM.DATA -o . -c 1,3,1 -a mode -n mode -p 1 -j 1.9
+    pycopm -i DROGON_HIST.DATA -c 1,1,3 -p 1
+    pycopm -i DROGON_HIST_PYCOPM.DATA -c 1,3,1 -p 1 -j 2.5
 
 this would generate the following coarse model:
 
@@ -95,8 +119,23 @@ this would generate the following coarse model:
     Note that the total pore volume is conserved for the coarse model.
 
 Here, we first coarse in the z direction, which reduces the number of cells from 31 to 11, and after we coarse in the y direction.
-After trial and error, the jump (-j) is set to 1.9 to avoid generated connections across the faults.
+After trial and error, the jump (-j) is set to 2.5 to avoid generated connections across the faults. For geological models with a lot of
+inactive cells and faults, this divide and conquer apporach is recommended, i.e., coarsening first in the z directon and after coarsening
+in the x and y directions.
 
 .. note::
-    After genereting the first coarser deck (DROGON_HIST_PYCOPM.DATA), change the path '../include/props/drogon.swatinit' to 'SWATINIT.INC',
-    which contains the right number of values for the coarse model.
+    Add to the generated coarse deck the missing include files in the grid section related to the region operations (e.g.,
+    ../include/grid/drogon.multregt for this case).
+
+Norne
+-----
+By downloading the `Norne model <https://github.com/OPM/opm-tests/tree/master/norne>`_ (and replacing the needed include files as described in the previous
+example), then here we create a coarser model by removing certain pilars in order to keep the main features of the geological model:
+
+.. code-block:: bash
+
+    pycopm -i NORNE_ATW2013.DATA -x 0,2,0,2,2,0,2,0,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,0,2,0,2,2,0,2,2,0,2,2,2,2,0 -y 0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,0,2,0,2,0,2,0,2,0,2,0,2,0,2,0,2,2,2,2,2,2,2,2,2,0 -z 0,0,2,0,0,2,2,2,2,2,02,2,2,2,2,0,0,2,0,2,2,0,0,0,0,0,0,0,0,0,0 -a min -p 1
+
+this would generate the following coarse model:
+
+.. figure:: figs/norne_vec.png

docs/_sources/introduction.rst.txt

@@ -12,8 +12,8 @@ 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
+In the initial development of the framework, the focus were 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 were 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 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
@@ -32,16 +32,20 @@ The current implementation supports the following executable with the argument o
 
 where 
 
--i  The base name of the :doc:`configuration file <./configuration_file>` or the name of the deck, e.g., `DROGON.DATA`, (`input.txt` by default).
--o  The base name of the :doc:`output folder <./output_folder>` ('.'' by default, i.e., the folder where pycopm is executed).
--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, e.g., min makes the new coarser cell inactive it at least one cell is inactive, while max makes it active it at least one cell is active (`max` by default).
--j  Tuning parameter to avoid creation of neighbouring connections in the coarser model where there are discontinuities between cells along the z direction, e.g., around faults ('' by default, i.e., nothing corrected; if need it, try with values of the order of 1).
--x  Vector of x-coarsening, e.g., if the grid has 6 cells in the x direction, then `0,2,0,2,0,2,0` would generate a coarser model with 3 cells, while `0,2,2,2,2,2,0` would generate a coarser model with 1 cell, i.e., 0 keeps the pilars while 2 removes them ('' by default),
--y  Vector of y-coarsening, see the description for -x ('' by default).
--z  Vector of z-coarsening, see the description for -x ('' by default).
--e  Use `utf8` or `ISO-8859-1` encoding to read the deck (`ISO-8859-1` by default).
--p  Add the removed pore volume to the closest coarser cells (`0` by default, `1` to enable).
--n  Use `min`, `max`, or `mode` to scale satnum, fipnum, pvtnum, eqlnum, imbnum, and multnum (`mode` by default).
--s  Use `min`, `max`, or `mean` to scale permx, permy, permz, and poro ('' by default, i.e., using the arithmetic average for permx/permy, harmonic average for permz, and the mean for the porosity).
+-i    The base name of the :doc:`configuration file <./configuration_file>` or the name of the deck, e.g., `DROGON.DATA`, (`input.txt` by default).
+-o    The base name of the :doc:`output folder <./output_folder>` ('.'' by default, i.e., the folder where pycopm is executed).
+-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; either use this flag or the -x, -y, and -z ones).
+-x    Vector of x-coarsening, e.g., if the grid has 6 cells in the x direction, then `0,2,0,2,0,2,0` would generate a coarser model with 3 cells, while `0,2,2,2,2,2,0` would generate a coarser model with 1 cell, i.e., 0 keeps the pilars while 2 removes them ('' by default),
+-y    Vector of y-coarsening, see the description for -x ('' by default).
+-z    Vector of z-coarsening, see the description for -x ('' by default).
+-a    Use `min`, `max`, or `mode` to scale the actnum, e.g., min makes the new coarser cell inactive if at least one cell is inactive, while max makes it active it at least one cell is active (`mode` by default).
+-n    Use `min`, `max`, or `mode` to scale endnum, eqlnum, fipnum, fluxnum, imbnum, miscnum, multnum, pvtnum, rocknum, and satnum (`mode` by default).
+-s    Use `min`, `max`, or `mean` to scale permx, permy, permz, poro, swatinit, and all mult(-)xyz ('' by default, i.e., using the arithmetic average for permx/permy, harmonic average for permz, and the mean for the rest).
+-p    Add the removed pore volume to the closest coarser cells (`0` by default, `1` to enable).
+-j    Tuning parameter to avoid creation of neighbouring connections in the coarser model where there are discontinuities between cells along the z direction, e.g., around faults ('' by default, i.e., nothing corrected; if need it, try with values of the order of 1).
+-m    Execute a dry run on the input deck to generate the static properties ('prep'), generate only the coarse files ('deck'), only exectute a dry run on the generated coarse model ('dry'), 'prep_deck', 'deck_dry', or do all ('all') (`prep_deck` by default).
+-w    Name of the generated deck ('' by default, i.e., the name of the input deck plus _PYCOPM.DATA).
+-l    Added text before each generated .INC (`PYCOPM_` by default, i.e., the coarse porv is saved in PYCOPM_PORV.INC; set to '' to generate PORV.INC, PERMX.INC, etc).
+-e    Use `utf8` or `ISO-8859-1` encoding to read the deck (`ISO-8859-1` by default).
+-ijk  Given i,j,k indices in the input model, return the coarse i,j,k corresponding positions ('' by default; if not empty, e.g., 1,2,3 then the -m is set to deck and there will not be generation of coarse files, only the i,j,k coarse indices in the terminal).

docs/_sources/output_folder.rst.txt

@@ -21,12 +21,18 @@ are generated in the postprocessing folder. The OPM simulation results can be vi
 
 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 current development of **pycopm** focuces on only creating coarser models (i.e., all needed input files to run OPM Flow) by using the input deck.
 
 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>`_).
+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>`_).
+
+.. Note::
+    For input decks that include other files without giving the full path (e.g., './include/summary...'), then we recommend
+    to use the default output folder (-o .), i.e., the generated deck and coarse files would be generated in the same location as
+    the input deck and no errors would appear for not finding the include files; otherwise, you might need to copy all needed folders
+    with the include files to the output folder or setting the correct path to the include files in the generated coarse deck. 

docs/configuration_file.html

@@ -89,7 +89,7 @@ <h1>Configuration file<a class="headerlink" href="#configuration-file" title="Li
 only for the drogon and norne model. To use <strong>pycopm</strong> 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 <a class="reference internal" href="introduction.html#overview"><span class="std std-ref">Overview</span></a> or run <cite>pycopm -h</cite> for the definition
-of the argument options, and the <a class="reference internal" href="examples.html"><span class="doc">examples</span></a>.)</p>
+of the argument options, as well as the examples in <a class="reference internal" href="examples.html#generic"><span class="std std-ref">Via OPM Flow decks</span></a>.)</p>
 </div>
 <p>Here we use as an example one of the configuration files used in the tests
 (see <a class="reference external" href="https://github.com/crrs-tools/pycopm/blob/main/tests/configs/ert.txt">ert.txt</a>).