Merge pull request #12 from daavid00/developing

Update to toml and docs

.github/workflows/CI.yml

@@ -41,16 +41,17 @@ jobs:
       run: |
         pip install --upgrade pip setuptools wheel
         pip install -r dev-requirements.txt
+        pip install opm
         
     - name: Install expreccs
       run: |
         pip install .
         
     - 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: |

.gitignore

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

README.md

@@ -1,5 +1,5 @@
 [![Build Status](https://github.com/cssr-tools/expreccs/actions/workflows/CI.yml/badge.svg)](https://github.com/cssr-tools/expreccs/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-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)
 [![DOI](https://zenodo.org/badge/760077220.svg)](https://zenodo.org/doi/10.5281/zenodo.12100600)
@@ -12,9 +12,15 @@ This repository contains scripts to set up a workflow to run site and regional r
 
 ## 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.04 or current master branches)
 
-You can install the Python requirements in a virtual environment with the following commands:
+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:
 
 ```bash
 # Clone the repo
@@ -27,26 +33,24 @@ python3 -m venv vexpreccs
 source vexpreccs/bin/activate
 # Upgrade pip, setuptools, and wheel
 pip install --upgrade pip setuptools wheel
-# Install the expreccs package (in editable mode for contributions/modifications; otherwise, pip install .)
+# Install the expreccs package
 pip install -e .
 # For contributions/testing/linting, install the dev-requirements
 pip install -r dev-requirements.txt
 ``` 
 
-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` (see the [_CI.yml_](https://github.com/cssr-tools/expreccs/blob/main/.github/workflows/CI.yml)), which in turn should build the executable in ./build/opm-simulators/bin/flow_gaswater_dissolution. 
-
-For macOS users with the latest chips (M1/M2, guessing also M3?), the opm Python package is not available via pip install, while resdata 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). If you face this issue, then before installation, remove resdata and opm from the `requirements.txt`, then proceed with the Python requirements installation, install the OPM Flow dependencies (using macports or brew), and once inside the vexpreccs Python environment, run the `./build_opm-flow_macOS.bash`, and deactivate and activate the virtual environment (this script builds OPM Flow as well as the opm Python package, and it exports the required PYTHONPATH).
+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.
 
 ## Running expreccs
 You can run _expreccs_ as a single command line:
 ```
 expreccs -i some_input.txt -o some_output_folder
 ```
 Run `expreccs --help` to see all possible command line argument options. Inside the `some_input.txt` file you provide the path to the
-flow executable and simulation parameters. See the .txt files in the examples and tests/configs folders.
+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 [_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). 
 
 ## About expreccs
 The expreccs package is funded by Wintershall Dea, Equinor, Shell, and the Research Council of Norway [project number 336294].

buildopm.sh

@@ -0,0 +1,29 @@
+CURRENT_DIRECTORY="$PWD"
+
+for module in common
+do   git clone https://gitlab.dune-project.org/core/dune-$module.git --branch v2.9.1
+done
+for module in common
+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
+do
+    git clone https://github.com/OPM/opm-$repo.git
+done
+
+source vexpreccs/bin/activate
+
+mkdir build
+
+for repo in common
+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
+
+echo "export PYTHONPATH=\$PYTHONPATH:$CURRENT_DIRECTORY/build/opm-common/build/python" >> $CURRENT_DIRECTORY/vexpreccs/bin/activate

dev-requirements.txt

@@ -1,6 +1,7 @@
 black
-pylint
+numpydoc
 mypy
+pylint
 pytest-cov
 sphinx
 sphinx-rtd-theme

docs/_sources/examples.rst.txt

@@ -63,3 +63,15 @@ to generate the animation (using ResInsight) in the :doc:`introduction section <
 .. code-block:: bash
 
     expreccs -i example2.txt -m reference
+
+Generic (under development)
+---------------------------
+
+See/run the last lines (34 to 42) in the `test_main.py <https://github.com/cssr-tools/expreccs/blob/main/pyproject.toml>`_ 
+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.
+
+.. code-block:: bash
+
+    expreccs -e name_of_folder_for_the_regional_model,name_of_folder_for_the_site_model

docs/_sources/expreccs.utils.reg_sit_given_decks.rst.txt

@@ -0,0 +1,8 @@
+expreccs.utils.reg\_sit\_given\_decks module
+============================================
+
+.. automodule:: expreccs.utils.reg_sit_given_decks
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/_sources/expreccs.utils.rst.txt

@@ -11,6 +11,7 @@ Submodules
    expreccs.utils.inputvalues
    expreccs.utils.mapboundaries
    expreccs.utils.mapproperties
+   expreccs.utils.reg_sit_given_decks
    expreccs.utils.runs
    expreccs.utils.writefile
 

docs/_sources/index.rst.txt

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

docs/_sources/installation.rst.txt

@@ -0,0 +1,136 @@
+============
+Installation
+============
+
+Python package
+--------------
+
+To install the **expreccs** executable in an existing Python environment: 
+
+.. code-block:: 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:
+
+.. code-block:: console
+
+    # Clone the repo
+    git clone https://github.com/cssr-tools/expreccs.git
+    # Get inside the folder
+    cd expreccs
+    # Create virtual environment
+    python3 -m venv vexpreccs
+    # Activate virtual environment
+    source vexpreccs/bin/activate
+    # Upgrade pip, setuptools, and wheel
+    pip install --upgrade pip setuptools wheel
+    # Install the expreccs 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
+--------
+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/expreccs/blob/main/.github/workflows/CI.yml>`_ script 
+    for installation of OPM Flow (binary packages) and the expreccs 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**
+
+.. _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 vexpreccs/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/vexpreccs/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/expreccs/blob/main/pyproject.toml>`_,
+and the opm Python package will be used (this is the default package for reading the simulation files, see the :ref:`overview`).