PET: Python Ensemble Toolbox

PET is a toolbox for ensemble-based Data Assimilation and Optimisation. It is developed and maintained by the eponymous group at NORCE Norwegian Research Centre AS.

Installation

PET requires Python 3.12 through 3.14. The standard installation includes EnIF and EnIF-MDA with their dependencies.

To install PET, first clone the repo (assuming you have added the SSH key)

git clone git@github.com:Python-Ensemble-Toolbox/PET.git PET

Alternatively, click here to download ZIP.

On Linux

Before installing ensure you have python3 pre-requisites. On a Debian system run:

sudo apt-get update
sudo apt-get install python3
sudo apt-get install python3-pip
sudo apt-get install python3-venv

Make sure you have the latest version of pip and setuptools:

python3 -m pip install --upgrade pip setuptools

Optionally (but recommended): Create and activate a virtual environment:

python3 -m venv venv-PET
source venv-PET/bin/activate

If you do not install PET inside a virtual environment, you may have to include the --user option in the following (to install to your local Python site packages, usually located in ~/.local).

Inside the PET folder, run

python3 -m pip install -e .

• The dot is needed to point to the current directory.
• The -e option installs PET such that changes to it take effect immediately (without re-installation).

To also install the tools needed for running tests and linting locally:

python3 -m pip install -e ".[dev]"

On Windows

TL;DR: use conda to create the environment and install PET. Inside the PET folder, run:

conda env create -f environment.yml -n pet
conda activate pet

For more details refer to Installing PET on Windows. This setup may also work on Linux, though it has not been tested yet.

Documentation

The configuration reference lists every key of the dataassim, ensemble, optim and simulator sections; the architecture page explains how a run is put together and where a new scheme, analysis, localization, optimizer or simulator goes.

Command-line interface

Installing PET also installs a pet command for working with config files:

pet validate my_config.toml   # check a config file for missing/invalid keys
pet convert my_case.pipt      # convert a legacy .pipt/.popt file to .toml (or --to yaml)
pet migrate my_config.toml    # update a config file to the current schema
pet version                   # print the installed PET version

Examples

PET needs to be set up with a configuration file. See the example repository for inspiration.

Simulation wrappers

To use the subsurface simulators Eclipse or OPM, you need to install the SimulatorWrap repository. This repository also contains instructions on how to link your own simulator to PET.

Visualization

Some basic plotting functionality is provided here. The functions should be copied and adapted for each specific use cases.

Tutorials

• A PIPT tutorial is found here
• A POPT tutorial is found here

Suggested readings:

If you use PET in a scientific publication, we would appreciate it if you cited one of the first papers where the PET was introduced. Each of them describes some of the PET's functionalities:

Bayesian data assimilation with EnRML and ES-MDA for History-Matching Workflow with AI-Geomodeling

Cite as

Fossum, Kristian, Sergey Alyaev, and Ahmed H. Elsheikh. "Ensemble history-matching workflow using interpretable SPADE-GAN geomodel." First Break 42.2 (2024): 57-63. https://doi.org/10.3997/1365-2397.fb2024014

@article{fossum2024ensemble,
  title={Ensemble history-matching workflow using interpretable SPADE-GAN geomodel},
  author={Fossum, Kristian and Alyaev, Sergey and Elsheikh, Ahmed H},
  journal={First Break},
  volume={42},
  number={2},
  pages={57--63},
  year={2024},
  publisher={European Association of Geoscientists \& Engineers},
  url = {https://doi.org/10.3997/1365-2397.fb2024014}
}

Bayesian inversion technique, localization, and data compression for history matching of the Edvard Grieg field using 4D seismic data

Cite as

Lorentzen, R.J., Bhakta, T., Fossum, K. et al. Ensemble-based history matching of the Edvard Grieg field using 4D seismic data. Comput Geosci 28, 129–156 (2024). https://doi.org/10.1007/s10596-024-10275-0

@article{lorentzen2024ensemble,
  title={Ensemble-based history matching of the Edvard Grieg field using 4D seismic data},
  author={Lorentzen, Rolf J and Bhakta, Tuhin and Fossum, Kristian and Haugen, Jon Andr{\'e} and Lie, Espen Oen and Ndingwan, Abel Onana and Straith, Knut Richard},
  journal={Computational Geosciences},
  volume={28},
  number={1},
  pages={129--156},
  year={2024},
  publisher={Springer},
  url={https://doi.org/10.1007/s10596-024-10275-0}
}

Offshore wind farm layout optimization using ensemble methods

Cite as

Eikrem, K.S., Lorentzen, R.J., Faria, R. et al. Offshore wind farm layout optimization using ensemble methods. Renewable Energy 216, 119061 (2023). https://www.sciencedirect.com/science/article/pii/S0960148123009758

@article{Eikrem2023offshore,
title = {Offshore wind farm layout optimization using ensemble methods},
journal = {Renewable Energy},
volume = {216},
pages = {119061},
year = {2023},
issn = {0960-1481},
doi = {https://doi.org/10.1016/j.renene.2023.119061},
url = {https://www.sciencedirect.com/science/article/pii/S0960148123009758},
author = {Kjersti Solberg Eikrem and Rolf Johan Lorentzen and Ricardo Faria and Andreas St{\o}rksen Stordal and Alexandre Godard},
keywords = {Wind farm layout optimization, Ensemble optimization (EnOpt and EPF-EnOpt), Constrained optimization, Levelized cost of energy (LCOE), Floating offshore wind},
}