cssr-tools · daavid00 · Nov 26, 2024 · Nov 26, 2024
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -1,4 +1,4 @@
-name: Run the expreccs executable
+name: Run expreccs
 
 on:
  push:

diff --git a/.gitignore b/.gitignore
@@ -142,8 +142,6 @@ opm-common/
 opm-grid/
 opm-models/
 opm-simulators/
-build_opm_mpi.sh
-build_opm_macos.sh
 
 # Extra folders
 tests/configs/back

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,16 +1,35 @@
 # Contributing
 
-Hola hola 🙂.
-The following is a set of guidelines for contributing to expreccs.
+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/expreccs/blob/main/dev-requirements.txt); in addition, the opm Python package is required, then for not macOs users run **pip install opm**, or else follow the instructions in [_macOS installation_](https://cssr-tools.github.io/expreccs/installation.html#source-build-in-macos))
+    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=expreccs --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/expreccs/tree/main/docs) folder)
+    * Tip: See the [_CI.yml_](https://github.com/cssr-tools/expreccs/blob/main/.github/workflows/CI.yml) script and the [_Actions_](https://github.com/cssr-tools/expreccs/actions) for installation of expreccs, 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/expreccs/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/expreccs/blob/main/pyproject.toml). 
diff --git a/README.md b/README.md
@@ -3,30 +3,32 @@
 [![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/760077220.svg)](https://zenodo.org/doi/10.5281/zenodo.12100600)
-
-# A Python framework for the ExpReCCS (Expansion of ResourCes for CO2 Storage on the Horda Platform) project
-
 <img src="docs/text/figs/expreccs.gif" width="830" height="500">
 
-This repository contains scripts to set up a workflow to run site and regional reservoirs for CO2 storage using the [_OPM-Flow_](https://opm-project.org/?page_id=19) simulator.
+# expreccs: A Python framework using OPM Flow to simulate regional and site reservoirs for CO2 storage
+
+## Main feature
+Simplified and flexible software for two-stage approach (dynamic pressure boundary conditions) to improve CO2 storage regional and site simulations.
 
 ## Installation
 You will first need to install
-* Flow (https://opm-project.org, Release 2024.04 or current master branches)
+* Flow (https://opm-project.org, Release 2024.10 or current master branches)
 
 To install the _expreccs_ executable in an existing Python environment: 
 
 ```bash
 pip install git+https://github.com/cssr-tools/expreccs.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
 git clone https://github.com/cssr-tools/expreccs.git
 # Get inside the folder
 cd expreccs
+# For a specific version (e.g., v2024.10), or skip this step (i.e., edge version)
+git checkout v2024.10
 # Create the virtual environment
 python3 -m venv vexpreccs
 # Activate the virtual environment
@@ -39,20 +41,31 @@ pip install -e .
 pip install -r dev-requirements.txt
 ``` 
 
-See the [_installation_](https://cssr-tools.github.io/exprecss/installation.html) for further details on building OPM Flow from the master branches in Linux, Windows, and macOS, as well as the opm Python package.
+See the [_installation_](https://cssr-tools.github.io/exprecss/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 expreccs
 You can run _expreccs_ as a single command line:
 ```
-expreccs -i some_input.txt -o some_output_folder
+expreccs -i configuration_file.txt
 ```
-Run `expreccs --help` to see all possible command line argument options. Inside the `some_input.txt` file you provide the path to the
+Run `expreccs --help` to see all possible command line argument options. Inside the `configuration_file.txt` file you provide the path to the
 flow executable and simulation parameters. See the .txt files in the [_examples_](https://github.com/cssr-tools/expreccs/tree/main/examples) and [_tests_](https://github.com/cssr-tools/expreccs/tree/main/tests/configs) folders.
 
 ## Getting started
-See the [_examples_](https://cssr-tools.github.io/expreccs/examples.html) in the [_documentation_](https://cssr-tools.github.io/expreccs/introduction.html). 
+See the [_examples_](https://cssr-tools.github.io/expreccs/examples.html) in the [_documentation_](https://cssr-tools.github.io/expreccs/introduction.html).
+
+## Citing
+If you would like to cite this repository:
+
+* Landa-Marbán, D. 2024. expreccs: A Python framework using OPM Flow to simulate regional and site reservoirs for CO2 storage. V2024.04. https://doi.org/10.5281/zenodo.12100600.
+
+## Publications
+The following is a list of manuscripts in which _expreccs_ is used:
+
+1. Tveit, S., Gasda, S.E., Landa-Marbán, D., Sandve, T.H., submitted. A hierarchical approach for modeling regional pressure interference in multi-site CO2 operations. http://dx.doi.org/10.2139/ssrn.5005237.
+1. Gasda, S.E., et al., submitted. Quantifying the impact of regional-scale pressure interference on commercial CO2 storage targets for multiple licenses. 
 
 ## About expreccs
-The expreccs package is funded by Wintershall Dea, Equinor, Shell, and the Research Council of Norway [project number 336294].
+The _expreccs_ package is funded by Wintershall Dea, Equinor, Shell, and the Research Council of Norway [project number 336294].
 This is work in progress. [_Here_](https://www.norceresearch.no/en/projects/expansion-of-resources-for-co2-storage-on-the-horda-platform-expreccs) is the link to the project details.
-Contributions are more than welcome using the fork and pull request approach.
+Contributions are more than welcome using the fork and pull request approach. For new features, please request them raising an issue.
diff --git a/docs/_images/back-coupling_summary_BPR_regional_reference.png b/docs/_images/back-coupling_summary_BPR_regional_reference.png
diff --git a/docs/_images/distance_from_border.png b/docs/_images/distance_from_border.png
diff --git a/docs/_images/fpr_plopm.png b/docs/_images/fpr_plopm.png
diff --git a/docs/_images/hello_world_distance_from_border.png b/docs/_images/hello_world_distance_from_border.png
diff --git a/docs/_images/hello_world_reference_watfluxi+.png b/docs/_images/hello_world_reference_watfluxi+.png
diff --git a/docs/_images/hello_world_regional_watfluxi+.png b/docs/_images/hello_world_regional_watfluxi+.png
diff --git a/docs/_images/hello_world_sensor_pressure_over_time.png b/docs/_images/hello_world_sensor_pressure_over_time.png
diff --git a/docs/_images/hello_world_site_flux_watfluxi+.png b/docs/_images/hello_world_site_flux_watfluxi+.png
diff --git a/docs/_images/hello_world_summary_BHP_site_reference.png b/docs/_images/hello_world_summary_BHP_site_reference.png
diff --git a/docs/_images/plopm.png b/docs/_images/plopm.png
diff --git a/docs/_images/pressure_plopm.png b/docs/_images/pressure_plopm.png
diff --git a/docs/_images/pyopmspe11.gif b/docs/_images/pyopmspe11.gif
diff --git a/docs/_images/reference_watfluxi+.png b/docs/_images/reference_watfluxi+.png
diff --git a/docs/_images/regional_watfluxi+.png b/docs/_images/regional_watfluxi+.png
diff --git a/docs/_images/sensor_pressure_over_time.png b/docs/_images/sensor_pressure_over_time.png
diff --git a/docs/_images/site_flux_watfluxi+.png b/docs/_images/site_flux_watfluxi+.png
diff --git a/docs/_images/wells_pressure_site_reference.png b/docs/_images/wells_pressure_site_reference.png
diff --git a/docs/_sources/about.rst.txt b/docs/_sources/about.rst.txt
@@ -11,4 +11,6 @@ Wintershall Dea, Equinor, Shell, and the Research Council of Norway [project num
 This is work in progress. 
 `Here <https://www.norceresearch.no/en/projects/expansion-of-resources-for-co2-storage-on-the-horda-platform-expreccs>`_ is the link to the project details.
 
-Contributions are more than welcome using the fork and pull request approach.
+Contributions are more than welcome using the fork and pull request approach.
+
+For new features, please request them raising an issue.
diff --git a/docs/_sources/contributing.rst.txt b/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/expreccs/blob/main/dev-requirements.txt>`_; in addition, the opm Python package is required, then for not macOs users run **pip install opm**, or else follow the instructions in `macOS installation <https://cssr-tools.github.io/expreccs/installation.html#source-build-in-macos>`_)
+    #. **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=expreccs --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/expreccs/tree/main/docs>`_ folder)
+
+    .. tip::
+        See the `CI.yml <https://github.com/cssr-tools/expreccs/blob/main/.github/workflows/CI.yml>`_ script and the `Actions <https://github.com/cssr-tools/expreccs/actions>`_ for installation of expreccs, 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/expreccs/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/expreccs/blob/main/pyproject.toml>`_.
diff --git a/docs/_sources/examples.rst.txt b/docs/_sources/examples.rst.txt
@@ -6,12 +6,12 @@ Example 1
 ---------
 
 We consider the configuration file `example1.txt <https://github.com/cssr-tools/expreccs/blob/main/examples/example1.txt>`_ in the 
-examples folder (the animation in the `Github home page <https://github.com/cssr-tools/expreccs>`_ was based on this configuration file). 
+examples folder (the animation in the `GitHub home page <https://github.com/cssr-tools/expreccs>`_ was based on this configuration file). 
 If the results are to be saved in a folder called 'hello_world', this is achieved by the following command: 
 
 .. code-block:: bash
 
-    expreccs -i example1.txt -o hello_world 
+    expreccs -i example1.txt -o hello_world
 
 Then we can change in line 14 the BC projections from the regional simulations from
 'flux' to 'pres', and run the following command to only simulate the site model:
@@ -36,22 +36,25 @@ in PNGs figures, we run the following command:
 
 Below are some of the figures generated inside the postprocessing folder:
 
-.. figure:: figs/reference_watfluxi+.png
+.. figure:: figs/hello_world_reference_watfluxi+.png
     :scale: 80%
-.. figure:: figs/regional_watfluxi+.png
+.. figure:: figs/hello_world_regional_watfluxi+.png
     :scale: 80%
-.. figure:: figs/site_flux_watfluxi+.png
+.. figure:: figs/hello_world_site_flux_watfluxi+.png
     :scale: 80%
 
-    Final water flux (sm3/day) in the x direction for (top) the reference, (middle) regional, and 
-    (bottom) site (with fluxes as BC). 
+    Final water velocity (m/day) in the x direction for (top) the reference, (middle) regional, and 
+    (bottom) site (with fluxes as BC). The figure names in the postprocessing folder are hello_world_reference_watfluxi+.png,
+    hello_world_regional_watfluxi+.png, and hello_world_site_flux_watfluxi+.png respectively. 
 
-.. figure:: figs/sensor_pressure_over_time.png
-.. figure:: figs/wells_pressure_site_reference.png
-.. figure:: figs/distance_from_border.png
+.. figure:: figs/hello_world_sensor_pressure_over_time.png
+.. figure:: figs/hello_world_summary_BHP_site_reference.png
+.. figure:: figs/hello_world_distance_from_border.png
 
     Comparison of cell pressures on the sensor location (top), well BHPs (middle), and minimum
-    distance from the CO2 plume to the site boundaries (bottom). 
+    distance from the CO2 plume to the site boundaries (bottom). The figure names in the postprocessing folder are 
+    hello_world_sensor_pressure_over_time.png, hello_world_summary_BHP_site_reference.png, and 
+    hello_world_distance_from_border.png respectively
 
 
 Example 2
@@ -67,7 +70,7 @@ to generate the animation (using ResInsight) in the :doc:`introduction section <
 Generic (under development)
 ---------------------------
 
-See/run the last lines (34 to 42) in the `test_main.py <https://github.com/cssr-tools/expreccs/blob/main/tests/test_main.py>`_ 
+See/run the `test_generic_deck.py <https://github.com/cssr-tools/expreccs/blob/main/tests/test_generic_deck.py>`_ 
 for an example where **expreccs** is used in two given models (regional and site, in this case they are created using
 the **expreccs** package, but in general can be any given geological models), generating a new input deck where
 the pressures are projected.
@@ -89,7 +92,7 @@ By running:
 
     expreccs -i example1_back.txt -o back-coupling -m all -p yes
 
-This is one of the generated figures:
+This is one of the generated figures in the back-coupling/postprocessing folder (named as back-coupling_summary_BPR_regional_reference.png):
 
 .. image:: ./figs/back-coupling_summary_BPR_regional_reference.png
 
@@ -98,20 +101,20 @@ iteration is set to 10 in line 22 of the `configuration_file <https://github.com
 between any of the iterations, we can use our friend `plopm <https://github.com/cssr-tools/plopm>`_. 
 
 .. tip::
-    You can install plopm by executing in the terminal: pip install git+https://github.com/cssr-tools/plopm.git.
+    You can install `plopm <https://github.com/cssr-tools/plopm>`_ by executing in the terminal: **pip install git+https://github.com/cssr-tools/plopm.git**.
 
-For example, to show the difference in the spatial maps for pressure at iteration 4 and 7 at the third restart, this is achieved by executing:
+For example, to show the difference in the spatial maps for pressure between iteration 4 and 7 at the third restart, this is achieved by executing:
 
 .. code-block:: bash
 
-    plopm -i back-coupling/output/regional_7/regional_7,back-coupling/output/regional_4/regional_4 -v pressure -r 3 -s ,,1 -c rainbow -n "lambda x, _: f'{x:.2f}'" -d 5,5
+    plopm -i back-coupling/output/regional_7/regional_7 -diff back-coupling/output/regional_4/regional_4 -v pressure -r 3 -s ,,1 -c rainbow -cformat .2f -d 5,5
 
 .. image:: ./figs/pressure_plopm.png
 
-And to show the comparison for the summary vector FPR for iterations 1, 5, 7, and 9:
+and to show the comparison for the summary vector FPR for iterations 1, 5, 7, and 9:
 
 .. code-block:: bash
 
-    plopm -i back-coupling/output/regional_1/regional_1,back-coupling/output/regional_5/regional_5,back-coupling/output/regional_7/regional_7,back-coupling/output/regional_9/regional_9 -v fpr -d 5,5 -f 10
+    plopm -i 'back-coupling/output/regional_1/regional_1 back-coupling/output/regional_5/regional_5 back-coupling/output/regional_7/regional_7 back-coupling/output/regional_9/regional_9' -v fpr -d 5,5 -f 10
 
 .. image:: ./figs/fpr_plopm.png
diff --git a/docs/_sources/index.rst.txt b/docs/_sources/index.rst.txt
@@ -11,6 +11,7 @@ Welcome to expreccs's documentation!
    configuration_file
    examples
    api
+   contributing
    output_folder
    related
    about