expreccs.visualization.plotting module#

Create time-series and spatial comparison figures for expreccs.

This module coordinates visualization of reference, regional, and site-model results produced by OPM Flow. It configures Matplotlib, loads simulation data, and writes figures for field and site summary vectors, well controls, sensor responses, plume distance from the site boundary, and reference-to-site errors.

The plotting workflow supports a single expreccs output folder and comparisons across several output folders. Summary quantities are read from SMSPEC data, while spatial quantities are derived from restart and initialization arrays by the visualization reading module. Two-dimensional geological, final-time, and difference maps are delegated to the maps2d module.

Plotting state, loaded simulation data, labels, styles, and derived series are stored in the shared configuration dictionary. The main entry point initializes these values before dispatching the individual plotting routines.

plot_results(dic)[source]#

Generate all figures requested by the expreccs plotting workflow.

Configure Matplotlib, identify output folders, initialize plotting metadata, read the selected OPM Flow cases, and dispatch summary, sensor, plume-distance, maximum-difference, geological, and final-time plots. In comparison mode, figures combine site results from multiple expreccs output folders with one reference result.

Parameters:

dicdict: Shared plotting configuration. Expected entries include folders, compare, plot, and iterations. The routine adds output paths, labels, styles, loaded case data, figure counts, and plotting arrays.

plotting_settings(dic)[source]#

Initialize plotting styles, quantities, labels, and physical units.

Populate the shared configuration with line colors, markers, line styles, reservoir labels, colormaps, restart quantities, output names, and axis units used consistently by the time-series and two-dimensional plotting routines.

Parameters:

dicdict: Shared plotting configuration. iterations controls the labels generated for iteratively back-coupled regional models.

wells_site(dic, nquan, nfol, ndeck, nwell)[source]#

Add one well-control series to the current summary axis.

Read bottom-hole pressure, gas-injection rate, or water-injection rate from the selected model summary. Injection rates are converted from surface-volume rates to megatonnes per year before the series is styled and added to the axis.

Parameters:

dicdict: Shared plotting data containing folders, decks, summary vectors, dates, styles, labels, and the current axis.
nquanint: Summary-quantity index: 0 for WBHP, 1 for WGIR, or 2 for WWIR.
nfolint: Index of the current expreccs output folder.
ndeckint: Index of the reservoir case within the folder's selected decks.
nwellstr: OPM summary well name used to construct the requested summary key.

summary_site(dic, nfol, ndeck, opmn)[source]#

Add one model summary vector to the current axis.

Read the requested OPM summary key, convert gas in-place values to kilotonnes, and convert block face-flow rates to pore-area-normalized fluxes. In comparison mode, the reference series is plotted only from the first folder.

Parameters:

dicdict: Shared plotting data containing model summaries, dates, sensor geometry, physical properties, styles, labels, and the current axis.
nfolint: Index of the current expreccs output folder.
ndeckint: Index of the selected reservoir case within that folder.
opmnstr: Complete OPM summary key, including region, block, or well qualifiers.

handle_site_summary(dic, i, quantity)[source]#

Add site-scale and reference series for one summary quantity.

Iterate over selected non-regional models and dispatch region, block, or well-summary plotting according to the requested quantity. Site well plots are restricted to well names identified as site wells.

Parameters:

dicdict: Shared plotting data containing folders, selected decks, labels, loaded summaries, and the current axis.
iint: Position of the requested quantity in the summary-quantity sequence.
quantitystr: Summary quantity identifier, such as BHP, PR, GIP, or BPR.

summary_plot(dic, i, quantity)[source]#

Write site-scale and regional summary figures for one quantity.

Create separate figures for the site/reference and regional/reference views, add all applicable model series, sort legend entries, format the time axis, and write both PNG files to the configured output directory.

Parameters:

dicdict: Shared plotting data containing folders, model summaries, output paths, labels, styles, and the current figure and axis objects.
iint: Index selecting the y-axis unit and well-summary quantity.
quantitystr: OPM summary quantity identifier used in labels, keys, and filenames.

over_time_distance(dic)[source]#

Plot minimum plume distance from the site boundary over time.

For the reference model and every site model, identify cells whose gas saturation exceeds the configured threshold, calculate their minimum horizontal distance to the inner site boundary, and write a combined time-series figure. The reference calculation is restricted to the site region through FIPNUM.

Parameters:

dicdict: Shared plotting data containing model grids, plume indicators, dates, site geometry, comparison settings, styles, and the saturation threshold.

positions(dic, fol, res, nrst)[source]#

Calculate centers of cells selected by a plume indicator.

Obtain active-cell corner coordinates from the OPM grid and calculate the x, y, and z center of every cell marked by the selected restart-step indicator. For the reference model, only cells belonging to the site FIPNUM region are used.

Parameters:

dicdict: Shared plotting data containing model grids, indicator arrays, and reference FIPNUM values.
folstr: Absolute or relative path identifying the current expreccs output folder.
resstr: Reservoir case name, such as reference or a site-model directory name.
nrstint: Restart-step index whose plume indicator is evaluated.

Returns:

np.ndarray: Array with shape (n, 3) containing selected cell-center coordinates. An empty (0, 3) array is returned when no cells satisfy the indicator.

handle_labels_distance(dic, nfol, res, fol, j)[source]#

Add one labeled plume-distance series to the current axis.

Select labels, colors, and line styles for a reference or site-model distance series. Comparison mode distinguishes output folders and plots the common reference only once.

Parameters:

dicdict: Shared plotting data containing dates, distance values, labels, styles, comparison state, and the active distance axis.
nfolint: Index of the current expreccs output folder.
resstr: Reference or site reservoir case name.
folstr: Path identifying the current expreccs output folder.
jint: Position of the reservoir case in the reference-plus-sites sequence.

over_time_max_difference(dic, nqua, quantity)[source]#

Plot maximum absolute reference-to-site error over time.

Restrict reference arrays to the site FIPNUM region, remove terminal boundary faces for positive-direction flux quantities, and calculate the maximum absolute difference for every site model and restart step. The resulting series are written together with the maximum reference value.

Parameters:

dicdict: Shared plotting data containing reference and site arrays, FIPNUM values, site dimensions, dates, labels, units, styles, and output paths.
nquaint: Index of the restart quantity and its corresponding axis, unit, and filename.
quantitystr: Restart-derived quantity, such as saturation, pressure, phase flux, or CO2 mass.

over_time_sensor(dic, nqua, quantity)[source]#

Plot one restart-derived quantity at the sensor over time.

Extract the value at each model's sensor cell for every restart step and add the reference and site series to a dedicated figure. Comparison mode plots the reference once and identifies each site series by its output folder.

Parameters:

dicdict: Shared plotting data containing sensor indices, restart arrays, dates, labels, units, styles, comparison state, and output paths.
nquaint: Index of the restart quantity and its corresponding figure, unit, and filename.
quantitystr: Restart-derived quantity evaluated at the sensor cell.

handle_labels_difference(dic, res, j, nqua, nfol)[source]#

Add one labeled maximum-difference series to its axis.

Construct a legend label containing the model name and maximum model value, then select colors and line styles according to comparison mode, output folder, and site-model position.

Parameters:

dicdict: Shared plotting data containing maximum-difference values, dates, labels, styles, quantities, comparison state, and active axes.
resstr: Site reservoir case name.
jint: Index of the site model within the current output folder.
nquaint: Index of the plotted restart quantity and destination axis.
nfolint: Index of the current expreccs output folder.