Adding API level documentation

.github/workflows/ci_pycopm_ubuntu.yml

@@ -34,6 +34,7 @@ jobs:
       run: |
         black --target-version py314 src/ tests/ --check
         pylint src/ tests/
+        ruff check src/ tests/
         mypy --ignore-missing-imports src/ tests/
 
     - name: Run tests

CONTRIBUTING.md

@@ -6,6 +6,7 @@ Contributions are more than welcome using the fork and pull request approach 
 
 - We use [_Black code formatting_](https://black.readthedocs.io/en/stable/)
 - We use [_Pylint_](https://pylint.readthedocs.io/en/stable/)
+- We use [_Ruff_](https://docs.astral.sh/ruff/)
 - We document our code
 
 ## Contribute to the software
@@ -15,6 +16,7 @@ Contributions are more than welcome using the fork and pull request approach 
     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 --target-version py314 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. **ruff check src/ tests/** (this also 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 --basetemp=test_outputs tests/ -n auto** (this runs locally the tests, and might rise issues that need to be fixed before the pull request)
     1. **pycopm -i examples/decks/HELLO_WORLD.DATA -c 5,5,1 -m all -o output** (this runs the hello world example, which succeeds if the file output/HELLO_WORLD_PYCOPM.EGRID is created)

README.md

@@ -1,7 +1,7 @@
 [![Build Status](https://github.com/cssr-tools/pycopm/actions/workflows/ci_pycopm_ubuntu.yml/badge.svg)](https://github.com/cssr-tools/pycopm/actions/workflows/ci_pycopm_ubuntu.yml)
 [![Build Status](https://github.com/cssr-tools/pycopm/actions/workflows/ci_pycopm_macos.yml/badge.svg)](https://github.com/cssr-tools/pycopm/actions/workflows/ci_pycopm_macos.yml)
 [![Build Status](https://github.com/cssr-tools/pycopm/actions/workflows/ci_pycopm_docker.yml/badge.svg)](https://github.com/cssr-tools/pycopm/actions/workflows/ci_pycopm_docker.yml)
-<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11%20to%203.14-blue.svg"></a>
+<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%20to%203.14-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)
 <img src="docs/text/figs/pycopm.png" width="900" height="380">

dev-requirements.txt

@@ -3,5 +3,6 @@ mypy
 pylint
 pytest-cov
 pytest-xdist
+ruff
 sphinx
 sphinx-rtd-theme

docs/_sources/configuration_file.rst.txt

@@ -18,10 +18,10 @@ The first input parameter is:
     :linenos:
 
     # Set mpirun, the full path to the flow executable, and simulator flags (except --output-dir)
-    flow = "flow --newton-min-iterations=1"
+    flow_command = "flow --newton-min-iterations=1"
 
 If **flow** is not in your path, then write the full path to the executable, as well as adding mpirun
-if this is supported in your machine (e.g., flow = "mpirun -np 8 /Users/dmar/Github/opm/build/opm-simulators/bin/flow -\-newton-min-iterations=1").
+if this is supported in your machine (e.g., flow_command = "mpirun -np 8 /Users/dmar/Github/opm/build/opm-simulators/bin/flow -\-newton-min-iterations=1").
 
 The next entries define the following parameters:
 
@@ -30,32 +30,31 @@ The next entries define the following parameters:
     :lineno-start: 4
 
     # Set the model parameters
-    field = "norne"  # Geological model (norne or drogon)
-    mode = "ert" # Mode to run (single-run, files, or ert)
-    X = [0,2,0,2,2,0,2,0,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,0,2,0,2,2,0,2,2,0,2,2,2,2,0] # Array of x-coarsening 
-    Y = [0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,0,2,0,2,0,2,0,2,0,2,0,2,0,2,0,2,2,2,2,2,2,2,2,2,0] # Array of y-coarsening 
-    Z = [0,0,2,0,0,2,2,2,2,2,0,2,2,2,2,2,0,0,2,0,2,2,0] # Array of z-coarsening
-    net = 2 # Number of ensembles
-    mep = 2 # Maximum number of ensembles running in parallel
-    mrt = 600 # Maximum runtime in seconds of a realization. A value of 0 means unlimited runtime. 
-    mrn = 2 # Minimum number of realizations that must have succeeded for the simulation to be regarded as a success.
-    rds = 7 # Set a specific seed for reproducibility. A value of 0 means no seed.  
-    obs = "observations_training" # Name of the observation file for the hm ('observations_training', 'observations_test', or 'observations_complete')
-    deck = 0 # Select which coarser deck to use: 0 -> default one or 1 -> LET sat functions
-    letsatn = 1 # For norne: for the LET coarser deck, select: 0 -> SATNUM=1, 1 -> SATNUM is computed from Sandve et al 2022, 2 -> #SATNUM=#Cells.
-    cporv = 0 # 0 -> no corrections for lost porv, 1 -> correct it on all cells
-    initial = 0 # Initialization 0 -> Equil 1->INIT from fine-scale
-    error = [0.1,0.1,0.1] # Error WWPR, WOPR, and WGPR
-    minerror = [100,100,100000] # Minimum error of WWPR, WOPR, and WGPR
-    date = 2005-03-01 # Last date to HM
-    suffixes = ["PRT"] # Delete files with this suffix to save storage
+    model_name = "norne"  # Geological model (norne or drogon)
+    execution_mode = "single-run" # Mode to run (single-run, files, or ert)
+    x_coarsening = [0,2,0,2,2,0,2,0,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,0,2,0,2,2,0,2,2,0,2,2,2,2,0] # Array of x-coarsening 
+    y_coarsening = [0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,2,0,2,0,2,0,2,0,2,0,2,0,2,0,2,0,2,0,2,0,2,2,2,2,2,2,2,2,2,0] # Array of y-coarsening 
+    z_coarsening = [0,0,2,0,0,2,2,2,2,2,0,2,2,2,2,2,0,0,2,0,2,2,0] # Array of z-coarsening
+    ensemble_size = 2 # Number of ensembles
+    max_parallel_realizations = 2 # Maximum number of ensembles running in parallel
+    max_realization_runtime_seconds = 600 # Maximum runtime in seconds of a realization. A value of 0 means unlimited runtime. 
+    min_successful_realizations = 2 # Minimum number of realizations that must have succeeded for the simulation to be regarded as a success.
+    random_seed = 7 # Set a specific seed for reproducibility. A value of 0 means no seed.  
+    saturation_function_method = 0 # Select which coarser deck to use: 0 -> default one or 1 -> LET sat functions
+    satnum_generation_method = 1 # For norne: for the LET coarser deck, select: 0 -> SATNUM=1, 1 -> SATNUM is computed from Sandve et al 2022, 2 -> #SATNUM=#Cells.
+    pore_volume_correction = 0 # 0 -> no corrections for lost porv, 1 -> correct it on all cells
+    initialization_method = 0 # Initialization 0 -> Equil 1->INIT from fine-scale
+    observation_relative_errors = [0.1,0.1,0.1] # Error WWPR, WOPR, and WGPR
+    observation_minimum_errors = [100,100,100000] # Minimum error of WWPR, WOPR, and WGPR
+    history_matching_end_date = 2005-03-01 # Last date to HM
+    cleanup_file_suffixes = ["PRT"] # Delete files with this suffix to save storage
 
 The single-run mode results in Flow running only one simulation and the information shown in
 the terminal is the one from the Flow executable instead of the ERT one. The ert option calls the ERT
 executable and the command values are given after in the same input file which are discussed later. The
 files option only writes the needed input files for ERT. 
 
-The X, Y, and Z inputs define which pillars are removed (value 2) in the x, y, and z direction respectively. 
+The x-, y, and z-coarsening inputs define which pillars are removed (value 2) in the x, y, and z direction respectively. 
 
 .. figure:: figs/index.png
 .. figure:: figs/index_plopm.png
@@ -70,8 +69,7 @@ Values of 0 do not remove the pilar.
 
 The remaining lines define the number of ensembles, maximum number of ensembles running in parallel, the maximum runtime in seconds to stop a realization
 (0 means unlimited time), the minimum number of realizations for the simulation to be regarded as a success,
-the random seed for reproducibility (0 means no seed), the observation file for the hm 
-('observations_training.data', 'observations_test.data', or 'observations_complete.data'), to use the saturation
+the random seed for reproducibility (0 means no seed), to use the saturation
 functions from opm-tests norne or to use the LET saturation functions, defining if each of the coarser cells is
 considered as only one region, regions as in Sandve et al 2022 or as a different SATNUM region, and the cporv entry
 sets if the ntg and poro properties on the cells on the boundary are modified to account for lost PV respect to the
@@ -85,7 +83,7 @@ If the ert option is activated, then the following input:
     :lineno-start: 25
 
     # Set the command line for the ert executable (gui, test_run, ensemble_experiment, ensemble_smoother, iterative_ensemble_smoother, and es_mda) and flags
-    ert = "es_mda --weights 1"
+    ert_arguments = "es_mda --weights 1"
 
 sets the type of ert option and command flags. Currently, the options supported are gui, test_run, ensemble_experiment, ensemble_smoother, iterative_ensemble_smoother, and es_mda.
 Confer to the `ERT <https://ert.readthedocs.io/en/latest/>`_ documentation for a full description of these options.
@@ -97,7 +95,7 @@ The LET saturation function parameters for each of the coarsened cells are given
     :lineno-start: 28
 
     # Properties LET saturation functions: name, value, use dist in hm?, dist, distpara, distpara
-    LET = [["lw", 3, 1, "UNIFORM", 1.1,   5],
+    let_parameters = [["lw", 3, 1, "UNIFORM", 1.1,   5],
     ["ew",        1, 1, "UNIFORM", -1,    2], 
     ["tw",        3, 1, "UNIFORM", 1.1,   5], 
     ["lo",        3, 1, "UNIFORM", 1.1,   5], 
@@ -125,7 +123,7 @@ Finally, we set if the permeabilities will be considered for the hm:
     :lineno-start: 48
 
     # Coarser rock properties: name, use dist in hm?, coarsing approach (max or mean)
-    rock = [["PERMX", 1, "max"],
+    rock_property_settings = [["PERMX", 1, "max"],
     ["PERMY",         0, "max"],
     ["PERMZ",         0, "max"]]
 

docs/_sources/contributing.rst.txt

@@ -11,7 +11,7 @@ Ground Rules
 ============
 
 - We use Black code formatting
-- We use Pylint
+- We use Pylint and Ruff code analysis tools
 - We document our code
 
 ==========================
@@ -24,6 +24,7 @@ Contribute to the software
     #. **pip install -r dev-requirements.txt** (this installs the `dev-requirements.txt <https://github.com/cssr-tools/pycopm/blob/main/dev-requirements.txt>`_)
     #. **black \-\-target-version py314 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)
+    #. **ruff check src/ tests/** (this also 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 \-\-basetemp=test_outputs tests/ -n auto** (this runs locally the tests, and might rise issues that need to be fixed before the pull request)
     #. **pycopm -i examples/decks/HELLO_WORLD.DATA -c 5,5,1 -m all -o output** (this runs the hello world example, which succeeds if the file output/HELLO_WORLD_PYCOPM.EGRID is created)

docs/_sources/installation.rst.txt

@@ -4,7 +4,7 @@ Installation
 
 The following steps work installing the dependencies in Ubuntu via apt-get or in macOS using `brew <https://brew.sh>`_ or `macports <https://www.macports.org>`_.
 While using package managers such as Anaconda, Miniforge, or Mamba might work, these are not tested.
-The supported Python versions are 3.11 to 3.14.
+The supported Python versions are 3.12 to 3.14.
 
 .. note::
 

docs/_sources/introduction.rst.txt

@@ -38,17 +38,17 @@ where
 -f          OPM Flow path to executable (e.g., /home/pycopm/build/opm-simulators/bin/flow), or just 'flow' if this was installed via binaries or if the folder where flow is built has been added to your path ('flow' by default).
 -m          Execute a dry run of the input deck to generate the static properties ('prep'), generate only the modified files ('deck'), only exectute a dry run on the generated model ('dry'), 'prep_deck', 'deck_dry', or do all ('all') ('prep_deck' by default).
 -v          The location to extract the sub model which can be assigned by region values, e.g., 'fipnum 2,4' extracts the cells with fipnums equal to 2 or 4, by a polygon given the xy locations in meters, e.g., 'xypolygon [0,0] [30,0] [30,30] [0,0]', or by the name of the well and three different options for the neighbourhood: box, diamond, and diamondxy, where for box the i, j, and k interval around the connections are given, e.g., 'welln box [-1,1] [-2,2] [0,3]' results in a vicinity with 1 pm cell in the x direction, 2 pm cells in the y direction and only 3 cells in the k positive direction, while the diamond considers only the given number of cells around the well connections (e.g., 'welln diamond 2') and diamondxy it is restricted to the xy plane ('' by default).
--c          Level of coarsening in the x, y, and z dir ('2,2,2' by default; either use this flag or the -x, -y, and -z ones).
+-c          Level of coarsening in the x, y, and z dir (',' by default; either use this flag or the -x, -y, and -z ones).
 -x          Array of x-coarsening, e.g., if the grid has 6 cells in the x direction, then '0,2,0,2,0,2,0' would generate a coarsened model with 3 cells, while '0,2,2,2,2,2,0' would generate a coarser model with 1 cell, i.e., 0 keeps the pilars while 2 removes them. As an alternative, the range of the cells to coarse can be given separate them by commas, e.g., '1:3,5:6' generates a coarsened model with 3 cells where the cells with the first three and two last i indices are coarsened to one ('' by default),
 -y          Array of y-coarsening, see the description for -x ('' by default).
 -z          Array of z-coarsening, see the description for -x ('' by default).
 -g          Level of grid refinement in the x, y, and z dir ('' by default).
 -rx         Array of x-refinement, e.g., if the grid has 6 cells in the x direction, then '0,1,0,2,0,4' would generate a refined model with 13 cells, while 0,0,0,1,0,0 would generate a refined model with 7 cells ('' by default).
 -ry         Array of y-refinement, see the description for -rx ('' by default).
 -rz         Array of z-refinement, see the description for -rx ('' by default).
--a          In coarsening, use 'min', 'max', or 'mode' to scale the actnum, e.g., 'min' makes the new coarser cell inactive if at least one cell is inactive, while 'max' makes it active it at least one cell is active ('mode' by default).
--n          In coarsening, use 'min', 'max', or 'mode' to scale endnum, eqlnum, fipnum, fluxnum, imbnum, miscnum, multnum, opernum, pvtnum, rocknum, and satnum ('mode' by default).
--s          In coarsening, use 'min', 'max', 'mean', or 'pvmean' to scale permx, permy, permz, poro, swatinit, disperc, thconr, and all mult(-)xyz ('' by default, i.e., using the arithmetic average for permx/permy, harmonic average for permz, volume weighted mean for mult(-)xyz, and the pore volume weighted mean ('pvmean') for the rest).
+-a          In coarsening, use 'min', 'max', or 'mode' to scale the actnum, e.g., 'min' makes the new coarser cell inactive if at least one cell is inactive, while 'max' makes it active it at least one cell is active ('mode' by default). For range coarsenings using -z, then one can specify this per layer, e.g., '-z 1:10,11:15 -a min,mode'.
+-n          In coarsening, use 'min', 'max', or 'mode' to scale endnum, eqlnum, fipnum, fluxnum, imbnum, miscnum, multnum, opernum, pvtnum, rocknum, and satnum ('mode' by default). For range coarsenings using -z, then one can specify this per layer, e.g., '-z 1:3,4 -a max,min'.
+-s          In coarsening, use 'min', 'max', 'mean', or 'pvmean' to scale permx, permy, permz, poro, swatinit, disperc, thconr, and all mult(-)xyz ('' by default, i.e., using the arithmetic average for permx/permy, harmonic average for permz, volume weighted mean for mult(-)xyz, and the pore volume weighted mean ('pvmean') for the rest). . For range coarsenings using -z, then one can specify this per layer, e.g., '-z 1:40,41:43,44:50 -a pvmean,max,pvmean'.
 -p          In coarsening, set to '1' to add the removed pore volume to the closest coarser cells, while in submodels '1' adds the porv from outside on the boundary of the submodel, '2' adds the corner regions (e.g., below the mini and minj from the input model) to the corners in the submodel, '3' distributes the porv uniformly along the boundary, and '4' distributes it on the whole submodel ('0' by default, i.e., no porv correction).
 -q          Adjust the pv to the initial FGIP and FOIP from the input deck; use this option only for systems with initial oil, gas, and water, e.g., norne or drogon, but no in Smeaheia ('0' by default, '1' to enable).
 -t          In coarsening, write and use upscaled transmissibilities by ('1') armonic averaging and summing the transmissibilities in the corresponding coarsening direction and ('2') scaling the face transmissibily on the coarse faces ('0' by default, i.e., transmissibilities are not used).
@@ -61,3 +61,4 @@ where
 -d          Options to transform the x,y,z coordinates: 'translate [10,-5,4]' adds the values in meters to the coordinates, 'scale [1,2,3]' multiplies the coordinates by the given values respectively, and 'rotatexy 45' applies a rotation in degrees in the xy plane (rotatexz and rotateyz applies a rotation around the y and x axis respectively) ('' by default).
 -explicit   Set to 1 to explicitly write the cell values in the SOLUTION section in the deck ('0' by default).
 -dual       Set the criterium to differentiate net and non-net in coarsening using a static variable, e.g., 'poro <= 0.1' ('' by default).
+-precision  Set the number of significant digits used when writing floating-point values, or 0 to use machine precision

docs/_sources/pycopm.utils.coarsening.rst.txt

@@ -0,0 +1,8 @@
+pycopm.utils.coarsening module
+==============================
+
+.. automodule:: pycopm.utils.coarsening
+   :members:
+   :private-members:
+   :show-inheritance:
+   :undoc-members:

docs/text/pycopm.utils.generate_files.rst → docs/_sources/pycopm.utils.generate_decks.rst.txt

@@ -1,7 +1,7 @@
-pycopm.utils.generate\_files module
+pycopm.utils.generate\_decks module
 ===================================
 
-.. automodule:: pycopm.utils.generate_files
+.. automodule:: pycopm.utils.generate_decks
    :members:
    :private-members:
    :show-inheritance:

docs/_sources/pycopm.utils.refinement.rst.txt

@@ -0,0 +1,8 @@
+pycopm.utils.refinement module
+==============================
+
+.. automodule:: pycopm.utils.refinement
+   :members:
+   :private-members:
+   :show-inheritance:
+   :undoc-members:

docs/_sources/pycopm.utils.rst.txt

@@ -7,14 +7,15 @@ Submodules
 .. toctree::
    :maxdepth: 4
 
+   pycopm.utils.coarsening
    pycopm.utils.files_writer
-   pycopm.utils.generate_files
-   pycopm.utils.grid_builder
+   pycopm.utils.generate_decks
    pycopm.utils.input_values
-   pycopm.utils.mapping_methods
    pycopm.utils.parser_deck
-   pycopm.utils.properties_builder
+   pycopm.utils.refinement
    pycopm.utils.runs_executer
+   pycopm.utils.transformation
+   pycopm.utils.vicinity
 
 Module contents
 ---------------