pycopm.utils.coarsening module#

Coarsen corner-point grids and aggregate reservoir properties.

The module supports deck-based coarsening and the TOML workflows used to generate reduced Norne and Drogon models.

class CoarseningMaps(x, y, z, cell_groups, coarsened_axes, matrix_mask, vertical_transfer_enabled, reference_to_coarse=<factory>, nnc_text='NNC\n', coarse_tranx=<factory>, coarse_trany=<factory>, dual_tranx=<factory>, dual_trany=<factory>, dual_defaults=<factory>)[source]#

Bases: object

Store mappings and intermediate values used during coarsening.

Parameters:

  • x (NDArray)

  • y (NDArray)

  • z (NDArray)

  • cell_groups (NDArray)

  • coarsened_axes (str)

  • matrix_mask (NDArray)

  • vertical_transfer_enabled (bool)

  • reference_to_coarse (list[int])

  • nnc_text (str)

  • coarse_tranx (NDArray)

  • coarse_trany (NDArray)

  • dual_tranx (NDArray)

  • dual_trany (NDArray)

  • dual_defaults (dict[str, float])

x: NDArray#

Axis array marking boundaries removed by coarsening in the x direction. Values greater than one identify intervals merged with the preceding interval.

y: NDArray#

Axis array marking boundaries removed by coarsening in the y direction. Values greater than one identify intervals merged with the preceding interval.

z: NDArray#

Axis array marking boundaries removed by coarsening in the z direction. Values greater than one identify intervals merged with the preceding interval.

cell_groups: NDArray#

One-based coarse-cell identifier for each original cell, flattened in (z, y, x) order.

coarsened_axes: str#

Concatenated names of the coarsened axes, for example "xz".

matrix_mask: NDArray#

Per-cell mask separating matrix cells (one) from fracture or non-net cells (zero) in dual-porosity models.

vertical_transfer_enabled: bool#

Whether vertical matrix-fracture transfer connections are retained.

reference_to_coarse: list[int]#

Coarse-cell identifier for each reference-grid cell, populated while properties are coarsened.

nnc_text: str#

NNC include-file content accumulated while mapping non-neighbouring and matrix-fracture connections.

coarse_tranx: NDArray#

Horizontal x-direction transmissibilities for the matrix or single-porosity coarse grid.

coarse_trany: NDArray#

Horizontal y-direction transmissibilities for the matrix or single-porosity coarse grid.

dual_tranx: NDArray#

Horizontal x-direction transmissibilities for the fracture continuum of a dual-porosity grid.

dual_trany: NDArray#

Horizontal y-direction transmissibilities for the fracture continuum of a dual-porosity grid.

dual_defaults: dict[str, float]#

Default property values inserted into separator rows of the extended dual-porosity grid.

create_coarsening_maps(dck, cmdargs)[source]#

Create axis mappings and assign original cells to coarse cells.

Parameters:
dck

Deck configuration whose output dimensions are updated.

cmdargs

Command arguments containing coarsening, x_coarsening, y_coarsening, and z_coarsening.

Returns:
CoarseningMaps

Axis mappings, cell groups, and dual-porosity masks.

Parameters:

  • dck (ConfigViaDeck)

  • cmdargs (Namespace)

Return type:

CoarseningMaps

_grouped_sum(values, groups, size=None)[source]#

Return the sum of values for each one-based group.

Parameters:

  • values (NDArray)

  • groups (NDArray)

  • size (int | None)

Return type:

NDArray

_grouped_count(values, groups, size=None)[source]#

Return the number of non-NaN values for each one-based group.

Parameters:

  • values (NDArray)

  • groups (NDArray)

  • size (int | None)

Return type:

NDArray

_grouped_min(values, groups, size=None)[source]#

Return the minimum value for each one-based group, ignoring NaNs.

Parameters:

  • values (NDArray)

  • groups (NDArray)

  • size (int | None)

Return type:

NDArray

_grouped_max(values, groups, size=None)[source]#

Return the maximum value for each one-based group, ignoring NaNs.

