Merge pull request #15 from daavid00/developing

Updates before the v2024.10 release

CONTRIBUTING.md

@@ -1,16 +1,35 @@
 # Contributing
 
-Hola hola 🙂.
-The following is a set of guidelines for contributing to pycopm.
+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/pycopm/blob/main/dev-requirements.txt))
+    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=pycopm --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/pycopm/tree/main/docs) folder)
+    * Tip: See the [_CI.yml_](https://github.com/cssr-tools/pycopm/blob/main/.github/workflows/CI.yml) script and the [_Actions_](https://github.com/cssr-tools/pycopm/actions) for installation of pycopm, 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/pycopm/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/pycopm/blob/main/pyproject.toml). 

README.md

@@ -12,23 +12,24 @@ Creation of coarser models from given input decks.
 
 ## Installation
 You will first need to install
-* OPM Flow (https://opm-project.org, Release 2024.04 or current master branches)
+* OPM Flow (https://opm-project.org, Release 2024.10 or current master branches)
 
-To install the _pycopm_ executable in an existing Python environment:
+To install the _pycopm_ executable from the development version:
 
 ```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:
+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/pycopm.git
 # Get inside the folder
 cd pycopm
-# Create virtual environment (for higher versions of Python than the default one, e.g., python3.12 -m venv vpycopm)
+# For a specific version (e.g., v2024.10), or skip this step (i.e., edge version)
+git checkout v2024.10
+# Create virtual environment (to specific Python, python3.12 -m venv vpycopm)
 python3 -m venv vpycopm
 # Activate virtual environment
 source vpycopm/bin/activate
@@ -40,7 +41,7 @@ pip install -e .
 pip install -r dev-requirements.txt
 ``` 
 
-See the [_installation_](https://cssr-tools.github.io/pycopm/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/pycopm/installation.html) for further details on building OPM Flow from the master branches in Linux, Windows, and macOS. 
 
 ## Running pycopm
 You can run _pycopm_ as a single command line:
@@ -65,4 +66,5 @@ The following is a list of manuscripts in which _pycopm_ is used:
 The _pycopm_ package is being funded by the [_Center for Sustainable Subsurface Resources (CSSR)_](https://cssr.no) 
 [project no. 331841] and by [_Expansion of Resources for CO2 Storage on the Horda Platform (ExpReCCS)_](https://www.norceresearch.no/en/projects/expansion-of-resources-for-co2-storage-on-the-horda-platform-expreccs) [project no. 336294].
 This is work in progress.
-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 a new feature, please request this by raising an issue.

docs/_sources/about.rst.txt

@@ -7,5 +7,9 @@ About pycopm
 
 **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] 
 and by `Expansion of Resources for CO2 Storage on the Horda Platform (ExpReCCS) <https://www.norceresearch.no/en/projects/expansion-of-resources-for-co2-storage-on-the-horda-platform-expreccs>`_ [project no. 336294].
+
 This is work in progress.
-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 a new feature, please request this raising an issue.

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/pycopm/blob/main/dev-requirements.txt>`_)
+    #. **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=pycopm --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/pycopm/tree/main/docs>`_ folder)
+
+    .. tip::
+        See the `CI.yml <https://github.com/cssr-tools/pycopm/blob/main/.github/workflows/CI.yml>`_ script and the `Actions <https://github.com/cssr-tools/pycopm/actions>`_ for installation of pycopm, 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/pycopm/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/pycopm/blob/main/pyproject.toml>`_.

docs/_sources/examples.rst.txt

@@ -94,7 +94,7 @@ We use our `plopm <https://github.com/cssr-tools/plopm>`_ friend to generate PNG
     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.
+    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.
 
 Drogon
 ------
@@ -152,7 +152,7 @@ If we run these three models using OPM Flow, then we can compare the summary vec
 
 .. code-block:: bash
 
-    plopm -i 'DROGON_HIST DROGON_HIST_PYCOPM_PYCOPM DROGON_2TIMES_COARSER' -v 'FOIP,FOPR,TCPU' -tunits y -f 14 -subfigs 2,2 -delax 1 -loc empty,empty,empty,center -d 10,5 -xformat '.1f' -xlnum 6 -ylabel 'sm$^3$ sm$^3$/day seconds' -t 'Field oil in place  Field oil production rate  Simulation time' -labels 'DROGON  DROGON 3XZ COARSER  DROGON 2XYZ COARSER' -save drogon_pycopm_comparison -yformat '.2e,.0f,.0f'
+    plopm -i 'DROGON_HIST DROGON_HIST_PYCOPM_PYCOPM DROGON_2TIMES_COARSER' -v 'FOIP,FOPR,TCPU' -tunits y -f 14 -subfigs 2,2 -delax 1 -loc empty,empty,empty,center -d 10,5 -xformat '.1f' -xlnum 6 -ylabel 'sm$^3$  sm$^3$/day  seconds' -t 'Field oil in place  Field oil production rate  Simulation time' -labels 'DROGON  DROGON 3XZ COARSER  DROGON 2XYZ COARSER' -save drogon_pycopm_comparison -yformat '.2e,.0f,.0f'
 
 .. figure:: figs/drogon_pycopm_comparison.png
 
@@ -164,7 +164,7 @@ We can also make a nice GIF by executing:
 
 .. code-block:: bash
 
-    plopm -v sgas -subfigs 1,3 -i 'DROGON_HIST DROGON_HIST_PYCOPM_PYCOPM DROGON_2TIMES_COARSER' -d 16,10.5 -r 0,3 -m gif -dpi 1000 -t "DROGON  DROGON 3XZ COARSER  DROGON 2XYZ COARSER" -f 16 -interval 2000 -loop 1 -cformat .2f -cbsfax 0.30,0.01,0.4,0.02 -s ,,1 -rotate -30 -xunits km -yunits km -xformat .0f -yformat .0f -c cet_rainbow_bgyrm_35_85_c69
+    plopm -v sgas -subfigs 1,3 -i 'DROGON_HIST DROGON_HIST_PYCOPM_PYCOPM DROGON_2TIMES_COARSER' -d 16,10.5 -r 0,3 -m gif -dpi 300 -t "DROGON  DROGON 3XZ COARSER  DROGON 2XYZ COARSER" -f 16 -interval 2000 -loop 1 -cformat .2f -cbsfax 0.30,0.01,0.4,0.02 -s ,,1 -rotate -30 -xunits km -yunits km -xformat .0f -yformat .0f -c cet_rainbow_bgyrm_35_85_c69
 
 .. figure:: figs/sgas.gif
 

docs/_sources/index.rst.txt

@@ -7,11 +7,13 @@ Welcome to pycopm's documentation!
    :maxdepth: 4
 
    introduction
+   theory
    installation
    configuration_file
    examples
    api
    output_folder
+   contributing
    related
    about
 

docs/_sources/installation.rst.txt

@@ -2,16 +2,19 @@
 Installation
 ============
 
+The following steps work installing the dependencies in Linux via apt-get or in macOS using brew or macports.
+While using package managers such as Anaconda, Miniforge, or Mamba might work, these are not tested.
+
 Python package
 --------------
 
-To install the **pycopm** executable in an existing Python environment: 
+To install the **pycopm** executable from the development version: 
 
 .. code-block:: 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 
+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:
 
 .. code-block:: console
@@ -20,7 +23,9 @@ install the Python requirements in a virtual environment with the following comm
     git clone https://github.com/cssr-tools/pycopm.git
     # Get inside the folder
     cd pycopm
-    # Create virtual environment
+    # For a specific version (e.g., v2024.10), or skip this step (i.e., edge version)
+    git checkout v2024.10
+    # Create virtual environment (to specific Python, python3.12 -m venv vpycopm)
     python3 -m venv vpycopm
     # Activate virtual environment
     source vpycopm/bin/activate
@@ -31,21 +36,25 @@ install the Python requirements in a virtual environment with the following comm
     # For contributions/testing/linting, install the dev-requirements
     pip install -r dev-requirements.txt
 
+.. tip::
+
+    Typing **git tag -l** writes all available specific versions.
+
 OPM Flow
 --------
 You also need to install:
 
-* OPM Flow (https://opm-project.org, Release 2024.04 or current master branches)
+* OPM Flow (https://opm-project.org, Release 2024.10 or current master branches)
 
 .. tip::
 
     See the `CI.yml <https://github.com/cssr-tools/pycopm/blob/main/.github/workflows/CI.yml>`_ script 
-    for installation of OPM Flow (binary packages) and the pycopm package in Linux. 
+    for installation of OPM Flow (binary packages) and the pycopm package in Ubuntu. 
 
 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.): 
+in the terminal the following lines (which in turn should build flow in the folder ./build/opm-simulators/bin/flow): 
 
 .. code-block:: console
 
@@ -106,7 +115,7 @@ For macOS, there are no available binary packages, so OPM Flow needs to be built
     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/opm-$repo
+        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/opm-$repo
         make -j5 opm$repo
         cd ../..
     done    

docs/_sources/related.rst.txt

@@ -37,7 +37,7 @@ expreccs
 .. image:: ./figs/expreccs.gif
     :scale: 50%
 
-`Expansion of ResourCes for CO2 Storage on the Horda Platform <https://github.com/cssr-tools/expreccs>`_.
+`A Python framework using OPM Flow to simulate regional and site reservoirs for CO2 storage <https://github.com/cssr-tools/expreccs>`_.
 
 *******
 ad-micp