API Reference

Surfaces (maps)

RegularSurface

Functions

xtgeo.surface_from_file(mfile, fformat=None, template=None, values=True, engine=None, dtype=<class 'numpy.float64'>)[source]

Make an instance of a RegularSurface directly from file import.

Parameters:

mfile (str) – Name of file
fformat – File format, None/guess/irap_binary/irap_ascii/ijxyz/petromod/ zmap_ascii/xtg/hdf is currently supported. If None or guess, the file ‘signature’ is used to guess format first, then file extension.
template – Only valid if ijxyz format, where an existing Cube or RegularSurface instance is applied to get correct topology.
values (bool) – If True (default), surface values will be read (Irap binary only)
engine (str) – Key indended for developers initially, now deprecated and have no effect. To be removed in future versions.
dtype (Union[Type[float64], Type[float32]]) – Requsted numpy dtype of values; default is float64, alternatively float32

Example:

>>> import xtgeo
>>> mysurf = xtgeo.surface_from_file(surface_dir + '/topreek_rota.gri')

Changed in version 2.1: Key “values” for Irap binary maps added

Changed in version 2.13: Key “engine” added

xtgeo.surface_from_cube(cube, value)[source]

Make RegularSurface directly from a cube instance with a constant value.

The surface geometry will be exactly the same as for the Cube.

Parameters:

cube (xtgeo.cube.Cube) – A Cube instance
value (float) – A constant value for the surface

Example:

>>> import xtgeo
>>> mycube = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")
>>> mymap = xtgeo.surface_from_cube(mycube, 2700)

xtgeo.surface_from_grid3d(grid, template=None, where='top', property='depth', rfactor=1.0, index_position='center', **kwargs)[source]

This makes an instance of a RegularSurface directly from a Grid() instance.

Parameters:

grid (Grid) – XTGeo 3D Grid instance, describing the corner point grid geometry
template (RegularSurface | str | None) – Optional, to use an existing surface as template for map geometry, or by using “native” which returns a surface that approximate the 3D grid layout (same number of rows and columns, and same rotation). If None (default) a non-rotated surface will be made based on a refined estimation from the current grid resolution (see rfactor).
where (str | int) – Cell layer number, or if property is “depth”, use “top” or “base” to get a surface sampled from the very top or very base of the grid (including inactive cells!). Otherwise use the syntax “2_top” where 2 is layer no. 2 and _top indicates top of cell, while “_base” indicates base of cell. Cell layer numbering starts from 1. Default position in a cell layer is “top” if layer is given as pure number and “depth” is the property. If a grid property is given, the position is always found the center depth within in a cell.
property (str | GridProperty) – Which property to return. Choices are “depth”, “i” (columns) or “j” (rows) or, more generic, a GridProperty instance which belongs to the given grid geometry. Alle these returns a RegularSurface. A special variant is “raw” which returns a list of 2D numpy arrays. See details in the Note section.
rfactor (float) – Note this setting will only apply if template is None. Determines how fine the extracted map is; higher values for finer map (but computing time will increase slightly). The default is 1.0, which in effect will make a surface approximentaly twice as fine as the average resolution estimated from the 3D grid.
index_position (Literal['center', 'top', 'base']) – Default is “center” which means that the index is taken from the Z center of the cell. If “top” is given, the index is taken from the top of the cell, and if “base” is given, the index is taken from the base of the cell. This is only valid for index properties “i” and “j”.

Return type:

Union[RegularSurface, List[ndarray]]

Note::: The keyword mode is deprecated and will be removed in XTGeo version 5, use keyword property instead. If both are given, property will be used.
Note::: For property “depth”, “i” and “j”, all cells in a layer will be used (including inactive 3D cells), while for a GridProperty, only active cells will be used. Hence the extent of the resulting surfaces may differ.
Note::: For property “raw”, the return is a list of 2D arrays, where the first array is the i-index (int), the second is the j-index (int), the third is the top depth (float64), the fourth is the bottom depth (float64), and the fifth is a mask (boolean) for inactive cells. For the index arrays, -1 indicates that the cell is outside any grid cell (projected from above; i.e. could also be within a fault). For the depth arrays, the value is NaN for inactive cells. The inactive mask is True for inactive cells. The index arrays and mask is derived from the Z midpoints of the 3D cells. The “raw” option is useful for further processing in Python, e.g. when a combination of properties is needed.

Added in version 2.1.

Changed in version 4.2: Changed mode to property to add support for a GridProperty. The where arg. can now be an integer. Added option activeonly.

Changed in version 4.3: Added option raw to get data for further processing. and add index_position for “i” and “j” properties.

xtgeo.surface_from_roxar(project, name, category, stype='horizons', realisation=0, dtype=<class 'numpy.float64'>)[source]

This makes an instance of a RegularSurface directly from roxar input.

Parameters:

project (str or special) – Name of project (as folder) if outside RMS, og just use the magic project word if within RMS.
name (str) – Name of surface/map
category (str) – For horizons/zones or clipboard/general2d_data: for example ‘DS_extracted’. For clipboard/general2d_data this can be empty or None, or use ‘/’ for multiple folder levels (e.g. ‘fld/subfld’). For ‘trends’, the category is not applied.
stype (str) – RMS folder type, ‘horizons’ (default), ‘zones’, ‘clipboard’, ‘general2d_data’ or ‘trends’
realisation (int) – Realisation number, default is 0
dtype (Union[Type[float64], Type[float32]]) – Requested numpy dtype for array; default is 64 bit

Example:

# inside RMS:
import xtgeo
mysurf = xtgeo.surface_from_roxar(project, 'TopEtive', 'DepthSurface')

Note:

When dealing with surfaces to and from ``stype="trends"``, the surface must
exist in advance, i.e. the Roxar API do not allow creating new surfaces.
Actually trends are read only, but a workaround using ``load()`` in Roxar
API makes it possible to overwrite existing surface trends. In addition,
``realisation`` is not applied in trends.

Classes

class xtgeo.RegularSurface(ncol, nrow, xinc, yinc, xori=0.0, yori=0.0, yflip=1, rotation=0.0, values=None, ilines=None, xlines=None, masked=True, name='unknown', filesrc=None, fformat=None, undef=1e+33, dtype=<class 'numpy.float64'>)[source]

Bases: object

Class for a regular surface in the XTGeo framework.

The values can as default be accessed by the user as a 2D masked numpy (ncol, nrow) float64 array, but also other representations or views are possible (e.g. as 1D ordinary numpy).

Instantiating a RegularSurface:

vals = np.zeros(30 * 50)
surf = xtgeo.RegularSurface(
    ncol=30, nrow=50, xori=1234.5, yori=4321.0, xinc=30.0, yinc=50.0,
    rotation=30.0, values=vals, yflip=1,
)

Parameters:

ncol (int) – Integer for number of X direction columns.
nrow (int) – Integer for number of Y direction rows.
xori (Optional[float]) – X (East) origon coordinate.
yori (Optional[float]) – Y (North) origin coordinate.
xinc (float) – X increment.
yinc (float) – Y increment.
yflip (Optional[int]) – If 1, the map grid is left-handed (assuming depth downwards), otherwise -1 means that Y axis is flipped (right-handed).
rotation (Optional[float]) – rotation in degrees, anticlock from X axis between 0, 360.
values (Union[List[float], float, None]) – A scalar (for constant values) or a “array-like” input that has ncol * nrow elements. As result, a 2D (masked) numpy array of shape (ncol, nrow), C order will be made.
masked (Optional[bool]) – Indicating if numpy array shall be masked or not. Default is True.
name (Optional[str]) – A given name for the surface, default is file name root or ‘unknown’ if constructed from scratch.

Examples

The instance can be made by specification:

>>> surface = RegularSurface(
... ncol=20,
... nrow=10,
... xori=2000.0,
... yori=2000.0,
... rotation=0.0,
... xinc=25.0,
... yinc=25.0,
... values=np.zeros((20,10))
... )

Public Data Attributes:

