resqpy.grid_surface.find_faces_to_represent_surface_regular

resqpy.grid_surface.find_faces_to_represent_surface_regular(grid, surface, name, title=None, centres=None, agitate=False, random_agitation=False, feature_type='fault', progress_fn=None, consistent_side=False, return_properties=None)

Returns a grid connection set containing those cell faces which are deemed to represent the surface.

Parameters

  • grid (RegularGrid) – the grid for which to create a grid connection set representation of the surface

  • surface (Surface) – the surface to be intersected with the grid

  • name (str) – the feature name to use in the grid connection set

  • title (str, optional) – the citation title to use for the grid connection set; defaults to name

  • centres (numpy float array of shape (nk, nj, ni, 3), optional) – precomputed cell centre points in local grid space, to avoid possible crs issues; required if grid’s crs includes an origin (offset)?

  • agitate (bool, default False) – if True, the points of the surface are perturbed by a small offset, which can help if the surface has been built from a regular mesh with a periodic resonance with the grid

  • random_agitation (bool, default False) – if True, the agitation is by a small random distance; if False, a constant positive shift of 5.0e-6 is applied to x, y & z values; ignored if agitate is False

  • feature_type (str, default 'fault') – ‘fault’, ‘horizon’ or ‘geobody boundary’

  • (f(x (progress_fn) – float), optional): a callback function to be called at intervals by this function; the argument will progress from 0.0 to 1.0 in unspecified and uneven increments

  • consistent_side (bool, default False) – if True, the cell pairs will be ordered so that all the first cells in each pair are on one side of the surface, and all the second cells on the other

  • return_properties (list of str, optional) – if present, a list of property arrays to calculate and return as a dictionary; recognised values in the list are ‘offset’ and ‘normal vector’; offset is a measure of the distance between the centre of the cell face and the intersection point of the inter-cell centre vector with a triangle in the surface; normal vector is a unit vector normal to the surface triangle; each array has an entry for each face in the gcs; the returned dictionary has the passed strings as keys and numpy arrays as values

Returns

gcs or (gcs, dict) where gcs is a new GridConnectionSet with a single feature, not yet written to hdf5 nor xml created; dict is a dictionary mapping from property name to numpy array; ‘offset’ will map to a numpy float array of shape (gcs.count, ); ‘normal vector’ will map to a numpy float array of shape (gcs.count, 3) holding a unit vector normal to the surface for each of the faces in the gcs; the dict is only returned if a non-empty list has been passed as return_properties

Notes

use find_faces_to_represent_surface_regular_optimised() instead, for faster computation; this function can handle the surface and grid being in different coordinate reference systems, as long as the implicit parent crs is shared; no trimming of the surface is carried out here: for computational efficiency, it is recommended to trim first; organisational objects for the feature are created if needed; if grid has differing xy & z units, this is accounted for here when generating normal vectors, ie. true normal unit vectors are returned