Parameters:

  • values (NDArray)

  • groups (NDArray)

  • size (int | None)

Return type:

NDArray

_grouped_mean(values, groups, size=None)[source]#

Return the mean value for each one-based group, ignoring NaNs.

Parameters:

  • values (NDArray)

  • groups (NDArray)

  • size (int | None)

Return type:

NDArray

_grouped_first(values, groups, size=None)[source]#

Return the first non-NaN value for each one-based group.

Parameters:

  • values (NDArray)

  • groups (NDArray)

  • size (int | None)

Return type:

NDArray

_grouped_last(values, groups, size=None)[source]#

Return the last non-NaN value for each one-based group.

Parameters:

  • values (NDArray)

  • groups (NDArray)

  • size (int | None)

Return type:

NDArray

_grouped_mode(values, group_codes, number_groups)[source]#

Return the smallest mode for each zero-based group, ignoring NaNs.

Parameters:

  • values (NDArray)

  • group_codes (NDArray)

  • number_groups (int)

Return type:

NDArray

coarsen_properties(dck, coarsening, modified_deck, wellcind)[source]#

Aggregate reservoir properties onto the coarsened grid.

Continuous properties use their configured or property-specific aggregation; discrete properties use min, max, or mode. The function writes property include files and updates output pore volume and active cells.

Parameters:
dck

Deck configuration and source INIT or restart properties.

coarsening

Cell groups and masks created by create_coarsening_maps().

modified_deck

Deck lines updated with generated property includes.

wellcind

Coarse-cell indices containing well completions.

Returns:
cluster_minimum, cluster_maximum, removal_mask, generated_files

Activity summaries, the mask used to remove depth-jump cells, and the generated include file names.

Parameters:

  • dck (ConfigViaDeck)

  • coarsening (CoarseningMaps)

  • modified_deck (list[str])

  • wellcind (list[int])

Return type:

tuple[NDArray, NDArray, NDArray, list[str]]

_interleave_dual_property(property_values, dual_values, nx, nz, default_value=0)[source]#

Interleave property and dual-property layers with separator rows.

Parameters:

  • property_values (NDArray)

  • dual_values (NDArray)

  • nx (int)

  • nz (int)

  • default_value (float)

Return type:

NDArray

_find_include_statement(modified_deck, include_line)[source]#

Return the list interval containing an INCLUDE statement.

Parameters:

  • modified_deck (list[str])

  • include_line (str)

Return type:

tuple[int, int]

_compact_permeability_properties(dck, permx, permy, permz, modified_deck)[source]#

Use COPY and MULTIPLY if PERMY and PERMZ can be generated from PERMX.

Parameters:

  • dck (ConfigViaDeck)

  • permx (NDArray)

  • permy (NDArray)

  • permz (NDArray)

  • modified_deck (list[str])

Return type:

list[str]

redistribute_removed_pore_volume(dck, con, cluster_minimum, cluster_maximum, removal_mask)[source]#

Redistribute pore volume from removed coarse cells.

Pore volume is divided among the nearest active neighbours without changing the total pore volume.

Parameters:
dck

Deck configuration whose output_porv is updated.

con

One-based coarse-cell identifier for each original cell.

cluster_minimum, cluster_maximum

Aggregated activity values used to identify changed clusters.

removal_mask

Mask identifying retained coarse cells.

Parameters:

  • dck (ConfigViaDeck)

  • con (NDArray)

  • cluster_minimum (NDArray)

  • cluster_maximum (NDArray)

  • removal_mask (NDArray)

Return type:

None

_find_active_neighbors(dck, neighbor_indices, cluster_id, distance, offset, ijk)[source]#

Find active neighbouring cells for pore-volume redistribution.

Parameters:

  • dck (ConfigViaDeck)

  • neighbor_indices (list[int])

  • cluster_id (int)

  • distance (int)

  • offset (int)

  • ijk (list)

Return type:

list[int]

_global_index_to_ijk(dck, global_index)[source]#