`metadata`	Return metadata object instance of type MetaDataRegularSurface.
`ncol`	The NCOL (NX or N-Idir) number, as property (read only).
`nrow`	The NROW (NY or N-Jdir) number, as property (read only).
`dimensions`	The surface dimensions as a tuple of 2 integers (read only).
`nactive`	Number of active map nodes (read only).
`rotation`	The rotation, anticlock from X axis, in degrees [0..360>.
`xinc`	The X increment (or I dir increment).
`yinc`	The Y increment (or I dir increment).
`yflip`	The Y flip (handedness) indicator 1, or -1 (read only).
`xori`	The X coordinate origin of the map.
`yori`	The Y coordinate origin of the map.
`ilines`	The inlines numbering vector (read only).
`xlines`	The xlines numbering vector (read only).
`xmin`	The minimim X coordinate (read only).
`xmax`	The maximum X coordinate (read only).
`ymin`	The minimim Y coordinate (read only).
`ymax`	The maximum Y xoordinate (read only).
`dtype`	Getting the dtype of the values (np.array); float64 or float32
`values`	The map values, as 2D masked numpy (float64/32), shape (ncol, nrow).
`values1d`	(Read only) Map values, as 1D numpy masked, normally a numpy view(?).
`npvalues1d`	(Read only) Map values, as 1D numpy (not masked), undef as np.nan.
`name`	A free form name for the surface, to be used in display etc.
`undef`	Returns the undef map value (read only).
`undef_limit`	Returns the undef_limit map value (read only).
`filesrc`	Gives the name of the file source (if any).

Public Methods:

`methods`()	Returns the names of the methods in the class.
`generate_hash`([hashmethod])	Return a unique hash ID for current instance.
`describe`([flush])	Describe an instance by printing to stdout.
`load_values`()	Import surface values in cases where metadata only is loaded.
`to_file`(mfile[, fformat, pmd_dataunits, ...])	Export a surface (map) to file.
`to_hdf`(mfile[, compression])	Export a surface (map) with metadata to a HDF5 file.
`to_roxar`(project, name, category[, stype, ...])	Store (export) a regular surface to a Roxar RMS project.
`copy`()	Deep copy of a RegularSurface object to another instance.
`get_values1d`([order, asmasked, fill_value, ...])	Get a 1D numpy or masked array of the map values.
`set_values1d`(val[, order])	Update the values attribute based on a 1D input, multiple options.
`get_rotation`()	Returns the surface roation, in degrees, from X, anti-clock.
`get_nx`()	Same as ncol (nx) (for backward compatibility).
`get_ny`()	Same as nrow (ny) (for backward compatibility).
`get_xori`()	Same as property xori (for backward compatibility).
`get_yori`()	Same as property yori (for backward compatibility).
`get_xinc`()	Same as property xinc (for backward compatibility).
`get_yinc`()	Same as property yinc (for backward compatibility).
`similarity_index`(other)	Report the degree of similarity between two maps, by comparing mean.
`compare_topology`(other[, strict])	Check that two object has the same topology, i.e. map definitions.
`swapaxes`()	Swap (flip) the axes columns vs rows, keep origin but reverse yflip.
`make_lefthanded`()	Makes the surface lefthanded in case yflip is -1.
`make_righthanded`()	Makes the surface righthanded in case yflip is 1.
`get_map_xycorners`()	Get the X and Y coordinates of the map corners.
`get_value_from_xy`([point, sampling])	Return the map value given a X Y point.
`get_xy_value_from_ij`(iloc, jloc[, zvalues])	Returns x, y, z(value) from a single i j location.
`get_ij_values`([zero_based, asmasked, order])	Return I J numpy 2D arrays, optionally as masked arrays.
`get_ij_values1d`([zero_based, activeonly, order])	Return I J numpy as 1D arrays.
`get_xy_values`([order, asmasked])	Return coordinates for X and Y as numpy (masked) 2D arrays.
`get_xy_values1d`([order, activeonly])	Return coordinates for X and Y as numpy 1D arrays.
`get_xyz_values`()	Return coordinates for X Y and Z (values) as numpy (masked) 2D arrays.
`get_xyz_values1d`([order, activeonly, fill_value])	Return coordinates for X Y and Z (values) as numpy 1D arrays.
`get_dataframe`([ijcolumns, ij, order, ...])	Return a Pandas dataframe object, with columns X_UTME, Y_UTMN, VALUES.
`dataframe`(**kwargs)	Deprecated; see method get_dataframe().
`get_xy_value_lists`([lformat, xyfmt, valuefmt])	Returns two lists for coordinates (x, y) and values.
`autocrop`()	Automatic cropping of the surface to minimize undefined areas.
`fill`([fill_value])	Fast infilling of undefined values.
`smooth`([method, iterations, width])	Various smoothing methods for surfaces.
`operation`(opname, value)	Do operation on map values.
`operation_polygons`(poly, value[, opname, ...])	A generic function for map operations inside or outside polygon(s).
`add_inside`(poly, value)	Add a value (scalar or other map) inside polygons.
`add_outside`(poly, value)	Add a value (scalar or other map) outside polygons.
`sub_inside`(poly, value)	Subtract a value (scalar or other map) inside polygons.
`sub_outside`(poly, value)	Subtract a value (scalar or other map) outside polygons.
`mul_inside`(poly, value)	Multiply a value (scalar or other map) inside polygons.
`mul_outside`(poly, value)	Multiply a value (scalar or other map) outside polygons.
`div_inside`(poly, value)	Divide a value (scalar or other map) inside polygons.
`div_outside`(poly, value)	Divide a value (scalar or other map) outside polygons.
`set_inside`(poly, value)	Set a value (scalar or other map) inside polygons.
`set_outside`(poly, value)	Set a value (scalar or other map) outside polygons.
`eli_inside`(poly)	Eliminate current map values inside polygons.
`eli_outside`(poly)	Eliminate current map values outside polygons.
`add`(other)	Add another map to current map.
`subtract`(other)	Subtract another map from current map.
`multiply`(other)	Multiply another map and current map.
`divide`(other)	Divide current map with another map.
`gridding`(points[, method, coarsen])	Grid a surface from points.
`resample`(other[, mask, sampling])	Resample an instance surface values from another surface instance.
`unrotate`([factor])	Unrotete a map instance, and this will also change nrow, ncol, xinc, etc.
`refine`(factor)	Refine a surface with a factor.
`coarsen`(factor)	Coarsen a surface with a factor.
`slice_grid3d`(grid, prop[, zsurf, sbuffer])	Slice the grid property and update the instance surface to sampled values.
`slice_cube`(cube[, zsurf, sampling, mask, ...])	Slice the cube and update the instance surface to sampled cube values.
`slice_cube_window`(cube[, zsurf, other, ...])	Slice the cube within a vertical window and get the statistical attrubutes.
`get_boundary_polygons`([alpha_factor, ...])	Extract boundary polygons from the surface.
`get_fence`(xyfence[, sampling])	Sample the surface along X and Y positions (numpy arrays) and get Z.
`get_randomline`(fencespec[, hincrement, ...])	Extract a line along a fencespec.
`hc_thickness_from_3dprops`([xprop, yprop, ...])	Make a thickness weighted HC thickness map.
`avg_from_3dprop`([xprop, yprop, mprop, ...])	Average map (DZ weighted) based on numpy arrays of properties from a 3D grid.
`quickplot`([filename, title, subtitle, ...])	Fast surface plot of maps using matplotlib.
`distance_from_point`([point, azimuth])	Make map values as horizontal distance from a point with azimuth direction.
`translate_coordinates`([translate])	Translate a map in X Y VALUE space.

__init__(ncol, nrow, xinc, yinc, xori=0.0, yori=0.0, yflip=1, rotation=0.0, values=None, ilines=None, xlines=None, masked=True, name='unknown', filesrc=None, fformat=None, undef=1e+33, dtype=<class 'numpy.float64'>)[source]

Instantiating a RegularSurface:

vals = np.zeros(30 * 50)
surf = xtgeo.RegularSurface(
    ncol=30, nrow=50, xori=1234.5, yori=4321.0, xinc=30.0, yinc=50.0,
    rotation=30.0, values=vals, yflip=1,
)

Parameters:

ncol (int) – Integer for number of X direction columns.
nrow (int) – Integer for number of Y direction rows.
xori (Optional[float]) – X (East) origon coordinate.
yori (Optional[float]) – Y (North) origin coordinate.
xinc (float) – X increment.
yinc (float) – Y increment.
yflip (Optional[int]) – If 1, the map grid is left-handed (assuming depth downwards), otherwise -1 means that Y axis is flipped (right-handed).
rotation (Optional[float]) – rotation in degrees, anticlock from X axis between 0, 360.
values (Union[List[float], float, None]) – A scalar (for constant values) or a “array-like” input that has ncol * nrow elements. As result, a 2D (masked) numpy array of shape (ncol, nrow), C order will be made.
masked (Optional[bool]) – Indicating if numpy array shall be masked or not. Default is True.
name (Optional[str]) – A given name for the surface, default is file name root or ‘unknown’ if constructed from scratch.

Examples

The instance can be made by specification:

>>> surface = RegularSurface(
... ncol=20,
... nrow=10,
... xori=2000.0,
... yori=2000.0,
... rotation=0.0,
... xinc=25.0,
... yinc=25.0,
... values=np.zeros((20,10))
... )

add(other)[source]: Add another map to current map.

add_inside(poly, value)[source]: Add a value (scalar or other map) inside polygons.

add_outside(poly, value)[source]: Add a value (scalar or other map) outside polygons.

autocrop()[source]

Automatic cropping of the surface to minimize undefined areas.

This method is simply removing undefined “white areas”. The instance will be updated with new values for xori, yori, ncol, etc. Rotation will never change

Returns:: RegularSurface instance is updated in-place

Added in version 2.12.

avg_from_3dprop(xprop=None, yprop=None, mprop=None, dzprop=None, truncate_le=None, zoneprop=None, zone_minmax=None, coarsen=1, zone_avg=False)[source]

Average map (DZ weighted) based on numpy arrays of properties from a 3D grid.

The 3D arrays mush be ordinary numpies of size (nx,ny,nz). Undef entries must be given weights 0 by using DZ=0

Parameters:

xprop – 3D numpy of all X coordinates (also inactive cells)
yprop – 3D numpy of all Y coordinates (also inactive cells)
mprop – 3D numpy of requested property (e.g. porosity) all
dzprop – 3D numpy of dz values (for weighting) NB zero for undef cells
truncate_le (float) – Optional. Truncate value (mask) if value is less
zoneprop – 3D numpy to a zone property
zone_minmax – a tuple with from-to zones to combine (e.g. (1,3))

Returns:

Nothing explicit, but updates the surface object.

coarsen(factor)[source]

Coarsen a surface with a factor.

Range for coarsening is 2 to 10, where e.g. 2 meaning half the number of columns and rows.

Note that there may be some ‘loss’ of nodes at the edges of the updated map, as only the ‘inside’ nodes in the updated map versus the input map are applied.

Parameters:: factor (int) – Coarsen factor (2 .. 10)
Raises:: ValueError – Coarsen is too large, giving too few nodes in result

compare_topology(other, strict=True)[source]

Check that two object has the same topology, i.e. map definitions.

Map definitions such as origin, dimensions, number of defined cells…

Parameters:

other (RegularSurface) – The other surface to compare with
strict (bool) – If false, the masks are not compared

Return type:

bool

Returns:

True of same topology, False if not

copy()[source]

Deep copy of a RegularSurface object to another instance.

Example:

>>> mymap = xtgeo.surface_from_file(surface_dir + '/topreek_rota.gri')
>>> mymapcopy = mymap.copy()

dataframe(**kwargs)[source]: Deprecated; see method get_dataframe().

describe(flush=True)[source]: Describe an instance by printing to stdout.

property dimensions

The surface dimensions as a tuple of 2 integers (read only).

Type:: 2-tuple

distance_from_point(point=(0, 0), azimuth=0.0)[source]

Make map values as horizontal distance from a point with azimuth direction.

Parameters:

point (tuple) – Point to measure from
azimuth (float) – Angle from North (clockwise) in degrees

div_inside(poly, value)[source]: Divide a value (scalar or other map) inside polygons.

div_outside(poly, value)[source]: Divide a value (scalar or other map) outside polygons.

divide(other)[source]: Divide current map with another map.

property dtype: Getting the dtype of the values (np.array); float64 or float32

eli_inside(poly)[source]: Eliminate current map values inside polygons.

eli_outside(poly)[source]: Eliminate current map values outside polygons.

property filesrc: Gives the name of the file source (if any).

fill(fill_value=None)[source]

Fast infilling of undefined values.

Note that minimum and maximum values will not change.

Algorithm if fill_value is not set is based on a nearest node extrapolation. Technically, scipy.ndimage.distance_transform_edt is applied. If fill_value is set by a scalar, that (constant) value be be applied

Parameters:: fill_value (float) – If defined, fills all undefined cells with that value.
Returns:: RegularSurface instance is updated in-place

Added in version 2.1.

Changed in version 2.6: Added option key fill_value

generate_hash(hashmethod='md5')[source]

Return a unique hash ID for current instance.

See generic_hash() for documentation.

Added in version 2.14.

get_boundary_polygons(alpha_factor=1.0, convex=False, simplify=True)[source]

Extract boundary polygons from the surface.

A regular surface may often contain areas of undefined (masked) entries which makes the surface appear ‘ragged’ and/or ‘patchy’.

This method extracts boundaries around the surface patches, and the precision depends on the keyword settings. As default, the alpha_factor of 1 makes a precise boundary, while a larger alpha_factor makes more rough polygons.

Parameters:

alpha_factor (Optional[float]) – An alpha multiplier, where lowest allowed value is 1.0. A higher number will produce smoother and less accurate polygons. Not applied if convex is set to True.
convex (Optional[bool]) – The default is False, which means that a “concave hull” algorithm is used. If convex is True, the alpha factor is overridden to a large number, producing a ‘convex’ shape boundary instead.
simplify (Optional[bool]) – If True, a simplification is done in order to reduce the number of points in the polygons, where tolerance is 0.1. Another alternative to True is to input a Dict on the form {"tolerance": 2.0, "preserve_topology": True}, cf. the Polygons.simplify() method. For details on e.g. tolerance, see Shapely’s simplify() method.

Returns:

A XTGeo Polygons instance

Example:

surf = xtgeo.surface_from_file("mytop.gri")
# eliminate all values below a depth, e.g. a fluid contact
surf.values = np.ma.masked_greater(surf.values, 2100.0)
boundary = surf.get_boundary_polygons()
# the boundary may contain several smaller polygons; keep only the
# largest (first) polygon which is number 0:
boundary.filter_byid([0])  # polygon is updated in-place

See also

The Polygons.boundary_from_points() class method.

Added in version 3.1.

get_dataframe(ijcolumns=False, ij=False, order='C', activeonly=True, fill_value=nan)[source]

Return a Pandas dataframe object, with columns X_UTME, Y_UTMN, VALUES.

Parameters:

ijcolumns (bool) – If True, and IX and JY indices will be added as dataframe columns. Redundant, use “ij” instead.
ij (bool) – Same as ijcolumns. If True, and IX and JY indices will be added as dataframe columns. Preferred syntax
order (str) – ‘C’ (default) for C order (row fastest), or ‘F’ for Fortran order (column fastest)
activeonly (bool) – If True, only active nodes are listed. If False, the values will have fill_value default None = NaN as values
fill_value (float) – Value of inactive nodes if activeonly is False

Example:

>>> import xtgeo
>>> surf = xtgeo.surface_from_file(surface_dir + '/topreek_rota.gri')
>>> dfr = surf.get_dataframe()
>>> dfr.to_csv('somecsv.csv')

Returns:: A Pandas dataframe object.

get_fence(xyfence, sampling='bilinear')[source]

Sample the surface along X and Y positions (numpy arrays) and get Z.

Changed in version 2.14: Added keyword option sampling

Returns a masked numpy 2D array similar as input, but with updated Z values, which are masked if undefined.

Parameters:

xyfence (ndarray) – A 2D numpy array with shape (N, 3) where columns are (X, Y, Z). The Z will be updated to the map.
sampling (Optional[str]) – Use “bilinear” (default) for interpolation or “nearest” for snapping to nearest node.

Return type:

MaskedArray

get_ij_values(zero_based=False, asmasked=False, order='C')[source]

Return I J numpy 2D arrays, optionally as masked arrays.

Parameters:

zero_based (bool) – If False, first number is 1, not 0
asmasked (bool) – If True, UNDEF map nodes are skipped
order (str) – ‘C’ (default) or ‘F’ order (row vs column major)

get_ij_values1d(zero_based=False, activeonly=True, order='C')[source]

Return I J numpy as 1D arrays.

Parameters:

zero_based (bool) – If False, first number is 1, not 0
activeonly (bool) – If True, UNDEF map nodes are skipped
order (str) – ‘C’ (default) or ‘F’ order (row vs column major)

get_map_xycorners()[source]

Get the X and Y coordinates of the map corners.

Returns a tuple on the form ((x0, y0), (x1, y1), (x2, y2), (x3, y3)) where (if unrotated and normal flip) 0 is the lower left corner, 1 is the right, 2 is the upper left, 3 is the upper right.

get_nx()[source]: Same as ncol (nx) (for backward compatibility).

get_ny()[source]: Same as nrow (ny) (for backward compatibility).

get_randomline(fencespec, hincrement=None, atleast=5, nextend=2, sampling='bilinear')[source]

Extract a line along a fencespec.

Added in version 2.1.

Changed in version 2.14: Added keyword option sampling

Here, horizontal axis is “length” and vertical axis is sampled depth, and this is used for fence plots.

The input fencespec is either a 2D numpy where each row is X, Y, Z, HLEN, where X, Y are UTM coordinates, Z is depth/time, and HLEN is a length along the fence, or a Polygons instance.

If input fencspec is a numpy 2D, it is important that the HLEN array has a constant increment and ideally a sampling that is less than the map resolution. If a Polygons() instance, this is automated if hincrement is None, and ignored if hincrement is False.

Returns a ndarray with shape (:, 2).

Parameters:

fencespec (Union[ndarray, object]) – 2D numpy with X, Y, Z, HLEN as rows or a xtgeo Polygons() object.
hincrement (Union[bool, float, None]) – Resampling horizontally. This applies only if the fencespec is a Polygons() instance. If None (default), the distance will be deduced automatically. If False, then it assumes the Polygons can be used as-is.
atleast (Optional[int]) – Minimum number of horizontal samples (only if fencespec is a Polygons instance and hincrement != False)
nextend (Optional[int]) – Extend with nextend * hincrement in both ends (only if fencespec is a Polygons instance and hincrement != False)
sampling (Optional[str]) – Use “bilinear” (default) for interpolation or “nearest” for snapping to nearest node.

Return type:

ndarray

Example:

fence = xtgeo.polygons_from_file("somefile.pol")
fspec = fence.get_fence(distance=20, nextend=5, asnumpy=True)
surf = xtgeo.surface_from_file("somefile.gri")

arr = surf.get_randomline(fspec)

distance = arr[:, 0]
zval = arr[:, 1]
# matplotlib...
plt.plot(distance, zval)

See also

Class Polygons: The method get_fence() which can be used to pregenerate fencespec

get_rotation()[source]: Returns the surface roation, in degrees, from X, anti-clock.

get_value_from_xy(point=(0.0, 0.0), sampling='bilinear')[source]

Return the map value given a X Y point.

Parameters:

point (float tuple) – Position of X and Y coordinate
sampling (str) – Sampling method, either “bilinear” for bilinear interpolation, or “nearest” for nearest node sampling (e.g. facies maps)

Returns:

The map value (interpolated). None if XY is outside defined map

Example::: mvalue = map.get_value_from_xy(point=(539291.12, 6788228.2))

Changed in version 2.14: Added keyword option sampling

get_values1d(order='C', asmasked=False, fill_value=1e+33, activeonly=False)[source]

Get a 1D numpy or masked array of the map values.

Parameters:

order (str) – Flatteting is in C (default) or F order
asmasked (bool) – If true, return as MaskedArray, other as standard numpy ndarray with undef as np.nan or fill_value
fill_value (str) – Relevent only if asmasked is False, this will be the value of undef entries
activeonly (bool) – If True, only active cells. Keys ‘asmasked’ and ‘fill_value’ are not revelant.

Returns:

A numpy 1D array or MaskedArray

get_xinc()[source]: Same as property xinc (for backward compatibility).

get_xori()[source]: Same as property xori (for backward compatibility).

get_xy_value_from_ij(iloc, jloc, zvalues=None)[source]

Returns x, y, z(value) from a single i j location.

Parameters:

iloc (int) – I (col) location (base is 1)
jloc (int) – J (row) location (base is 1)
zvalues (ndarray) – to precompute the numpy surface once in the caller, and submit the numpy array (use surf.get_values1d()).

Returns:

The x, y, z values at location iloc, jloc

get_xy_value_lists(lformat='webportal', xyfmt=None, valuefmt=None)[source]

Returns two lists for coordinates (x, y) and values.

For lformat = ‘webportal’ (default):

The lists are returned as xylist and valuelist, where xylist is on the format:

[(x1, y1), (x2, y2) …] (a list of x, y tuples)

and valuelist is one the format

[v1, v2, …]

Inactive cells will be ignored.

Parameters:

lformat (string) – List return format (‘webportal’ is default, other options later)
xyfmt (string) – The formatter for xy numbers, e.g. ‘12.2f’ (default None). Note no checks on valid input.
valuefmt (string) – The formatter for values e.g. ‘8.4f’ (default None). Note no checks on valid input.

Returns:

xylist, valuelist

Example

>>> import xtgeo
>>> surf = xtgeo.surface_from_file(surface_dir + '/topreek_rota.gri')
>>> xylist, valuelist = surf.get_xy_value_lists(valuefmt='6.2f')

get_xy_values(order='C', asmasked=True)[source]

Return coordinates for X and Y as numpy (masked) 2D arrays.

Parameters:

order (str) – ‘C’ (default) or ‘F’ order (row major vs column major)
asmasked (bool) – If True , inactive nodes are masked.

get_xy_values1d(order='C', activeonly=True)[source]

Return coordinates for X and Y as numpy 1D arrays.

Parameters:

order (str) – ‘C’ (default) or ‘F’ order (row major vs column major)
activeonly (bool) – Only active cells are returned.

get_xyz_values()[source]: Return coordinates for X Y and Z (values) as numpy (masked) 2D arrays.

get_xyz_values1d(order='C', activeonly=True, fill_value=nan)[source]

Return coordinates for X Y and Z (values) as numpy 1D arrays.

Parameters:

order (str) – ‘C’ (default) or ‘F’ order (row major vs column major)
activeonly (bool) – Only active cells are returned.
fill_value (float) – If activeonly is False, value of inactive nodes

get_yinc()[source]: Same as property yinc (for backward compatibility).

get_yori()[source]: Same as property yori (for backward compatibility).

gridding(points, method='linear', coarsen=1)[source]

Grid a surface from points.

Parameters:

points (Points) – XTGeo Points instance.
method (str) – Gridding method option: linear / cubic / nearest
coarsen (int) – Coarsen factor, to speed up gridding, but will give poorer result.

Example:

>>> import xtgeo
>>> mypoints = xtgeo.Points(points_dir + '/pointset2.poi')
>>> mysurf = xtgeo.surface_from_file(surface_dir + '/topreek_rota.gri')

>>> # update the surface by gridding the points
>>> mysurf.gridding(mypoints)

Raises:

RuntimeError – If not possible to grid for some reason
ValueError – If invalid input

hc_thickness_from_3dprops(xprop=None, yprop=None, hcpfzprop=None, zoneprop=None, zone_minmax=None, dzprop=None, zone_avg=False, coarsen=1, mask_outside=False)[source]

Make a thickness weighted HC thickness map.

Make a HC thickness map based on numpy arrays of properties from a 3D grid. The numpy arrays here shall be ndarray, not masked numpies (MaskedArray).

Note that the input hcpfzprop is hydrocarbon fraction multiplied with thickness, which can be achieved by e.g.: cpfz = dz*poro*ntg*shc or by hcpfz = dz*hcpv/vbulk

Parameters:

xprop (ndarray) – 3D numpy array of X coordinates
yprop (ndarray) – 3D numpy array of Y coordinates
hcpfzprop (ndarray) – 3D numpy array of HC fraction multiplied with DZ per cell.
zoneprop (ndarray) – 3D numpy array indicating zonation property, where 1 is the lowest (0 values can be used to exclude parts of the grid)
dzprop (ndarray) – 3D numpy array holding DZ thickness. Will be applied in weighting if zone_avg is active.
zone_minmax (tuple) – (optional) 2 element list indicating start and stop zonation (both start and end spec are included)
zone_avg (bool) – A zone averaging is done prior to map gridding. This may speed up the process a lot, but result will be less precise. Default is False.
coarsen (int) – Select every N’th X Y point in the gridding. Will speed up process, but less precise result. Default=1
mask_outside (bool) – Will mask the result map undef where sum of DZ is zero. Default is False as it costs some extra CPU.

Returns:

True if operation went OK (but check result!), False if not

property ilines: The inlines numbering vector (read only).

load_values()[source]

Import surface values in cases where metadata only is loaded.

Currently, only Irap binary format is supported.

Example:

surfs = []
for i in range(1000):
    surfs.append(xtgeo.surface_from_file(f"myfile{i}.gri", values=False))

# load values in number 88:
surfs[88].load_values()

Added in version 2.1.

make_lefthanded()[source]

Makes the surface lefthanded in case yflip is -1. This will change origin.

Lefthanded regular maps are common in subsurface data, where I is to east, J is to north and Z axis is positive down for depth and time data.

The instance is changed in-place. The method is a no-op if yflip already is 1. :rtype: None

Added in version 4.2.

make_righthanded()[source]

Makes the surface righthanded in case yflip is 1. This will change origin.

Righthanded regular maps are less common in subsurface data, where I is to east, J is to north and Z axis is positive down for depth and time data. This method is mainly for consistency since make_lefthanded() is present.

The instance is changed in-place. The method is a no-op if yflip already is -1. :rtype: None

Added in version 4.5.

property metadata: Return metadata object instance of type MetaDataRegularSurface.

classmethod methods()[source]

Returns the names of the methods in the class.

>>> print(RegularSurface.methods())
METHODS for RegularSurface():
======================
__init__
__repr__
...

mul_inside(poly, value)[source]: Multiply a value (scalar or other map) inside polygons.

mul_outside(poly, value)[source]: Multiply a value (scalar or other map) outside polygons.

multiply(other)[source]: Multiply another map and current map.

property nactive: Number of active map nodes (read only).

property name: A free form name for the surface, to be used in display etc.

property ncol: The NCOL (NX or N-Idir) number, as property (read only).

property npvalues1d

(Read only) Map values, as 1D numpy (not masked), undef as np.nan.

In most cases this will be a copy of the values.

Example:

>>> import xtgeo
>>> map = xtgeo.surface_from_file(surface_dir + '/topreek_rota.gri')
>>> values = map.npvalues1d
>>> mean = np.nanmean(values)
>>> values[values <= 0] = np.nan
>>> print(values)
[nan nan ... nan]

property nrow: The NROW (NY or N-Jdir) number, as property (read only).

operation(opname, value)[source]

Do operation on map values.

Do operations on the current map values. Valid operations are:

‘elilt’ or ‘eliminatelessthan’: Eliminate less than <value>
‘elile’ or ‘eliminatelessequal’: Eliminate less or equal than <value>

Parameters:

opname (str) – Name of operation. See list above.
value – A scalar number (float) or a tuple of two floats, dependent on operation opname.

Examples:

surf.operation('elilt', 200)  # set all values < 200 as undef

operation_polygons(poly, value, opname='add', inside=True, _version=2)[source]

A generic function for map operations inside or outside polygon(s).

Parameters:

poly (Polygons) – A XTGeo Polygons instance
value (float or RegularSurface) – Value to add, subtract etc
opname (str) – Name of operation… ‘add’, ‘sub’, etc
inside (bool) – If True do operation inside polygons; else outside.
_version (int) – Algorithm version, 2 will be much faster when many points on polygons (this key will be removed in later versions and shall not be applied)

quickplot(filename=None, title='QuickPlot for Surfaces', subtitle=None, infotext=None, minmax=(None, None), xlabelrotation=None, colormap='rainbow', faults=None, logarithmic=False)[source]

Fast surface plot of maps using matplotlib.

Parameters:

filename (str) – Name of plot file; None will plot to screen.
title (str) – Title of plot
subtitle (str) – Subtitle of plot
infotext (str) – Additonal info on plot.
minmax (tuple) – Tuple of min and max values to be plotted. Note that values outside range will be set equal to range limits
xlabelrotation (float) – Rotation in degrees of X labels.
colormap (str) – Name of matplotlib or RMS file or XTGeo colormap. Default is matplotlib’s ‘rainbow’
faults (dict) – If fault plot is wanted, a dictionary on the form => {‘faults’: XTGeo Polygons object, ‘color’: ‘k’}
logarithmic (bool) – If True, a logarithmic contouring color scale will be used.

refine(factor)[source]

Refine a surface with a factor.

Range for factor is 2 to 10.

Note that there may be some ‘loss’ of nodes at the edges of the updated map, as only the ‘inside’ nodes in the updated map versus the input map are applied.

Parameters:: factor (int) – Refinement factor

resample(other, mask=True, sampling='bilinear')[source]

Resample an instance surface values from another surface instance.

Note that there may be some ‘loss’ of nodes at the edges of the updated map, as only the ‘inside’ nodes in the updated map versus the input map are applied.

The interpolation algorithm in resample is bilinear interpolation. The topolopogy of the surface (map definitions, rotation, …) will not change, only the map values. Areas with undefined nodes in other will become undefined in the instance if mask is True; othewise they will be kept as is.

Parameters:

other (RegularSurface) – Surface to resample from.
mask (bool) – If True (default) nodes outside will be made undefined, if False then values will be kept as original
sampling (str) – Either ‘bilinear’ interpolation (default) or, ‘nearest’ for nearest node. The latter can be useful for resampling discrete maps.

Example:

# map with 230x210 columns, rotation 20
surf1 = xtgeo.surface_from_file("some1.gri")
# map with 270x190 columns, rotation 0
surf2 = xtgeo.surface_from_file("some2.gri")
# will sample (interpolate) surf2's values to surf1
surf1.resample(surf2)

Returns:: Instance’s surface values will be updated in-place.

Changed in version 2.9: Added mask keyword, default is True for backward compatibility.

Changed in version 2.21: Added sampling keyword option.

property rotation: The rotation, anticlock from X axis, in degrees [0..360>.

set_inside(poly, value)[source]: Set a value (scalar or other map) inside polygons.

set_outside(poly, value)[source]: Set a value (scalar or other map) outside polygons.

set_values1d(val, order='C')[source]

Update the values attribute based on a 1D input, multiple options.

If values are np.nan or values are > UNDEF_LIMIT, they will be masked.

Parameters:

val (list-like) – Set values as a 1D array
order (str) – Input is C (default) or F order

similarity_index(other)[source]

Report the degree of similarity between two maps, by comparing mean.

The method computes the average per surface, and the similarity is difference in mean divided on mean of self. I.e. values close to 0.0 mean small difference.

Parameters:: other (surface object) – The other surface to compare with

slice_cube(cube, zsurf=None, sampling='nearest', mask=True, snapxy=False, deadtraces=True, algorithm=2)[source]

Slice the cube and update the instance surface to sampled cube values.

Parameters:

cube (object) – Instance of a Cube()
zsurf (surface object) – Instance of a depth (or time) map, which is the depth or time map (or…) that is used a slicer. If None, then the surface instance itself is used a slice criteria. Note that zsurf must have same map defs as the surface instance.
sampling (str) – ‘nearest’ for nearest node (default), or ‘trilinear’ for trilinear interpolation.
mask (bool) – If True (default), then the map values outside the cube will be undef. Otherwise, map will be kept as is.
snapxy (bool) – If True (optional), then the map values will get values at nearest Cube XY location. Only relevant to use if surface is derived from seismic coordinates (e.g. Auto4D).
deadtraces (bool) – If True (default) then dead cube traces (given as value 2 in SEGY trace headers), are treated as undefined, and map will become undefined at dead trace location.
algorithm (int) – 1 for legacy method, 2 (default from 2.9) for new method available in xtgeo from version 2.9

Example:

>>> import xtgeo
>>> cube = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")
>>> surf = xtgeo.surface_from_file(surface_dir + '/topreek_rota.gri')
>>> # update surf to sample cube values:
>>> surf.slice_cube(cube)

Raises:

Exception if maps have different definitions (topology) –
RuntimeWarning if number of sampled nodes is less than 10% –

Changed in version 2.9: Added algorithm keyword, default is 2

slice_cube_window(cube, zsurf=None, other=None, other_position='below', sampling='nearest', mask=True, zrange=None, ndiv=None, attribute='max', maskthreshold=0.1, snapxy=False, showprogress=False, deadtraces=True, algorithm=2)[source]

Slice the cube within a vertical window and get the statistical attrubutes.

The statistical attributes can be min, max etc. Attributes are:

‘max’ for maximum
‘min’ for minimum
‘rms’ for root mean square
‘mean’ for expected value
‘var’ for variance (population var; https://en.wikipedia.org/wiki/Variance)
‘maxpos’ for maximum of positive values
‘maxneg’ for negative maximum of negative values
‘maxabs’ for maximum of absolute values
‘sumpos’ for sum of positive values using cube sampling resolution
‘sumneg’ for sum of negative values using cube sampling resolution
‘meanabs’ for mean of absolute values
‘meanpos’ for mean of positive values
‘meanneg’ for mean of negative values

Note that ‘all’ can be used to select all attributes that are currently available.

Parameters:

cube – Instance of a Cube() here
zsurf – Instance of a depth (or time) map, which is the depth or time map (or…) that is used a slicer. If None, then the surface instance itself is used a slice criteria. Note that zsurf must have same map defs as the surface instance.
other – Instance of other surface if window is between surfaces instead of a static window. The zrange input is then not applied.
sampling – ‘nearest’/’trilinear’/’cube’ for nearest node (default), or ‘trilinear’ for trilinear interpolation. The ‘cube’ option is only available with algorithm = 2 and will overrule ndiv and sample at the cube’s Z increment resolution.
mask – If True (default), then the map values outside the cube will be undef, otherwise map will be kept as-is
zrange – The one-sided “radius” range of the window, e.g. 10 (10 is default) units (e.g. meters if in depth mode). The full window is +- zrange (i.e. diameter). If other surface is present, zrange is computed based on those two surfaces instead.
ndiv – Number of intervals for sampling within zrange. None means ‘auto’ sampling, using 0.5 of cube Z increment as basis. If algorithm = 2/3 and sampling is ‘cube’, the cube Z increment will be used.
attribute – The requested attribute(s), e.g. ‘max’ value. May also be a list of attributes, e.g. [‘min’, ‘rms’, ‘max’]. By such, a dict of surface objects is returned. Note ‘all’ will make a list of all possible attributes.
maskthreshold (float) – Only if two surface; if isochore is less than given value, the result will be masked.
snapxy – If True (optional), then the map values will get values at nearest Cube XY location, and the resulting surfaces layout map will be defined by the seismic layout. Quite relevant to use if surface is derived from seismic coordinates (e.g. Auto4D), but can be useful in other cases also, as long as one notes that map definition may change from input.
showprogress – If True, then a progress is printed to stdout.
deadtraces – If True (default) then dead cube traces (given as value 2 in SEGY trace headers), are treated as undefined, and map will be undefined at dead trace location.
algorithm – 1 for legacy method, 2 (default) for new faster and more precise method available from xtgeo version 2.9, and algorithm 3 as new implementation from Sept. 2023 (v3.4)

Example:

>>> import xtgeo
>>> cube = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")
>>> surf = xtgeo.surface_from_file(surface_dir + '/topreek_rota.gri')
>>> # update surf to sample cube values in a total range of 30 m:
>>> surf.slice_cube_window(cube, attribute='min', zrange=15.0)

>>> # Here a list is given instead:
>>> alst = ['min', 'max', 'rms']

>>> myattrs = surf.slice_cube_window(cube, attribute=alst, zrange=15.0)
>>> for attr in myattrs.keys():
...     _ = myattrs[attr].to_file(
...         outdir + '/myfile_' + attr + '.gri'
...     )

Raises:

Exception if maps have different definitions (topology) –
ValueError if attribute is invalid. –

Returns:

If attribute is a string, then the instance is updated and None is returned. If attribute is a list, then a dictionary of surface objects is returned.

Note

This method is now deprecated and will be removed in xtgeo version 5. Please replace with Cube().compute_attributes_in_window() as soon as possible.

Changed in version 2.9: Added algorithm keyword, default is now 2, while 1 is the legacy version

Changed in version 3.4: Added algorithm 3 which is more robust and hence recommended!

Changed in version 4.1: Flagged as deprecated.

slice_grid3d(grid, prop, zsurf=None, sbuffer=1)[source]

Slice the grid property and update the instance surface to sampled values.

Parameters:

grid (Grid) – Instance of a Grid.
prop (GridProperty) – Instance of a GridProperty, belongs to grid
zsurf (surface object) – Instance of map, which is used a slicer. If None, then the surface instance itself is used a slice criteria. Note that zsurf must have same map defs as the surface instance.
sbuffer (int) – Default is 1; if “holes” after sampling extend this to e.g. 3

Example:

>>> import xtgeo
>>> grd = xtgeo.grid_from_file(reek_dir + '/REEK.EGRID')
>>> prop = xtgeo.gridproperty_from_file(
...     reek_dir + '/REEK.UNRST',
...     name='PRESSURE',
...     date="first",
...     grid=grd,
... )
>>> surf = xtgeo.surface_from_file(surface_dir + '/topreek_rota.gri')
>>> # update surf to sample the 3D grid property:
>>> surf.slice_grid3d(grd, prop)

Raises:: Exception if maps have different definitions (topology) –

smooth(method='median', iterations=1, width=1)[source]

Various smoothing methods for surfaces.

Parameters:

method (Literal['median', 'gaussian']) – Smoothing method (median or gaussian)
iterations (int) – Number of iterations
width (float) –
- If method is ‘median’ range of influence is in nodes.
- If method is ‘gaussian’ range of influence is standard deviation of the Gaussian kernel.

Return type:

None

Added in version 2.1.

sub_inside(poly, value)[source]: Subtract a value (scalar or other map) inside polygons.

sub_outside(poly, value)[source]: Subtract a value (scalar or other map) outside polygons.

subtract(other)[source]: Subtract another map from current map.

swapaxes()[source]: Swap (flip) the axes columns vs rows, keep origin but reverse yflip.

to_file(mfile, fformat='irap_binary', pmd_dataunits=(15, 10), engine=None, error_if_near_empty=False)[source]

Export a surface (map) to file.

Note, for zmap_ascii and storm_binary an unrotation will be done automatically. The sampling will be somewhat finer than the original map in order to prevent aliasing. See unrotate().

Parameters:

mfile (Union[str, Path, BytesIO]) – Name of file, Path instance or IOBytestream instance. An alias can be e.g. “%md5sum%” or “%fmu-v1%” with string or Path() input.
fformat (Optional[str]) – File format, irap_binary/irap_ascii/zmap_ascii/ storm_binary/ijxyz/petromod/xtg*. Default is irap_binary.
pmd_dataunits (Optional[Tuple[int, int]]) – A tuple of length 2 for petromod format, spesifying metadata for units (DataUnitDistance, DataUnitZ).
engine (Optional[str]) – This was mainly a developer setting! The ‘engine’ is now deprecated.
error_if_near_empty (bool) – Default is False. If True, raise a RuntimeError if number of map nodes is less than 4. Otherwise, if False and number of nodes are less than 4, a UserWarning will be given.

Returns:

The actual file instance, or None if io.Bytestream

Return type:

ofile (pathlib.Path)

Examples:

>>> # read and write to ordinary file
>>> surf = xtgeo.surface_from_file(
...     surface_dir + '/topreek_rota.fgr',
...     fformat = 'irap_ascii'
... )
>>> surf.values = surf.values + 300
>>> filename = surf.to_file(
...     outdir + '/topreek_rota300.fgr',
...     fformat = 'irap_ascii'
... )

>>> # writing to io.BytesIO:
>>> stream = io.BytesIO()
>>> surf.to_file(stream, fformat="irap_binary")

>>> # read from memory stream:
>>> _ = stream.seek(0)
>>> newsurf = xtgeo.surface_from_file(stream, fformat = 'irap_binary')

Changed in version 2.5: Added support for BytesIO

Changed in version 2.13: Improved support for BytesIO

Changed in version 2.14: Support for alias file name and return value

Changed in version 3.8: Add key error_if_near_empty

Changed in version 4.6: The engine keyword (for developers) is deprecated and will be removed in version 5

to_hdf(mfile, compression='lzf')[source]

Export a surface (map) with metadata to a HDF5 file.

Warning

This implementation is currently experimental and only recommended for testing.

The file extension shall be ‘.hdf’

Parameters:

mfile (Union[str, Path, BytesIO]) – Name of file, Path instance or BytesIO instance. An alias can be e.g. $md5sum.hdf, $fmu-v1.hdf with string or Path() input.
compression (Optional[str]) – Compression method, None, lzf (default), blosc

Returns:

The actual file instance, or None if io.Bytestream

Return type:

pathlib.Path

Example

>>> import xtgeo
>>> surf = xtgeo.surface_from_file(surface_dir + '/topreek_rota.gri')
>>> filepath = surf.to_hdf(outdir + "/topreek_rota.hdf")

Added in version 2.14.

to_roxar(project, name, category, stype='horizons', realisation=0)[source]

Store (export) a regular surface to a Roxar RMS project.

The export to the RMS project can be done either within the project or outside the project. The storing is done to the Horizons or the Zones folder in RMS.

Note

The horizon or zone name and category must exists in advance, otherwise an Exception will be raised.

When project is file path (direct access, outside RMS) then to_roxar() will implicitly do a project save. Otherwise, the project will not be saved until the user do an explicit project save action.

Parameters:

project (str or special) – Name of project (as folder) if outside RMS, og just use the magic project word if within RMS.
name (str) – Name of surface/map
category (str) – Required for horizons/zones: e.g. ‘DS_extracted’. For clipboard/general2d_data is reperesent the folder(s), where “” or None means no folder, while e.g. “myfolder/subfolder” means that folders myfolder/subfolder will be created if not already present. For stype = ‘trends’, the category will not be applied
stype (str) – RMS folder type, ‘horizons’ (default), ‘zones’, ‘clipboard’ ‘general2d_data’, ‘trends’
realisation (int) – Realisation number, default is 0

Raises:

ValueError – If name or category does not exist in the project

Example

Here the from_roxar method is used to initiate the object directly:

import xtgeo
topupperreek = xtgeo.surface_from_roxar(project, 'TopUpperReek',
                                      'DS_extracted')
topupperreek.values += 200

# export to file:
topupperreek.to_file('topupperreek.gri')

# store in project
topupperreek.to_roxar(project, 'TopUpperReek', 'DS_something')

Note:

When dealing with surfaces to and from ``stype="trends"``, the surface must
exist in advance, i.e. the Roxar API do not allow creating new surfaces.
Actually trends are read only, but a workaround using ``load()`` in Roxar
API makes it possible to overwrite existing surface trends. In addition,
``realisation`` is not applied in trends.

Added in version 2.1: clipboard support

Added in version 2.19: general2d_data and trends support

translate_coordinates(translate=(0, 0, 0))[source]

Translate a map in X Y VALUE space.

Parameters:: translate (tuple) – Translate (shift) distance in X Y Z

Example:

>>> import xtgeo
>>> mysurf = xtgeo.surface_from_file(surface_dir + '/topreek_rota.gri')
>>> print(mysurf.xori, mysurf.yori)
468895.125 5932889.5
>>> mysurf.translate_coordinates((300,500,0))
>>> print(mysurf.xori, mysurf.yori)
469195.125 5933389.5

property undef: Returns the undef map value (read only).

property undef_limit: Returns the undef_limit map value (read only).

unrotate(factor=2)[source]

Unrotete a map instance, and this will also change nrow, ncol, xinc, etc.

The default sampling (factor=2) makes a finer grid in order to avoid artifacts, and this default can be used in most cases.

If an even finer grid is wanted, increase the factor. Theoretically the new increment for factor=N is between $\\frac{1}{N}$ and $\\frac{1}{N}\\sqrt{2}$ of the original increment, dependent on the rotation of the original surface.

If the current instance already is unrotated, nothing is done.

Parameters:: factor (int) – Refinement factor (>= 1)

property values

The map values, as 2D masked numpy (float64/32), shape (ncol, nrow).

When setting values as a scalar, the current mask will be preserved.

When setting values, list-like input (lists, tuples) is also accepted, as long as the length is correct and the entries are number-like.

In order to specify undefined values, you can specify the undef attribute in the list, or use float("nan").

Example:

# list like input where nrow=3 and ncol=5 (15 entries)
newvalues = list(range(15))
newvalues[2] = srf.undef
srf.values = newvalues  # here, entry 2 will be undefined

property values1d

(Read only) Map values, as 1D numpy masked, normally a numpy view(?).

Example:

map = xtgeo.surface_from_file('myfile.gri')
map.values1d

property xinc: The X increment (or I dir increment).

property xlines: The xlines numbering vector (read only).

property xmax: The maximum X coordinate (read only).

property xmin: The minimim X coordinate (read only).

property xori: The X coordinate origin of the map.

property yflip

The Y flip (handedness) indicator 1, or -1 (read only).

The value 1 (default) means a left-handed system if depth values are positive downwards. Assume -1 is rare, but may happen when surface is derived from seismic cube.

property yinc: The Y increment (or I dir increment).

property ymax: The maximum Y xoordinate (read only).

property ymin: The minimim Y coordinate (read only).

property yori: The Y coordinate origin of the map.

Surfaces

Classes

class xtgeo.Surfaces(surfaces=None, subtype=None, order=None)[source]

Bases: object

Class for a collection of Surface objects, for operations that involves a number of surfaces, such as statistical numbers.

A collection of surfaces can be different things:

A list if surfaces in stratigraphic order
A collection of different realisations of the same surface
A collection of isochores

Parameters:

input (list, optional) – A list of XTGeo objects and/or file names)
subtype (str) – “tops”, “isochores”, or None (default)
order (str) – Assummed order: “same”, “stratigraphic”, None(default)

See also

Class RegularSurface class.

Added in version 2.1.

Public Data Attributes:

surfaces

Get or set a list of individual surfaces

Public Methods:

`append`(input)	Append surface(s) from a RegularSurface or a list of objects or files.
`describe`([flush])	Describe an instance by printing to stdout
`copy`()	Copy a Surfaces instance to a new unique instance (a deep copy).
`get_surface`(name)	Get a RegularSurface() instance by name, or return None if name not found
`apply`(func, args, *kwargs)	Apply a function to the Surfaces array.
`statistics`([percentiles])	Return statistical measures from the surfaces.
`is_depth_consistent`()	Check that surfaces are depth consistent, i.e. not crossing each other.
`make_depth_consistent`([inplace])	Make surfaces depth consistent, i.e. not crossing each other.

__init__(surfaces=None, subtype=None, order=None)[source]

append(input)[source]

Append surface(s) from a RegularSurface or a list of objects or files.

Parameters:: input (list[RegularSurface] | list[str] | RegularSurface) – A single RegularSurface, or list of RegularSurface objects and/or file names.
Return type:: None

apply(func, *args, **kwargs)[source]

Apply a function to the Surfaces array.

The return value of the function (numpy nan comptatible) will be a numpy array of the same shape as the first surface.

E.g. surfs.apply(np.nanmean, axis=0) will return the mean surface.

Parameters:

func – Function to apply, e.g. np.nanmean
args – The function arguments
kwargs – The function keyword arguments

Raises:

ValueError – If surfaces differ in topology.

copy()[source]: Copy a Surfaces instance to a new unique instance (a deep copy).

describe(flush=True)[source]: Describe an instance by printing to stdout

get_surface(name)[source]: Get a RegularSurface() instance by name, or return None if name not found

is_depth_consistent()[source]

Check that surfaces are depth consistent, i.e. not crossing each other.

Return type:: bool

make_depth_consistent(inplace=True)[source]

Make surfaces depth consistent, i.e. not crossing each other.

The algorithm is starting with top surface and iteratively adjust the surface below to be consistent with the previous surface.

Parameters:: inplace (bool) – If True (default), the object is changed in-place, if False, a new object is returned.
Return type:: Surfaces | None

statistics(percentiles=None)[source]

Return statistical measures from the surfaces.

The statistics returned is: * mean: the arithmetic mean surface * std: the standard deviation surface (where ddof = 1) * percentiles: on demand (such operations may be slow)

Currently this function expects that the surfaces all have the same shape/topology.

Parameters:: percentiles (list of float) – If defined, a list of perecentiles to evaluate e.g. [10, 50, 90] for p10, p50, p90
Returns:: A dictionary of statistical measures, see list above
Return type:: dict
Raises:: ValueError – If surfaces differ in topology.

Example:

surfs = Surfaces(mylist)  # mylist is a collection of files
stats = surfs.statistics()
# export the mean surface
stats["mean"].to_file("mymean.gri")

Changed in version 2.13: Added percentile

property surfaces: Get or set a list of individual surfaces

Points and Polygons

Points

Functions

xtgeo.points_from_file(pfile, fformat='guess')[source]

Make an instance of a Points object directly from file import.

Supported formats are:

‘xyz’ or ‘poi’ or ‘pol’: Simple XYZ format

‘zmap’: ZMAP line format as exported from RMS (e.g. fault lines)

‘rms_attr’: RMS points formats with attributes (extra columns)

‘guess’: Try to choose file format based on extension

Parameters:

pfile (str | Path) – Name of file or pathlib object.
fformat (str | None) – File format, xyz/pol/… Default is guess where file extension or file signature is parsed to guess the correct format.

Example:

import xtgeo
mypoints = xtgeo.points_from_file('somefile.xyz')

xtgeo.points_from_roxar(project, name, category, stype='horizons', realisation=0, attributes=False)[source]

Load a Points instance from Roxar RMS project.

The import from the RMS project can be done either within the project or outside the project.

Note also that horizon/zone/faults name and category must exists in advance, otherwise an Exception will be raised.

Parameters:

project – Name of project (as folder) if outside RMS, or just use the magic project word if within RMS.
name (str) – Name of points item, or name of well pick set if well picks.
category (str) – For horizons/zones/faults: for example ‘DL_depth’ or use a folder notation on clipboard/general2d_data. For well picks it is the well pick type: ‘horizon’ or ‘fault’.
stype (str) – RMS folder type, ‘horizons’ (default), ‘zones’, ‘clipboard’, ‘general2d_data’, ‘faults’ or ‘well_picks’
realisation (int) – Realisation number, default is 0
attributes (bool) – Bool or list with attribute names to collect. If True, all attributes are collected.

Example:

# inside RMS:
import xtgeo
mypoints = xtgeo.points_from_roxar(project, 'TopEtive', 'DP_seismic')

Added in version 2.19: general2d_data support is added

xtgeo.points_from_surface(regular_surface, zname='Z_TVDSS')[source]

This makes an instance of a Points directly from a RegularSurface object.

Each surface node will be stored as a X Y Z point.

Parameters:

regular_surface – XTGeo RegularSurface() instance
zname (str) – Name of third column

Added in version 2.16: Replaces the from_surface() method.

xtgeo.points_from_wells(wells, tops=True, incl_limit=None, top_prefix='Top', zonelist=None, use_undef=False)[source]

Get tops or zone points data from a list of wells.

Parameters:

wells (list[Well]) – List of XTGeo well objects. If a list of well files, the routine will try to load well based on file signature and/or extension, but only default settings are applied. Hence this is less flexible and more fragile.
tops (bool) – Get the tops if True (default), otherwise zone.
incl_limit (float | None) – Inclination limit for zones (thickness points)
top_prefix (str) – Prefix used for Tops.
zonelist (list | None) – Which zone numbers to apply, None means all.
use_undef (bool) – If True, then transition from UNDEF is also used.

Returns:

None if empty data, otherwise a Points() instance.

Example:

wells = [xtgeo.well_from_file("w1.w"), xtgeo.well_from_file("w2.w")]
points = xtgeo.points_from_wells(wells)

xtgeo.points_from_wells_dfrac(wells, dlogname, dcodes, incl_limit=90, count_limit=3, zonelist=None, zonelogname=None)[source]

Get fraction of discrete code(s) e.g. facies per zone.

Parameters:

wells (list[Well]) – List of XTGeo well objects. If a list of file names, the routine will try to load well based on file signature and/or extension, but only default settings are applied. Hence this is less flexible and more fragile.
dlogname (str) – Name of discrete log (e.g. Facies)
dcodes (list[int]) – Code(s) to get fraction for, e.g. [3]
incl_limit (float) – Inclination limit for zones (thickness points)
count_limit (int) – Min. no of counts per segment for valid result
zonelist (list | None) – Which zone numbers to apply, default None means all.
zonelogname (str | None) – If None, the zonelogname property in the well object will be applied. This option is particualr useful if one uses wells directly from files.

Returns:

None if empty data, otherwise a Points() instance.

Example:

wells = [xtgeo.well_from_file("w1.w"), xtgeo.well_from_file("w2.w")]
points = xtgeo.points_from_wells_dfrac(
        wells, dlogname="Facies", dcodes=[4], zonelogname="ZONELOG"
    )

Classes

class xtgeo.Points(values=None, xname='X_UTME', yname='Y_UTMN', zname='Z_TVDSS', attributes=None, filesrc=None)[source]

Bases: XYZ

Class for Points data in XTGeo.

The Points class is a subclass of the XYZ abstract class, and the point set itself is a pandas dataframe object.

For points, 3 float columns (X Y Z) are mandatory. In addition it is possible to have addiotional points attribute columns, and such attributes may be integer, strings or floats.

The instance can be made either from file (then as classmethod), from another object or by a spesification, e.g. from file or a surface:

xp1 = xtgeo.points_from_file('somefilename', fformat='xyz')
# or
regsurf = xtgeo.surface_from_file("somefile.gri")
xp2 = xtgeo.points_from_surface(regsurf)

You can also initialise points from list of tuples/lists in Python, where each tuple is a (X, Y, Z) coordinate:

plist = [(234, 556, 12), (235, 559, 14), (255, 577, 12)]
mypoints = Points(values=plist)

The tuples can also contain point attributes which needs spesification via an attributes dictionary:

plist = [
    (234, 556, 12, "Well1", 22),
    (235, 559, 14, "Well2", 44),
    (255, 577, 12, "Well3", 55)]
attrs = {"WellName": "str", "ID": "int"}
mypoints = Points(values=plist, attributes=attrs)

And points can be initialised from a 2D numpy array or an existing dataframe:

>>> mypoints1 = Points(values=[(1,1,1), (2,2,2), (3,3,3)])
>>> mypoints2 = Points(
...     values=pd.DataFrame(
...          [[1, 2, 3], [1, 2, 3], [1, 2, 3]],
...          columns=["X_UTME", "Y_UTMN", "Z_TVDSS"]
...     )
... )

Similar as for lists, attributes are alse possible for numpy and dataframes.

Default column names in the dataframe:

X_UTME: UTM X coordinate as self._xname
Y_UTMN: UTM Y coordinate as self._yname
Z_TVDSS: Z coordinate, often depth below TVD SS, but may also be something else! Use zname attribute to change name.

Note

Attributes may have undefined entries. Pandas version 0.21 (which is applied for RMS version up to 12.0.x) do not support NaN values for Integers. The solution is store undefined values as large numbers, xtgeo.UNDEF_INT (2000000000) for integers and xtgeo.UNDEF (10e32) for float values. This will change from xtgeo version 3.x where Pandas version 1 and above will be required, which in turn support will pandas.NA entries.

Parameters:

values (list | ndarray | DataFrame) – Provide input values on various forms (list-like or dataframe).
xname (str) – Name of first (X) mandatory column
yname (str) – Name of second (Y) mandatory column
zname (str) – Name of third (Z) mandatory column
attributes (dict | None) – A dictionary for attribute columns as ‘name: type’, e.g. {“WellName”: “str”, “IX”: “int”}. This is applied when values are input and is to name and type the extra attribute columns in a point set.

Initialisation of Points().

Public Data Attributes:

dataframe

Returns or set the Pandas dataframe object.

Inherited from XYZ

`xyztype`	Read only, returns the type of XYZ data (POINTS, POLYGONS, ...)
`xname`	Returns or set the name of the X column.
`yname`	Returns or set the name of the Y column.
`zname`	Returns or set the name of the Z column.
`dataframe`	Return or set the Pandas dataframe object.
`nrow`	Returns the Pandas dataframe object number of rows.

Public Methods:

`get_dataframe`([copy])	Returns the Pandas dataframe object.
`set_dataframe`(df)	Set the Pandas dataframe object.
`to_file`(pfile[, fformat, attributes, ...])	Export Points to file.
`to_roxar`(project, name, category[, stype, ...])	Export (store) a Points item to a Roxar RMS project.
`copy`()	Returns a deep copy of an instance.
`snap_surface`(surf[, activeonly])	Snap (transfer) the points Z values to a RegularSurface
`get_boundary`()	Get the square XYZ window (boundaries) of the instance.

Inherited from XYZ

`copy`()	Returns a deep copy of an instance
`describe`([flush])	Describe an instance by printing to stdout
`get_dataframe`([copy])	Return the Pandas dataframe object.
`set_dataframe`(dataframe)	Set the Pandas dataframe object.
`protected_columns`()	returns: Columns not deleted by `delete_columns()`, for
`geometry_columns`()	returns: Columns can be deleted silently by `delete_columns()`
`delete_columns`(clist[, strict])	Delete one or more columns by name.
`get_nwells`([well_name_column])	Get number of unique wells in the instance.
`get_boundary`()	Get the square XYZ window (boundaries) of the instance.
`mark_in_polygons`(poly[, name, inside_value, ...])	Add a column that assign values if points are inside or outside polygons.
`operation_polygons`(poly, value[, opname, ...])	A generic function for operations restricted to inside or outside polygon(s).
`add_inside`(poly, value)	Add a value (scalar) to points inside polygons (old behaviour).
`add_inside_polygons`(poly, value)	Add a value (scalar) to points inside polygons (new behaviour).
`add_outside`(poly, value)	Add a value (scalar) to points outside polygons (old behaviour).
`add_outside_polygons`(poly, value)	Add a value (scalar) to points outside polygons (new behaviour).
`sub_inside`(poly, value)	Subtract a value (scalar) to points inside polygons.
`sub_inside_polygons`(poly, value)	Subtract a value (scalar) for points inside polygons (new behaviour).
`sub_outside`(poly, value)	Subtract a value (scalar) to points outside polygons.
`sub_outside_polygons`(poly, value)	Subtract a value (scalar) for points outside polygons (new behaviour).
`mul_inside`(poly, value)	Multiply a value (scalar) to points inside polygons.
`mul_inside_polygons`(poly, value)	Multiply a value (scalar) for points inside polygons (new behaviour).
`mul_outside`(poly, value)	Multiply a value (scalar) to points outside polygons.
`mul_outside_polygons`(poly, value)	Multiply a value (scalar) for points outside polygons (new behaviour).
`div_inside`(poly, value)	Divide a value (scalar) to points inside polygons.
`div_inside_polygons`(poly, value)	Divide a value (scalar) for points inside polygons (new behaviour).
`div_outside`(poly, value)	Divide a value (scalar) outside polygons (value 0.0 will give result 0).
`div_outside_polygons`(poly, value)	Divide a value (scalar) for points outside polygons (new behaviour).
`set_inside`(poly, value)	Set a value (scalar) to points inside polygons.
`set_inside_polygons`(poly, value)	Set a value (scalar) for points inside polygons (new behaviour).
`set_outside`(poly, value)	Set a value (scalar) to points outside polygons.
`set_outside_polygons`(poly, value)	Set a value (scalar) for points outside polygons (new behaviour).
`eli_inside`(poly)	Eliminate current points inside polygons (old implentation).
`eli_inside_polygons`(poly)	Remove points inside polygons.
`eli_outside`(poly)	Eliminate current points outside polygons (old implentation).
`eli_outside_polygons`(poly)	Remove points outside polygons.

__init__(values=None, xname='X_UTME', yname='Y_UTMN', zname='Z_TVDSS', attributes=None, filesrc=None)[source]: Initialisation of Points().

add_inside(poly, value)

Add a value (scalar) to points inside polygons (old behaviour).

Parameters:

poly – A xtgeo Polygons instance
value – Value to add to Z values inside polygons.

See notes under operation_polygons() and consider instead add_inside polygons().

add_inside_polygons(poly, value)

Add a value (scalar) to points inside polygons (new behaviour).

This is an improved implementation than add_inside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to add to Z values inside polygons.

Added in version 3.2.

add_outside(poly, value)

Add a value (scalar) to points outside polygons (old behaviour).

Parameters:

poly – A xtgeo Polygons instance
value – Value to add to Z values outside polygons.

See notes under operation_polygons() and consider instead add_outside polygons().

add_outside_polygons(poly, value)

Add a value (scalar) to points outside polygons (new behaviour).

This is an improved implementation than add_outside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to add to Z values outside polygons.

Added in version 3.2.

copy()[source]: Returns a deep copy of an instance.

property dataframe: Returns or set the Pandas dataframe object.

delete_columns(clist, strict=False)

Delete one or more columns by name.

Note that the columns returned by protected_columns(self)() (for instance, the coordinate columns) will not be deleted.

Parameters:

self (obj) – Points or Polygons
clist (list) – Name of columns
strict (bool) – I False, will not trigger exception if a column is not found. Otherways a ValueError will be raised.

Raises:

ValueError – If strict is True and columnname not present

Example::: mypoly.delete_columns([“WELL_ID”, mypoly.hname, mypoly.dhname])

Added in version 2.1.

describe(flush=True): Describe an instance by printing to stdout

div_inside(poly, value)

Divide a value (scalar) to points inside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to divide Z values inside polygons.

See notes under operation_polygons() and consider instead div_inside polygons().

div_inside_polygons(poly, value)

Divide a value (scalar) for points inside polygons (new behaviour).

This is an improved implementation than div_inside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to divide to Z values inside polygons.

Added in version 3.2.

div_outside(poly, value)

Divide a value (scalar) outside polygons (value 0.0 will give result 0).

Parameters:

poly – A xtgeo Polygons instance
value – Value to divide Z values outside polygons.

See notes under operation_polygons() and consider instead div_outside polygons().

div_outside_polygons(poly, value)

Divide a value (scalar) for points outside polygons (new behaviour).

Note if input value is 0.0 (division on zero), the result will be 0.0.

This is an improved implementation than div_outside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to divide to Z values outside polygons.

Added in version 3.2.

eli_inside(poly)

Eliminate current points inside polygons (old implentation).

Parameters:: poly – A xtgeo Polygons instance

See notes under operation_polygons() and consider instead eli_inside polygons().

eli_inside_polygons(poly)

Remove points inside polygons.

This is an improved implementation than eli_inside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:: poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances

Added in version 3.2.

eli_outside(poly)

Eliminate current points outside polygons (old implentation).

Parameters:: poly – A xtgeo Polygons instance

See notes under operation_polygons() and consider instead eli_outside polygons().

eli_outside_polygons(poly)

Remove points outside polygons.

This is an improved implementation than eli_outside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:: poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances

Added in version 3.2.

geometry_columns()

Returns:: Columns can be deleted silently by delete_columns()

get_boundary()[source]

Get the square XYZ window (boundaries) of the instance.

Returns:: (xmin, xmax, ymin, ymax, zmin, zmax)

See also

The class method Polygons.boundary_from_points()

get_dataframe(copy=True)[source]

Returns the Pandas dataframe object.

Parameters:: copy (bool) – If True (default) the a deep copy is returned; otherwise a view which may be faster in some cases)
Return type:: DataFrame

Changed in version 3.7: Add keyword copy, defaulted to True

get_nwells(well_name_column='WellName')

Get number of unique wells in the instance.

Parameters:: well_name_column (str) – Name of column with well names
Returns:: Number of unique wells, 0 if no well or column not present.

mark_in_polygons(poly, name='pstatus', inside_value=1, outside_value=0)

Add a column that assign values if points are inside or outside polygons.

This is a generic function that adds a column in the points dataframe with a flag for values being inside or outside polygons in a Polygons instance.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – One single xtgeo Polgons instance, or a list of Polygons instances.
name (str) – Name of column that flags inside or outside status
inside_value (int) – Flag value for being inside polygons
outside_value (int) – Flag value for being outside polygons

..versionadded:: 3.2

mul_inside(poly, value)

Multiply a value (scalar) to points inside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to multiply to Z values inside polygons.

See notes under operation_polygons() and consider instead mul_inside polygons().

mul_inside_polygons(poly, value)

Multiply a value (scalar) for points inside polygons (new behaviour).

This is an improved implementation than mul_inside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to multiply to Z values inside polygons.

Added in version 3.2.

mul_outside(poly, value)

Multiply a value (scalar) to points outside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to multiply to Z values outside polygons.

See notes under operation_polygons() and consider instead mul_outside polygons().

mul_outside_polygons(poly, value)

Multiply a value (scalar) for points outside polygons (new behaviour).

This is an improved implementation than mul_outside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to multiply to Z values outside polygons.

Added in version 3.2.

property nrow: Returns the Pandas dataframe object number of rows.

operation_polygons(poly, value, opname='add', inside=True, version=1)

A generic function for operations restricted to inside or outside polygon(s).

The operations are performed on the Z values, while the ‘inside’ or ‘outside’ of polygons are purely based on X and Y values (typically X is East and Y in North coordinates).

The operations are XYZ generic i.e. done on the points that defines the Polygon or the point in Points, depending on the calling instance.

Possible opname strings:

add: add the value
sub: substract the value
mul: multiply the value
div: divide the value
set: replace current values with value
eli: eliminate; here value is not applied

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A single Polygons instance or a list of Polygons instances. The list option is only allowed when version = 2
value (float) – Value to add, subtract etc
opname (str) – Name of operation… ‘add’, ‘sub’, etc
inside (bool) – If True do operation inside polygons; else outside. Note that boundary is treated as ‘inside’
version (int) – The algorithm version, see notes below. Although version 1 is default, version 2 is recommended as it is much faster and works intuitively when have multiple polygons and/or using the is_inside=False (i.e. outside)

Note

version=1: This function works only intuitively when using one single polygon in the poly instance. When having several polygons the operation is done sequentially per polygon which may lead to surprising results. For instance, using “add inside” into two overlapping polygons, the addition will be doubled in the overlapping part. Similarly, using e.g. “eli, outside” will completely remove all points of two non-overlapping polygons are given as input.

version=2: This is a new and recommended implementation. It works much faster and intuitively for both inside and outside, overlapping and multiple polygons within a Polygons instance.

Changed in version 3.2: Add version option which defaults to 1. Also allow that poly option can be a list of Polygons when version is 2.

protected_columns()

Returns:: Columns not deleted by delete_columns(), for instance the coordinate columns.

set_dataframe(df)[source]: Set the Pandas dataframe object.

set_inside(poly, value)

Set a value (scalar) to points inside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to set Z values inside polygons.

See notes under operation_polygons() and consider instead set_inside polygons().

set_inside_polygons(poly, value)

Set a value (scalar) for points inside polygons (new behaviour).

This is an improved implementation than set_inside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to set as Z values inside polygons.

Added in version 3.2.

set_outside(poly, value)

Set a value (scalar) to points outside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to set Z values outside polygons.

See notes under operation_polygons() and consider instead set_outside polygons().

set_outside_polygons(poly, value)

Set a value (scalar) for points outside polygons (new behaviour).

This is an improved implementation than set_outside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to set as Z values inside polygons.

Added in version 3.2.

snap_surface(surf, activeonly=True)[source]

Snap (transfer) the points Z values to a RegularSurface

Parameters:

surf (RegularSurface) – Surface to snap to.
activeonly (bool) – If True (default), the points outside the defined surface will be removed. If False, these points will keep the original values.

Returns:

None (instance is updated inplace)

Raises:

ValueError – Input object of wrong data type, must be RegularSurface
RuntimeError – Error code from C routine surf_get_zv_from_xyv is …

Added in version 2.1.

sub_inside(poly, value)

Subtract a value (scalar) to points inside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to subtract to Z values inside polygons.

See notes under operation_polygons() and consider instead sub_inside polygons().

sub_inside_polygons(poly, value)

Subtract a value (scalar) for points inside polygons (new behaviour).

This is an improved implementation than sub_inside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to subtract to Z values inside polygons.

Added in version 3.2.

sub_outside(poly, value)

Subtract a value (scalar) to points outside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to subtract to Z values outside polygons.

See notes under operation_polygons() and consider instead sub_outside polygons().

sub_outside_polygons(poly, value)

Subtract a value (scalar) for points outside polygons (new behaviour).

This is an improved implementation than sub_outside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to subtract to Z values outside polygons.

Added in version 3.2.

to_file(pfile, fformat='xyz', attributes=True, pfilter=None, wcolumn=None, hcolumn=None, mdcolumn='M_MDEPTH', **kwargs)[source]

Export Points to file.

Parameters:

pfile (str) – Name of file
fformat (str) – File format xyz/poi/pol or rms_attr
attributes (bool or list) – List of extra columns to export (some formats) or True for all attributes present
pfilter (dict) – Filter on e.g. top name(s) with keys TopName or ZoneName as {‘TopName’: [‘Top1’, ‘Top2’]}.
wcolumn (str) – Name of well column (rms_wellpicks format only)
hcolumn (str) – Name of horizons column (rms_wellpicks format only)
mdcolumn (str) – Name of MD column (rms_wellpicks format only)

Returns:

Number of points exported

Note that the rms_wellpicks will try to output to:

HorizonName, WellName, MD if a MD (mdcolumn) is present,
HorizonName, WellName, X, Y, Z otherwise

Note

For backward compatibility, the key filter can be applied instead of pfilter.

Raises:: KeyError if pfilter is set and key(s) are invalid –

to_roxar(project, name, category, stype='horizons', pfilter=None, realisation=0, attributes=False)[source]

Export (store) a Points item to a Roxar RMS project.

The export to the RMS project can be done either within the project or outside the project.

Note also that horizon/zone name and category must exists in advance, otherwise an Exception will be raised.

Note

When project is file path (direct access, outside RMS) then to_roxar() will implicitly do a project save. Otherwise, the project will not be saved until the user do an explicit project save action.

Parameters:

project (str or special) – Name of project (as folder) if outside RMS, og just use the magic project word if within RMS.
name (str) – Name of points item, or name of well pick set if well picks.
category (str) – For horizons/zones/faults: for example ‘DL_depth’ or use a folder notation on clipboard/general2d_data. For well picks it is the well pick type: “horizon” or “fault”.
pfilter (dict) – Filter on e.g. top name(s) with keys TopName or ZoneName as {‘TopName’: [‘Top1’, ‘Top2’]}
stype – RMS folder type, ‘horizons’ (default), ‘zones’, ‘clipboard’, ‘general2d_data’, ‘faults’ or ‘well_picks’
realisation (int) – Realisation number, default is 0
attributes (bool) – If True, attributes will be preserved (from RMS 11)

Raises:

ValueError – Various types of invalid inputs.
NotImplementedError – Not supported in this ROXAPI version

Added in version 2.19: general2d_data support is added

property xname: Returns or set the name of the X column.

property xyztype: Read only, returns the type of XYZ data (POINTS, POLYGONS, …)

property yname: Returns or set the name of the Y column.

property zname: Returns or set the name of the Z column.

Polygons

Functions

xtgeo.polygons_from_file(pfile, fformat='guess')[source]

Make an instance of a Polygons object directly from file import.

Supported formats are:

‘xyz’ or ‘pol’: Simple XYZ format

‘zmap’: ZMAP line format as exported from RMS (e.g. fault lines)

‘guess’: Try to choose file format based on extension

Parameters:

pfile (str) – Name of file
fformat (str) – See Polygons.from_file()

Example:

import xtgeo
mypoly = xtgeo.polygons_from_file('somefile.xyz')

xtgeo.polygons_from_roxar(project, name, category, stype='horizons', realisation=0, attributes=False)[source]

Load a Polygons instance from Roxar RMS project.

Note also that horizon/zone/faults name and category must exists in advance, otherwise an Exception will be raised.

Parameters:

project (str | Any) – Name of project (as folder) if outside RMS, or just use the magic project word if within RMS.
name (str) – Name of polygons item
category (str) – For horizons/zones/faults: for example ‘DL_depth’ or use a folder notation on clipboard/general2d_data.
stype (str | None) – RMS folder type, ‘horizons’ (default), ‘zones’, ‘clipboard’, ‘faults’, ‘general2d_data’
realisation (int | None) – Realisation number, default is 0
attributes (bool | list[str]) – Polygons can store an attrubute (e.g. a fault name) per polygon, i.e. per “POLY_ID”)

