resqpy.fault.GridConnectionSet

class resqpy.fault.GridConnectionSet(parent_model, uuid=None, cache_arrays=False, find_properties=True, grid=None, ascii_load_format=None, ascii_file=None, k_faces=None, j_faces=None, i_faces=None, k_sides=None, j_sides=None, i_sides=None, feature_name=None, feature_type='fault', create_organizing_objects_where_needed=False, create_transmissibility_multiplier_property=True, fault_tmult_dict=None, title=None, originator=None, extra_metadata=None)

Bases: BaseResqpy

Class for obj_GridConnectionSetRepresentation holding pairs of connected faces, usually for faults.

Public Data Attributes:

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:

__init__(parent_model[, uuid, cache_arrays, ...])	Initializes a new GridConnectionSet.
single_feature([feature_index, feature_name])	Returns a new GridConnectionSet object containing the single feature copied from this set.
cache_arrays()	Checks that the connection set array data is loaded and loads from hdf5 if not.
number_of_grids()	Returns the number of grids involved in the connection set.
number_of_features()	Returns the number of features (faults) in the connection set.
list_of_feature_names([strip])	Returns a list of the feature (fault) names for which the connection set has cell face data.
write_hdf5([file_name, mode])	Create or append to an hdf5 file, writing datasets for the connection set after caching arrays.
create_xml([ext_uuid, add_as_part, ...])	Creates a Grid Connection Set (fault faces) xml node.

Methods:

from_gcs_uuid_list(parent_model, ...[, ...])	Create a GridConnectionSet by merging some existing grid connections sets.
extract_property_collection()	Prepares the property collection for this grid connection set.
set_pairs_from_kelp(kelp_0, kelp_1, ...[, ...])	Set cell_index_pairs and face_index_pairs based on j and i face kelp strands.
set_pairs_from_face_masks(k_faces, j_faces, ...)	Sets cell_index_pairs and face_index_pairs based on triple face masks, using simple no throw pairing.
set_pairs_from_faces_df(faces[, ...])	Sets cell_index_pairs and face_index_pairs based on pandas dataframe, using simple no throw pairing.
write_hdf5_and_create_xml_for_new_properties()	Wites any new property arrays to hdf5, creates xml for the properties and adds them to model.
append(other)	Adds the features in other grid connection set to this one.
filtered_by_layer_range([min_k0, max_k0, ...])	Returns a new GridConnectionSet, being a copy with cell faces whittled down to a layer range.
filtered_by_cell_mask(mask[, ...])	Returns a new GridConnectionSet, being a copy with cell faces whittled down by a boolean mask array.
clean_feature_list()	Removes any features that have no associated connections.
grid_for_index(grid_index)	Returns the grid object for the given grid_index.
list_of_fault_names([strip])	Returns a list of the fault names for which the connection set has cell face data.
feature_index_and_uuid_for_fault_name(fault_name)	Returns the index into the feature (fault) list for the named fault.
feature_name_for_feature_index(feature_index)	Returns the fault name corresponding to the given index into the feature (fault) list.
fault_name_for_feature_index(feature_index)	Returns the fault name corresponding to the given index into the feature (fault) list.
feature_index_for_cell_face(cell_kji0, axis, p01)	Returns the index into the feature (fault) list for the given face of the given cell, or None.
indices_for_feature_index(feature_index)	Returns numpy list of indices into main arrays for elements for the specified feature.
raw_list_of_cell_face_pairs_for_feature_index(...)	Returns list of cell face pairs contributing to feature (fault) with given index, in raw form.
inherit_properties_for_selected_indices(...)	Adds to imported property list by sampling the properties for another grid connection set.
list_of_cell_face_pairs_for_feature_index([...])	Returns list of cell face pairs contributing to feature (fault) with given index.
simplified_sets_of_kelp_for_feature_index(...)	Returns a pair of sets of column indices, one for J+ faces, one for I+ faces, contributing to feature.
rework_face_pairs()	Overwrites the in-memory array of face pairs to reflect neighbouring I or J columns.
write_simulator(filename[, mode, simulator, ...])	Creates a Nexus include file holding MULT keywords and data.
get_column_edge_list_for_feature(feature[, ...])	Extracts a list of cell faces for a given feature index, over a given range of layers in the grid.
get_column_edge_bool_array_for_feature(feature)	Generate a boolean aray defining which column edges are present for a given feature and k-layer range.
get_property_by_feature_index_list([...])	Returns a list of property values by feature based on extra metadata items.
get_column_edge_float_array_for_feature(...)	Generate a float value aray defining the property values for different column edges present for a given feature.
get_combined_fault_mask_index_value_arrays([...])	Generate combined mask, index and value arrays for all column edges across a k-layer range, for a defined feature_list.
tr_property_array([fa, tol_fa, tol_half_t, ...])	Return a transmissibility array with one value per pair in the connection set.
inherit_features(featured)	Inherit features from another connection set, reassigning feature indices for matching faces.
compact_indices()	Returns numpy int array of shape (count, 2) combining each cell index, face index into a single integer.
surface([feature_index])	Returns a Surface object representing the faces of the feature, for an unsplit grid.
face_surface_normal_vectors(...[, ...])	Returns an array of the surface normal vectors corresponding to each GCS face.
grid_face_arrays(property_uuid[, ...])	Creates a triplet of grid face numpy arrays populated from a property for this gcs.

