Horizon

class petres.models.Horizon[source]

Bases: object

Continuous horizon defined from scattered picks and an interpolator.

Parameters:

  • name (str) – Horizon identifier used in viewers and derived objects.

  • interpolator (BaseInterpolator) – Fitted in __post_init__ on the provided xy/depth picks. Must accept 2D inputs.

  • xy (ndarray with dimensions (n, 2)) – XY coordinates for the picked horizon points.

  • depth (ndarray with dimensions (n,)) – Depth values for each pick. Must align with the rows of xy.

  • store_picks (bool, default True) – Whether to retain the raw picks after fitting. Set to False to minimize memory once the interpolator is trained.

Notes

The dataclass-generated __init__ delegates validation and fitting to __post_init__. Use from_wells() to build horizons from well tops.

name: str
interpolator: BaseInterpolator
xy: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]
depth: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]
store_picks: bool = True
__post_init__()[source]

Validate inputs, coerce arrays, and fit the interpolator.

Raises:

  • ValueError – If xy does not have dimensions (n, 2) or depth does not match the number of picks.

  • TypeError – If the interpolator is not a BaseInterpolator instance or does not support 2D coordinates.

classmethod from_wells(*, name, wells, interpolator, store_picks=True)[source]

Construct a horizon from well tops.

Parameters:

  • name (str) – Horizon name to extract from each well’s tops mapping.

  • wells (Iterable[VerticalWell]) – Wells providing XY positions and horizon tops.

  • interpolator (BaseInterpolator) – Interpolator instance to fit on the aggregated picks.

  • store_picks (bool, default True) – Whether to keep the picks after fitting.

Returns:

Horizon fitted to the provided well tops.

Return type:

Horizon

Raises:

ValueError – If any well is missing the requested horizon top.

Examples

>>> horizon = Horizon.from_wells(
...     name="TopReservoir",
...     wells=[well_a, well_b],
...     interpolator=my_rbf,
... )
to_zone(name, depth)[source]

Create a zone by shifting this horizon by a constant depth.

Parameters:

  • name (str) – Name of the generated zone.

  • depth (float) – Vertical shift applied to derive the second horizon. Positive values move the second horizon deeper (assuming depth increases downward).

Returns:

Zone composed of this horizon and the shifted counterpart.

Return type:

Zone

Raises:

ValueError – If depth is zero or picks were not retained (store_picks=False).

Examples

>>> gross = horizon.to_zone(name="Gross", depth=25.0)
>>> gross.top is horizon
True
sample(xy)[source]

Evaluate the horizon depth at arbitrary XY locations.

Parameters:

xy (array-like with dimensions (n, 2)) – Points containing x and y coordinates.

Returns:

Depth values with length n.

Return type:

ndarray

Raises:

ValueError – If xy is not a 2D array with two columns.

Examples

>>> xy = np.array([[0.0, 0.0], [10.0, 5.0]])
>>> horizon.sample(xy)
array([1234.5, 1236.8])
to_grid(x, y)[source]

Resample the horizon onto a rectilinear grid.

Parameters:

  • x (array-like) – 1D x-vertices.

  • y (array-like) – 1D y-vertices.

Returns:

Depth array with dimensions (len(y), len(x)) matching meshgrid(y, x) order.

Return type:

ndarray

Examples

>>> x = np.linspace(0, 100, 11)
>>> y = np.linspace(0, 50, 6)
>>> depth_grid = horizon.to_grid(x, y)
intersect(well)[source]

Compute the depth where the horizon intersects a vertical well.

Parameters:

well (VerticalWell) – Well instance providing XY coordinates.

Returns:

Depth value at the well location.

Return type:

float

Examples

>>> horizon.intersect(well)
1530.2
show(*, x=None, y=None, xlim=None, ylim=None, ni=None, nj=None, dx=None, dy=None, view='3d', wells=None)[source]

Render the horizon in either 3D or 2D.

Dispatches to show3d or show2d based on view, passing through any grid specification arguments.