Example:

import xtgeo
mysurf = xtgeo.polygons_from_roxar(project, 'TopAare', 'DepthPolys')

Added in version 2.19: general2d_data support is added

Added in version 3.x: support for polygon attributes (other than POLY_ID)

xtgeo.polygons_from_wells(wells, zone=1, resample=1)[source]

Get polygons from wells and a single zone number.

Parameters:

wells (list[Well]) – List of XTGeo well objects, a single XTGeo well or a list of well files. If a list of well files, the routine will try to load well based on file signature and/or extension, but only default settings are applied. Hence this is less flexible and more fragile.
zone (int | None) – The zone number to extract the linepiece from
resample (int | None) – If given, resample every N’th sample to make polylines smaller in terms of bits and bytes. 1 = No resampling, which means just use well sampling (which can be rather dense; typically 15 cm).

Returns:

None if empty data, otherwise a Polygons() instance.

Example:

wells = ["w1.w", "w2.w"]
points = xtgeo.polygons_from_wells(wells, zone=2)

Classes

class xtgeo.Polygons(values=None, xname='X_UTME', yname='Y_UTMN', zname='Z_TVDSS', pname='POLY_ID', hname='R_HLEN', dhname='H_DELTALEN', tname='T_CUMLEN', dtname='T_DELTALEN', name='poly', attributes=None, fformat='guess', filesrc=None)[source]

Bases: XYZ

Class for a Polygons object (connected points) in the XTGeo framework.

The term Polygons is here used in a wider context, as it includes polylines that do not connect into closed polygons. A Polygons instance may contain several pieces of polylines/polygons, which are identified by POLY_ID.

The polygons are stored in Python as a Pandas dataframe, which allow for flexible manipulation and fast execution.

A Polygons instance will have 4 mandatory columns; here by default names:

X_UTME - for X UTM coordinate (Easting)
Y_UTMN - For Y UTM coordinate (Northing)
Z_TVDSS - For depth or property from mean SeaLevel; Depth positive down
POLY_ID - for polygon ID as there may be several polylines segments

Each Polygons instance can also a name (through the name attribute). Default is ‘poly’. E.g. if a well fence, it is logical to name the instance to be the same as the well name.

Parameters:

values (list | ndarray | DataFrame) – Provide input values on various forms (list-like or dataframe).
xname (str) – Name of first (X) mandatory column.
yname (str) – Name of second (Y) mandatory column.
zname (str) – Name of third (Z) mandatory column.
pname (str) – Name of forth (P) mandatory enumerating column.
hname (str) – Name of cumulative horizontal length, defaults to “H_CUMLEN” if in dataframe otherwise None.
dhname (str) – Name of delta horizontal length, defaults to “H_DELTALEN” if in dataframe otherwise None.
tname (str) – Name of cumulative total length, defaults to “T_CUMLEN” if in dataframe otherwise None.
dtname (str) – Name of delta total length, defaults to “T_DELTALEN” if in dataframe otherwise None.
attributes (dict | None) – A dictionary for attribute columns as ‘name: type’, e.g. {“WellName”: “str”, “IX”: “int”}. This is applied when values are input and is to name and type the extra attribute columns in a polygons set.

Note

Most export/import file formats do not support additional attributes; only the three first columns (X, Y, Z) are fully supported.

Concrete initialisation for base class _XYZ.

Public Data Attributes:

`name`	Returns or sets the name of the instance.
`pname`
`hname`	Returns or set the name of the cumulative horizontal length.
`dhname`	Returns or set the name of the delta horizontal length column if it exists.
`tname`	Returns or set the name of the cumulative total length column if it exists.
`dtname`	Returns or set the name of the delta total length column if it exists.
`dataframe`	Returns or set the Pandas dataframe object.

Inherited from XYZ

`xyztype`	Read only, returns the type of XYZ data (POINTS, POLYGONS, ...)
`xname`	Returns or set the name of the X column.
`yname`	Returns or set the name of the Y column.
`zname`	Returns or set the name of the Z column.
`dataframe`	Return or set the Pandas dataframe object.
`nrow`	Returns the Pandas dataframe object number of rows.

Public Methods:

`get_dataframe`([copy])	Returns the Pandas dataframe object.
`set_dataframe`(df)	Set the Pandas dataframe object.
`boundary_from_points`(points[, alpha_factor, ...])	Instantiate polygons from detecting the boundary around points.
`protected_columns`()	returns: Columns not deleted by `delete_columns()`, for
`to_file`(pfile[, fformat])	Export Polygons to file.
`to_roxar`(project, name, category[, stype, ...])	Export (store) a Polygons item to a Roxar RMS project.
`copy`()	Returns a deep copy of an instance
`get_xyz_dataframe`()	Get a dataframe copy from the Polygons points with no ID column.
`get_shapely_objects`()	Returns a list of Shapely LineString objects, one per POLY_ID.
`get_boundary`()	Get the square XYZ window (boundaries) of the instance.
`simplify`([tolerance, preserve_topology])	Simply a polygon, i.e. remove unneccesary points.
`filter_byid`([polyid])	Remove all line segments not in polyid.
`tlen`([tname, dtname, atindex])	Compute and add or replace columns for cum.
`hlen`([hname, dhname, atindex])	Compute and add/replace columns for cum.
`extend`(distance[, nsamples, mode2d])	Extend polyline by distance at both ends, nsmaples times.
`rescale`(distance[, addlen, kind, mode2d])	Rescale (resample) by using a new increment.
`get_fence`([distance, atleast, nextend, ...])	Extracts a fence with constant horizontal sampling.
`quickplot`([filename, others, title, ...])	Simple plotting of polygons using matplotlib.

Inherited from XYZ

`copy`()	Returns a deep copy of an instance
`describe`([flush])	Describe an instance by printing to stdout
`get_dataframe`([copy])	Return the Pandas dataframe object.
`set_dataframe`(dataframe)	Set the Pandas dataframe object.
`protected_columns`()	returns: Columns not deleted by `delete_columns()`, for
`geometry_columns`()	returns: Columns can be deleted silently by `delete_columns()`
`delete_columns`(clist[, strict])	Delete one or more columns by name.
`get_nwells`([well_name_column])	Get number of unique wells in the instance.
`get_boundary`()	Get the square XYZ window (boundaries) of the instance.
`mark_in_polygons`(poly[, name, inside_value, ...])	Add a column that assign values if points are inside or outside polygons.
`operation_polygons`(poly, value[, opname, ...])	A generic function for operations restricted to inside or outside polygon(s).
`add_inside`(poly, value)	Add a value (scalar) to points inside polygons (old behaviour).
`add_inside_polygons`(poly, value)	Add a value (scalar) to points inside polygons (new behaviour).
`add_outside`(poly, value)	Add a value (scalar) to points outside polygons (old behaviour).
`add_outside_polygons`(poly, value)	Add a value (scalar) to points outside polygons (new behaviour).
`sub_inside`(poly, value)	Subtract a value (scalar) to points inside polygons.
`sub_inside_polygons`(poly, value)	Subtract a value (scalar) for points inside polygons (new behaviour).
`sub_outside`(poly, value)	Subtract a value (scalar) to points outside polygons.
`sub_outside_polygons`(poly, value)	Subtract a value (scalar) for points outside polygons (new behaviour).
`mul_inside`(poly, value)	Multiply a value (scalar) to points inside polygons.
`mul_inside_polygons`(poly, value)	Multiply a value (scalar) for points inside polygons (new behaviour).
`mul_outside`(poly, value)	Multiply a value (scalar) to points outside polygons.
`mul_outside_polygons`(poly, value)	Multiply a value (scalar) for points outside polygons (new behaviour).
`div_inside`(poly, value)	Divide a value (scalar) to points inside polygons.
`div_inside_polygons`(poly, value)	Divide a value (scalar) for points inside polygons (new behaviour).
`div_outside`(poly, value)	Divide a value (scalar) outside polygons (value 0.0 will give result 0).
`div_outside_polygons`(poly, value)	Divide a value (scalar) for points outside polygons (new behaviour).
`set_inside`(poly, value)	Set a value (scalar) to points inside polygons.
`set_inside_polygons`(poly, value)	Set a value (scalar) for points inside polygons (new behaviour).
`set_outside`(poly, value)	Set a value (scalar) to points outside polygons.
`set_outside_polygons`(poly, value)	Set a value (scalar) for points outside polygons (new behaviour).
`eli_inside`(poly)	Eliminate current points inside polygons (old implentation).
`eli_inside_polygons`(poly)	Remove points inside polygons.
`eli_outside`(poly)	Eliminate current points outside polygons (old implentation).
`eli_outside_polygons`(poly)	Remove points outside polygons.

__init__(values=None, xname='X_UTME', yname='Y_UTMN', zname='Z_TVDSS', pname='POLY_ID', hname='R_HLEN', dhname='H_DELTALEN', tname='T_CUMLEN', dtname='T_DELTALEN', name='poly', attributes=None, fformat='guess', filesrc=None)[source]: Concrete initialisation for base class _XYZ.

add_inside(poly, value)

Add a value (scalar) to points inside polygons (old behaviour).

Parameters:

poly – A xtgeo Polygons instance
value – Value to add to Z values inside polygons.

See notes under operation_polygons() and consider instead add_inside polygons().

add_inside_polygons(poly, value)

Add a value (scalar) to points inside polygons (new behaviour).

This is an improved implementation than add_inside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to add to Z values inside polygons.

Added in version 3.2.

add_outside(poly, value)

Add a value (scalar) to points outside polygons (old behaviour).

Parameters:

poly – A xtgeo Polygons instance
value – Value to add to Z values outside polygons.

See notes under operation_polygons() and consider instead add_outside polygons().

add_outside_polygons(poly, value)

Add a value (scalar) to points outside polygons (new behaviour).

This is an improved implementation than add_outside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to add to Z values outside polygons.

Added in version 3.2.

classmethod boundary_from_points(points, alpha_factor=1.0, alpha=None, convex=False)[source]

Instantiate polygons from detecting the boundary around points.

Parameters:

points – The XTGeo Points instance to estimate boundary/boundaries around.
alpha_factor (float | None) – The alpha factor is a multiplier to alpha. Normally it will be around 1, but can be increased to get a looser boundary. Dependent on the points topology, it can also be decreased to some extent.
alpha (float | None) – The alpha factor for determine the ‘precision’ in how to delineate the polygon. A large value will produce a smoother polygon. The default is to detect the value from the data, but note that this default may be far from optimal for you needs. Usually use the alpha_factor to tune the best value. The actual alpha applied in the concave hull algorithm is alpha_factor multiplied with alpha.
convex (bool) – If True, then compute a maximum boundary (convex), and note that alpha_factor and alpha are not applied in ths case. Default is False.

Returns:

A Polygons instance.

copy()[source]: Returns a deep copy of an instance

property dataframe: Returns or set the Pandas dataframe object.

delete_columns(clist, strict=False)

Delete one or more columns by name.

Note that the columns returned by protected_columns(self)() (for instance, the coordinate columns) will not be deleted.

Parameters:

self (obj) – Points or Polygons
clist (list) – Name of columns
strict (bool) – I False, will not trigger exception if a column is not found. Otherways a ValueError will be raised.

Raises:

ValueError – If strict is True and columnname not present

Example::: mypoly.delete_columns([“WELL_ID”, mypoly.hname, mypoly.dhname])

Added in version 2.1.

describe(flush=True): Describe an instance by printing to stdout

property dhname

Returns or set the name of the delta horizontal length column if it exists.

If the column does not exist, None is returned. Default name is H_DELTALEN.

Added in version 2.1.

div_inside(poly, value)

Divide a value (scalar) to points inside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to divide Z values inside polygons.

See notes under operation_polygons() and consider instead div_inside polygons().

div_inside_polygons(poly, value)

Divide a value (scalar) for points inside polygons (new behaviour).

This is an improved implementation than div_inside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to divide to Z values inside polygons.

Added in version 3.2.

div_outside(poly, value)

Divide a value (scalar) outside polygons (value 0.0 will give result 0).

Parameters:

poly – A xtgeo Polygons instance
value – Value to divide Z values outside polygons.

See notes under operation_polygons() and consider instead div_outside polygons().

div_outside_polygons(poly, value)

Divide a value (scalar) for points outside polygons (new behaviour).

Note if input value is 0.0 (division on zero), the result will be 0.0.

This is an improved implementation than div_outside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to divide to Z values outside polygons.

Added in version 3.2.

property dtname: Returns or set the name of the delta total length column if it exists.

Added in version 2.1.

eli_inside(poly)

Eliminate current points inside polygons (old implentation).

Parameters:: poly – A xtgeo Polygons instance

See notes under operation_polygons() and consider instead eli_inside polygons().

eli_inside_polygons(poly)

Remove points inside polygons.

This is an improved implementation than eli_inside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:: poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances

Added in version 3.2.

eli_outside(poly)

Eliminate current points outside polygons (old implentation).

Parameters:: poly – A xtgeo Polygons instance

See notes under operation_polygons() and consider instead eli_outside polygons().

eli_outside_polygons(poly)

Remove points outside polygons.

This is an improved implementation than eli_outside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:: poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances

Added in version 3.2.

extend(distance, nsamples=1, mode2d=True)[source]

Extend polyline by distance at both ends, nsmaples times.

The instance is updated in-place.

Parameters:

distance (float) – The horizontal distance (sampling) to extend
nsamples (int) – Number of samples to extend.
mode2d (bool) – XY extension (only True is supported)

Added in version 2.1.

filter_byid(polyid=None)[source]

Remove all line segments not in polyid.

The instance is updated in-place.

Parameters:: polyid (int or list of int) – Which ID(s) to keep, None means use first.

Example:

mypoly.filter_byid(polyid=[2, 4])  # keep POLY_ID 2 and 4

Added in version 2.1.

geometry_columns()

Returns:: Columns can be deleted silently by delete_columns()

get_boundary()[source]

Get the square XYZ window (boundaries) of the instance.

Returns:: (xmin, xmax, ymin, ymax, zmin, zmax)

See also

The class method Polygons.boundary_from_points()

get_dataframe(copy=True)[source]

Returns the Pandas dataframe object.

Parameters:: copy (bool) – If True, return a deep copy of the dataframe
Return type:: DataFrame

get_fence(distance=20, atleast=5, nextend=2, name=None, asnumpy=True, polyid=None)[source]

Extracts a fence with constant horizontal sampling.

Additonal H_CUMLEN and H_DELTALEN vectors will be added, suitable for X sections.

Parameters:

distance (float) – New horizontal distance between points
atleast (int) – Minimum number of points. If the true length/atleast is less than distance, than distance will be be reset to length/atleast. Values below 3 are not permitted
nextend (int) – Number of samples to extend at each end. Note that in case of internal resetting of distance (due to ‘atleast’), then nextend internally will be modified in order to fulfill the initial intention. Hence keep distance*nextend as target.
name (str) – Name of polygon (if asnumpy=False)
asnumpy (bool) – Return a [:, 5] numpy array with columns X.., Y.., Z.., HLEN, dH
polyid (int) – Which POLY_ID to use. Default (if None) is to use the first found.

Returns:

A numpy array (if asnumpy=True) or a new Polygons() object

Added in version 2.1.

get_nwells(well_name_column='WellName')

Get number of unique wells in the instance.

Parameters:: well_name_column (str) – Name of column with well names
Returns:: Number of unique wells, 0 if no well or column not present.

get_shapely_objects()[source]: Returns a list of Shapely LineString objects, one per POLY_ID.

Added in version 2.1.

get_xyz_dataframe()[source]

Get a dataframe copy from the Polygons points with no ID column.

Convert from POLY_ID based to XYZ, where a new polygon is marked with a 999 value as flag.

hlen(hname='H_CUMLEN', dhname='H_DELTALEN', atindex=0)[source]

Compute and add/replace columns for cum. horizontal length and delta length.

The instance is updated in-place.

Parameters:

hname (str) – Name of cumulative horizontal length. Default is H_CUMLEN.
dhname (str) – Name of delta length column. Default is H_DELTALEN.
atindex (int) – Which index which shall be 0.0 for cumulative length.

Added in version 2.1.

property hname

Returns or set the name of the cumulative horizontal length.

If the column does not exist, None is returned. Default name is H_CUMLEN.

Added in version 2.1.

mark_in_polygons(poly, name='pstatus', inside_value=1, outside_value=0)

Add a column that assign values if points are inside or outside polygons.

This is a generic function that adds a column in the points dataframe with a flag for values being inside or outside polygons in a Polygons instance.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – One single xtgeo Polgons instance, or a list of Polygons instances.
name (str) – Name of column that flags inside or outside status
inside_value (int) – Flag value for being inside polygons
outside_value (int) – Flag value for being outside polygons

..versionadded:: 3.2

mul_inside(poly, value)

Multiply a value (scalar) to points inside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to multiply to Z values inside polygons.

See notes under operation_polygons() and consider instead mul_inside polygons().

mul_inside_polygons(poly, value)

Multiply a value (scalar) for points inside polygons (new behaviour).

This is an improved implementation than mul_inside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to multiply to Z values inside polygons.

Added in version 3.2.

mul_outside(poly, value)

Multiply a value (scalar) to points outside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to multiply to Z values outside polygons.

See notes under operation_polygons() and consider instead mul_outside polygons().

mul_outside_polygons(poly, value)

Multiply a value (scalar) for points outside polygons (new behaviour).

This is an improved implementation than mul_outside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to multiply to Z values outside polygons.

Added in version 3.2.

property name: Returns or sets the name of the instance.

property nrow: Returns the Pandas dataframe object number of rows.

operation_polygons(poly, value, opname='add', inside=True, version=1)

A generic function for operations restricted to inside or outside polygon(s).

The operations are performed on the Z values, while the ‘inside’ or ‘outside’ of polygons are purely based on X and Y values (typically X is East and Y in North coordinates).

The operations are XYZ generic i.e. done on the points that defines the Polygon or the point in Points, depending on the calling instance.

Possible opname strings:

add: add the value
sub: substract the value
mul: multiply the value
div: divide the value
set: replace current values with value
eli: eliminate; here value is not applied

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A single Polygons instance or a list of Polygons instances. The list option is only allowed when version = 2
value (float) – Value to add, subtract etc
opname (str) – Name of operation… ‘add’, ‘sub’, etc
inside (bool) – If True do operation inside polygons; else outside. Note that boundary is treated as ‘inside’
version (int) – The algorithm version, see notes below. Although version 1 is default, version 2 is recommended as it is much faster and works intuitively when have multiple polygons and/or using the is_inside=False (i.e. outside)

Note

version=1: This function works only intuitively when using one single polygon in the poly instance. When having several polygons the operation is done sequentially per polygon which may lead to surprising results. For instance, using “add inside” into two overlapping polygons, the addition will be doubled in the overlapping part. Similarly, using e.g. “eli, outside” will completely remove all points of two non-overlapping polygons are given as input.

version=2: This is a new and recommended implementation. It works much faster and intuitively for both inside and outside, overlapping and multiple polygons within a Polygons instance.

Changed in version 3.2: Add version option which defaults to 1. Also allow that poly option can be a list of Polygons when version is 2.

property pname

protected_columns()[source]

Returns:: Columns not deleted by delete_columns(), for instance the coordinate columns.

quickplot(filename=None, others=None, title='QuickPlot for Polygons', subtitle=None, infotext=None, linewidth=1.0, color='r')[source]

Simple plotting of polygons using matplotlib.

Parameters:

filename (str) – Name of plot file; None will plot to screen.
others (list of Polygons) – List of other polygon instances to plot
title (str) – Title of plot
subtitle (str) – Subtitle of plot
infotext (str) – Additonal info on plot.
linewidth (float) – Width of line.
color (str) – Name of color (may use matplotib shortcuts, e.g. ‘r’ for ‘red’)

rescale(distance, addlen=False, kind='simple', mode2d=True)[source]

Rescale (resample) by using a new increment.

The increment (distance) may be a horizontal or a True 3D distance dependent on mode2d.

The instance is updated in-place.

If the distance is larger than the total input poly-line length, nothing is done. Note that the result distance may differ from the requested distance caused to rounding to fit original length.

Hence actual distance is input distance +- 50%.

Parameters:

distance (float) – New distance between points
addlen (str) – If True, total and horizontal cum. and delta length columns will be added.
kind (str) – What kind of rescaling: slinear/cubic/simple
mode2d (bool) – The distance may be a 2D (XY) ora 3D (XYZ) mode.

Changed in version 2.1: a new algorithm

set_dataframe(df)[source]: Set the Pandas dataframe object.

set_inside(poly, value)

Set a value (scalar) to points inside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to set Z values inside polygons.

See notes under operation_polygons() and consider instead set_inside polygons().

set_inside_polygons(poly, value)

Set a value (scalar) for points inside polygons (new behaviour).

This is an improved implementation than set_inside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to set as Z values inside polygons.

Added in version 3.2.

set_outside(poly, value)

Set a value (scalar) to points outside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to set Z values outside polygons.

See notes under operation_polygons() and consider instead set_outside polygons().

set_outside_polygons(poly, value)

Set a value (scalar) for points outside polygons (new behaviour).

This is an improved implementation than set_outside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to set as Z values inside polygons.

Added in version 3.2.

simplify(tolerance=0.1, preserve_topology=True)[source]

Simply a polygon, i.e. remove unneccesary points.

This is based on Shapely’s simplify() method

Parameters:

tolerance (float | None) – Cf. Shapely’s documentation
preserve_topology (bool | None) – Default is True, if False a faster algorithm is applied

Return type:

bool

Returns:

True if simplification is achieved. The polygons instance is updated in-place.

sub_inside(poly, value)

Subtract a value (scalar) to points inside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to subtract to Z values inside polygons.

See notes under operation_polygons() and consider instead sub_inside polygons().

sub_inside_polygons(poly, value)

Subtract a value (scalar) for points inside polygons (new behaviour).

This is an improved implementation than sub_inside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to subtract to Z values inside polygons.

Added in version 3.2.

sub_outside(poly, value)

Subtract a value (scalar) to points outside polygons.

Parameters:

poly – A xtgeo Polygons instance
value – Value to subtract to Z values outside polygons.

See notes under operation_polygons() and consider instead sub_outside polygons().

sub_outside_polygons(poly, value)

Subtract a value (scalar) for points outside polygons (new behaviour).

This is an improved implementation than sub_outside(), and is now the recommended method, as it is both faster and works similar for all single and overlapping sub-polygons within one or more Polygons instances.

Parameters:

poly (Union[TypeVar(Polygons), list[TypeVar(Polygons)]]) – A xtgeo Polygons instance, or a list of xtgeo Polygons instances
value (float) – Value to subtract to Z values outside polygons.

Added in version 3.2.

tlen(tname='T_CUMLEN', dtname='T_DELTALEN', atindex=0)[source]

Compute and add or replace columns for cum. total 3D length and delta length.

The instance is updated in-place.

Parameters:

tname (str) – Name of cumulative total length. Default is T_CUMLEN.
dtname (str) – Name of delta length column. Default is T_DELTALEN.
atindex (int) – Which index which shall be 0.0 for cumulative length.

Added in version 2.1.

property tname: Returns or set the name of the cumulative total length column if it exists.

Added in version 2.1.

to_file(pfile, fformat='xyz')[source]

Export Polygons to file.

Parameters:

pfile (str) – Name of file
fformat (str) – File format xyz/poi/pol

Returns:

Number of polygon points exported

to_roxar(project, name, category, stype='horizons', realisation=0, attributes=False)[source]

Export (store) a Polygons item to a Roxar RMS project.

