pycopm.utils.vicinity module

Extract submodels and map pore volume from outside their boundaries.

class pycopm.utils.vicinity.VicinityMaps(selector: str, shape: str | None, cell_mask: ~numpy._typing._array_like.NDArray, min_i: int, max_i: int, min_j: int, max_j: int, min_k: int, max_k: int, layer_min_i: ~numpy._typing._array_like.NDArray, layer_max_i: ~numpy._typing._array_like.NDArray, layer_min_j: ~numpy._typing._array_like.NDArray, layer_max_j: ~numpy._typing._array_like.NDArray, layer_selected_porv: ~numpy._typing._array_like.NDArray, layer_external_porv: ~numpy._typing._array_like.NDArray, well_cells: list[list[int]], well_indices: list[int] = <factory>, active_counts: ~numpy._typing._array_like.NDArray = <factory>, source_indices: ~numpy._typing._array_like.NDArray = <factory>)

Bases: object

Store a vicinity selection, bounds, and pore-volume mappings.

Global and per-layer bounds are one-based and inclusive.

active_counts: NDArray

Number of selected active cells in each output layer.

cell_mask: NDArray

Boolean mask identifying selected original-grid cells, flattened in (z, y, x) order.

layer_external_porv: NDArray

Total pore volume outside the selection in each original layer.

layer_max_i: NDArray

Maximum selected i index in each original layer.

layer_max_j: NDArray

Maximum selected j index in each original layer.

layer_min_i: NDArray

Minimum selected i index in each original layer.

layer_min_j: NDArray

Minimum selected j index in each original layer.

layer_selected_porv: NDArray

Total pore volume of selected active cells in each original layer.

max_i: int

Maximum selected i index across all layers.

max_j: int

Maximum selected j index across all layers.

max_k: int

Maximum selected k index.

min_i: int

Minimum selected i index across all layers.

min_j: int

Minimum selected j index across all layers.

min_k: int

Minimum selected k index.

selector: str

Selected well name, or an empty string for polygon and region selections.

shape: str | None

box, diamond, or diamondxy. None is used for polygon and region selections.

Type:

Well-vicinity shape

source_indices: NDArray

Original-grid source index assigned to each output boundary cell during pore-volume correction. Zero denotes no assigned source.

well_cells: list[list[int]]

Zero-based completion coordinates in [i, j, k] order for the selected well.

well_indices: list[int]

Zero-based output-grid indices of selected well cells. These cells are excluded from boundary source remapping.

class pycopm.utils.vicinity._BoundaryMapping(pore_volume: float, active_count: int, offsets: NDArray)

Bases: object

Store pore-volume mapping results for one submodel boundary.

active_count: int

Number of active cells receiving pore volume from the boundary.

offsets: NDArray

Distance from the geometric boundary to each receiving cell.

pore_volume: float

Unassigned pore volume collected along the boundary.

pycopm.utils.vicinity._add_or_collect_porv(dck: ConfigViaDeck, submodel_index: int, pore_volume: float) → float

pycopm.utils.vicinity._apply_layer_pore_volume_correction(dck: ConfigViaDeck, vicinity: VicinityMaps, layer_index: int, column_offset: int, row_offset: int, trailing_columns: int, trailing_rows: int, south: _BoundaryMapping, north: _BoundaryMapping, east: _BoundaryMapping, west: _BoundaryMapping, corner_porv: tuple[float, float, float, float]) → None

pycopm.utils.vicinity._corner_pore_volumes(dck: ConfigViaDeck, vicinity: VicinityMaps, original_layer: int) → tuple[float, float, float, float]

Calculate excluded pore volume in the four layer corners.

Returns:

Corner pore-volume totals for the selected original layer.

Return type:

southwest, southeast, northwest, northeast

pycopm.utils.vicinity._distribute_vertical_pore_volume(dck: ConfigViaDeck, vicinity: VicinityMaps) → None

Distribute pore volume excluded above and below the submodel.

Parameters:

• dck – Deck configuration whose output_porv is updated.

• vicinity – Selection bounds and correction settings.

pycopm.utils.vicinity._find_nearest_active_corner_cell(dck: ConfigViaDeck, layer_index: int, corner_i: int, corner_j: int) → int

Return the nearest active cell to a corner in a layer.

pycopm.utils.vicinity._get_well_completions_for_vicinity(dck: ConfigViaDeck, optvic) → list

Collect zero-based completions for a selected well.

Parameters:

• dck – Deck configuration identifying the source DATA file.

• optvic – Well name from the vicinity specification.

Returns:

Completion coordinates in [i, j, k] order.

Return type:

list[list[int]]

pycopm.utils.vicinity._map_east_boundary(dck: ConfigViaDeck, vicinity: VicinityMaps, layer_index: int, original_layer: int, column_offset: int, row_offset: int, trailing_rows: int) → _BoundaryMapping

pycopm.utils.vicinity._map_north_boundary(dck: ConfigViaDeck, vicinity: VicinityMaps, layer_index: int, original_layer: int, column_offset: int, trailing_rows: int, trailing_columns: int) → _BoundaryMapping

pycopm.utils.vicinity._map_south_boundary(dck: ConfigViaDeck, vicinity: VicinityMaps, layer_index: int, original_layer: int, column_offset: int, row_offset: int, trailing_columns: int) → _BoundaryMapping

pycopm.utils.vicinity._map_west_boundary(dck: ConfigViaDeck, vicinity: VicinityMaps, layer_index: int, original_layer: int, row_offset: int, trailing_rows: int, trailing_columns: int) → _BoundaryMapping

pycopm.utils.vicinity._original_index(dck: ConfigViaDeck, column: int, row: int, layer: int) → int

pycopm.utils.vicinity._submodel_index(dck: ConfigViaDeck, column: int, row: int, layer: int) → int

pycopm.utils.vicinity.apply_boundary_pore_volume_correction(dck: ConfigViaDeck, vicinity: VicinityMaps) → None

Map pore volume excluded from the submodel onto active cells.

The correction strategy is selected by dck.pore_volume_correction. Depending on the chosen method, excluded pore volume is assigned to corresponding boundary cells, nearest corner cells, all boundary cells, or all active cells.

Parameters:

• dck – Deck configuration whose output_porv is updated.

• vicinity – Selection bounds and pore-volume mapping arrays.

pycopm.utils.vicinity.create_vicinity_maps(dck: ConfigViaDeck) → VicinityMaps

Select submodel cells and calculate their bounds.

Selections can use region values, an xy polygon, or a well-centred box, diamond, or diamondxy neighbourhood.

Parameters:

dck – Deck configuration containing the vicinity specification and source grid.

Returns:

Selection mask, bounds, well cells, and per-layer pore-volume totals.

Return type:

VicinityMaps

pycopm.utils.vicinity.extract_vicinity_grid(dck: ConfigViaDeck, vicinity: VicinityMaps) → None

Extract and write the selected corner-point subgrid.

Parameters:

• dck – Deck configuration containing source geometry and axis mappings.

• vicinity – Inclusive bounds of the selected submodel.

pycopm.utils.vicinity.map_vicinity_properties(dck: ConfigViaDeck, vicinity: VicinityMaps, modified_deck: list[str]) → None

Map reservoir properties into the submodel bounding box.

Cells inside the bounding box but outside the selection are written as inactive. The function updates output pore volume and active cells.

Parameters:

• dck – Deck configuration containing source properties and output dimensions.

• vicinity – Selection and bounds created by create_vicinity_maps().

• modified_deck – Deck lines updated with generated property includes.