Zone

class petres.models.Zone[source]

Bases: object

A stratigraphic interval bounded by a top and base horizon.

Parameters:

  • name (str) – Identifier for the zone.

  • top (Horizon) – Upper horizon surface.

  • base (Horizon) – Lower horizon surface.

  • levels (tuple[float, ...], default (0.0, 1.0)) – Normalized internal layer interfaces in the range [0, 1]. The default represents a single layer with no subdivision.

name: str
top: Horizon
base: Horizon
levels: tuple[float, ...] = (0.0, 1.0)
property n_layers: int

Return the number of layers defined by levels.

thickness(xy)[source]

Compute zone thickness at the given XY locations.

Parameters:

xy (ndarray) – Points of shape (n, 2) containing x and y coordinates.

Returns:

Thickness values (base minus top) of shape (n,).

Return type:

ndarray

Examples

>>> xy = np.array([[0, 0], [50, 20]])
>>> zone.thickness(xy)
array([30.1, 29.8])
show(*, x=None, y=None, xlim=None, ylim=None, ni=None, nj=None, dx=None, dy=None, view='3d', wells=None)[source]

Render the zone in 3D or 2D.

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

Parameters:

  • x (ndarray or None, default None) – 1D vertex arrays. Mutually exclusive with xlim/ylim.

  • y (ndarray or None, default None) – 1D vertex arrays. Mutually exclusive with xlim/ylim.

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

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

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

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

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

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

  • view ({'3d', '2d'}, default '3d') – Target visualization backend.

Raises:

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

Examples

>>> zone.show()
>>> zone.show(view="2d", xlim=(0, 500), ylim=(0, 500), ni=100, nj=100)
show3d(*, x=None, y=None, xlim=None, ylim=None, ni=None, nj=None, dx=None, dy=None, z_scale=1.0, title='auto', color='#BFFF00', show_layers=True, show_edges=True, wells=None)[source]

Render the zone in an interactive 3D PyVista scene.

Adds the zone’s top/base surfaces and optional layer slices to a PyVista3DViewer.

Parameters:

  • x (ndarray or None, default None) – 1D vertex arrays. Mutually exclusive with xlim/ylim.

  • y (ndarray or None, default None) – 1D vertex arrays. Mutually exclusive with xlim/ylim.

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

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

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

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

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

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

  • color (Any or None, default DEFAULT_COLOR) – Solid color for the zone surfaces. Defaults to the project-wide default color defined in petres.config.colors (DEFAULT_COLOR).

  • show_layers (bool, default True) – Whether to render internal layers derived from levels.

  • show_edges (bool, default True) – Whether to draw mesh edges.

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

Examples

>>> zone.show3d(x=[0, 100], y=[0, 50], ni=50, nj=25, color="lightgray")
show2d(*, x=None, y=None, xlim=None, ylim=None, ni=None, nj=None, dx=None, dy=None, mode='thickness', cmap='petres', show_contours=True, contour_levels=10, aspect='auto', title='auto', wells=None, **kwargs)[source]

Render the zone as 2D maps of top, base, or thickness.

Samples the top/base horizons on a rectilinear grid and plots the chosen scalar field.

Parameters:

  • x (ndarray or None, default None) – 1D vertex arrays. Mutually exclusive with xlim/ylim.

  • y (ndarray or None, default None) – 1D vertex arrays. Mutually exclusive with xlim/ylim.

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

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

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

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

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

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

  • mode ({'top', 'base', 'thickness'}, default 'thickness') – Which scalar to plot.

  • cmap (str, default DEFAULT_CMAP) – 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 None, default 'auto') – Plot title; when ‘auto’ uses the zone 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

>>> zone.show2d(mode="top", xlim=(0, 400), ylim=(0, 300), ni=80, nj=60, cmap="cividis")
divide(*, nk=None, fractions=None, levels=None)[source]

Define internal layering for this zone (single method, Petrel-like).

Exactly one of {nk, fractions, levels} may be provided. If none are provided, the zone becomes single-layer (levels=(0,1)).

Parameters:

  • nk (int or None, default None) – Number of layers divided equally. Must be >= 2.

  • fractions (Sequence[float] or None, default None) – Relative layer thicknesses (positive). Normalized to sum to 1. Example: [0.1, 0.2, 0.7] -> levels [0, 0.1, 0.3, 1.0].

  • levels (Sequence[float] or None, default None) – Normalized interface levels in [0, 1], strictly increasing, starting at 0 and ending at 1. Example: [0, 0.3, 1] -> 2 layers.

Returns:

New Zone instance with updated levels.

Return type:

Zone

Raises:

  • ValueError – If more than one of nk, fractions, or levels is provided, or if inputs violate monotonicity/validity rules.

  • TypeError – If nk is not an integer when supplied.

to_grid(x, y)[source]

Sample top and base horizons on a rectilinear grid.

Parameters:

  • x (ndarray) – 1D x-vertices.

  • y (ndarray) – 1D y-vertices.

Returns:

Tuple (top_z, base_z) each of shape (len(y), len(x)).

Return type:

tuple[np.ndarray, np.ndarray]

Examples

>>> x = np.linspace(0, 200, 41)
>>> y = np.linspace(0, 100, 21)
>>> top_z, base_z = zone.to_grid(x, y)
__init__(name, top, base, levels=(0.0, 1.0))