Skip to content

Commit

Permalink
Updating the documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
daavid00 committed Jul 14, 2024
1 parent 18fadb3 commit 6c695aa
Show file tree
Hide file tree
Showing 49 changed files with 1,367 additions and 324 deletions.
24 changes: 13 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).

Expand All @@ -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).
Binary file modified docs/_images/contents.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_images/output_generic.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_images/plopm.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_images/smeia.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/_sources/about.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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.
8 changes: 8 additions & 0 deletions docs/_sources/configuration_file.rst.txt
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
62 changes: 54 additions & 8 deletions docs/_sources/examples.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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>`_:
Expand All @@ -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.
41 changes: 28 additions & 13 deletions docs/_sources/introduction.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------
Expand All @@ -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>`_.
26 changes: 22 additions & 4 deletions docs/_sources/output_folder.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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>`_).
11 changes: 9 additions & 2 deletions docs/_sources/related.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,7 @@
Related
=======

Below are some packages following the same configuration-file-to-postprocessing-folder approach;
check them out 🙂.
Below are some tools that might be of interest; check them out 🙂.

**********
pyopmspe11
Expand All @@ -23,6 +22,14 @@ pyopmnearwell

`A framework to simulate near well dynamics using OPM Flow <https://github.com/cssr-tools/pyopmnearwell>`_.

*****
plopm
*****

.. image:: ./figs/plopm.png

`Quick generation of PNG figures from a simulation model given any 2D slide <https://github.com/cssr-tools/plopm>`_.

********
expreccs
********
Expand Down
2 changes: 1 addition & 1 deletion docs/about.html
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@
<section id="about-pycopm">
<h1>About pycopm<a class="headerlink" href="#about-pycopm" title="Link to this heading"></a></h1>
<a class="reference internal image-reference" href="_images/droganim.gif"><img alt="_images/droganim.gif" src="_images/droganim.gif" style="width: 513.5px; height: 416.0px;" /></a>
<p>The <strong>pycopm</strong> tool for coarsening 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><strong>pycopm</strong>, a tool for coarsening 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].
This is work in progress.
Contributions are more than welcome using the fork and pull request approach.</p>
</section>
Expand Down
8 changes: 8 additions & 0 deletions docs/configuration_file.html
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,14 @@

<section id="configuration-file">
<h1>Configuration file<a class="headerlink" href="#configuration-file" title="Link to this heading"></a></h1>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The configuration files allow to set the integrated studies (coarsening and history matching)
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>
</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>).
The first input parameter is:</p>
Expand Down
Loading

0 comments on commit 6c695aa

Please sign in to comment.