Inherited from BaseResqpy

__init__(parent_model[, uuid, cache_arrays, ...])	Initializes a new GridConnectionSet.
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 a Grid Connection Set (fault faces) xml node.
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, cache_arrays=False, find_properties=True, grid=None, ascii_load_format=None, ascii_file=None, k_faces=None, j_faces=None, i_faces=None, k_sides=None, j_sides=None, i_sides=None, feature_name=None, feature_type='fault', create_organizing_objects_where_needed=False, create_transmissibility_multiplier_property=True, fault_tmult_dict=None, title=None, originator=None, extra_metadata=None)

Initializes a new GridConnectionSet.

Optionally loads it from xml or a list of simulator format ascii files.

Parameters

• parent_model (model.Model object) – the resqml model that this grid connection set will be part of

• uuid (uuid.UUID, optional) – the uuid of an existing RESQML GridConnectionSetRepresentation from which this resqpy object is populated

• find_properties (boolean, default True) – if True and uuid is present, the property collection relating to the grid connection set is prepared

• grid (grid.Grid object, optional) – If present, the grid object that this connection set relates to; if absent, the main grid for the parent model is assumed; only used if uuid is None; see also notes

• ascii_load_format (string, optional) – If present, must be ‘nexus’; ignored if loading from xml; otherwise required if ascii_file is present

• ascii_file (string, optional) – the full path of an ascii file holding fault definition data in nexus keyword format; ignored if loading from xml; otherwise, if present, ascii_load_format must also be set

• k_faces (boolean arrays, optional) – if present, these arrays are used to identify which faces between logically neighbouring cells to include in the new grid connection set

• j_faces (boolean arrays, optional) – if present, these arrays are used to identify which faces between logically neighbouring cells to include in the new grid connection set

• i_faces (boolean arrays, optional) – if present, these arrays are used to identify which faces between logically neighbouring cells to include in the new grid connection set

• k_sides (boolean arrays, optional) – if present, and k_faces etc are present, these arrays are used to determine which side of the cell face should appear as the first in the pairing

• j_sides (boolean arrays, optional) – if present, and k_faces etc are present, these arrays are used to determine which side of the cell face should appear as the first in the pairing

• i_sides (boolean arrays, optional) – if present, and k_faces etc are present, these arrays are used to determine which side of the cell face should appear as the first in the pairing

• feature_name (string, optional) – the feature name to use when setting from faces

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

• create_organizing_objects_where_needed (boolean, default False) – if True when loading from ascii or face masks, a fault interpretation object and tectonic boundary feature object will be created for any named fault for which such objects do not exist; if False, missing organizational objects will cause an error to be logged; ignored when loading from xml

• create_transmissibility_multiplier_property (boolean, default True) – if True when loading from ascii, a transmissibility multiplier property is created for the connection set

• str (fault_tmult_dict (dict of) – float): optional dictionary mapping fault name to a transmissibility multiplier; only used if initialising from ascii and creating a multiplier property

• title (str, optional) – the citation title to use for a new grid connection set; ignored if uuid is not None

• originator (str, optional) – the name of the person creating the new grid connection set, defaults to login id; ignored if uuid is not None

• extra_metadata (dict, optional) – string key, value pairs to add as extra metadata for the grid connection set ignored if uuid is not None

Returns

a new GridConnectionSet object, initialised from xml or ascii file, or left empty

Notes

