hyopml

hyopml is a lightweight Python package that enables the integration of data-driven hybrid Newton methods into OPM Flow simulations.
It provides a NumPy-based neural-network wrapper and utilities to convert models trained in other ML libraries (TensorFlow, PyTorch, JAX) into a compact format compatible with OPM Flow.

The goal of hyopml is to provide fast, deterministic, dependency-free inference inside OPM, improving nonlinear solver robustness and accelerating convergence for challenging simulation cases.

---

Features

• Lightweight MLP inference engine (pure NumPy, no ML framework required)
• Converters from:
  • TensorFlow / Keras
  • PyTorch
  • JAX
• Export tools for OPM Flow (kerasify-like format)
• Improved Newton initial guesses, reducing convergence difficulties
• Ready-to-use in OPM Flow 2025.10+

---

1. Requirements

• Python 3.8+
• OPM Flow ≥ 2025.10
  Installation details: https://opm-project.org/?p=2026

Note Depending on your OPM Flow Version, the flag to call Hybrid Newton may differ:

• 2025.10 (Tag: release/2025.10/final): --use-hy-ne and --hy-ne-config-file
• 2025.10+: --use-hybrid-newton and --hybrid-newton-config-file

---

Installing the Package

You can install the library either in normal mode or in development mode. It is recommended to use a Python virtual environment to keep dependencies isolated.

Clone the repository and install the package:

# Clone and install normally
git clone https://github.com/cssr-tools/hyopml.git
cd hyopml
# create a virtual environement
python3 -m venv venv-hyopml
source venv-hyopml/bin/activate

pip install .

# OR, for development (editable) mode
git clone https://github.com/cssr-tools/hyopml.git
cd hyopml

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest -vvv tests

Tutorials

Two example notebooks are included to help you get started quickly:

1. SPE1.ipynb Objective: Demonstrate how to use a NumPy-based neural network as a Exact Global Hybrid Newton preconditioner in OPM Flow to accelerate nonlinear solver convergence.

The notebook covers:

• Running a reference simulation and collecting data.
• Creating a neural network predicting exact solutions.
• Configuring OPM Flow to apply the neural network.
• Comparing solver performance and discussing limitations.

Main functions used

• hyopml.data: collect_input_features, compute_output_vars, extract_unrst_variables for data management.
• hyopml.neural_networks: Dense, Sequential for neural network creation.
• hyopml.write_config: write_config for creation of json file readable by OPM Flow that specify how to use the neural network.

2. convert_model.ipynb Objective: Once you know how to use the Hybrid Newton preconditioner within OPM Flow, you may want to train your model on your own data using your preferred machine learning framework: JAX, PyTorch, or TensorFlow/Keras. This notebook demonstrates how to convert a trained neural network into a format readable by OPM Flow.

Main functions used

• pytorch_to_numpy_model, keras_to_numpy_model, jax_to_numpy_model: Convert your trained model to numpy Multi-Layer Perceptron.
• opm.ml.ml_tools.kerasify.export_model: export your numpy model to OPM Flow compatible format.

---

References

If you use this library in your research or projects, please consider citing one of the following papers:

• Antoine Lechevallier, Sylvain Desroziers, Thibault Faney, Eric Flauraud, Frédéric Nataf,
  Hybrid Newton method for the acceleration of well event handling in the simulation of CO₂ storage using supervised learning,
  Computers & Geosciences, Volume 197, 2025, 105872.
  https://doi.org/10.1016/j.cageo.2025.105872

• Antoine Lechevallier, Tor Harald Sandve, David Landa-Marbán, Birane Kane, Sarah Eileen Gasda,
  Incremental Machine Learning for Near-Well Prediction: A Non-Linear Preconditioning Approach to Faster History Matching,
  Paper presented at the SPE Reservoir Simulation Conference, Galveston, Texas, USA, March 2025.
  https://doi.org/10.2118/223843-MS

• Antoine Lechevallier, Tor Harald Sandve, David Landa-Marbán, Birane Kane, Sarah Gasda,
  Fast Nonlinear Preconditioning for History Matching via Random Feature Learning, 2025.
  HAL Preprint