Merge pull request #13 from daavid00/dev

New features and extended documentaion

.github/workflows/CI.yml

@@ -37,10 +37,11 @@ jobs:
         sudo apt-get install libopm-simulators-bin
         sudo apt-get install texlive-fonts-recommended texlive-fonts-extra dvipng cm-super
         
-    - name: Install test dependecies
+    - name: Install dependecies
       run: |
         pip install --upgrade pip setuptools wheel
         pip install -r dev-requirements.txt
+        pip install opm
         
     - name: Install plopm
       run: |

README.md

@@ -7,7 +7,7 @@
 # plopm: Simplified and flexible tool to visualize OPM Flow geological models
 
 ## Main feature
-Quick generation of PNG figures from a simulation model given any 2D slide.
+Quick generation of PNG figures and VTKs from a OPM Flow type model.
 
 ## Installation
 To install the _plopm_ executable in an existing Python environment: 
@@ -40,7 +40,7 @@ To use the conversion from OPM Flow output files (i.e., .EGRID, .INIT, .UNRST) t
 ## Running plopm
 You can run _plopm_ as a single command line:
 ```
-plopm -i some_input -o some_output_folder
+plopm -i name(s)_of_input_file(s)
 ```
 Run `plopm --help` to see all possible command line argument options.
 