in the resqml standard, a grid connection set can be used to identify connections between different grids (eg. parent grid to LGR); however, many of the methods in this code currently only handle connections within a single grid; when loading from an ascii file, cell faces are paired on a simplistic logical neighbour basis (as if there is no throw on the fault); this is because the simulator input does not include the full juxtaposition information; the simple mode is adequate for identifying which faces are involved in a fault but not for matters of juxtaposition or absolute transmissibility calculations; if uuid is None and ascii_file is None and k_faces, j_faces & i_faces are None, then an empty connection set is returned; if a transmissibility multiplier property is generated, it will only appear in the property collection for the grid connection set after the create_xml() method has been called

append(other)

Adds the features in other grid connection set to this one.

Parameters

other (GridConnectionSet) – the other grid connection set which will have its contents appended to this grid connection set

Notes

the other grid connection set must relate to the same grid as this (and both must be for a single grid); this method assigns a new uuid to the grid connection set and should only be used when constructing the gcs; no attempt is made to combine properties for the grid connection sets and no check is made for properties; the other gcs may belong to a different model than this gcs, however both must have a parent model set; use the higher level class method from_gcs_uuid_list() instead if property merging is required

append_extra_metadata(meta_dict)

Append a given dictionary of metadata to the existing metadata.

cache_arrays()

Checks that the connection set array data is loaded and loads from hdf5 if not.

property citation_title

Citation block title equivalent to self.title.

clean_feature_list()

Removes any features that have no associated connections.

compact_indices()

Returns numpy int array of shape (count, 2) combining each cell index, face index into a single integer.

create_xml(ext_uuid=None, add_as_part=True, add_relationships=True, write_new_properties=True, title=None, originator=None, extra_metadata=None)

Creates a Grid Connection Set (fault faces) xml node.

Optionally adds to parts forest.

extract_property_collection()

Prepares the property collection for this grid connection set.

face_surface_normal_vectors(triangle_per_face: ndarray, surface_normal_vectors: ndarray, add_as_property: bool = False, uom: str = 'm') → ndarray

Returns an array of the surface normal vectors corresponding to each GCS face.

Parameters

• triangle_per_face (np.ndarray) – an array of the surface triangle index corresponding to each face.

• surface_normal_vectors (np.ndarray) – an array of the normal vectors for each triangle in the surface.

• add_as_property (bool) – if True, face_surface_normal_vectors_array is added as a property to the model.

• uom (str) – the unit of measure of the normal vectors. It is used if add_as_property is True.

Returns

face_surface_normal_vectors_array (np.ndarray) – the surface normal vectors corresponding to each GCS face.

Note

returned vectors are sampled from the normal vectors for the surface triangles, which are true normals, accounting for any difference between xy & z units for the surface crs

fault_name_for_feature_index(feature_index, strip=True)

Returns the fault name corresponding to the given index into the feature (fault) list.

feature_index_and_uuid_for_fault_name(fault_name)

Returns the index into the feature (fault) list for the named fault.

Parameters

fault_name (string) – the name of the fault of interest

Returns

(index, uuid) where index is an integer which can be used to index the feature_list and is compatible

with the elements of feature_indices (connection interpretations elements in xml); uuid is the uuid.UUID of the feature interpretation for the fault; (None, None) is returned if the named fault is not found in the feature list

feature_index_for_cell_face(cell_kji0, axis, p01)

Returns the index into the feature (fault) list for the given face of the given cell, or None.

Note

where the cell face appears in more than one feature, the result will arbitrarily be the first occurrence in the cell_index_pair ordering of the grid connection set

feature_name_for_feature_index(feature_index, strip=True)

Returns the fault name corresponding to the given index into the feature (fault) list.

Parameters

• feature_index (non-negative integer) – the index into the ordered feature list (fault interpretation list)

• strip (boolean, default True) – if True, the citation title for the feature interpretation is split and the first word is returned (stripped of leading and trailing whitespace); if False, the citation title is returned unaltered

Returns

string being the citation title of the indexed fault interpretation part, optionally stripped down to the first word; by convention this is the name of the fault

filtered_by_cell_mask(mask, both_cells_required=True, pare_down=True, return_indices=False)

Returns a new GridConnectionSet, being a copy with cell faces whittled down by a boolean mask array.

Parameters

• mask (numpy bool array of shape grid.extent_kji) – connections will be kept for cells where this mask is True

• both_cells_required (bool, default True) – if True, both cells involved in a connection must have a mask value of True to be included; if False, any connection where either cell has a True mask value will be included