Parameters:

  • x (array-like or None, optional) – 1D x-vertices. Mutually exclusive with xlim.

  • y (array-like or None, optional) – 1D y-vertices. Mutually exclusive with ylim.

  • xlim (tuple[float, float] or None, optional) – Inclusive x-limits used to generate vertices when x is not given.

  • ylim (tuple[float, float] or None, optional) – Inclusive y-limits used to generate vertices when y is not given.

  • ni (int or None, optional) – Number of cells along x when using xlim. Must be >= 1.

  • nj (int or None, optional) – Number of cells along y when using ylim. Must be >= 1.

  • dx (float or None, optional) – Cell size along x when using xlim. Mutually exclusive with ni.

  • dy (float or None, optional) – Cell size along y when using ylim. Mutually exclusive with nj.

  • view ({'3d', '2d'}, default '3d') – Target visualization backend. Use ‘3d’ for PyVista, ‘2d’ for Matplotlib.

  • 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.

Raises:

ValueError – If view is not one of {‘3d’, ‘2d’}.

Examples

>>> horizon.show()
>>> horizon.show(view="2d", x=[0, 10], y=[0, 10])
show3d(*, x=None, y=None, xlim=None, ylim=None, ni=None, nj=None, dx=None, dy=None, color='tan', scalars=True, cmap='turbo', title='auto', z_scale=1.0, wells=None)[source]

Render the horizon in an interactive 3D PyVista scene.

Samples the interpolated surface on the provided grid and adds it to a PyVista3DViewer, coloring by depth.

Parameters:

  • x (array-like or None, optional) – 1D vertex arrays. Mutually exclusive with xlim/ylim.

  • y (array-like or None, optional) – 1D vertex arrays. Mutually exclusive with xlim/ylim.

  • xlim (tuple[float, float] or None, optional) – Bounds used to generate vertices when x or y are not supplied.

  • ylim (tuple[float, float] or None, optional) – Bounds used to generate vertices when x or y are not supplied.

  • ni (int or None, optional) – Number of cells along x/y when using bounds. Must be >= 1.

  • nj (int or None, optional) – Number of cells along x/y when using bounds. Must be >= 1.

  • dx (float or None, optional) – Cell size along x/y when using bounds. Mutually exclusive with ni/nj.

  • dy (float or None, optional) – Cell size along x/y when using bounds. Mutually exclusive with ni/nj.

  • color (Any or None, default 'tan') – Solid color for the surface when scalars is False; otherwise used as edge/mesh color by the backend.

  • scalars (bool, default True) – Whether to color by depth values.

  • cmap (str or None, default 'turbo') – Colormap name applied when scalars is True.

  • 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 to exaggerate vertical relief.

  • 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.

Examples

>>> horizon.show3d(x=[0, 100], y=[0, 100], ni=50, nj=50, cmap="viridis")
show2d(*, x=None, y=None, xlim=None, ylim=None, ni=None, nj=None, dx=None, dy=None, cmap='turbo', show_contours=True, contour_levels=10, aspect='auto', title='auto', wells=None, **kwargs)[source]

Render the horizon as a 2D Matplotlib map.

Interpolates the surface on a regular grid and displays it with optional contours.

Parameters:

  • x (array-like or None, optional) – 1D vertex arrays. Mutually exclusive with xlim/ylim.

  • y (array-like or None, optional) – 1D vertex arrays. Mutually exclusive with xlim/ylim.

  • xlim (tuple[float, float] or None, optional) – Bounds used to generate vertices when x or y are not supplied.

  • ylim (tuple[float, float] or None, optional) – Bounds used to generate vertices when x or y are not supplied.

  • ni (int or None, optional) – Number of cells along x/y when using bounds. Must be >= 1.

  • nj (int or None, optional) – Number of cells along x/y when using bounds. Must be >= 1.

  • dx (float or None, optional) – Cell size along x/y when using bounds. Mutually exclusive with ni/nj.

  • dy (float or None, optional) – Cell size along x/y when using bounds. Mutually exclusive with ni/nj.

  • cmap (str, default "turbo") – Colormap used for the surface.

  • show_contours (bool, default True) – Whether to overlay contour lines.

  • contour_levels (int, default 10) – Number of contour levels.

  • aspect ({'auto', 'equal'}, default 'auto') – Axes aspect ratio.

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

  • 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) – Additional keyword arguments forwarded to the Matplotlib surface helper.

Examples

>>> horizon.show2d(xlim=(0, 500), ylim=(0, 500), ni=100, nj=100, cmap="magma")
__init__(name, interpolator, xy, depth, store_picks=True)