diff --git a/README.md b/README.md
index e41b81f..91c376f 100755
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ To install the _plopm_ executable in an existing Python environment:
pip install git+https://github.com/cssr-tools/plopm.git
```
-If you are interested in a specific version (e.g., v2026.04) 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:
+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:
```bash
# Clone the repo
@@ -46,7 +46,7 @@ plopm -i name(s)_of_input_file(s)
Run `plopm --help` to see all possible command line argument options.
## Getting started
-See the [_examples_](https://cssr-tools.github.io/plopm/examples.html) in the [_documentation_](https://cssr-tools.github.io/plopm/introduction.html) and this [_paper_](https://github.com/cssr-tools/plopm/tree/main/paper/paper.pdf).
+See the [_tutorial_](https://cssr-tools.github.io/plopm/tutorial.html) and [_examples_](https://cssr-tools.github.io/plopm/examples.html) in the [_documentation_](https://cssr-tools.github.io/plopm/introduction.html) and this [_paper_](https://github.com/cssr-tools/plopm/tree/main/paper/paper.pdf).
## Citing
* Landa-Marbán, D. 2026. plopm: A lightweight and flexible tool for visualization and postprocessing of OPM Flow geological models. [https://doi.org/10.13140/RG.2.2.12046.22081](https://doi.org/10.13140/RG.2.2.12046.22081).
@@ -61,7 +61,7 @@ The following is a list of manuscripts in which _plopm_ is used:
* Sandve, T.H., Boon, W., Landa-Marbán, D., Tveit, S., Gasda, S.E., 2025. Multi-Scale Simulation Strategies for Managing Pressure Interference in Multi-Site CO2 Storage in Large Regional Aquifers, presented at GET 2025, https://doi.org/10.3997/2214-4609.202521134.
* Landa-Marbán, D., Lie, K.-A., Lye, K. O., Møyner, O., Rasmussen, A. F., and T. H., Sandve, 2026. Exploring Convergence and Its Limits in Case B of the 11th SPE Comparative Solution Project. SPE J. https://doi.org/10.2118/231853-PA.
* Landa-Marbán, D., Sandve, T.H., Both, J.W., Nordbotten, J.M., and Gasda, S.E., 2026. Performance of an open-source image-based history matching framework for CO2 storage. Transp Porous Med, https://doi.org/10.1007/s11242-025-02275-0.
-* Landa-Marbán, D., Sandve, T.H., and Gasda, S.E., 2025. A Coarsening Approach to the Troll Aquifer Model. https://arxiv.org/abs/2508.08670.
+* Landa-Marbán, D., Sandve, T.H., and Gasda, S.E., 2026. A coarsening approach to the troll aquifer model. In Nils Anders Røkke, Philip Stefan Ringrose, & Stefan Marcell Götz (Eds.), TCCS-13. CO2 Capture, Transport and Storage Trondheim, Norway | 16–19 June 2025 Short Papers from the 13th Trondheim CCS Conference (pp. 13–20). SINTEF akademisk forlag. https://hdl.handle.net/11250/5559902
The software also supports the online documentation of several open‑source tools, including:
diff --git a/docs/_images/poro_sgas.png b/docs/_images/poro_sgas.png
new file mode 100644
index 0000000..5bc6653
Binary files /dev/null and b/docs/_images/poro_sgas.png differ
diff --git a/docs/_images/spe11c_temp_i,14,k_t2.png b/docs/_images/spe11c_temp_i,14,k_t2.png
new file mode 100644
index 0000000..d9ac3a7
Binary files /dev/null and b/docs/_images/spe11c_temp_i,14,k_t2.png differ
diff --git a/docs/_modules/index.html b/docs/_modules/index.html
index 83ade7d..6f3aa86 100644
--- a/docs/_modules/index.html
+++ b/docs/_modules/index.html
@@ -53,7 +53,7 @@
-
+
diff --git a/docs/_modules/plopm/config/config.html b/docs/_modules/plopm/config/config.html
index e348fd7..052bfb0 100644
--- a/docs/_modules/plopm/config/config.html
+++ b/docs/_modules/plopm/config/config.html
@@ -53,7 +53,7 @@
-
+
diff --git a/docs/_modules/plopm/core/plopm.html b/docs/_modules/plopm/core/plopm.html
index 8384aab..a2c5108 100644
--- a/docs/_modules/plopm/core/plopm.html
+++ b/docs/_modules/plopm/core/plopm.html
@@ -53,7 +53,7 @@
-
+
diff --git a/docs/_modules/plopm/utils/initialization.html b/docs/_modules/plopm/utils/initialization.html
index 5de24c6..d13ff9b 100644
--- a/docs/_modules/plopm/utils/initialization.html
+++ b/docs/_modules/plopm/utils/initialization.html
@@ -53,7 +53,7 @@
-
+
@@ -474,6 +474,7 @@
minc=0ifvarnotin("wells","grid","faults"):ifint(cfg.color_log[n])==0:
- iflen(data.steps)>1andcfg.subplot_grid[0]andlen(cfg.cases[0])==1:
+ restart_subplots=(
+ len(data.steps)>1
+ andcfg.subplot_grid[0]
+ andlen(cfg.cases[0])==1
+ andnot(
+ len(cfg.variables)>1andlen(data.steps)==len(cfg.variables)
+ )
+ )
+ ifrestart_subplots:ifcfg.colorbar_position[0]!=-1:cb[0]=fig.colorbar(imag,
diff --git a/docs/_modules/plopm/utils/write_vtk.html b/docs/_modules/plopm/utils/write_vtk.html
index 52b2eb6..6368b7d 100644
--- a/docs/_modules/plopm/utils/write_vtk.html
+++ b/docs/_modules/plopm/utils/write_vtk.html
@@ -53,7 +53,7 @@
-
+
diff --git a/docs/_sources/examples.rst.txt b/docs/_sources/examples.rst.txt
index 9032af6..51d2c90 100644
--- a/docs/_sources/examples.rst.txt
+++ b/docs/_sources/examples.rst.txt
@@ -61,12 +61,12 @@ Example gallery
Create maps, summary plots, and cell time series.
- .. grid-item-card:: Colormaps
+ .. grid-item-card:: Colormaps and subfigures
:link: example-colormaps
:link-type: ref
:img-top: figs/spe11b_disperc_i,1,k_t5.png
- Use named, RGB, and HEX colormaps.
+ Use named, RGB, and HEX colormaps, as well as subfigures.
.. grid-item-card:: Generic deck
:link: example-generic-deck
@@ -82,6 +82,13 @@ Example gallery
Transform, crop, and inspect Norne.
+ .. grid-item-card:: Wells and faults
+ :link: example-wells-faults
+ :link-type: ref
+ :img-top: figs/norne_faults.png
+
+ Show wells and faults in Norne.
+
.. grid-item-card:: Projections and subfigures
:link: example-projections
:link-type: ref
@@ -157,9 +164,10 @@ Example gallery
:maxdepth: 1
examples/hello-world
- examples/colormaps
+ examples/colormaps-subfigures
examples/generic-deck
examples/transformations
+ examples/wells-faults
examples/projections
examples/histograms
examples/caprock
diff --git a/docs/_sources/examples/animations.rst.txt b/docs/_sources/examples/animations.rst.txt
index 041c28a..b9e2e17 100644
--- a/docs/_sources/examples/animations.rst.txt
+++ b/docs/_sources/examples/animations.rst.txt
@@ -3,28 +3,89 @@
GIFs and masks
==============
-Animate results and apply masks.
+Create GIF animations from restart steps and use a static model property as a
+background mask.
-Create a masked GIF comparing two cases.
+Prepare the comparison cases
+----------------------------
+
+This example compares a base SPE11B simulation with a second case that uses
+twice the injection rate.
+
+Install **pyopmspe11**, download the example configuration, and create the
+higher-rate configuration:
+
+.. code-block:: console
+
+ pip install git+https://github.com/OPM/pyopmspe11.git
+ curl -L -O https://raw.githubusercontent.com/OPM/pyopmspe11/main/examples/spe11b.toml
+ cp spe11b.toml spe11b_larger_inj.toml
+ sed -i.bak 's/0.035/0.07/g' spe11b_larger_inj.toml
+ rm -f spe11b_larger_inj.toml.bak
+
+Run both simulations:
+
+.. code-block:: console
+
+ pyopmspe11 -i spe11b.toml -o spe11b -fz 0
+ pyopmspe11 -i spe11b_larger_inj.toml -o spe11b_larger_inj -fz 0
+
+The first case uses the injection rate defined in ``spe11b.toml``. The second
+configuration replaces ``0.035`` kg/s with ``0.07`` kg/s.
+
+Create a masked comparison
+--------------------------
+
+Plot the liquid-phase CO2 mass fraction from both simulations and use
+``satnum`` as a static background mask:
.. code-block:: console
plopm -v xco2l -sg 1,2 -i 'spe11b/SPE11B spe11b_larger_inj/SPE11B_LARGER_INJ' -fs 16,2.5 -mv satnum -r 0,1,2,3,4,5 -m gif -dpi 1000 -t 'spe11b spe11b larger injection' -fz 16 -gi 1000 -gl 1 -cbf .2f -cbp 0.30,0.01,0.4,0.02
.. figure:: ../figs/xco2l.gif
+ :alt: Animated comparison of liquid-phase CO2 mass fraction for two SPE11B injection rates
:align: center
:width: 90%
-Create an unmasked gas-saturation GIF with grid edges.
+ Liquid-phase CO2 mass fraction for the base case and the case with the
+ larger injection rate. ``satnum`` provides the static background mask.
+
+The principal options are:
+
+* :option:`plopm -m` selects GIF output.
+* :option:`plopm -r` selects the restart steps used as frames.
+* :option:`plopm -mv` selects the static mask variable.
+* :option:`plopm -sg` places both cases in one figure.
+* :option:`plopm -gi` sets the interval between frames in milliseconds.
+* :option:`plopm -gl` enables continuous looping.
+
+Animate gas saturation
+----------------------
+
+Create an unmasked gas-saturation animation, display the grid edges, and show
+the spatial coordinates in kilometres:
.. code-block:: console
plopm -i spe11b/SPE11B -v sgas -tu y -c cet_cwr -ge 'black,5e-3' -fs 16,5 -m gif -dpi 1000 -fz 20 -gi 1000 -gl 1 -cbf .2f -asp 0 -xu km -yu km -xf .1f -yf .1f -cbn 5 -cbl 'Gas saturation [-]'
.. figure:: ../figs/spe11b_sgas.gif
+ :alt: Animated SPE11B gas saturation with grid edges
:align: center
:width: 90%
+ Gas saturation through time with visible grid edges and distances expressed
+ in kilometres.
+
+Here, :option:`plopm -ge` controls the grid-edge color and width,
+:option:`plopm -asp` disables equal axis scaling, and
+:option:`plopm -tu` displays time in years.
+
+.. tip::
+
+ Use ``-tu empty`` to hide the time label from the animation.
+
Reproduce this example
----------------------
diff --git a/docs/_sources/examples/caprock.rst.txt b/docs/_sources/examples/caprock.rst.txt
index 7464b80..284825c 100644
--- a/docs/_sources/examples/caprock.rst.txt
+++ b/docs/_sources/examples/caprock.rst.txt
@@ -3,19 +3,79 @@
Caprock integrity
=================
-Evaluate pressure limits.
+Evaluate pressure limits and identify regions where reservoir pressure exceeds
+the estimated caprock pressure limit.
-``limipres``, ``overpres``, and ``objepres`` support caprock-integrity analysis.
+The special variables ``limipres``, ``overpres``, and ``objepres`` support
+caprock-integrity analysis:
+
+``limipres``
+ Estimated limiting pressure based on depth and the stress coefficient.
+
+``overpres``
+ Difference between the simulated pressure and the estimated limiting
+ pressure. Positive values identify cells where the pressure exceeds the
+ estimated limit.
+
+``objepres``
+ Objective value derived from the pressure-limit calculation. This quantity
+ can be exported to CSV for use in optimization and sensitivity workflows.
+
+The pressure-limit calculation uses the stress coefficient selected with
+:option:`plopm -sc`.
+
+Plot limiting and excess pressure
+---------------------------------
+
+Project the first 22 layers of the Norne model and compare ``limipres`` with
+``overpres``:
.. code-block:: console
plopm -i NORNE_ATW2013 -s ',,1:22 ,,1:22' -v limipres,overpres -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,8800]' -fs 15,10 -c Spectral,spring -sg 1,2 -rdl 1
- plopm -i NORNE_ATW2013 -m csv -v objepres -s ',,1:22'
.. figure:: ../figs/norne_atw2013_overpres_i,j,1:22_t64.png
+ :alt: Limiting pressure and excess pressure across the first 22 layers of the Norne model
:align: center
:width: 90%
+ Limiting pressure and excess pressure projected across layers 1 through 22
+ of the Norne model.
+
+The command applies the same spatial selection to both quantities:
+
+* :option:`plopm -s` selects layers 1 through 22.
+* :option:`plopm -rot` rotates the Norne grid.
+* :option:`plopm -tr` translates the rotated coordinates.
+* :option:`plopm -x` and :option:`plopm -y` crop the displayed region.
+* :option:`plopm -sg` places both quantities in one row with two panels.
+* :option:`plopm -rdl` removes repeated axis labels from the subplot layout.
+
+Export the objective value
+--------------------------
+
+Export ``objepres`` for the same layers as a CSV file:
+
+.. code-block:: console
+
+ plopm -i NORNE_ATW2013 -m csv -v objepres -s ',,1:22'
+
+The CSV output can be used as an objective value in optimization, uncertainty
+quantification, and sensitivity studies.
+
+Change the stress coefficient
+-----------------------------
+
+The default stress coefficient is ``0.134``. Select another value with
+:option:`plopm -sc`:
+
+.. code-block:: console
+
+ plopm -i NORNE_ATW2013 -s ',,1:22 ,,1:22' -v limipres,overpres -sc 0.15 -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,8800]' -fs 15,10 -c Spectral,spring -sg 1,2 -rdl 1
+
+Changing the stress coefficient changes the estimated limiting pressure and,
+consequently, the calculated excess-pressure and objective values.
+
Reproduce this example
----------------------
diff --git a/docs/_sources/examples/colormaps-subfigures.rst.txt b/docs/_sources/examples/colormaps-subfigures.rst.txt
new file mode 100644
index 0000000..3b7cf95
--- /dev/null
+++ b/docs/_sources/examples/colormaps-subfigures.rst.txt
@@ -0,0 +1,168 @@
+.. _example-colormaps:
+
+Colormaps and subfigures
+========================
+
+Use named colormaps, RGB values, or hexadecimal colors to customize discrete
+and continuous variables. Combine several plots in one figure with either
+individual or shared colorbars.
+
+Select colors
+-------------
+
+Use :option:`plopm -c` with:
+
+* A Matplotlib colormap name, such as ``viridis`` or ``Spectral``.
+* A Colorcet colormap name, such as ``cet_glasbey_bw``.
+* RGB colors written as ``red;green;blue`` values.
+* Hexadecimal colors written as ``#RRGGBB``.
+
+Separate colors belonging to one discrete palette with spaces. Separate the
+color specifications for different plots with commas.
+
+Compare three color specifications
+----------------------------------
+
+Plot ``satnum``, ``fipnum``, and ``disperc`` with a custom RGB palette, a
+Colorcet colormap, and two hexadecimal colors:
+
+.. code-block:: console
+
+ plopm -i SPE11B -v satnum,fipnum,disperc -c '193;147;56 127;148;191 193;127;97 181;73;57 81;124;66 101;64;147 134;133;130',cet_glasbey_bw,'#b6c406 #fffa86' -sg 3,1 -rdl 1 -cbn 3,6,2 -cbf .0f,.0f,.1f -fs 7,4
+
+.. figure:: ../figs/spe11b_disperc_i,1,k_t5.png
+ :alt: SPE11B variables displayed with RGB, Colorcet, and hexadecimal colors
+ :align: center
+ :width: 90%
+
+ ``satnum`` uses a custom RGB palette, ``fipnum`` uses
+ ``cet_glasbey_bw``, and ``disperc`` uses two hexadecimal colors.
+
+The custom RGB palette contains seven colors, one for each SPE11 facies:
+
+.. code-block:: text
+
+ 193;147;56
+ 127;148;191
+ 193;127;97
+ 181;73;57
+ 81;124;66
+ 101;64;147
+ 134;133;130
+
+The remaining options control the combined figure:
+
+* :option:`plopm -sg` arranges the three plots in three rows and one column.
+* :option:`plopm -rdl` removes repeated axis labels.
+* :option:`plopm -cbn` sets 3, 6, and 2 colorbar ticks for the three plots.
+* :option:`plopm -cbf` sets the corresponding colorbar number formats.
+* :option:`plopm -fs` sets the figure size.
+
+.. note::
+
+ Quote color specifications containing spaces, semicolons, or hexadecimal
+ values so the shell passes them to **plopm** as one argument.
+
+Subfigures with individual colorbars
+------------------------------------
+
+Combine static and dynamic quantities in one figure. When the plotted
+quantities use different value ranges or colormaps, each subplot has its own
+colorbar:
+
+.. code-block:: console
+
+ plopm -i SPE11B -v poro,sgas,sgas -sg 1,3 -r 0,1,5 -st 0 -fs 25,2 -c terrain,jet,jet -cbn 5 -cbf .1f -fn poro_sgas
+
+.. figure:: ../figs/poro_sgas.png
+ :alt: SPE11B porosity and gas saturation shown in three subfigures
+ :align: center
+ :width: 100%
+
+ Porosity and gas saturation at two restart steps, displayed with individual
+ colorbars.
+
+The command applies the values in each comma-separated list in subplot order:
+
+* ``poro`` is plotted at restart step 0 with the ``terrain`` colormap.
+* The first ``sgas`` plot uses restart step 1 and the ``jet`` colormap.
+* The second ``sgas`` plot uses restart step 5 and the ``jet`` colormap.
+* :option:`plopm -sg` arranges the three plots in one row.
+* :option:`plopm -st` removes the common figure title.
+* :option:`plopm -fn` sets the output filename to ``poro_sgas``.
+
+Subfigures with a shared colorbar
+---------------------------------
+
+When subfigures show the same quantity from different inputs or restart steps,
+use one shared colorbar. Position and size the shared colorbar with
+:option:`plopm -cbp`:
+
+.. code-block:: console
+
+ plopm -i 'SPE11B SPE11C SPE11B SPE11C' -sg 2,2 -v temp -s ',1, ,14, ,1, ,14,' -r 0,0,5,2 -st 0 -fs 10,10 -asp 0 -rdl 1 -c cet_diverging_rainbow_bgymr_45_85_c67_r -cbn 5 -cbp 0.15,0.92,0.7,0.02 -cbl 'Temperature [$^o$C]' -t 'SPE11B (initial temperature) SPE11C (initial temperature) SPE11B (end of simulation, 25 y) SPE11C (end of simulation, 25 y)' -fz 15
+
+.. figure:: ../figs/spe11c_temp_i,14,k_t2.png
+ :alt: SPE11B and SPE11C temperature at initial and final restart steps
+ :align: center
+ :width: 70%
+
+ Initial and final temperatures for SPE11B and SPE11C, displayed with one
+ shared colorbar.
+
+The four inputs, slices, restart steps, and titles correspond by position:
+
+.. code-block:: text
+
+ SPE11B -> slice ,1, -> restart 0 -> initial SPE11B temperature
+ SPE11C -> slice ,14, -> restart 0 -> initial SPE11C temperature
+ SPE11B -> slice ,1, -> restart 5 -> SPE11B after 25 years
+ SPE11C -> slice ,14, -> restart 2 -> SPE11C after 25 years
+
+The shared-colorbar options are:
+
+* :option:`plopm -cbp` sets ``left,bottom,width,height`` in figure coordinates.
+* :option:`plopm -cbn` sets the number of colorbar ticks.
+* :option:`plopm -cbl` sets the shared colorbar label.
+* :option:`plopm -c` applies one common colormap to all four temperature maps.
+
+:option:`plopm -asp` disables equal axis scaling, while
+:option:`plopm -rdl` removes repeated subplot labels. Two spaces separate the
+four titles supplied through :option:`plopm -t`.
+
+Reproduce this example
+----------------------
+
+Run the complete workflow from the repository root:
+
+.. code-block:: console
+
+ . ./tests/scripts/docs_colormaps-subfigures.sh
+
+.. grid:: 1 2 2 2
+ :gutter: 2
+
+ .. grid-item::
+
+ .. button-link:: https://github.com/cssr-tools/plopm/blob/main/tests/scripts/docs_colormaps-subfigures.sh
+ :color: primary
+ :outline:
+ :expand:
+
+ View script
+
+ .. grid-item::
+
+ .. button-link:: https://raw.githubusercontent.com/cssr-tools/plopm/main/tests/scripts/docs_colormaps-subfigures.sh
+ :color: secondary
+ :outline:
+ :expand:
+
+ View raw script
+
+.. button-ref:: examples-gallery
+ :ref-type: ref
+ :color: primary
+ :outline:
+
+ Back to the examples gallery
diff --git a/docs/_sources/examples/colormaps.rst.txt b/docs/_sources/examples/colormaps.rst.txt
deleted file mode 100644
index 4fa7ed2..0000000
--- a/docs/_sources/examples/colormaps.rst.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-.. _example-colormaps:
-
-Colormaps
-=========
-
-Use named, RGB, and HEX colormaps.
-
-Use :option:`plopm -c` with Matplotlib or Colorcet names, RGB values, or HEX colors.
-
-.. code-block:: console
-
- plopm -i SPE11B -v satnum,fipnum,disperc -c '193;147;56 127;148;191 193;127;97 181;73;57 81;124;66 101;64;147 134;133;130',cet_glasbey_bw,'#b6c406 #fffa86' -sg 3,1 -rdl 1 -cbn 3,6,2 -cbf .0f,.0f,.1f -fs 7,4
-
-.. figure:: ../figs/spe11b_disperc_i,1,k_t5.png
- :align: center
- :width: 90%
-
-Reproduce this example
-----------------------
-
-Run the complete workflow from the repository root:
-
-.. code-block:: console
-
- . ./tests/scripts/docs_colormaps.sh
-
-.. grid:: 1 2 2 2
- :gutter: 2
-
- .. grid-item::
-
- .. button-link:: https://github.com/cssr-tools/plopm/blob/main/tests/scripts/docs_colormaps.sh
- :color: primary
- :outline:
- :expand:
-
- View script
-
- .. grid-item::
-
- .. button-link:: https://raw.githubusercontent.com/cssr-tools/plopm/main/tests/scripts/docs_colormaps.sh
- :color: secondary
- :outline:
- :expand:
-
- View raw script
-
-.. button-ref:: examples-gallery
- :ref-type: ref
- :color: primary
- :outline:
-
- Back to the examples gallery
diff --git a/docs/_sources/examples/csv.rst.txt b/docs/_sources/examples/csv.rst.txt
index 9529b68..b522f1a 100644
--- a/docs/_sources/examples/csv.rst.txt
+++ b/docs/_sources/examples/csv.rst.txt
@@ -3,44 +3,120 @@
Reading CSV files
=================
-Combine CSV and OPM Flow data.
+Read time-series and spatial-map CSV files, compare benchmark submissions, and
+combine CSV data with OPM Flow output.
-Use :option:`plopm -cc` to combine CSV and OPM Flow data.
+CSV column syntax
+-----------------
+
+Use :option:`plopm -cc` to identify the columns in each CSV input. Column
+indices start at 1:
+
+* Use ``time,value`` for a time series, for example ``1,3``.
+* Use ``x,y,value`` for a spatial map, for example ``1,2,5``.
+* Separate specifications for multiple inputs with semicolons.
+* Leave one specification empty when the corresponding input is an OPM Flow
+ result rather than a CSV file.
+
+Compare simulation and reporting grids
+--------------------------------------
+
+Compare liquid-phase CO2 mass fraction on the OPM Flow simulation grid with
+the same quantity from the regular benchmark reporting grid:
.. code-block:: console
plopm -v xco2l -i 'r1_Cart_10m/R1_CART_10M r1_Cart_10m/spe11b_spatial_map_500y' -cc ';1,2,5' -sg 2,1 -rdl 1 -r 100 -fs 10,3 -st 0 -t 'Simulation grid Reporting grid' -cbp 0.35,0.97,0.3,0.02 -yu km -xu km -yf .1f -xf .1f -cbn 5 -xnt 8 -cbf .2f
.. figure:: ../figs/spe11b_spatial_map_500y_xco2l_csv_t100.png
+ :alt: Liquid-phase CO2 mass fraction on the simulation and reporting grids
:align: center
:width: 90%
-Compare a CSV series with an OPM summary vector.
+ Liquid-phase CO2 mass fraction from the OPM Flow simulation grid and the
+ SPE11B reporting-grid CSV file at 500 years.
+
+The first column specification is empty because the first input is an OPM Flow
+case. The second input uses columns 1, 2, and 5 for x, y, and the plotted value.
+
+Compare CSV and OPM summary data
+--------------------------------
+
+Compare a pressure time series from a CSV file with the corresponding OPM Flow
+summary vector:
.. code-block:: console
plopm -i 'r1_Cart_10m/spe11b_time_series r1_Cart_10m/R1_CART_10M' -v ',BWPR:256,1,5' -cc '1,3;' -sf '1e-5,1' -ls 'solid,dotted' -lw '4,4' -yl 'Sensor pressure [bar]' -llb 'From CSV file From OPM Flow output file' -c 'r,k'
.. figure:: ../figs/spe11b_time_series_BWPR-1944.png
+ :alt: Sensor pressure from a CSV file and an OPM Flow summary vector
:align: center
:width: 90%
-Compare several benchmark series.
+ Sensor pressure read from the SPE11B time-series CSV file and directly from
+ the OPM Flow summary output.
+
+The empty first entry in :option:`plopm -v` is a placeholder for the CSV input.
+The empty second entry in :option:`plopm -cc` indicates that the second input
+is read as OPM Flow output. The scale factors convert the two sources to the
+same displayed unit.
+
+Compare benchmark time series
+-----------------------------
+
+After downloading the selected SPE11 benchmark submissions, compare the same
+CSV quantity from several participants and the pyopmspe11 simulation:
+
+.. code-block:: console
+
+ plopm -i 'opm1/spe11b_time_series opm2/spe11b_time_series opm3/spe11b_time_series opm4/spe11b_time_series r1_Cart_10m/spe11b_time_series' -cc '1,4;1,4;1,4;1,4;1,4' -tu y -x '[0,1000]' -yl 'dissA [kiloton]' -yf .1f -sf 1e-6 -c '#a8d8e3,#a8d8e3,#a8d8e3,#a8d8e3,#fc035a' -lw 5,5,5,5,5 -ls solid
.. figure:: ../figs/spe11b_time_series_csv_ens.png
+ :alt: Comparison of SPE11B benchmark time series from several submissions
:align: center
:width: 90%
-Compare several benchmark spatial maps.
+ Dissolved CO2 mass in box A for several benchmark submissions and the
+ pyopmspe11 simulation.
+
+Each input uses columns 1 and 4. The scale factor converts kilograms to
+kilotonnes, and the color selection highlights the local simulation.
+
+Compare benchmark spatial maps
+------------------------------
+
+Compare the same CSV spatial quantity from several benchmark submissions in a
+single subplot layout:
+
+.. code-block:: console
+
+ plopm -i 'opm1/spe11b_spatial_map_250y opm2/spe11b_spatial_map_250y opm3/spe11b_spatial_map_250y opm4/spe11b_spatial_map_250y r1_Cart_10m/spe11b_spatial_map_250y' -cc '1,2,5;1,2,5;1,2,5;1,2,5;1,2,5' -sg 3,2 -rdl 1 -st 0 -cbp 0.35,0.97,0.3,0.02 -yu km -xu km -yf .1f -xf .1f -cbn 5 -xnt 8 -cbf .2f -fs 14,4 -t 'opm1 opm2 opm3 opm4 my simulation' -cbl 'Time 250 years, CO$_2$ mass fraction (liquid phase) [-]' -c inferno
.. figure:: ../figs/spe11b_spatial_map_250y_csv_csv_t-1.png
+ :alt: Comparison of SPE11B spatial maps from several submissions
:align: center
:width: 90%
+ Liquid-phase CO2 mass fraction at 250 years for several benchmark
+ submissions and the pyopmspe11 simulation.
+
+All inputs use columns 1, 2, and 5 for x, y, and liquid-phase CO2 mass
+fraction. A global colorbar makes the maps directly comparable.
+
+Create animations from CSV sequences
+------------------------------------
+
+To create a GIF from a sequence of CSV spatial-map files, include ``PLOPM`` in
+the input filename where the time value changes. Select the required times with
+:option:`plopm -r` and use ``-m gif``. **plopm** replaces ``PLOPM`` with each
+selected time when reading the files.
+
Reproduce this example
----------------------
-Run the complete workflow from the repository root:
+Run the complete workflow from the repository root. The script downloads or
+prepares the required benchmark CSV inputs before generating the figures:
.. code-block:: console
diff --git a/docs/_sources/examples/ensembles.rst.txt b/docs/_sources/examples/ensembles.rst.txt
index d3167c1..529b5e6 100644
--- a/docs/_sources/examples/ensembles.rst.txt
+++ b/docs/_sources/examples/ensembles.rst.txt
@@ -3,44 +3,120 @@
Different inputs and ensembles
==============================
-Compare cases and ensembles.
+Compare simulation cases, calculate differences between models, and summarize
+ensembles of related runs.
-Compare summary quantities from two simulations.
+Prepare the comparison cases
+----------------------------
+
+This example uses two SPE11B simulations with different injection rates. The
+base case is written to ``spe11b`` and the modified case to
+``spe11b_larger_inj``. The maintained Bash script prepares and runs both cases
+before generating the figures below.
+
+Compare summary quantities
+--------------------------
+
+Pass several input cases to :option:`plopm -i` and separate plotted variables
+with commas. The following command compares three related quantities:
.. code-block:: console
plopm -i 'spe11b/SPE11B spe11b_larger_inj/SPE11B' -v 'fgmip,fgmip / 1E6,RGMDS:5' -yl '[kg] [Kt] [kg]' -tu w -fs 10,5 -c r,b -ls 'solid,dashed' -t 'Field gas mass in place Converted to kilotonnes Dissolved CO$_2$ in facies 5' -fz 14 -sg 2,2 -rdl 1 -ll empty,empty,empty,center -fn comparison
.. figure:: ../figs/comparison.png
+ :alt: Summary quantities from two SPE11B simulations
:align: center
:width: 90%
-Subtract one case from another.
+ Field gas mass in place, the same quantity converted to kilotonnes, and
+ dissolved CO2 mass in facies 5 for the two simulations.
+
+The command demonstrates that variable expressions can be entered directly in
+:option:`plopm -v`. Here, ``fgmip / 1E6`` converts field gas mass in place from
+kilograms to kilotonnes.
+
+The remaining options control the comparison:
+
+* :option:`plopm -yl` assigns a y-axis label to each quantity.
+* :option:`plopm -tu` displays time in weeks.
+* :option:`plopm -c` and :option:`plopm -ls` distinguish the two cases by
+ color and line style.
+* :option:`plopm -sg` arranges the three plots in a two-by-two layout.
+* :option:`plopm -rdl` removes repeated subplot labels.
+* :option:`plopm -ll` removes legends from the first three panels and places
+ the shared legend in the remaining panel.
+
+Subtract one case from another
+------------------------------
+
+Use :option:`plopm -di` to subtract a reference case from the primary input.
+This command calculates the difference in gas saturation at restart step 3:
.. code-block:: console
plopm -i spe11b_larger_inj/SPE11B -v sgas -r 3 -di spe11b/SPE11B -hide 0,0,0,1
.. figure:: ../figs/sgas_diff.png
+ :alt: Difference in gas saturation between two SPE11B simulations
:align: center
:width: 90%
-Format the difference map.
+ Gas saturation in the higher-injection case minus gas saturation in the
+ base case.
+
+The input selected with :option:`plopm -di` must provide the same variable and
+a compatible grid. Positive values indicate a larger gas saturation in the
+primary input; negative values indicate a larger value in the reference case.
+
+Format the difference map
+-------------------------
+
+Customize the difference map with a colormap, fixed color limits, colorbar tick
+count, number format, and output filename:
.. code-block:: console
plopm -i spe11b_larger_inj/SPE11B -v sgas -r 3 -di spe11b/SPE11B -hide 0,0,0,1 -c tab20c_r -cl '[0,0.8]' -cbn 9 -cbf 0.1 -fn formated
.. figure:: ../figs/sgas_diff_edit.png
+ :alt: Formatted difference in gas saturation between two SPE11B simulations
:align: center
:width: 90%
-Use :option:`plopm -ens` for ensemble statistics.
+ Formatted gas-saturation difference with a fixed color range and nine
+ colorbar ticks.
+
+Use :option:`plopm -cl` when several difference maps must use the same color
+range. This makes the magnitudes directly comparable between figures.
+
+Plot ensemble statistics
+------------------------
+
+Use :option:`plopm -ens` to summarize a collection of simulations. Ensemble
+members are identified from the supplied input folders, and the selected mode
+controls which statistical representation is plotted:
+
+* ``-ens 0`` disables ensemble processing.
+* ``-ens 1`` plots the ensemble mean with error bands.
+* ``-ens 2`` plots the minimum, mean, and maximum.
+* ``-ens 3`` combines both representations.
+
+Use :option:`plopm -fb` with modes 1 and 3 to customize the fill colors and
+alpha values of the error bands.
.. figure:: ../figs/ensemble.png
+ :alt: Statistical summary of a simulation ensemble
:align: center
:width: 90%
+ Ensemble statistics generated from multiple related simulations.
+
+The `ensemble example directory
+`_ contains
+the supporting configuration and generation workflow. The maintained script
+also demonstrates the available :option:`plopm -ens` modes.
+
Reproduce this example
----------------------
diff --git a/docs/_sources/examples/filters.rst.txt b/docs/_sources/examples/filters.rst.txt
index 2cb938b..c1fe7aa 100644
--- a/docs/_sources/examples/filters.rst.txt
+++ b/docs/_sources/examples/filters.rst.txt
@@ -3,19 +3,87 @@
Filters
=======
-Select cells with conditions.
+Select cells by applying conditions to static or dynamic model variables.
-Join conditions for one input with ``&`` and separate input filters with commas.
+Filter syntax
+-------------
+
+Use :option:`plopm -flt` to define cell-selection conditions:
+
+* Join multiple conditions for one input with ``&``.
+* Separate filters for different inputs with commas.
+* Leave an entry empty when no filter should be applied to the corresponding
+ input.
+* Quote the complete filter expression so the shell does not interpret ``&``.
+
+Compare filtered selections
+---------------------------
+
+The following command reads the same SPE11B case three times and applies a
+different filter to each input:
.. code-block:: console
plopm -i 'SPE11B SPE11B SPE11B' -flt ',fipnum >= 2 & fipnum != 4,satnum == 5' -v fipnum -sg 3,1 -rdl 1 -cbf .0f -fs 7,4 -cbp 0.15,0.97,0.7,0.02 -t 'No filter fipnum >= 2 and fipnum != 4 satnum == 5' -st 0
.. figure:: ../figs/filter_opm.png
+ :alt: SPE11B FIP regions shown without a filter and with two cell-selection filters
:align: center
:width: 90%
-Dynamic filters require ``RPORV`` in ``RPTRST``.
+ ``fipnum`` without filtering, with two joined ``fipnum`` conditions, and
+ with cells restricted to ``satnum == 5``.
+
+The three comma-separated filter entries correspond to the three inputs in the
+same order:
+
+``empty``
+ Applies no filter to the first input.
+
+``fipnum >= 2 & fipnum != 4``
+ Keeps cells whose FIP region is at least 2 while excluding region 4.
+
+``satnum == 5``
+ Keeps cells assigned to facies 5.
+
+The subplot options arrange and format the comparison:
+
+* :option:`plopm -sg` creates three rows and one column.
+* :option:`plopm -rdl` removes repeated axis labels.
+* :option:`plopm -cbf` displays discrete FIP values without decimal places.
+* :option:`plopm -cbp` positions the shared horizontal colorbar.
+* :option:`plopm -t` assigns one title to each subplot; two spaces separate
+ the titles.
+* :option:`plopm -st` removes the common figure title.
+
+Supported conditions
+--------------------
+
+Filters can use comparison operators such as ``==``, ``!=``, ``>``, ``>=``,
+``<``, and ``<=``. The variable named in a condition does not need to be the
+same variable selected with :option:`plopm -v`.
+
+For example, this plots gas saturation only in facies 5:
+
+.. code-block:: console
+
+ plopm -i SPE11B -v sgas -flt 'satnum == 5'
+
+Dynamic filters
+---------------
+
+Filters using dynamic variables, such as ``sgas``, require ``RPORV`` in the
+OPM Flow ``RPTRST`` output request. The filter is evaluated at the selected
+restart step.
+
+For example:
+
+.. code-block:: console
+
+ plopm -i SPE11B -v pressure -r 4 -flt 'sgas >= 0.2'
+
+This plots pressure only in cells where gas saturation is at least 0.2 at
+restart step 4.
Reproduce this example
----------------------
diff --git a/docs/_sources/examples/generic-deck.rst.txt b/docs/_sources/examples/generic-deck.rst.txt
index afbfb46..f75e9a9 100644
--- a/docs/_sources/examples/generic-deck.rst.txt
+++ b/docs/_sources/examples/generic-deck.rst.txt
@@ -3,29 +3,71 @@
Generic deck
============
-Plot a generic OPM Flow model.
+Use **plopm** with a generic OPM Flow model. This example uses SPE10 MODEL 2
+to plot a reservoir property, inspect the grid, and display the wells.
-Plot vertical permeability from SPE10 MODEL 2.
+Plot vertical permeability
+--------------------------
+
+Plot vertical permeability on the fourth slice in the xz plane:
.. code-block:: console
plopm -i SPE10_MODEL2 -v permz -s ,4, -clog 1 -xu km -yu km -xnt 6 -yf .2f -t 'K$_z$ at the fourth slice in the xz plane' -cl '[1e-7,1e3]'
.. figure:: ../figs/spe10_model2_permz_*,4,*_t0.png
+ :alt: Vertical permeability on the fourth xz slice of SPE10 MODEL 2
:align: center
:width: 90%
-Plot the grid and wells from above.
+ Vertical permeability on the fourth xz slice, displayed with a logarithmic
+ color scale between ``1e-7`` and ``1e3`` mD.
+
+The main options are:
+
+* :option:`plopm -v` selects vertical permeability, ``permz``.
+* :option:`plopm -s` selects the fourth cell in the y direction and leaves the
+ x and z entries empty, producing an xz slice.
+* :option:`plopm -clog` enables logarithmic color scaling.
+* :option:`plopm -cl` sets fixed color-scale limits.
+* :option:`plopm -xu` and :option:`plopm -yu` display spatial coordinates in
+ kilometres.
+* :option:`plopm -xnt` sets the number of x-axis ticks.
+* :option:`plopm -yf` formats the y-axis tick labels with two decimal places.
+
+Plot the grid from above
+------------------------
+
+Select the first layer and use the special variable ``grid`` to inspect the
+model geometry from above:
.. code-block:: console
plopm -i SPE10_MODEL2 -s ,,1 -fs 3,4 -fz 8 -v grid -hide 0,0,1,0
+
+The four values supplied to :option:`plopm -hide` control the left axis,
+bottom axis, colorbar, and title, in that order. Here, the colorbar is hidden
+while the axes and title remain visible.
+
+Plot the wells from above
+-------------------------
+
+Use the same layer selection with the special variable ``wells``:
+
+.. code-block:: console
+
plopm -i SPE10_MODEL2 -s ,,1 -fs 3,4 -fz 8 -v wells -hide 0,0,0,1
.. figure:: ../figs/wells.png
+ :alt: SPE10 MODEL 2 grid and wells viewed from above
:align: center
:width: 90%
+ Top views of the SPE10 MODEL 2 grid and declared wells.
+
+For the wells plot, the final value in :option:`plopm -hide` removes the title.
+The well locations must be available in the OPM input deck.
+
Reproduce this example
----------------------
diff --git a/docs/_sources/examples/graphical-abstract.rst.txt b/docs/_sources/examples/graphical-abstract.rst.txt
index 9b74140..87c206e 100644
--- a/docs/_sources/examples/graphical-abstract.rst.txt
+++ b/docs/_sources/examples/graphical-abstract.rst.txt
@@ -3,39 +3,92 @@
Graphical abstract
==================
-Reproduce the graphical abstract.
+Reproduce the main elements of the **plopm** graphical abstract. The workflow
+combines three different uses of **plopm**:
-The graphical abstract combines an SPE11B summary comparison, a Norne map, and an SPE11C VTK visualization.
+* A summary comparison between two SPE11B simulations.
+* A transformed top view of the Norne model.
+* VTK output from a three-dimensional SPE11C model for visualization in
+ ParaView.
.. figure:: ../figs/plopm.png
+ :alt: Graphical abstract showing SPE11B, Norne, and SPE11C visualization workflows
:align: center
:width: 90%
- The plopm graphical abstract.
+ The **plopm** graphical abstract combines summary plotting, spatial-map
+ generation, and VTK export.
-Generate the SPE11B comparison.
+Compare two SPE11B simulations
+------------------------------
+
+Generate a base SPE11B case and a second case with a higher injection rate.
+The maintained script downloads the pyopmspe11 configuration, modifies the
+injection rate, and runs both simulations before creating the comparison.
+
+Plot field gas mass in place for both cases and convert the values from
+kilograms to kilotonnes directly in the variable expression:
.. code-block:: console
plopm -i 'spe11b/SPE11B spe11b_higher_rate/SPE11B_HIGHER_RATE' -v 'fgmip * 1e-6' -c 'r,b' -tu y -xf .0f -lw 2 -llb 'Base case Higher injection rate' -xnt 6 -yl 'Total CO$_2$ mass [Kt]' -fz 18 -t 'Comparing two runs of the SPE11B model'
-Generate the Norne map.
+The command demonstrates:
+
+* Multiple simulation inputs with :option:`plopm -i`.
+* Arithmetic expressions in :option:`plopm -v`.
+* Time conversion to years with :option:`plopm -tu`.
+* Custom colors, labels, line widths, ticks, and title formatting.
+
+Generate the Norne map
+----------------------
+
+Clone the OPM example-data repository and use an OPM Flow dry run to generate
+the files required by **plopm**:
.. code-block:: console
git clone https://github.com/OPM/opm-data.git
flow opm-data/norne/NORNE_ATW2013.DATA --enable-dry-run=1
+
+Plot horizontal permeability on the top layer, then rotate, translate, and crop
+the grid:
+
+.. code-block:: console
+
plopm -i opm-data/norne/NORNE_ATW2013 -v permx -clog 1 -rot 65 -s ,,1 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,7600]' -t 'Top view of NORNE' -xu km -yu km -fz 16 -ge 'black,1e-2' -xf .1f -yf .1f -fs 8,8
-Generate SPE11C VTK files.
+This part of the graphical abstract demonstrates logarithmic color scaling,
+coordinate transformations, spatial cropping, grid edges, and unit conversion.
+
+Generate SPE11C VTK files
+-------------------------
+
+Install **pyopmspe11**, download its SPE11C example configuration, and run the
+case without output subfolders:
.. code-block:: console
pip install git+https://github.com/OPM/pyopmspe11.git
curl -L -O https://raw.githubusercontent.com/OPM/pyopmspe11/refs/heads/main/examples/spe11c.toml
- pyopmspe11 -i spe11c.toml -o spe11c -fz 0
+ pyopmspe11 -i spe11c.toml -o spe11c -f 0
+
+Export facies and liquid-phase CO2 mass fraction at the initial and final
+selected restart steps:
+
+.. code-block:: console
+
plopm -i spe11c/SPE11C -v satnum,xco2l -vf UInt16,Float16 -r 0,5 -m vtk
+Here, :option:`plopm -vf` assigns an unsigned 16-bit integer type to ``satnum``
+and a 16-bit floating-point type to ``xco2l``. The generated VTK files can be
+opened in ParaView for three-dimensional inspection.
+
+.. note::
+
+ OPM Flow is required to run the SPE11 simulations and to prepare the Norne
+ model. ParaView is required only to inspect the generated VTK files.
+
Reproduce this example
----------------------
diff --git a/docs/_sources/examples/hello-world.rst.txt b/docs/_sources/examples/hello-world.rst.txt
index 061a8e5..b3606e2 100644
--- a/docs/_sources/examples/hello-world.rst.txt
+++ b/docs/_sources/examples/hello-world.rst.txt
@@ -3,48 +3,97 @@
Hello world
===========
-Create maps, summary plots, and cell time series.
+Create spatial maps, summary plots, and cell time series from an SPE11B model.
-Run the default command from the ``examples`` directory.
+Run the default command
+-----------------------
+
+Run the following command from the ``examples`` directory:
.. code-block:: console
plopm -i SPE11B
.. figure:: ../figs/spe11b_satnum_*,1,*_t5.png
+ :alt: Default SPE11B SATNUM plot on the middle xz slice
:align: center
:width: 90%
-Plot gas saturation at restart step 4.
+ The default command plots the standard static variables. This figure shows
+ ``satnum`` on the default ``,1,`` slice at the final restart step.
+
+When :option:`plopm -v` is omitted, **plopm** plots its default variable set.
+The default spatial selection is ``,1,``, which displays the first xz slice.
+
+Plot gas saturation
+-------------------
+
+Select gas saturation at restart step 4 and customize the colorbar:
.. code-block:: console
plopm -i SPE11B -v sgas -r 4 -cbn 3 -c cubehelix -cbt '[0, middle, 0.9]'
.. figure:: ../figs/spe11b_sgas_i,1,k_t4.png
+ :alt: SPE11B gas saturation at restart step 4
:align: center
:width: 90%
-Plot field gas in place.
+ Gas saturation on the default xz slice at restart step 4.
+
+The command uses:
+
+* :option:`plopm -v` to select ``sgas``.
+* :option:`plopm -r` to select restart step 4.
+* :option:`plopm -c` to select the ``cubehelix`` colormap.
+* :option:`plopm -cbn` to use three colorbar ticks.
+* :option:`plopm -cbt` to replace the numeric tick labels with custom text.
+
+Plot field gas in place
+-----------------------
+
+Summary quantities are plotted over time rather than on a spatial slice. Plot
+field gas in place with dates on the x-axis:
.. code-block:: console
plopm -i SPE11B -v fgip -c b -ls dotted -fz 12 -fs 5,5 -lw 4 -tu dates
.. figure:: ../figs/fgip.png
+ :alt: SPE11B field gas in place over time
:align: center
:width: 90%
-Plot pressure increase at three cells.
+ Field gas in place plotted against simulation dates.
+
+Here, :option:`plopm -tu` selects dates, while :option:`plopm -c`,
+:option:`plopm -ls`, and :option:`plopm -lw` control the line appearance.
+
+Plot cell values over time
+--------------------------
+
+Select three cells and plot pressure increase relative to the initial pressure:
.. code-block:: console
plopm -i 'SPE11B SPE11B SPE11B' -v 'pressure - 0pressure' -s '1,1,1 41,1,29 83,1,58' -llb 'Top left corner Middle Right lower corner' -yl 'Pressure increase at the sensor locations [bar]' -yf .0f -xnt 11 -tu dates
.. figure:: ../figs/spe11b_pressure-0pressure.png
+ :alt: Pressure increase at three SPE11B cells over time
:align: center
:width: 90%
+ Pressure increase at cells near the top-left corner, middle, and lower-right
+ corner of the model.
+
+Three indices in :option:`plopm -s` select one cell over time. The three input
+entries correspond to the three cell selections. The expression
+``pressure - 0pressure`` subtracts the initial pressure from each time step.
+
+The legend labels are separated by two spaces. :option:`plopm -yf` displays
+pressure values without decimal places, and :option:`plopm -xnt` sets eleven
+x-axis ticks.
+
Reproduce this example
----------------------
diff --git a/docs/_sources/examples/histograms.rst.txt b/docs/_sources/examples/histograms.rst.txt
index 2231358..00c37b7 100644
--- a/docs/_sources/examples/histograms.rst.txt
+++ b/docs/_sources/examples/histograms.rst.txt
@@ -3,18 +3,67 @@
Histograms
==========
-Plot property distributions.
+Plot distributions of static reservoir properties and optionally fit
+probability distributions to the data.
-Plot porosity and permeability histograms with fitted distributions.
+Plot porosity and permeability distributions
+---------------------------------------------
+
+Plot porosity and x-direction permeability from the Norne model. Use 20 bins
+for each histogram, fit a normal distribution to porosity, and fit a lognormal
+distribution to permeability:
.. code-block:: console
plopm -i NORNE_ATW2013 -v poro,permx -hist '20,norm 20,lognorm' -ag 0 -sg 1,2 -fs 15,5 -ll 'upper center' -y '[0,10000] [0,23000]' -c '#7274b3,#cddb6e'
.. figure:: ../figs/norne_atw2013_permx.png
+ :alt: Porosity and permeability histograms for the Norne model
:align: center
:width: 90%
+ Porosity with a fitted normal distribution and x-direction permeability
+ with a fitted lognormal distribution.
+
+Histogram syntax
+----------------
+
+Use :option:`plopm -hist` to set the number of bins and an optional fitted
+distribution:
+
+``20``
+ Creates a histogram with 20 bins and no fitted distribution.
+
+``20,norm``
+ Creates a histogram with 20 bins and fits a normal distribution.
+
+``20,lognorm``
+ Creates a histogram with 20 bins and fits a lognormal distribution.
+
+Separate specifications for multiple plots with spaces. In this example,
+``20,norm 20,lognorm`` applies the normal fit to ``poro`` and the lognormal fit
+to ``permx``.
+
+Format the figure
+-----------------
+
+The remaining options control the subplot layout and appearance:
+
+* :option:`plopm -ag` disables the axis grid.
+* :option:`plopm -sg` places both histograms in one row with two columns.
+* :option:`plopm -fs` sets the complete figure size to 15 by 5 inches.
+* :option:`plopm -ll` places each legend at the upper center.
+* :option:`plopm -y` applies separate y-axis limits to the two plots.
+* :option:`plopm -c` assigns a different color to each histogram.
+
+The two y-axis limits are separated by a space and correspond to the variables
+in the order supplied through :option:`plopm -v`.
+
+.. note::
+
+ Lognormal fitting is appropriate only for positive values. Review the data
+ and selected property before choosing a fitted distribution.
+
Reproduce this example
----------------------
diff --git a/docs/_sources/examples/projections.rst.txt b/docs/_sources/examples/projections.rst.txt
index 6a11f7a..d586f66 100644
--- a/docs/_sources/examples/projections.rst.txt
+++ b/docs/_sources/examples/projections.rst.txt
@@ -3,18 +3,80 @@
Projections and subfigures
==========================
-Combine projection methods in one figure.
+Project several layers onto a two-dimensional map, apply a different
+aggregation method to each variable, and combine the results in one figure.
-Apply a different aggregation to each projected quantity.
+Select the projected layers
+---------------------------
+
+Use :option:`plopm -s` with the range ``1:22`` to project the first 22 layers
+of the Norne model. Repeat the spatial selection once for each plotted
+variable:
.. code-block:: console
plopm -i NORNE_ATW2013 -v 'index_k,permx,poro' -s ',,1:22 ,,1:22 ,,1:22' -agg 'first,arithmetic,max' -sg 1,3 -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,8800]' -fs 24,10 -c 'PuOr,vanimo,jet' -cbf '.0f,.0f,.2f' -cbn '2,4,8' -st 0 -t 'Top k values using first Averaged permx using arithmetic Values of porosity using max' -fz 18
.. figure:: ../figs/norne_atw2013_poro_i,j,1:22_t64.png
+ :alt: Norne layer index, permeability, and porosity projected across layers 1 through 22
:align: center
:width: 90%
+ Layer index, x-direction permeability, and porosity projected across the
+ first 22 layers with three different aggregation methods.
+
+Apply different aggregation methods
+-----------------------------------
+
+Use :option:`plopm -agg` to select how values from several cells are combined
+at each projected map location. The methods are applied in the same order as
+the variables:
+
+``first``
+ Selects the first value encountered along the projection direction. Here it
+ displays the top ``index_k`` value.
+
+``arithmetic``
+ Calculates the arithmetic mean. Here it averages ``permx`` across the
+ selected layers.
+
+``max``
+ Selects the maximum value. Here it displays the largest ``poro`` value
+ across the selected layers.
+
+The command therefore applies:
+
+.. code-block:: text
+
+ index_k -> first
+ permx -> arithmetic
+ poro -> max
+
+If :option:`plopm -agg` is omitted, **plopm** selects an aggregation method
+based on the variable type. Providing it explicitly is useful when comparing
+projection methods or when the scientific interpretation requires a specific
+calculation.
+
+Arrange and format the subfigures
+---------------------------------
+
+The remaining options control the combined figure:
+
+* :option:`plopm -sg` arranges the three maps in one row and three columns.
+* :option:`plopm -rot` rotates the Norne grid by 65 degrees.
+* :option:`plopm -tr` translates the rotated coordinates.
+* :option:`plopm -x` and :option:`plopm -y` crop the displayed region.
+* :option:`plopm -c` assigns a different colormap to each variable.
+* :option:`plopm -cbf` applies separate colorbar number formats.
+* :option:`plopm -cbn` uses 2, 4, and 8 colorbar ticks for the three maps.
+* :option:`plopm -st` removes the common figure title.
+* :option:`plopm -t` assigns one title to each subplot. Two spaces separate
+ consecutive titles.
+
+The lists supplied to :option:`plopm -agg`, :option:`plopm -c`,
+:option:`plopm -cbf`, and :option:`plopm -cbn` correspond to the variables in
+the order supplied through :option:`plopm -v`.
+
Reproduce this example
----------------------
diff --git a/docs/_sources/examples/relative-permeability.rst.txt b/docs/_sources/examples/relative-permeability.rst.txt
index d5148cd..3c417aa 100644
--- a/docs/_sources/examples/relative-permeability.rst.txt
+++ b/docs/_sources/examples/relative-permeability.rst.txt
@@ -3,19 +3,82 @@
Relative permeability and capillary pressure
============================================
-Plot saturation functions.
+Plot saturation functions stored in an OPM Flow deck, including hysteresis
+curves when they are available.
-Append a SATNUM table number or ``h`` for hysteresis curves.
+Variable syntax
+---------------
+
+Use the saturation-function variable name by itself to read the first SATNUM
+table. Append a table number to select another SATNUM region, or append ``h``
+to select hysteresis curves.
+
+Examples include:
+
+``krg``
+ Gas relative permeability from the first SATNUM table.
+
+``krg2``
+ Gas relative permeability from SATNUM table 2.
+
+``krgh``
+ Gas relative-permeability hysteresis curve.
+
+``krwh``
+ Water relative-permeability hysteresis curve.
+
+``pcwg``
+ Gas-water capillary pressure from the first SATNUM table.
+
+Plot hysteresis relative permeability
+-------------------------------------
+
+Plot the hydrogen and brine hysteresis curves from the H2HYSTERESIS model:
.. code-block:: console
plopm -i H2HYSTERESIS -v krgh,krwh -llb 'Hydrogen Brine' -c r,#0314fc -x '[0,1]' -lw 5 -fz 18 -fs 8,6 -yl 'Relative permeability, $k_r$ [-]' -xl 'Liquid saturation, $s_w$ [-]' -ls solid,solid -xnt 6 -ynt 6
+
+The variables ``krgh`` and ``krwh`` select the gas and water hysteresis curves.
+The legend labels are separated by two spaces and correspond to the variables
+in the order supplied through :option:`plopm -v`.
+
+Plot capillary pressure
+-----------------------
+
+Plot the gas-water capillary-pressure curve on a logarithmic y-axis:
+
+.. code-block:: console
+
plopm -i H2HYSTERESIS -v pcwg -c k -x '[0,1]' -lw 5 -ll empty -fz 18 -fs 8,6 -yl 'Capillary pressure, $p_c$ [bar]' -xl 'Liquid saturation, $s_w$ [-]' -xnt 6 -ylog 1
.. figure:: ../figs/saturation_functions.png
+ :alt: Hydrogen and brine relative permeability and gas-water capillary pressure
:align: center
:width: 90%
+ Relative-permeability hysteresis curves for hydrogen and brine, together
+ with gas-water capillary pressure.
+
+Format the curves
+-----------------
+
+The plotting options control both saturation-function figures:
+
+* :option:`plopm -x` limits liquid saturation to the interval from 0 to 1.
+* :option:`plopm -lw` sets the line width.
+* :option:`plopm -fs` sets the figure size.
+* :option:`plopm -xl` and :option:`plopm -yl` set the axis labels.
+* :option:`plopm -xnt` and :option:`plopm -ynt` set the axis tick counts.
+* :option:`plopm -ll` removes the capillary-pressure legend.
+* :option:`plopm -ylog` enables logarithmic scaling for capillary pressure.
+
+.. note::
+
+ The requested SATNUM table or hysteresis data must be present in the OPM
+ input deck. If no suffix is supplied, **plopm** reads the first available
+ saturation-function table.
+
Reproduce this example
----------------------
diff --git a/docs/_sources/examples/transformations.rst.txt b/docs/_sources/examples/transformations.rst.txt
index f109312..bcba759 100644
--- a/docs/_sources/examples/transformations.rst.txt
+++ b/docs/_sources/examples/transformations.rst.txt
@@ -3,53 +3,53 @@
Rotation, translation, and zoom
===============================
-Transform, crop, and inspect Norne.
+Transform, crop, and inspect the Norne grid.
-Start with the Norne top view.
+Start with the Norne top view
+-----------------------------
+
+Plot the first layer before applying coordinate transformations:
.. code-block:: console
plopm -i NORNE_ATW2013 -s ,,1
.. figure:: ../figs/norne.png
+ :alt: Original top view of the Norne grid
:align: center
:width: 90%
-Rotate, translate, and crop the grid.
-
-.. code-block:: console
-
- plopm -i NORNE_ATW2013 -s ,,1 -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,7600]' -fz 8
+ Original top view of the first Norne layer.
-.. figure:: ../figs/norne_transformed.png
- :align: center
- :width: 90%
+Rotate, translate, and crop the grid
+------------------------------------
-Apply the same transformation to faults.
+Rotate the model by 65 degrees, translate the coordinates, and crop the map to
+the selected x and y limits:
.. code-block:: console
- plopm -i NORNE_ATW2013 -v faults -s ,,1 -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,8800]' -fz 8 -gr 1
- plopm -i NORNE_ATW2013 -v faults -s ,,1:22 -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,8800]' -fz 8 -agg max
+ plopm -i NORNE_ATW2013 -s ,,1 -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,7600]' -fz 8
-.. figure:: ../figs/norne_faults.png
+.. figure:: ../figs/norne_transformed.png
+ :alt: Rotated, translated, and cropped Norne grid
:align: center
:width: 90%
-Plot all wells and wells on the selected layer.
-
-.. code-block:: console
+ Norne after rotation, translation, and spatial cropping.
- plopm -i NORNE_ATW2013 -v wells -s ,,1 -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,8800]' -fz 8 -gr 1 -fn norne_wells_global
- plopm -i NORNE_ATW2013 -v wells -s ,,1 -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,8800]' -fz 8 -fn norne_wells
-
-.. figure:: ../figs/norne_wells.png
- :align: center
- :width: 90%
+The transformation options are applied in the following order:
-.. note::
+* :option:`plopm -rot` rotates the grid counterclockwise by the selected angle
+ in degrees.
+* :option:`plopm -tr` translates the rotated x and y coordinates.
+* :option:`plopm -x` and :option:`plopm -y` crop the displayed coordinate
+ range.
+* :option:`plopm -fz` sets the font size.
- Faults and wells must be declared directly in the input deck.
+Use the same transformation values when comparing properties, faults, wells,
+or other spatial outputs from the same model. See :doc:`wells-faults` for Norne
+fault and well examples using this transformation.
Reproduce this example
----------------------
diff --git a/docs/_sources/examples/vtk.rst.txt b/docs/_sources/examples/vtk.rst.txt
index 0c5c96a..4a12bd8 100644
--- a/docs/_sources/examples/vtk.rst.txt
+++ b/docs/_sources/examples/vtk.rst.txt
@@ -3,20 +3,95 @@
Convert to VTK
==============
-Export data for `ParaView `_.
+Export OPM Flow grid and property data to VTK for three-dimensional inspection
+in `ParaView `_.
-Export selected variables for restart steps 0 and 5.
+Requirements
+------------
+
+OPM Flow is required to generate the grid used by the VTK export. If the
+``flow`` executable is not available on ``PATH``, select it with
+:option:`plopm -fp`.
+
+Export selected variables
+-------------------------
+
+Export temperature, FIP regions, total CO2 mass, and liquid-phase CO2 mass
+fraction for restart steps 0 and 5:
.. code-block:: console
plopm -i SPE11B -v temp,fipnum,co2m,xco2l -vf Float32,UInt16,Float64,Float16 -r 0,5 -m vtk
.. figure:: ../figs/vtk_temp.png
+ :alt: SPE11B grid and temperature after 25 years viewed in ParaView
:align: center
:width: 90%
Grid and temperature after 25 years of CO2 injection, viewed in ParaView.
+Select VTK data types
+---------------------
+
+Use :option:`plopm -vf` to assign a VTK data type to each variable. The data
+types correspond to the variables in the order supplied through
+:option:`plopm -v`:
+
+.. code-block:: text
+
+ temp -> Float32
+ fipnum -> UInt16
+ co2m -> Float64
+ xco2l -> Float16
+
+The selected types balance precision and file size:
+
+``Float32``
+ Stores temperature with single-precision floating-point values.
+
+``UInt16``
+ Stores the discrete ``fipnum`` region identifiers as unsigned integers.
+
+``Float64``
+ Preserves higher precision for total CO2 mass.
+
+``Float16``
+ Reduces storage for the bounded liquid-phase CO2 mass fraction.
+
+Use a wider type when the expected value range or required numerical precision
+cannot be represented safely by a smaller type.
+
+Select restart steps
+--------------------
+
+The command uses :option:`plopm -r` to export the initial state and restart
+step 5. **plopm** writes the selected variables for each requested step so the
+results can be inspected or animated in ParaView.
+
+Customize variable names
+------------------------
+
+Use :option:`plopm -vn` to assign custom names in the VTK output:
+
+.. code-block:: console
+
+ plopm -i SPE11B -v temp,fipnum,co2m,xco2l -vn temperature,fip_region,total_co2_mass,liquid_co2_fraction -vf Float32,UInt16,Float64,Float16 -r 0,5 -m vtk
+
+The number of names supplied through :option:`plopm -vn` must match the number
+of variables selected with :option:`plopm -v`.
+
+Use a custom Flow executable
+----------------------------
+
+If Flow is installed outside ``PATH``, provide its executable explicitly:
+
+.. code-block:: console
+
+ plopm -i SPE11B -v temp,fipnum,co2m,xco2l -vf Float32,UInt16,Float64,Float16 -r 0,5 -m vtk -fp /path/to/flow
+
+See :ref:`opm-flow-installation` for OPM Flow installation guidance and
+:ref:`options-vtk` for the complete VTK option reference.
+
Reproduce this example
----------------------
diff --git a/docs/_sources/examples/wells-faults.rst.txt b/docs/_sources/examples/wells-faults.rst.txt
new file mode 100644
index 0000000..21b14f8
--- /dev/null
+++ b/docs/_sources/examples/wells-faults.rst.txt
@@ -0,0 +1,110 @@
+.. _example-wells-faults:
+
+Wells and faults
+================
+
+Plot faults and wells declared in the Norne input deck. Apply the same rotation,
+translation, and cropping values used for the transformed Norne grid so the
+outputs remain spatially consistent.
+
+.. note::
+
+ Faults and wells must be declared directly in the input deck.
+
+Plot faults
+-----------
+
+Plot faults intersecting the first layer and use the whole-model value range:
+
+.. code-block:: console
+
+ plopm -i NORNE_ATW2013 -v faults -s ,,1 -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,8800]' -fz 8 -gr 1
+
+Project faults across layers 1 through 22. Use ``max`` so a map cell is shown
+only when the projected fault condition is present across the selected cells:
+
+.. code-block:: console
+
+ plopm -i NORNE_ATW2013 -v faults -s ,,1:22 -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,8800]' -fz 8 -agg max
+
+.. figure:: ../figs/norne_faults.png
+ :alt: Norne faults on one layer and projected across layers 1 through 22
+ :align: center
+ :width: 90%
+
+ Norne faults on the first layer and projected across the first 22 layers.
+
+The main options are:
+
+* ``faults`` is a special variable selected with :option:`plopm -v`.
+* :option:`plopm -gr` uses the whole-model range for the first-layer plot.
+* :option:`plopm -agg` controls how faults are combined across a layer range.
+* :option:`plopm -rot`, :option:`plopm -tr`, :option:`plopm -x`, and
+ :option:`plopm -y` apply the same transformation as the property map.
+
+Plot wells
+----------
+
+Plot all wells declared in the model, regardless of whether they intersect the
+selected layer:
+
+.. code-block:: console
+
+ plopm -i NORNE_ATW2013 -v wells -s ,,1 -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,8800]' -fz 8 -gr 1 -fn norne_wells_global
+
+Plot only the wells intersecting the selected layer:
+
+.. code-block:: console
+
+ plopm -i NORNE_ATW2013 -v wells -s ,,1 -rot 65 -tr '[6456335.5,-3476500]' -x '[0,5600]' -y '[0,8800]' -fz 8 -fn norne_wells
+
+.. figure:: ../figs/norne_wells.png
+ :alt: All Norne wells and wells intersecting the selected layer
+ :align: center
+ :width: 90%
+
+ All declared Norne wells and the subset intersecting the first layer.
+
+For the first command, :option:`plopm -gr` selects the global well view and
+:option:`plopm -fn` writes ``norne_wells_global``. Without the global-range
+selection, the second command restricts the output to wells associated with the
+selected layer and writes ``norne_wells``.
+
+See :doc:`transformations` for the original and transformed Norne grid views.
+
+Reproduce this example
+----------------------
+
+Run the complete workflow from the repository root:
+
+.. code-block:: console
+
+ . ./tests/scripts/docs_wells-faults.sh
+
+.. grid:: 1 2 2 2
+ :gutter: 2
+
+ .. grid-item::
+
+ .. button-link:: https://github.com/cssr-tools/plopm/blob/main/tests/scripts/docs_wells-faults.sh
+ :color: primary
+ :outline:
+ :expand:
+
+ View script
+
+ .. grid-item::
+
+ .. button-link:: https://raw.githubusercontent.com/cssr-tools/plopm/main/tests/scripts/docs_wells-faults.sh
+ :color: secondary
+ :outline:
+ :expand:
+
+ View raw script
+
+.. button-ref:: examples-gallery
+ :ref-type: ref
+ :color: primary
+ :outline:
+
+ Back to the examples gallery
diff --git a/docs/_sources/index.rst.txt b/docs/_sources/index.rst.txt
index 1f15f2a..494a6be 100644
--- a/docs/_sources/index.rst.txt
+++ b/docs/_sources/index.rst.txt
@@ -56,14 +56,14 @@ Plot pressure on the plane at ``j=1``:
.. code-block:: console
- plopm -i SPE11B -v pressure -s ,1,
+ plopm -i examples/SPE11B -v pressure -s ,1,
Display the built-in help or list the variables available for an input case:
.. code-block:: console
plopm --help
- plopm -i SPE11B -lv 1
+ plopm -i examples/SPE11B -lv 1
See the :doc:`tutorial` for a guided workflow and the :doc:`command-line` for
exact syntax and option descriptions.
diff --git a/docs/_sources/options/syntax.rst.txt b/docs/_sources/options/syntax.rst.txt
index 0f58f5b..9688a98 100644
--- a/docs/_sources/options/syntax.rst.txt
+++ b/docs/_sources/options/syntax.rst.txt
@@ -13,7 +13,7 @@ For example:
.. code-block:: console
- plopm -i SPE11C -v pressure -s ,1, -r 5
+ plopm -i SPE11C -v pressure -s ,1, -r 2
Use ``plopm --help`` for the options supported by the installed version.
@@ -125,7 +125,7 @@ Select a range with ``-s`` and apply an aggregation method with ``-agg``:
.. code-block:: console
- plopm -i SPE11C -v pressure -s ,,5:10 -agg mean -r 5
+ plopm -i SPE11C -v pressure -s ,,5:10 -agg mean -r 2
Supported methods are ``min``, ``max``, ``sum``, ``mean``, ``pvmean``,
``harmonic``, ``arithmetic``, ``first``, and ``last``.
diff --git a/docs/api.html b/docs/api.html
index 8014400..acbb9f3 100644
--- a/docs/api.html
+++ b/docs/api.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/modules.html b/docs/api/modules.html
index b4954d3..dcb667e 100644
--- a/docs/api/modules.html
+++ b/docs/api/modules.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.config.config.html b/docs/api/plopm.config.config.html
index 52ddfce..ce4f1b4 100644
--- a/docs/api/plopm.config.config.html
+++ b/docs/api/plopm.config.config.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.config.html b/docs/api/plopm.config.html
index b3e7e4a..df258db 100644
--- a/docs/api/plopm.config.html
+++ b/docs/api/plopm.config.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.core.html b/docs/api/plopm.core.html
index a203806..29b64db 100644
--- a/docs/api/plopm.core.html
+++ b/docs/api/plopm.core.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.core.plopm.html b/docs/api/plopm.core.plopm.html
index 5424461..dac9bb3 100644
--- a/docs/api/plopm.core.plopm.html
+++ b/docs/api/plopm.core.plopm.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.html b/docs/api/plopm.html
index b9e8f2c..6c94f03 100644
--- a/docs/api/plopm.html
+++ b/docs/api/plopm.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.utils.html b/docs/api/plopm.utils.html
index feaf4ec..931e1f9 100644
--- a/docs/api/plopm.utils.html
+++ b/docs/api/plopm.utils.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.utils.initialization.html b/docs/api/plopm.utils.initialization.html
index cfba36f..21335c6 100644
--- a/docs/api/plopm.utils.initialization.html
+++ b/docs/api/plopm.utils.initialization.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.utils.mapping.html b/docs/api/plopm.utils.mapping.html
index 48c4194..b66e51d 100644
--- a/docs/api/plopm.utils.mapping.html
+++ b/docs/api/plopm.utils.mapping.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.utils.readers.html b/docs/api/plopm.utils.readers.html
index a2dc90a..11aef0f 100644
--- a/docs/api/plopm.utils.readers.html
+++ b/docs/api/plopm.utils.readers.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.utils.terminal.html b/docs/api/plopm.utils.terminal.html
index 4249312..14c76bb 100644
--- a/docs/api/plopm.utils.terminal.html
+++ b/docs/api/plopm.utils.terminal.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.utils.write_oned.html b/docs/api/plopm.utils.write_oned.html
index 5f69dda..f880389 100644
--- a/docs/api/plopm.utils.write_oned.html
+++ b/docs/api/plopm.utils.write_oned.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.utils.write_twod.html b/docs/api/plopm.utils.write_twod.html
index 00e1591..5cb2b1a 100644
--- a/docs/api/plopm.utils.write_twod.html
+++ b/docs/api/plopm.utils.write_twod.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/api/plopm.utils.write_vtk.html b/docs/api/plopm.utils.write_vtk.html
index 99dbdb2..ec1bcca 100644
--- a/docs/api/plopm.utils.write_vtk.html
+++ b/docs/api/plopm.utils.write_vtk.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/command-line.html b/docs/command-line.html
index 106b922..e86cfc5 100644
--- a/docs/command-line.html
+++ b/docs/command-line.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/contributing.html b/docs/contributing.html
index 22a2d24..672b66c 100644
--- a/docs/contributing.html
+++ b/docs/contributing.html
@@ -56,7 +56,7 @@
-
+
diff --git a/docs/examples.html b/docs/examples.html
index bb29c2c..5ce3111 100644
--- a/docs/examples.html
+++ b/docs/examples.html
@@ -56,7 +56,7 @@
-
+
@@ -426,9 +426,10 @@
limipres, overpres, and objepres support caprock-integrity analysis.
+
Evaluate pressure limits and identify regions where reservoir pressure exceeds
+the estimated caprock pressure limit.
+
The special variables limipres, overpres, and objepres support
+caprock-integrity analysis:
+
+
limipres
Estimated limiting pressure based on depth and the stress coefficient.
+
+
overpres
Difference between the simulated pressure and the estimated limiting
+pressure. Positive values identify cells where the pressure exceeds the
+estimated limit.
+
+
objepres
Objective value derived from the pressure-limit calculation. This quantity
+can be exported to CSV for use in optimization and sensitivity workflows.
+
+
+
The pressure-limit calculation uses the stress coefficient selected with
+plopm-sc.
Use named colormaps, RGB values, or hexadecimal colors to customize discrete
+and continuous variables. Combine several plots in one figure with either
+individual or shared colorbars.
Combine static and dynamic quantities in one figure. When the plotted
+quantities use different value ranges or colormaps, each subplot has its own
+colorbar:
When subfigures show the same quantity from different inputs or restart steps,
+use one shared colorbar. Position and size the shared colorbar with
+plopm-cbp:
plopm-c applies one common colormap to all four temperature maps.
+
+
plopm-asp disables equal axis scaling, while
+plopm-rdl removes repeated subplot labels. Two spaces separate the
+four titles supplied through plopm-t.
Liquid-phase CO2 mass fraction from the OPM Flow simulation grid and the
+SPE11B reporting-grid CSV file at 500 years.#
+
-
Compare a CSV series with an OPM summary vector.
+
The first column specification is empty because the first input is an OPM Flow
+case. The second input uses columns 1, 2, and 5 for x, y, and the plotted value.
The empty first entry in plopm-v is a placeholder for the CSV input.
+The empty second entry in plopm-cc indicates that the second input
+is read as OPM Flow output. The scale factors convert the two sources to the
+same displayed unit.
To create a GIF from a sequence of CSV spatial-map files, include PLOPM in
+the input filename where the time value changes. Select the required times with
+plopm-r and use -mgif. plopm replaces PLOPM with each
+selected time when reading the files.
This example uses two SPE11B simulations with different injection rates. The
+base case is written to spe11b and the modified case to
+spe11b_larger_inj. The maintained Bash script prepares and runs both cases
+before generating the figures below.
Field gas mass in place, the same quantity converted to kilotonnes, and
+dissolved CO2 mass in facies 5 for the two simulations.#
+
-
Subtract one case from another.
+
The command demonstrates that variable expressions can be entered directly in
+plopm-v. Here, fgmip/1E6 converts field gas mass in place from
+kilograms to kilotonnes.
Gas saturation in the higher-injection case minus gas saturation in the
+base case.#
+
-
Format the difference map.
+
The input selected with plopm-di must provide the same variable and
+a compatible grid. Positive values indicate a larger gas saturation in the
+primary input; negative values indicate a larger value in the reference case.
Use plopm-ens to summarize a collection of simulations. Ensemble
+members are identified from the supplied input folders, and the selected mode
+controls which statistical representation is plotted:
+
+
-ens0 disables ensemble processing.
+
-ens1 plots the ensemble mean with error bands.
+
-ens2 plots the minimum, mean, and maximum.
+
-ens3 combines both representations.
+
+
Use plopm-fb with modes 1 and 3 to customize the fill colors and
+alpha values of the error bands.
+
+
+
+
Ensemble statistics generated from multiple related simulations.#
+
+
The ensemble example directory contains
+the supporting configuration and generation workflow. The maintained script
+also demonstrates the available plopm-ens modes.
Filters can use comparison operators such as ==, !=, >, >=,
+<, and <=. The variable named in a condition does not need to be the
+same variable selected with plopm-v.
+
For example, this plots gas saturation only in facies 5:
Filters using dynamic variables, such as sgas, require RPORV in the
+OPM Flow RPTRST output request. The filter is evaluated at the selected
+restart step.
The four values supplied to plopm-hide control the left axis,
+bottom axis, colorbar, and title, in that order. Here, the colorbar is hidden
+while the axes and title remain visible.
Generate a base SPE11B case and a second case with a higher injection rate.
+The maintained script downloads the pyopmspe11 configuration, modifies the
+injection rate, and runs both simulations before creating the comparison.
+
Plot field gas mass in place for both cases and convert the values from
+kilograms to kilotonnes directly in the variable expression:
plopm -i 'spe11b/SPE11B spe11b_higher_rate/SPE11B_HIGHER_RATE' -v 'fgmip * 1e-6' -c 'r,b' -tu y -xf .0f -lw 2 -llb 'Base case Higher injection rate' -xnt 6 -yl 'Total CO$_2$ mass [Kt]' -fz 18 -t 'Comparing two runs of the SPE11B model'
This part of the graphical abstract demonstrates logarithmic color scaling,
+coordinate transformations, spatial cropping, grid edges, and unit conversion.
Here, plopm-vf assigns an unsigned 16-bit integer type to satnum
+and a 16-bit floating-point type to xco2l. The generated VTK files can be
+opened in ParaView for three-dimensional inspection.
+
+
Note
+
OPM Flow is required to run the SPE11 simulations and to prepare the Norne
+model. ParaView is required only to inspect the generated VTK files.
Pressure increase at cells near the top-left corner, middle, and lower-right
+corner of the model.#
+
+
Three indices in plopm-s select one cell over time. The three input
+entries correspond to the three cell selections. The expression
+pressure-0pressure subtracts the initial pressure from each time step.
+
The legend labels are separated by two spaces. plopm-yf displays
+pressure values without decimal places, and plopm-xnt sets eleven
+x-axis ticks.
Plot porosity and x-direction permeability from the Norne model. Use 20 bins
+for each histogram, fit a normal distribution to porosity, and fit a lognormal
+distribution to permeability:
Use plopm-hist to set the number of bins and an optional fitted
+distribution:
+
+
20
Creates a histogram with 20 bins and no fitted distribution.
+
+
20,norm
Creates a histogram with 20 bins and fits a normal distribution.
+
+
20,lognorm
Creates a histogram with 20 bins and fits a lognormal distribution.
+
+
+
Separate specifications for multiple plots with spaces. In this example,
+20,norm20,lognorm applies the normal fit to poro and the lognormal fit
+to permx.
Use plopm-agg to select how values from several cells are combined
+at each projected map location. The methods are applied in the same order as
+the variables:
+
+
first
Selects the first value encountered along the projection direction. Here it
+displays the top index_k value.
+
+
arithmetic
Calculates the arithmetic mean. Here it averages permx across the
+selected layers.
+
+
max
Selects the maximum value. Here it displays the largest poro value
+across the selected layers.
+
+
+
The command therefore applies:
+
index_k -> first
+permx -> arithmetic
+poro -> max
+
+
+
If plopm-agg is omitted, plopm selects an aggregation method
+based on the variable type. Providing it explicitly is useful when comparing
+projection methods or when the scientific interpretation requires a specific
+calculation.
Use the saturation-function variable name by itself to read the first SATNUM
+table. Append a table number to select another SATNUM region, or append h
+to select hysteresis curves.
+
Examples include:
+
+
krg
Gas relative permeability from the first SATNUM table.
+
+
krg2
Gas relative permeability from SATNUM table 2.
+
+
krgh
Gas relative-permeability hysteresis curve.
+
+
krwh
Water relative-permeability hysteresis curve.
+
+
pcwg
Gas-water capillary pressure from the first SATNUM table.
plopm-ylog enables logarithmic scaling for capillary pressure.
+
+
+
Note
+
The requested SATNUM table or hysteresis data must be present in the OPM
+input deck. If no suffix is supplied, plopm reads the first available
+saturation-function table.
Use the same transformation values when comparing properties, faults, wells,
+or other spatial outputs from the same model. See Wells and faults for Norne
+fault and well examples using this transformation.
The command uses plopm-r to export the initial state and restart
+step 5. plopm writes the selected variables for each requested step so the
+results can be inspected or animated in ParaView.
Plot faults and wells declared in the Norne input deck. Apply the same rotation,
+translation, and cropping values used for the transformed Norne grid so the
+outputs remain spatially consistent.
+
+
Note
+
Faults and wells must be declared directly in the input deck.
Project faults across layers 1 through 22. Use max so a map cell is shown
+only when the projected fault condition is present across the selected cells:
All declared Norne wells and the subset intersecting the first layer.#
+
+
For the first command, plopm-gr selects the global well view and
+plopm-fn writes norne_wells_global. Without the global-range
+selection, the second command restricts the output to wells associated with the
+selected layer and writes norne_wells.