• pare_down (bool, default True) – if True, any unused features in the new grid connection set will be removed and the feature indices adjusted appropriately; if False, unused features will be left in the list for the new connection set, meaning that the feature indices will be compatible with those for self

• return_indices (bool, default False) – if True, a numpy list of the selected indices is also returned (see notes)

Returns

a new GridConnectionSet or (GridConnectionSet, numpy int array of shape (N,)) depending on return_indices argument, where the array is a list of selected indices (see notes)

Note

currently only works for single grid connection sets; if return_indices is True, a second item is returned which is a 1D numpy int array holding the indices of cell face pairs that have been selected from the original grid connection set; these values can be used to select equivalent entries from associated properties

filtered_by_layer_range(min_k0=None, max_k0=None, pare_down=True, return_indices=False)

Returns a new GridConnectionSet, being a copy with cell faces whittled down to a layer range.

Parameters

• min_k0 (int, optional) – if present, the minimum layer number to be included (zero based)

• max_k0 (int, optional) – if present, the maximum layer number to be included (zero based)

• pare_down (bool, default True) – if True, any unused features in the new grid connection set will be removed and the feature indices adjusted appropriately; if False, unused features will be left in the list for the new connection set, meaning that the feature indices will be compatible with those for self

• return_indices (bool, default False) – if True, a numpy list of the selected indices is also returned (see notes)

Returns

a new GridConnectionSet or (GridConnectionSet, numpy int array of shape (N,)) depending on return_indices argument, where the array is a list of selected indices (see notes)

Notes

cells in layer max_k0 are included in the filtered set (not pythonesque); currently only works for single grid connection sets; if return_indices is True, a second item is returned which is a 1D numpy int array holding the indices of cell face pairs that have been selected from the original grid connection set; these values can be used to select equivalent entries from associated properties

classmethod from_gcs_uuid_list(parent_model, source_model, gcs_uuid_list, title, gcs_property_uuid_list_of_lists=None)

Create a GridConnectionSet by merging some existing grid connections sets.

Parameters

• parent_model (Model) – the model to host the new, merged GridConnectionSet

• source_model (Model) – the model containing the existing grid connection sets (and properties)

• gcs_uuid_list (list of UUID) – a list or tuple of the existing GridConnectionSet uuids to be merged

• title (str) – the citation title for the new grid connection set

• gcs_property_uuid_list_of_lists (set of lists of UUID, optional) – a list or set or tuple where each entry is a list or tuple of uuids of similar properties with one property per gcs in gcs_uuid_list; see notes

Returns

the new GridConnectionSet being a merged copy of those specified in the list of uuids; the hdf5 data is written by the method, and the xml created and part(s) added

Notes

source_model may be the same as parent_model; each source grid connection set must be for a single grid and that must be common to them all; if the target model is different from the source model, the grid must have been copied to the target model before calling this function, and must have the same uuid as in the source model; if properties are being processed, each group of properties to be merged into a single property must be presented in the same order as the gcs’es and must have the corresponding gcs as the supporting representation; the indexable element must be faces and within a group of properties, the property kind, uom, time index, points attributes must match, as must the time series and string lookup uuids; property count attribute can only be 1 and time series must be None; each merged property citation title is inherited from that for the first gcs in the ordered list

get_column_edge_bool_array_for_feature(feature, gridindex=0, min_k=0, max_k=0)

Generate a boolean aray defining which column edges are present for a given feature and k-layer range.

Parameters

• index (feature - feature) –

• gridlist (gridindex - index of grid to be used in grid connection set) –

• 0 (default) –

• layer (max_k - maximum k) –

• layer –

Returns

boolean fault_by_column_edge_mask array (shape nj,ni,2,2)

note: the indices for the final two axes define the edges:

the first defines j or i (0 or 1) the second negative or positive face (0 or 1)

so [[True,False],[False,True]] indicates the -j and +i edges of the column are present

get_column_edge_float_array_for_feature(feature, fault_by_column_edge_mask, property_name='Transmissibility multiplier', gridindex=0, ref_k=None)

Generate a float value aray defining the property values for different column edges present for a given feature.

Parameters

• index (feature - feature) –

• present (fault_by_column_edge_mask - fault_by_column_edge_mask with True on edges where feature is) –

• property (property_name - name of) – lowercase version is also used as property kind when searching for a property array

