Support for toml input files

Author: daavid00

.github/workflows/CI.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.8']
+        python-version: ['3.11']
         os: [ubuntu-latest]
 
     runs-on: ${{ matrix.os }}

.gitignore

@@ -180,9 +180,7 @@ examples/hello_world/spe11a
 examples/hello_world/spe11b
 examples/hello_world/spe11c
 playground
-tests/configs/test_compare
-tests/configs/output
-tests/configs/spe11a
-tests/configs/spe11b
-tests/configs/spe11c
-tests/configs/check_format.py
+
+# Tests
+tests/configs/check_format.py
+**/tests/configs/*/

README.md

@@ -46,10 +46,10 @@ See the [_installation_](https://OPM.github.io/pyopmspe11/installation.html) for
 ## Running pyopmspe11
 You can run _pyopmspe11_ as a single command line:
 ```
-pyopmspe11 -i configuration_file.txt
+pyopmspe11 -i configuration_file
 ```
 Run `pyopmspe11 --help` to see all possible command line 
-argument options. Inside the `configuration_file.txt` you provide the path to the flow executable and simulation parameters. See the .txt files in the [_examples_](https://github.com/OPM/pyopmspe11/tree/main/examples), [_benchmark_](https://github.com/OPM/pyopmspe11/tree/main/benchmark), and [_tests_](https://github.com/OPM/pyopmspe11/tree/main/tests/configs) folders.
+argument options. Inside the `configuration_file` you provide the path to the flow executable and simulation parameters. See the .txt and .toml files in the [_examples_](https://github.com/OPM/pyopmspe11/tree/main/examples), [_benchmark_](https://github.com/OPM/pyopmspe11/tree/main/benchmark), and [_tests_](https://github.com/OPM/pyopmspe11/tree/main/tests/configs) folders.
 
 ## Getting started
 See the [_examples_](https://OPM.github.io/pyopmspe11/examples.html) in the [_documentation_](https://OPM.github.io/pyopmspe11/introduction.html). 

docs/_sources/configuration_file.rst.txt

@@ -1,14 +1,25 @@
-==================
+******************
 Configuration file
-==================
+******************
+
+In the initial development of **pyopmspe11**, the adopted configuration file format was the
+one described below, i.e., via :ref:`txt` files. The current development of **pyopmspe11** considers
+:ref:`toml` files. To keep compatibility with previous configuration files, then support for :ref:`txt` files
+will be kept, while new features will by added using :ref:`toml` configuration files.
+
+.. _txt:
+
+===
+txt 
+===
 
 The first input parameter in the configuration file is:
 
 .. code-block:: python
     :linenos:
 
     """Set the full path to the flow executable and flags"""
-    flow --linear-solver=cprw --enable-tuning=true --enable-opm-rst-file=true --output-extra-convergence-info=steps,iterations --newton-min-iterations=1
+    flow --enable-tuning=true --enable-opm-rst-file=true --output-extra-convergence-info=steps,iterations
 
 If **flow** is not in your path, then write the full path to the executable
 (e.g., /Users/dmar/opm/build/opm-simulators/bin/flow). We also add in the same 
@@ -23,9 +34,9 @@ line as many flags as required (see the OPM Flow documentation `here <https://op
     flow simulator to improve/fix convergence and mass issues (i.e., by setting the flag \-\-linear-solver=cprw to change the linear solver,
     by tightening the cnv tolerances (\-\-tolerance-cnv), etc.).
 
-****************************
+----------------------------
 Reservoir-related parameters
-****************************
+----------------------------
 
 The following input lines in the configuration file are:
 
@@ -35,7 +46,7 @@ The following input lines in the configuration file are:
 
     """Set the model parameters"""
     spe11c master     #Name of the spe case (spe11a, spe11b, or spe11c) and OPM Flow version (master or release)
-    complete gaswater #Name of the co2 model (immiscible, convective [convective requires a Flow version newer than 22-08-2024], or complete) and co2store implementation (gaswater or gasoil [oil properties are set to water internally in OPM flow])
+    complete gaswater #Name of the co2 model (immiscible, convective, or complete) and co2store implementation (gaswater or gasoil [oil properties are set to water internally in OPM flow])
     corner-point      #Type of grid (cartesian, tensor, or corner-point)
     8400 5000 1200    #Length, width, and depth [m]
     420               #If cartesian, number of x cells [-]; otherwise, variable array of x-refinment
@@ -68,9 +79,9 @@ resulting in 18 levels. Then, the z-refinment in each of these levels is set. Se
     The top figure shows the 7 different facies, while the bottom figure shows the fipnum numbers used to identify
     the boxes (A, B, and C), sensors, and the required regions to report the benchmark data.  
 
-***********************
+-----------------------
 Soil-related parameters
-***********************
+-----------------------
 The following entries define the properties of the different facies:
 
 .. code-block:: python
@@ -108,9 +119,9 @@ The following entries define the properties of the different facies:
 
     Visualization in ResInsight of the relative permeability and capillary pressure functions in the facie 1.
 
-***********************
+-----------------------
 Well-related parameters
-***********************
+-----------------------
 The last part of the configuration file sets the wells radius, location, and the injection schedule.
 
 .. code-block:: python
@@ -133,4 +144,84 @@ The last part of the configuration file sets the wells radius, location, and the
       500   100   100 1  0 10 1  0 10
     
 .. warning::
-    Keep the linebreak between the sections (in the current implementation this is used for the reading of the parameters).
+    Keep the linebreak between the sections (in the current implementation this is used for the reading of the parameters).
+
+.. _toml:
+
+====
+toml 
+====
+
+The previous configuration file can be written using the widely in-use `toml format <https://docs.python.org/3/library/tomllib.html>`_ as:
+
+.. code-block:: python
+    :linenos:
+
+    # Set the full path to the flow executable and flags
+    flow = "flow --enable-tuning=true --enable-opm-rst-file=true --output-extra-convergence-info=steps,iterations"
+
+    # Set the model parameters
+    spe11 = "spe11c" # Name of the spe case (spe11a, spe11b, or spe11c)
+    version = "release" # OPM Flow version (release or master)
+    model = "complete" # Name of the co2 model (immiscible, convective, or complete)
+    co2store = "gaswater" # co2store implementation (gaswater or gasoil [oil properties are set to water internally in OPM flow])
+    grid = "corner-point" # Type of grid (cartesian, tensor, or corner-point)
+    dims = [8400.0, 5000.0, 1200.0] # Length, width, and depth [m]
+    x_n = [420] # If cartesian, number of x cells [-]; otherwise, variable array of x-refinment
+    y_n = [30, 40, 50, 40, 30] # If cartesian, number of y cells [-]; otherwise, variable array of y-refinment [-] (for spe11c)
+    z_n = [5, 3, 1, 2, 3, 2, 4, 4, 10, 4, 6, 6, 4, 8, 4, 15, 30, 9] # If cartesian, number of z cells [-]; if tensor, variable array of z-refinment; if corner-point, fix array of z-refinment (18 entries)
+    temperature = [70.0, 36.12] # Temperature bottom and top rig [C]
+    datum = 300 # Datum [m]
+    pressure = 3e7 # Pressure at the datum [Pa]
+    kzMult = 0.1 # Multiplier for the permeability in the z direction [-] 
+    diffusion = [1e-9, 2e-8] # Diffusion (in liquid and gas) [m^2/s]
+    rockExtra = [8.5e-1, 2500.0] # Rock specific heat capacity [kJ/(kg K)] and rock density [kg/m^3] (for spe11b/c)
+    pvAdded = 5e4  # Extra pore volume per area on lateral boundaries [m] (for spe11b/c)
+    widthBuffer = 1 # Width of buffer cells [m] (for spe11b/c)
+    elevation = 150 # Maximum elevation difference (relative to the baseline gradient) of the arch in the y direction [m] (for spe11c)
+    backElevation = 10 # Back boundary elevation w.r.t the front boundary [m] (for spe11c)
+    dispersion = [10, 10, 10, 10, 10, 10, 0] # Dispersion rock [m], facie 1 to 7
+    rockCond = [1.9, 1.25, 1.25, 1.25, 0.92, 0.26, 2.0] # Thermal conductivity rock [W/(m K)], facie 1 to 7
+    radius = [0.15, 0.15] # Wells radius [m] (0 to use the SOURCE keyword instead of well keywords), well 1 to 2
+    wellCoord = [[2700.0, 1000.0, 300.0], [5100.0, 1000.0, 700.0]] # Well positions: x, y, and z coordinates [m], well 1 to 2
+    wellCoordF = [[2700.0, 4000.0, 300.0], [5100.0, 4000.0, 700.0]] # Well final positions: x, y, and z coordinates [m], well 1 to 2 (for spe11c)
+
+    # Set the saturation functions
+    krw = "(max(0, (s_w - swi) / (1 - swi))) ** 1.5"                                                         # Wetting rel perm saturation function [-]
+    krn = "(max(0, (1 - s_w - sni) / (1 - sni))) ** 1.5"                                                     # Non-wetting rel perm saturation function [-]
+    pcap = "penmax * math.erf(pen * ((s_w-swi) / (1.-swi)) ** (-(1.0 / 1.5)) * math.pi**0.5 / (penmax * 2))" # Capillary pressure saturation function [Pa]
+    s_w = "(np.exp(np.flip(np.linspace(0, 5.0, npoints))) - 1) / (np.exp(5.0) - 1)"                          # Points to evaluate the saturation functions (s_w) [-]
+
+    # Properties sat functions: 1) swi [-], 2) sni [-], 3) pen [Pa], 4) penmax [Pa], and 5) npoints [-], facie 1 to 7
+    safu = [[0.32, 0.1, 193531.39, 3e7, 1000],
+            [0.14, 0.1, 8654.99,   3e7, 1000], 
+            [0.12, 0.1, 6120.00,   3e7, 1000], 
+            [0.12, 0.1, 3870.63,   3e7, 1000], 
+            [0.12, 0.1, 3060.00,   3e7, 1000], 
+            [0.10, 0.1, 2560.18,   3e7, 1000], 
+            [0,      0,       0,   3e7,    2]]
+
+    # Properties rock: 1) K [mD] and 2) phi [-], facie 1 to 7
+    rock = [[0.10132, 0.10],
+            [101.324, 0.20],
+            [202.650, 0.20],
+            [506.625, 0.20],
+            [1013.25, 0.25],
+            [2026.50, 0.35],
+            [1e-5,    1e-6]]
+
+    # Define the injection values ([hours] for spe11a; [years] for spe11b/c): 1) injection time, 2) time step size to write results, 3) maximum solver time step, 4) injected fluid (0 water, 1 co2) (well1), 5) injection rate [kg/s] (well1), 6) temperature [C] (well1), 7) injected fluid (0 water, 1 co2) (well2), 8) injection rate [kg/s] (well2), and 9) temperature [C] (well2)
+    inj = [[999.9, 999.9, 100, 1,  0, 10, 1,  0, 10],
+           [  0.1,   0.1, 0.1, 1,  0, 10, 1,  0, 10],
+           [   25,     5,   5, 1, 50, 10, 1,  0, 10],
+           [   25,     5,   5, 1, 50, 10, 1, 50, 10],
+           [   50,    25,  25, 1,  0, 10, 1,  0, 10],
+           [  400,    50,  50, 1,  0, 10, 1,  0, 10],
+           [  500,   100, 100, 1,  0, 10, 1,  0, 10]]
+
+
+For additional examples of configuration files using toml, see the 
+`hello_world <https://github.com/OPM/pyopmspe11/tree/main/examples/hello_world>`_ and `configs <https://github.com/OPM/pyopmspe11/tree/main/tests/configs>`_ folders.
+
+.. note::
+    A Python version of at least 3.11 is requiered to use the toml format. For older Python versions, then use the :ref:`txt` configuration files.

docs/_sources/contributing.rst.txt

@@ -25,7 +25,7 @@ Contribute to the software
     #. **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=pyopmspe11 --cov-report term-missing tests/** (this runs locally the tests, and might rise issues that need to be fixed before the pull request)
+    #. **pytest --cov=pyopmspe11 --cov-report term-missing tests/** (this runs locally the tests, and might rise issues that need to be fixed before the pull request; to save the files, add the flag **--basetemp=test_outputs**)
     #. **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 delete all content from the `docs <https://github.com/cssr-tools/pyopmspe11/tree/main/docs>`_ folder except `Makefile <https://github.com/OPM/pyopmspe11/blob/main/docs/Makefile>`_, `text <https://github.com/OPM/pyopmspe11/blob/main/docs/text>`_, and `.nojekyll <https://github.com/OPM/pyopmspe11/blob/main/docs/.nojekyll>`_, after copy all contents from the docs/_build/html/ folder, and finally paste them in the `docs <https://github.com/cssr-tools/pyopmspe11/tree/main/docs>`_ folder)
 
     .. tip::

docs/_sources/examples.rst.txt

@@ -19,6 +19,12 @@ compare your example results to this figure to evaluate if your example ran corr
 
 .. figure:: figs/spe11b_tco2_2Dmaps.png
 
+Using the :ref:`toml` format, the previous run is equivalent to:
+
+.. code-block:: bash
+
+    pyopmspe11 -i spe11b.toml -o spe11b -m all -g all -t 5 -r 50,1,15 -w 1
+
 Let us now change the grid type from corner-point to tensor in line 7 of the configuration file.
 Then, we run the simulations and we save the results in a different output folder:
 

docs/_sources/introduction.rst.txt

@@ -29,7 +29,7 @@ The current implementation supports the following executable with the argument o
 
 .. code-block:: bash
 
-    pyopmspe11 -i configuration_file.txt
+    pyopmspe11 -i configuration_file
 
 where