resqpy.grid.RegularGrid

class resqpy.grid.RegularGrid(parent_model, uuid=None, extent_kji=None, dxyz=None, dxyz_dkji=None, origin=(0.0, 0.0, 0.0), crs_uuid=None, use_vertical=False, mesh=None, mesh_dz_dk=1.0, set_points_cached=False, as_irregular_grid=False, find_properties=True, title=None, originator=None, extra_metadata={})

Bases: Grid

Class for completely regular block grids, usually aligned with xyz axes.

Public Data Attributes:

Inherited from Grid

resqml_type
nk_plus_k_gaps	Returns the number of layers including any K gaps.

Inherited from BaseResqpy

resqml_type
part	Standard part name corresponding to self.uuid.
root	XML node corresponding to self.uuid.
citation_title	Citation block title equivalent to self.title.

Commonly Used Methods:

__init__(parent_model[, uuid, extent_kji, ...])	Creates a regular grid object based on dxyz, or derived from a Mesh object.
corner_points([cell_kji0, points_root, ...])	Returns a numpy array of corner points for a single cell or the whole grid.
xyz_box([points_root, lazy, local])	Returns the minimum and maximum xyz for the grid geometry.
create_xml([ext_uuid, add_as_part, ...])	Creates xml for this RegularGrid object; by default the explicit geometry is not included.

Inherited from Grid

__init__(parent_model[, uuid, extent_kji, ...])	Creates a regular grid object based on dxyz, or derived from a Mesh object.
cache_all_geometry_arrays()	Loads from hdf5 into memory all the arrays defining the grid geometry.
write_hdf5([expand_const_arrays, ...])	Writes grid geometry arrays to hdf5; a thin wrapper around write_hdf5_from_caches().
xy_units()	Returns the projected view (x, y) units of measure of the coordinate reference system for the grid.
z_units()	Returns the vertical (z) units of measure of the coordinate reference system for the grid.
create_xml([ext_uuid, add_as_part, ...])	Creates xml for this RegularGrid object; by default the explicit geometry is not included.
points_ref([masked])	Returns an in-memory numpy array containing the xyz data for points used in the grid geometry.
corner_points([cell_kji0, points_root, ...])	Returns a numpy array of corner points for a single cell or the whole grid.
centre_point([cell_kji0, ...])	Returns centre point of a cell or array of centre points of all cells.
create_column_pillar_mapping()	Creates an array attribute holding set of 4 pillar indices for each I, J column of cells.
pinched_out([cell_kji0])	Returns pinched out boolean (always False) for a single cell or full array.
volume([cell_kji0, required_uom])	Returns bulk rock volume of cell or numpy array of bulk rock volumes for all cells.
thickness([cell_kji0])	Returns cell thickness (K axial length) for a single cell or full array.
z_inc_down()	Return True if z increases downwards in the coordinate reference system used by the grid geometry
xyz_box([points_root, lazy, local])	Returns the minimum and maximum xyz for the grid geometry.

Methods:

cell_geometry_is_defined([cell_kji0, ...])	Override of Grid method indicating whether a cell has defined geometry, here always True.
pillar_geometry_is_defined([pillar_ji0, ...])	Override of Grid method indicating whether a pillar has defined geometry, here always True.
make_regular_points_cached([apply_origin_offset])	Set up the cached points array as an explicit representation of the regular grid geometry.
axial_lengths_kji()	Returns a triple float being lengths of primary axes (K, J, I) for each cell.
point_raw([index, points_root, cache_array])	Returns element from points data, indexed as corner point (k0, j0, i0).
half_cell_transmissibility([use_property, ...])	Returns (and caches if realization is None) half cell transmissibilities for this regular grid.
centre_point([cell_kji0, ...])	Returns centre point of a cell or array of centre points of all cells.
aligned_column_centres()	For an aligned grid, returns an array of column centres in xy, of shape (nj, ni, 2).
volume([cell_kji0, required_uom])	Returns bulk rock volume of cell or numpy array of bulk rock volumes for all cells.
thickness([cell_kji0])	Returns cell thickness (K axial length) for a single cell or full array.
pinched_out([cell_kji0])	Returns pinched out boolean (always False) for a single cell or full array.
actual_pillar_shape([patch_metadata, tolerance])	Returns actual shape of pillars.
find_cell_for_point_xy(x, y[, k0, ...])	Searches in 2D for a cell containing point x,y in layer k0; return (j0, i0) or (None, None).
aligned_dxyz()	Returns triple float dx, dy, dz cell dimensions for aligned grids only.
slice_points([axis, ref_slice, local])	Returns a slice of points data for a layer or a cross section.

Inherited from Grid

