GridProperty

class petres.grids.GridProperty[source]

Bases: object

Represent a cell-based property defined on a corner-point grid.

The property stores values per cell with shape (nk, nj, ni) and provides assignment helpers for constants, random distributions, functions, arrays, and well-based interpolation.

Parameters:

  • name (str) – Property name (must be unique on the grid).

  • grid (CornerPointGrid) – Owning grid; used for shape and masking.

  • values (ndarray or None, optional, default None) – Property values of shape (nk, nj, ni). If None, initialized to NaN.

  • eclipse_keyword (str or None, optional, default None) – Optional Eclipse keyword for export.

  • description (str or None, optional, default None) – Free-form description.

Notes

Initialization delegates validation and normalization to __post_init__().

Initialize the property and run post-initialization validation.

Raises:

  • TypeError – If name or eclipse_keyword has an invalid type.

  • ValueError – If name is empty, values shape mismatches the grid, or eclipse_keyword resolves to an empty keyword.

__init__(name, grid, values=None, eclipse_keyword=None, description=None)[source]

Initialize the property and run post-initialization validation.

Raises:

  • TypeError – If name or eclipse_keyword has an invalid type.

  • ValueError – If name is empty, values shape mismatches the grid, or eclipse_keyword resolves to an empty keyword.

name: str
grid: CornerPointGrid
values: np.ndarray | None = None
eclipse_keyword: str | None = None
description: str | None = None
__post_init__()[source]

Validate and normalize property initialization inputs.

Raises:

  • TypeError – If name is not a string or eclipse_keyword has invalid type.

  • ValueError – If name is empty, values shape mismatches grid shape, or eclipse_keyword resolves to an empty keyword.

show(*, show_inactive=False, cmap='turbo', title='auto', z_scale=1.0, wells=None, **kwargs)[source]

Visualize the property in 3D using the grid viewer.

Parameters:

  • show_inactive (bool, default False) – Whether to display inactive cells.

  • cmap (str or None, default 'turbo') – Colormap used for rendering.

  • title (str or 'auto', default 'auto') – Window title; 'auto' uses the property name.

  • z_scale (float, default 1.0) – Scale factor for the z-axis.

  • wells (VerticalWell or Sequence[VerticalWell] or None, optional) – Well(s) to plot on top of the grid. Can be a single VerticalWell or a sequence of them. If None, no wells are plotted.

  • **kwargs (Any) – Forwarded to viewer add_grid.

Notes

title='auto' expands to Property: <name>.

property shape: tuple[int, int, int]

Return property array shape.

Returns:

Shape ordered as (nk, nj, ni).

Return type:

tuple of int

property nk: int

Return number of cells in k direction.

Returns:

Number of layers.

Return type:

int

property nj: int

Return number of cells in j direction.

Returns:

Number of rows.

Return type:

int

property ni: int

Return number of cells in i direction.

Returns:

Number of columns.

Return type:

int

property n_cells: int

Return total number of cells.

Returns:

Product nk * nj * ni.

Return type:

int

property min: float

Return minimum finite property value.

Returns:

NaN-aware minimum value.

Return type:

float

property max: float

Return maximum finite property value.

Returns:

NaN-aware maximum value.

Return type:

float

property mean: float

Return arithmetic mean of finite values.

Returns:

NaN-aware mean value.

Return type:

float

property median: float

Return median of finite values.

Returns:

NaN-aware median value.

Return type:

float

property std: float

Return standard deviation of finite values.

Returns:

NaN-aware standard deviation.

Return type:

float

fill_normal(mean, std, *, zone=None, include_inactive=True, min=None, max=None, seed=None)[source]

Fill target cells with samples from a normal distribution.

Parameters:

  • mean (float) – Mean of the normal distribution.

  • std (float) – Standard deviation of the normal distribution.

  • zone (str or Zone or None, optional, default None) – Restrict assignment to a zone.

  • include_inactive (bool, default True) – When False, only active cells are assigned.

  • min (float, optional, default None) – Minimum value after adding noise (clipping).

  • max (float, optional, default None) – Maximum value after adding noise (clipping).

  • seed (int or None, optional, default None) – Seed for reproducible sampling.

Returns:

Self, for chaining.

Return type:

GridProperty

Raises:

ValueError – If std is negative.

apply(func, *, source, zone=None, include_inactive=True)[source]

Apply a function to one or more source arrays and store the result.

Parameters:

  • func (callable) – Function applied to the resolved source arrays.

  • source (str | GridProperty | sequence of these) –

    Input source(s) for the function.

    Supported built-in string sources: - “x” : cell-center x coordinate - “y” : cell-center y coordinate - “depth”, “z” : cell-center depth (positive downward) - “top” : top z of cell - “bottom” : bottom z of cell - “thickness” : cell thickness - “active” : 1 for active cells, 0 for inactive

    You may also pass another GridProperty, or a tuple/list mixing them.

  • zone (str | Zone | None, optional, default None) – Restrict assignment to a zone.

  • include_inactive (bool, default True) – When False, only active cells are assigned.