• metadata; (should be present within the FaultInterpreation feature) – lowercase version is also used as property kind when searching for a property array

• required (gridindex - index of grid for which column edge data is) –

• feature; (ref_k - reference k_layer to use where property has variable value for a) – if None, no property array will be used and None will be returned for variable properties

Returns

float property_value_by_column_edge array (shape nj,ni,2,2) based on extra metadata

note: the indices for the final two axes define the edges:

the first defines j or i (0 or 1) the second negative or positive face (0 or 1)

so [[1,np.nan],[np.nan,np.nan]] indicates the -j edge of the column are present with a value of 1

this method preferentially uses a constant extra metadata item for the feature, with the property collection being used when the extra metadata is absent

get_column_edge_list_for_feature(feature, gridindex=0, min_k=0, max_k=0)

Extracts a list of cell faces for a given feature index, over a given range of layers in the grid.

Parameters

• index (feature - feature) –

• gridlist (gridindex - index of grid to be used in grid connection set) –

• 0 (default) –

• layer (max_k - maximum k) –

• 0 –

• layer –

• 0 –

Returns

list of cell faces for the feature (j_col, i_col, face_axis, face_polarity)

get_combined_fault_mask_index_value_arrays(gridindex=0, min_k=0, max_k=0, property_name='Transmissibility multiplier', feature_list=None, ref_k=None)

Generate combined mask, index and value arrays for all column edges across a k-layer range, for a defined feature_list.

Parameters

• gridlist (gridindex - index of grid to be used in grid connection set) –

• 0 (default) –

• k_layer (max_k - maximum) –

• k_layer –

• property (property_name - name of) – lowercase version is used as property kind when searching for a property array

• metadata; (should be present within the FaultInterpreation feature) – lowercase version is used as property kind when searching for a property array

• for (feature_list - list of feature index numbers to run) –

• features (default to all) –

• feature; (ref_k - reference k_layer to use where property has variable value for a) – if None defaults to min_k

Returns

bool array mask showing all column edges within features (shape nj,ni,2,2) int array showing the feature index for all column edges within features (shape nj,ni,2,2) float array showing the property value for all column edges within features (shape nj,ni,2,2)

get_property_by_feature_index_list(feature_index_list=None, property_name='Transmissibility multiplier')

Returns a list of property values by feature based on extra metadata items.

Parameters

• feature_index_list (list of int, optional) – if present, the feature indices for which property values will be included in the resulting list; if None, values will be included for each feature in the feature_list for this connection set

• property_name (string, default 'Transmissibility multiplier') – the property name of interest, as used in the features’ extra metadata as a key (this not a property collection citation title)

Returns

list of float being the list of property values for the list of features, in corresponding order

Notes

this method does not refer to property collection arrays, it simply looks for a constant extra metadata item for each feature; where no such item is found, a NaN is added to the return list; currently assumes fault interpretation (not horizon or geobody boundary)

grid_face_arrays(property_uuid, default_value=None, feature_index=None, active_only=True, lazy=False, baffle_uuid=None)

Creates a triplet of grid face numpy arrays populated from a property for this gcs.

Parameters

• property_uuid (UUID) – the uuid of the gcs property

• default_value (float or int, optional) – the value to use in the grid property on faces that do not appear in the grid connection set; will default to np.NaN for continuous properties, -1 for categorical or discrete

• feature_index (int, optional) – if present, only faces for this feature are used

• active_only (bool, default True) – if True and an active property exists for the grid connection set, then only active faces are used when populating the grid face arrays

• lazy (bool, default False) – if True, only the first cell & face of a pair is used when setting values in the arrays; if False, both left and right are used

• baffle_uuid (uuid, optional) – if present, the uuid of a discrete (bool) property of the gcs holding baffle flags; where True the output face value is set to zero regardless of the main property value

Returns

triple numpy arrays –

identifying the K, J & I direction grid face property values;

shapes are (nk + 1, nj, ni), (nk, nj + 1, ni), (nk, nj, ni + 1) respectively

Notes

can only be used on single grid gcs; gcs property must have indexable of faces; at present generates grid properties with indexable ‘faces’ not ‘faces per cell’, which might not be appropriate for grids with split pillars (structural faults); points properties not currently supported; count must be 1

grid_for_index(grid_index)

Returns the grid object for the given grid_index.

indices_for_feature_index(feature_index)

Returns numpy list of indices into main arrays for elements for the specified feature.

inherit_features(featured)