The export to the RMS project can be done either within the project or outside the project.

Note also that horizon/zone name and category must exists in advance, otherwise an Exception will be raised.

Note

When project is file path (direct access, outside RMS) then to_roxar() will implicitly do a project save. Otherwise, the project will not be saved until the user do an explicit project save action.

Parameters:

project (str or special) – Name of project (as folder) if outside RMS, og just use the magic project word if within RMS.
name (str) – Name of polygons item
category (str) – For horizons/zones/faults: for example ‘DL_depth’ and use a folder notation for clipboard/general2d_data
stype (str) – RMS folder type, ‘horizons’ (default), ‘zones’ or ‘faults’ or ‘clipboard’ (in prep: well picks)
realisation (int) – Realisation number, default is 0
attributes (bool) – If True, attributes will be preserved (from RMS 13)

Raises:

ValueError – Various types of invalid inputs.
NotImplementedError – Not supported in this ROXAPI version

Note

Setting (storing) polygons with attributes is not supported in RMSAPI.

Added in version 2.19: general2d_data support is added

Added in version 4.X: Added attributes

property xname: Returns or set the name of the X column.

property xyztype: Read only, returns the type of XYZ data (POINTS, POLYGONS, …)

property yname: Returns or set the name of the Y column.

property zname: Returns or set the name of the Z column.

Wells

Well (single)

Functions

xtgeo.well_from_file(wfile, fformat='rms_ascii', mdlogname=None, zonelogname=None, lognames='all', lognames_strict=False, strict=False)[source]

Make an instance of a Well directly from file import.

Parameters:

wfile (str | Path) – File path for well, either a string or a pathlib.Path instance
fformat (str | None) – “rms_ascii” or “hdf5”
mdlogname (str | None) – Name of Measured Depth log, if any
zonelogname (str | None) – Name of Zonelog, if any
lognames (str | list[str] | None) – Name or list of lognames to import, default is “all”
lognames_strict (bool | None) – If True, all lognames must be present.
strict (bool | None) – If True, then import will fail if zonelogname or mdlogname are asked for but those names are not present in wells.

Return type:

Well

Example:

>>> import xtgeo
>>> import pathlib
>>> welldir = pathlib.Path("../foo")
>>> mywell = xtgeo.well_from_file(welldir / "OP_1.w")

Changed in version 2.1: Added lognames and lognames_strict

Changed in version 2.1: strict now defaults to False

xtgeo.well_from_roxar(project, name, trajectory='Drilled trajectory', logrun='log', lognames='all', lognames_strict=False, inclmd=False, inclsurvey=False)[source]

This makes an instance of a Well directly from Roxar RMS.

Note this method works only when inside RMS, or when RMS license is activated (through the roxar environment).

Parameters:

project (str | object) – Path to project or magic the project variable in RMS.
name (str) – Name of Well, as shown in RMS.
trajectory (str | None) – Name of trajectory in RMS.
logrun (str | None) – Name of logrun in RMS.
lognames (str | list[str] | None) – List of lognames to import, or use ‘all’ for all present logs
lognames_strict (bool | None) – If True and log is not in lognames is a list, an Exception will be raised.
inclmd (bool | None) – If True, a Measured Depth log will be included.
inclsurvey (bool | None) – If True, logs for azimuth and deviation will be included.

Return type:

Well

Returns:

Well instance.

Example:

# inside RMS:
import xtgeo
mylogs = ['ZONELOG', 'GR', 'Facies']
mywell = xtgeo.well_from_roxar(
    project, "31_3-1", trajectory="Drilled", logrun="log", lognames=mylogs
)

Changed in version 2.1: lognames defaults to “all”, not None

Classes

class xtgeo.Well(rkb=0.0, xpos=0.0, ypos=0.0, wname='', df=None, mdlogname=None, zonelogname=None, wlogtypes=None, wlogrecords=None, filesrc=None)[source]

Bases: object

Class for a single well in the XTGeo framework.

The well logs are stored in a Pandas dataframe, which make manipulation easy and fast.

The well trajectory are here represented as first 3 columns in the dataframe, and XYZ have pre-defined names: X_UTME, Y_UTMN, Z_TVDSS.

Other geometry logs may has also ‘semi-defined’ names, but this is not a strict rule:

M_MDEPTH or Q_MDEPTH: Measured depth, either real/true (M_xx) or quasi computed/estimated (Q_xx). The Quasi may be incorrect for all uses, but sufficient for some computations.

Similar for M_INCL, Q_INCL, M_AZI, Q_ASI.

All Pandas values (yes, discrete also!) are currently stored as float64 format, and undefined values are Nan. Integers are stored as Float due to the (historic) lacking support for ‘Integer Nan’.

Note there is a method that can return a dataframe (copy) with Integer and Float columns, see get_filled_dataframe().

The instance can be made either from file or by specification:

>>> well1 = xtgeo.well_from_file(well_dir + '/OP_1.w')
>>> well2 = xtgeo.Well(rkb=32.0, xpos=1234.0, ypos=4567.0, wname="Foo",
            df: mydataframe, ...)

Parameters:

rkb (float) – Well RKB height
xpos (float) – Well head X pos
ypos (float) – Well head Y pos
wname (str) – well name
df (DataFrame | None) – A pandas dataframe with log values, expects columns to include ‘X_UTME’, ‘Y_UTMN’, ‘Z_TVDSS’ for x, y and z coordinates. Other columns should be log values.
filesrc (str | Path | None) – source file if any
mdlogname (str | None) – Name of Measured Depth log, if any.
zonelogname (str | None) – Name of Zonelog, if any
wlogtypes (dict[str, str] | None) – dictionary of log types, ‘DISC’ (discrete) or ‘CONT’ (continuous), defaults to to ‘CONT’.
wlogrecords (dict[str, str] | None) – dictionary of codes for ‘DISC’ logs, None for no codes given, defaults to None.

Public Data Attributes:

`xname`	Return or set name of X coordinate column.
`yname`	Return or set name of Y coordinate column.
`zname`	Return or set name of Z coordinate column.
`metadata`	Return metadata object instance of type MetaDataRegularSurface.
`rkb`	Returns RKB height for the well (read only).
`xpos`	Returns well header X position (read only).
`ypos`	Returns well header Y position (read only).
`wellname`	Returns well name, read only.
`name`	Returns or set (rename) a well name.
`wname`	Returns or set (rename) a well name.
`safewellname`	Get well name on syntax safe form; '/' and spaces replaced with '_'.
`xwellname`	See safewellname.
`shortwellname`	Well name on a short form where blockname/spaces removed (read only).
`truewellname`	Returns well name on the assummed form aka '31/2-E-4 AH2'.
`mdlogname`	Returns name of MD log, if any (None if missing).
`zonelogname`	Returns or sets name of zone log, return None if missing.
`dataframe`	Returns or set the Pandas dataframe object for all logs.
`nrow`	Returns the Pandas dataframe object number of rows.
`ncol`	Returns the Pandas dataframe object number of columns.
`nlogs`	Returns the Pandas dataframe object number of columns.
`lognames_all`	Returns dataframe column names as list, including mandatory coords.
`lognames`	Returns the Pandas dataframe column as list excluding coords.
`wlogtypes`	Returns wlogtypes
`wlogrecords`	Returns wlogrecords

Public Methods:

`ensure_consistency`()	Ensure consistency for the instance.
`get_short_wellname`(wellname)	Well name on a short name form where blockname and spaces are removed.
`describe`([flush])	Describe an instance by printing to stdout.
`to_file`(wfile[, fformat])	Export well to file or memory stream.
`to_hdf`(wfile[, compression])	Export well to HDF based file.
`to_roxar`(args, *kwargs)	Export (save/store) a well to a roxar project.
`get_lognames`()	Get the lognames for all logs.
`get_wlogs`()	Get a compound dictionary with well log metadata.
`set_wlogs`(wlogs)	Set a compound dictionary with well log metadata.
`isdiscrete`(logname)	Return True of log is discrete, otherwise False.
`copy`()	Copy a Well instance to a new unique Well instance.
`rename_log`(lname, newname)	Rename a log, e.g. Poro to PORO.
`create_log`(lname[, logtype, logrecord, ...])	Create a new log with initial values.
`copy_log`(lname, newname[, force])	Copy a log from an existing to a name
`delete_log`(lname)	Delete/remove an existing log, or list of logs.
`delete_logs`(lname)	Delete/remove an existing log, or list of logs.
`get_logtype`(lname)	Returns the type of a given log (e.g. DISC or CONT), None if not present.
`set_logtype`(lname, ltype)	Sets the type of a give log (e.g. DISC or CONT).
`get_logrecord`(lname)	Returns the record (dict) of a given log name, None if not exists.
`set_logrecord`(lname, newdict)	Sets the record (dict) of a given discrete log.
`get_logrecord_codename`(lname, key)	Returns the name entry of a log record, for a given key.
`get_dataframe`([copy])	Get a copy (default) or a view of the dataframe.
`get_filled_dataframe`([fill_value, ...])	Fill the Nan's in the dataframe with real UNDEF values.
`set_dataframe`(dfr)	Set the dataframe.
`create_relative_hlen`()	Make a relative length of a well, as a log.
`geometrics`()	Compute some well geometrical arrays MD, INCL, AZI, as logs.
`truncate_parallel_path`(other[, xtol, ytol, ...])	Truncate the part of the well trajectory that is ~parallel with other.
`may_overlap`(other)	Consider if well overlap in X Y coordinates with other well, True/False.
`limit_tvd`(tvdmin, tvdmax)	Truncate the part of the well that is outside tvdmin, tvdmax.
`downsample`([interval, keeplast])	Downsample by sampling every N'th element (coarsen only).
`rescale`([delta, tvdrange])	Rescale (refine or coarse) by sampling a delta along the trajectory, in MD.
`get_polygons`([skipname])	Return a Polygons object from the well trajectory.
`get_fence_polyline`([sampling, nextend, ...])	Return a fence polyline as a numpy array or a Polygons object.
`create_surf_distance_log`(surf[, name])	Make a log that is vertical distance to a regular surface.
`report_zonation_holes`([threshold])	Reports if well has holes in zonation, less or equal to N samples.
`get_zonation_points`([tops, incl_limit, ...])	Extract zonation points from Zonelog and make a marker list.
`get_zone_interval`(zonevalue[, resample, ...])	Extract the X Y Z ID line (polyline) segment for a given zonevalue.
`get_fraction_per_zone`(dlogname, dcodes[, ...])	Get fraction of a discrete parameter, e.g. a facies, per zone.
`mask_shoulderbeds`(inputlogs, targetlogs[, ...])	Mask data around zone boundaries or other discrete log boundaries.
`get_surface_picks`(surf)	Return `Points` obj where well crosses the surface (horizon picks).
`make_ijk_from_grid`(grid[, grid_id, ...])	Look through a Grid and add grid I J K as discrete logs.
`make_zone_qual_log`(zqname)	Create a zone quality/indicator (flag) log.
`get_gridproperties`(gridprops[, grid, prop_id])	Look through a Grid and add a set of grid properties as logs.

__init__(rkb=0.0, xpos=0.0, ypos=0.0, wname='', df=None, mdlogname=None, zonelogname=None, wlogtypes=None, wlogrecords=None, filesrc=None)[source]

copy()[source]: Copy a Well instance to a new unique Well instance.

copy_log(lname, newname, force=True)[source]

Copy a log from an existing to a name

If the new log already exists, it will be silently overwritten, unless the option force=False.

Parameters:

lname (str) – name of existing log
newname (str) – name of new log

Return type:

bool

Returns:

True if a new log is made (either new or force overwrite an existing) or False if the new log already exists, and force=False.

Note:

A copy can also be done directly in the dataframe, but with less
consistency checks; hence this method is recommended

create_log(lname, logtype='CONT', logrecord=None, value=0.0, force=True)[source]

Create a new log with initial values.

If the logname already exists, it will be silently overwritten, unless the option force=False.

Parameters:

lname (str) – name of new log
logtype (str) – Must be ‘CONT’ (default) or ‘DISC’ (discrete)
logrecord (dict | None) – A dictionary of key: values for ‘DISC’ logs
value (float) – initial value to set
force (bool) – If True, and lname exists, it will be overwritten, if False, no new log will be made. Will return False.

Return type:

bool

Returns:

True ff a new log is made (either new or force overwrite an existing) or False if the new log already exists, and force=False.

Note:

A new log can also be created by adding it to the dataframe directly, but
with less control over e.g. logrecord

create_relative_hlen()[source]

Make a relative length of a well, as a log.

The first well og entry defines zero, then the horizontal length is computed relative to that by simple geometric methods.

create_surf_distance_log(surf, name='DIST_SURF')[source]

Make a log that is vertical distance to a regular surface.

If the trajectory is above the surface (i.e. more shallow), then the distance sign is positive.

Parameters:

surf (object) – The RegularSurface instance.
name (str | None) – The name of the new log. If it exists it will be overwritten.

Example:

mywell.rescale()  # optional
thesurf = xtgeo.surface_from_file("some.gri")
mywell.create_surf_distance_log(thesurf, name="sdiff")

property dataframe: Returns or set the Pandas dataframe object for all logs.

delete_log(lname)[source]

Delete/remove an existing log, or list of logs.

Will continue silently if a log does not exist.

Parameters:: lname (str | list[str]) – A logname or a list of lognames
Return type:: int
Returns:: Number of logs deleted

Note:

A log can also be deleted by simply removing it from the dataframe.

delete_logs(lname)

Delete/remove an existing log, or list of logs.

Will continue silently if a log does not exist.

Parameters:: lname (str | list[str]) – A logname or a list of lognames
Return type:: int
Returns:: Number of logs deleted

Note:

A log can also be deleted by simply removing it from the dataframe.

describe(flush=True)[source]: Describe an instance by printing to stdout.

downsample(interval=4, keeplast=True)[source]

Downsample by sampling every N’th element (coarsen only).

Parameters:

interval (int) – Sampling interval.
keeplast (bool) – If True, the last element from the original dataframe is kept, to avoid that the well is shortened.

ensure_consistency()[source]: Ensure consistency for the instance.

Added in version 3.5.

geometrics()[source]

Compute some well geometrical arrays MD, INCL, AZI, as logs.

These are kind of quasi measurements hence the logs will named with a Q in front as Q_MDEPTH, Q_INCL, and Q_AZI.

These logs will be added to the dataframe. If the mdlogname attribute does not exist in advance, it will be set to ‘Q_MDEPTH’.

Returns:: False if geometrics cannot be computed

get_dataframe(copy=True)[source]

Get a copy (default) or a view of the dataframe.

Parameters:: copy (bool) – If True, return a deep copy. A view (copy=False) will be faster and more memory efficient, but less “safe” for some cases when manipulating dataframes.

Changed in version 3.7: Added copy keyword

get_fence_polyline(sampling=20, nextend=2, tvdmin=None, asnumpy=True)[source]

Return a fence polyline as a numpy array or a Polygons object.

The result will aim for a regular sampling interval, useful for extracting fence plots (cross-sections).

Parameters:

sampling (float) – Sampling interval i.e. horizonal distance (input)
nextend (int) – Number if sampling to extend; e.g. 2 * 20
tvdmin (float) – Minimum TVD starting point.
as_numpy (bool) – If True, a numpy array, otherwise a Polygons object with 5 columns where the 2 last are HLEN and POLY_ID and the POLY_ID will be set to 0.

Returns:

A numpy array of shape (NLEN, 5) in F order, Or a Polygons object with 5 columns If not possible, return False

Changed in version 2.1: improved algorithm

get_filled_dataframe(fill_value=1e+33, fill_value_int=2000000000)[source]

Fill the Nan’s in the dataframe with real UNDEF values.

This module returns a copy of the dataframe in the object; it does not change the instance.

Note that DISC logs will be casted to columns with integer as datatype.

Returns:

A pandas dataframe where Nan er replaces with preset: high XTGeo UNDEF values, or user defined values.

get_fraction_per_zone(dlogname, dcodes, zonelist=None, incl_limit=80, count_limit=3, zonelogname=None)[source]

Get fraction of a discrete parameter, e.g. a facies, per zone.

It can be constrained by an inclination.

Also, it needs to be evaluated only of ZONE is complete; either INCREASE or DECREASE ; hence a quality flag is made and applied.

Parameters:

dlogname (str) – Name of discrete log, e.g. ‘FACIES’
dnames (list of int) – Codes of facies (or similar) to report for
zonelist (list of int) – Zones to use
incl_limit (float) – Inclination limit for well path.
count_limit (int) – Minimum number of counts required per segment for valid calculations
zonelogname (str). If None, the Well() – applied

Returns:

A pandas dataframe (ready for the xyz/Points class), None if a zonelog is missing or or dlogname is missing, list is zero length for any reason.

get_gridproperties(gridprops, grid=('ICELL', 'JCELL', 'KCELL'), prop_id='_model')[source]

Look through a Grid and add a set of grid properties as logs.

The name of the logs will …

This can be done to sample model properties along a well.

Parameters:

gridprops (Grid) – A XTGeo GridProperties instance (a collection of properties) or a single GridProperty instance
grid (Grid or tuple) – A XTGeo Grid instance or a reference via tuple. If this is tuple with log names, it states that these logs already contains the gridcell IJK numbering.
prop_id (str) – Add a tag (optional) to the current log name, e.g as PORO_model, where _model is the tag.

Raises:

None –

Added in version 2.1.

get_lognames()[source]: Get the lognames for all logs.

get_logrecord(lname)[source]: Returns the record (dict) of a given log name, None if not exists.

get_logrecord_codename(lname, key)[source]

Returns the name entry of a log record, for a given key.

Example:

# get the name for zonelog entry no 4:
zname = well.get_logrecord_codename('ZONELOG', 4)

get_logtype(lname)[source]

Returns the type of a given log (e.g. DISC or CONT), None if not present.

Return type:: str | None

get_polygons(skipname=False)[source]

Return a Polygons object from the well trajectory.

Parameters:: skipname (bool) – If True then name column is omitted

Added in version 2.1.

Changed in version 2.13: Added skipname key

static get_short_wellname(wellname)[source]

Well name on a short name form where blockname and spaces are removed.

This should cope with both North Sea style and Haltenbanken style. E.g.: ‘31/2-G-5 AH’ -> ‘G-5AH’, ‘6472_11-F-23_AH_T2’ -> ‘F-23AHT2’

get_surface_picks(surf)[source]

Return Points obj where well crosses the surface (horizon picks).

There may be several points in the Points() dataframe attribute. Also a DIRECTION column will show 1 if surface is penetrated from above, and -1 if penetrated from below.

Parameters:: surf (RegularSurface) – The surface instance
Returns:: A Points instance, or None if no crossing points

Added in version 2.8.

get_wlogs()[source]

Get a compound dictionary with well log metadata.

The result will be an dict on the form:

{"X_UTME": ["CONT", None], ... "Facies": ["DISC", {1: "BG", 2: "SAND"}]}

Return type:: dict

get_zonation_points(tops=True, incl_limit=80, top_prefix='Top', zonelist=None, use_undef=False)[source]

Extract zonation points from Zonelog and make a marker list.

Currently it is either ‘Tops’ or ‘Zone’ (thicknesses); default is tops (i.e. tops=True).

The zonelist can be a list of zones, or a tuple with two members specifying first and last member. Note however that the zonation shall be without jumps and increasing. E.g.:

zonelist=(1, 5)  # meaning [1, 2, 3, 4, 5]
# or
zonelist=[1, 2, 3, 4]
# while _not_ legal:
zonelist=[1, 4, 8]

Zone numbers less than 0 are not accepted

Parameters:

tops (bool) – If True then compute tops, else (thickness) points.
incl_limit (float) – If given, and usezone is True, the max angle of inclination to be used as input to zonation points.
top_prefix (str) – As well logs usually have isochore (zone) name, this prefix could be Top, e.g. ‘SO43’ –> ‘TopSO43’
zonelist (list of int or tuple) – Zones to use
use_undef (bool) – If True, then transition from UNDEF is also used.

Returns:

A pandas dataframe (ready for the xyz/Points class), None if a zonelog is missing

get_zone_interval(zonevalue, resample=1, extralogs=None)[source]

Extract the X Y Z ID line (polyline) segment for a given zonevalue.

Parameters:

zonevalue (int) – The zone value to extract
resample (int) – If given, downsample every N’th sample to make polylines smaller in terms of bit and bytes. 1 = No downsampling.
extralogs (list of str) – List of extra log names to include

Returns:

A pandas dataframe X Y Z ID (ready for the xyz/Polygon class), None if a zonelog is missing or actual zone does dot exist in the well.

isdiscrete(logname)[source]

Return True of log is discrete, otherwise False.

Parameters:: logname (str) – Name of log to check if discrete or not

Added in version 2.2.0.

limit_tvd(tvdmin, tvdmax)[source]

Truncate the part of the well that is outside tvdmin, tvdmax.

Range will be in tvdmin <= tvd <= tvdmax.

Parameters:

tvdmin (float) – Minimum TVD
tvdmax (float) – Maximum TVD

property lognames

Returns the Pandas dataframe column as list excluding coords.

Type:: list

property lognames_all

Returns dataframe column names as list, including mandatory coords.

Type:: list

make_ijk_from_grid(grid, grid_id='', algorithm=2, activeonly=True)[source]

Look through a Grid and add grid I J K as discrete logs.

Note that the the grid counting has base 1 (first row is 1 etc).

By default, log (i.e. column names in the dataframe) will be ICELL, JCELL, KCELL, but you can add a tag (ID) to that name.

Parameters:

grid (Grid) – A XTGeo Grid instance
grid_id (str) – Add a tag (optional) to the current log name
algorithm (int) – Which interbal algorithm to use, default is 2 (expert setting)
activeonly (bool) – If True, only active cells are applied (algorithm 2 only)

Raises:

RuntimeError – ‘Error from C routine, code is …’

Changed in version 2.9: Added keys for and activeonly

make_zone_qual_log(zqname)[source]

Create a zone quality/indicator (flag) log.

This routine looks through to zone log and flag intervals according to neighbouring zones:

0: Undetermined flag
1: Zonelog interval numbering increases,
e.g. for zone 2: 1 1 1 1 2 2 2 2 2 5 5 5 5 5
2: Zonelog interval numbering decreases,
e.g. for zone 2: 6 6 6 2 2 2 2 1 1 1
3: Interval is a U turning point, e.g. 0 0 0 2 2 2 1 1 1
4: Interval is a inverse U turning point, 3 3 3 2 2 2 5 5
9: Interval is bounded by one or more missing sections,
e.g. 1 1 1 2 2 2 -999 -999

If a log with the name exists, it will be silently replaced

Parameters:: zqname (str) – Name of quality log

mask_shoulderbeds(inputlogs, targetlogs, nsamples=2, strict=False)[source]

Mask data around zone boundaries or other discrete log boundaries.

This operates on number of samples, hence the actual distance which is masked depends on the sampling interval (ie. count) or on distance measures. Distance measures are TVD (true vertical depth) or MD (measured depth).

Parameters:

inputlogs (list[str]) – List of input logs, must be of discrete type.
targetlogs (list[str]) – List of logs where mask is applied.
nsamples (int | dict[str, float] | None) – Number of samples around boundaries to filter, per side, i.e. value 2 means 2 above and 2 below, in total 4 samples. As alternative specify nsamples indirectly with a relative distance, as a dictionary with one record, as {“tvd”: 0.5} or {“md”: 0.7}.
strict (bool | None) – If True, will raise Exception of any of the input or target log names are missing.

Return type:

bool

Returns:

True if any operation has been done. False in case nothing has been done,: e.g. no targetlogs for this particular well and strict is False.

Raises:

ValueError – Various messages when wrong or inconsistent input.

Example

>>> mywell1 = Well(well_dir + '/OP_1.w')
>>> mywell2 = Well(well_dir + '/OP_2.w')
>>> did_succeed = mywell1.mask_shoulderbeds(["Zonelog", "Facies"], ["Perm"])
>>> did_succeed = mywell2.mask_shoulderbeds(
...     ["Zonelog"],
...     ["Perm"],
...     nsamples={"tvd": 0.8}
... )

may_overlap(other)[source]: Consider if well overlap in X Y coordinates with other well, True/False.

property mdlogname

Returns name of MD log, if any (None if missing).

Type:: str

property metadata: Return metadata object instance of type MetaDataRegularSurface.

property name: Returns or set (rename) a well name.

property ncol

Returns the Pandas dataframe object number of columns.

Type:: int

property nlogs

Returns the Pandas dataframe object number of columns.

Type:: int

property nrow

Returns the Pandas dataframe object number of rows.

Type:: int

rename_log(lname, newname)[source]: Rename a log, e.g. Poro to PORO.

report_zonation_holes(threshold=5)[source]

Reports if well has holes in zonation, less or equal to N samples.

Zonation may have holes due to various reasons, and usually a few undef samples indicates that something is wrong. This method reports well and start interval of the “holes”

The well shall have zonelog from import (via zonelogname attribute) and preferly a MD log (via mdlogname attribute); however if the latter is not present, a report withou MD values will be present.

Parameters:: threshold (int) – Number of samples (max.) that defines a hole, e.g. 5 means that undef samples in the range [1, 5] (including 5) is applied
Returns:: A Pandas dataframe as a report. None if no list is made.
Raises:: RuntimeError if zonelog is not present –

rescale(delta=0.15, tvdrange=None)[source]

Rescale (refine or coarse) by sampling a delta along the trajectory, in MD.

Parameters:

delta (float) – Step length
tvdrange (tuple of floats) – Resampling can be limited to TVD interval

Changed in version 2.2: Added tvdrange

property rkb: Returns RKB height for the well (read only).

property safewellname: Get well name on syntax safe form; ‘/’ and spaces replaced with ‘_’.

set_dataframe(dfr)[source]: Set the dataframe.

set_logrecord(lname, newdict)[source]: Sets the record (dict) of a given discrete log.

set_logtype(lname, ltype)[source]: Sets the type of a give log (e.g. DISC or CONT).

set_wlogs(wlogs)[source]

Set a compound dictionary with well log metadata.

This operation is somewhat risky as it may lead to inconsistency, so use with care! Typically, one will use get_wlogs() first and then modify some attributes.

Parameters:

wlogs (dict) – Input data dictionary

Raises:

ValueError – Invalid log type found in input:
ValueError – Invalid log record found in input:
ValueError – Invalid input key found:
ValueError – Invalid log record found in input:

property shortwellname

Well name on a short form where blockname/spaces removed (read only).

This should cope with both North Sea style and Haltenbanken style.

E.g.: ‘31/2-G-5 AH’ -> ‘G-5AH’, ‘6472_11-F-23_AH_T2’ -> ‘F-23AHT2’

Type:: str

to_file(wfile, fformat='rms_ascii')[source]

Export well to file or memory stream.

Parameters:

wfile (str | Path | BytesIO) – File name or stream.
fformat (str | None) – File format (‘rms_ascii’/’rmswell’, ‘hdf/hdf5/h5’).

Example:

>>> xwell = Well(well_dir + '/OP_1.w')
>>> dfr = xwell.get_dataframe()
>>> dfr['Poro'] += 0.1
>>> xwell.set_dataframe(dfr)
>>> filename = xwell.to_file(outdir + "/somefile_copy.rmswell")

to_hdf(wfile, compression='lzf')[source]

Export well to HDF based file.

Warning

This implementation is currently experimental and only recommended for testing.

Parameters:: wfile (str | Path) – HDF File name to write to export to.
Return type:: Path
Returns:: A Path instance to actual file applied.

Added in version 2.14.

to_roxar(*args, **kwargs)[source]

Export (save/store) a well to a roxar project.

Note this method works only when inside RMS, or when RMS license is activated in terminal.

The current implementation will either update the existing well (then well log array size must not change), or it will make a new well in RMS.

Parameters:

project (str, object) – Magic string ‘project’ or file path to project
wname (str) – Name of well, as shown in RMS.
( (lognames) – obj:list or :obj:str): List of lognames to save, or use simply ‘all’ for current logs for this well. Default is ‘all’
realisation (int) – Currently inactive
trajectory (str) – Name of trajectory in RMS, default is “Drilled trajectory”
logrun (str) – Name of logrun in RMS, defaault is “log”
update_option (str) – None | “overwrite” | “append”. This only applies when the well (wname) exists in RMS, and rules are based on name matching. Default is None which means that all well logs in RMS are emptied and then replaced with the content from xtgeo. The “overwrite” option will replace logs in RMS with logs from xtgeo, and append new if they do not exist in RMS. The “append” option will only append logs if name does not exist in RMS already. Reading only a subset of logs and then use “overwrite” or “append” may speed up execution significantly.

Note

When project is file path (direct access, outside RMS) then to_roxar() will implicitly do a project save. Otherwise, the project will not be saved until the user do an explicit project save action.

Example:

# assume that existing logs in RMS are ["PORO", "PERMH", "GR", "DT", "FAC"]
# read only one existing log (faster)

wll = xtgeo.well_from_roxar(project, "WELL1", lognames=["PORO"])
dfr = wll.get_dataframe()
dfr["PORO"] += 0.2  # add 0.2 to PORO log
wll.set_dataframe(dfr)
wll.create_log("NEW", value=0.333)  # create a new log with constant value

# the "option" is a variable... for output, ``lognames="all"`` is default
if option is None:
    # remove all current logs in RMS; only logs will be PORO and NEW
    wll.to_roxar(project, "WELL1", update_option=option)
elif option == "overwrite":
    # keep all original logs but update PORO and add NEW
    wll.to_roxar(project, "WELL1", update_option=option)
elif option == "append":
    # keep all original logs as they were (incl. PORO) and add NEW
    wll.to_roxar(project, "WELL1", update_option=option)

Note

The keywords lognames and update_option will interact

Added in version 2.12.

Changed in version 2.15: Saving to new wells enabled (earlier only modifying existing)

Changed in version 3.5: Add key update_option

property truewellname: Returns well name on the assummed form aka ‘31/2-E-4 AH2’.

truncate_parallel_path(other, xtol=None, ytol=None, ztol=None, itol=None, atol=None)[source]

Truncate the part of the well trajectory that is ~parallel with other.

Parameters:

other (Well) – Other well to compare with
xtol (float) – Tolerance in X (East) coord for measuring unit
ytol (float) – Tolerance in Y (North) coord for measuring unit
ztol (float) – Tolerance in Z (TVD) coord for measuring unit
itol (float) – Tolerance in inclination (degrees)
atol (float) – Tolerance in azimuth (degrees)

property wellname

Returns well name, read only.

Type:: str

property wlogrecords: Returns wlogrecords

property wlogtypes: Returns wlogtypes

property wname: Returns or set (rename) a well name.

property xname: Return or set name of X coordinate column.

property xpos: Returns well header X position (read only).

property xwellname: See safewellname.

property yname: Return or set name of Y coordinate column.

property ypos: Returns well header Y position (read only).

property zname: Return or set name of Z coordinate column.

property zonelogname

Returns or sets name of zone log, return None if missing.

Type:: str

Wells (multiple)

Classes

class xtgeo.Wells(wells=None)[source]

Bases: object

Class for a collection of Well objects, for operations that involves a number of wells.

Blocked well (single)

Functions

xtgeo.blockedwell_from_file(bwfile, fformat='rms_ascii', mdlogname=None, zonelogname=None, strict=False)[source]

Make an instance of a BlockedWell directly from file import.

Parameters:

bmfile (str) – Name of file
fformat (str) – See Well.from_file()
mdlogname (str) – See Well.from_file()
zonelogname (str) – See Well.from_file()
strict (bool) – See Well.from_file()

Example:

>>> import xtgeo
>>> well3 = xtgeo.blockedwell_from_file(well_dir + '/OP_1.bw')

xtgeo.blockedwell_from_roxar(project, gname, bwname, wname, lognames=None, ijk=True, realisation=0)[source]

This makes an instance of a BlockedWell directly from Roxar RMS.

For arguments, see BlockedWell.from_roxar().

Example:

# inside RMS:
import xtgeo
mylogs = ['ZONELOG', 'GR', 'Facies']
mybw = xtgeo.blockedwell_from_roxar(project, 'Simgrid', 'BW', '31_3-1',
                                    lognames=mylogs)

Classes

class xtgeo.BlockedWell(*args, **kwargs)[source]

Bases: Well

Class for a blocked well in the XTGeo framework, subclassed from the Well class.

Similar to Wells, the blocked well logs are stored as Pandas dataframe, which make manipulation easy and fast.

For blocked well logs, the numbers of rows cannot be changed if you want to save the result in RMS, as this is derived from the grid. Also the blocked well icon must exist before save.

The well trajectory are here represented as logs, and XYZ have magic names as default: X_UTME, Y_UTMN, Z_TVDSS, which are the three first Pandas columns.

Other geometry logs has also ‘semi-magic’ names:

M_MDEPTH or Q_MDEPTH: Measured depth, either real/true (M…) or quasi computed/estimated (Q…). The Quasi computations may be incorrect for all uses, but sufficient for some computations.

Similar for M_INCL, Q_INCL, M_AZI, Q_AZI.

I_INDEX, J_INDEX, K_INDEX: They are grid indices. For practical reasons they are treated as a CONT logs, since the min/max grid indices usually are unknown, and hence making a code index is not trivial.

All Pandas values (yes, discrete also!) are stored as float32 or float64 format, and undefined values are Nan. Integers are stored as Float due to the lacking support for ‘Integer Nan’ (currently lacking in Pandas, but may come in later Pandas versions).

Note there is a method that can return a dataframe (copy) with Integer and Float columns, see get_filled_dataframe().

The instance can be made either from file or:

>>> well1 = xtgeo.blockedwell_from_file(well_dir + '/OP_1.bw')  # RMS ascii well

If in RMS, instance can be made also from RMS icon:

well4 = xtgeo.blockedwell_from_roxar(
    project,
    'gridname',
    'bwname',
    'wellname',
)

Public Data Attributes:

gridname

Returns or set (rename) the grid name that the blocked wells belongs to.

Inherited from Well

`xname`	Return or set name of X coordinate column.
`yname`	Return or set name of Y coordinate column.
`zname`	Return or set name of Z coordinate column.
`metadata`	Return metadata object instance of type MetaDataRegularSurface.
`rkb`	Returns RKB height for the well (read only).
`xpos`	Returns well header X position (read only).
`ypos`	Returns well header Y position (read only).
`wellname`	Returns well name, read only.
`name`	Returns or set (rename) a well name.
`wname`	Returns or set (rename) a well name.
`safewellname`	Get well name on syntax safe form; '/' and spaces replaced with '_'.
`xwellname`	See safewellname.
`shortwellname`	Well name on a short form where blockname/spaces removed (read only).
`truewellname`	Returns well name on the assummed form aka '31/2-E-4 AH2'.
`mdlogname`	Returns name of MD log, if any (None if missing).
`zonelogname`	Returns or sets name of zone log, return None if missing.
`dataframe`	Returns or set the Pandas dataframe object for all logs.
`nrow`	Returns the Pandas dataframe object number of rows.
`ncol`	Returns the Pandas dataframe object number of columns.
`nlogs`	Returns the Pandas dataframe object number of columns.
`lognames_all`	Returns dataframe column names as list, including mandatory coords.
`lognames`	Returns the Pandas dataframe column as list excluding coords.
`wlogtypes`	Returns wlogtypes
`wlogrecords`	Returns wlogrecords