Returns:

Self, for chaining.

Return type:

GridProperty

Examples

>>> poro.apply(lambda z: 0.32 - 0.00015 * z, source="depth")

>>> perm.apply(lambda p: 1000 * p**3, source=poro)

>>> perm.apply(
...     lambda z, p: (1000 * p**3) * np.exp(-z / 3000.0),
...     source=("depth", poro),
... )
Raises:

  • TypeError – If func is not callable or source type is invalid.

  • ValueError – If resolved source dimensions are incompatible or function output shape is unsupported.

fill(value, *, zone=None, include_inactive=True)[source]

Fill target cells with a constant numeric value.

Parameters:

  • value (float or int) – Value to assign.

  • zone (str | Zone | None, optional, default None) – Restrict assignment to a zone.

  • include_inactive (bool, default True) – When False, only active cells are assigned.

Returns:

Self, for chaining.

Return type:

GridProperty

Raises:

TypeError – If value is not numeric.

fill_lognormal(mean, std, *, zone=None, include_inactive=True, min=None, max=None, seed=None)[source]

Fill target cells with samples from a lognormal distribution.

Parameters:

  • mean (float) – Mean in linear space (e.g. permeability mean).

  • std (float) – Standard deviation in linear space.

  • zone (str | Zone | None, optional, default None) – Restrict to zone.

  • include_inactive (bool, default True) – When False, only active cells are assigned.

  • min (float | None, default None) – Optional lower bound.

  • max (float | None, default None) – Optional upper bound.

  • seed (int | None, default None) – Random seed.

Notes

Internally converts linear mean/std to log-space parameters.

Returns:

Self, for chaining.

Return type:

GridProperty

Raises:

ValueError – If mean <= 0 or std < 0.

fill_uniform(low, high, *, zone=None, include_inactive=True, seed=None)[source]

Fill target cells with samples from a uniform distribution.

Parameters:

  • low (float) – Lower bound of the distribution.

  • high (float) – Upper bound of the distribution (must be >= low).

  • zone (str or Zone or None, optional, default None) – Restrict assignment to a zone.

  • include_inactive (bool, default True) – When False, inactive cells are excluded.

  • seed (int or None, optional, default None) – Seed for reproducible sampling.

Returns:

Self, for chaining.

Return type:

GridProperty

Raises:

ValueError – If high < low.

fill_nan(value, *, zone=None, include_inactive=True)[source]

Fill NaN entries with a constant value.

Parameters:

  • value (float or int) – Replacement value for NaN cells.

  • zone (str or Zone or None, optional, default None) – Restrict assignment to a zone.

  • include_inactive (bool, default True) – When False, inactive cells are excluded.

Returns:

Self, for chaining.

Return type:

GridProperty

from_array(values, *, zone=None, include_inactive=True)[source]

Assign values from an array, optionally scoped by zone/active mask.

Parameters:

  • values (ndarray) – Source array shaped (nk, nj, ni).

  • zone (str or Zone or None, optional, default None) – Restrict assignment to a zone.

  • include_inactive (bool, default True) – When False, inactive cells are excluded.

Returns:

Self, for chaining.

Return type:

GridProperty

Raises:

ValueError – If values shape does not match grid shape.

from_wells(wells, interpolator, *, source=None, zone=None, location='center', include_inactive=True)[source]

Populate this property by interpolating well samples.

Parameters:

  • wells (sequence of VerticalWell) – Wells containing property samples.

  • interpolator (BaseInterpolator) – Interpolator instance with fit(points, values) and predict(query) methods.

  • source (str | None, optional, default None) – Sample property name to read from wells. Defaults to self.name.

  • location ({"center", "top", "bottom"}, default "center") – Grid cell location used as interpolation target.

  • zone (str | Zone | None, optional, default None) – Restrict assignment to a zone.

  • include_inactive (bool, default True) – When False, only active cells are assigned.

Notes

Interpolation mode is inferred from well sample storage for source: scalar samples are interpolated in XY (2D), depth-indexed samples are interpolated in XYZ (3D).

Returns:

Self, for chaining.

Return type:

GridProperty

Raises:

  • ValueError – If well sample modes for source are inconsistent, source data is invalid, or interpolator output shape is invalid.

  • TypeError – If interpolator is not a BaseInterpolator or wells contain invalid entries.

to_grdecl(path)[source]

Write property values to a GRDECL file.

Parameters:

path (str) – Destination file path.

Raises:
summary()[source]

Return a formatted textual summary for the property.

Returns:

Multi-line summary string containing metadata and statistics.

Return type:

str