Hybrid Newton solver extension for the black-oil model. More...

#include <HybridNewton.hpp>

Classes
struct	FeatureFlags

Public Member Functions
	BlackOilHybridNewton (Simulator &simulator)
void	tryApplyHybridNewton ()
	Attempt to apply the Hybrid Newton correction at the current timestep.

Protected Types
enum	{ numPhases = FluidSystem::numPhases }
enum	{ gasPhaseIdx = FluidSystem::gasPhaseIdx }
enum	{ oilPhaseIdx = FluidSystem::oilPhaseIdx }
enum	{ waterPhaseIdx = FluidSystem::waterPhaseIdx }
using	Simulator = GetPropType<TypeTag, Properties::Simulator>
using	Evaluation = GetPropType<TypeTag, Properties::Evaluation>
using	FluidSystem = GetPropType<TypeTag, Properties::FluidSystem>
using	MaterialLaw = GetPropType<TypeTag, Properties::MaterialLaw>
using	Indices = GetPropType<TypeTag, Properties::Indices>
using	Scalar = GetPropType<TypeTag, Properties::Scalar>

Protected Member Functions
void	validateFluidSystem ()
bool	shouldApplyHybridNewton (Scalar current_time, const HybridNewtonConfig &config) const
	Check whether the Hybrid Newton method should be applied at the given time.
ML::Tensor< Evaluation >	constructInputTensor (const HybridNewtonConfig &config)
	Construct the input feature tensor for the Hybrid Newton model.
Scalar	getScalarFeatureValue (const FeatureSpec &spec)
	Retrieve and transform a scalar feature (global across the domain).
Scalar	getPerCellFeatureValue (const FeatureSpec &spec, int cell_index)
	Retrieve and transform a per-cell feature value.
ML::Tensor< Evaluation >	constructOutputTensor (const ML::Tensor< Evaluation > &input, const HybridNewtonConfig &config)
	Run the Hybrid Newton model to produce output predictions.
void	updateInitialGuess (ML::Tensor< Evaluation > &output, const HybridNewtonConfig &config)
	Update the nonlinear solver's initial guess using ML predictions.
FeatureFlags	flagFeatures (const std::vector< std::pair< std::string, FeatureSpec > > &features)

Protected Attributes
Simulator &	simulator_
std::vector< HybridNewtonConfig >	configs_
bool	configsLoaded_

Static Protected Attributes
static constexpr bool	compositionSwitchEnabled = Indices::compositionSwitchIdx >= 0

Detailed Description

template<typename TypeTag>
class Opm::BlackOilHybridNewton< TypeTag >

Hybrid Newton solver extension for the black-oil model.

This class integrates machine learning–based corrections into the standard Newton solver of the black-oil simulator. It uses one or more trained Hybrid Newton models to adjust the initial guess of the nonlinear solver at specific timesteps.

Each model is described by a HybridNewtonConfig, which specifies:

the path to the model file,
the cells to which the model applies,
the time points when it should be applied,
the input and output features with their transformations and scalings.

At runtime, the class:

Loads the relevant configuration(s),
Constructs an input tensor [n_cells x n_input_features],
Runs the ML model to produce an output tensor [n_cells x n_output_features],
Updates the nonlinear solver’s initial guess accordingly.

Member Function Documentation

◆ constructInputTensor()

template<typename TypeTag>

ML::Tensor< Evaluation > Opm::BlackOilHybridNewton< TypeTag >::constructInputTensor ( const HybridNewtonConfig & config )

inlineprotected

Construct the input feature tensor for the Hybrid Newton model.

The tensor is constructed in the exact order specified by config.input_features:

Scalar features (e.g., TIMESTEP) contribute one entry each.
Per-cell features (e.g., PRESSURE, SGAS) contribute a block of n_cells entries, one per cell index in config.cell_indices.

Example: Suppose config.input_features = [SGAS, TIMESTEP, PRESSURE] and config.n_cells = 3. The resulting tensor layout is:

[ SGAS(cell0), SGAS(cell1), SGAS(cell2), TIMESTEP, PRESSURE(cell0), PRESSURE(cell1), PRESSURE(cell2) ]

Thus, the tensor length equals:

