[DOCS] update

.github/workflows/CI.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.8']
+        python-version: ['3.12']
         os: [ubuntu-latest]
 
     runs-on: ${{ matrix.os }}
@@ -50,3 +50,8 @@ jobs:
     - name: Run the tests
       run: |
         pytest --cov=pymm --cov-report term-missing tests/
+
+    - name: Build documentation
+      run: |
+        pushd docs
+        make html

CONTRIBUTING.md

@@ -1,16 +1,35 @@
 # Contributing
 
-Hola hola :).
-The following is a set of guidelines for contributing to pymm.
+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/pymm/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=pymm --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/pymm/tree/main/docs) folder)
+    * Tip: See the [_CI.yml_](https://github.com/cssr-tools/pymm/blob/main/.github/workflows/CI.yml) script and the [_Actions_](https://github.com/cssr-tools/pymm/actions) for installation of _pymm_, as well as the execution of the six previous steps in Ubuntu 24.10 using Python 3.12.
+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/pymm/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/pymm/blob/main/pyproject.toml). 

README.md

@@ -1,5 +1,5 @@
 [![Build Status](https://github.com/cssr-tools/pymm/actions/workflows/CI.yml/badge.svg)](https://github.com/cssr-tools/pymm/actions/workflows/CI.yml)
-<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.8%20to%203.12-blue.svg"></a>
+<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.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/DOI/10.5281/zenodo.8430989.svg)](https://doi.org/10.5281/zenodo.8430989)
@@ -8,27 +8,30 @@
 
 <img src="docs/text/figs/pymm.gif" width="830" height="700">
 
-This repository provides a workflow to perform computational fluid dynamics (CFD) simulations in microsystems. Given an image of a microsystem and an input text file with few parameters, then the _pymm_ executable process the image and builds the grid using [_Gmsh_](https://gmsh.info) and runs the CFD simulations using [_OpenFOAM_](https://www.openfoam.com).
+## Main feature
+Creation of [_OpenFOAM_](https://www.openfoam.com) simulation models from given input images using [_Gmsh_](https://gmsh.info).
 
 ## Installation
 You will first need to install
 * OpenFOAM (https://www.openfoam.com) (tested with OpenFOAM-12)
 * Gmsh (https://gmsh.info) (tested with Gmsh 4.13.1)
 
-To install the _pymm_ executable in an existing Python environment: 
+To install the _pymm_ executable from the development version: 
 
 ```bash
 pip install git+https://github.com/cssr-tools/pymm.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/pymm.git
 # Get inside the folder
 cd pymm
-# 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 vpymm
 # Activate virtual environment
 source vpymm/bin/activate
@@ -45,12 +48,15 @@ See the [_OpenFOAM page_](https://openfoam.org/download/12-ubuntu/), where from
 ## Running pymm
 You can run _pymm_ as a single command line:
 ```
-pymm -i some_input_image.png -p some_input_parameters.txt -o some_output_folder
+pymm -i name_of_input_image.png -p input_parameters.txt -o output_folder
 ```
-Run `pymm --help` to see all possible command line argument options. Inside the `some_input_parameters.txt` file you provide the framework parameters such as the dimensions of the microsystem, mesh size, inlet pressure, and more. See the .txt files in the examples folder.
+Run `pymm --help` to see all possible command line argument options. Inside the `input_parameters.txt` file you provide the framework parameters such as the dimensions of the microsystem, mesh size, inlet pressure, and more.
 
 ## Getting started
-See the [_examples_](https://cssr-tools.github.io/pymm/examples.html) in the [_documentation_](https://cssr-tools.github.io/pymm/introduction.html). 
+See the [_examples_](https://cssr-tools.github.io/pymm/examples.html) in the [_documentation_](https://cssr-tools.github.io/pymm/introduction.html).
+
+## Citing
+* Landa-Marbán, D. 2023. An open-source image-based framework for CFD in microsystems. https://doi.org/10.5281/zenodo.8430988.
 
 ## Journal papers using pymm
 The following is a list of journal papers in which _pymm_ is used:
@@ -59,5 +65,6 @@ The following is a list of journal papers in which _pymm_ is used:
 1. Liu, N., Haugen, M., Benali, B., Landa-Marbán, D., Fernø, M.A., 2023. Pore-scale kinetics of calcium dissolution and secondary precipitation during geological carbon storage. Chem. Geol. 641, 121782. https://doi.org/10.1016/j.chemgeo.2023.121782.
 
 ## About pymm
-The image-based Python package for computational fluid dynamics pymm is funded by [_Center for Sustainable Subsurface Resources_](https://cssr.no) [project no. 331841] and [_NORCE Norwegian Research Centre As_](https://www.norceresearch.no) [project number 101070]. 
-Contributions are more than welcome using the fork and pull request approach.
+_pymm_, an image-based Python package for computational fluid dynamics, is funded by [_Center for Sustainable Subsurface Resources_](https://cssr.no) [project no. 331841] and [_NORCE Norwegian Research Centre As_](https://www.norceresearch.no) [project number 101070]. 
+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

@@ -9,4 +9,6 @@ The image-based Python package for computational fluid dynamics **pymm** is fund
 Center for Sustainable Subsurface Resources [project no. 331841] and NORCE Norwegian 
 Research Centre As [project number 101070]. 
 
-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/pymm/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=pymm --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/pymm/tree/main/docs>`_ folder)
+
+    .. tip::
+        See the `CI.yml <https://github.com/cssr-tools/pymm/blob/main/.github/workflows/CI.yml>`_ script and the `Actions <https://github.com/cssr-tools/pymm/actions>`_ for installation of pymm, 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/pymm/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/pymm/blob/main/pyproject.toml>`_.

docs/_sources/index.rst.txt

@@ -1,16 +1,18 @@
 .. pymm documentation master file
 
 Welcome to pymm's documentation!
-==================================
+================================
 
 .. toctree::
    :maxdepth: 4
 
    introduction
+   installation
    configuration_file
    examples
    api
    output_folder
+   contributing
    related
    about
 

docs/_sources/installation.rst.txt

@@ -0,0 +1,57 @@
+============
+Installation
+============
+
+The following steps work installing the dependencies in Linux via apt-get using Python3.12.
+While using package managers such as Anaconda, Miniforge, or Mamba might work, these are not tested.
+
+Python package
+--------------
+
+To install the **pymm** executable from the development version: 
+
+.. code-block:: bash
+
+    pip install git+https://github.com/cssr-tools/pymm.git
+
+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
+
+    # Clone the repo
+    git clone https://github.com/cssr-tools/pymm.git
+    # Get inside the folder
+    cd pymm
+    # 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 vpymm)
+    python3 -m venv vpymm
+    # Activate virtual environment
+    source vpymm/bin/activate
+    # Upgrade pip, setuptools, and wheel
+    pip install --upgrade pip setuptools wheel
+    # Install the pymm package
+    pip install -e .
+    # For contributions/testing/linting, install the dev-requirements
+    pip install -r dev-requirements.txt
+
+.. tip::
+
+    Typing **git tag -l** writes all available specific versions.
+
+OpenFOAM
+--------
+
+See the `OpenFOAM page <https://openfoam.org/download/12-ubuntu/>`_, where from OpenFOAM-12 the simulator is available via apt get.
+
+Gmsh
+----
+
+See the `Gmsh page <https://gmsh.info/#Download>`_.
+
+
+.. tip::
+
+    See the `CI.yml <https://github.com/cssr-tools/pymm/blob/main/.github/workflows/CI.yml>`_ script 
+    for installation of pymm in Ubuntu using Python3.12. 

docs/_sources/introduction.rst.txt

@@ -4,8 +4,12 @@ Introduction
 
 .. image:: ./figs/pymm.gif
 
-This documentation describes the content of the **pymm** package.
-This package relies on python packages (e.g., `porespy <https://porespy.org>`_ and 
+This documentation describes the **pymm** tool hosted in `https://github.com/cssr-tools/pymm <https://github.com/cssr-tools/pymm>`_.
+
+Description
+-----------
+
+The **pymm** tool relies on Python packages (e.g., `porespy <https://porespy.org>`_ and 
 `skimage <https://scikit-image.org>`_) to generate the spatial domains for the simulations from
 the microsystem images, and `Gmsh <https://gmsh.info>`_ as a mesh generator. 
 The numerical simulations for the water flow and tracer are performed using 
@@ -30,12 +34,3 @@ where
 - \-t, \-type: Run the whole framework ('all'), only the mesh part ('mesh'), keep the current mesh and only the flow ('flow'), flow and tracer ('flowntracer'), or only tracer ('tracer') ('mesh' by default).
 - \-o, \-output: The base name of the :doc:`output folder <./output_folder>` ('output' by default).
 - \-g, \-gmsh: The full path to the Gmsh executable or simple 'gmsh' if it runs from the terminal ('gmsh' by default).
-
-Installation
-------------
-
-See the `Github page <https://github.com/cssr-tools/pymm>`_.
-
-.. tip::
-
-    See the `CI.yml <https://github.com/cssr-tools/pymm/blob/main/.github/workflows/CI.yml>`_.

docs/_sources/output_folder.rst.txt

@@ -15,4 +15,4 @@ Then after running **pymm**, one could modify the generated OpenFOAM related fil
 run directly the simulations calling the OpenFOAM solvers, e.g., to change additional 
 tolerances that are not currently included in the parameters.txt file and/or to change 
 the numerical schemes (see the OpenFOAM documentation 
-`here <https://www.openfoam.com/documentation/user-guide/6-solving/6.2-numerical-schemes>`_.
+`here <https://www.openfoam.com/documentation/user-guide/6-solving/6.2-numerical-schemes>`_).

docs/_sources/related.rst.txt

@@ -13,14 +13,22 @@ pyopmspe11
 
 `A Python framework using OPM Flow for the CSP SPE11 benchmark project <https://github.com/OPM/pyopmspe11>`_.
 
+*****
+plopm
+*****
+
+.. image:: ./figs/plopm.png
+
+`Quick generation of PNGs, GIFs, and VTKs from a OPM Flow type model <https://github.com/cssr-tools/plopm>`_.
+
 *************
 pyopmnearwell
 *************
 
 .. image:: ./figs/pyopmnearwell.gif
     :scale: 50%
 
-`A framework to simulate near well dynamics using OPM Flow <https://github.com/daavid00/pyopmnearwell>`_.
+`A framework to simulate near well dynamics using OPM Flow <https://github.com/cssr-tools/pyopmnearwell>`_.
 
 ******
 pycopm
@@ -31,22 +39,14 @@ pycopm
 
 `Simplified and flexible framework for coarsening geological models <https://github.com/cssr-tools/pycopm>`_.
 
-*****
-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
 ********
 
 .. image:: ./figs/expreccs.gif
     :scale: 50%
 
-`Expansion of ResourCes for CO2 Storage on the Horda Platform <https://github.com/daavid00/expreccs>`_.
+`A Python framework using OPM Flow to simulate regional and site reservoirs for CO2 storage <https://github.com/cssr-tools/expreccs>`_.
 
 *******
 ad-micp

docs/_static/basic.css

@@ -1,12 +1,5 @@
 /*
- * basic.css
- * ~~~~~~~~~
- *
  * Sphinx stylesheet -- basic theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 /* -- main layout ----------------------------------------------------------- */
@@ -115,15 +108,11 @@ img {
 /* -- search page ----------------------------------------------------------- */
 
 ul.search {
-    margin: 10px 0 0 20px;
-    padding: 0;
+    margin-top: 10px;
 }
 
 ul.search li {
-    padding: 5px 0 5px 20px;
-    background-image: url(file.png);
-    background-repeat: no-repeat;
-    background-position: 0 7px;
+    padding: 5px 0;
 }
 
 ul.search li a {