fmu.tools.nestedhybridgrid package

Submodules

fmu.tools.nestedhybridgrid.nestedhybrid module

Nested hybrid grid creation.

Create a merged grid where one region is refined (subdivided) and stitched back into the original grid via Non-Neighbour Connections (NNCs).

Public API

create_nested_hybrid_gridfunction

Build a nested hybrid grid from a coarse grid, a region property, and a refinement specification.

nnc_to_gridpropertyfunction

Convert NNC transmissibility DataFrames to GridProperty instances.

nnc_to_flowsimulator_inputfunction

Write NNC transmissibilities to a flow-simulator input file.

fmu.tools.nestedhybridgrid.nestedhybrid.create_nested_hybrid_grid(grid, region, target_region_id, refinement)

Create a nested hybrid grid by refining one region and merging it back.

The cells belonging to target_region_id are replaced by a refined (subdivided) version of the same region. A NEST_ID discrete property is attached to the merged grid, encoding the nested hybrid structure:

• NEST_ID == 1: coarse (mother) grid cells.

• NEST_ID == 2: refined grid cells.

In addition, a NNC mapping table is returned that lists every mother ↔ refined cell pair that should be connected by a Non-Neighbour Connection (NNC). The table is derived from the topological knowledge available at merge time (which original cell was refined and how its sub-cells map into the merged grid).

The table columns are:

• I1, J1, K1: mother cell indices (1-based) in the merged grid.

• I2, J2, K2: refined cell indices (1-based) in the merged grid.

• DIRECTION: face direction from the mother cell’s perspective (I+, I-, J+, J-, K+, K-).

This table can be passed to xtgeo.Grid.get_transmissibilities() to compute NNC transmissibilities for the specified cell pairs.

Parameters:

• grid (Grid) – The original coarse grid.

• region (GridProperty) – A xtgeo.GridProperty whose values identify the regions (e.g. an integer region parameter).

• target_region_id (int) – The region value to refine.

• refinement (tuple[int, int, int]) – (ncol, nrow, nlay) refinement factors.

Return type:

tuple[Grid, DataFrame]

Returns:

A tuple (merged_grid, nnc_table) where merged_grid is a new xtgeo.Grid with the refined region stitched back into the coarse grid and nnc_table is a pandas.DataFrame mapping mother cells to their connected refined cells.

fmu.tools.nestedhybridgrid.nestedhybrid.nnc_to_gridproperty(grid, nnc_df)

Convert NNC transmissibility data to three GridProperty instances.

Takes the NNC DataFrame produced by xtgeo.Grid.get_transmissibilities() and maps transmissibility values onto grid cells, producing one property per direction (I, J, K).

For rows where DIRECTION contains "+", the transmissibility value is placed in cell (I1, J1, K1). For rows where DIRECTION contains "-", the value is placed in cell (I2, J2, K2). Index columns (I1, J1, K1, I2, J2, K2) are expected to be 1-based.

If multiple rows map to the same cell and direction, the transmissibility values are summed (parallel flow paths are additive).

Parameters:

• grid (Grid) – The xtgeo Grid that defines the geometry.

• nnc_df (DataFrame) – A DataFrame with at least columns I1, J1, K1, I2, J2, K2, T, DIRECTION.

Return type:

tuple[GridProperty, GridProperty, GridProperty]

Returns:

A tuple (tranx_nnc, trany_nnc, tranz_nnc) of xtgeo.GridProperty instances named "TRANX_NNC", "TRANY_NNC", and "TRANZ_NNC" respectively. Cells without an NNC value are set to -1.0.

fmu.tools.nestedhybridgrid.nestedhybrid.nnc_to_flowsimulator_input(nnc_df, filepath)

Write NNC transmissibilities to a flow-simulator input file.

Produces a file with the NNC keyword suitable for reservoir simulators that use Eclipse-style input decks, such as Eclipse and OPM Flow. The file can be included in the deck via INCLUDE. Each row of nnc_df becomes one NNC record with the six cell indices and the transmissibility value.

