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.

class fmu.tools.nestedhybridgrid.nestedhybrid.CellsByParent(cell_indices, group_start, group_stop)[source]

Bases: object

Group flattened cell indices by parent.

group_start and group_stop are indexed by parent and define slices into cell_indices. Unmapped parents have both set to -1.

cell_indices: ndarray

group_start: ndarray

group_stop: ndarray

classmethod from_parent_indices(parent_indices, selected_mask, parent_cell_count)[source]

Return type:: Self

property mapped_mask: ndarray: Return a boolean mask indicating which parents have mapped cells.

property mapped_parent_indices: ndarray: Return parent indices that have mapped cells.

property counts: ndarray: Return the number of cells mapped to each parent.

get_indices(parent_idx)[source]

Return type:: ndarray

class fmu.tools.nestedhybridgrid.nestedhybrid.BoundingBox(**data)[source]

Bases: BaseModel

imin: int

imax: int

jmin: int

jmax: int

kmin: int

kmax: int

classmethod from_condition(condition)[source]

Get the ijk bounding box from a 3D boolean mask.

Return type:: Self

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fmu.tools.nestedhybridgrid.nestedhybrid.Refinement(**data)[source]

Bases: BaseModel

col: int

row: int

lay: int

classmethod from_tuple(refinement)[source]

Create a refinement model from a 3-tuple.

Return type:: Self

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fmu.tools.nestedhybridgrid.nestedhybrid.NestedHybridGrid(coarse_grid, region, refinement, target_region_id=1)[source]

Bases: object

Class to build a nested hybrid grid with a refined target region.

The target region is refined and merged back into the coarse grid. A NNC mapping table is computed that lists every coarse ↔ refined cell pair that should be connected by a Non-Neighbour Connection (NNC).

classmethod from_rms(project, grid_name, region_name, refinement, properties=None, *, target_region_id=1)[source]

Create a NestedHybridGrid instance from an RMS project.

Parameters:

project (Any) – RMS project instance.
grid_name (str) – Name of the grid in the RMS project.
region_name (str) – Name of the region property in the RMS project.
refinement (tuple[int, int, int]) – Refinement factors as (ncol, nrow, nlay).
properties (list[str] | None) – Optional list of property names to load from the project.
target_region_id (int) – Region value to refine (default: 1).

Return type:

Self

to_rms(project, grid_name)[source]

Write the nested hybrid grid and its properties to an RMS project.

Return type:: None

property grid: Grid: The final nested hybrid grid.

property properties: list[GridProperty]: The final nested hybrid grid properties.

property dimensions: Dimensions: The final nested hybrid grid dimensions.

property nnc_table: DataFrame: Non-Neighbour Connection (NNC) mapping table.

property nested_cells_by_parent: CellsByParent: Lazy mapping from parent-grid indices to active merged-grid cells.

create_upscaling_mappings(i_map, j_map, k_map)[source]

Method to remap geogrid-to-parent IJK references into geogrid-to-nestedgrid IJK references. These properties can in turn be used when upscaling properties from geogrid to the nested hybrid grid.

Inputs ‘i_map’, ‘j_map’ and ‘k_map’ are geogrid properties that reference the IJK of the input grid that the nested grid is based on. The nested grid already contains the same parent grid references through the ‘parent_I’, ‘parent_J’ and ‘parent_K’ properties.

Return type:: tuple[GridProperty, GridProperty, GridProperty]
Returns:: A 3-tuple of xtgeo.GridProperty objects with mapped geogrid-to-nested-grid references, ordered as I, J, K.

write_nnc_table(filename)[source]

Write the NNC mapping table to CSV.

Return type:: None

fmu.tools.nestedhybridgrid.nestedhybrid.create_nested_hybrid_grid(grid, region, target_region_id, refinement)[source]

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 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)[source]

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)[source]

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)[source]

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 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)[source]

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)[source]

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.

class fmu.tools.nestedhybridgrid.NestedHybridGrid(coarse_grid, region, refinement, target_region_id=1)[source]

Bases: object

Class to build a nested hybrid grid with a refined target region.

The target region is refined and merged back into the coarse grid. A NNC mapping table is computed that lists every coarse ↔ refined cell pair that should be connected by a Non-Neighbour Connection (NNC).

classmethod from_rms(project, grid_name, region_name, refinement, properties=None, *, target_region_id=1)[source]

Create a NestedHybridGrid instance from an RMS project.

Parameters:

project (Any) – RMS project instance.
grid_name (str) – Name of the grid in the RMS project.
region_name (str) – Name of the region property in the RMS project.
refinement (tuple[int, int, int]) – Refinement factors as (ncol, nrow, nlay).
properties (list[str] | None) – Optional list of property names to load from the project.
target_region_id (int) – Region value to refine (default: 1).

Return type:

Self

to_rms(project, grid_name)[source]

Write the nested hybrid grid and its properties to an RMS project.

Return type:: None

property grid: Grid: The final nested hybrid grid.

property properties: list[GridProperty]: The final nested hybrid grid properties.

property dimensions: Dimensions: The final nested hybrid grid dimensions.

property nnc_table: DataFrame: Non-Neighbour Connection (NNC) mapping table.

property nested_cells_by_parent: CellsByParent: Lazy mapping from parent-grid indices to active merged-grid cells.

create_upscaling_mappings(i_map, j_map, k_map)[source]

Method to remap geogrid-to-parent IJK references into geogrid-to-nestedgrid IJK references. These properties can in turn be used when upscaling properties from geogrid to the nested hybrid grid.

Inputs ‘i_map’, ‘j_map’ and ‘k_map’ are geogrid properties that reference the IJK of the input grid that the nested grid is based on. The nested grid already contains the same parent grid references through the ‘parent_I’, ‘parent_J’ and ‘parent_K’ properties.

Return type:: tuple[GridProperty, GridProperty, GridProperty]
Returns:: A 3-tuple of xtgeo.GridProperty objects with mapped geogrid-to-nested-grid references, ordered as I, J, K.

write_nnc_table(filename)[source]

Write the NNC mapping table to CSV.

Return type:: None