Public Methods:

`copy`()	Copy a Well instance to a new unique Well instance.
`to_roxar`(args, *kwargs)	Set (export) a single blocked well item inside roxar project.

Inherited from Well

`ensure_consistency`()	Ensure consistency for the instance.
`get_short_wellname`(wellname)	Well name on a short name form where blockname and spaces are removed.
`describe`([flush])	Describe an instance by printing to stdout.
`to_file`(wfile[, fformat])	Export well to file or memory stream.
`to_hdf`(wfile[, compression])	Export well to HDF based file.
`to_roxar`(args, *kwargs)	Export (save/store) a well to a roxar project.
`get_lognames`()	Get the lognames for all logs.
`get_wlogs`()	Get a compound dictionary with well log metadata.
`set_wlogs`(wlogs)	Set a compound dictionary with well log metadata.
`isdiscrete`(logname)	Return True of log is discrete, otherwise False.
`copy`()	Copy a Well instance to a new unique Well instance.
`rename_log`(lname, newname)	Rename a log, e.g. Poro to PORO.
`create_log`(lname[, logtype, logrecord, ...])	Create a new log with initial values.
`copy_log`(lname, newname[, force])	Copy a log from an existing to a name
`delete_log`(lname)	Delete/remove an existing log, or list of logs.
`delete_logs`(lname)	Delete/remove an existing log, or list of logs.
`get_logtype`(lname)	Returns the type of a given log (e.g. DISC or CONT), None if not present.
`set_logtype`(lname, ltype)	Sets the type of a give log (e.g. DISC or CONT).
`get_logrecord`(lname)	Returns the record (dict) of a given log name, None if not exists.
`set_logrecord`(lname, newdict)	Sets the record (dict) of a given discrete log.
`get_logrecord_codename`(lname, key)	Returns the name entry of a log record, for a given key.
`get_dataframe`([copy])	Get a copy (default) or a view of the dataframe.
`get_filled_dataframe`([fill_value, ...])	Fill the Nan's in the dataframe with real UNDEF values.
`set_dataframe`(dfr)	Set the dataframe.
`create_relative_hlen`()	Make a relative length of a well, as a log.
`geometrics`()	Compute some well geometrical arrays MD, INCL, AZI, as logs.
`truncate_parallel_path`(other[, xtol, ytol, ...])	Truncate the part of the well trajectory that is ~parallel with other.
`may_overlap`(other)	Consider if well overlap in X Y coordinates with other well, True/False.
`limit_tvd`(tvdmin, tvdmax)	Truncate the part of the well that is outside tvdmin, tvdmax.
`downsample`([interval, keeplast])	Downsample by sampling every N'th element (coarsen only).
`rescale`([delta, tvdrange])	Rescale (refine or coarse) by sampling a delta along the trajectory, in MD.
`get_polygons`([skipname])	Return a Polygons object from the well trajectory.
`get_fence_polyline`([sampling, nextend, ...])	Return a fence polyline as a numpy array or a Polygons object.
`create_surf_distance_log`(surf[, name])	Make a log that is vertical distance to a regular surface.
`report_zonation_holes`([threshold])	Reports if well has holes in zonation, less or equal to N samples.
`get_zonation_points`([tops, incl_limit, ...])	Extract zonation points from Zonelog and make a marker list.
`get_zone_interval`(zonevalue[, resample, ...])	Extract the X Y Z ID line (polyline) segment for a given zonevalue.
`get_fraction_per_zone`(dlogname, dcodes[, ...])	Get fraction of a discrete parameter, e.g. a facies, per zone.
`mask_shoulderbeds`(inputlogs, targetlogs[, ...])	Mask data around zone boundaries or other discrete log boundaries.
`get_surface_picks`(surf)	Return `Points` obj where well crosses the surface (horizon picks).
`make_ijk_from_grid`(grid[, grid_id, ...])	Look through a Grid and add grid I J K as discrete logs.
`make_zone_qual_log`(zqname)	Create a zone quality/indicator (flag) log.
`get_gridproperties`(gridprops[, grid, prop_id])	Look through a Grid and add a set of grid properties as logs.

__init__(*args, **kwargs)[source]

copy()[source]: Copy a Well instance to a new unique Well instance.

copy_log(lname, newname, force=True)

Copy a log from an existing to a name

If the new log already exists, it will be silently overwritten, unless the option force=False.

Parameters:

lname (str) – name of existing log
newname (str) – name of new log

Return type:

bool

Returns:

True if a new log is made (either new or force overwrite an existing) or False if the new log already exists, and force=False.

Note:

A copy can also be done directly in the dataframe, but with less
consistency checks; hence this method is recommended

create_log(lname, logtype='CONT', logrecord=None, value=0.0, force=True)

Create a new log with initial values.

If the logname already exists, it will be silently overwritten, unless the option force=False.

Parameters:

lname (str) – name of new log
logtype (str) – Must be ‘CONT’ (default) or ‘DISC’ (discrete)
logrecord (dict | None) – A dictionary of key: values for ‘DISC’ logs
value (float) – initial value to set
force (bool) – If True, and lname exists, it will be overwritten, if False, no new log will be made. Will return False.

Return type:

bool

Returns:

True ff a new log is made (either new or force overwrite an existing) or False if the new log already exists, and force=False.

Note:

A new log can also be created by adding it to the dataframe directly, but
with less control over e.g. logrecord

create_relative_hlen()

Make a relative length of a well, as a log.

The first well og entry defines zero, then the horizontal length is computed relative to that by simple geometric methods.

create_surf_distance_log(surf, name='DIST_SURF')

Make a log that is vertical distance to a regular surface.

If the trajectory is above the surface (i.e. more shallow), then the distance sign is positive.

Parameters:

surf (object) – The RegularSurface instance.
name (str | None) – The name of the new log. If it exists it will be overwritten.

Example:

mywell.rescale()  # optional
thesurf = xtgeo.surface_from_file("some.gri")
mywell.create_surf_distance_log(thesurf, name="sdiff")

property dataframe: Returns or set the Pandas dataframe object for all logs.

delete_log(lname)

Delete/remove an existing log, or list of logs.

Will continue silently if a log does not exist.

Parameters:: lname (str | list[str]) – A logname or a list of lognames
Return type:: int
Returns:: Number of logs deleted

Note:

A log can also be deleted by simply removing it from the dataframe.

delete_logs(lname)

Delete/remove an existing log, or list of logs.

Will continue silently if a log does not exist.

Parameters:: lname (str | list[str]) – A logname or a list of lognames
Return type:: int
Returns:: Number of logs deleted

Note:

A log can also be deleted by simply removing it from the dataframe.

describe(flush=True): Describe an instance by printing to stdout.

downsample(interval=4, keeplast=True)

Downsample by sampling every N’th element (coarsen only).

Parameters:

interval (int) – Sampling interval.
keeplast (bool) – If True, the last element from the original dataframe is kept, to avoid that the well is shortened.

ensure_consistency(): Ensure consistency for the instance.

Added in version 3.5.

geometrics()

Compute some well geometrical arrays MD, INCL, AZI, as logs.

These are kind of quasi measurements hence the logs will named with a Q in front as Q_MDEPTH, Q_INCL, and Q_AZI.

These logs will be added to the dataframe. If the mdlogname attribute does not exist in advance, it will be set to ‘Q_MDEPTH’.

Returns:: False if geometrics cannot be computed

get_dataframe(copy=True)

Get a copy (default) or a view of the dataframe.

Parameters:: copy (bool) – If True, return a deep copy. A view (copy=False) will be faster and more memory efficient, but less “safe” for some cases when manipulating dataframes.

Changed in version 3.7: Added copy keyword

get_fence_polyline(sampling=20, nextend=2, tvdmin=None, asnumpy=True)

Return a fence polyline as a numpy array or a Polygons object.

The result will aim for a regular sampling interval, useful for extracting fence plots (cross-sections).

Parameters:

sampling (float) – Sampling interval i.e. horizonal distance (input)
nextend (int) – Number if sampling to extend; e.g. 2 * 20
tvdmin (float) – Minimum TVD starting point.
as_numpy (bool) – If True, a numpy array, otherwise a Polygons object with 5 columns where the 2 last are HLEN and POLY_ID and the POLY_ID will be set to 0.

Returns:

A numpy array of shape (NLEN, 5) in F order, Or a Polygons object with 5 columns If not possible, return False

Changed in version 2.1: improved algorithm

get_filled_dataframe(fill_value=1e+33, fill_value_int=2000000000)

Fill the Nan’s in the dataframe with real UNDEF values.

This module returns a copy of the dataframe in the object; it does not change the instance.

Note that DISC logs will be casted to columns with integer as datatype.

Returns:

A pandas dataframe where Nan er replaces with preset: high XTGeo UNDEF values, or user defined values.

get_fraction_per_zone(dlogname, dcodes, zonelist=None, incl_limit=80, count_limit=3, zonelogname=None)

Get fraction of a discrete parameter, e.g. a facies, per zone.

It can be constrained by an inclination.

Also, it needs to be evaluated only of ZONE is complete; either INCREASE or DECREASE ; hence a quality flag is made and applied.

Parameters:

dlogname (str) – Name of discrete log, e.g. ‘FACIES’
dnames (list of int) – Codes of facies (or similar) to report for
zonelist (list of int) – Zones to use
incl_limit (float) – Inclination limit for well path.
count_limit (int) – Minimum number of counts required per segment for valid calculations
zonelogname (str). If None, the Well() – applied

Returns:

A pandas dataframe (ready for the xyz/Points class), None if a zonelog is missing or or dlogname is missing, list is zero length for any reason.

get_gridproperties(gridprops, grid=('ICELL', 'JCELL', 'KCELL'), prop_id='_model')

Look through a Grid and add a set of grid properties as logs.

The name of the logs will …

This can be done to sample model properties along a well.

Parameters:

gridprops (Grid) – A XTGeo GridProperties instance (a collection of properties) or a single GridProperty instance
grid (Grid or tuple) – A XTGeo Grid instance or a reference via tuple. If this is tuple with log names, it states that these logs already contains the gridcell IJK numbering.
prop_id (str) – Add a tag (optional) to the current log name, e.g as PORO_model, where _model is the tag.

Raises:

None –

Added in version 2.1.

get_lognames(): Get the lognames for all logs.

get_logrecord(lname): Returns the record (dict) of a given log name, None if not exists.

get_logrecord_codename(lname, key)

Returns the name entry of a log record, for a given key.

Example:

# get the name for zonelog entry no 4:
zname = well.get_logrecord_codename('ZONELOG', 4)

get_logtype(lname)

Returns the type of a given log (e.g. DISC or CONT), None if not present.

Return type:: str | None

get_polygons(skipname=False)

Return a Polygons object from the well trajectory.

Parameters:: skipname (bool) – If True then name column is omitted

Added in version 2.1.

Changed in version 2.13: Added skipname key

static get_short_wellname(wellname)

Well name on a short name form where blockname and spaces are removed.

This should cope with both North Sea style and Haltenbanken style. E.g.: ‘31/2-G-5 AH’ -> ‘G-5AH’, ‘6472_11-F-23_AH_T2’ -> ‘F-23AHT2’

get_surface_picks(surf)

Return Points obj where well crosses the surface (horizon picks).

There may be several points in the Points() dataframe attribute. Also a DIRECTION column will show 1 if surface is penetrated from above, and -1 if penetrated from below.

Parameters:: surf (RegularSurface) – The surface instance
Returns:: A Points instance, or None if no crossing points

Added in version 2.8.

get_wlogs()

Get a compound dictionary with well log metadata.

The result will be an dict on the form:

{"X_UTME": ["CONT", None], ... "Facies": ["DISC", {1: "BG", 2: "SAND"}]}

Return type:: dict

get_zonation_points(tops=True, incl_limit=80, top_prefix='Top', zonelist=None, use_undef=False)

Extract zonation points from Zonelog and make a marker list.

Currently it is either ‘Tops’ or ‘Zone’ (thicknesses); default is tops (i.e. tops=True).

The zonelist can be a list of zones, or a tuple with two members specifying first and last member. Note however that the zonation shall be without jumps and increasing. E.g.:

zonelist=(1, 5)  # meaning [1, 2, 3, 4, 5]
# or
zonelist=[1, 2, 3, 4]
# while _not_ legal:
zonelist=[1, 4, 8]

Zone numbers less than 0 are not accepted

Parameters:

tops (bool) – If True then compute tops, else (thickness) points.
incl_limit (float) – If given, and usezone is True, the max angle of inclination to be used as input to zonation points.
top_prefix (str) – As well logs usually have isochore (zone) name, this prefix could be Top, e.g. ‘SO43’ –> ‘TopSO43’
zonelist (list of int or tuple) – Zones to use
use_undef (bool) – If True, then transition from UNDEF is also used.

Returns:

A pandas dataframe (ready for the xyz/Points class), None if a zonelog is missing

get_zone_interval(zonevalue, resample=1, extralogs=None)

Extract the X Y Z ID line (polyline) segment for a given zonevalue.

Parameters:

zonevalue (int) – The zone value to extract
resample (int) – If given, downsample every N’th sample to make polylines smaller in terms of bit and bytes. 1 = No downsampling.
extralogs (list of str) – List of extra log names to include

Returns:

A pandas dataframe X Y Z ID (ready for the xyz/Polygon class), None if a zonelog is missing or actual zone does dot exist in the well.

property gridname: Returns or set (rename) the grid name that the blocked wells belongs to.

isdiscrete(logname)

Return True of log is discrete, otherwise False.

Parameters:: logname (str) – Name of log to check if discrete or not

Added in version 2.2.0.

limit_tvd(tvdmin, tvdmax)

Truncate the part of the well that is outside tvdmin, tvdmax.

Range will be in tvdmin <= tvd <= tvdmax.

Parameters:

tvdmin (float) – Minimum TVD
tvdmax (float) – Maximum TVD

property lognames

Returns the Pandas dataframe column as list excluding coords.

Type:: list

property lognames_all

Returns dataframe column names as list, including mandatory coords.

Type:: list

make_ijk_from_grid(grid, grid_id='', algorithm=2, activeonly=True)

Look through a Grid and add grid I J K as discrete logs.

Note that the the grid counting has base 1 (first row is 1 etc).

By default, log (i.e. column names in the dataframe) will be ICELL, JCELL, KCELL, but you can add a tag (ID) to that name.

Parameters:

grid (Grid) – A XTGeo Grid instance
grid_id (str) – Add a tag (optional) to the current log name
algorithm (int) – Which interbal algorithm to use, default is 2 (expert setting)
activeonly (bool) – If True, only active cells are applied (algorithm 2 only)

Raises:

RuntimeError – ‘Error from C routine, code is …’

Changed in version 2.9: Added keys for and activeonly

make_zone_qual_log(zqname)

Create a zone quality/indicator (flag) log.

This routine looks through to zone log and flag intervals according to neighbouring zones:

0: Undetermined flag
1: Zonelog interval numbering increases,
e.g. for zone 2: 1 1 1 1 2 2 2 2 2 5 5 5 5 5
2: Zonelog interval numbering decreases,
e.g. for zone 2: 6 6 6 2 2 2 2 1 1 1
3: Interval is a U turning point, e.g. 0 0 0 2 2 2 1 1 1
4: Interval is a inverse U turning point, 3 3 3 2 2 2 5 5
9: Interval is bounded by one or more missing sections,
e.g. 1 1 1 2 2 2 -999 -999

If a log with the name exists, it will be silently replaced

Parameters:: zqname (str) – Name of quality log

mask_shoulderbeds(inputlogs, targetlogs, nsamples=2, strict=False)

Mask data around zone boundaries or other discrete log boundaries.

This operates on number of samples, hence the actual distance which is masked depends on the sampling interval (ie. count) or on distance measures. Distance measures are TVD (true vertical depth) or MD (measured depth).

Parameters:

inputlogs (list[str]) – List of input logs, must be of discrete type.
targetlogs (list[str]) – List of logs where mask is applied.
nsamples (int | dict[str, float] | None) – Number of samples around boundaries to filter, per side, i.e. value 2 means 2 above and 2 below, in total 4 samples. As alternative specify nsamples indirectly with a relative distance, as a dictionary with one record, as {“tvd”: 0.5} or {“md”: 0.7}.
strict (bool | None) – If True, will raise Exception of any of the input or target log names are missing.

Return type:

bool

Returns:

True if any operation has been done. False in case nothing has been done,: e.g. no targetlogs for this particular well and strict is False.

Raises:

ValueError – Various messages when wrong or inconsistent input.

Example

>>> mywell1 = Well(well_dir + '/OP_1.w')
>>> mywell2 = Well(well_dir + '/OP_2.w')
>>> did_succeed = mywell1.mask_shoulderbeds(["Zonelog", "Facies"], ["Perm"])
>>> did_succeed = mywell2.mask_shoulderbeds(
...     ["Zonelog"],
...     ["Perm"],
...     nsamples={"tvd": 0.8}
... )

may_overlap(other): Consider if well overlap in X Y coordinates with other well, True/False.

property mdlogname

Returns name of MD log, if any (None if missing).

Type:: str

property metadata: Return metadata object instance of type MetaDataRegularSurface.

property name: Returns or set (rename) a well name.

property ncol

Returns the Pandas dataframe object number of columns.

Type:: int

property nlogs

Returns the Pandas dataframe object number of columns.

Type:: int

property nrow

Returns the Pandas dataframe object number of rows.

Type:: int

rename_log(lname, newname): Rename a log, e.g. Poro to PORO.

report_zonation_holes(threshold=5)

Reports if well has holes in zonation, less or equal to N samples.

Zonation may have holes due to various reasons, and usually a few undef samples indicates that something is wrong. This method reports well and start interval of the “holes”

The well shall have zonelog from import (via zonelogname attribute) and preferly a MD log (via mdlogname attribute); however if the latter is not present, a report withou MD values will be present.

Parameters:: threshold (int) – Number of samples (max.) that defines a hole, e.g. 5 means that undef samples in the range [1, 5] (including 5) is applied
Returns:: A Pandas dataframe as a report. None if no list is made.
Raises:: RuntimeError if zonelog is not present –

rescale(delta=0.15, tvdrange=None)

Rescale (refine or coarse) by sampling a delta along the trajectory, in MD.

Parameters:

delta (float) – Step length
tvdrange (tuple of floats) – Resampling can be limited to TVD interval

Changed in version 2.2: Added tvdrange

property rkb: Returns RKB height for the well (read only).

property safewellname: Get well name on syntax safe form; ‘/’ and spaces replaced with ‘_’.

set_dataframe(dfr): Set the dataframe.

set_logrecord(lname, newdict): Sets the record (dict) of a given discrete log.

set_logtype(lname, ltype): Sets the type of a give log (e.g. DISC or CONT).

set_wlogs(wlogs)

Set a compound dictionary with well log metadata.

This operation is somewhat risky as it may lead to inconsistency, so use with care! Typically, one will use get_wlogs() first and then modify some attributes.

Parameters:

wlogs (dict) – Input data dictionary

Raises:

ValueError – Invalid log type found in input:
ValueError – Invalid log record found in input:
ValueError – Invalid input key found:
ValueError – Invalid log record found in input:

property shortwellname

Well name on a short form where blockname/spaces removed (read only).

This should cope with both North Sea style and Haltenbanken style.

E.g.: ‘31/2-G-5 AH’ -> ‘G-5AH’, ‘6472_11-F-23_AH_T2’ -> ‘F-23AHT2’

Type:: str

to_file(wfile, fformat='rms_ascii')

Export well to file or memory stream.

Parameters:

wfile (str | Path | BytesIO) – File name or stream.
fformat (str | None) – File format (‘rms_ascii’/’rmswell’, ‘hdf/hdf5/h5’).

Example:

>>> xwell = Well(well_dir + '/OP_1.w')
>>> dfr = xwell.get_dataframe()
>>> dfr['Poro'] += 0.1
>>> xwell.set_dataframe(dfr)
>>> filename = xwell.to_file(outdir + "/somefile_copy.rmswell")

to_hdf(wfile, compression='lzf')

Export well to HDF based file.

Warning

This implementation is currently experimental and only recommended for testing.

Parameters:: wfile (str | Path) – HDF File name to write to export to.
Return type:: Path
Returns:: A Path instance to actual file applied.

Added in version 2.14.

to_roxar(*args, **kwargs)[source]

Set (export) a single blocked well item inside roxar project.

Note this method works only when inside RMS, or when RMS license is activated. RMS will store blocked wells as a Gridmodel feature, not as a well.

Note

When project is file path (direct access, outside RMS) then to_roxar() will implicitly do a project save. Otherwise, the project will not be saved until the user do an explicit project save action.

Parameters:

project (str or object) – Magic object ‘project’ or file path to project
gname (str) – Name of GridModel icon in RMS
bwname (str) – Name of Blocked Well icon in RMS, usually ‘BW’
wname (str) – Name of well, as shown in RMS.
lognames (list or "all") – List of lognames to include, or use ‘all’ for all current blocked logs for this well (except index logs). Default is “all”.
realisation (int) – Realisation index (0 is default)
ijk (bool) – If True, then also write special index logs if they exist, such as I_INDEX, J_INDEX, K_INDEX, etc. Default is False

property truewellname: Returns well name on the assummed form aka ‘31/2-E-4 AH2’.

truncate_parallel_path(other, xtol=None, ytol=None, ztol=None, itol=None, atol=None)

Truncate the part of the well trajectory that is ~parallel with other.

Parameters:

other (Well) – Other well to compare with
xtol (float) – Tolerance in X (East) coord for measuring unit
ytol (float) – Tolerance in Y (North) coord for measuring unit
ztol (float) – Tolerance in Z (TVD) coord for measuring unit
itol (float) – Tolerance in inclination (degrees)
atol (float) – Tolerance in azimuth (degrees)

property wellname

Returns well name, read only.

Type:: str

property wlogrecords: Returns wlogrecords

property wlogtypes: Returns wlogtypes

property wname: Returns or set (rename) a well name.

property xname: Return or set name of X coordinate column.

property xpos: Returns well header X position (read only).

property xwellname: See safewellname.

property yname: Return or set name of Y coordinate column.

property ypos: Returns well header Y position (read only).

property zname: Return or set name of Z coordinate column.

property zonelogname

Returns or sets name of zone log, return None if missing.

Type:: str

Blocked wells (multiple)

Functions

xtgeo.blockedwells_from_roxar(project, gname, bwname, lognames=None, ijk=True)[source]

This makes an instance of a BlockedWells directly from Roxar RMS.

For arguments, see BlockedWells.from_roxar().

Note the difference between classes BlockedWell and BlockedWells.

Example:

# inside RMS:
import xtgeo
mylogs = ['ZONELOG', 'GR', 'Facies']
mybws = xtgeo.blockedwells_from_roxar(project, 'Simgrid', 'BW',
                                    lognames=mylogs)

Classes

class xtgeo.BlockedWells(wells=None)[source]

Bases: Wells

Class for a collection of BlockedWell objects, for operations that involves a number of wells.

See also the xtgeo.well.BlockedWell class.

Public Data Attributes:

Inherited from Wells

`names`	Returns a list of well names (read only).
`wells`	Returns or sets a list of XTGeo Well objects, None if empty.

Public Methods:

`copy`()	Copy a BlockedWells instance to a new unique instance.
`get_blocked_well`(name)	Get a BlockedWell() instance by name, or None

Inherited from Wells

`describe`([flush])	Describe an instance by printing to stdout
`copy`()	Copy a Wells instance to a new unique instance (a deep copy).
`get_well`(name)	Get a Well() instance by name, or None
`get_dataframe`([filled, fill_value1, fill_value2])	Get a big dataframe for all wells or blocked wells in instance, with well name as first column
`quickplot`([filename, title])	Fast plot of wells using matplotlib.
`limit_tvd`(tvdmin, tvdmax)	Limit TVD to be in range tvdmin, tvdmax for all wells
`downsample`([interval, keeplast])	Downsample by sampling every N'th element (coarsen only), all wells.
`wellintersections`([wfilter, showprogress])	Get intersections between wells, return as dataframe table.

__init__(wells=None)

copy()[source]: Copy a BlockedWells instance to a new unique instance.

describe(flush=True): Describe an instance by printing to stdout

downsample(interval=4, keeplast=True): Downsample by sampling every N’th element (coarsen only), all wells.

get_blocked_well(name)[source]: Get a BlockedWell() instance by name, or None

get_dataframe(filled=False, fill_value1=-999, fill_value2=-9999)

Get a big dataframe for all wells or blocked wells in instance, with well name as first column

Parameters:

filled (bool) – If True, then NaN’s are replaces with values
fill_value1 (int) – Only applied if filled=True, for logs that have missing values
fill_value2 (int) – Only applied if filled=True, when logs are missing completely for that well.

get_well(name): Get a Well() instance by name, or None

limit_tvd(tvdmin, tvdmax): Limit TVD to be in range tvdmin, tvdmax for all wells

property names

Returns a list of well names (read only).

Example:

namelist = wells.names
for prop in namelist:
    print ('Well name is {}'.format(name))

quickplot(filename=None, title='QuickPlot')

Fast plot of wells using matplotlib.

Parameters:

filename (str) – Name of plot file; None will plot to screen.
title (str) – Title of plot

wellintersections(wfilter=None, showprogress=False)

Get intersections between wells, return as dataframe table.

Notes on wfilter: A wfilter is settings to improve result. In particular to remove parts of trajectories that are parallel.

wfilter = {‘parallel’: {‘xtol’: 4.0, ‘ytol’: 4.0, ‘ztol’:2.0,: ‘itol’:10, ‘atol’:2}}

Here xtol is tolerance in X coordinate; further Y tolerance, Z tolerance, (I)nclination tolerance, and (A)zimuth tolerance.

Parameters:

tvdrange (tuple of floats) – Search interval. One is often just interested in the reservoir section.
wfilter (dict) – A dictionrary for filter options, in order to improve result. See example above.
showprogress (bool) – Will show progress to screen if enabled.

Returns:

A Pandas dataframe object, with columns WELL, CWELL and UTMX UTMY: TVD coordinates for CWELL where CWELL crosses WELL, and also MDEPTH for the WELL.

property wells: Returns or sets a list of XTGeo Well objects, None if empty.

Cubes (e.g. seismic)

Cube

Functions

xtgeo.cube_from_file(mfile, fformat='guess')[source]

This makes an instance of a Cube directly from file import.

Parameters:

mfile (str) – Name of file
fformat (str) – See Cube.from_file()

Example:

>>> import xtgeo
>>> mycube = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")

xtgeo.cube_from_roxar(project, name, folder=None)[source]

This makes an instance of a Cube directly from roxar input.

The folder is a string on form “a” or “a/b” if subfolders are present

Example:

import xtgeo
mycube = xtgeo.cube_from_roxar(project, "DepthCube")

Classes

class xtgeo.Cube(ncol, nrow, nlay, xinc, yinc, zinc, xori=0.0, yori=0.0, zori=0.0, yflip=1, values=0.0, rotation=0.0, zflip=1, ilines=None, xlines=None, traceidcodes=None, segyfile=None, filesrc=None)[source]

Bases: object

Class for a (seismic) cube in the XTGeo framework.

The values are stored as a 3D numpy array (4 bytes; float32 is default), with internal C ordering (nlay fastest).

See xtgeo.cube_from_file() for importing cubes from e.g. segy files.

See also Cube section in documentation: docs/datamodel.rst

Examples:

>>> import xtgeo
>>> # a user defined cube:
>>> mycube = xtgeo.Cube(
...     xori=100.0,
...     yori=200.0,
...     zori=150.0,
...     ncol=40,
...     nrow=30,
...     nlay=10,
...     rotation=30,
...     values=0
... )

Parameters:

xori – Origin in Easting coordinate
yori – Origin in Northing coordinate
zori – Origin in Depth coordinate, where depth is positive down
ncol – Number of columns
nrow – Number of columns
nlay – Number of layers, starting from top
rotation – Cube rotation, X axis is applied and “school-wise” rotation, anti-clock in degrees
values – Numpy array with shape (ncol, nrow, nlay), C order, np.float32
ilines – 1D numpy array with ncol elements, aka INLINES array, defaults to arange
xlines – 1D numpy array with nrow elements, aka XLINES array, defaults to arange
segyfile – Name of source segyfile if any
filesrc – String: Source file if any
yflip – Normally 1; if -1 Y axis is flipped –> from left-handed (1) to right handed (-1). Right handed cubes are common.

Initiate a Cube instance.

Public Data Attributes:

`metadata`	Return metadata object instance of type MetaDataRegularSurface.
`ncol`	The NCOL (NX or I dir) number (read-only).
`nrow`	The NROW (NY or J dir) number (read-only).
`nlay`	The NLAY (or NZ or K dir) number (read-only).
`dimensions`	The cube dimensions with 3 integers (read only).
`xori`	The XORI (origin corner) coordinate.
`yori`	The YORI (origin corner) coordinate.
`zori`	The ZORI (origin corner) coordinate.
`xinc`	The XINC (increment X) as property.
`yinc`	The YINC (increment Y).
`zinc`	The ZINC (increment Z).
`rotation`	The rotation, anticlock from X axis in degrees.
`ilines`	The inlines numbering vector.
`xlines`	The xlines numbering vector.
`zslices`	Return the time/depth slices as an int array (read only).
`traceidcodes`	The trace identifaction codes array (ncol, nrow).
`yflip`	The YFLIP indicator, 1 is normal, -1 means Y flipped.
`zflip`	The ZFLIP indicator, 1 is normal, -1 means Z flipped.
`segyfile`	The input segy file name (str), if any (or None) (read-only).
`filesrc`	The input file name (str), if any (or None) (read-only).
`values`	The values, as a 3D numpy (ncol, nrow, nlay), 4 byte float.

Public Methods:

`generate_hash`([hashmethod])	Return a unique hash ID for current instance.
`describe`([flush])	Describe an instance by printing to stdout or return.
`copy`()	Deep copy of a Cube() object to another instance.
`swapaxes`()	Swap the axes inline vs xline, keep origin.
`resample`(incube[, sampling, outside_value])	Resample a Cube object into this instance.
`do_thinning`(icol, jrow, klay)	Thinning the cube by removing every N column, row and/or layer.
`do_cropping`(icols, jrows, klays[, mode])	Cropping the cube by removing rows, columns, layers.
`values_dead_traces`(newvalue)	Set values for traces flagged as dead.
`get_xy_value_from_ij`(iloc, jloc[, ixline, ...])	Returns x, y coordinate from a single i j location.
`compute_attributes_in_window`(upper, lower[, ...])	Return a cube's attributes as a set of surfaces, given two input surfaces.
`get_randomline`(fencespec[, zmin, zmax, ...])	Get a randomline from a fence spesification.
`to_file`(sfile[, fformat, pristine, engine])	Export cube data to file.
`to_roxar`(project, name[, folder, propname, ...])	Export (transfer) a cube from a XTGeo cube object to Roxar data.

__init__(ncol, nrow, nlay, xinc, yinc, zinc, xori=0.0, yori=0.0, zori=0.0, yflip=1, values=0.0, rotation=0.0, zflip=1, ilines=None, xlines=None, traceidcodes=None, segyfile=None, filesrc=None)[source]: Initiate a Cube instance.

compute_attributes_in_window(upper, lower, ndiv=10, interpolation='cubic', minimum_thickness=0.0)[source]

Return a cube’s attributes as a set of surfaces, given two input surfaces.

The attributes are computed vertically (per column) within a window defined by the two input surfaces and/or levels.

The statistical measures can be min, max, mean, variance etc. A complete list of supported attributes is given below.