@@ -51,4 +51,4 @@ See the [_examples_](https://cssr-tools.github.io/plopm/examples.html) in the [_
 The _plopm_ package is being funded by the [_HPC Simulation Software for the Gigatonne Storage Challenge project_](https://www.norceresearch.no/en/projects/hpc-simulation-software-for-the-gigatonne-storage-challenge) [project number 622059] and [_Center for Sustainable Subsurface Resources (CSSR)_](https://cssr.no) 
 [project no. 331841].
 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 new features, please request them raising an issue.

docs/_sources/about.rst.txt

@@ -3,9 +3,8 @@ About plopm
 ===========
 
 .. image:: ./figs/about.png
-    :scale: 25%
 
-This **plopm** package is being funded by the `HPC Simulation Software for the Gigatonne Storage Challenge project <https://www.norceresearch.no/en/projects/hpc-simulation-software-for-the-gigatonne-storage-challenge>`_ 
+**plopm** is being funded by the `HPC Simulation Software for the Gigatonne Storage Challenge project <https://www.norceresearch.no/en/projects/hpc-simulation-software-for-the-gigatonne-storage-challenge>`_ 
 [project number 622059] and `Center for Sustainable Subsurface Resources (CSSR) <https://cssr.no>`_ [project no. 331841].
 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 new features, please request them raising an issue.

docs/_sources/examples.rst.txt

@@ -22,43 +22,26 @@ The default argument options are:
 
 .. code-block:: bash
 
-    plopm -i SPE11B -o . -s ,1, -f 14 -x '' -y '' -z yes -u resdata -v '' -c '' -n '' -l '' -r -1 -w 0
+    plopm -i SPE11B -o . -v '' -m png -s ,1, -p flow -z yes -f 14 -x '' -y '' -u resdata  -c ''  -e '' -n '' -b '' -d 8,16 -l '' -t '' -r -1 -w 0 -g 0 -a 1 -time s -ylabel '' -xlabel '' -ylnum 4 -xlnum 4 -cnum '' -clabel '' -labels '' -axgrid 1 -dpi 300 -xformat '' -yformat '' -xunits m -yunits m -remove 0,0,0,0 -facecolor w -save '' -log 0 -rotate 0 -translate '[0,0]' -global 0 -ncolor w
 
 See the :ref:`overview` or run `plopm -h` for the definition of the argument options.
 
-For example, for the gas saturation at the report step number 4:
+For example, for the gas saturation at the report step number 4 using a given colormap (-c):
 
 .. code-block:: bash
 
-    plopm -i SPE11B -v sgas -c cubehelix -r 4 -n "lambda x, _: f'{x:.2f}'"
+    plopm -i SPE11B -v sgas -r 4 -c cubehelix
 
 .. figure:: figs/sgas_spe11b.png
 
-and for the gas in place summary vector:
+and for the gas in place summary vector given a color, line style, font size, dimension of the figure, and using dates for the times:
 
 .. code-block:: bash
 
-    plopm -i SPE11B -v fgip -c k
+    plopm -i SPE11B -v fgip -c b -e ':' -f 12 -d 5,5 -time dates
 
 .. figure:: figs/fgip_spe11b.png
-    :scale: 20%
-
-=====
-Norne 
-=====
-
-This example relies on the simulation results in `opm-tests <https://github.com/OPM/opm-tests/tree/master/norne/ECL.2014.2>`_. If you
-download the files in that folder, then by using the **plopm** tool:
-
-.. code-block:: bash
-
-    plopm -i NORNE_ATW2013 -o . -s ,,1 -x 455600,462200 -y 7319500,7327100
-
-these are some of the generated figures:
-
-.. image:: ./figs/plopm.png
-
-Here, we plot the top view (xy axis, k=1), and we set the xlim (-x) and ylim (-y) in order to reduce the white space outside the active cells.
+    :scale: 30%
 
 ============
 Generic deck 
@@ -73,16 +56,41 @@ for an example where **plopm** is used to generate figures from the
 
 .. code-block:: bash
 
-    plopm -i SPE10_MODEL2 -o . -s 4,,
+    plopm -i SPE10_MODEL2 -v permz -s ,4, -log 1 -xunits km -yunits km -xlnum 6 -yformat .2f -t 'K$_z$ at the forth slide in the xz plane' -b '[1e-7,1e3]'
 
-To plot the location of the wells from the top view, then:
+Here, we look at the forth slide in the xz plane and use log scale for the permeability in the z direction, as well as changing the axis units to km, 
+setting the format to the numbers to two floats in the y axis, and setting manualli the upper and lower bound for the color map.
+
+To plot information for the grid, and also the location of the wells from the top view, this is achieved by:
 
 .. code-block:: bash
 
-    plopm -i SPE10_MODEL2 -w 1
+    plopm -i SPE10_MODEL2 -s 1,, -d 3,4 -f 8 -g 1 && plopm -i SPE10_MODEL2 -s 1,, -d 3,4 -f 8 -w 1
 
 .. image:: ./figs/wells.png
-    :scale: 20%
+
+===============================
+Rotation, translation, and zoom
+===============================
+
+This example relies on the simulation results in `opm-tests <https://github.com/OPM/opm-tests/tree/master/norne/ECL.2014.2>`_. If you
+download the files in that folder, then by using the **plopm** tool:
+
+.. code-block:: bash
+
+    plopm -i NORNE_ATW2013 -s ,,1
+
+these are some of the generated figures:
+
+.. image:: ./figs/norne.png
+
+In order to reduce the white space outside the active cells, as well as to rotate the grid and translate it, this can be ahieved by:
+
+.. code-block:: bash
+
+    plopm -i NORNE_ATW2013 -s ,,1 -rotate 65 -translate '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,7600]' -f 20
+
+.. image:: ./figs/norne_transformed.png
 
 =====================
 Different input files 
@@ -93,11 +101,12 @@ called spe11b_larger_inj. Then, to plot the summary vector for both runs we can
 
 .. code-block:: bash
 
-    plopm -i spe11b/SPE11B,/Users/dmar/spe11b_larger_inj/SPE11B -v tcpu -d 5,5 -c r,b -e 'solid;:' -t 'Comparing the simulation times' -f 10 
+    plopm -i spe11b/SPE11B,/home/user/spe11b_larger_inj/SPE11B -v fgipm -a 1e-6 -time w -d 5,5 -c r,b -e 'solid;:' -t 'Comparing the total mass' -f 10
 
-.. image:: ./figs/tcpu.png
+.. image:: ./figs/fgipm.png
+    :scale: 30%
 
-Here, we have lower the size of the figure to 5,5 inches, set to use red and blue colors with solid and dotted lines, as well as settting the title and lower the font size to 10.
+Here, we plot the injected mass and scaled to kilo tons, and the time is shown in weeks.
 
 .. tip::
     For any summary variable, one can give the path to more than two different simulation cases, just by separating the folder paths by commas in the -i.
@@ -114,20 +123,20 @@ To changue the colormap and setting the clorbar limits manually, this can be ach
 
 .. code-block:: bash
     
-    plopm -i spe11b/SPE11B,spe11b_larger_inj/SPE11B -v sgas -r 3 -c tab20c -b '[-0.8,0]'
+    plopm -i spe11b/SPE11B,spe11b_larger_inj/SPE11B -v sgas -r 3 -c tab20c -b '[-0.8,0]' -n "lambda x, _: f'{x:.3f}'"
 
 .. image:: ./figs/sgas_diff_edit.png
 
 ==============
 Convert to VTK 
 ==============
 Inside the `examples folder <https://github.com/cssr-tools/plopm/blob/main/examples>`_, then we can create VTKs from the
-OPM Flow simulation results (i.e., .EGRID, .INIT, .UNRST). For example, to create VTKS for the temperature from the restart 
-files from the initial (0) to the number 5 restart, using a OPM Flow build from source in a given path, this can be achieved by:
+OPM Flow simulation results (i.e., .EGRID, .INIT, .UNRST). For example, to create VTKS for the temperature, fipnum, and the co2 mass 
+from the restart files from the initial (0) to the number 5 restart, using a OPM Flow build from source in a given path, this can be achieved by:
 
 .. code-block:: bash
     
-    plopm -i SPE11B -v temp -r 0,5 -m vtk -p /Users/dmar/build/opm-simulators/bin/flow
+    plopm -i SPE11B -v temp,fipnum,co2m -r 0,5 -m vtk -p /Users/dmar/build/opm-simulators/bin/flow
 
 .. figure:: ./figs/vtk_temp.png
 
@@ -136,4 +145,5 @@ files from the initial (0) to the number 5 restart, using a OPM Flow build from
 .. note::
 
     It is possible to write directly VTKs from OPM Flow simulations by adding the flag **--enable-vtk-output=true**.
-    However, there are quantities that are not written (e.g., fipnum, flores). This is when **plopm** can be helpful.
+    However, there are quantities that are not written (e.g., fipnum, flores), in addition to quantities not supported
+    such as component mass (e.g., co2, h2o). This is when **plopm** can be helpful.

docs/_sources/installation.rst.txt

@@ -34,6 +34,7 @@ install the Python requirements in a virtual environment with the following comm
 .. note::
 
     For not macOS users, to install the Python opm package, execute in the terminal **pip install opm**.
+    In addition, to install the dependencies used for the figure's formatting, execute **sudo apt-get install texlive-fonts-recommended texlive-fonts-extra dvipng cm-super**.
     For macOS, see :ref:`macOS`.
 
 OPM Flow
@@ -84,7 +85,7 @@ in the terminal the following lines (which in turn should build flow in the fold
     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**
 
 Regarding the reading of from OPM Flow output files (i.e., .EGRID, .INIT, .UNRST), it is possible to use the opm python package instead of resdata (e.g., it seems the opm Python package
-is faster than resdata to read large simulation files). To use opm, you first need to install it, by executing in the terminal **pip install opm**.  
+is faster than resdata to read large simulation files). To use opm, you first need to install it, by executing in the terminal **pip install opm** and when executing plopm adding the flag **-u opm**.  
 
 .. _macOS:
 

docs/_sources/introduction.rst.txt

@@ -4,11 +4,11 @@ Introduction
 
 .. image:: ./figs/plopm.png
 
-This documentation describes the content of the **plopm** tool. 
+This documentation describes the **plopm** tool hosted in `https://github.com/cssr-tools/plopm <https://github.com/cssr-tools/plopm>`_. 
 
 Concept
 -------
-Simplified and flexible framework for quick visualization of `OPM Flow <https://www.paraview.org>`_ geological models.
+Simplified and flexible framework for quick visualization of `OPM Flow <https://opm-project.org>`_ geological models.
 The approach is the generation of PNG figures from static (e.g, porosity, pore volume fluid in place numbers)
 and dynamic (e.g., pressure, fluid saturations) properties given any 2D slide (e.g., the middle part of a reservoir in the xy plane),
 as well as plotting any given summary vector (e.g., field gas in place a.k.a fgip). 
@@ -26,29 +26,55 @@ The current implementation supports the following executable with the argument o
 
 .. code-block:: bash
 
-    plopm -i some_input -o some_output_folder
+    plopm -i name(s)_of_input_file(s)
 
 where 
 
-- \-i: The base name of the input files; if more than one is given, separate them by ',' (e.g, 'SPE11B,SPE11B_TUNED') (`SPE11B` by default).
-- \-o: The base name of the output folder (`.` by default).
-- \-f: The font size (`14` by default).
-- \-s: The slide for the 2D maps of the static variables, e.g, `10,,` to plot the xz plane on all cells with i=10 (`,1,` by default, i.e., the xz surface at j=1).
-- \-x: Option to set the lower and upper bounds in the 2D map along x ('' by default).
-- \-y: Option to set the lower and upper bounds in the 2D map along y ('' by default).
-- \-z: The option to scale the axis in the 2D maps (`yes` by default).
-- \-u: Use resdata or opm Python libraries (`resdata` by default).
-- \-v: Specify the name of the static vairable to plot (e.g., `depth`) ('' by default, i.e., plotting: porv, permx, permz, poro, fipnum, and satnum).
-- \-c: Specify the colormap (e.g., `jet`) ('' by default, i.e., set by plopm).
-- \-n: Specify the format for the numbers in the colormap (e.g., "lambda x, _: f'{x:.0f}'") ('' by default, i.e., set by plopm).
-- \-l: Specify the units (e.g., \"[m\\$^2\\$]\") ('' by default, i.e., set by plopm).
-- \-r: Restart number to plot the dynamic variable, where 1 corresponds to the initial one ('-1' by default, i.e., the last restart file).
-- \-w: Plot the positions of the wells or sources ('0' by default).
-- \-g: Plot information about the number of cells in the x, y, and z directions and number of active grid cells ('0' by default).
-- \-e: Specify the linestyles separated by ';' (e.g., 'solid;:') ('' by default, i.e., set by plopm).
-- \-b: Specify the upper and lower bounds for the color map (e.g., '[-0.1,11]') ('' by default, i.e., set by matplotlib).
-- \-d: Specify the dimensions  of the Figure (e.g., '5,5') ('8,16' by default).
-- \-t: Specify the figure title (e.g., 'Final saturation map') ('' by default, i.e., set by plopm).
-- \-r: Restart number to plot the dynamic variable, where 1 corresponds to the initial one ('-1' by default, i.e., the last restart file).
-- \-p: Path to flow (e.g., '\home\build\bin\flow'). This is used to generate the grid for the vtk files ('flow' by default).
-- \-m: Generate 'png' or 'vtk' files ('png' by default).
+-i    The base name (or full path) of the input files; if more than one is given, separate them by ',' (e.g, 'SPE11B,\\home\\user\\SPE11B_TUNED') ('SPE11B' by default).
+-o    The base name (or full path) of the output folder ('.' by default, i.e., the folder where plopm is executed).
+-v    Specify the name of the vairable to plot, e.g., 'pressure', in addition to special extensive quantities for the mass such as 'gasm', 'dism', 'liqm', 'vapm', 'co2m', 'h2om', 'fwcdm', and 'fgipm' ('' by default, i.e., plotting: porv, permx, permz, poro, fipnum, and satnum).
+-m    Generate 'png' or 'vtk' files ('png' by default).
+-s    The slide in the 3D model to plot the 2D maps, e.g, '10,,' to plot the xz plane on all cells with i=10 (',1,' by default, i.e., the xz surface at j=1).
+-p    Path to flow, e.g., '\\home\\build\\bin\\flow'. This is used to generate the grid for the vtk files ('flow' by default).
+-z    Scale the axis in the 2D maps ('1' by default).
+-f    The font size ('14' by default).
+-x    Set the lower and upper bounds along x, e.g., '[-100,200]' ('' by default).
+-y    Set the lower and upper bounds along y, e.g., '[-10,300]' ('' by default).
+-u    Use resdata or opm Python libraries ('resdata' by default).
+-c    Specify the colormap, e.g., 'jet', or color(s) for the summary, e.g., 'b,r' ('' by default, i.e., set by plopm).
+-e    Specify the linestyles separated by ';', e.g., 'solid;:' ('' by default, i.e., set by plopm).
+-n    Specify the format for the numbers in the colormap, e.g., "lambda x, _    f'{x:.0f}'" ('' by default, i.e., set by plopm).
+-b    Specify the upper and lower bounds for the color map, e.g., '[-0.1,11]' ('' by default, i.e., set by plopm).
+-d    Specify the dimensions in inches generated png, e.g., '5,5' ('8,16' by default).
+-l    Specify the units of the variable, e.g., \"[m\\$^2\\$]\" ('' by default, i.e., set by plopm).
+-t    Specify the figure title, e.g., 'Final saturation map' ('' by default, i.e., set by plopm).
+-r    Restart number to plot the dynamic variable, where 1 corresponds to the initial one ('-1' by default, i.e., the last restart file).
+-w    Plot the positions of the wells or sources ('0' by default).
+-g    Plot information about the number of cells in the x, y, and z directions and number of active grid cells ('0' by default).
+-a    Scale the mass variable, e.g., 1e-9 for the color bar for the CO2 mass to be in Mt ('1' by default).
+-time       For the x axis in the summary use seconds 's', minutes 'm', hours 'h', days 'd', weeks 'w', years 'y', or dates 'dates' ('s' by default).
+-ylabel     Text for the y axis ('' by default, i.e., set by plopm).
+-xlabel     Text for the x axis ('' by default, i.e., set by plopm).
+-ylnum      Number of y axis labels ('4' by default).
+-xlnum      Number of x axis labels ('4' by default).
+-cnum       Number of color labels ('' by default, i.e., set by plopm).
+-clabel     Text for the colorbar ('' by default, i.e., set by plopm).
+-labels     Legend in the summary plot, separated by commas if more than one ('' by default, i.e., set by plopm).
+-axgrid     Set axis.grid to True for the summary plots ('1' by default).
+-dpi        Dots per inch for the figure ('300' by default).
+-xformat    Format for the x numbers, e.g., .2e for exponential notation ('' by default, i.e., set by plopm).
+-yformat    Format for the y numbers, e.g., .1f for one decimal ('' by default, i.e., set by plopm).
+-xunits     For the x axis in the spatial maps meters 'm', kilometers 'km', centimeters 'cm', or milimeters 'mm' ('m' by default).
+-yunits     For the y axis in the spatial maps meters 'm', kilometers 'km', centimeters 'cm', or milimeters 'mm' ('m' by default).
+-remove     Set the entries to 1 to remove in the spatial maps the left axis, bottom axis, colorbar, and title ('0,0,0,0' by default).
+-facecolor  Color outside the spatial map ('w' by default, i.e., white).
+-save       Name of the output files ('' by default, i.e., set by plopm).
+-log        Log scale for the color map ('0' by default).
+-rotate     Grades to rotate the grid in the 2D maps ('0' by default).
+-translate  Translate the grid in the 2D maps x,y directions ('[0,0]' by default).
+-global     Min and max in the colorbars from the current 2D slide values (0) or whole 3D model '1' ('0' by default).
+-ncolor     Color for the inactive cells in the 2D maps ('w' by default, i.e., white).
+
+.. tip::
+
+    Type in the terminal **plopm --help** to show these argument options.  

docs/_static/basic.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- basic theme.
  *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */

docs/_static/doctools.js

@@ -4,7 +4,7 @@
  *
  * Base JavaScript utilities for all Sphinx HTML documentation.
  *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */

docs/_static/language_data.js

@@ -5,15 +5,15 @@
  * This script contains the language-specific data used by searchtools.js,
  * namely the list of stopwords, stemmer, scorer and splitter.
  *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
 
 var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];
 
 
-/* Non-minified version is copied as a separate JS file, if available */
+/* Non-minified version is copied as a separate JS file, is available */
 
 /**
  * Porter Stemmer