Inherit features from another connection set, reassigning feature indices for matching faces.

Parameters

featured (GridConnectionSet) – the other connection set which holds features to be inherited

Notes

the list of cell face pairs in this set remains unchanged; the corresponding feature indices are updated based on individual cell faces that are found in the featured connection set; the feature list is extended with inherited features as required; this method is typically used to populate a fault connection set built from grid geometry with named fault features from a simplistic connection set, thus combining full geometric juxtaposition information with named features; currently restricted to single grid connection sets

inherit_properties_for_selected_indices(other, selected_indices)

Adds to imported property list by sampling the properties for another grid connection set.

Parameters

• other (GridConnectionSet) – the source grid connection set whose properties will be sampled

• selected_indices (1D numpy int array) – the indices, into the main arrays of other, of the cell face pairs for which data is to be inherited

Notes

this method is typically called after creating a subset grid connection set using methods such as: filtered_by_layer_range(), filtered_by_cell_mask() or single_feature(); for the first two of those, set the return_indices argument True to acquire the array to pass as selected_indices here; when working with a single_feature() connection set, the indices can be acquired by calling indices_for_feature_index() for the source connection set; this method only adds the inherited property data to the imported list of the property collection for this grid connection set (self); it does not write the data to hdf5 or create the xml; those actions will happen when calling create_xml() with the write_new_properties argument set True; they can also be triggered by calling the write_hdf5_and_create_xml_for_new_properties() method directly; the property collection for the other grid connection set must be established before calling this method, for example by setting find_properties to True when instantiating other

list_of_cell_face_pairs_for_feature_index(feature_index=None)

Returns list of cell face pairs contributing to feature (fault) with given index.

Parameters

feature_index (non-negative integer, optional) – the index into the ordered feature list (fault interpretation list); if None, all cell face pairs are returned

Returns

(cell_index_pairs, face_index_pairs) or (cell_index_pairs, face_index_pairs, grid_index_pairs) where cell_index_pairs is a numpy int array of shape (N, 2, 3) being the paired kji0 cell indices; and face_index_pairs is a numpy int array of shape (N, 2, 2) being the paired face indices with the final axis of extent 2 indexed by 0 to give the facial axis (0 = K, 1 = J, 2 = I), and indexed by 1 to give the facial polarity (0 = minus face, 1 = plus face); and grid_index_pairs is a numpy int array of shape (N, 2) the values of which can be used to index the grid_list attribute to access relevant Grid objects; if the connection set is for a single grid, the return value is a pair; otherwise a triplet

list_of_fault_names(strip=True)

Returns a list of the fault names for which the connection set has cell face data.

list_of_feature_names(strip=True)

Returns a list of the feature (fault) names for which the connection set has cell face data.

number_of_features()

Returns the number of features (faults) in the connection set.

number_of_grids()

Returns the number of grids involved in the connection set.

property part

Standard part name corresponding to self.uuid.

raw_list_of_cell_face_pairs_for_feature_index(feature_index)

Returns list of cell face pairs contributing to feature (fault) with given index, in raw form.

Parameters

feature_index (non-negative integer) – the index into the ordered feature list (fault interpretation list)

Returns

(cell_index_pairs, face_index_pairs) or (cell_index_pairs, face_index_pairs, grid_index_pairs) where each is an integer numpy array of shape (N, 2); if the connection set is for a single grid, the returned value is a pair, otherwise a triplet; the returned data is in raw form: normalized cell indices (for flattened array) and face indices in range 0..5; grid indices can be used to index the grid_list attribute for relevant Grid object

rework_face_pairs()

Overwrites the in-memory array of face pairs to reflect neighbouring I or J columns.

Note

the indexing of faces within a cell is not clearly documented in the RESQML guides; the constant self.face_index_map and its inverse is the best guess at what this mapping is; this function overwrites the faces within cell data where a connected pair are in neighbouring I or J columns, using the face within cell values that fit with the neighbourly relationship; for some implausibly extreme gridding, this might not give the correct result

property root

XML node corresponding to self.uuid.

set_pairs_from_face_masks(k_faces, j_faces, i_faces, feature_name, create_organizing_objects_where_needed, feature_type='fault', k_sides=None, j_sides=None, i_sides=None)

Sets cell_index_pairs and face_index_pairs based on triple face masks, using simple no throw pairing.