(# of scalar features) + (# of per-cell features × n_cells).

Parameters

config HybridNewtonConfig containing feature definitions and cell indices.

Returns: A 1D tensor of Evaluation values with the computed layout.

◆ constructOutputTensor()

template<typename TypeTag>

ML::Tensor< Evaluation > Opm::BlackOilHybridNewton< TypeTag >::constructOutputTensor	(	const ML::Tensor< Evaluation > &	input,
		const HybridNewtonConfig &	config )

inlineprotected

Run the Hybrid Newton model to produce output predictions.

Uses the input tensor (prepared by constructInputTensor) together with the model specified in config to compute the corresponding output tensor. Scaling and transformations defined in the configuration are applied automatically.

Parameters

input	The input tensor of shape [(# of scalar features) + (# of per-cell features × n_cells)].
config	The HybridNewtonConfig specifying model path and output feature definitions.

Returns: A tensor of shape [n_cells x n_output_features], where rows correspond to cells and columns correspond to output features.

Exceptions

std::runtime_error if model inference fails or if the output tensor does not match the expected feature layout.

◆ getPerCellFeatureValue()

template<typename TypeTag>

Scalar Opm::BlackOilHybridNewton< TypeTag >::getPerCellFeatureValue	(	const FeatureSpec &	spec,
		int	cell_index )

inlineprotected

Retrieve and transform a per-cell feature value.

Supported per-cell features include:

PRESSURE, SWAT, SOIL, SGAS, RS, RV, PERMX.

The raw value is taken from the simulator state, converted into the configured unit system, then passed through the feature's transformation and scaling functions.

Parameters

spec	The feature specification, including transform and scaling.
cell_index	The cell index for which to retrieve the value.

Returns: The transformed and scaled feature value.

Exceptions

std::runtime_error if the feature is unknown.

◆ getScalarFeatureValue()

template<typename TypeTag>

Scalar Opm::BlackOilHybridNewton< TypeTag >::getScalarFeatureValue ( const FeatureSpec & spec )

inlineprotected

Retrieve and transform a scalar feature (global across the domain).

Supported scalar feature:

"TIMESTEP": current timestep size.

The raw value is passed through the feature's transformation and scaling functions before being returned.

Parameters

spec	The feature specification, including transform and scaling.

Returns: The transformed and scaled feature value.

Exceptions

std::runtime_error if the feature is unknown.

◆ shouldApplyHybridNewton()

template<typename TypeTag>

bool Opm::BlackOilHybridNewton< TypeTag >::shouldApplyHybridNewton	(	Scalar	current_time,
		const HybridNewtonConfig &	config ) const

inlineprotected

Check whether the Hybrid Newton method should be applied at the given time.

This function evaluates the current simulation time against the application times specified in the HybridNewtonConfig. The behavior depends on how many entries are provided in config.apply_times:

If one entry is provided, the method is applied exactly at that time (within a tolerance of 1e-6).
If two entries are provided, the method is applied during the inclusive interval between the start and end times.
For any other number of entries, the method is not applied.

Parameters

current_time	The current simulation time.
config	The HybridNewtonConfig specifying when the Hybrid Newton method should be applied.

Returns: True if the Hybrid Newton method should be applied at current_time, false otherwise.

◆ tryApplyHybridNewton()

template<typename TypeTag>

void Opm::BlackOilHybridNewton< TypeTag >::tryApplyHybridNewton ( )

inline

Attempt to apply the Hybrid Newton correction at the current timestep.

This function acts as the entry point for Hybrid Newton corrections. It first checks whether the Hybrid Newton mechanism is enabled (via Parameters::UseHybridNewton). If enabled, it validates the fluid system and loads model configurations from the parameter-specified configuration file (if not already loaded).

At each timestep, it iterates over all loaded configurations and applies those that match the current simulation time.

Typical call site: at the beginning of a nonlinear solve for each timestep.

Exceptions

std::runtime_error if configuration validation fails or if an invalid fluid system is encountered.

◆ updateInitialGuess()

template<typename TypeTag>

void Opm::BlackOilHybridNewton< TypeTag >::updateInitialGuess	(	ML::Tensor< Evaluation > &	output,
		const HybridNewtonConfig &	config )

inlineprotected

Update the nonlinear solver's initial guess using ML predictions.

For each target cell, this function:

Reads predicted output features from the ML tensor,
Applies inverse scaling and transformations,
If marked as delta values (spec.is_delta == true), adds the predicted delta to the current simulator state,
Updates fluid state variables accordingly:
- PRESSURE: replaces oil-phase pressure and reconstructs other phase pressures using capillary pressure relations,
- SWAT, SOIL, SGAS: updates saturations with closure rules if fewer than 3 are predicted,
- RS, RV: updates dissolved/volatilized gas-oil ratios if composition-switching is enabled.

Special handling:

Saturations are clamped to [0,1] and normalized to ensure their sum is unity.
Invalid states (e.g., zero saturation sum) raise exceptions.

Parameters

output	The ML output tensor [n_cells x n_output_features].
config	The model configuration specifying output feature mappings.

Exceptions

std::runtime_error if an unknown output feature is encountered or if state consistency cannot be enforced.

The documentation for this class was generated from the following file:

opm/simulators/flow/HybridNewton.hpp

Classes

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ constructInputTensor()

◆ constructOutputTensor()

◆ getPerCellFeatureValue()

◆ getScalarFeatureValue()

◆ shouldApplyHybridNewton()

◆ tryApplyHybridNewton()

◆ updateInitialGuess()