pofff.visualization.everert module#

Postprocess ERT ensembles and Everest optimization studies.

The module reads realizations and optimization batches, computes diagnostics, plots simulation and parameter distributions, reports failures and monotonicity rejections, and reconstructs the best simulation for benchmark postprocessing.

class pofff.visualization.everert.Config(path: Path, times: str, jobs: list[str], external: Path, run_command: str, maps: Path, min_saturation: float, min_concentration: float)[source]#

Bases: object

Store options and paths for ERT and Everest postprocessing.

The object is populated from command-line arguments and shared by ensemble diagnostics, optimization processing, best-simulation extraction, and benchmark-data generation.

Attributes:

path: Root directory containing the ERT or Everest results and generated figures.
times: Comma-separated benchmark evaluation times in hours.
jobs: Generated job scripts to execute when reconstructing the best simulation.
external: Root directory containing the external FluidFlower benchmark data.
run_command: Experimental realization identifier, such as run2.
maps: Path to the NumPy cell map used to generate benchmark spatial data.
min_saturation: Minimum gas-saturation threshold used to segment simulated CO2.
min_concentration: Minimum dissolved-CO2 concentration threshold used to segment simulated CO2.

external: Path#

jobs: list[str]#

maps: Path#

min_concentration: float#

min_saturation: float#

path: Path#

run_command: str#

times: str#

class pofff.visualization.everert.EnsembleState(observations: ndarray, n_e: int, n_i: int, no_obs: int, no_para: int, simulations: list[list[list]] = <factory>, sim_ens: list[list[float]] = <factory>, miss_ens: list[list[float]] = <factory>, par_dis: list[list[float]] = <factory>, idrealisation: list[list[int]] = <factory>, num_ens: list[int] = <factory>, cumulative: list[list[list[float]]] = <factory>, para_file: Path | None = None, para_names: list[str] = <factory>)[source]#

Bases: object

Store ERT ensemble results and derived diagnostics.

The object is initialized from the ERT output structure. Successful realizations then populate its simulation values, misfits, parameter distributions, realization identifiers, and per-observation diagnostics for each iteration.

Attributes:

observations: Observation values and uncertainties loaded from deck/obs.txt. A one-dimensional array represents one observation; otherwise, rows contain the observed value and its uncertainty.
n_e: Number of ensemble realizations found in the simulation output.
n_i: Number of ERT iterations represented in the simulation output.
no_obs: Number of observations used to calculate the ensemble misfit.
no_para: Number of history-matching parameters found in parameters.txt.
simulations: Simulated observable values grouped by iteration and realization.
sim_ens: Sum of the simulated observable values for each successful realization, grouped by iteration.
miss_ens: Normalized least-squares misfit for each successful realization, grouped by iteration.
par_dis: History-matching parameter values grouped by iteration. Values for all parameters and realizations are stored in file order.
idrealisation: Original realization identifiers for successful simulations, grouped by iteration.
num_ens: Number of successful realizations in each iteration.
cumulative: Simulated values grouped by iteration, observation, and successful realization for cumulative-misfit plots.
para_file: Path to the most recently discovered parameters.txt file, or None when parameter values are unavailable.
para_names: History-matching parameter names read from para_file.

cumulative: list[list[list[float]]]#

idrealisation: list[list[int]]#

miss_ens: list[list[float]]#

n_e: int#

n_i: int#

no_obs: int#

no_para: int#

num_ens: list[int]#

observations: ndarray#

par_dis: list[list[float]]#

para_file: Path | None#

para_names: list[str]#

sim_ens: list[list[float]]#

simulations: list[list[list]]#

class pofff.visualization.everert.OptimizationState(optimization: list[float] = <factory>, optimal_value: float = -inf, ind_batch: int = 0, ind_sim: int = 0, tot_eval: int = 0, s: list[list[int]] = <factory>, x: list[int] = <factory>)[source]#

Bases: object

Store Everest optimization progress and the best evaluation.

The object is populated while processing optimization batches. It tracks the best objective value reached after each batch, counts successful and unsuccessful evaluations, and identifies the evaluation from which the optimal simulation should be reconstructed.

Attributes:

optimization: Best objective value reached after each optimization batch.
optimal_value: Best objective value found across all processed batches.
ind_batch: Zero-based index of the batch containing the best evaluation.
ind_sim: Zero-based evaluation index of the best solution within ind_batch.
tot_eval: Total number of processed optimization evaluations.
s: Evaluation counts grouped by status and batch. Rows contain successful, failed, and nonmonotonic evaluation counts, respectively.
x: Temporary counters for successful, failed, and nonmonotonic evaluations in the batch currently being processed.

ind_batch: int#