‘max’ for maximum
‘min’ for minimum
‘rms’ for root mean square
‘mean’ for expected value
‘var’ for variance (population var; https://en.wikipedia.org/wiki/Variance)
‘maxpos’ for maximum of positive values
‘maxneg’ for negative maximum of negative values
‘maxabs’ for maximum of absolute values
‘sumpos’ for sum of positive values using cube sampling resolution
‘sumneg’ for sum of negative values using cube sampling resolution
‘meanabs’ for mean of absolute values
‘meanpos’ for mean of positive values
‘meanneg’ for mean of negative values
‘upper’ will return a copy of the upper surface applied
‘lower’ will return a copy of the lower surface applied

Parameters:

upper (RegularSurface | float) – The uppermost surface or constant level to compute within.
lower (RegularSurface | float) – The lower surface or level to compute within.
ndiv (int) – Number of intervals for sampling within zrange. Default is 10. using 0.1 of cube Z increment as basis. A higher ndiv will increase CPU time and memory usage, but also increase the precision of the result.
interpolation (Literal['cubic', 'linear']) – ‘cubic’ or ‘linear’ for interpolation of the seismic signal, default here is ‘cubic’.
minimum_thickness (float) – Minimum thickness (isochore or isochron) between the two surfaces. If the thickness is less or equal than this value, the result will be masked. Default is 0.0.

Return type:

dict[RegularSurface]

Example:

>>> import xtgeo
>>> cube = xtgeo.cube_from_file("mycube.segy")
>>> surf = xtgeo.surface_from_file("topreek.gri")
>>> # sample in a total range of 30 m, 15 units above and 15 units below:
>>> attrs = cube.compute_attributes_in_window((surf-15), (surf + 15))
>>> attrs["max"].to_file("max.gri")  # save the 'max' attribute to file

Note

This method is a significantly improved version of the slice_cube_window() method within RegularSurface(), and it is strongly recommended to replace the former with this as soon as possible.

Added in version 4.1.

copy()[source]

Deep copy of a Cube() object to another instance.

>>> mycube = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")
>>> mycube2 = mycube.copy()

describe(flush=True)[source]

Describe an instance by printing to stdout or return.

Parameters:: flush (bool) – If True, description is printed to stdout.

property dimensions

The cube dimensions with 3 integers (read only).

Type:: NamedTuple

do_cropping(icols, jrows, klays, mode='edges')[source]

Cropping the cube by removing rows, columns, layers.

Note that input boundary checking is currently lacking, and this is a currently a user responsibility!

The ‘mode’ is used to determine to different ‘approaches’ on cropping. Examples for icols and mode ‘edges’: Here the tuple (N, M) will cut N first rows and M last rows.

However, if mode is ‘inclusive’ then, it defines the range of rows to be included, and the numbering now shall be the INLINE, XLINE and DEPTH/TIME mode.

Parameters:

icols (int tuple) – Cropping front, end of rows, or inclusive range
jrows (int tuple) – Cropping front, end of columns, or inclusive range
klays (int tuple) – Cropping top, base layers, or inclusive range.
mode (str) – ‘Default is ‘edges’; alternative is ‘inclusive’

Example

Crop 10 columns from front, 2 from back, then 20 rows in front, 40 in back, then no cropping of layers:

>>> import xtgeo
>>> mycube1 = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")
>>> mycube2 = mycube1.copy()
>>> mycube1.do_cropping((10, 2), (20, 40), (0, 0))
>>> mycube1.to_file(outdir + '/mysegy_smaller.segy')

In stead, do cropping as ‘inclusive’ where inlines, xlines, slices arrays are known:

>>> mycube2.do_cropping((11, 32), (112, 114), (150, 200))

do_thinning(icol, jrow, klay)[source]

Thinning the cube by removing every N column, row and/or layer.

Parameters:

icol (int) – Thinning factor for columns (usually inlines)
jrow (int) – Thinning factor for rows (usually xlines)
klay (int) – Thinning factor for layers

Raises:

ValueError – If icol, jrow or klay are out of reasonable range

Example

>>> mycube1 = Cube(cube_dir + "/ib_test_cube2.segy")
>>> mycube1.do_thinning(2, 2, 1)  # keep every second column, row
>>> mycube1.to_file(outdir + '/mysegy_smaller.segy')

property filesrc: The input file name (str), if any (or None) (read-only).

generate_hash(hashmethod='md5')[source]

Return a unique hash ID for current instance.

See generic_hash() for documentation.

Added in version 2.14.

get_randomline(fencespec, zmin=None, zmax=None, zincrement=None, hincrement=None, atleast=5, nextend=2, sampling='nearest')[source]

Get a randomline from a fence spesification.

This randomline will be a 2D numpy with depth/time on the vertical axis, and length along as horizontal axis. Undefined values will have the np.nan value.

The input fencespec is either a 2D numpy where each row is X, Y, Z, HLEN, where X, Y are UTM coordinates, Z is depth/time, and HLEN is a length along the fence, or a Polygons instance.

If input fencspec is a numpy 2D, it is important that the HLEN array has a constant increment and ideally a sampling that is less than the Cube resolution. If a Polygons() instance, this is automated!

Parameters:

fencespec (ndarray or Polygons) – 2D numpy with X, Y, Z, HLEN as rows or a xtgeo Polygons() object.
zmin (float) – Minimum Z (default is Cube Z minima/origin)
zmax (float) – Maximum Z (default is Cube Z maximum)
zincrement (float) – Sampling vertically, default is Cube ZINC/2
hincrement (float or bool) – Resampling horizontally. This applies only if the fencespec is a Polygons() instance. If None (default), the distance will be deduced automatically.
atleast (int) – Minimum number of horizontal samples (only if fencespec is a Polygons instance)
nextend (int) – Extend with nextend * hincrement in both ends (only if fencespec is a Polygons instance)
sampling (str) – Algorithm, ‘nearest’ or ‘trilinear’ (first is faster, second is more precise for continuous fields)

Returns:

(hmin, hmax, vmin, vmax, ndarray2d)

Return type:

A tuple

Raises:

ValueError – Input fence is not according to spec.

Changed in version 2.1: support for Polygons() as fencespec, and keywords hincrement, atleast and sampling

See also

Class Polygons: The method get_fence() which can be used to pregenerate fencespec

get_xy_value_from_ij(iloc, jloc, ixline=False, zerobased=False)[source]

Returns x, y coordinate from a single i j location.

Parameters:

iloc (int) – I (col) location (base is 1)
jloc (int) – J (row) location (base is 1)
ixline (bool) – If True, then input locations are inline and xline position
zerobased (bool) – If True, first index is 0, else it is 1. This does not apply when ixline is set to True.

Returns:

The X, Y coordinate pair.

property ilines: The inlines numbering vector.

property metadata: Return metadata object instance of type MetaDataRegularSurface.

property ncol: The NCOL (NX or I dir) number (read-only).

property nlay: The NLAY (or NZ or K dir) number (read-only).

property nrow: The NROW (NY or J dir) number (read-only).

resample(incube, sampling='nearest', outside_value=None)[source]

Resample a Cube object into this instance.

Parameters:

incube (Cube) – A XTGeo Cube instance
sampling (str) – Sampling algorithm: ‘nearest’ for nearest node of ‘trilinear’ for trilinear interpoltion (more correct but slower)
outside_value (None or float) – use this value

Raises:

ValueError – If cubes do not overlap

Example

>>> import xtgeo
>>> mycube1 = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")
>>> mycube2 = xtgeo.Cube(
...     xori=777574,
...     yori=6736507,
...     zori=1000,
...     xinc=10,
...     yinc=10,
...     zinc=4,
...     ncol=100,
...     nrow=100,
...     nlay=100,
...     yflip=mycube1.yflip,
...     rotation=mycube1.rotation
... )
>>> mycube2.resample(mycube1)

property rotation: The rotation, anticlock from X axis in degrees.

property segyfile: The input segy file name (str), if any (or None) (read-only).

swapaxes()[source]: Swap the axes inline vs xline, keep origin.

to_file(sfile, fformat='segy', pristine=False, engine=None)[source]

Export cube data to file.

Parameters:

sfile (str) – Filename
fformat (str, optional) – file format ‘segy’ (default) or ‘rms_regular’
pristine (bool) – If True, make SEGY from scratch.
engine (str) – Which “engine” to use.

Example::

>>> import xtgeo
>>> zz = xtgeo.cube_from_file(cube_dir + "/ib_test_cube2.segy")
>>> zz.to_file(outdir + '/some.rmsreg')

to_roxar(project, name, folder=None, propname='seismic_attribute', domain='time', compression=('wavelet', 5.0), target='seismic')[source]

Export (transfer) a cube from a XTGeo cube object to Roxar data.

Note

When project is file path (direct access, outside RMS) then to_roxar() will implicitly do a project save. Otherwise, the project will not be saved until the user do an explicit project save action.

Parameters:

project (Any) – Inside RMS use the magic ‘project’, else use path to RMS project, or a project reference
name (str) – Name of cube (seismic data) within RMS project.
folder (str | None) – Cubes may be stored under a folder in the tree, use ‘/’ to seperate subfolders.
propname (str) – Name of grid property; only relevant when target is “grid” and defaults to “seismic_attribute”
domain (str) – ‘time’ (default) or ‘depth’
compression (tuple[str, float]) – Reference to Roxar API ‘compression method’ and ‘compression tolerance’, but implementation is pending. Hence inactive.
target (str) – Optionally, the seismic cube can be written to the Grid model tree in RMS. Internally, it will be convert to a “box” grid with one gridproperty, before it is written to RMS. The compression``and ``domain are not relevant when writing to grid model.

Raises:

To be described... –

Example:

zz = xtgeo.cube_from_file('myfile.segy')
zz.to_roxar(project, 'reek_cube')
# write cube to "Grid model" tree in RMS instead
zz.to_roxar(project, 'cube_as_grid', propname="impedance", target="grid")

Changed in version 3.4: Add target and propname keys

property traceidcodes: The trace identifaction codes array (ncol, nrow).

property values: The values, as a 3D numpy (ncol, nrow, nlay), 4 byte float.

values_dead_traces(newvalue)[source]

Set values for traces flagged as dead.

Dead traces have traceidcodes 2 and corresponding values in the cube will here receive a constant value to mimic “undefined”.

Parameters:

newvalue (float) – Set cube values to newvalues where traceid is 2.

Returns:

The estimated simple ‘average’ of old value will: be returned as (max + min)/2. If no dead traces, return None.

Return type:

oldvalue (float)

property xinc: The XINC (increment X) as property.

property xlines: The xlines numbering vector.

property xori: The XORI (origin corner) coordinate.

property yflip

The YFLIP indicator, 1 is normal, -1 means Y flipped.

YFLIP = 1 means a LEFT HANDED coordinate system with Z axis positive down, while inline (col) follow East (X) and xline (rows) follows North (Y), when rotation is zero.

property yinc: The YINC (increment Y).

property yori: The YORI (origin corner) coordinate.

property zflip

The ZFLIP indicator, 1 is normal, -1 means Z flipped.

ZFLIP = 1 and YFLIP = 1 means a LEFT HANDED coordinate system with Z axis positive down, while inline (col) follow East (X) and xline (rows) follows North (Y), when rotation is zero.

property zinc: The ZINC (increment Z).

property zori: The ZORI (origin corner) coordinate.

property zslices: Return the time/depth slices as an int array (read only).

3D grids and properties

Grid

Functions

xtgeo.grid_from_file(gfile, fformat=None, **kwargs)[source]

Read a grid (cornerpoint) from filelike and an returns a Grid() instance.

Parameters:

gfile (Union[str, Path, StringIO, BytesIO, FileWrapper]) – File name to be imported. If fformat=”eclipse_run” then a fileroot name shall be input here, see example below.
fformat (str | None) – File format egrid/roff/grdecl/bgrdecl/eclipserun/xtgcpgeom (None is default and means “guess”)
initprops (str list) – Optional, and only applicable for file format “eclipserun”. Provide a list the names of the properties here. A special value “all” can be get all properties found in the INIT file
restartprops (str list) – Optional, see initprops
restartdates (int list) – Optional, required if restartprops
ijkrange (list-like) – Optional, only applicable for hdf files, see Grid.from_hdf().
zerobased (bool) – Optional, only applicable for hdf files, see Grid.from_hdf().
mmap (bool) – Optional, only applicable for xtgf files, see Grid.from_xtgf().

Return type:

Grid

Example:

>>> import xtgeo
>>> mygrid = xtgeo.grid_from_file(reek_dir + "/REEK.EGRID")

Example using “eclipserun”:

>>> mycase = "REEK"  # meaning REEK.EGRID, REEK.INIT, REEK.UNRST
>>> xg = xtgeo.grid_from_file(
...     reek_dir + "/" + mycase,
...     fformat="eclipserun",
...     initprops="all",
... )
Grid ... filesrc='.../REEK.EGRID'

Raises:: OSError – if file is not found etc

xtgeo.grid_from_roxar(project, gname, realisation=0, info=False)[source]

Read a 3D grid inside a RMS project and return a Grid() instance.

Parameters:

project (str or special) – The RMS project or the project variable from inside RMS.
gname (str) – Name of Grid Model in RMS.
realisation (int) – Realisation number.
dimensions_only (bool) – If True, only the ncol, nrow, nlay will read. The actual grid geometry will remain empty (None). This will be much faster of only grid size info is needed, e.g. for initalising a grid property.
info (bool) – If true, only grid info

Return type:

Grid

Example:

# inside RMS
import xtgeo
mygrid = xtgeo.grid_from_roxar(project, "REEK_SIM")

Classes

class xtgeo.Grid(coordsv, zcornsv, actnumsv, dualporo=False, dualperm=False, subgrids=None, units=None, filesrc=None, props=None, name=None, roxgrid=None, roxindexer=None)[source]

Bases: _Grid3D

Class for a 3D grid corner point geometry in XTGeo.

I.e. the geometric grid cells and the active cell indicator.

The grid geometry class instances are normally created when importing a grid from file, as it is normally too complex to create from scratch.

Parameters:

coordsv (ndarray) – numpy array of dtype float64 and dimensions (nx + 1, ny + 1, 6) Giving the x,y,z values of the upper and lower corners in the grid.
zcornsv (ndarray) – numpy array of dtype float32 and dimensions (nx + 1, ny + 1, nz + 1, 4) giving the sw, se, nw, ne corners along the i,jth corner line for the kth layer.
actnumsv (ndarray) – numpy array of dtype int32 and dimensions (nx, ny, nz) giving the activity number for each cell. 0 means inactive, 1 means active. For dualporo=True/dualperm=True grids, value can also be 2 or 3 meaning rock volume only and pore volume only respectively.
dualporo (bool) – True if dual porosity grid.
dualperm (bool) – True if dual permeability grid.
subgrids (dict | None) – dictionary giving names to subset of layers. Has name as key and list of layer indices as values. Defaults to no names given.
units (Units | None) – The length units the coordinates are in, (either Units.CM, Units.METRES, Units.FEET for cm, metres and feet respectively). Default (None) is unitless.
filesrc (Path | str | None) – Optional filename of grid.
props (GridProperties | None) – GridProperties instance containing the properties of the grid, defaults to empty instance.
name (str | None) – Optional name of the grid.
roxgrid (Any | None) – Roxar Grid the Grid originates from if any, defaults to no such grid.
roxindexer (Any | None) – Roxar grid indexer for the roxgrid. Defaults to no such indexer.

See also

The GridProperty and the GridProperties classes.

Public Data Attributes:

`metadata`	Return or set metadata instance of type MetaDataCPGeometry.
`filesrc`	Source for grid (filepath or name in RMS).
`name`	Name attribute of grid.
`dimensions`	The grid dimensions (read only).
`vectordimensions`	The storage grid array dimensions tuple of 3 integers (read only).
`ijk_handedness`	IJK handedness for grids, "right" or "left".
`subgrids`	A dict with subgrid name and an array as value.
`nactive`	Returns the number of active cells (read only).
`actnum_array`	Returns the 3D ndarray which for active cells.
`actnum_indices`	np.ndrarray: Indices (1D array) for active cells (read only).
`ntotal`	Returns the total number of cells (read only).
`dualporo`	Boolean flag for dual porosity scheme (read only).
`dualperm`	Boolean flag for dual porosity scheme (read only).
`gridprops`	Return or set a XTGeo GridProperties objects attached to the Grid.
`props`	Return or set a list of XTGeo GridProperty objects.
`propnames`	Returns a list of property names that are hooked to a grid.
`roxgrid`	Get the Roxar native proj.grid_models[gname].get_grid() object.
`roxindexer`	The Roxar native proj.grid_models[gname].get_grid().grid_indexer object.

Inherited from _Grid3D

`ncol`	Returns the NCOL (NX or Ncolumns) number of cells.
`nrow`	Returns the NROW (NY or Nrows) number of cells.
`nlay`	Returns the NLAY (NZ or Nlayers) number of cells.

Public Methods:

`generate_hash`([hashmethod])	Return a unique hash ID for current instance.
`to_file`(gfile[, fformat])	Export grid geometry to file, various vendor formats.
`to_hdf`(gfile[, compression, chunks, subformat])	Export grid geometry to HDF5 storage format (experimental!).
`to_xtgf`(gfile[, subformat])	Export grid geometry to xtgeo native binary file format (experimental!).
`to_roxar`(project, gname[, realisation, ...])	Export (upload) a grid from XTGeo to RMS via Roxar API.
`convert_units`(units)	Convert the units of the grid.
`copy`()	Copy from one existing Grid instance to a new unique instance.
`describe`([details, flush])	Describe an instance by printing to stdout.
`get_dataframe`([activeonly, ijk, xyz, ...])	Returns a Pandas dataframe for the grid and any attached grid properties.
`get_vtk_esg_geometry_data`()	Get grid geometry data suitable for use with VTK's vtkExplicitStructuredGrid.
`get_vtk_geometries`()	Get necessary arrays on correct layout for VTK ExplicitStructuredGrid usage.
`append_prop`(prop)	Append a single property to the grid.
`set_subgrids`(sdict)	Set the subgrid from a simplified ordered dictionary.
`get_subgrids`()	Get the subgrids on a simplified ordered dictionary.
`rename_subgrids`(names)	Rename the names in the subgrids with the new names.
`estimate_design`([nsub])	Estimate design and simbox thickness of the grid or a subgrid.
`estimate_flip`()	Estimate flip (handedness) of grid returns as 1 or -1.
`subgrids_from_zoneprop`(zoneprop)	Estimate subgrid index from a zone property.
`get_zoneprop_from_subgrids`()	Make a XTGeo GridProperty instance for a Zone property subgrid index.
`get_boundary_polygons`([alpha_factor, ...])	Extract boundary polygons from the grid cell centers.
`get_actnum_indices`([order, inverse])	Returns the 1D ndarray which holds the indices for active cells.
`get_dualactnum_indices`([order, fracture])	Returns the 1D ndarray which holds the indices for matrix/fracture cases.
`get_prop_by_name`(name)	Gets a property object by name lookup, return None if not present.
`get_actnum`([name, asmasked, dual])	Return an ACTNUM GridProperty object.
`set_actnum`(actnum)	Modify the existing active cell index, ACTNUM.
`get_dz`([name, flip, asmasked, metric])	Return the dZ as GridProperty object.
`get_dx`([name, asmasked, metric])	Return the dX as GridProperty object.
`get_dy`([name, asmasked, metric])	Return the dY as GridProperty object.
`get_cell_volume`([ijk, activeonly, ...])	Return the bulk volume for a given cell.
`get_bulk_volume`([name, asmasked, precision])	Return the geometric cell volume for all cells as a GridProperty object.
`get_heights_above_ffl`(ffl[, option])	Returns 3 properties: htop, hbot and hmid, primarely for use in Sw models."
`get_property_between_surfaces`(top, base[, ...])	Returns a 3D GridProperty object with <value> between two surfaces."
`get_ijk`([names, asmasked, zerobased])	Returns 3 xtgeo.grid3d.GridProperty objects: I counter, J counter, K counter.
`get_ijk_from_points`(points[, activeonly, ...])	Returns a list/dataframe of cell indices based on a Points() instance.
`get_xyz`([names, asmasked])	Returns 3 xtgeo.grid3d.GridProperty objects for x, y, z coordinates.
`get_xyz_cell_corners`([ijk, activeonly, ...])	Return a 8 * 3 tuple x, y, z for each corner.
`get_xyz_corners`([names])	Returns 8*3 (24) xtgeo.grid3d.GridProperty objects, x, y, z for each corner.
`get_layer_slice`(layer[, top, activeonly])	Get numpy arrays for cell coordinates e.g. for plotting.
`get_geometrics`([allcells, cellcenter, ...])	Get a list of grid geometrics such as origin, min, max, etc.
`get_adjacent_cells`(prop, val1, val2[, ...])	Get a discrete property which reports val1 properties vs neighbouring val2.
`get_gridquality_properties`()	Return a GridProperties() instance with grid quality measures.
`activate_all`()	Activate all cells in the grid, by manipulating ACTNUM.
`inactivate_by_dz`(threshold)	Inactivate cells thinner than a given threshold.
`inactivate_inside`(poly[, layer_range, ...])	Inacativate grid inside a polygon.
`inactivate_outside`(poly[, layer_range, ...])	Inacativate grid outside a polygon.
`collapse_inactive_cells`()	Collapse inactive layers where, for I J with other active cells.
`crop`(colcrop, rowcrop, laycrop[, props])	Reduce the grid size by cropping.
`reduce_to_one_layer`()	Reduce the grid to one single layer.
`translate_coordinates`([translate, flip])	Translate (move) and/or flip grid coordinates in 3D.
`reverse_row_axis`([ijk_handedness])	Reverse the row axis (J indices).
`make_zconsistent`([zsep])	Make the 3D grid consistent in Z, by a minimal gap (zsep).
`convert_to_hybrid`([nhdiv, toplevel, ...])	Convert to hybrid grid, either globally or in a selected region.
`refine_vertically`(rfactor[, zoneprop])	Refine vertically, proportionally.
`report_zone_mismatch`([well, zonelogname, ...])	Reports mismatch between wells and a zone.
`get_randomline`(fencespec, prop[, zmin, ...])	Get a sampled randomline from a fence spesification.

__init__(coordsv, zcornsv, actnumsv, dualporo=False, dualperm=False, subgrids=None, units=None, filesrc=None, props=None, name=None, roxgrid=None, roxindexer=None)[source]

activate_all()[source]

Activate all cells in the grid, by manipulating ACTNUM.

Return type:: None

property actnum_array

Returns the 3D ndarray which for active cells.

Values are 1 for active, 0 for inactive, in C order (read only).

property actnum_indices

np.ndrarray: Indices (1D array) for active cells (read only).

In dual poro/perm systems, this will be the active indices for the matrix cells and/or fracture cells (i.e. actnum >= 1).

Type:: obj

append_prop(prop)[source]

Append a single property to the grid.

Return type:: None

collapse_inactive_cells()[source]

Collapse inactive layers where, for I J with other active cells.

Return type:: None

convert_to_hybrid(nhdiv=10, toplevel=1000.0, bottomlevel=1100.0, region=None, region_number=None)[source]

Convert to hybrid grid, either globally or in a selected region.

This function will convert the internal structure in the corner point grid, so that the cells between two levels toplevel and bottomlevel become horizontal, which can be useful in flow simulators when e.g. liquid contact movements are dominating. See example on usage in the Troll field.

Note that the resulting hybrid will have an increased number of layers. If the initial grid has N layers, and the number of horizontal layers is NHDIV, then the result grid will have N * 2 + NHDIV layers.

Parameters:

nhdiv (int) – Number of hybrid layers.
toplevel (float) – Top of hybrid grid.
bottomlevel (float) – Base of hybrid grid.
region (GridProperty, optional) – Region property (if needed).
region_number (int) – Which region to apply hybrid grid in if region.

Return type:

None

Example

Create a hybridgrid from file, based on a GRDECL file (no region):

import xtgeo
grd = xtgeo.grid_from_file("simgrid.grdecl", fformat="grdecl")
grd.convert_to_hybrid(nhdiv=12, toplevel=2200, bottomlevel=2250)
# save in binary GRDECL fmt:
grd.to_file("simgrid_hybrid.bgrdecl", fformat="bgrdecl")

See also

Make a hybrid grid example.

convert_units(units)[source]

Convert the units of the grid. :type units: Units :param units: The unit to convert to.

Raises:: ValueError – When the grid is unitless (no initial unit information available).
Return type:: None

copy()[source]

Copy from one existing Grid instance to a new unique instance.

Note that associated properties will also be copied.

Example:

>>> grd = create_box_grid((5,5,5))
>>> newgrd = grd.copy()

Return type:: Grid

crop(colcrop, rowcrop, laycrop, props=None)[source]

Reduce the grid size by cropping.

The new grid will get new dimensions.

If props is “all” then all properties assosiated (linked) to then grid are also cropped, and the instances are updated.

Parameters:

colcrop (tuple) – A tuple on the form (i1, i2) where 1 represents start number, and 2 represent end. The range is inclusive for both ends, and the number start index is 1 based.
rowcrop (tuple) – A tuple on the form (j1, j2)
laycrop (tuple) – A tuple on the form (k1, k2)
props (list or str) – None is default, while properties can be listed. If “all”, then all GridProperty objects which are linked to the Grid instance are updated.

Return type:

None

Returns:

The instance is updated (cropped)

Example:

>>> import xtgeo
>>> mygrid = xtgeo.grid_from_file(reek_dir + "/REEK.EGRID")
>>> mygrid.crop((3, 6), (4, 20), (1, 10))
>>> mygrid.to_file(outdir + "/gf_reduced.roff")

describe(details=False, flush=True)[source]

Describe an instance by printing to stdout.

Return type:: str | None

property dimensions

The grid dimensions (read only).

Type:: Dimensions NamedTuple

property dualperm: Boolean flag for dual porosity scheme (read only).

property dualporo: Boolean flag for dual porosity scheme (read only).

estimate_design(nsub=None)[source]

Estimate design and simbox thickness of the grid or a subgrid.

If the grid consists of several subgrids, and nsub is not specified, then a failure should be raised.

Parameters:

nsub (int or str) – Subgrid index to check, either as a number (starting with 1) or as subgrid name. If set to None, the whole grid will examined.

Returns:

where key “design” gives one letter in(P, T, B, X, M): P=proportional, T=topconform, B=baseconform, X=underdetermined, M=Mixed conform. Key “dzsimbox” is simbox thickness estimate per cell. None if nsub is given, but subgrids are missing, or nsub (name or number) is out of range.

Return type:

result (dict)

Example:

>>> import xtgeo
>>> grd = xtgeo.grid_from_file(emerald_dir + "/emerald_hetero_grid.roff")
>>> print(grd.subgrids)
dict([('subgrid_0', range(1, 17)), ('subgrid_1', range(17, 47))])
>>> res = grd.estimate_design(nsub="subgrid_0")
>>> print("Subgrid design is", res["design"])
Subgrid design is P
>>> print("Subgrid simbox thickness is", res["dzsimbox"])
Subgrid simbox thickness is 2.548...

estimate_flip()[source]

Estimate flip (handedness) of grid returns as 1 or -1.

The flip numbers are 1 for left-handed and -1 for right-handed. :rtype: Literal[1, -1]

See also

ijk_handedness

property filesrc

Source for grid (filepath or name in RMS).

Type:: str

generate_hash(hashmethod='md5')[source]

Return a unique hash ID for current instance.

See generic_hash() for documentation. :rtype: str

Added in version 2.14.

get_actnum(name='ACTNUM', asmasked=False, dual=False)[source]

Return an ACTNUM GridProperty object.

Parameters:

name (str) – name of property in the XTGeo GridProperty object.
asmasked (bool) – Actnum is returned with all cells shown as default. Use asmasked=True to make 0 entries masked.
dual (bool) – If True, and the grid is a dualporo/perm grid, an extended ACTNUM is applied (numbers 0..3)

Return type:

GridProperty

Example:

>>> import xtgeo
>>> mygrid = xtgeo.create_box_grid((2,2,2))
>>> act = mygrid.get_actnum()
>>> print("{}% of cells are active".format(act.values.mean() * 100))
100.0% of cells are active

Changed in version 2.6: Added dual keyword

get_actnum_indices(order='C', inverse=False)[source]

Returns the 1D ndarray which holds the indices for active cells.

Parameters:

order (str) – “Either ‘C’ (default) or ‘F’ order).
inverse (bool) – Default is False, returns indices for inactive cells if True.

Return type:

ndarray

Changed in version 2.18: Added inverse option

get_adjacent_cells(prop, val1, val2, activeonly=True)[source]

Get a discrete property which reports val1 properties vs neighbouring val2.

The result will be a new gridproperty, which in general has value 0 but 1 if criteria is met, and 2 if criteria is met but cells are faulted.

Parameters:

prop (xtgeo.GridProperty) – A discrete grid property, e.g region
val1 (int) – Primary value to evaluate
val2 (int) – Neighbourung value
activeonly (bool) – If True, do not look at inactive cells

Return type:

GridProperty

Raises: Nothing

get_boundary_polygons(alpha_factor=1.0, convex=False, simplify=True, filter_array=None)[source]

Extract boundary polygons from the grid cell centers.

A filter_array can be applied to extract boundaries around specific parts of the grid e.g. a region or a zone.

The concavity and precision of the boundaries are controlled by the alpha_factor. A low alpha_factor makes more precise boundaries, while a larger value makes more rough polygons.

Note that the alpha_factor is a multiplier (default value 1) on top of an auto estimated value, derived from the maximum xinc and yinc from the grid cells. Dependent on the regularity of the grid, tuning of the alpha_factor (up/down) is sometimes necessary to get satisfactory results.

Parameters:

alpha_factor (float) – An alpha multiplier, which controls the precision of the boundaries. A higher number will produce smoother and less accurate polygons. Not applied if convex is set to True.
convex (bool) – The default is False, which means that a “concave hull” algorithm is used. If convex is True, the alpha factor is overridden to a large number, producing a ‘convex’ shape boundary instead.
simplify (bool | dict[str, Any]) – If True, a simplification is done in order to reduce the number of points in the polygons, where tolerance is 0.1. Another alternative to True is to input a Dict on the form {"tolerance": 2.0, "preserve_topology": True}, cf. the Polygons.simplify() method. For details on e.g. tolerance, see Shapely’s simplify() method.
filter_array (ndarray | None) – An numpy boolean array with equal shape as the grid dimension, used to filter the grid cells and define where to extract boundaries.

Return type:

Polygons

Returns:

A XTGeo Polygons instance

Example:

grid = xtgeo.grid_from_roxar(project, "Simgrid")
# extract polygon for a specific region, here region 3
region = xtgeo.gridproperty_from_roxar(project, "Simgrid", "Regions")
filter_array = (region.values==3)
boundary = grid.get_boundary_polygons(filter_array=filter_array)

See also

The Polygons.boundary_from_points() class method.

get_bulk_volume(name='bulkvol', asmasked=True, precision=2)[source]

Return the geometric cell volume for all cells as a GridProperty object.

This method is currently experimental.

A bulk volume of a cornerpoint cell is actually a non-trivial and a non-unique entity. The volume is approximated by dividing the cell (hexahedron) into 6 tetrehedrons; there is however a large number of ways to do this division.

As default (precision=2) an average of two different ways to divide the cell into tetrahedrons is averaged.

Parameters:

name (str) – name of property, default to “bulkvol”
asmasked (bool) – are masked. Otherwise a numpy array will all bulk for all cells is returned
precision (int) – An number indication precision level, where a higher number means increased precision but also increased computing time. Currently 1, 2 (default), 4 are supported.

Return type:

GridProperty

Returns:

XTGeo GridProperty object

Added in version 2.13: (as experimental)

get_cell_volume(ijk=(1, 1, 1), activeonly=True, zerobased=False, precision=2)[source]

Return the bulk volume for a given cell.

This method is currently experimental.

A bulk volume of a cornerpoint cell is actually a non-trivial and a non-unique entity. The volume is approximated by dividing the cell (hexahedron) into 6 tetrehedrons; there is however a large number of ways to do this division.

As default (precision=2) an average of two different ways to divide the cell into tetrahedrons is averaged.

Parameters:

ijk (tuple) – A tuple of I J K (NB! cell counting starts from 1 unless zerobased is True).
activeonly (bool) – Skip undef cells if True; return None for inactive.
precision (int) – An even number indication precision level,where a higher number means increased precision but also increased computing time. Currently 1, 2, 4 are supported.

Return type:

float

Returns:

Cell total bulk volume

Example:

>>> import xtgeo
>>> grid = xtgeo.grid_from_file(reek_dir + "/REEK.EGRID")
>>> print(grid.get_cell_volume(ijk=(10,13,2)))
107056...

Added in version 2.13: (as experimental)

get_dataframe(activeonly=True, ijk=True, xyz=True, doubleformat=False)[source]

Returns a Pandas dataframe for the grid and any attached grid properties.

Note that this dataframe method is rather similar to GridProperties dataframe function, but have other defaults.

Parameters:

activeonly (bool) – If True (default), return only active cells.
ijk (bool) – If True (default), show cell indices, IX JY KZ columns
xyz (bool) – If True (default), show cell center coordinates.
doubleformat (bool) – If True, floats are 64 bit, otherwise 32 bit. Note that coordinates (if xyz=True) is always 64 bit floats.

Return type:

DataFrame

Returns:

A Pandas dataframe object

Example:

>>> import xtgeo
>>> grd = xtgeo.grid_from_file(reek_dir + "/REEK.EGRID", fformat="egrid")
>>> names = ["SOIL", "SWAT", "PRESSURE"]
>>> dates = [19991201]
>>> xpr = xtgeo.gridproperties_from_file(
...     reek_dir + "/REEK.UNRST",
...     fformat="unrst",
...     names=names,
...     dates=dates,
...     grid=grd,
... )
>>> grd.gridprops = xpr  # attach properties to grid

>>> df = grd.get_dataframe()

>>> # save as CSV file
>>> df.to_csv(outdir + "/mygrid.csv")

get_dualactnum_indices(order='C', fracture=False)[source]

Returns the 1D ndarray which holds the indices for matrix/fracture cases.

Parameters:

order (str) – “Either ‘C’ (default) or ‘F’ order).
fracture (bool) – If True use Fracture properties.

Return type:

ndarray | None

get_dx(name='dX', asmasked=True, metric='horizontal')[source]

Return the dX as GridProperty object.

Returns the average length of x direction edges for each cell as a GridProperty. The length is by default horizontal vector length (see the metric parameter).

Parameters:

name (str) – names of properties
asmasked (bool) – are masked.
metric (str) – One of the following metrics: * “euclid”: sqrt(dx^2 + dy^2 + dz^2) * “horizontal”: sqrt(dx^2 + dy^2) * “east west vertical”: sqrt(dy^2 + dz^2) * “north south vertical”: sqrt(dx^2 + dz^2) * “x projection”: dx * “y projection”: dy * “z projection”: dz

Return type:

GridProperty

Returns:

XTGeo GridProperty objects containing dx.

get_dy(name='dY', asmasked=True, metric='horizontal')[source]

Return the dY as GridProperty object.

Returns the average length of y direction edges for each cell as a GridProperty. The length is by default horizontal vector length (see the metric parameter).

Parameters:

name (str) – names of properties
asmasked (bool) – are masked.
metric (str) – One of the following metrics: * “euclid”: sqrt(dx^2 + dy^2 + dz^2) * “horizontal”: sqrt(dx^2 + dy^2) * “east west vertical”: sqrt(dy^2 + dz^2) * “north south vertical”: sqrt(dx^2 + dz^2) * “x projection”: dx * “y projection”: dy * “z projection”: dz

Return type:

GridProperty

Returns:

Two XTGeo GridProperty objects (dx, dy).

get_dz(name='dZ', flip=True, asmasked=True, metric='z projection')[source]

Return the dZ as GridProperty object.

Returns the average length of z direction edges for each cell as a GridProperty. The length is by default the z delta, ie. projected onto the z dimension (see the metric parameter).

Parameters:

name (str) – name of property
flip (bool) – Use False for Petrel grids were Z is negative down (experimental)
asmasked (bool) – True if only for active cells, False for all cells
metric (str) – One of the following metrics: * “euclid”: sqrt(dx^2 + dy^2 + dz^2) * “horizontal”: sqrt(dx^2 + dy^2) * “east west vertical”: sqrt(dy^2 + dz^2) * “north south vertical”: sqrt(dx^2 + dz^2) * “x projection”: dx * “y projection”: dy * “z projection”: dz

Return type:

GridProperty

Returns:

A XTGeo GridProperty object dZ

get_geometrics(allcells=False, cellcenter=True, return_dict=False, _ver=1)[source]

Get a list of grid geometrics such as origin, min, max, etc.

This returns a tuple: (xori, yori, zori, xmin, xmax, ymin, ymax, zmin, zmax, avg_rotation, avg_dx, avg_dy, avg_dz, grid_regularity_flag)

If a dictionary is returned, the keys are as in the list above.

Parameters:

allcells (bool) – If True, return also for inactive cells
cellcenter (bool) – If True, use cell center, otherwise corner coords
return_dict (bool) – If True, return a dictionary instead of a list, which is usually more convinient.
_ver (int) – Private option; only for developer!

Return type:

dict | tuple

Raises: Nothing

Example:

>>> mygrid = grid_from_file(reek_dir + "REEK.EGRID")
>>> gstuff = mygrid.get_geometrics(return_dict=True)
>>> print(f"X min/max is {gstuff['xmin']:.2f} {gstuff['xmax']:.2f}")
X min/max is 456620.79 467106.33

get_gridquality_properties()[source]

