Loading...
Searching...
No Matches
Opm::BlackOilHybridNewton< TypeTag > Class Template Reference

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:

1. Loads the relevant configuration(s),
2. Constructs an input tensor [n_cells x n_input_features],
3. Runs the ML model to produce an output tensor [n_cells x n_output_features],
4. 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 | ) |

inline protected

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 )

inline protected

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 )

inline protected

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 | ) |

inline protected

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

inline protected

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::UseHyNe). 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 )

inline protected

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

For each target cell, this function:

1. Reads predicted output features from the ML tensor,
2. Applies inverse scaling and transformations,
3. If marked as delta values (spec.is_delta == true), adds the predicted delta to the current simulator state,
4. 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