set_pairs_from_faces_df(faces, create_organizing_objects_where_needed=False, create_mult_prop=True, fault_tmult_dict=None, one_based_indexing=True)

Sets cell_index_pairs and face_index_pairs based on pandas dataframe, using simple no throw pairing.

Parameters

• faces (pandas.DataFrame) – dataframe with columns ‘name’, ‘face’, ‘i1’, ‘i2’, ‘j1’, ‘j2’, ‘k1’, ‘k2’, ‘mult’

• create_organizing_objects_where_needed (bool, default False) – if True, interpretation and feature objects are created (including xml creation) where needed

• create_mult_prop (bool, default True) – if True, a transmissibility multiplier property is added to the collection for this grid connection set

• str (fault_tmult_dict (dict of) – float): optional dictionary mapping fault name to a transmissibility multiplier; if present, is combined with multiplier values from the dataframe

• one_based_indexing (bool, default True) – if True, the i, j & k values in the dataframe are taken to be in simulator protocol and 1 is subtracted to yield the RESQML cell indices

Notes

as a side effect, this method will set the cell indices in faces to be zero based; this method currently assumes fault interpretation (not horizon or geobody boundary)

set_pairs_from_kelp(kelp_0, kelp_1, feature_name, create_organizing_objects_where_needed, axis='K', feature_type='fault')

Set cell_index_pairs and face_index_pairs based on j and i face kelp strands.

Uses simple no throw pairing.

simplified_sets_of_kelp_for_feature_index(feature_index)

Returns a pair of sets of column indices, one for J+ faces, one for I+ faces, contributing to feature.

Parameters

feature_index (non-negative integer) – the index into the ordered feature list (fault interpretation list)

Returns

(set of numpy pair of integers, set of numpy pair of integers) the first set is those columns where the J+ faces are contributing to the connection (or the J- faces of the neighbouring column); the second set is where the the I+ faces are contributing to the connection (or the I- faces of the neighbouring column)

Notes

K faces are ignored; this is compatible with the resqml baffle functionality elsewhere

single_feature(feature_index=None, feature_name=None)

Returns a new GridConnectionSet object containing the single feature copied from this set.

Note

the single feature connection set is established in memory but this method does not write to the hdf5 nor create xml or add as a part to the model

surface(feature_index=None)

Returns a Surface object representing the faces of the feature, for an unsplit grid.

Note

this method does not write the hdf5 data nor create the xml for the surface

tr_property_array(fa=None, tol_fa=0.0001, tol_half_t=1e-05, apply_multipliers=False)

Return a transmissibility array with one value per pair in the connection set.

argument:

fa (numpy float array of shape (count, 2), optional): if present, the fractional area for each pair connection,

from perspective of each side of connection; if None, a fractional area of one is assumed

tol_fa (float, default 0.0001): fractional area tolerance – if the fractional area on either side of a

juxtaposition is less than this, then the corresponding transmissibility is set to zero

tol_half_t (float, default 1.0e-5): if the half cell transmissibility either side of a juxtaposition is

less than this, the corresponding transmissibility is set to zero; units are as for returned values (see notes)

apply_multipliers (boolean, default False): if True, a transmissibility multiplier array is fetched from the

property collection for the connection set, and failing that a multiplier for each feature is extracted from the feature extra metadata, and applied to the transmissibility calculation

Returns

numpy float array of shape (count,) being the absolute transmissibilities across the connected cell face pairs; see notes regarding units

Notes

implicit units of measure of returned values will be m3.cP/(kPa.d) if grids’ crs length units are metres, bbl.cP/(psi.d) if length units are feet; the computation is compatible with the Nexus NEWTRAN formulation; multiple grids are assumed to be in the same units and z units must be the same as xy units; this method does not add the transmissibility array as a property

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

write_hdf5(file_name=None, mode='a')

Create or append to an hdf5 file, writing datasets for the connection set after caching arrays.

write_hdf5_and_create_xml_for_new_properties()

Wites any new property arrays to hdf5, creates xml for the properties and adds them to model.

Note

this method is usually called by the create_xml() method for the grid connection set

write_simulator(filename, mode='w', simulator='nexus', include_both_sides=False, use_minus=False, trans_mult_uuid=None)

Creates a Nexus include file holding MULT keywords and data. trans_mult_uuid (optional) is the uuid of a property on the gcs containing transmissibility multiplier values. If not provided values of 1.0 will be used.

title

Citation title

originator

Creator of object. By default, user id.

uuid

Unique identifier