Return the i, j, and k indices from a zero-based global cell index.

Parameters:

  • dck (ConfigViaDeck)

  • global_index (int)

Return type:

tuple[int, int, int]

coarsen_corner_point_grid(dck, coarsening)[source]#

Remove selected pillars and ZCORN surfaces from the grid.

Parameters:
dck

Deck configuration containing the original corner-point grid.

coarsening

Axis mappings defining the removed rows, columns, and layers.

Returns:
coord, zcorn

Coarsened arrays when dual porosity is enabled; otherwise empty arrays.

Parameters:
Return type:

tuple[NDArray, NDArray]

build_dual_porosity_grid(dck, coarsening, cr, zc)[source]#

Extend a coarsened grid with a second porosity continuum.

The matrix and fracture grids are separated in the j direction, and their connections are added to coarsening.nnc_text.

Parameters:
dck

Deck configuration for the coarsened model.

coarsening

Coarsening data containing continuum masks and transmissibilities.

cr, zc

Coarsened COORD and ZCORN arrays.

Returns:
coord, zcorn

Extended dual-porosity grid arrays.

Parameters:

  • dck (ConfigViaDeck)

  • coarsening (CoarseningMaps)

  • cr (NDArray)

  • zc (NDArray)

Return type:

tuple[NDArray, NDArray]

_collect_removed_zcorn_indices(dck, coa_z, removal_indices)[source]#

Add the ZCORN indices removed by vertical coarsening.

Parameters:

  • dck (ConfigViaDeck)

  • coa_z (NDArray)

  • removal_indices (list[int])

Return type:

list[int]

map_nnc_transmissibilities(dck, coarsening)[source]#

Map original non-neighbouring transmissibilities to the coarse grid.

Connections that become Cartesian neighbours are accumulated in TRANX or TRANY; remaining connections are written as NNC records.

Parameters:
dck

Deck configuration and source NNC data.

coarsening

Coarse mapping updated with transmissibilities and NNC text.

Returns:
generated_files

Names of the written include files.

Parameters:
Return type:

list[str]

create_coarsening_map(cfg)[source]#

Map each fine-grid cell to a one-based coarse-cell identifier.

The output dimensions and original-to-output axis mappings in cfg are also updated.

Parameters:
cfg

TOML configuration containing the axis coarsening arrays.

Returns:
NDArray

One-based coarse-cell identifier for every fine-grid cell.

Parameters:

cfg (ConfigViaTOML)

Return type:

NDArray

_group_minimum_zero_based(values, groups, number_groups)[source]#
Parameters:

  • values (NDArray)

  • groups (NDArray)

  • number_groups (int)

Return type:

NDArray

_group_maximum_zero_based(values, groups, number_groups)[source]#
Parameters:

  • values (NDArray)

  • groups (NDArray)

  • number_groups (int)

Return type:

NDArray

_group_sum_zero_based(values, groups, number_groups)[source]#
Parameters:

  • values (NDArray)

  • groups (NDArray)

  • number_groups (int)

Return type:

NDArray

_read_satnum(cfg, actnum, nxyz, satnum_opm)[source]#

Read or generate fine-grid SATNUM values.

Parameters:
cfg

TOML configuration controlling the SATNUM source.

actnum

Fine-grid active-cell mask.

nxyz

Number of fine-grid cells.

satnum_opm

SATNUM values read from the reference INIT file.

Returns:
NDArray

SATNUM value for every fine-grid cell.

Parameters:

  • cfg (ConfigViaTOML)

  • actnum (NDArray)

  • nxyz (int)

  • satnum_opm (NDArray)

Return type:

NDArray

coarsen_and_write_properties(cfg, coa_map)[source]#

Aggregate and write properties for a TOML-generated model.

Parameters:
cfg

TOML configuration and reference-case settings.

coa_map

One-based fine-to-coarse cell mapping.

Returns:
int

Highest generated SATNUM value, used as the number of saturation tables.

Parameters:

  • cfg (ConfigViaTOML)

  • coa_map (NDArray)

Return type:

int