Return a GridProperties() instance with grid quality measures.

These measures are currently: :rtype: GridProperties

minangle_topbase (degrees) - minimum angle of top and base
maxangle_topbase (degrees) - maximum angle of top and base
minangle_topbase_proj (degrees) min angle projected (bird view)
maxangle_topbase_proj (degrees) max angle projected (bird view)
minangle_sides (degress) minimum angle, all side surfaces
maxangle_sides (degress) maximum angle, all side surfaces
collapsed (int) Integer, 1 of one or more corners are collpased in Z
faulted (int) Integer, 1 if cell is faulted (one or more neighbours offset)
negative_thickness (int) Integer, 1 if cell has negative thickness
concave_proj (int) 1 if cell is concave seen from projected bird view

Example:

# store grid quality measures in RMS
gprops = grd.gridquality()
for gprop in gprops:
    gprop.to_roxar(project, "MyGrid", gprop.name)

get_heights_above_ffl(ffl, option='cell_center_above_ffl')[source]

Returns 3 properties: htop, hbot and hmid, primarely for use in Sw models.”

Parameters:

ffl (GridProperty) – Free fluid level e.g. FWL (or level whatever is required; a level from which cells above will be shown as delta heights (positive), while cells below will have 0.0 values.
option (str) – How to compute values, as either “cell_center_above_ffl” or “cell_corners_above_ffl”. The first one looks at cell Z centerlines, and compute the top, the bottom and the midpoint. The second will look at cell corners, using the uppermost corner for top, and the lowermost corner for bottom. In both cases, values are modified if cell is intersected with the provided ffl.

Return type:

tuple[GridProperty, GridProperty, GridProperty]

Returns:

(htop, hbot, hmid) delta heights, as xtgeo GridProperty objects

Added in version 3.9.

get_ijk(names=('IX', 'JY', 'KZ'), asmasked=True, zerobased=False)[source]

Returns 3 xtgeo.grid3d.GridProperty objects: I counter, J counter, K counter.

Parameters:

names (tuple[str, str, str]) – a 3 x tuple of names per property (default IX, JY, KZ).
asmasked (bool) – If True, UNDEF cells are masked, default is True
zerobased (bool) – If True, counter start from 0, otherwise 1 (default=1).

Return type:

tuple[GridProperty, GridProperty, GridProperty]

get_ijk_from_points(points, activeonly=True, zerobased=False, dataframe=True, includepoints=True, columnnames=('IX', 'JY', 'KZ'), fmt='int', undef=-1)[source]

Returns a list/dataframe of cell indices based on a Points() instance.

If a point is outside the grid, -1 values are returned

Parameters:

points (Points) – A XTGeo Points instance
activeonly (bool) – If True, UNDEF cells are not included
zerobased (bool) – If True, counter start from 0, otherwise 1 (default=1).
dataframe (bool) – If True result is Pandas dataframe, otherwise a list of tuples
includepoints (bool) – If True, include the input points in result
columnnames (tuple) – Name of columns if dataframe is returned
fmt (str) – Format of IJK arrays (int/float). Default is “int”
undef (int or float) – Value to assign to undefined (outside) entries.

Return type:

DataFrame | list

Added in version 2.6.

Changed in version 2.8: Added keywords columnnames, fmt, undef

get_layer_slice(layer, top=True, activeonly=True)[source]

Get numpy arrays for cell coordinates e.g. for plotting.

In each cell there are 5 XY pairs, making a closed polygon as illustrated here:

XY3 < XY2 !~~~~~~~! ! ! ^ !~~~~~~~! XY0 -> XY1 XY4

Note that cell ordering is C ordering (row is fastest)

Parameters:

layer (int) – K layer, starting with 1 as topmost
tip (bool) – If True use top of cell, otherwise use base
activeonly (bool) – If True, only return active cells

Returns:

[[[X0, Y0], [X1, Y1]…[X4, Y4]], [[..][..]]…] icarray (np): On the form [ic1, ic2, …] where ic is cell count (C order)

Return type:

layerarray (np)

Example

Return two arrays forr cell corner for bottom layer:

grd = xtgeo.grid_from_file(REEKFILE)

parr, ibarr = grd.get_layer_slice(grd.nlay, top=False)

Added in version 2.3.

get_prop_by_name(name)[source]

Gets a property object by name lookup, return None if not present.

Return type:: GridProperty | None

get_property_between_surfaces(top, base, value=1, name='between_surfaces')[source]

Returns a 3D GridProperty object with <value> between two surfaces.”

Parameters:

top (RegularSurface) – The bounding top surface (RegularSurface object)
base (RegularSurface) – The bounding base surface (RegularSurface object)
value (int) – An integer > 0 to assign to cells between surfaces, 1 as default
name (str) – Name of the property, default is “between_surfaces”

Return type:

GridProperty

Returns:

xtgeo GridProperty object with <value> if cell center is between surfaces, otherwise 0. Note that the property wil be discrete if input value is an integer, otherwise it will be continuous.

Added in version 4.5.

get_randomline(fencespec, prop, zmin=None, zmax=None, zincrement=1.0, hincrement=None, atleast=5, nextend=2)[source]

Get a sampled randomline from a fence spesification.

This randomline will be a 2D numpy with depth on the vertical axis, and length along as horizontal axis. Undefined values will have the np.nan value.

The input fencespec is either a 2D numpy where each row is X, Y, Z, HLEN, where X, Y are UTM coordinates, Z is depth/time, and HLEN is a length along the fence, or a Polygons instance.

If input fencspec is a numpy 2D, it is important that the HLEN array has a constant increment and ideally a sampling that is less than the Grid resolution. If a Polygons() instance, this will be automated if hincrement is None.

Parameters:

fencespec (ndarray or Polygons) – 2D numpy with X, Y, Z, HLEN as rows or a xtgeo Polygons() object.
prop (GridProperty or str) – The grid property object, or name, which shall be plotted.
zmin (float) – Minimum Z (default is Grid Z minima/origin)
zmax (float) – Maximum Z (default is Grid Z maximum)
zincrement (float) – Sampling vertically, default is 1.0
hincrement (float) – Resampling horizontally. This applies only if the fencespec is a Polygons() instance. If None (default), the distance will be deduced automatically.
atleast (int) – Minimum number of horizontal samples This applies only if the fencespec is a Polygons() instance.
nextend (int) – Extend with nextend * hincrement in both ends. This applies only if the fencespec is a Polygons() instance.

Returns:

(hmin, hmax, vmin, vmax, ndarray2d)

Return type:

A tuple

Raises:

ValueError – Input fence is not according to spec.

Example:

mygrid = xtgeo.grid_from_file("somegrid.roff")
poro = xtgeo.gridproperty_from_file("someporo.roff")
mywell = xtgeo.well_from_file("somewell.rmswell")
fence = mywell.get_fence_polyline(sampling=5, tvdmin=1750, asnumpy=True)
(hmin, hmax, vmin, vmax, arr) = mygrid.get_randomline(
     fence, poro, zmin=1750, zmax=1850, zincrement=0.5,
)
# matplotlib ...
plt.imshow(arr, cmap="rainbow", extent=(hmin1, hmax1, vmax1, vmin1))

Added in version 2.1.

See also

Class Polygons: The method get_fence() which can be used to pregenerate fencespec

get_subgrids()[source]

Get the subgrids on a simplified ordered dictionary.

The simplified dictionary is on the form {“name1”: 3, “name2”: 5}

Return type:: dict[str, int] | None

get_vtk_esg_geometry_data()[source]

Get grid geometry data suitable for use with VTK’s vtkExplicitStructuredGrid.

Builds and returns grid geometry data in a format tailored for use with VTK’s explicit structured grid (ESG). Essentially this entails building an unstructured grid representation where all the grid cells are represented as hexahedrons with explicit connectivities. The cell connectivity array refers into the accompanying vertex array.

In VTK, cell order increases in I fastest, then J, then K.

Return type:: tuple[ndarray, ndarray, ndarray, ndarray]

The returned tuple contains:

numpy array with dimensions in terms of points (not cells)
vertex array, numpy array with vertex coordinates
connectivity array for all the cells, numpy array with integer indices
inactive cell indices, numpy array with integer indices

This function also tries to remove/weld duplicate vertices, but this is still a work in progress.

Example usage with VTK:

dims, vert_arr, conn_arr, inact_arr = xtg_grid.get_vtk_esg_geometry_data()

vert_arr = vert_arr.reshape(-1, 3)
vtk_points = vtkPoints()
vtk_points.SetData(numpy_to_vtk(vert_arr, deep=1))

vtk_cell_array = vtkCellArray()
vtk_cell_array.SetData(8, numpy_to_vtkIdTypeArray(conn_arr, deep=1))

vtk_esgrid = vtkExplicitStructuredGrid()
vtk_esgrid.SetDimensions(dims)
vtk_esgrid.SetPoints(vtk_points)
vtk_esgrid.SetCells(vtk_cell_array)

vtk_esgrid.ComputeFacesConnectivityFlagsArray()

ghost_arr_vtk = vtk_esgrid.AllocateCellGhostArray()
ghost_arr_np = vtk_to_numpy(ghost_arr_vtk)
ghost_arr_np[inact_arr] = vtkDataSetAttributes.HIDDENCELL

Added in version 2.20.

get_vtk_geometries()[source]

Get necessary arrays on correct layout for VTK ExplicitStructuredGrid usage.

Example:

import pyvista as pv
dim, crn, inactind = grd.get_vtk_geometries()
grid = pv.ExplicitStructuredGrid(dim, crn)
grid.flip_z(inplace=True)
grid.hide_cells(inactind, inplace=True)
grid.plot(show_edges=True)

Return type:: tuple[ndarray, ndarray, ndarray]
Returns:: dims, corners, inactive_indices

Added in version 2.18.

get_xyz(names=('X_UTME', 'Y_UTMN', 'Z_TVDSS'), asmasked=True)[source]

Returns 3 xtgeo.grid3d.GridProperty objects for x, y, z coordinates.

The values are mid cell values. Note that ACTNUM is ignored, so these is also extracted for UNDEF cells (which may have weird coordinates). However, the option asmasked=True will mask the numpies for undef cells.

Parameters:

names (tuple[str, str, str]) – a 3 x tuple of names per property (default is X_UTME,
Y_UTMN
Z_TVDSS).
asmasked (bool) – If True, then inactive cells is masked (numpy.ma).

Return type:

tuple[GridProperty, GridProperty, GridProperty]

get_xyz_cell_corners(ijk=(1, 1, 1), activeonly=True, zerobased=False)[source]

Return a 8 * 3 tuple x, y, z for each corner.

2       3
!~~~~~~~!
!  top  !
!~~~~~~~!    Listing corners with Python index (0 base)
0       1

6       7
!~~~~~~~!
!  base !
!~~~~~~~!
4       5

Parameters:

ijk (tuple) – A tuple of I J K (NB! cell counting starts from 1 unless zerobased is True)
activeonly (bool) – Skip undef cells if set to True.

Return type:

tuple[int, ...]

Returns:

A tuple with 24 elements (x1, y1, z1, … x8, y8, z8): for 8 corners. None if cell is inactive and activeonly=True.

Example:

>>> grid = grid_from_file(reek_dir + "REEK.EGRID")
>>> print(grid.get_xyz_cell_corners(ijk=(10,13,2)))
(458704.10..., 1716.969970703125)

Raises:: RuntimeWarning if spesification is invalid. –

get_xyz_corners(names=('X_UTME', 'Y_UTMN', 'Z_TVDSS'))[source]

Returns 8*3 (24) xtgeo.grid3d.GridProperty objects, x, y, z for each corner.

The values are cell corner values. Note that ACTNUM is ignored, so these is also extracted for UNDEF cells (which may have weird coordinates).

2       3
!~~~~~~~!
!  top  !
!~~~~~~~!    Listing corners with Python index (0 base)
0       1

6       7
!~~~~~~~!
!  base !
!~~~~~~~!
4       5

Parameters:: names (list) – Generic name of the properties, will have a number added, e.g. X0, X1, etc.
Return type:: tuple[GridProperty, ...]

Example:

>>> import xtgeo
>>> grid = xtgeo.create_box_grid((2,2,2))
>>> gps = grid.get_xyz_corners() # list of 24 grid properties
>>> len(gps)
24
>>> gps[0].values.tolist()
[[[0.0, 0.0], ... [[1.0, 1.0], [1.0, 1.0]]]

Raises:: RunetimeError if corners has wrong spesification –

get_zoneprop_from_subgrids()[source]

Make a XTGeo GridProperty instance for a Zone property subgrid index.

Return type:: NoReturn

property gridprops: Return or set a XTGeo GridProperties objects attached to the Grid.

property ijk_handedness

IJK handedness for grids, “right” or “left”.

For a non-rotated grid with K increasing with depth, ‘left’ is corner in lower-left, while ‘right’ is origin in upper-left corner.

Type:: str

inactivate_by_dz(threshold)[source]

Inactivate cells thinner than a given threshold.

Return type:: None

inactivate_inside(poly, layer_range=None, inside=True, force_close=False)[source]

Inacativate grid inside a polygon.

The Polygons instance may consist of several polygons. If a polygon is open, then the flag force_close will close any that are not open when doing the operations in the grid.

Parameters:

poly (Polygons) – A polygons object
layer_range (tuple) – A tuple of two ints, upper layer = 1, e.g. (1, 14). Note that base layer count is 1 (not zero)
inside (bool) – True if remove inside polygon
force_close (bool) – If True then force polygons to be closed.

Raises:

RuntimeError – If a problems with one or more polygons.
ValueError – If Polygon is not a XTGeo object

Return type:

None

inactivate_outside(poly, layer_range=None, force_close=False)[source]

Inacativate grid outside a polygon.

Return type:: None

make_zconsistent(zsep=1e-05)[source]

Make the 3D grid consistent in Z, by a minimal gap (zsep).

Parameters:: zsep (float) – Minimum gap
Return type:: None

property metadata

Return or set metadata instance of type MetaDataCPGeometry.

Type:: obj

property nactive

Returns the number of active cells (read only).

Type:: int

property name

Name attribute of grid.

Type:: str

property ncol: Returns the NCOL (NX or Ncolumns) number of cells.

property nlay: Returns the NLAY (NZ or Nlayers) number of cells.

property nrow: Returns the NROW (NY or Nrows) number of cells.

property ntotal: Returns the total number of cells (read only).

property propnames: Returns a list of property names that are hooked to a grid.

property props

Return or set a list of XTGeo GridProperty objects.

When setting, the dimension of the property object is checked, and will raise an IndexError if it does not match the grid.

When setting props, the current property list is replaced.

See also append_prop() method to add a property to the current list.

reduce_to_one_layer()[source]

Reduce the grid to one single layer.

Example:

>>> import xtgeo
>>> grid = xtgeo.grid_from_file(reek_dir + "/REEK.EGRID")
>>> grid.nlay
14
>>> grid.reduce_to_one_layer()
>>> grid.nlay
1

Return type:: None

refine_vertically(rfactor, zoneprop=None)[source]

Refine vertically, proportionally.

The rfactor can be a scalar or a dictionary.

If rfactor is a dict and zoneprop is None, then the current subgrids array is used. If zoneprop is defined, the current subgrid index will be redefined for the case. A warning will be issued if subgrids are defined, but the give zone property is inconsistent with this.

Also, if a zoneprop is defined but no current subgrids in the grid, then subgrids will be added to the grid, if more than 1 subgrid.

Parameters:

self (object) – A grid XTGeo object
rfactor (scalar or dict) – Refinement factor, if dict, then the dictionary must be consistent with self.subgrids if this is present.
zoneprop (GridProperty) – Zone property; must be defined if rfactor is a dict

Returns:

if.. RuntimeError: if mismatch in dimensions for rfactor and zoneprop

Return type:

ValueError

Examples:

# refine vertically all by factor 3

grd.refine_vertically(3)

# refine by using a dictionary; note that subgrids must exist!
# and that subgrids that are not mentioned will have value 1
# in refinement (1 is meaning no refinement)

grd.refine_vertically({1: 3, 2: 4, 4: 1})

# refine by using a a dictionary and a zonelog. If subgrids exists
# but are inconsistent with the zonelog; the current subgrids will
# be redefined, and a warning will be issued! Note also that ranges
# in the dictionary rfactor and the zone property must be aligned.

grd.refine_vertically({1: 3, 2: 4, 4: 0}, zoneprop=myzone)

rename_subgrids(names)[source]

Rename the names in the subgrids with the new names.

Parameters:: names (list) – List of new names, length of list must be same as length of subgrids
Return type:: None

Example:

>>> grd = create_box_grid((3, 3, 3))
>>> grd.subgrids = dict(
...     [("1", range(1,2)), ("2", range(2,3)), ("3", range(3,4))]
... )
>>> grd.rename_subgrids(["Inky", "Tinky", "Pinky"])

Raises:

ValueError – Input names not a list or a tuple
ValueError – Lenght of names list not same as number of subgrids

Added in version 2.12.

report_zone_mismatch(well=None, zonelogname='ZONELOG', zoneprop=None, zonelogrange=(0, 9999), zonelogshift=0, depthrange=None, perflogname=None, perflogrange=(1, 9999), filterlogname=None, filterlogrange=(1e-32, 9999.0), resultformat=1)[source]

Reports mismatch between wells and a zone.

Approaches on matching:

Use the well zonelog as basis, and compare sampled zone with that interval. This means that zone cells outside well range will not be counted
Compare intervals with wellzonation in range or grid zonations in range. This gives a wider comparison, and will capture cases where grid zonations is outside well zonation

Note if zonelogname and/or filterlogname and/or perflogname is given, and such log(s) are not present, then this function will return None.

Parameters:

well (Well) – a XTGeo well object
zonelogname (str) – Name of the zone logger
zoneprop (GridProperty) – Grid property instance to use for zonation
zonelogrange (tuple) – zone log range, from - to (inclusive)
zonelogshift (int) – Deviation (numerical shift) between grid and zonelog, e.g. if Zone property starts with 1 and this corresponds to a zonelog index of 3 in the well, the shift shall be -2.
depthrange (tuple) – Interval for search in TVD depth, to speed up
perflogname (str) – Name of perforation log to filter on (> 0 default).
perflogrange (tuple) – Range of values where perforations are present.
filterlogname (str) – General filter, work as perflog, filter on values > 0
filterlogrange (tuple) – Range of values where filter shall be present.
resultformat (int) – If 1, consider the zonelogrange in the well as basis for match ratio, return (percent, match count, total count). If 2 then a dictionary is returned with various result members

Returns:

report dependent on resultformat

A tuple with 3 members:
(match_as_percent, number of matches, total count) approach 1
A dictionary with keys:
- MATCH1 - match as percent, approach 1
- MCOUNT1 - number of match samples approach 1
- TCOUNT1 - total number of samples approach 1
- MATCH2 - match as percent, approach 2
- MCOUNT2 - a.a for option 2
- TCOUNT2 - a.a. for option 2
- WELLINTV - a Well() instance for the actual interval
None, if perflogname or zonelogname of filtername is given, but the log does not exists for the well

Return type:

res (tuple or dict)

Example:

g1 = xtgeo.grid_from_file("gullfaks2.roff")

z = xtgeo.gridproperty_from_file(gullfaks2_zone.roff", name="Zone")

w2 = xtgeo.well_from_file("34_10-1.w", zonelogname="Zonelog")

w3 = xtgeo.well_from_file("34_10-B-21_B.w", zonelogname="Zonelog"))

wells = [w2, w3]

for w in wells:
    response = g1.report_zone_mismatch(
        well=w, zonelogname="ZONELOG", zoneprop=z,
        zonelogrange=(0, 19), depthrange=(1700, 9999))

    print(response)

Changed in version 2.8: Added several new keys and better precision in result

Changed in version 2.11: Added perflogrange and filterlogrange

reverse_row_axis(ijk_handedness=None)[source]

Reverse the row axis (J indices).

This means that IJK system will switched between a left vs right handed system. It is here (by using ijk_handedness key), possible to set a wanted stated.

Note that properties that are assosiated with the grid (through the gridprops or props attribute) will also be reversed (which is desirable).

Parameters:: ijk_handedness (str) – If set to “right” or “left”, do only reverse rows if handedness is not already achieved.
Return type:: None

Example:

grd = xtgeo.grid_from_file("somefile.roff")
prop1 = xtgeo.gridproperty_from_file("somepropfile1.roff")
prop2 = xtgeo.gridproperty_from_file("somepropfile2.roff")

grd.props = [prop1, prop2]

# secure that the grid geometry is IJK right-handed
grd.reverse_row_axis(ijk_handedness="right")

Added in version 2.5.

property roxgrid: Get the Roxar native proj.grid_models[gname].get_grid() object.

property roxindexer: The Roxar native proj.grid_models[gname].get_grid().grid_indexer object.

set_actnum(actnum)[source]

Modify the existing active cell index, ACTNUM.

Parameters:: actnum (GridProperty) – a gridproperty instance with 1 for active cells, 0 for inactive cells
Return type:: None

Example::

>>> mygrid = create_box_grid((5,5,5))
>>> act = mygrid.get_actnum()
>>> act.values[:, :, :] = 1
>>> act.values[:, :, 4] = 0
>>> mygrid.set_actnum(act)

set_subgrids(sdict)[source]

Set the subgrid from a simplified ordered dictionary.

The simplified dictionary is on the form {“name1”: 3, “name2”: 5}

Note that the input must be an dict!

Return type:: None

property subgrids

A dict with subgrid name and an array as value.

I.e. a dict on the form {"name1": [1, 2, 3, 4], "name2": [5, 6, 7], "name3": [8, 9, 10]}, here meaning 3 subgrids where upper is 4 cells vertically, then 3, then 3. The numbers must sum to NLAY.

The numbering in the arrays are 1 based; meaning uppermost layer is 1 (not 0).

None will be returned if no subgrid indexing is present.

See also set_subgrids() and get_subgrids() which have a similar function, but differs a bit.

Note that this design is a bit different from the Roxar API, where repeated sections are allowed, and where indices start from 0, not one.

Type:: list of int

subgrids_from_zoneprop(zoneprop)[source]

Estimate subgrid index from a zone property.

The new will esimate which will replace the current if any.

Parameters:

zoneprop (GridProperty) – a XTGeo GridProperty instance.

Return type:

dict[str, int] | None

Returns:

Will also return simplified dictionary is on the form: {“name1”: 3, “name2”: 5}

to_file(gfile, fformat='roff')[source]

Export grid geometry to file, various vendor formats.

Parameters:

gfile (str) – Name of output file
fformat (str) – File format; roff/roff_binary/roff_ascii/ grdecl/bgrdecl/egrid.

Raises:

OSError – Directory does not exist

Return type:

None

Example::

>>> grid = create_box_grid((2,2,2))
>>> grid.to_file(outdir + "/myfile.roff")

to_hdf(gfile, compression=None, chunks=False, subformat=844)[source]

Export grid geometry to HDF5 storage format (experimental!).

Parameters:

gfile (str | Path) – Name of output file
compression (str | None) – Compression method, such as “blosc” or “lzf”
chunks (bool | None) – chunks settings
subformat (int | None) – Format of output arrays in terms of bytes. E.g. 844 means 8 byte for COORD, 4 byte for ZCORNS, 4 byte for ACTNUM.

Raises:

OSError – Directory does not exist

Return type:

Union[str, Path, StringIO, BytesIO]

Returns:

Used file object, or None if memory stream

Example

>>> grid = create_box_grid((2,2,2))
>>> filename = grid.to_hdf(outdir + "/myfile_grid.h5")

to_roxar(project, gname, realisation=0, info=False, method='cpg')[source]

Export (upload) a grid from XTGeo to RMS via Roxar API.

Note

When project is file path (direct access, outside RMS) then to_roxar() will implicitly do a project save. Otherwise, the project will not be saved until the user do an explicit project save action.

Parameters:

project (str or roxar._project) – Inside RMS use the magic ‘project’, else use path to RMS project, or a project reference
gname (str) – Name of grid in RMS
realisation (int) – Realisation umber, default 0
info (bool) – TBD
method (str) – Save approach, the default is ‘cpg’ which applied the internal RMS API, while ‘roff’ will do a save to a temporary area, and then load into RMS. For strange reasons, the ‘roff’ method is per RMS version 14.2 a faster method (strange since file i/o is way more costly than direct API access, in theory).

Return type:

None

Note

When storing grids that needs manipulation of inactive cells, .e.g. activate_all() method, using method=’roff’ is recommended. The reason is that saving cells using ‘cpg’ method will force zero depth values on inactive cells.

to_xtgf(gfile, subformat=844)[source]

Export grid geometry to xtgeo native binary file format (experimental!).

Parameters:

gfile (str | Path) – Name of output file
subformat (int | None) – Format of output arryas in terms of bytes. E.g. 844 means 8 byte for COORD, 4 byte for ZCORNS, 4 byte for ACTNUM.

Raises:

OSError – Directory does not exist

Returns:

Used pathlib.Path file object, or None if: memory stream

Return type:

gfile (pathlib.Path)

Example::

>>> grid = create_box_grid((2,2,2))
>>> filename = grid.to_xtgf(outdir + "/myfile.xtg")

translate_coordinates(translate=(0.0, 0.0, 0.0), flip=(1, 1, 1))[source]

Translate (move) and/or flip grid coordinates in 3D.

By ‘flip’ here, it means that the full coordinate array are multiplied with -1.

Parameters:

translate (tuple) – Translation distance in X, Y, Z coordinates
flip (tuple) – Flip array. The flip values must be 1 or -1.

Raises:

RuntimeError – If translation goes wrong for unknown reasons

Return type:

None

property vectordimensions

The storage grid array dimensions tuple of 3 integers (read only).

The tuple is (ncoord, nzcorn, nactnum).

Type:: 3-tuple

Grid property (single)

Functions

xtgeo.gridproperty_from_file(pfile, fformat=None, **kwargs)[source]

Make a GridProperty instance directly from a file import.

Note that the the property may be linked to its geometrical grid through the grid= option. Sometimes this is required, for instance for most Eclipse input.

Parameters:

pfile (Union[str, Path, StringIO, BytesIO]) – Name of file to be imported.
fformat (str | None) – File format to be used (roff/init/unrst/grdecl). Defaults to None and tries to infer from file extension.
name (str) – Name of property to import
date (int or str) – For restart files, date in YYYYMMDD format. Also the YYYY-MM-DD form is allowed (string), and for Eclipse, mnemonics like ‘first’, ‘last’ is also allowed.
grid (Grid, optional) – Grid object for checks. Optional for ROFF, required for Eclipse).
gridlink (bool) – If True, and grid is not None, a link from the grid instance to the property is made. If False, no such link is made. Avoiding gridlink is recommended when running statistics of multiple realisations of a property.
fracture (bool) – Only applicable for DUAL POROSITY systems. If True then the fracture property is read. If False then the matrix property is read. Names will be appended with “M” or “F”
ijrange (list-like) – A list of 4 numbers (i1, i2, j1, j2) for a subrange of cells to read. Only applicable for xtgcpprop format.
zerobased (bool) – Input if cells counts are zero- or one-based in ijrange. Only applicable for xtgcpprop format.

Return type:

GridProperty

Returns:

A GridProperty instance.

Examples:

import xtgeo
gprop = xtgeo.gridproperty_from_file("somefile.roff", fformat="roff")

# or

mygrid = xtgeo.grid_from_file("ECL.EGRID")
pressure_1 = xtgeo.gridproperty_from_file("ECL.UNRST", name="PRESSURE",
                                         date="first", grid=mygrid)

xtgeo.gridproperty_from_roxar(project, gname, pname, realisation=0, faciescodes=False)[source]

Make a GridProperty instance directly inside RMS.

Parameters:

project (Any) – The Roxar project path or magical pre-defined variable in RMS
gname (str) – Name of the grid model
pname (str) – Name of the grid property
realisation (int) – Realisation number (default 0; first)
faciescodes (bool) – If a Roxar property is of the special body_facies type (e.g. result from a channel facies object modelling), the default is to get the body code values. If faciescodes is True, the facies code values will be read instead. For other roxar properties this key is not relevant.

Return type:

GridProperty

Returns:

A GridProperty instance.

Example:

import xtgeo
myporo = xtgeo.gridproperty_from_roxar(project, 'Geogrid', 'Poro')

Classes

class xtgeo.GridProperty(gridlike=None, ncol=None, nrow=None, nlay=None, name='unknown', discrete=False, date=None, grid=None, linkgeometry=True, fracture=False, codes=None, dualporo=False, dualperm=False, roxar_dtype=None, values=None, roxorigin=False, filesrc=None)[source]

Bases: _Grid3D

Class for a single 3D grid property, e.g porosity or facies.

An GridProperty instance may or may not ‘belong’ to a grid (geometry) object. E.g. for ROFF input, ncol, nrow, nlay are given in the import file and the grid geometry file is not needed. For many Eclipse files, the grid geometry is needed as this holds the active number indices (ACTNUM).

Normally the instance is created when importing a grid property from file, but it can also be created directly, as e.g.:

poro = GridProperty(ncol=233, nrow=122, nlay=32)

The grid property values someinstance.values by themselves is a 3D masked numpy usually as either float64 (double) or int32 (if discrete), and undefined cells are displayed as masked. The internal array order is now C_CONTIGUOUS. (i.e. not in Eclipse manner). A 1D view (C order) is achieved by the values1d property, e.g.:

poronumpy = poro.values1d

Changed in version 2.6: Possible to make GridProperty instance directly from Grid

Changed in version 2.8: Possible to base it on existing GridProperty instance

Instantiating.

Parameters:

gridlike (Grid | GridProperty | None) – Grid or GridProperty instance, or leave blank.
ncol (int | None) – Number of columns (nx). Defaults to 4.
nrow (int | None) – Number of rows (ny). Defaults to 3.
nlay (int | None) – Number of layers (nz). Defaults to 5.
name (str) – Name of property. Defaults to “unknown”.
discrete (bool) – True or False. Defaults to False.
date (str | None) – Date on YYYYMMDD form.
grid (Grid | None) – Attached Grid object.
linkgeometry (bool) – If True, establish a link between GridProperty and Grid. Defaults to True.
fracture (bool) – True if fracture option (relevant for flow simulator data). Defaults to False.
codes (dict[int, str] | None) – Codes in case a discrete property e.g. {1: “Sand”, 4: “Shale”}.
dualporo (bool) – True if dual porosity system. Defaults to False.
dualperm (bool) – True if dual porosity and dual permeability system. Defaults to False.
roxar_dtype (Union[type[uint8], type[uint16], type[float32], None]) – Specify Roxar datatype e.g. np.uint8.
values (ndarray | float | int | None) – Values to apply.
roxorigin (bool) – True if the object comes from Roxar API. Defaults to False.
filesrc (str | None) – Where the file came from.

Raises:

RuntimeError – If something goes wrong (e.g. file not found).

Examples:

import xtgeo
myprop = xtgeo.gridproperty_from_file("emerald.roff", name="PORO")

# or

values = np.ma.ones((12, 17, 10), dtype=np.float64),
myprop = GridProperty(ncol=12, nrow=17, nlay=10,
                      values=values, discrete=False,
                      name="MyValue")

# or create properties from a Grid() instance

mygrid = xtgeo.grid_from_file("grid.roff")
myprop1 = xtgeo.GridProperty(mygrid, name="PORO")
myprop2 = xtgeo.GridProperty(mygrid, name="FACIES", discrete=True, values=1,
                       linkgeometry=True)  # alternative 1
myprop2.geometry = mygrid  # alternative 2 to link grid geometry to property

# from Grid instance:
grd = xtgeo.grid_from_file("somefile_grid_file")
myprop = GridProperty(grd, values=99, discrete=True)  # based on grd

# or from existing GridProperty instance:
myprop2 = GridProperty(myprop, values=99, discrete=False)  # based on myprop

Public Data Attributes:

`metadata`	Get or set metadata object instance of type MetaDataCPProperty.
`name`	Get or set the property name.
`dimensions`	Get the grid dimensions as a NamedTuple of 3 integers.
`nactive`	Get the number of active cells.
`geometry`	Get or set the linked geometry, i.e. the Grid instance.
`actnum_indices`	Get the 1D ndarray which holds the indices for active cells given in 1D, C order.
`isdiscrete`	Get or set whether this property is discrete.
`dtype`	Get or set the `values` numpy dtype.
`filesrc`	Get or set the GridProperty file src (if any).
`roxar_dtype`	Get or set the roxar dtype (if any).
`date`	Get or set the property date as string in YYYYMMDD format.
`codes`	Get or set the property codes as a dictionary.
`ncodes`	Get number of codes if discrete grid property.
`values`	Get or set the grid property as a masked 3D numpy array.
`ntotal`	Get total number of cells (ncol * nrow * nlay).
`roxorigin`	Get boolean value of True if the property comes from ROXAPI.
`values1d`	Get a masked 1D array view of values.
`undef`	Get the actual undef value for floats or ints in numpy arrays.
`undef_limit`	Get the undef limit number, which is slightly less than the undef value.

Inherited from _Grid3D

`ncol`	Returns the NCOL (NX or Ncolumns) number of cells.
`nrow`	Returns the NROW (NY or Nrows) number of cells.
`nlay`	Returns the NLAY (NZ or Nlayers) number of cells.

Public Methods:

`generate_hash`()	Generates a sha256 hash id representing a GridProperty.
`methods`()	A list of methods in the class as a string.
`ensure_correct_values`(ncol, nrow, nlay, invalues)	Ensures that values is a 3D masked numpy (ncol, nrol, nlay).
`to_file`(pfile[, fformat, name, append, ...])	Export the grid property to file.
`to_roxar`(projectname, gridname, propertyname)	Store a grid model property into a RMS project.
`describe`([flush])	Describe a GridProperty instance by printing its properties to stdout
`get_npvalues3d`([fill_value])	Get a pure numpy copy (not masked) of the values in 3D shape.
`get_actnum`([name, asmasked])	Return an ACTNUM GridProperty object.
`get_active_npvalues1d`()	Get the active cells as a 1D numpy masked array.
`get_npvalues1d`([activeonly, fill_value, order])	Return the grid property as a 1D numpy array (copy) for active or all cells, but inactive have a fill value.
`copy`([newname])	Copy a GridProperty object to another instance.
`mask_undef`()	Make UNDEF values masked.
`crop`(spec)	Crop a property between grid coordinates.
`get_xy_value_lists`([grid, activeonly])	Get lists of xy coords and values for Webportal format.
`get_values_by_ijk`(iarr, jarr, karr[, base])	Get a 1D ndarray of values by I J K arrays.
`discrete_to_continuous`()	Convert from discrete to continuous values.
`continuous_to_discrete`()	Convert from continuous to discrete values.
`operation_polygons`(poly, value[, opname, inside])	A generic function for doing 3D grid property operations restricted to inside or outside polygon(s).
`add_inside`(poly, value)	Add a value (scalar) inside polygons.
`add_outside`(poly, value)	Add a value (scalar) outside polygons.
`sub_inside`(poly, value)	Subtract a value (scalar) inside polygons.
`sub_outside`(poly, value)	Subtract a value (scalar) outside polygons.
`mul_inside`(poly, value)	Multiply a value (scalar) inside polygons.
`mul_outside`(poly, value)	Multiply a value (scalar) outside polygons.
`div_inside`(poly, value)	Divide a value (scalar) inside polygons.
`div_outside`(poly, value)	Divide a value (scalar) outside polygons.
`set_inside`(poly, value)	Set a value (scalar) inside polygons.
`set_outside`(poly, value)	Set a value (scalar) outside polygons.

__init__(gridlike=None, ncol=None, nrow=None, nlay=None, name='unknown', discrete=False, date=None, grid=None, linkgeometry=True, fracture=False, codes=None, dualporo=False, dualperm=False, roxar_dtype=None, values=None, roxorigin=False, filesrc=None)[source]

Instantiating.

Parameters:

gridlike (Grid | GridProperty | None) – Grid or GridProperty instance, or leave blank.
ncol (int | None) – Number of columns (nx). Defaults to 4.
nrow (int | None) – Number of rows (ny). Defaults to 3.
nlay (int | None) – Number of layers (nz). Defaults to 5.
name (str) – Name of property. Defaults to “unknown”.
discrete (bool) – True or False. Defaults to False.
date (str | None) – Date on YYYYMMDD form.
grid (Grid | None) – Attached Grid object.
linkgeometry (bool) – If True, establish a link between GridProperty and Grid. Defaults to True.
fracture (bool) – True if fracture option (relevant for flow simulator data). Defaults to False.
codes (dict[int, str] | None) – Codes in case a discrete property e.g. {1: “Sand”, 4: “Shale”}.
dualporo (bool) – True if dual porosity system. Defaults to False.
dualperm (bool) – True if dual porosity and dual permeability system. Defaults to False.
roxar_dtype (Union[type[uint8], type[uint16], type[float32], None]) – Specify Roxar datatype e.g. np.uint8.
values (ndarray | float | int | None) – Values to apply.
roxorigin (bool) – True if the object comes from Roxar API. Defaults to False.
filesrc (str | None) – Where the file came from.

Raises:

RuntimeError – If something goes wrong (e.g. file not found).

Examples:

import xtgeo
myprop = xtgeo.gridproperty_from_file("emerald.roff", name="PORO")

# or

values = np.ma.ones((12, 17, 10), dtype=np.float64),
myprop = GridProperty(ncol=12, nrow=17, nlay=10,
                      values=values, discrete=False,
                      name="MyValue")

# or create properties from a Grid() instance

mygrid = xtgeo.grid_from_file("grid.roff")
myprop1 = xtgeo.GridProperty(mygrid, name="PORO")
myprop2 = xtgeo.GridProperty(mygrid, name="FACIES", discrete=True, values=1,
                       linkgeometry=True)  # alternative 1
myprop2.geometry = mygrid  # alternative 2 to link grid geometry to property

# from Grid instance:
grd = xtgeo.grid_from_file("somefile_grid_file")
myprop = GridProperty(grd, values=99, discrete=True)  # based on grd

# or from existing GridProperty instance:
myprop2 = GridProperty(myprop, values=99, discrete=False)  # based on myprop

property actnum_indices: Get the 1D ndarray which holds the indices for active cells given in 1D, C order.

add_inside(poly, value)[source]

Add a value (scalar) inside polygons.

Return type:: None

add_outside(poly, value)[source]

Add a value (scalar) outside polygons.

Return type:: None

property codes: Get or set the property codes as a dictionary.

continuous_to_discrete()[source]

Convert from continuous to discrete values.

Return type:: None

copy(newname=None)[source]

Copy a GridProperty object to another instance.

Parameters:: newname (str | None) – Give the copied instance a new name.
Return type:: GridProperty
Returns:: A copy of the GridProperty instance.

>>> import xtgeo
>>> myporo = xtgeo.gridproperty_from_file(
...    reek_dir + '/reek_sim_poro.roff',
...    name="PORO"
... )
>>> mycopy = myporo.copy(newname='XPROP')
>>> print(mycopy.name)
XPROP

crop(spec)[source]

Crop a property between grid coordinates.

Parameters:: spec (tuple[tuple[int, int], tuple[int, int], tuple[int, int]]) – Provide a tuple of i, j, k lower and upper bounds to crop between, e.g. ((1, 3), (2, 4), (1, 5)) would crop a grid property such that only values from 1:3 in the i plane, 2:4 in the j plane, and 1:5 in the k plane would be present.
Return type:: None

property date: Get or set the property date as string in YYYYMMDD format.

describe(flush=True)[source]

Describe a GridProperty instance by printing its properties to stdout

Parameters:: flush (bool) – Print to stdout. True by default.
Return type:: str
Returns:: A string description of the grid property instance.

property dimensions: Get the grid dimensions as a NamedTuple of 3 integers.

discrete_to_continuous()[source]

Convert from discrete to continuous values.

Return type:: None

div_inside(poly, value)[source]

Divide a value (scalar) inside polygons.

Return type:: None

div_outside(poly, value)[source]

Divide a value (scalar) outside polygons.

Return type:: None

property dtype

Get or set the values numpy dtype.

When setting, note that the the dtype must correspond to the isdiscrete property. Hence dtype cannot alter isdiscrete status

Example:

if myprop.isdiscrete:
    myprop.dtype = np.uint16

ensure_correct_values(ncol, nrow, nlay, invalues)[source]

Ensures that values is a 3D masked numpy (ncol, nrol, nlay).

Parameters:

ncol (int) – Number of columns.
nrow (int) – Number of rows.
nlay (int) – Number of layers.
invalues (Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[bool | int | float | complex | str | bytes]]) – Values to process.

