resqpy.unstructured.UnstructuredGrid¶
- class resqpy.unstructured.UnstructuredGrid(parent_model, uuid=None, find_properties=True, geometry_required=True, cache_geometry=False, cell_shape='polyhedral', title=None, originator=None, extra_metadata={})¶
Bases:
BaseResqpy
Class for RESQML Unstructured Grid objects.
Public Data Attributes:
resqml_type
Inherited from
BaseResqpy
resqml_type
Standard part name corresponding to self.uuid.
XML node corresponding to self.uuid.
Citation block title equivalent to self.title.
Commonly Used Methods:
__init__
(parent_model[, uuid, ...])Create an Unstructured Grid object and optionally populate from xml tree.
Loads from hdf5 into memory all the arrays defining the grid geometry.
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:
Set the number of cells in the grid.
Returns the number of cells deemed to be active for flow simulation purposes.
Returns uuid for coordinate reference system, as stored in geometry xml tree.
Returns boolean numpy array indicating which cells are inactive, if (in)active property found for this grid.
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.
Returns a numpy int vector listing the indices of faces which are only used by one cell.
Returns a numpy int vector listing the indices of faces which are used by exactly one of 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.
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.
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.
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.
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.
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)Returns the volume of a single cell.
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, ...])Create an Unstructured Grid object and optionally populate from xml tree.
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, geometry_required=True, cache_geometry=False, cell_shape='polyhedral', title=None, originator=None, extra_metadata={})[source]¶
Create an Unstructured Grid object and optionally populate from xml tree.
- 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
geometry_required (boolean, default True) – if True and no geometry node exists in the xml, an assertion error is raised; ignored if uuid is None
cache_geometry (boolean, default False) – if True and uuid is present, all the geometry arrays are loaded into attributes of the new grid object
cell_shape (str, optional) – one of ‘polyhedral’, ‘tetrahedral’, ‘pyramidal’, ‘prism’, ‘hexahedral’; ignored if uuid is present
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 Unstructured Grid object
Notes
if not instantiating from an existing RESQML object, then pass a cell_shape here (if geometry is going to be used), then set the cell count and, for geometry, build the points array and other arrays before writing to the hdf5 file and creating the xml; hinge node faces and subnode topology not yet supported at all; setting cache_geometry True is equivalent to calling the cache_all_geometry_arrays() method
- active_cell_count()[source]¶
Returns the number of cells deemed to be active for flow simulation purposes.
- adjusted_volume(v, required_uom=None)[source]¶
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)[source]¶
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()[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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
- 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={})[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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()[source]¶
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)[source]¶
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()[source]¶
Returns uuid for coordinate reference system, as stored in geometry xml tree.
- Returns
uuid.UUID object
- extract_inactive_mask()[source]¶
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()[source]¶
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.
- 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 location of the centre point of the face
Note
this returns a nominal centre point for a face - the mean position of its nodes - which is not generally its barycentre
- face_indices_and_handedness_for_cell(cell)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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
- internal_face_indices_for_masked_cells(exclude_cell_mask)[source]¶
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)[source]¶
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
- node_indices_for_face(face_index)[source]¶
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)[source]¶
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()[source]¶
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)[source]¶
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)[source]¶
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)[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 cell; units of measure is implied by crs units
Note
this is a computationally expensive method
- write_hdf5(file=None, geometry=True, imported_properties=None, write_active=None)[source]¶
Write to an hdf5 file the datasets for the grid geometry and optionally properties from cached arrays.
- xy_units()[source]¶
Returns the projected view (x, y) units of measure of the coordinate reference system for the grid.
- xyz_box()[source]¶
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()[source]¶
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