resqpy.unstructured.TetraGrid¶

class resqpy.unstructured.TetraGrid(parent_model, uuid=None, find_properties=True, cache_geometry=False, title=None, originator=None, extra_metadata={})¶

Bases: UnstructuredGrid

Class for unstructured grids where every cell is a tetrahedron.

Public Data Attributes:

Inherited from UnstructuredGrid

resqml_type

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:

Inherited from UnstructuredGrid

`__init__`(parent_model[, uuid, ...])	Creates a new resqpy TetraGrid object (RESQML UnstructuredGrid with cell shape tetrahedral)
`cache_all_geometry_arrays`()	Loads from hdf5 into memory all the arrays defining the grid geometry.
`points_ref`()	Returns an in-memory numpy array containing the xyz data for points used in the grid geometry.
`xyz_box`()	Returns the minimum and maximum xyz for the grid geometry.
`centre_point`([cell, cache_centre_array])	Returns centre point of a cell or array of centre points of all cells.
`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.
`write_hdf5`([file, geometry, ...])	Write to an hdf5 file the datasets for the grid geometry and optionally properties from cached arrays.
`create_xml`([ext_uuid, add_as_part, ...])	Creates an unstructured grid node and optionally adds as a part in the model.

Methods:

`__init__`(parent_model[, uuid, ...])	Creates a new resqpy TetraGrid object (RESQML UnstructuredGrid with cell shape tetrahedral)
`check_tetra`()	Checks that each cell has 4 faces and each face has 3 nodes.
`face_centre_point`(face_index)	Returns a nominal centre point for a single face calculated as the mean position of its nodes.
`volume`(cell[, required_uom])	Returns the volume of a single cell.
`grid_volume`()	Returns the sum of the volumes of all the cells in the grid.
`from_unstructured_cell`(u_grid, cell[, ...])	Instantiates a small TetraGrid representing a single cell from an UnstructuredGrid as a set of tetrahedra.

Inherited from UnstructuredGrid

`set_cell_count`(n)	Set the number of cells in the grid.
`active_cell_count`()	Returns the number of cells deemed to be active for flow simulation purposes.
`extract_crs_uuid`()	Returns uuid for coordinate reference system, as stored in geometry xml tree.
`extract_inactive_mask`()	Returns boolean numpy array indicating which cells are inactive, if (in)active property found for this grid.
`extract_property_collection`()	Load grid property collection object holding lists of all properties in model that relate to this grid.
`set_cells_per_face`([check_all_faces_used])	Sets and returns the cells_per_face array showing which cells are using each face.
`masked_cells_per_face`(exclude_cell_mask)	Sets and returns the cells_per_face array showing which cells are using each face.
`external_face_indices`()	Returns a numpy int vector listing the indices of faces which are only used by one cell.
`external_face_indices_for_masked_cells`(...)	Returns a numpy int vector listing the indices of faces which are used by exactly one of masked cells.
`internal_face_indices_for_masked_cells`(...)	Returns a numpy int vector listing the indices of faces which are used by two of masked cells.
`face_centre_point`(face_index)	Returns a nominal centre point for a single face calculated as the mean position of its nodes.
`face_count_for_cell`(cell)	Returns the number of faces for a particular cell.
`max_face_count_for_any_cell`()	Returns the largest number of faces in use by any one cell.
`node_count_for_face`(face_index)	Returns the number of nodes for a particular face.
`max_node_count_for_any_face`()	Returns the largest number of nodes in use by any one face.
`node_indices_for_face`(face_index)	Returns numpy list of node indices for a single face.
`distinct_node_indices_for_cell`(cell)	Returns a numpy list of distinct node indices used by the faces of a single cell.
`face_indices_for_cell`(cell)	Returns numpy list of face indices for a single cell.
`face_indices_and_handedness_for_cell`(cell)	Returns numpy list of face indices for a single cell, and numpy boolean list of face right handedness.
`edges_for_face`(face_index)	Returns numpy list of pairs of node indices, each pair being one edge of the face.
`edges_for_face_with_node_indices_ordered_within_pairs`(...)	Returns numpy list of pairs of node indices, each pair being one edge of the face.
`distinct_edges_for_cell`(cell)	Returns numpy list of pairs of node indices, each pair being one distinct edge of the cell.
`cell_face_centre_points`(cell)	Returns a numpy array of centre points of the faces for a single cell.
`face_normal`(face_index)	Returns a unit vector normal to a planar approximation of the face.
`planar_face_points`(face_index[, xy_plane])	Returns points for a planar approximation of a face.
`face_triangulation`(face_index[, local_nodes])	Returns a Delauney triangulation of (a planar approximation of) a face.
`area_of_face`(face_index[, in_plane])	Returns the area of a face.
`cell_centre_point`(cell)	Returns centre point of a single cell calculated as the mean position of the centre points of its faces.
`volume`(cell[, required_uom])	Returns the volume of a single cell.
`check_indices`()	Asserts that all node and face indices are within range.
`adjusted_volume`(v[, required_uom])	Returns volume adjusted for differing xy & z units in crs, and/or converted to required uom.

Inherited from BaseResqpy

`__init__`(parent_model[, uuid, ...])	Creates a new resqpy TetraGrid object (RESQML UnstructuredGrid with cell shape tetrahedral)
`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 an unstructured grid node and optionally adds as a part in the model.
`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, find_properties=True, cache_geometry=False, title=None, originator=None, extra_metadata={})[source]¶

Creates a new resqpy TetraGrid object (RESQML UnstructuredGrid with cell shape tetrahedral)

Parameters

parent_model (model.Model object) – the model which this grid is part of
uuid (uuid.UUID, optional) – if present, the new grid object is populated from the RESQML object
find_properties (boolean, default True) – if True and uuid is present, a grid property collection is instantiated as an attribute, holding properties for which this grid is the supporting representation
cache_geometry (boolean, default False) – if True and uuid is present, all the geometry arrays are loaded into attributes of the new grid object
title (str, optional) – citation title for new grid; ignored if uuid is present
originator (str, optional) – name of person creating the grid; defaults to login id; ignored if uuid is present
extra_metadata (dict, optional) – dictionary of extra metadata items to add to the grid; ignored if uuid is present

Returns

a newly created TetraGrid object

active_cell_count()¶: Returns the number of cells deemed to be active for flow simulation purposes.

adjusted_volume(v, required_uom=None)¶: Returns volume adjusted for differing xy & z units in crs, and/or converted to required uom.

Note

if required_uom is not specified, units of returned value will be cube of crs units if xy & z are the same and either ‘m’ or ‘ft’, otherwise ‘m3’ will be used

append_extra_metadata(meta_dict)¶: Append a given dictionary of metadata to the existing metadata.

area_of_face(face_index, in_plane=False)¶

Returns the area of a face.

Parameters

face_index (int) – the index of the face for which the area is required
in_plane (boolean, default False) – if True, the area returned is the area of the planar approximation of the face; if False, the area is the sum of the areas of the triangulation of the face, which need not be planar

Returns

float being the area of the face

Notes

units of measure of the area is implied by the units of the crs in use by the grid

cache_all_geometry_arrays()¶

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

Returns: None

Notes

call this method if much grid geometry processing is coming up; the arrays are cached as direct attributes to this grid object; the node and face indices make use of ‘jagged’ arrays (effectively an array of lists represented as a linear array and a ‘cumulative length’ index array)

cell_centre_point(cell)¶

Returns centre point of a single cell calculated as the mean position of the centre points of its faces.

Parameters: cell (int) – the index of the cell for which the centre point is required
Returns: numpy float array of shape (3,) being the xyz location of the centre point of the cell

Note

this is a nominal centre point - the mean of the nominal face centres - which is not generally the barycentre of the cell

cell_face_centre_points(cell)¶

Returns a numpy array of centre points of the faces for a single cell.

Parameters: cell (int) – the index of the cell for which face centre points are required
Returns: numpy array of shape (F, 3) being the xyz location of each of the F faces for the cell

Notes

the order of the returned face centre points matches the faces_per_cell for the cell; the returned values are nominal centre points for the faces - the mean position of their nodes - which are not generally their barycentres

centre_point(cell=None, cache_centre_array=False)¶

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

Optionally cache centre points for all cells.

Parameters

cell (optional) – if present, the cell number of the individual cell for which the centre point is required; zero based indexing
cache_centre_array (boolean, default False) – If True, or cell is None, an array of centre points is generated and added as an attribute of the grid, with attribute name array_centre_point

Returns

(x, y, z) 3 element numpy array of floats holding centre point of a single cell; or numpy 2D array of shape (cell_count, 3) if cell is None

Notes

a simple mean of the nominal centres of the faces is used to calculate the centre point of a cell; this is not generally the barycentre of the cell; resulting coordinates are in the same (local) crs as the grid points

check_indices()¶: Asserts that all node and face indices are within range.

check_tetra()[source]¶: Checks that each cell has 4 faces and each face has 3 nodes.

property citation_title¶: Citation block title equivalent to self.title.

create_xml(ext_uuid=None, add_as_part=True, add_relationships=True, title=None, originator=None, write_active=True, write_geometry=True, extra_metadata={})¶

Creates an unstructured grid node and optionally adds as a part in the model.

Parameters

ext_uuid (uuid.UUID, optional) – the uuid of the hdf5 external part holding the array data for the grid geometry
add_as_part (boolean, default True) – if True, the newly created xml node is added as a part in the model
add_relationships (boolean, default True) – if True, relationship xml parts are created relating the new grid part to: the crs, and the hdf5 external part
title (string) – used as the citation title text; careful consideration should be given to this argument when dealing with multiple grids in one model, as it is the means by which a human will distinguish them
originator (string, optional) – the name of the human being who created the unstructured grid part; default is to use the login name
write_active (boolean, default True) – if True, xml for an active cell property is also generated, but only if the active_property_uuid is set and no part exists in the model for that uuid
write_geometry (boolean, default True) – if False, the geometry node is omitted from the xml
extra_metadata (dict) – any key value pairs in this dictionary are added as extra metadata xml nodes

Returns

the newly created unstructured grid xml node

Notes

the write_active argument should generally be set to the same value as that passed to the write_hdf5… method; the RESQML standard allows the geometry to be omitted for a grid, controlled here by the write_geometry argument; the explicit geometry may be omitted for unstructured grids, in which case the arrays should not be written to the hdf5 file either

distinct_edges_for_cell(cell)¶

Returns numpy list of pairs of node indices, each pair being one distinct edge of the cell.

Parameters: cell (int) – the index of the cell
Returns: numpy int array of shape (E, 2) being the node indices identifying the E edges of the cell

Note

within each pair, the two node indices are ordered with the lower index first

distinct_node_indices_for_cell(cell)¶

Returns a numpy list of distinct node indices used by the faces of a single cell.

Parameters: cell (int) – the index of the cell for which distinct node indices are required
Returns: numpy int array of shape (N, ) being the indices of N distinct nodes used by the cell’s faces

Note

the returned array is sorted by increasing node index

edges_for_face(face_index)¶

Returns numpy list of pairs of node indices, each pair being one edge of the face.

Parameters: face_index (int) – the index of the face (as used in faces_per_cell and implicitly in nodes_per_face)
Returns: numpy int array of shape (N, 2) being the node indices identifying the N edges of the face

Notes

the order of the pairs follows the order of the nodes for the face; within each pair, the order of the two node indices also follows the order of the nodes for the face

edges_for_face_with_node_indices_ordered_within_pairs(face_index)¶

Returns numpy list of pairs of node indices, each pair being one edge of the face.

Parameters: face_index (int) – the index of the face (as used in faces_per_cell and implicitly in nodes_per_face)
Returns: numpy int array of shape (N, 2) being the node indices identifying the N edges of the face

Notes

the order of the pairs follows the order of the nodes for the face; within each pair, the two node indices are ordered with the lower index first

external_face_indices()¶: Returns a numpy int vector listing the indices of faces which are only used by one cell.

Note

resulting array is ordered by face index

external_face_indices_for_masked_cells(exclude_cell_mask)¶

Returns a numpy int vector listing the indices of faces which are used by exactly one of masked cells.

Parameters

exclude_cell_mask (numpy bool array of shape (cell_count,)) – cells with a value True in this array
result (are excluded when populating the) –

Note

resulting array is ordered by face index

extract_crs_uuid()¶

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

Returns: uuid.UUID object

extract_inactive_mask()¶

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

Returns: numpy array of booleans, of shape (cell_count,) 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_property_collection()¶

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

Returns: resqml_property.PropertyCollection 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

face_centre_point(face_index)[source]¶: Returns a nominal centre point for a single face calculated as the mean position of its nodes.

Note

this is a nominal centre point for a face and not generally its barycentre

face_count_for_cell(cell)¶: Returns the number of faces for a particular cell.

face_indices_and_handedness_for_cell(cell)¶

Returns numpy list of face indices for a single cell, and numpy boolean list of face right handedness.

Parameters: cell (int) – the index of the cell for which face indices are required
Returns: numpy int array of shape (F,), numpy boolean array of shape (F, ) – being the face indices of each of the F faces for the cell, and the right handedness (clockwise order) of the face nodes when viewed from within the cell

Note

the face indices are used when accessing the nodes per face data and can also be used to identify shared faces; the handedness (clockwise or anti-clockwise ordering of nodes) is significant for some processing of geometry such as volume calculations

face_indices_for_cell(cell)¶

Returns numpy list of face indices for a single cell.

Parameters: cell (int) – the index of the cell for which face indices are required
Returns: numpy int array of shape (F,) being the face indices of each of the F faces for the cell

Note

the face indices are used when accessing the nodes per face data and can also be used to identify shared faces

face_normal(face_index)¶

Returns a unit vector normal to a planar approximation of the face.

Parameters: face_index (int) – the index of the face (as used in faces_per_cell and implicitly in nodes_per_face)
Returns: numpy float array of shape (3,) being the xyz components of a unit length vector normal to the face

Note

in the case of a degenerate face, a zero length vector is returned; the direction of the normal will be into or out of the cell depending on the handedness of the cell face; the direction of the vector is a true normal, accounting for any difference in xy & z units

face_triangulation(face_index, local_nodes=False)¶

Returns a Delauney triangulation of (a planar approximation of) a face.

Parameters

face_index (int) – the index of the face for which a triangulation is required
local_nodes (boolean, default False) – if True, the returned node indices are local to the face nodes, ie. can index into node_indices_for_face(); if False, the returned node indices are the global node indices in use by the grid

Returns

numpy int array of shape (N - 2, 3) being the node indices of the triangulation, where N is the number of nodes defining the face

classmethod from_unstructured_cell(u_grid, cell, title=None, extra_metadata={}, set_handedness=False)[source]¶: Instantiates a small TetraGrid representing a single cell from an UnstructuredGrid as a set of tetrahedra.

grid_volume()[source]¶

Returns the sum of the volumes of all the cells in the grid.

Returns: float being the total volume of the grid; units of measure is implied by crs units

internal_face_indices_for_masked_cells(exclude_cell_mask)¶

Returns a numpy int vector listing the indices of faces which are used by two of masked cells.

Parameters

exclude_cell_mask (numpy bool array of shape (cell_count,)) – cells with a value True in this array
result (are excluded when populating the) –

Note

resulting array is ordered by face index

masked_cells_per_face(exclude_cell_mask)¶

Sets and returns the cells_per_face array showing which cells are using each face.

Parameters

exclude_cell_mask (numpy bool array of shape (cell_count,)) – cells with a value True in this array
result (are excluded when populating the) –

Returns

numpy int array of shape (face_count, 2) showing upto 2 cell indices for each face index; -1 is a null value; if only one cell uses a face, its index is always in position 0 of the second axis

Note

this method recomputes the result on every call - nothing extra is cached in the grid

max_face_count_for_any_cell()¶: Returns the largest number of faces in use by any one cell.

max_node_count_for_any_face()¶: Returns the largest number of nodes in use by any one face.

node_count_for_face(face_index)¶: Returns the number of nodes for a particular face.

node_indices_for_face(face_index)¶

Returns numpy list of node indices for a single face.

Parameters: face_index (int) – the index of the face (as used in faces_per_cell and implicitly in nodes_per_face)
Returns: numpy int array of shape (N,) being the node indices identifying the vertices of the face

Note

the node indices are used to index the points data (points_cached attribute); ordering of returned nodes is clockwise or anticlockwise when viewed from within the cell, as indicated by the entry in the cell_face_is_right_handed array

property part¶: Standard part name corresponding to self.uuid.

planar_face_points(face_index, xy_plane=False)¶

Returns points for a planar approximation of a face.

Parameters

face_index (int) – the index of the face for which a planar approximation is required
xy_plane (boolean, default False) – if True, the returned points lie in a horizontal plane with z = 0.0; if False, the plane is located approximately in the position of the original face, with the same normal direction

Returns

numpy float array of shape (N, 3) being the xyz points of the planar face nodes corresponding to the N nodes of the original face, in the same order

points_ref()¶

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

Returns: numpy array of shape (node_count, 3)

Notes

this is the usual way to get at the actual grid geometry points data in the native RESQML layout; the array is cached as an attribute of the grid object

property root¶: XML node corresponding to self.uuid.

set_cell_count(n: int)¶

Set the number of cells in the grid.

Parameters: n (int) – the number of cells in the unstructured grid

Note

only call this method when creating a new grid, not when working from an existing RESQML grid

set_cells_per_face(check_all_faces_used=True)¶

Sets and returns the cells_per_face array showing which cells are using each face.

Parameters: check_all_faces_used (boolean, default True) – if True, an assertion error is raised if there are any faces which do not appear in any cells
Returns: numpy int array of shape (face_count, 2) showing upto 2 cell indices for each face index; -1 is a null value; if only one cell uses a face, its index is always in position 0 of the second axis

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

volume(cell, required_uom=None)[source]¶

Returns the volume of a single cell.

Parameters: cell (int) – the index of the cell for which the volume is required
Returns: float being the volume of the tetrahedral cell

Note

if required_uom is not specified, returned units will be cube of crs units if xy & z are the same and either ‘m’ or ‘ft’, otherwise ‘m3’ will be used

write_hdf5(file=None, geometry=True, imported_properties=None, write_active=None)¶

Write to an hdf5 file the datasets for the grid geometry and optionally properties from cached arrays.

xy_units()¶

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

xyz_box()¶

Returns the minimum and maximum xyz for the grid geometry.

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

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