ind_sim: int#

optimal_value: float#

optimization: list[float]#

s: list[list[int]]#

tot_eval: int#

x: list[int]#

pofff.visualization.everert._configure_matplotlib()[source]#: Apply consistent matplotlib styling.

pofff.visualization.everert._copy_tree_contents(src: Path, dst: Path)[source]#

Copy contents of src into dst (cp -r src/. dst/).

Parameters:

srcPath: Source file or directory.
dstPath: Destination file or directory.

pofff.visualization.everert._ensure_directory(path: Path)[source]#

Create directory if missing.

Parameters:

pathPath: Input, output, or project path.

pofff.visualization.everert._extract_best_simulation(cfg: Config, state: EnsembleState)[source]#

Extract best-fitting ensemble realization.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.
stateEnsembleState: Mutable ensemble state populated during postprocessing.

pofff.visualization.everert._extract_optimal_solution(cfg: Config, opt: OptimizationState)[source]#

Extract and postprocess optimal optimization result.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.
optOptimizationState: Processed Everest optimization state.

pofff.visualization.everert._initialize_ensemble(cfg: Config) → EnsembleState[source]#

Initialize ensemble from simulation folders.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.

Returns:

EnsembleState: Initialized ensemble state sized from the result directories.

pofff.visualization.everert._parse_arguments(argv) → Config[source]#

Parse command-line arguments.

Parameters:

argvobject: Arguments to parse instead of the process command line.

Returns:

Config: Parsed command-line arguments or the corresponding runtime configuration.

pofff.visualization.everert._plot_cumulative_misfit(cfg: Config, state: EnsembleState, tab20)[source]#

Plot cumulative misfit contributions per observation.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.
stateEnsembleState: Mutable ensemble state populated during postprocessing.
tab20object: Matplotlib categorical colormap used for consistent series colors.

pofff.visualization.everert._plot_history_matching_mismatch(cfg: Config, state: EnsembleState)[source]#

Plot ensemble-mean misfit per iteration.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.
stateEnsembleState: Mutable ensemble state populated during postprocessing.

pofff.visualization.everert._plot_misfit(cfg: Config, state: EnsembleState)[source]#

Plot ensemble misfit per iteration.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.
stateEnsembleState: Mutable ensemble state populated during postprocessing.

pofff.visualization.everert._plot_observable_distribution(cfg: Config, state: EnsembleState)[source]#

Plot observable sum distributions.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.
stateEnsembleState: Mutable ensemble state populated during postprocessing.

pofff.visualization.everert._plot_optimization(cfg: Config, opt: OptimizationState)[source]#

Plot optimization progress.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.
optOptimizationState: Processed Everest optimization state.

pofff.visualization.everert._plot_optimization_details(cfg: Config, opt: OptimizationState)[source]#

Plot optimization success statistics.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.
optOptimizationState: Processed Everest optimization state.

pofff.visualization.everert._plot_parameter_distributions(cfg: Config, state: EnsembleState)[source]#

Boxplots of parameter distributions.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.
stateEnsembleState: Mutable ensemble state populated during postprocessing.

pofff.visualization.everert._plot_simulation_ensemble(cfg: Config, state: EnsembleState, tab20)[source]#

Plot initial and final ensemble simulations.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.
stateEnsembleState: Mutable ensemble state populated during postprocessing.
tab20object: Matplotlib categorical colormap used for consistent series colors.

pofff.visualization.everert._process_optimization(cfg: Config) → OptimizationState[source]#

Process Everest optimization results.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.

Returns:

OptimizationState: Optimization history and location of the best evaluation.

pofff.visualization.everert._read_realisation(cfg: Config, state: EnsembleState, i: int, j: int)[source]#

Read one realization and update ensemble statistics.

Parameters:

cfgConfig: Shared pofff configuration and derived runtime state.
stateEnsembleState: Mutable ensemble state populated during postprocessing.
iint: Iteration or row index.
jint: Realization or column index.

pofff.visualization.everert._run_command(cmd: list[str]) → None[source]#

Execute external command and abort on failure.

Parameters:

cmdlist[str]: Command and arguments to execute without a shell.

Raises:

subprocess.CalledProcessError: If the command exits with a nonzero status.

pofff.visualization.everert._save_figure(fig, path: Path, dpi=300)[source]#

Save figure and release memory.

Parameters:

figobject: Matplotlib figure to save and close.
pathPath: Input, output, or project path.
dpiobject, optional: Output resolution in dots per inch.

pofff.visualization.everert.run_everert(argv=None)[source]#

Generate diagnostics for an ERT ensemble or Everest optimization.

Parameters:

argvobject, optional: Arguments to parse instead of the process command line.