set_modified([update_xml, update_hdf5])	Assigns a new uuid to this grid; also calls set_modified() for parent model.
cell_count([active_only, ...])	Returns number of cells in grid; optionally limited by active, non-pinched-out, or having geometry.
natural_cell_index(cell_kji0)	Returns a single integer for the cell, being the index into a flattened array.
natural_cell_indices(cell_kji0s)	Returns a numpy integer array with a value for each of the cells, being the index into a flattened array.
denaturalized_cell_index(c0)	Returns a 3 element cell_kji0 index (as a tuple) for the cell with given natural index.
denaturalized_cell_indices(c0s)	Returns an integer array holding kji0 indices for the cells with given natural indices.
resolve_geometry_child(tag[, child_node])	If xml child node is None, looks for tag amongst children of geometry root.
set_parent(parent_grid_uuid, ...)	Set relationship with respect to a parent grid.
actual_pillar_shape([patch_metadata, tolerance])	Returns actual shape of pillars.
column_is_inactive(col_ji0)	Returns True if all the cells in the specified column are inactive.
write_hdf5_from_caches([file, mode, ...])	Writes hdf5 datasets for the grid geometry (and parent grid mapping) and optionally properties, from cached arrays.
off_handed()	Returns False if IJK and xyz have same handedness, True if they differ.
write_nexus_corp(file_name[, local_coords, ...])	Write grid geometry to file in Nexus CORP ordering.
skin([use_single_layer_tactics, is_regular])	Returns a GridSkin composite surface object reoresenting the outer surface of the grid.
x_section_points(axis[, ref_slice0, ...])	Deprecated: please use unsplit_x_section_points instead.
cell_geometry_is_defined([cell_kji0, ...])	Override of Grid method indicating whether a cell has defined geometry, here always True.
pillar_geometry_is_defined([pillar_ji0, ...])	Override of Grid method indicating whether a pillar has defined geometry, here always True.
geometry_defined_for_all_cells([cache_array])	Returns True if geometry is defined for all cells; False otherwise.
geometry_defined_for_all_pillars([...])	Returns True if geometry is defined for all pillars; False otherwise.
cell_geometry_is_defined_ref()	Returns an in-memory numpy array containing the boolean data indicating which cells have geometry defined.
pillar_geometry_is_defined_ref()	Returns an in-memory numpy array containing the boolean data indicating which pillars have geometry defined.
set_geometry_is_defined([treat_as_nan, ...])	Set cached flags and/or arrays indicating which primary pillars have any points defined and which cells all points.
find_faults([set_face_sets, ...])	Searches for column-faces that are faulted and assigns fault ids; creates list of column-faces per fault id.
fault_throws()	Finds mean throw of each J and I face; adds throw arrays as attributes to this grid and returns them.
fault_throws_per_edge_per_column([mode, ...])	Return array holding max, mean or min throw based on split node separations.
extract_parent()	Returns the uuid of the parent grid for the supplied grid
transmissibility([tolerance, ...])	Returns transmissibilities for standard (IJK neighbouring) connections within this grid.
extract_extent_kji()	Returns the grid extent; for IJK grids this is a 3 integer numpy array, order is Nk, Nj, Ni.
extract_grid_is_right_handed()	Returns boolean indicating whether grid IJK axes are right handed, as stored in xml.
extract_k_direction_is_down()	Returns boolean indicating whether increasing K indices are generally for deeper cells, as stored in xml.
extract_geometry_time_index()	Returns integer time index, or None, for the grid geometry, as stored in xml for dynamic geometries.
extract_crs_uuid()	Returns uuid for coordinate reference system, as stored in geometry xml tree.
set_crs([crs_uuid])	Establish crs attribute if not already set
get_represented_interpretation()	Establishes the represented interpretation uuid, as stored in the xml tree, if present
extract_pillar_shape()	Returns string indicating whether whether pillars are curved, straight, or vertical as stored in xml.
extract_has_split_coordinate_lines()	Returns boolean indicating whether grid geometry has any split coordinate lines (split pillars, ie.
extract_k_gaps()	Returns information about gaps (voids) between layers in the grid.
extract_stratigraphy()	Loads stratigraphic information from xml.
extract_children()	Looks for LGRs related to this grid and sets the local_grid_uuid_list attribute.
extract_property_collection()	Load grid property collection object holding lists of all properties in model that relate to this grid.
extract_inactive_mask([check_pinchout])	Returns boolean numpy array indicating which cells are inactive, if (in)active property found in this grid.
is_split_column_face(j0, i0, axis, polarity)	Returns True if the I or J column face is split; False otherwise.
split_column_faces()	Returns a pair of numpy boolean arrays indicating which internal column faces (column edges) are split.
clear_face_sets()	Discard face sets.
set_face_set_gcs_list_from_dict([...])	Creates a grid connection set for each feature in the face set dictionary, based on kelp list pairs.
make_face_set_from_dataframe(df)	Creates a curtain face set for each named fault in dataframe.
make_face_sets_from_pillar_lists(...[, ...])	Creates a curtain face set for each pillar (or rod) list.
face_centre(cell_kji0, axis, zero_or_one[, ...])	Returns xyz location of the centre point of a face of the cell (or all cells).
face_centres_kji_01(cell_kji0[, ...])	Returns an array of shape (3, 2, 3) being (axis, 0 or 1, xyz) of face centre points for cell.
set_cached_points_from_property([...])	Modifies the cached points (geometry), setting the values from a points property.
point_raw([index, points_root, cache_array])	Returns element from points data, indexed as corner point (k0, j0, i0).
point([cell_kji0, corner_index, ...])	Return a cell corner point xyz; can optionally be used to cache points data.
uncache_points()	Frees up memory by removing the cached copy of the grid's points data.
unsplit_points_ref([cache_array, masked])	Returns a copy of the points array that has split pillars merged back into an unsplit configuration.
horizon_points([ref_k0, heal_faults, kp])	Returns reference to a points layer array of shape ((nj + 1), (ni + 1), 3) based on primary pillars.
split_horizon_points([ref_k0, masked, kp])	Returns reference to a corner points for a horizon, of shape (nj, ni, 2, 2, 3).
split_x_section_points(axis[, ref_slice0, ...])	Returns an array of points representing cell corners from an I or J interface slice for a faulted grid.
split_gap_x_section_points(axis[, ...])	Return array of points representing cell corners from an I or J interface slice for a faulted grid.
unsplit_x_section_points(axis[, ref_slice0, ...])	Returns a 2D (+1 for xyz) array of points representing cell corners from an I or J interface slice.
x_section_corner_points(axis[, ref_slice0, ...])	Returns a fully expanded array of points representing cell corners from an I or J interface slice.
pixel_map_for_split_horizon_points(...[, dy])	Makes a mapping from pixels to cell j, i indices, based on split horizon points for a single horizon.
coordinate_line_end_points()	Returns xyz of top and bottom of each primary pillar.
z_corner_point_depths([order])	Returns the z (depth) values of each corner of each cell.
invalidate_corner_points()	Deletes cached copy of corner points, if present.
centre_point_list(cell_kji0s)	Returns centre points for a list of cells; caches centre points for all cells.
point_areally([tolerance])	Returns array indicating which cells are reduced to a point in both I & J axes.
interpolated_point(cell_kji0, ...[, ...])	Returns xyz point interpolated from corners of cell.
interpolated_points(cell_kji0, ...[, ...])	Returns xyz points interpolated from corners of cell.
set_k_direction_from_points()	Sets the K direction indicator based on z direction and mean z values for top and base.
find_cell_for_point_xy(x, y[, k0, ...])	Searches in 2D for a cell containing point x,y in layer k0; return (j0, i0) or (None, None).
half_cell_transmissibility([use_property, ...])	Returns (and caches if realization is None) half cell transmissibilities for this regular grid.
pillar_foursome(ji0[, none_if_unsplit])	Returns an int array of the natural pillar indices applicable to each column around primary.
pillar_distances_sqr(xy[, ref_k0, kp, ...])	Returns array of the square of the distances of primary pillars in x,y plane to point xy.
nearest_pillar(xy[, ref_k0, kp])	Returns the (j0, i0) indices of the primary pillar with point closest in x,y plane to point xy.
nearest_rod(xyz, projection, axis[, ...])	Returns the (k0, j0) or (k0 ,i0) indices of the closest point(s) to xyz(s); projection is 'xy', 'xz' or 'yz'.
poly_line_for_cell(cell_kji0[, vertical_ref])	Returns a numpy array of shape (4, 3) being the 4 corners.
interface_lengths_kji(cell_kji0[, ...])	Returns 3 interface centre point separation lengths for axes k, j, i.
interface_vectors_kji(cell_kji0[, ...])	Returns 3 interface centre point difference vectors for axes k, j, i.
interface_length(cell_kji0, axis[, ...])	Returns the length between centres of an opposite pair of faces of the cell.
interface_vector(cell_kji0, axis[, ...])	Returns an xyz vector between centres of an opposite pair of faces of the cell (or vectors for all cells).
cell_inactive(cell_kji0[, pv_array, pv_tol])	Returns True if the cell is inactive.
get_volume_uom(required_uom)	Returns a RESQML unit of measure string to use for volume quantities for the grid.
get_volume_conversion_factor(required_uom)	Returns a factor for converting volumes calculated in the grid's CRS to the required uom.
fault_connection_set([skip_inactive, ...])	Returns (and caches) a GridConnectionSet representing juxtaposition across faces with split pillars.
pinchout_connection_set([skip_inactive, ...])	Returns (and caches) a GridConnectionSet representing juxtaposition across pinched out cells.
k_gap_connection_set([skip_inactive, ...])	Returns (and caches) a GridConnectionSet representing juxtaposition across zero thickness K gaps.
check_top_and_base_cell_edge_directions()	Check grid top face I & J edge vectors (in x,y) against basal equivalents.
global_to_local_crs(a, crs_uuid[, ...])	Converts array of points in situ from global coordinate system to established local one.
local_to_global_crs(a, crs_uuid[, ...])	Converts array of points in situ from local coordinate system to global one.
composite_bounding_box(bounding_box_list)	Returns the xyz box which envelopes all the boxes in the list, as a numpy array of shape (2, 3).
bounding_box(cell_kji0[, points_root, ...])	Returns the xyz box which envelopes the specified cell, as a numpy array of shape (2, 3).
xyz_box_centre([points_root, lazy, local])	Returns the (x,y,z) point (as 3 element numpy) at the centre of the xyz box for the grid.
pixel_maps(origin, width, height, dx[, dy, ...])	Makes a mapping from pixels to cell j, i indices, based on split horizon points for a single horizon.
split_horizons_points([min_k0, max_k0, masked])	Returns reference to a corner points layer of shape (nh, nj, ni, 2, 2, 3) where nh is number of horizons.
combined_tr_mult_properties_from_gcs_mults([...])	Add triplet of transmissibility multiplier properties by combining gcs properties.

Inherited from BaseResqpy

__init__(parent_model[, uuid, extent_kji, ...])	Creates a regular grid object based on dxyz, or derived from a Mesh object.
try_reuse()	Look for an equivalent existing RESQML object and modify the uuid of this object if found.
create_xml([ext_uuid, add_as_part, ...])	Creates xml for this RegularGrid object; by default the explicit geometry is not included.
append_extra_metadata(meta_dict)	Append a given dictionary of metadata to the existing metadata.
__eq__(other)	Implements equals operator; uses is_equivalent() otherwise compares class type and uuid.
__ne__(other)	Implements not equal operator.
__repr__()	String representation.

---

__init__(parent_model, uuid=None, extent_kji=None, dxyz=None, dxyz_dkji=None, origin=(0.0, 0.0, 0.0), crs_uuid=None, use_vertical=False, mesh=None, mesh_dz_dk=1.0, set_points_cached=False, as_irregular_grid=False, find_properties=True, title=None, originator=None, extra_metadata={})

Creates a regular grid object based on dxyz, or derived from a Mesh object.

Parameters

• parent_model (model.Model object) – the model to which the new grid will be assigned

• uuid (optional) – the uuid for an existing grid part; if present, the RegularGrid object is based on existing data or a mix of that data and other arguments where present

• extent_kji (triple positive integers, optional) – the number of cells in the grid (nk, nj, ni); required unless uuid is present

• dxyz (triple float, optional) – use when the I,J,K axes align with the x,y,z axes (possible with inverted directions); the size of each cell (dx, dy, dz); values may be negative

• dxyz_dkji (numpy float array of shape (3, 3), optional) – how x,y,z values increase with each step in each direction K,J,I; first index is KJI, second index is xyz; only one of dxyz, dxyz_dkji and mesh should be present; NB axis ordering is different to that used in Mesh class for dxyz_dij

• origin (triple float, default (0.0, 0.0, 0.0)) – the location in the local coordinate space of the crs of the ‘first’ corner point of the grid

• crs_uuid (uuid.UUID, optional) – the uuid of the coordinate reference system for the grid

• use_vertical (boolean, default False) – if True and the pillars of the regular grid are vertical then a pillar shape of ‘vertical’ is used; if False (or the pillars are not vertical), then a pillar shape of ‘straight’ is used

• mesh (surface.Mesh object, optional) – if present, the I,J layout of the grid is based on the mesh, which must be regular, and the K cell size is given by the mesh_dz_dk argument; if present, then dxyz and dxyz_dkji must be None

• mesh_dz_dk (float, default 1.0) – the size of cells in the K axis, which is aligned with the z axis, when starting from a mesh; ignored if mesh is None

• set_points_cached (boolean, default False) – if True, an explicit geometry is created for the regular grid in the form of the cached points array; will be treated as True if as_irregular_grid is True

• as_irregular_grid (boolean, default False) – if True, the grid is setup such that it will appear as a Grid object when next loaded from disc

• find_properties (boolean, default True) – if True and uuid is not None, a grid property collection is instantiated as an attribute, holding properties for which this grid is the supporting representation

• title (str, optional) – citation title for new grid; ignored if loading from xml

• originator (str, optional) – name of person creating the grid; defaults to login id; ignored if loading from xml

• extra_metadata (dict, optional) – dictionary of extra metadata items to add to the grid; ignored if loading from xml

Returns

a newly created RegularGrid object with inheritance from the Grid class

Notes

the RESQML standard allows for regular grid geometry pillars to be stored as parametric lines but that is not yet supported by this code base; however, constant dx, dy, dz arrays are supported; alternatively, regular meshes (Grid2d) may be stored in parameterized form and used to generate a regular grid here; if uuid, dxyz, dxyz_dkji and mesh arguments are all None then unit cube cells aligned with the x,y,z axes will be generated; to store the geometry explicitly set as_irregular_grid True and use the following methods: make_regular_points_cached(), write_hdf5(), create_xml(…, write_geometry = True); otherwise, avoid write_hdf5() and call create_xml(…, write_geometry = False); if geometry is not stored explicitly, the uuid of the crs is stored as extra metadata if origin is not triple zero, a new crs will be created with the origin moved appropriately

actual_pillar_shape(patch_metadata=False, tolerance=0.001)

Returns actual shape of pillars.

Parameters

• patch_metadata (boolean, default False) – if True, the actual shape replaces whatever was in the metadata

• tolerance (float, ignored) –

Returns

string – ‘vertical’, ‘straight’ or ‘curved’

Note

setting patch_metadata True will affect the attribute in this Grid object; however, it will not be preserved unless the create_xml() method is called, followed at some point with model.store_epc()

aligned_column_centres()

For an aligned grid, returns an array of column centres in xy, of shape (nj, ni, 2).

aligned_dxyz()

Returns triple float dx, dy, dz cell dimensions for aligned grids only.

append_extra_metadata(meta_dict)

Append a given dictionary of metadata to the existing metadata.

axial_lengths_kji()

Returns a triple float being lengths of primary axes (K, J, I) for each cell.

bounding_box(cell_kji0, points_root=None, cache_cp_array=False)

Returns the xyz box which envelopes the specified cell, as a numpy array of shape (2, 3).

cache_all_geometry_arrays()

Loads from hdf5 into memory all the arrays defining the grid geometry.

Notes

call this method if much grid geometry processing is coming up, to save having to worry about individual caching arguments to many other methods; this method does not create a column to pillar mapping which will often also be needed; the arrays are cached as direct attributes to this grid object; the names, shapes and types of the attributes are: - array_cell_geometry_is_defined (nk, nj, ni) bool; - array_pillar_geometry_is_defined (nj + 1, ni + 1) bool; - points_cached (nk + 1, nj + 1, ni + 1, 3) or (nk + 1, np, 3) float (np = number of primary pillars); - split_pillar_indices_cached (nps) int (nps = number of primary pillars that are split); - cols_for_split_pillars (npxc) int (npxc = number of column corners using extra pillars due to splitting); - cols_for_split_pillars_cl (npx) int (npx = number of extra pillars due to splitting); the last 3 are only present when the grid has one or more split pillars; the split pillar data includes the use of a ‘jagged’ array (effectively an array of lists represented as a linear array and a ‘cumulative length’ index array)

cell_count(active_only=False, non_pinched_out_only=False, geometry_defined_only=False)

Returns number of cells in grid; optionally limited by active, non-pinched-out, or having geometry.

Parameters

• active_only (boolean, default False) – if True, the count of active cells is returned

• non_pinched_out_only (boolean, default False) – if True, the count of cells with vertical thickness greater than 0.001 (units are crs vertical units) is returned

• geometry_defined_only (boolean, default False) – if True, the count of cells which have a defined geometry is returned (a zero thickness cell may still have a defined geometry)

Returns

integer being the number of cells in the grid

cell_geometry_is_defined(cell_kji0=None, cell_geometry_is_defined_root=None, cache_array=True)

Override of Grid method indicating whether a cell has defined geometry, here always True.

cell_geometry_is_defined_ref()

Returns an in-memory numpy array containing the boolean data indicating which cells have geometry defined.

Returns

numpy array of booleans of shape (nk, nj, ni); True value indicates cell has geometry defined; False indicates that the cell’s geometry (points xyz values) cannot be used

Note

if geometry is flagged in the xml as being defined for all cells, then this function returns None; geometry_defined_for_all_cells() can be used to test for that situation

cell_inactive(cell_kji0, pv_array=None, pv_tol=0.01)

Returns True if the cell is inactive.

centre_point(cell_kji0=None, cache_centre_array=False, use_origin=True)

Returns centre point of a cell or array of centre points of all cells.

Parameters

• cell_kji0 (optional) – if present, the (k, j, i) indices of the individual cell for which the centre point is required; zero based indexing

• cache_centre_array (bool, default False) – If True, or cell_kji0 is None, an array of centre points is generated and added as an attribute of the grid, with attribute name array_centre_point

• use_origin (bool, default True) – if True, the x, y & z offsets (local origin) are added to the computed cell centre points

Returns

(x, y, z) 3 element numpy array of floats holding centre point of cell; or numpy 3+1D array if cell_kji0 is None

Note

resulting coordinates are in the same (local) crs as the grid points if use_origin is True

centre_point_list(cell_kji0s)

Returns centre points for a list of cells; caches centre points for all cells.

Parameters

cell_kji0s (numpy int array of shape (N, 3)) – the (k, j, i) indices of the individual cells for which the centre points are required; zero based indexing

Returns

numpy float array of shape (N, 3) being the (x, y, z) centre points of the cells

Note

resulting coordinates are in the same (local) crs as the grid points

check_top_and_base_cell_edge_directions()

Check grid top face I & J edge vectors (in x,y) against basal equivalents.

Max 90 degree angle tolerated.

Returns

boolean – True if all checks pass; False if one or more checks fail

Notes

similarly checks cell edge directions in neighbouring cells in top (and separately in base) currently requires geometry to be defined for all pillars logs a warning if a check is not passed

property citation_title

Citation block title equivalent to self.title.

clear_face_sets()

Discard face sets.

column_is_inactive(col_ji0)

Returns True if all the cells in the specified column are inactive.

Parameters

col_ji0 (int pair) – the (j0, i0) column indices

Returns

boolean – True if all the cells in the column are inactive; False if at least one cell is active

combined_tr_mult_properties_from_gcs_mults(gcs_uuid_list=None, realization=None, merge_mode='minimum', sided=None, fill_value=1.0, active_only=True, apply_baffles=False, baffle_triplet=None, composite_property=False)

Add triplet of transmissibility multiplier properties by combining gcs properties.

Parameters

• gcs_uuid_list (list of UUID, optional) – if None, all grid connection sets related to this grid will be used

• realization (int, optional) – if present, is used to filter tranmissibility multiplier input properties and is added to the output properties

• merge_mode (str, default 'minimum') – one of ‘minimum’, ‘multiply’, ‘maximum’, ‘exception’; how to handle multiple values applicable to the same grid face

• sided (bool, optional) – whether to apply values on both sides of each gcs cell-face pair; if None, will default to False if merge mode is multiply, True otherwise

• fill_value (float, optional, default 1.0) – the value to use for grid faces not present in any of the gcs’es; if None, NaN will be used

• active_only (bool, default True) – if True and an active property exists for a grid connection set, then only active faces are used when combining to make the grid face properties

• apply_baffles (bool, default False) – if True, where a baffle property exists for a grid connection set, a transmissibility multiplier of zero will be used for faces marked as True, overriding the multiplier property values at such faces

• baffle_triplet (triplet of numpy bool arrays, optional) – if present, boolean masks over the grid internal faces; where True, a value of zero will be enforced for the multipliers regardless of the grid connection set properties

• composite_property (bool, default False) – if True, the transmissibility data is stored in a single property with no direction facet (in accordance with the RESQML standard); if False, a separate property is generated for each of the three directions

Returns

list of 3 uuids, one for each of the newly created transmissibility multiplier properties; or a list with just one uuid, if composite_property is True

Notes

each grid connection set must refer to this grid only; the generated properties have indexable element ‘faces’, not ‘faces per cell’, so may not be suitable for faulted grids; the baffle_triplet arrays, if provided, must be for internal faces only, so have extents of (nk - 1, nj, ni), (nk, nj - 1, ni), (nk, nj, ni -1); note that this is a different protocol than the indexable element of faces, which includes external faces; set composite_property True for compatibility with shape information indicated in RESQML documentation

composite_bounding_box(bounding_box_list)

Returns the xyz box which envelopes all the boxes in the list, as a numpy array of shape (2, 3).

coordinate_line_end_points()

Returns xyz of top and bottom of each primary pillar.

Returns

numpy float array of shape (nj + 1, ni + 1, 2, 3)

corner_points(cell_kji0=None, points_root=None, cache_resqml_array=None, cache_cp_array=False)

Returns a numpy array of corner points for a single cell or the whole grid.

Parameters

• cell_kji0 (triple float, optional) – if present, index of cell for which corner points are required; if None, an array holding corner points for all cells is returned

• points_root (ignored) – not used; exists for signature compatibility with parent class method

• cache_resqml_array (ignored) – not used; exists for signature compatibility with parent class method

• cache_cp_array (bool, default False) – if True (or cell_kji0 is None), the full corner point array is cached as an attribute of the grid

Notes

if cell_kji0 is not None, a 4D array of shape (2, 2, 2, 3) holding single cell corner points in logical order [kp, jp, ip, xyz] is returned; if cell_kji0 is None, a pagoda style 7D array [k, j, i, kp, jp, ip, xyz] is cached and returned; the ordering of the corner points is in the logical order, which is not the same as that used by Nexus CORP data; olio.grid_functions.resequence_nexus_corp() can be used to switch back and forth between this pagoda ordering and Nexus corp ordering; this is the usual way to access full corner points for cells where working with native resqml data is undesirable; this method returns coordinates in the local crs space

create_column_pillar_mapping()

Creates an array attribute holding set of 4 pillar indices for each I, J column of cells.

Returns

numpy integer array of shape (nj, ni, 2, 2) where the last two indices are jp, ip; the array contains the pillar index for each of the 4 corners of each column of cells

Notes

the array is also cached as an attribute of the grid object: grid.pillars_for_column for grids with split coordinates lines (faults), this array allows for fast access to the correct pillar data for the corner of a column of cells; here and elsewhere, ip & jp (& kp) refer to a 0 or 1 index which determines the side of a cell, ip & jp together select one of the four corners of a column; the pillar index is a single integer, which is used as the second index into the points array for a grid geometry with split pillars; for unsplit grid geometries, such a pillar index must be converted back into a j’, i’ pair of indices (or the points array must be reshaped to combine the two indices into one)

create_xml(ext_uuid=None, add_as_part=True, add_relationships=True, set_as_grid_root=True, title=None, originator=None, write_active=True, write_geometry=None, extra_metadata={}, expand_const_arrays=False, add_cell_length_properties=True, use_lattice=True)

Creates xml for this RegularGrid object; by default the explicit geometry is not included.

see docstring for Grid.create_xml()

additional argument:

add_cell_length_properties (boolean, default True): if True, 3 constant property arrays with cells as

indexable element are created to hold the lengths of the primary axes of the cells; the xml is created for the properties and they are added to the model (no hdf5 write needed)

use_lattice (boolean, default True): if True, a geometry node is created with a Point3dLatticeArray;

Note

if the regular grid has been instatiated using the as_irregular_grid mode, a lattice will not be used, regardless of the use_lattice argument; if using a lattice representation, the write_geomety argument is ignored and a lattice geometry will be created

denaturalized_cell_index(c0)

Returns a 3 element cell_kji0 index (as a tuple) for the cell with given natural index.

denaturalized_cell_indices(c0s)

Returns an integer array holding kji0 indices for the cells with given natural indices.

argument:

c0s: numpy integer array of shape (…,) being natural cell indices (for a flattened array)

Returns

numpy integer array of shape (…, 3) being the equivalent kji0 protocol cell indices

extract_children()

Looks for LGRs related to this grid and sets the local_grid_uuid_list attribute.

extract_crs_uuid()

Returns uuid for coordinate reference system, as stored in geometry xml tree.

Returns

uuid.UUID object

extract_extent_kji()

Returns the grid extent; for IJK grids this is a 3 integer numpy array, order is Nk, Nj, Ni.

Returns

numpy int array of shape (3,) being number of cells in k, j & i axes respectively; the return value is cached in attribute extent_kji, which can alternatively be referenced directly by calling code as the value is set from xml on initialisation

extract_geometry_time_index()

Returns integer time index, or None, for the grid geometry, as stored in xml for dynamic geometries.

Notes

if the value is not None, it represents the time index as stored in the xml, or the time index as updated when setting the node points from a points property

extract_grid_is_right_handed()

Returns boolean indicating whether grid IJK axes are right handed, as stored in xml.

Returns

boolean – True if grid is right handed; False if left handed

Notes

this is the actual handedness of the IJK indexing of grid cells; the coordinate reference system has its own implicit handedness for xyz axes; Nexus requires the IJK space to be righthanded so if it is not, the handedness of the xyz space is falsified when exporting for Nexus (as Nexus allows xyz to be right or lefthanded and it is the handedness of the IJK space with respect to the xyz space that matters)

extract_has_split_coordinate_lines()

Returns boolean indicating whether grid geometry has any split coordinate lines (split pillars, ie. faults).

Returns

boolean – True if the grid has one or more split pillars; False if all pillars are unsplit

Notes

the return value is based on the array elements present in the xml tree, unless it has already been determined; resqml ijk grids with split coordinate lines have extra arrays compared to unfaulted grids, and the main Points array is indexed differently: [k’, pillar_index, xyz] instead of [k’, j’, i’, xyz] (where k’, j’, i’ range of nk+k_gaps+1, nj+1, ni+1 respectively)

extract_inactive_mask(check_pinchout=False)

Returns boolean numpy array indicating which cells are inactive, if (in)active property found in this grid.

Returns

numpy array of booleans, of shape (nk, nj, ni) being True for cells which are inactive; False for active

Note

RESQML does not have a built-in concept of inactive (dead) cells, though the usage guide advises to use a discrete property with a local property kind of ‘active’; this resqpy code can maintain an ‘inactive’ attribute for the grid object, which is a boolean numpy array indicating which cells are inactive

extract_k_direction_is_down()

Returns boolean indicating whether increasing K indices are generally for deeper cells, as stored in xml.

Returns

boolean – True if increasing K generally indicates increasing depth

Notes

resqml allows layers to fold back over themselves, so the relationship between k and depth might not be monotonic; higher level code sometimes requires k to increase with depth; independently of this, z values may increase upwards or downwards in a coordinate reference system; this method does not modify the grid_is_righthanded indicator

extract_k_gaps()

Returns information about gaps (voids) between layers in the grid.

Returns

(int, numpy bool array, numpy int array) being the number of gaps between layers; a 1D bool array of extent nk-1 set True where there is a gap below the layer; and a 1D int array being the k index to actually use in the points data for each layer k0

Notes

all returned elements are stored as attributes in the grid object; int and bool array elements will be None if there are no k gaps; each k gap implies an extra element in the points data for each pillar; when wanting to index k interfaces (horizons) rather than layers, the last of the returned values can be used to index the k axis of the points data to yield the top face of the layer and the successor in k will always index the basal face of the same layer

extract_parent()

Returns the uuid of the parent grid for the supplied grid

extract_pillar_shape()

Returns string indicating whether whether pillars are curved, straight, or vertical as stored in xml.

Returns

string – either ‘curved’, ‘straight’ or ‘vertical’

Note

resqml datasets often have ‘curved’, even when the pillars are actually ‘vertical’ or ‘straight’; use actual_pillar_shape() method to determine the shape from the actual xyz points data

extract_property_collection()

Load grid property collection object holding lists of all properties in model that relate to this grid.

Returns

resqml_property.GridPropertyCollection object

Note

a reference to the grid property collection is cached in this grid object; if the properties change, for example by generating some new properties, the property_collection attribute of the grid object would need to be reset to None elsewhere before calling this method again

extract_stratigraphy()

Loads stratigraphic information from xml.

face_centre(cell_kji0, axis, zero_or_one, points_root=None, cache_resqml_array=True, cache_cp_array=False)

Returns xyz location of the centre point of a face of the cell (or all cells).

face_centres_kji_01(cell_kji0, points_root=None, cache_resqml_array=True, cache_cp_array=False)

Returns an array of shape (3, 2, 3) being (axis, 0 or 1, xyz) of face centre points for cell.

fault_connection_set(skip_inactive=True, compute_transmissibility=False, add_to_model=False, realization=None, inherit_features_from=None, title='fault juxtaposition set')

Returns (and caches) a GridConnectionSet representing juxtaposition across faces with split pillars.

Parameters

• skip_inactive (boolean, default True) – if True, then cell face pairs involving an inactive cell will be omitted from the results

• compute_transmissibilities (boolean, default False) – if True, then transmissibilities will be computed for the cell face pairs (unless already existing as a cached attribute of the grid)

• add_to_model (boolean, default False) – if True, the connection set is written to hdf5 and xml is created; if compute_transmissibilty is True then the transmissibility property is also added

• realization (int, optional) – if present, is used as the realization number when adding transmissibility property to model; ignored if compute_transmissibility is False

• inherit_features_from (GridConnectionSet, optional) – if present, the features (named faults) are inherited from this grid connection set based on a match of either cell face in a juxtaposed pair

• title (string, default 'fault juxtaposition set') – the citation title to use if adding to model

Returns

GridConnectionSet, numpy float array of shape (count,) transmissibilities (or None), where count is the number of cell face pairs in the grid connection set, which contains entries for all juxtaposed faces with a split pillar as an edge; if the grid does not have split pillars (ie. is unfaulted) or there are no qualifying connections, (None, None) is returned

fault_throws()

Finds mean throw of each J and I face; adds throw arrays as attributes to this grid and returns them.

Note

this method is deprecated, or due for overhaul to make compatible with resqml_fault module and the GridConnectionSet class

fault_throws_per_edge_per_column(mode='maximum', simple_z=False, axis_polarity_mode=True)

Return array holding max, mean or min throw based on split node separations.

Parameters

• mode (string, default 'maximum') – one of ‘minimum’, ‘mean’, ‘maximum’; determines how to resolve variation in throw for each column edge

• simple_z (boolean, default False) – if True, the returned throw values are vertical offsets; if False, the displacement in xyz space between split points is the basis of the returned values and may include a lateral offset component as well as xy displacement due to sloping pillars

• axis_polarity (boolean, default True) – determines shape and ordering of returned array; if True, the returned array has shape (nj, ni, 2, 2); if False the shape is (nj, ni, 4); see return value notes for more information

Returns

numpy float array of shape (nj, ni, 2, 2) or (nj, ni, 4) holding fault throw values for each column edge; units are

z units of crs for this grid; if simple_z is False, xy units and z units must be the same; positive values indicate greater depth if z is increasing downwards (or shallower if z is increasing upwards); negative values indicate the opposite; the shape and ordering of the returned array is determined by axis_polarity_mode; if axis_polarity_mode is True, the returned array has shape (nj, ni, 2, 2) with the third index being axis (0 = J, 1 = I) and the final index being polarity (0 = minus face edge, 1 = plus face edge); if axis_polarity_mode is False, the shape is (nj, ni, 4) and the face edges are ordered I-, J+, I+, J-, as required by the resqml standard for a property with indexable element ‘edges per column’

Notes

the throws calculated by this method are based merely on grid geometry and do not refer to grid connection sets; NB: the same absolute value is returned, with opposite sign, for the edges on opposing sides of a fault; either one of these alone indicates the full throw; the property module contains a pair of reformatting functions for moving an array between the two axis polarity modes; minimum and maximum modes work on the absolute throws

find_cell_for_point_xy(x, y, k0=0, vertical_ref='top', local_coords=True)

Searches in 2D for a cell containing point x,y in layer k0; return (j0, i0) or (None, None).

find_faults(set_face_sets=False, create_organizing_objects_where_needed=False)

Searches for column-faces that are faulted and assigns fault ids; creates list of column-faces per fault id.

Note

this method is deprecated, or due for overhaul to make compatible with resqml_fault module and the GridConnectionSet class

geometry_defined_for_all_cells(cache_array=True)

Returns True if geometry is defined for all cells; False otherwise.

argument:

cache_array (boolean, default True): if True, the ‘cell geometry is defined’ array is cached in memory,

unless the xml indicates that geometry is defined for all cells, in which case that is noted

Returns

boolean – True if geometry is defined for all cells; False otherwise

geometry_defined_for_all_pillars(cache_array=True, pillar_geometry_is_defined_root=None)

Returns True if geometry is defined for all pillars; False otherwise.

Parameters

• cache_array (boolean, default True) – if True, the ‘pillar geometry is defined’ array is cached in memory, unless the xml indicates that geometry is defined for all pillars, in which case that is noted

• pillar_geometry_is_defined_root (optional) – if present, the root of the ‘pillar geometry is defined’ xml tree for this grid; this optional argument is to allow for speed optimisation, to save searching for the node

Returns

boolean – True if the geometry is defined for all pillars; False otherwise

get_represented_interpretation()

Establishes the represented interpretation uuid, as stored in the xml tree, if present

get_volume_conversion_factor(required_uom)

Returns a factor for converting volumes calculated in the grid’s CRS to the required uom.

get_volume_uom(required_uom)

Returns a RESQML unit of measure string to use for volume quantities for the grid.

Parameters

required_uom (str, optional) – if present, the RESQML unit of measure (for quantity volume) to use

Returns

string holding a valid RESQML uom for quantity class volume

global_to_local_crs(a, crs_uuid, global_xy_units=None, global_z_units=None, global_z_increasing_downward=None)

Converts array of points in situ from global coordinate system to established local one.

half_cell_transmissibility(use_property=None, realization=None, tolerance=None)

Returns (and caches if realization is None) half cell transmissibilities for this regular grid.

Parameters

• use_property (ignored) –

• realization (int, optional) –

• tolerance (ignored) –

Returns

numpy float array of shape (nk, nj, ni, 3, 2) where the 3 covers K,J,I and the 2 covers the

face polarity: - (0) and + (1); units will depend on the length units of the coordinate reference system for the grid; the units will be m3.cP/(kPa.d) or bbl.cP/(psi.d) for grid length units of m and ft respectively

Notes

the values for - and + polarity will always be equal, the data is duplicated for compatibility with parent Grid class; the returned array is in the logical resqpy arrangement; it must be discombobulated before being added as a property; this method does not write to hdf5, nor create a new property or xml; if realization is None, a grid attribute cached array will be used

horizon_points(ref_k0=0, heal_faults=False, kp=0)

Returns reference to a points layer array of shape ((nj + 1), (ni + 1), 3) based on primary pillars.

Parameters

• ref_k0 (integer) – the horizon layer number, in the range 0 to nk (or layer number in range 0..nk-1 in the case of grids with k gaps)

• heal_faults (boolean, default False) – if True and the grid has split coordinate lines, an unsplit equivalent of the grid points is generated first and the returned points are based on that data; otherwise, the primary pillar data is used, which effectively gives a point from one side or another of any faults, rather than an averaged point

• kp (integer, default 0) – set to 1 to specify the base of layer ref_k0, in case of grids with k gaps

Returns

a numpy array of floats of shape ((nj + 1), (ni + 1), 3) being the (shared) cell corner point locations for the plane of points, based on the primary pillars or unsplit equivalent pillars

Notes

the primary pillars are the ‘first’ set of points for a pillar; a split pillar will have one to three other sets of point data but those are ignored by this function unless heal_faults is True, in which case an averaged point will be used for the split pillars; to get full unhealed representation of split horizon points, use split_horizon_points() function instead; for grids without k gaps, ref_k0 can be used alone, in the range 0..nk, to identify the horizon; alternatively, or for grids with k gaps, the ref_k0 can specify the layer in the range 0..nk-1, with kp being passed the value 0 (default) for the top of the layer, or 1 for the base of the layer

interface_length(cell_kji0, axis, points_root=None, cache_resqml_array=True, cache_cp_array=False, required_uom=None)

Returns the length between centres of an opposite pair of faces of the cell.

Note

if required_uom is not specified, units of returned length are the grid’s crs xy units

interface_lengths_kji(cell_kji0, points_root=None, cache_resqml_array=True, cache_cp_array=False, required_uom=None)

Returns 3 interface centre point separation lengths for axes k, j, i.

Note

if required_uom is not specified, units of returned length are the grid’s crs xy units

interface_vector(cell_kji0, axis, points_root=None, cache_resqml_array=True, cache_cp_array=False)

Returns an xyz vector between centres of an opposite pair of faces of the cell (or vectors for all cells).

Note

units are implicitly those of the grid’s crs; differing xy & z units would imply that the direction of the vector is not a true direction

interface_vectors_kji(cell_kji0, points_root=None, cache_resqml_array=True, cache_cp_array=False)

Returns 3 interface centre point difference vectors for axes k, j, i.

Note

units are implicitly those of the grid’s crs; differing xy & z units would imply that the direction of the vectors are not true directions

interpolated_point(cell_kji0, interpolation_fraction, points_root=None, cache_resqml_array=True, cache_cp_array=False)

Returns xyz point interpolated from corners of cell.

Depends on 3 interpolation fractions in range 0 to 1.

interpolated_points(cell_kji0, interpolation_fractions, points_root=None, cache_resqml_array=True, cache_cp_array=False)

Returns xyz points interpolated from corners of cell.

Depending on 3 interpolation fraction numpy vectors, each value in range 0 to 1.

Parameters

• cell_kji0 (triple int) – indices of individual cell whose corner points are to be interpolated

• interpolation_fractions (list of three numpy vectors of floats) – k, j & i interpolation fraction vectors, each element in range 0 to 1

• points_root (xml node, optional) – for efficiency when making multiple calls, this can be set to the xml node of the points data

• cache_resqml_array (boolean, default True) – if True, the resqml points data will be cached as an attribute of this grid object

• cache_cp_array (boolean, default False) – if True a fully expanded 7D corner points array will be established for this grid and cached as an attribute (recommended if looping over many or all the cells and if memory space allows)

Returns

4D numpy float array of shape (nik, nij, nii, 3) being the interpolated points; nik is the number of elements in the first of the interpolation fraction lists (ie. for k); similarly for nij and nii; the final axis covers xyz

notea:

this method returns a lattice of trilinear interpolations of the corner point of the host cell; the returned points are in ‘shared’ arrangement (like resqml points data for an IjkGrid without split pillars or k gaps), not a fully expanded 7D array; calling code must redistribute to corner points of individual fine cells if that is the intention

invalidate_corner_points()

Deletes cached copy of corner points, if present.

Use if any pillar geometry changes, or to reclaim memory.

is_split_column_face(j0, i0, axis, polarity)

Returns True if the I or J column face is split; False otherwise.

k_gap_connection_set(skip_inactive=True, compute_transmissibility=False, add_to_model=False, realization=None, tolerance=0.001)

Returns (and caches) a GridConnectionSet representing juxtaposition across zero thickness K gaps.

Parameters

• skip_inactive (boolean, default True) – if True, then cell face pairs involving an inactive cell will be omitted from the results

• compute_transmissibilities (boolean, default False) – if True, then transmissibilities will be computed for the cell face pairs (unless already existing as a cached attribute of the grid)

• add_to_model (boolean, default False) – if True, the connection set is written to hdf5 and xml is created; if compute_transmissibilty is True then the transmissibility property is also added

• realization (int, optional) – if present, is used as the realization number when adding transmissibility property to model; ignored if compute_transmissibility is False

• tolerance (float, default 0.001) – the maximum K gap thickness that will be ‘bridged’ by a connection; units are implicitly those of the z units in the grid’s coordinate reference system

Returns

GridConnectionSet, numpy float array of shape (count,) transmissibilities (or None), where count is the number of cell face pairs in the grid connection set, which contains entries for all juxtaposed K faces separated logically by pinched out (zero thickness) cells; if there are no pinchouts (or no qualifying connections) then (None, None) will be returned

Note

if cached values are found they are returned regardless of the specified tolerance

local_to_global_crs(a, crs_uuid, global_xy_units=None, global_z_units=None, global_z_increasing_downward=None)

Converts array of points in situ from local coordinate system to global one.

make_face_set_from_dataframe(df)

Creates a curtain face set for each named fault in dataframe.

Note

this method is deprecated, or due for overhaul to make compatible with resqml_fault module and the GridConnectionSet class

make_face_sets_from_pillar_lists(pillar_list_list, face_set_id, axis='K', ref_slice0=0, plus_face=False, projection='xy')

Creates a curtain face set for each pillar (or rod) list.

Returns

(face_set_dict, full_pillar_list_dict)

Note

‘xz’ and ‘yz’ projections currently only supported for unsplit grids

make_regular_points_cached(apply_origin_offset=True)

Set up the cached points array as an explicit representation of the regular grid geometry.

Parameters

• apply_origin_offset (boolean, default True) – if True, this method includes the regular grid

• data (origin in the calculated points) –

Note

if apply_origin_offset is True, the related crs must not store the origin as offset data

natural_cell_index(cell_kji0)

Returns a single integer for the cell, being the index into a flattened array.

natural_cell_indices(cell_kji0s)

Returns a numpy integer array with a value for each of the cells, being the index into a flattened array.

argument:

cell_kji0s: numpy integer array of shape (…, 3) being a list of cell indices in kji0 protocol

Returns

numpy integer array of shape (…,) being the equivalent natural cell indices (for a flattened array of cells)

nearest_pillar(xy, ref_k0=0, kp=0)

Returns the (j0, i0) indices of the primary pillar with point closest in x,y plane to point xy.

nearest_rod(xyz, projection, axis, ref_slice0=0, plus_face=False)

Returns the (k0, j0) or (k0 ,i0) indices of the closest point(s) to xyz(s); projection is ‘xy’, ‘xz’ or ‘yz’.

Note

currently only for unsplit grids

property nk_plus_k_gaps

Returns the number of layers including any K gaps.

off_handed()

Returns False if IJK and xyz have same handedness, True if they differ.

property part

Standard part name corresponding to self.uuid.

pillar_distances_sqr(xy, ref_k0=0, kp=0, horizon_points=None)

Returns array of the square of the distances of primary pillars in x,y plane to point xy.

Parameters

• xy (float pair) – the xy coordinate to compute the pillar distances to

• ref_k0 (int, default 0) – the horizon layer number to use

• horizon_points (numpy array, optional) – if present, should be array as returned by horizon_points() method; pass for efficiency in case of multiple calls

pillar_foursome(ji0, none_if_unsplit=False)

Returns an int array of the natural pillar indices applicable to each column around primary.

Parameters

• ji0 (pair of ints) – the pillar indices (j0, i0) of the primary pillar of interest

• none_if_unsplit (boolean, default False) – if True and the primary pillar is unsplit, None is returned; if False, a foursome is returned full of the natural index of the primary pillar

Returns

numpy int array of shape (2, 2) being the natural pillar indices (second axis index in raw points array) applicable to each of the four columns around the primary pillar; axes of foursome are (jp, ip); if the primary pillar is unsplit, None is returned if none_if_unsplit is set to True, otherwise the foursome as usual

pillar_geometry_is_defined(pillar_ji0=None, pillar_geometry_is_defined_root=None, cache_array=True)

Override of Grid method indicating whether a pillar has defined geometry, here always True.

pillar_geometry_is_defined_ref()

Returns an in-memory numpy array containing the boolean data indicating which pillars have geometry defined.

Returns

numpy array of booleans of shape (nj + 1, ni + 1); True value indicates pillar has geometry defined (at least for some points); False indicates that the pillar’s geometry (points xyz values) cannot be used; the resulting array only covers primary pillars; extra pillars for split pillars always have geometry defined

Note

if geometry is flagged in the xml as being defined for all pillars, then this function returns None

pinched_out(cell_kji0=None, **kwargs)

Returns pinched out boolean (always False) for a single cell or full array.

Parameters

• cell_kji0 (triple int, optional) – if present, the pinched out flag for a single cell is returned; if None, an array is returned

• Grid() (all other arguments ignored; present for compatibility with same method in) –

Returns

False, or numpy array filled with False

pinchout_connection_set(skip_inactive=True, compute_transmissibility=False, add_to_model=False, realization=None)

Returns (and caches) a GridConnectionSet representing juxtaposition across pinched out cells.

Parameters

• skip_inactive (boolean, default True) – if True, then cell face pairs involving an inactive cell will be omitted from the results

• compute_transmissibilities (boolean, default False) – if True, then transmissibilities will be computed for the cell face pairs (unless already existing as a cached attribute of the grid)

• add_to_model (boolean, default False) – if True, the connection set is written to hdf5 and xml is created; if compute_transmissibilty is True then the transmissibility property is also added

• realization (int, optional) – if present, is used as the realization number when adding transmissibility property to model; ignored if compute_transmissibility is False

Returns

GridConnectionSet, numpy float array of shape (count,) transmissibilities (or None), where count is the number of cell face pairs in the grid connection set, which contains entries for all juxtaposed K faces separated logically by pinched out (zero thickness) cells; if there are no pinchouts (or no qualifying connections) then (None, None) will be returned

pixel_map_for_split_horizon_points(horizon_points, origin, width, height, dx, dy=None)

Makes a mapping from pixels to cell j, i indices, based on split horizon points for a single horizon.

Parameters

• horizon_points (numpy array of shape (nj, ni, 2, 2, 2+)) – corner point x,y,z values for cell corners (j, i, jp, ip); as returned by split_horizon_points()

• origin (float pair) – x, y of south west corner of area covered by pixel rectangle, in local crs

• width (int) – the width of the pixel rectangle (number of pixels)

• height (int) – the height of the pixel rectangle (number of pixels)

• dx (float, optional) – the size (west to east) of a pixel, in locel crs

• dx – the size (south to north) of a pixel, in locel crs; defaults to dx

Returns

numpy int array of shape (height, width, 2), being the j, i indices of cells that the pixel centres lie within; values of -1 are used as null (ie. pixel not within any cell)

pixel_maps(origin, width, height, dx, dy=None, k0=None, vertical_ref='top')

Makes a mapping from pixels to cell j, i indices, based on split horizon points for a single horizon.

Parameters

• origin (float pair) – x, y of south west corner of area covered by pixel rectangle, in local crs

• width (int) – the width of the pixel rectangle (number of pixels)

• height (int) – the height of the pixel rectangle (number of pixels)

• dx (float) – the size (west to east) of a pixel, in locel crs

• dy (float, optional) – the size (south to north) of a pixel, in locel crs; defaults to dx

• k0 (int, default None) – if present, the single layer to create a 2D pixel map for; if None, a 3D map is created with one layer per layer of the grid

• vertical_ref (string, default 'top') – ‘top’ or ‘base’

Returns

numpy int array of shape (height, width, 2), or (nk, height, width, 2), being the j, i indices of cells that the pixel centres lie within; values of -1 are used as null (ie. pixel not within any cell)

point(cell_kji0=None, corner_index=array([0, 0, 0]), points_root=None, cache_array=True)

Return a cell corner point xyz; can optionally be used to cache points data.

Parameters

• cell_kji0 (3 integers, optional) – if not None, the index of the cell for the point of interest, in kji0 protocol

• corner_index (3 integers, default zeros) – the kp, jp, ip corner-within-cell indices (each 0 or 1)

• points_root (optional) – the xml node holding the points data

• cache_array (boolean, default True) – if True, the raw points data is cached in memory as a side effect

Returns

(x, y, z) of selected point as a 3 element numpy vector, or None if cell_kji0 is None

Note

if cell_kji0 is passed, the k0 value should be the layer index before adjustment for k_gaps, which this method will apply

point_areally(tolerance=0.001)

Returns array indicating which cells are reduced to a point in both I & J axes.

Returns

numopy bool array of shape extent_kji

Note

Any NaN point values will yield True for a cell

point_raw(index=None, points_root=None, cache_array=True)

Returns element from points data, indexed as corner point (k0, j0, i0).

Can optionally be used to cache points data.

Parameters

• index (3 integers, optional) – if not None, the index into the raw points data for the point of interest

• points_root (ignored) –

• cache_array (boolean, default True) – if True, the raw points data is cached in memory as a side effect

Returns

(x, y, z) of selected point as a 3 element numpy vector, or None if index is None

Notes

this function is typically called either to cache the points data in memory, or to fetch the coordinates of a single corner point; the index should be a triple kji0 with axes ranging over the shared corners nk+1, nj+1, ni+1

points_ref(masked=True)

Returns an in-memory numpy array containing the xyz data for points used in the grid geometry.

argument:

masked (boolean, default True): if True, a masked array is returned with NaN points masked out;

if False, a simple (unmasked) numpy array is returned

Returns

numpy array or masked array of float, of shape (nk + k_gaps + 1, nj + 1, ni + 1, 3) or (nk + k_gaps + 1, np, 3) where np is the total number of pillars (primary pillars + extras for split pillars)

Notes

this is the usual way to get at the actual grid geometry points data in the native resqml layout; the has_split_coordinate_lines boolean attribute can be used to determine which shape to expect; the shape is (nk + k_gaps + 1, nj + 1, ni + 1, 3) if there are no split coordinate lines (unfaulted); otherwise it is (nk + k_gaps + 1, np, 3), where np > (nj + 1) * (ni + 1), due to extra pillar data for the split pillars

poly_line_for_cell(cell_kji0, vertical_ref='top')

Returns a numpy array of shape (4, 3) being the 4 corners.

Corners are in order J-I-, J-I+, J+I+, J+I-; from the top or base face.

resolve_geometry_child(tag, child_node=None)

If xml child node is None, looks for tag amongst children of geometry root.

Parameters

• tag (string) – the tag of the geometry child node of interest

• child_node (optional) – the already resolved xml root of the child, or None

Returns

xml node of child of geometry node for this grid, which matches tag

Note

if child_node argument is not None, it is simply returned; if child_node is None, the geometry node for this grid is scanned for a child with matching tag

property root

XML node corresponding to self.uuid.

set_cached_points_from_property(points_property_uuid=None, property_collection=None, realization=None, time_index=None, set_grid_time_index=True, set_inactive=True, active_property_uuid=None, active_collection=None)

Modifies the cached points (geometry), setting the values from a points property.

Parameters

• points_property_uuid (uuid, optional) – the uuid of the points property; if present the remaining arguments are ignored except for inactive & active arguments

• property_collection (PropertyCollection, optional) – defaults to property collection for the grid; should only contain one set of points properties (but may also contain other non-points properties)

• realization (int, optional) – if present, the property in the collection with this realization number is used

• time_index (int, optional) – if present, the property in the collection with this time index is used

• set_grid_time_index (bool, default True) – if True, the grid’s time index will be set to the time_index argument and the grid’s time series uuid will be set to that referred to by the points property; if False, the grid’s time index will not be modified

• set_inactive (bool, default True) – if True, the grid’s inactive mask will be set based on an active cell property

• active_property_uuid (uuid, optional) – if present, the uuid of an active cell property to base the inactive mask on; ignored if set_inactive is False

• active_collection (uuid, optional) – default’s to property_collection if present, or the grid’s property collection otherwise; only used if set_inactive is True and active_property_uuid is None

Notes

the points property must have indexable element ‘nodes’ and be the same shape as the official points array for the grid; note that the shape of the points array is quite different between grids with split pillars and those without; the uom of the points property must be a length uom and match that used by the grid’s crs; the inactive mask of the grid will only be updated if the set_inactive argument is True; if points_property_uuid has been provided, and set_inactive is True, the active property must be identified with the active_property_uuid argument; if set_inactive is True and active_property_uuid is None and points_property_uuid is None and realization and/or time_index is in use, the active property collection must contain one series of active properties with the same variants (realizations and time indices) as the points property series; the active cell properties should be discrete and have a local property kind titled ‘active’; various cached data are invalidated and cleared by this method

set_crs(crs_uuid=None)

Establish crs attribute if not already set

set_face_set_gcs_list_from_dict(face_set_dict=None, create_organizing_objects_where_needed=False)

Creates a grid connection set for each feature in the face set dictionary, based on kelp list pairs.

set_geometry_is_defined(treat_as_nan=None, treat_dots_as_nan=False, complete_partial_pillars=False, nullify_partial_pillars=False, complete_all=False)

Set cached flags and/or arrays indicating which primary pillars have any points defined and which cells all points.

Parameters

• treat_as_nan (float, optional) – if present, any point with this value as x, y or z is changed to hold NaN values, which is the correct RESQML representation of undefined values

• treat_dots_as_nan (boolean, default False) – if True, the points around any inactive cell which has zero length along all its I and J edges will be set to NaN (which can intentionally invalidate the geometry of neighbouring cells)

• complete_partial_pillars (boolean, default False) – if True, pillars which have some but not all points defined will have values generated for the undefined (NaN) points

• nullify_partial_pillars (boolean, default False) – if True, pillars which have some undefined (NaN) points will be treated as if all the points on the pillar are undefined

• complete_all (boolean, default False) – if True, values will be generated for all undefined points (includes completion of partial pillars if both partial pillar arguments are False)

Notes

this method discards any previous information about which pillars and cells have geometry defined; the new settings are based solely on where points data is NaN (or has the value supplied as treat_as_nan etc.); the inactive attribute is also updated by this method, though any cells previously flagged as inactive will still be inactive; if points are generated due to either complete… argument being set True, the inactive mask is set prior to generating points, so all cells making use of generated points will be inactive; however, the geometry will show as defined where points have been generated; at most one of complete_partial_pillars and nullify_partial_pillars may be True; although the method modifies the cached (attribute) copies of various arrays, they are not written to hdf5 here

set_k_direction_from_points()

Sets the K direction indicator based on z direction and mean z values for top and base.

Note

this method does not modify the grid_is_righthanded indicator

set_modified(update_xml=False, update_hdf5=False)

Assigns a new uuid to this grid; also calls set_modified() for parent model.

Parameters

• update_xml (boolean, default False) – if True, the uuid is modified in the xml tree for the grid part

• update_hdf5 – (boolean, default False): if True, the uuid in the hdf5 internal path names for the datasets (arrays) for the grid are updated

Returns

the new uuid for this grid object

Notes

a resqml object should be thought of as immutable; therefore when modifying an object, it is preferable to assign it a new unique identifer which this method does for a grid; the hdf5 internal path names held in xml are only updated if both update_xml and update_hdf5 are True; if the grid object has been created using the Model.copy_part() method, it is not necessary to call this function as a new uuid will already have been assigned; NB: relationships are not updated by this function, including the relationship to the hdf5 external part

set_parent(parent_grid_uuid, self_is_refinement, parent_window)

Set relationship with respect to a parent grid.

Parameters

• parent_grid_uuid (uuid.UUID) – the uuid of the parent grid

• self_is_refinement (boolean) – if True, this grid is a refinement of the subset of the parent grid; if False, this grid is a coarsening

• parent_window – (olio.fine_coarse.FineCoarse object): slice mapping information in K, j & I axes; note that self_is_refinement determines which of the 2 grids is fine and which is coarse

skin(use_single_layer_tactics=False, is_regular=False)

Returns a GridSkin composite surface object reoresenting the outer surface of the grid.

slice_points(axis=0, ref_slice=0, local=False)

Returns a slice of points data for a layer or a cross section.

Parameters

• axis (int, default 0) – the axis of slicing 0 for K, 1 for J, 2 for I

• ref_slice (int, default 0) – the slice index in the direction of axis

• local (bool, default False) – if True, returned points are in the local crs; if False in global

Returns

numpy float array of points data of shape (Na, Nb, 3); (Na, Nb) are (NJ+1, NI+1), (NK+1, NI+1) or (NK+1, NJ+1) for axis values of 0, 1, or 2 respectively

split_column_faces()

Returns a pair of numpy boolean arrays indicating which internal column faces (column edges) are split.

split_gap_x_section_points(axis, ref_slice0=0, plus_face=False, masked=False)

Return array of points representing cell corners from an I or J interface slice for a faulted grid.

Parameters

• axis (string) – ‘I’ or ‘J’ being the axis of the cross-sectional slice (ie. dimension being dropped)

• ref_slice0 (int, default 0) – the reference value for indices in I or J (as defined in axis)

• plus_face (boolean, default False) – if False, negative face is used; if True, positive

• masked (boolean, default False) – if True, a masked numpy array is returned with NaN values masked out

Returns

a numpy array of shape (nk, nj, 2, 2, 3) or (nk, ni, 2, 2, 3) being the xyz points of the cell corners on the interfacial cross section; 3rd axis is kp; 4th axis is jp or ip; final axis is xyz

Note

this function is intended for split grids with k gaps though will also function for split grids without k gaps

split_horizon_points(ref_k0=0, masked=False, kp=0)

Returns reference to a corner points for a horizon, of shape (nj, ni, 2, 2, 3).

Parameters

• ref_k0 (integer) – the horizon layer number, in the range 0 to nk (or layer number in range 0..nk-1 in the case of grids with k gaps)

• masked (boolean, default False) – if True, a masked array is returned with NaN points masked out; if False, a simple (unmasked) numpy array is returned

• kp (integer, default 0) – set to 1 to specify the base of layer ref_k0, in case of grids with k gaps

Returns

numpy array of shape (nj, ni, 2, 2, 3) being corner point x,y,z values for cell corners (j, i, jp, ip)

Notes

if split points are needed for a range of horizons, it is more efficient to call split_horizons_points() than repeatedly call this function; for grids without k gaps, ref_k0 can be used alone, in the range 0..nk, to identify the horizon; alternatively, or for grids with k gaps, the ref_k0 can specify the layer in the range 0..nk-1, with kp being passed the value 0 (default) for the top of the layer, or 1 for the base of the layer

split_horizons_points(min_k0=None, max_k0=None, masked=False)

Returns reference to a corner points layer of shape (nh, nj, ni, 2, 2, 3) where nh is number of horizons.

Parameters

• min_k0 (integer) – the lowest horizon layer number to be included, in the range 0 to nk + k_gaps; defaults to zero

• max_k0 (integer) – the highest horizon layer number to be included, in the range 0 to nk + k_gaps; defaults to nk + k_gaps

• masked (boolean, default False) – if True, a masked array is returned with NaN points masked out; if False, a simple (unmasked) numpy array is returned

Returns

numpy array of shape (nh, nj, ni, 2, 2, 3) where nh = max_k0 - min_k0 + 1, being corner point x,y,z values for horizon corners (h, j, i, jp, ip) where h is the horizon (layer interface) index in the range 0 .. max_k0 - min_k0

Notes

data for horizon max_k0 is included in the result (unlike with python ranges); in the case of a grid with k gaps, the horizons points returned will follow the k indexing of the points data and calling code will need to keep track of the min_k0 offset when using k_raw_index_array to select a slice of the horizons points array

split_x_section_points(axis, ref_slice0=0, plus_face=False, masked=False)

Returns an array of points representing cell corners from an I or J interface slice for a faulted grid.

Parameters

• axis (string) – ‘I’ or ‘J’ being the axis of the cross-sectional slice (ie. dimension being dropped)

• ref_slice0 (int, default 0) – the reference value for indices in I or J (as defined in axis)

• plus_face (boolean, default False) – if False, negative face is used; if True, positive

• masked (boolean, default False) – if True, a masked numpy array is returned with NaN values masked out

Returns

a numpy array of shape (nk + 1, nj, 2, 3) or (nk + 1, ni, 2, 3) being the xyz points of the cell corners on the interfacial cross section; 3rd axis is jp or ip; final axis is xyz

Note

this function will only work for grids with no k gaps; it is intended for split grids though will also function for unsplit grids; use split_gap_x_section_points() if k gaps are present

thickness(cell_kji0=None, **kwargs)

Returns cell thickness (K axial length) for a single cell or full array.

Parameters

• cell_kji0 (triple int, optional) – if present, the thickness for a single cell is returned; if None, an array is returned

• Grid() (all other arguments ignored; present for compatibility with same method in) –

Returns

float, or numpy float array filled with a constant

transmissibility(tolerance=1e-06, use_tr_properties=True, realization=None, modifier_mode=None)

Returns transmissibilities for standard (IJK neighbouring) connections within this grid.

Parameters

• tolerance (float, default 1.0e-6) – the minimum half cell transmissibility below which zero inter-cell transmissibility will be set; units are as for returned values (see notes)

• use_tr_properties (boolean, default True) – if True, the grid’s property collection is inspected for possible transmissibility arrays and if found, they are used instead of calculation; note that when this argument is False, the property collection is still used for the feed arrays to the calculation

• realization (int, optional) – applies to pre-computed transmissibility properties or permeability and net to gross ratio properties when computing

• modifier_mode (string, optional) – if None, no transmissibility modifiers are applied; other options are: ‘faces multiplier’, for which directional transmissibility properties with indexable element of ‘faces’ will be used; ‘faces per cell multiplier’, in which case a transmissibility property with ‘faces per cell’ as the indexable element will be used to modify the half cell transmissibilities prior to combination; or ‘absolute’ in which case directional properties of local property kind ‘fault transmissibility’ (or ‘mat transmissibility’) and indexable element of ‘faces’ will be used as a third transmissibility term along with the two half cell transmissibilities at each face; see also the notes below

Returns

3 numpy float arrays of shape (nk + 1, nj, ni), (nk, nj + 1, ni), (nk, nj, ni + 1) being the neighbourly transmissibilities in K, J & I axes respectively

Notes

the 3 permeability arrays (and net to gross ratio if in use) must be identifiable in the property collection as they are used for the calculation; implicit units of measure of returned values will be m3.cP/(kPa.d) if grid crs length units are metres, bbl.cP/(psi.d) if length units are feet; the computation is compatible with the Nexus NEWTRAN formulation; values will be zero at pinchouts, and at column edges where there is a split pillar, even if there is juxtapostion of faces; the same is true of K gap faces (even where the gap is zero); NaNs in any of the feed properties also result in transmissibility values of zero; outer facing values will always be zero (included to be in accordance with RESQML faces properties); array caching in the grid object will only be used if realization is None; if a modifier mode of ‘faces multiplier’ or ‘faces per cell multiplier’ is specified, properties will be searched for with local property kind ‘transmissibility multiplier’ and the appropriate indexable element (and direction facet in the case of ‘faces multiplier’); the modifier mode of ‘absolute’ can be used to model the effect of faults and thin shales, tar mats etc. in a way which is independent of cell size; for ‘aboslute’ directional properties with indexable element of ‘faces’ and local property kind ‘fault transmissibility’ (or ‘mat transmissibility’) will be used; such absolute faces transmissibilities should have a value of np.inf or np.nan where no modification is required; note that this method is only dealing with logically neighbouring cells and will not compute values for faces with a split pillar, which should be handled elsewhere

try_reuse()

Look for an equivalent existing RESQML object and modify the uuid of this object if found.

Returns

boolean – True if an equivalent object was found, False if not

Note

by design this method may change this object’s uuid as a side effect

uncache_points()

Frees up memory by removing the cached copy of the grid’s points data.

Note

the memory will only actually become free when any other references to it pass out of scope or are deleted

unsplit_points_ref(cache_array=False, masked=False)

Returns a copy of the points array that has split pillars merged back into an unsplit configuration.

Parameters

• cache_array (boolean, default False) – if True, a copy of the unsplit points array is added as attribute array_unsplit_points to this grid object

• masked (boolean, default False) – if True, a masked array is returned with NaN points masked out; if False, a simple (unmasked) numpy array is returned

Returns

numpy array of float of shape (nk + k_gaps + 1, nj + 1, ni + 1, 3)

Note

for grids without split pillars, this function simply returns the points array in its native form; for grids with split pillars, an unsplit equivalent points array is calculated as the average of contributions to each pillar from the surrounding cell columns

unsplit_x_section_points(axis, ref_slice0=0, plus_face=False, masked=False)

Returns a 2D (+1 for xyz) array of points representing cell corners from an I or J interface slice.

Parameters

• axis (string) – ‘I’ or ‘J’ being the axis of the cross-sectional slice (ie. dimension being dropped)

• ref_slice0 (int, default 0) – the reference value for indices in I or J (as defined in axis)

• plus_face (boolean, default False) – if False, negative face is used; if True, positive

• masked (boolean, default False) – if True, a masked numpy array is returned with NaN values masked out

Returns

a 2+1D numpy array being the xyz points of the cell corners on the interfacial cross section; the 2D axes are K,J or K,I - whichever does not involve axis; shape is (nk + 1, nj + 1, 3) or (nk + 1, ni + 1, 3)

Note

restricted to unsplit grids with no k gaps; use split_x_section_points() for split grids with no k gaps or split_gap_x_section_points() for split grids with k gaps or x_section_corner_points() for any grid

volume(cell_kji0=None, required_uom=None)

Returns bulk rock volume of cell or numpy array of bulk rock volumes for all cells.

Parameters

• cell_kji0 (optional) – if present, the (k, j, i) indices of the individual cell for which the volume is required; zero based indexing

• required_uom (str, optional) – if present, the RESQML unit of measure (for quantity volume) that the volumes will be returned in; if None, the grid’s CRS z units cubed will be used

Returns

float, being the volume of cell identified by cell_kji0; or numpy float array of shape (nk, nj, ni) if cell_kji0 is None

Notes

the function can be used to find the volume of a single cell, or all cells; the method currently assumes that the primary i, j, k axes are mutually orthogonal

write_hdf5(expand_const_arrays=False, use_parametric_lines=False)

Writes grid geometry arrays to hdf5; a thin wrapper around write_hdf5_from_caches().

Parameters

• expand_const_arrays (bool, default False) – if True, any constant properties being written will be expanded to full arrays

• use_parametric_lines (bool, default False) – if True, the grid geomatry points will be stored using a 2 point (straight) parametric line form rather than the more commonly used full coordinate form; this argument must match that used when calling the create_xml() method

write_hdf5_from_caches(file=None, mode='a', geometry=True, imported_properties=None, write_active=None, stratigraphy=True, expand_const_arrays=False, use_int32=None, use_parametric_lines=False)

Writes hdf5 datasets for the grid geometry (and parent grid mapping) and optionally properties, from cached arrays.

Parameters

• file (str, optional) – if present, the hdf5 to write to; if None (the usual case), the file is identified automatically

• mode (str, default 'a') – ‘a’ or ‘w’ for append or (re)create

• geometry (bool, default True) – if True, the array data representing the grid geometry is included; otherwise not

• imported_properties (PropertyCollection, optional) – if present, the array data for the properties in the collection are also written to hdf5

• write_active (bool, optional) – if True, bool array data for an active property is written, by inverting the grid’s inactive array attribute; if None, the array is written if an active property does not already exist

• stratigraphy (bool, default True) – if True and stratigraphic information is set for the grid (mapping of grid layers to stratigraphic units), then the array data for the stratigraphy is also written to hdf5

• expand_const_arrays (bool, default False) – if True, any constant properties amongst the imported properties are expanded to full arrays and written to hdf5; if False, constant properties are not written to hdf5 as the data is fully handled in xml metadata

• use_int32 (bool, optional) – if True, integer arrays are written using 32 bit elements; if False, 64 bits are used; if None, a default will be used which will probably be 32 bit

• use_parametric_lines (bool, default False) – if True and geometry is being written, the cached points are converted to 2 point (straight) parametric line form before being written to hdf5; this setting needs to match that used when creating the xml; this argument must match that used when calling the create_xml() method

write_nexus_corp(file_name, local_coords=False, global_xy_units=None, global_z_units=None, global_z_increasing_downward=True, nexus_unit_system=None, write_nx_ny_nz=False, write_units_keyword=False, write_rh_keyword_if_needed=False, write_corp_keyword=False, use_binary=False, binary_only=False, nan_substitute_value=None)

Write grid geometry to file in Nexus CORP ordering.

Parameters

• file_name (str) – the path of the file to generate

• local_coords (bool, default False) – if True, CORP data is written in local coordinates

• global_xy_units (str, optional) – RESQML length uom to use for global xy coords; required if local_coords is False

• global_z_units (str, optional) – RESQML length uom to use for global z coords; required if local_coords is False

• global_z_increasing_downward (bool, default True) – whether global z values increase downwards; ignored if local_coords is True

• nexus_unit_system (str, optional) – the target Nexus unit system for the CORP data; if present, one of: ‘METRIC’, ‘METBAR’, ‘METKG/CM2’, ‘LAB’ or ‘ENGLISH’; if None, will be guessed based on local or global z units

• write_nx_ny_nz (bool, default False) – if True, NX NY NZ keywords and values are written

• write_units_keyword (bool, default False) – if True, the Nexus unit system keyword is written

• write_rh_keyword_if_needed (bool, default False) – if True, the RIGHTHANDED keyword is written if needed based on xyz and IJK handedness

• write_corp_keyword (bool, default False) – if True, the CORP keyword is written before the values

• use_binary (bool, default False) – if True, a pure binary file with the corp array is written

• binary_only (bool, default False) – if True, no ascii file is created, only a pure binary file

• nan_substitute_value (float, optional) – if present, a value to use in place of NaNs

x_section_corner_points(axis, ref_slice0=0, plus_face=False, masked=False, rotate=False, azimuth=None)

Returns a fully expanded array of points representing cell corners from an I or J interface slice.

Parameters

• axis (string) – ‘I’ or ‘J’ being the axis of the cross-sectional slice (ie. dimension being dropped)

• ref_slice0 (int, default 0) – the reference value for indices in I or J (as defined in axis)

• plus_face (boolean, default False) – if False, negative face is used; if True, positive

• masked (boolean, default False) – if True, a masked numpy array is returned with NaN values masked out

• rotate (boolean, default False) – if True, the cross section points are rotated around the z axis so that an azimuthal direction is mapped onto the positive x axis

• aximuth (float, optional) – the compass bearing in degrees to map onto the positive x axis if rotating; if None, the mean direction of the cross sectional points, along axis, is used; ignored if rotate is False

Returns

a numpy float array of shape (nk, nj, 2, 2, 3) or (nk, ni, 2, 2, 3) being the xyz points of the cell corners on the interfacial cross section; the 3rd index (1st 2) is kp, the 4th index is jp or ip

Note

this method will work for unsplit or split grids, with or without k gaps; use rotate argument to yield points with predominant variation in xz, suitable for plotting cross sections; if rotate is True then the absolute values of x & y will not be very meaningful though the units will still be the grid’s xy units for relative purposes

x_section_points(axis, ref_slice0=0, plus_face=False, masked=False)

Deprecated: please use unsplit_x_section_points instead.

xy_units()

Returns the projected view (x, y) units of measure of the coordinate reference system for the grid.

xyz_box(points_root=None, lazy=True, local=False)

Returns the minimum and maximum xyz for the grid geometry.

Parameters

• points_root (ignored) – for compatibility with Grid method signature

• lazy (ignored) – for compatibility with Grid method signature

• local (boolean, default False) – if True, the xyz ranges that are returned are in the local coordinate space, otherwise the global (crs parent) coordinate space

Returns

numpy array of float of shape (2, 3); the first axis is minimum, maximum; the second axis is x, y, z

xyz_box_centre(points_root=None, lazy=False, local=False)

Returns the (x,y,z) point (as 3 element numpy) at the centre of the xyz box for the grid.

Parameters

• points_root (optional) – if not None, the xml root node for the points data (speed optimization)

• lazy (boolean, default True) – if True, only the 8 outermost logical corners of the grid are used to determine the ranges of xyz and hence the centre; if False, all the points in the entire grid are scanned to determine the xyz ranges in an exhaustive manner

• local (boolean, default False) – if True, the xyz values that are returned are in the local coordinate space, otherwise the global (crs parent) coordinate space

Returns

numpy array of float of shape (3,) being the x, y, z coordinates of the centre of the grid

Note

the centre point returned is simply the midpoint of the x, y & z ranges of the grid

z_corner_point_depths(order='cellular')

Returns the z (depth) values of each corner of each cell.

Parameters

order (string, default 'cellular') – either ‘cellular’ or ‘linear’; if ‘cellular’ the resulting array has shape (nk, nj, ni, 2, 2, 2); if ‘linear’, the shape is (nk, 2, nj, 2, ni, 2)

Returns

numpy array of shape (nk, nj, ni, 2, 2, 2) or (nk, 2, nj, 2, ni, 2); for the cellular ordering, the result can be indexed with [k, j, i, kp, jp, ip] (where kp, for example, is 0 for the K- face and 1 for K+); for the linear ordering, the equivalent indexing is [k, kp, j, jp, i, ip], as used by some common simulator keyword formats

z_inc_down()

Return True if z increases downwards in the coordinate reference system used by the grid geometry

z_units()

Returns the vertical (z) units of measure of the coordinate reference system for the grid.

title

Citation title

originator

Creator of object. By default, user id.

uuid

Unique identifier