Parameters:

• nnc_df (DataFrame) – A DataFrame with at least columns I1, J1, K1, I2, J2, K2, T. Optional columns TYPE and DIRECTION are written as end-of-line comments.

• filepath (str | PathLike[str]) – Path to the output file.

Return type:

None

Module contents

fmu.tools.nestedhybridgrid.create_nested_hybrid_grid(grid, region, target_region_id, refinement)

Create a nested hybrid grid by refining one region and merging it back.

The cells belonging to target_region_id are replaced by a refined (subdivided) version of the same region. A NEST_ID discrete property is attached to the merged grid, encoding the nested hybrid structure:

• NEST_ID == 1: coarse (mother) grid cells.

• NEST_ID == 2: refined grid cells.

In addition, a NNC mapping table is returned that lists every mother ↔ refined cell pair that should be connected by a Non-Neighbour Connection (NNC). The table is derived from the topological knowledge available at merge time (which original cell was refined and how its sub-cells map into the merged grid).

The table columns are:

• I1, J1, K1: mother cell indices (1-based) in the merged grid.

• I2, J2, K2: refined cell indices (1-based) in the merged grid.

• DIRECTION: face direction from the mother cell’s perspective (I+, I-, J+, J-, K+, K-).

This table can be passed to xtgeo.Grid.get_transmissibilities() to compute NNC transmissibilities for the specified cell pairs.

Parameters:

• grid (Grid) – The original coarse grid.

• region (GridProperty) – A xtgeo.GridProperty whose values identify the regions (e.g. an integer region parameter).

• target_region_id (int) – The region value to refine.

• refinement (tuple[int, int, int]) – (ncol, nrow, nlay) refinement factors.

Return type:

tuple[Grid, DataFrame]

Returns:

A tuple (merged_grid, nnc_table) where merged_grid is a new xtgeo.Grid with the refined region stitched back into the coarse grid and nnc_table is a pandas.DataFrame mapping mother cells to their connected refined cells.

fmu.tools.nestedhybridgrid.nnc_to_flowsimulator_input(nnc_df, filepath)

Write NNC transmissibilities to a flow-simulator input file.

Produces a file with the NNC keyword suitable for reservoir simulators that use Eclipse-style input decks, such as Eclipse and OPM Flow. The file can be included in the deck via INCLUDE. Each row of nnc_df becomes one NNC record with the six cell indices and the transmissibility value.

Parameters:

• nnc_df (DataFrame) – A DataFrame with at least columns I1, J1, K1, I2, J2, K2, T. Optional columns TYPE and DIRECTION are written as end-of-line comments.

• filepath (str | PathLike[str]) – Path to the output file.

Return type:

None

fmu.tools.nestedhybridgrid.nnc_to_gridproperty(grid, nnc_df)

Convert NNC transmissibility data to three GridProperty instances.

Takes the NNC DataFrame produced by xtgeo.Grid.get_transmissibilities() and maps transmissibility values onto grid cells, producing one property per direction (I, J, K).

For rows where DIRECTION contains "+", the transmissibility value is placed in cell (I1, J1, K1). For rows where DIRECTION contains "-", the value is placed in cell (I2, J2, K2). Index columns (I1, J1, K1, I2, J2, K2) are expected to be 1-based.

If multiple rows map to the same cell and direction, the transmissibility values are summed (parallel flow paths are additive).

Parameters:

• grid (Grid) – The xtgeo Grid that defines the geometry.

• nnc_df (DataFrame) – A DataFrame with at least columns I1, J1, K1, I2, J2, K2, T, DIRECTION.

Return type:

tuple[GridProperty, GridProperty, GridProperty]

Returns:

A tuple (tranx_nnc, trany_nnc, tranz_nnc) of xtgeo.GridProperty instances named "TRANX_NNC", "TRANY_NNC", and "TRANZ_NNC" respectively. Cells without an NNC value are set to -1.0.