Return type:

MaskedArray

Returns:

The values as a masked numpy array.

property filesrc: Get or set the GridProperty file src (if any).

generate_hash()[source]

Generates a sha256 hash id representing a GridProperty.

Return type:: str
Returns:: A unique hash id string.

Added in version 2.10.

property geometry: Get or set the linked geometry, i.e. the Grid instance.

get_active_npvalues1d()[source]

Get the active cells as a 1D numpy masked array.

Return type:: MaskedArray
Returns:: The grid property as a 1D numpy masked array, active cells only.

get_actnum(name='ACTNUM', asmasked=False)[source]

Return an ACTNUM GridProperty object.

Note that this method is similar to, but not identical to, the job with same name in Grid(). Here, the maskedarray of the values is applied to deduce the ACTNUM array.

Parameters:

name (str) – Name of property in the XTGeo GridProperty object. Default is “ACTNUM”.
asmasked (bool) – Default is False, so that actnum is returned with all cells shown. Use asmasked=True to make 0 entries masked.

Return type:

GridProperty

Returns:

The ACTNUM GridProperty object.

Example:

act = mygrid.get_actnum()
print('{}% cells are active'.format(act.values.mean() * 100))

get_npvalues1d(activeonly=False, fill_value=nan, order='C')[source]

Return the grid property as a 1D numpy array (copy) for active or all cells, but inactive have a fill value.

Parameters:

activeonly (bool) – If True, then only return active cells. Default is False.
fill_value (Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[bool | int | float | complex | str | bytes]]) – Fill value for inactive cells. Default is np.nan.
order (Literal['C', 'F']) – Array internal order. Default is “C”, alternative is “F”.

Return type:

MaskedArray

Returns:

The grid property as a 1D numpy masked array.

Added in version 2.3.

Changed in version 2.8: Added fill_value and order

get_npvalues3d(fill_value=None)[source]

Get a pure numpy copy (not masked) of the values in 3D shape.

Note that Numpy dtype will be reset; int32 if discrete or float64 if continuous. The reason for this is to avoid inconsistensies regarding UNDEF values.

If fill_value is not None, than the returning dtype is always np.float64.

Parameters:: fill_value (Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[bool | int | float | complex | str | bytes], None]) – Value of masked entries. Default is None which means the XTGeo UNDEF value (a high number). This UNDEF value is different for a continuous or discrete property.
Return type:: ndarray
Returns:: Non-masked array copy of 3D-shaped values

get_values_by_ijk(iarr, jarr, karr, base=1)[source]

Get a 1D ndarray of values by I J K arrays.

This could for instance be a well path where I J K exists as well logs.

Note that the input arrays have 1 as base as default

Parameters:

iarr (ndarray) – Numpy array of I
jarr (ndarray) – Numpy array of J
karr (ndarray) – Numpy array of K
base (int) – Should be 1 or 0, dependent on what number base the input arrays has.

Return type:

MaskedArray | None

Returns:

A 1D numpy array of property values, with NaN if undefined. Returns None on IndexErrors.

get_xy_value_lists(grid=None, activeonly=True)[source]

Get lists of xy coords and values for Webportal format.

The coordinates are on the form (two cells):

[[[(x1,y1), (x2,y2), (x3,y3), (x4,y4)],
[(x5,y5), (x6,y6), (x7,y7), (x8,y8)]]]

Parameters:

grid (Grid | None) – The XTGeo Grid object for the property. Defaults to None.
activeonly (bool) – If True (default), active cells only, otherwise cell geometries will be listed and property will have value -999 in undefined cells.

Return type:

Tuple[List[List[List[Tuple[Union[float, int], Union[float, int]]]]], List[List[Union[float, int]]]]

Returns:

A tuple of two lists, one being the xr coords, the other the values at those coords.

Example:

import xtgeo
grid = xtgeo.grid_from_file("../xtgeo-testdata/3dgrids/bri/b_grid.roff")
prop = xtgeogridproperty_from_file(
    "../xtgeo-testdata/3dgrids/bri/b_poro.roff", grid=grid, name="PORO"
)

clist, valuelist = prop.get_xy_value_lists(
    grid=grid, activeonly=False
)

property isdiscrete

Get or set whether this property is discrete.

This can also be used to convert from continuous to discrete or from discrete to continuous:

myprop.isdiscrete = False

mask_undef()[source]

Make UNDEF values masked.

Return type:: None

property metadata: Get or set metadata object instance of type MetaDataCPProperty.

classmethod methods()[source]

A list of methods in the class as a string.

Return type:: str
Returns:: The names of the methods in the class.

Example::

>>> print(GridProperty.methods())
METHODS for GridProperty():
======================
__init__
_reset
_set_initial_dimensions
_check_dimensions_match
...

mul_inside(poly, value)[source]

Multiply a value (scalar) inside polygons.

Return type:: None

mul_outside(poly, value)[source]

Multiply a value (scalar) outside polygons.

Return type:: None

property nactive: Get the number of active cells.

property name: Get or set the property name.

property ncodes: Get number of codes if discrete grid property.

property ncol: Returns the NCOL (NX or Ncolumns) number of cells.

property nlay: Returns the NLAY (NZ or Nlayers) number of cells.

property nrow: Returns the NROW (NY or Nrows) number of cells.

property ntotal: Get total number of cells (ncol * nrow * nlay).

operation_polygons(poly, value, opname='add', inside=True)[source]

A generic function for doing 3D grid property operations restricted to inside or outside polygon(s).

This method requires that the property geometry is known (prop.geometry is set to a grid instance).

Parameters:

poly (Polygons) – A XTGeo Polygons instance.
value (float | int) – Value to add, subtract etc.
opname (Literal['add', 'sub', 'mul', 'div', 'set']) – Name of operation… “add”, “sub”, etc. Defaults to “add”.
inside (bool) – If True do operation inside polygons; else outside. Defaults to True.

Return type:

None

property roxar_dtype: Get or set the roxar dtype (if any).

property roxorigin: Get boolean value of True if the property comes from ROXAPI.

set_inside(poly, value)[source]

Set a value (scalar) inside polygons.

Return type:: None

set_outside(poly, value)[source]

Set a value (scalar) outside polygons.

Return type:: None

sub_inside(poly, value)[source]

Subtract a value (scalar) inside polygons.

Return type:: None

sub_outside(poly, value)[source]

Subtract a value (scalar) outside polygons.

Return type:: None

to_file(pfile, fformat='roff', name=None, append=False, dtype=None, fmt=None)[source]

Export the grid property to file.

Parameters:

pfile (Union[str, Path, StringIO, BytesIO]) – File name or pathlib.Path to export to.
fformat (Literal['roff', 'roffasc', 'grdecl', 'bgrdecl', 'xtgcpprop']) – The file format to be used. Default is roff binary, else roff_ascii/grdecl/bgrdecl.
name (str | None) – If provided, will explicitly give property name; else the existing name of the instance will used.
append (bool) – Append to existing file, only for (b)grdecl formats.
dtype (type[float32] | type[float64] | type[int32] | None) – The values data type. This is valid only for grdecl or bgrdecl formats, where the default is None which means ‘float32’ for floating point numbers and ‘int32’ for discrete properties. Other choices are ‘float64’ which are ‘DOUB’ entries in Eclipse formats.
fmt (str | None) – Format for ascii grdecl format. Default is None. If specified, the user is responsible for a valid format specifier, e.g. “%8.4f”.

Return type:

None

Example:

# This example demonstrates that file formats can be mixed
import xtgeo
rgrid = xtgeo.grid_from_file("reek.roff")
poro = GridProperty("reek_poro.grdecl", grid=rgrid, name='PORO')

poro.values += 0.05

poro.to_file("reek_export_poro.bgrdecl", format="bgrdecl")

Added in version 2.13: Key fmt was added and default format for float output to grdecl is now “%e” if fmt=None

to_roxar(projectname, gridname, propertyname, realisation=0, casting='unsafe')[source]

Store a grid model property into a RMS project.

Note

When project is file path (direct access, outside RMS) then to_roxar() will implicitly do a project save. Otherwise, the project will not be saved until the user do an explicit project save action.

Note

Beware values casting, see casting key. Default is “unsafe” which may create issues if your property has values that is outside the valid range. I.e. for float values XTGeo normally use float64 (8 byte) while roxar use float32 (4 byte). With extreme values, e.g. 10e40, such values will be truncated if “unsafe” casting. More common is casting issues with discrete as Roxar (RMS) often use uint8 which only allow values in range 1..256.

Parameters:

projectname (str) – Inside RMS use the magic ‘project’ string. Otherwise use a path to an RMS project, or a project reference.
gridname (str) – Name of grid model.
propertyname (str) – Name of grid property.
realisation (int) – Realisation number. Default is 0 (the first).
casting (Optional[Literal['no', 'equiv', 'safe', 'same_kind', 'unsafe']]) – This refers to numpy astype(… casting=…) settings.

Return type:

None

Changed in version 2.10: Key saveproject has been removed and will have no effect

Added in version 2.12: Key casting was added

property undef: Get the actual undef value for floats or ints in numpy arrays.

property undef_limit

Get the undef limit number, which is slightly less than the undef value.

Hence for numerical precision, one can force undef values to a given number, e.g.:

x[x<x.undef_limit] = 999

Undef limit values cannot be changed (read only).

property values: Get or set the grid property as a masked 3D numpy array.

property values1d: Get a masked 1D array view of values.

Grid properties (multiple)

Classes

class xtgeo.GridProperties(props=None)[source]

Bases: _Grid3D

Class for a collection of 3D grid props, belonging to the same grid topology.

It is a thin wrapper on a list that 1) checks that the GridProperties belong to the same Grid (loosely). 2) Contains operations that can be called on lists of GridProperty objects for easy discoverability.
Examples::
>>> import xtgeo
>>> # Create an
>>> grid_properties = xtgeo.GridProperties(props=[])
>>> # Get the dataframe via the gridproperties object
>>> grid_properties.get_dataframe()
Empty DataFrame...
>>> # Convert the gridproperties to a list
>>> grid_properties_list = list(grid_properties)
>>> # Get the dataframe of the list:
>>> gridproperties_dataframe(grid_properties_list)
Empty DataFrame...

Parameters:: props (list[GridProperty] | None) – The list of GridProperty objects.

See also

The GridProperty class.

Public Data Attributes:

`names`	Returns a list of property names.
`props`	Returns a list of XTGeo GridProperty objects, None if empty.
`dates`	Returns a list of valid (found) dates after import.

Inherited from _Grid3D

`ncol`	Returns the NCOL (NX or Ncolumns) number of cells.
`nrow`	Returns the NROW (NY or Nrows) number of cells.
`nlay`	Returns the NLAY (NZ or Nlayers) number of cells.

Public Methods:

`copy`()	Copy a GridProperties instance to a new unique instance.
`describe`([flush])	Describe an instance by printing to stdout.
`generate_hash`()	str: Return a unique hash ID for current gridproperties instance.
`get_prop_by_name`(name[, raiseserror])	Find and return a property object (GridProperty) by name.
`append_props`(proplist)	Add a list of GridProperty objects to current GridProperties instance.
`get_ijk`([names, zerobased, asmasked])	Returns 3 xtgeo.grid3d.GridProperty objects: I counter, J counter, K counter.
`get_actnum`([name, asmasked])	Return an ACTNUM GridProperty object.
`get_dataframe`([activeonly, ijk, xyz, ...])	Returns a Pandas dataframe table for the properties.
`scan_dates`(pfile[, fformat, maxdates, ...])	Quick scan dates in a simulation restart file.

__init__(props=None)[source]

append_props(proplist)[source]

Add a list of GridProperty objects to current GridProperties instance.

Return type:: None

copy()[source]

Copy a GridProperties instance to a new unique instance.

Note that the GridProperty instances will also be unique.

Return type:: GridProperties

property dates

Returns a list of valid (found) dates after import.

Returns None if no dates present

Note

See also GridProperties.scan_dates() for scanning available dates in advance

Example:

>>> import xtgeo
>>> grid = xtgeo.grid_from_file(reek_dir + "/REEK.EGRID")
>>> props = xtgeo.gridproperties_from_file(
...     reek_dir + "/REEK.INIT",
...     fformat="init",
...     names=["PERMX"],
...     grid=grid,
... )

>>> datelist = props.dates
>>> for date in datelist:
...     print ('Date applied is {}'.format(date))
Date applied is 19991201

Changed in version 2.16: dates is no longer an alias (undocumented behavior), and simply return the dates of the underlying list of GridProperty.

describe(flush=True)[source]

Describe an instance by printing to stdout.

Return type:: str | None

generate_hash()[source]: str: Return a unique hash ID for current gridproperties instance. :rtype: str

Added in version 2.10.

get_actnum(name='ACTNUM', asmasked=False)[source]

Return an ACTNUM GridProperty object.

Parameters:

name (str) – name of property in the XTGeo GridProperty object.
asmasked (bool) – ACTNUM is returned with all cells as default. Use asmasked=True to make 0 entries masked.

Example:

>>> import xtgeo
>>> grid = xtgeo.grid_from_file(reek_dir + "/REEK.EGRID")
>>> myprops = xtgeo.gridproperties_from_file(
...     reek_dir + "/REEK.INIT",
...     fformat="init",
...     names=["PERMX"],
...     grid=grid,
... )
>>> act = myprops.get_actnum()
>>> print('{}% of cells are active'.format(act.values.mean() * 100))
99.99...% of cells are active

Return type:: GridProperty | None
Returns:: A GridProperty instance of ACTNUM, or None if no props present.

get_dataframe(activeonly=False, ijk=False, xyz=False, doubleformat=False, grid=None)[source]

Returns a Pandas dataframe table for the properties.

See also xtgeo.gridproperties_dataframe()

Parameters:

activeonly (bool) – If True, return only active cells, NB! If True, will require a grid instance (see grid key)
ijk (bool) – If True, show cell indices, IX JY KZ columns
xyz (bool) – If True, show cell center coordinates (needs grid).
doubleformat (bool) – If True, floats are 64 bit, otherwise 32 bit. Note that coordinates (if xyz=True) is always 64 bit floats.
grid (Grid) – The grid geometry object. This is required for the xyz option.

Return type:

DataFrame

Returns:

Pandas dataframe object

Examples:

>>> import xtgeo
>>> grid = xtgeo.grid_from_file(reek_dir + "/REEK.EGRID")
>>> pps = xtgeo.gridproperties_from_file(
...     reek_dir + "/REEK.UNRST",
...     fformat="unrst",
...     names=['SOIL', 'SWAT', 'PRESSURE'],
...     dates=[19991201],
...     grid=grid,
... )
>>> df = pps.get_dataframe(activeonly=False, ijk=True, xyz=True, grid=grid)
>>> print(df)
       ACTNUM  IX  JY  ...  SOIL_19991201  SWAT_19991201  PRESSURE_19991201
0           1   1   1  ...            0.0            1.0         341.694183
1           1   1   1  ...            0.0            1.0         342.097107
2           1   1   1  ...            0.0            1.0         342.500061
3           1   1   1  ...            0.0            1.0         342.902954
4           1   1   1  ...            0.0            1.0         343.305908
...

get_ijk(names=('IX', 'JY', 'KZ'), zerobased=False, asmasked=False)[source]

Returns 3 xtgeo.grid3d.GridProperty objects: I counter, J counter, K counter.

Parameters:

names (tuple[str, str, str]) – a 3 x tuple of names per property (default IX, JY, KZ).
asmasked (bool) – If True, then active cells only.
zerobased (bool) – If True, counter start from 0, otherwise 1 (default=1).

Return type:

tuple[GridProperty, GridProperty, GridProperty]

get_prop_by_name(name, raiseserror=True)[source]

Find and return a property object (GridProperty) by name.

Parameters:

name (str) – Name of property to look for
raiseserror (bool) – If True, raises a ValueError if not found, otherwise return None

Return type:

GridProperty | None

property names

Returns a list of property names.

Example:

>>> import xtgeo
>>> grid = xtgeo.grid_from_file(reek_dir + "/REEK.EGRID")
>>> props = xtgeo.gridproperties_from_file(
...     reek_dir + "/REEK.INIT",
...     fformat="init",
...     names=["PERMX"],
...     grid=grid,
... )

>>> namelist = props.names
>>> for name in namelist:
...     print ('Property name is {}'.format(name))
Property name is PERMX

property ncol: Returns the NCOL (NX or Ncolumns) number of cells.

property nlay: Returns the NLAY (NZ or Nlayers) number of cells.

property nrow: Returns the NROW (NY or Nrows) number of cells.

property props

Returns a list of XTGeo GridProperty objects, None if empty.

Example:

>>> import xtgeo
>>> grid = xtgeo.grid_from_file(reek_dir + "/REEK.EGRID")
>>> myprops = xtgeo.gridproperties_from_file(
...     reek_dir + "/REEK.INIT",
...     fformat="init",
...     names=["PERMX"],
...     grid=grid,
... )

>>> proplist = myprops.props
>>> for prop in proplist:
...     print ('Property object name is {}'.format(prop.name))
Property object name is PERMX

>>> # adding a property, e.g. get ACTNUM as a property from the grid
>>> actn = grid.get_actnum()  # this will get actn as a GridProperty
>>> myprops.append_props([actn])

static scan_dates(pfile, fformat='unrst', maxdates=1000, dataframe=False, datesonly=False)[source]

Quick scan dates in a simulation restart file.

Parameters:

pfile (str) – Name of file or file handle with properties
fformat (str) – unrst (so far)
maxdates (int) – Maximum number of dates to collect
dataframe (bool) – If True, return a Pandas dataframe instead
datesonly (bool) – If True, SEQNUM is skipped,

Return type:

list | DataFrame

Returns:

A list of tuples or a dataframe with (seqno, date), date is on YYYYMMDD form. If datesonly is True and dataframe is False, the returning list will be a simple list of dates.

Example::

>>> dlist = GridProperties.scan_dates(reek_dir + "/REEK.UNRST")
>>> #or getting all dates a simple list:
>>> dlist = GridProperties.scan_dates(
... reek_dir + "/REEK.UNRST",
... datesonly=True)

Changed in version 2.13: Added datesonly keyword

Other

Roxar utilities

RoxUtils

class xtgeo.RoxUtils(project, readonly=False)[source]

Bases: object

Class RoxUtils, for accessing project level methods:

import xtgeo

xr = xtgeo.RoxUtils(project)
xr.create_horizon_category('DS_extracted_run3')
xr.delete_horizon_category('DS_extracted_run2')

The project itself can be a reference to an existing project, typically the magic project wording inside RMS python, or a file path to a RMS project (for external access).

Parameters:

project (roxar.Project or str) – Reference to a RMS project either an existing instance or a RMS project folder path.
readonly (bool) – saved to this project (which is the case for “secondary” projects).

Examples:

import xgeo
path = '/some/path/to/rmsprject.rmsx'

ext = xtgeo.RoxUtils(path, readonly=True)
# ...do something
ext.safe_close()

Public Data Attributes:

`roxversion`	Roxar API version (read only)
`project`	The Roxar project instance (read only)

Public Methods:

`safe_close`()	Close the project but only if roxarapps (external) mode, i.e. not current RMS project.
`version_required`(targetversion)	Defines a minimum ROXAPI version for some feature (True or False).
`rmsversion`(apiversion)	Get the actual RMS version(s) given an API version.
`create_horizons_category`(category[, domain, ...])	Create one or more a Horizons category entries.
`create_zones_category`(category[, domain, htype])	Create one or more a Horizons category entries.
`delete_horizons_category`(category)	Delete on or more horizons or zones categories
`delete_zones_category`(category)	Delete on or more horizons or zones categories.
`clear_horizon_category`(category)	Clear (or make empty) the content of one or more horizon categories.
`clear_zone_category`(category)	Clear (or make empty) the content of one or more zone categories.

__init__(project, readonly=False)[source]

clear_horizon_category(category)[source]

Clear (or make empty) the content of one or more horizon categories.

Parameters:: category (str or list) – Name(s) of category to empty, either as a simple string or a list of strings.

Added in version 2.1.

clear_zone_category(category)[source]

Clear (or make empty) the content of one or more zone categories.

Parameters:: category (str or list) – Name(s) of category to empty, either as a simple string or a list of strings.

Added in version 2.1.

create_horizons_category(category, domain='depth', htype='surface')[source]

Create one or more a Horizons category entries.

Parameters:

category (str or list) – Name(s) of category to make, either as a simple string or a list of strings.
domain (str) – ‘depth’ (default) or ‘time’
htype (str) – Horizon type: surface/lines/points

create_zones_category(category, domain='thickness', htype='surface')[source]

Create one or more a Horizons category entries.

Parameters:

category (str or list) – Name(s) of category to make, either as a simple string or a list of strings.
domain (str) – ‘thickness’ (default) or …?
htype (str) – Horizon type: surface/lines/points

delete_horizons_category(category)[source]: Delete on or more horizons or zones categories

delete_zones_category(category)[source]: Delete on or more horizons or zones categories. See previous

property project: The Roxar project instance (read only)

rmsversion(apiversion)[source]

Get the actual RMS version(s) given an API version.

Parameters:

apiversion (str) – ROXAPI version to ask for

Returns:

A list of RMS version(s) for the given API version, None if: not any match.

Example:

rox = RoxUtils(project)
rmsver = rox.rmsversion('1.5')
print('The supported RMS version are {}'.format(rmsver))

property roxversion: Roxar API version (read only)

safe_close()[source]

Close the project but only if roxarapps (external) mode, i.e. not current RMS project

In case roxar.Project.open() is done explicitly, safe_close() will do nothing.

version_required(targetversion)[source]

Defines a minimum ROXAPI version for some feature (True or False).

Parameters:: targetversion (str) – Minimum version to compare with.

Example:

rox = RoxUtils(project)
if rox.version_required('1.5'):
    somefunction()
else:
    print('Not supported in this version')

Metadata (experimental)

MetadataRegularSurface

class xtgeo.MetaDataRegularSurface[source]

Bases: MetaData

Metadata for RegularSurface() objects.

Docstring.

Public Data Attributes:

`REQUIRED`
`required`	Get of set required metadata.

Inherited from MetaData

`optional`	Return or set optional metadata.
`opt`	Return the metadata optional instance.
`freeform`	Get or set the current freeform metadata dictionary.

Public Methods:

Inherited from MetaData

`get_metadata`()	Get all metadata that are present.
`generate_fmu_name`()	Generate FMU name on form xxxx--yyyy--date but no suffix.

REQUIRED = {'ncol': 1, 'nrow': 1, 'rotation': 0.0, 'undef': 1e+33, 'xinc': 1.0, 'xori': 0.0, 'yflip': 1, 'yinc': 1.0, 'yori': 0.0}

__init__()[source]: Docstring.

property freeform: Get or set the current freeform metadata dictionary.

generate_fmu_name(): Generate FMU name on form xxxx–yyyy–date but no suffix.

get_metadata(): Get all metadata that are present.

property opt

Return the metadata optional instance.

This makes access to the _OptionalMetaData instance.

Example::

>>> import xtgeo
>>> surf = xtgeo.surface_from_file(surface_dir + "/topreek_rota.gri")
>>> surf.metadata.opt.shortname = "TopValysar"

property optional

Return or set optional metadata.

When setting optional names, it can be done in several ways…

surf.metadata.optional.name = “New name”

property required: Get of set required metadata.

MetaDataRegularCube

class xtgeo.MetaDataRegularCube[source]

Bases: MetaData

Metadata for Cube() objects.

Docstring.

Public Data Attributes:

`REQUIRED`
`required`	Get of set required metadata.

Inherited from MetaData

`optional`	Return or set optional metadata.
`opt`	Return the metadata optional instance.
`freeform`	Get or set the current freeform metadata dictionary.

Public Methods:

Inherited from MetaData

`get_metadata`()	Get all metadata that are present.
`generate_fmu_name`()	Generate FMU name on form xxxx--yyyy--date but no suffix.

REQUIRED = {'ncol': 1, 'nlay': 1, 'nrow': 1, 'rotation': 0.0, 'undef': 1e+33, 'xinc': 1.0, 'xori': 0.0, 'yflip': 1, 'yinc': 1.0, 'yori': 0.0, 'zflip': 1, 'zinc': 1.0, 'zori': 0.0}

__init__()[source]: Docstring.

property freeform: Get or set the current freeform metadata dictionary.

generate_fmu_name(): Generate FMU name on form xxxx–yyyy–date but no suffix.

get_metadata(): Get all metadata that are present.

property opt

Return the metadata optional instance.

This makes access to the _OptionalMetaData instance.

Example::

>>> import xtgeo
>>> surf = xtgeo.surface_from_file(surface_dir + "/topreek_rota.gri")
>>> surf.metadata.opt.shortname = "TopValysar"

property optional

Return or set optional metadata.

When setting optional names, it can be done in several ways…

surf.metadata.optional.name = “New name”

property required: Get of set required metadata.

MetaDataCPGeometry

class xtgeo.MetaDataCPGeometry[source]

Bases: MetaData

Metadata for Grid() objects of type simplified CornerPoint Geometry.

Docstring.

Public Data Attributes:

`REQUIRED`
`required`	Get of set required metadata.

Inherited from MetaData

`optional`	Return or set optional metadata.
`opt`	Return the metadata optional instance.
`freeform`	Get or set the current freeform metadata dictionary.

Public Methods:

Inherited from MetaData

`get_metadata`()	Get all metadata that are present.
`generate_fmu_name`()	Generate FMU name on form xxxx--yyyy--date but no suffix.

REQUIRED = {'ncol': 1, 'nlay': 1, 'nrow': 1, 'xscale': 1.0, 'xshift': 0.0, 'yscale': 1.0, 'yshift': 0.0, 'zscale': 1.0, 'zshift': 0.0}

__init__()[source]: Docstring.

property freeform: Get or set the current freeform metadata dictionary.

generate_fmu_name(): Generate FMU name on form xxxx–yyyy–date but no suffix.

get_metadata(): Get all metadata that are present.

property opt

Return the metadata optional instance.

This makes access to the _OptionalMetaData instance.

Example::

>>> import xtgeo
>>> surf = xtgeo.surface_from_file(surface_dir + "/topreek_rota.gri")
>>> surf.metadata.opt.shortname = "TopValysar"

property optional

Return or set optional metadata.

When setting optional names, it can be done in several ways…

surf.metadata.optional.name = “New name”

property required: Get of set required metadata.

MetaDataCPProperty

class xtgeo.MetaDataCPProperty[source]

Bases: MetaData

Metadata for GridProperty() objects belonging to CPGeometry.

Docstring.

Public Data Attributes:

`REQUIRED`
`required`	Get of set required metadata.

Inherited from MetaData

`optional`	Return or set optional metadata.
`opt`	Return the metadata optional instance.
`freeform`	Get or set the current freeform metadata dictionary.

Public Methods:

Inherited from MetaData

`get_metadata`()	Get all metadata that are present.
`generate_fmu_name`()	Generate FMU name on form xxxx--yyyy--date but no suffix.

REQUIRED = {'codes': None, 'discrete': False, 'ncol': 1, 'nlay': 1, 'nrow': 1}

__init__()[source]: Docstring.

property freeform: Get or set the current freeform metadata dictionary.

generate_fmu_name(): Generate FMU name on form xxxx–yyyy–date but no suffix.

get_metadata(): Get all metadata that are present.

property opt

Return the metadata optional instance.

This makes access to the _OptionalMetaData instance.

Example::

>>> import xtgeo
>>> surf = xtgeo.surface_from_file(surface_dir + "/topreek_rota.gri")
>>> surf.metadata.opt.shortname = "TopValysar"

property optional

Return or set optional metadata.

When setting optional names, it can be done in several ways…

surf.metadata.optional.name = “New name”

property required: Get of set required metadata.

MetaDataWell

class xtgeo.MetaDataWell[source]

Bases: MetaData

Metadata for single Well() objects.

Initialisation for Well metadata.

Public Data Attributes:

`REQUIRED`
`required`	Get of set required metadata.

Inherited from MetaData

`optional`	Return or set optional metadata.
`opt`	Return the metadata optional instance.
`freeform`	Get or set the current freeform metadata dictionary.

Public Methods:

Inherited from MetaData

`get_metadata`()	Get all metadata that are present.
`generate_fmu_name`()	Generate FMU name on form xxxx--yyyy--date but no suffix.

REQUIRED = {'mdlogname': None, 'name': 'noname', 'rkb': 0.0, 'wlogs': {}, 'xpos': 0.0, 'ypos': 0.0, 'zonelogname': None}

__init__()[source]: Initialisation for Well metadata.

property freeform: Get or set the current freeform metadata dictionary.

generate_fmu_name(): Generate FMU name on form xxxx–yyyy–date but no suffix.

get_metadata(): Get all metadata that are present.

property opt

Return the metadata optional instance.

This makes access to the _OptionalMetaData instance.

Example::

>>> import xtgeo
>>> surf = xtgeo.surface_from_file(surface_dir + "/topreek_rota.gri")
>>> surf.metadata.opt.shortname = "TopValysar"

property optional

Return or set optional metadata.

When setting optional names, it can be done in several ways…

surf.metadata.optional.name = “New name”

property required: Get of set required metadata.