resqpy.model.Model¶
- class resqpy.model.Model(epc_file: Optional[str] = None, full_load: bool = True, epc_subdir: Optional[Union[str, Iterable]] = None, new_epc: bool = False, create_basics: Optional[bool] = None, create_hdf5_ext: Optional[bool] = None, copy_from: Optional[str] = None, quiet=False)¶
Bases:
object
Class for RESQML (v2) based models.
Examples
To open an existing dataset:
Model(epc_file = 'filename.epc')
To create a new, empty model ready to populate:
Model(epc_file = 'new_file.epc', new_epc = True, create_basics = True, create_hdf5_ext = True)
Alternatively, use the module level convenience function:
new_model(epc_file = 'new_file.epc')
To copy an existing dataset then open the new copy:
Model(epc_file = 'new_file.epc', copy_from = 'existing.epc')
Public Data Attributes:
XML node corresponding to self.crs_uuid, the 'main' crs for the model.
Commonly Used Methods:
__init__
([epc_file, full_load, epc_subdir, ...])Create an empty model; load it from epc_file if given.
parts
([parts_list, obj_type, uuid, title, ...])Returns a list of parts matching all of the arguments passed.
part
([parts_list, obj_type, uuid, title, ...])Returns the name of a part matching all of the arguments passed.
uuids
([parts_list, obj_type, uuid, title, ...])Returns a list of uuids of parts matching all of the arguments passed.
uuid
([parts_list, obj_type, uuid, title, ...])Returns the uuid of a part matching all of the arguments passed.
roots
([parts_list, obj_type, uuid, title, ...])Returns a list of xml root nodes of parts matching all of the arguments passed.
root
([parts_list, obj_type, uuid, title, ...])Returns the xml root node of a part matching all of the arguments passed.
titles
([parts_list, obj_type, uuid, title, ...])Returns a list of citation titles of parts matching all of the arguments passed.
title
([parts_list, obj_type, uuid, title, ...])Returns the citation title of a part matching all of the arguments passed.
store_epc
([epc_file, main_xml_name, ...])Write xml parts of model to epc file (HDF5 arrays are not written here).
part_for_uuid
(uuid)Returns the part name which has the given uuid.
root_for_uuid
(uuid)Returns the xml root for the part which has the given uuid.
uuid_for_part
(part_name[, is_rels])Returns the uuid for the named part.
type_of_part
(part_name[, strip_obj])Returns content type for the named part (does not apply to rels parts).
type_of_uuid
(uuid[, strip_obj])Returns content type for the uuid.
root_for_part
(part_name[, is_rels])Returns root of parsed xml tree for the named part.
citation_title_for_part
(part)Returns the citation title for the specified part.
grid
([title, uuid, find_properties])Returns a shared Grid (or RegularGrid) object for this model, by default the 'main' grid.
Releases (closes) the currently open hdf5 file.
title_for_root
([root])Returns the Title text from the Citation within the given root node.
title_for_part
(part_name)Returns the Title text from the Citation for the given main part name (not for rels).
create_unknown
([root])Creates an Unknown node and optionally adds as child of root.
iter_objs
(cls)Iterate over all available objects of given resqpy class within the model.
Iterable of all WellboreInterpretations associated with the model.
Iterable of all trajectories associated with the model.
Iterable of all MdDatum objects associated with the model.
iter_crs
()Iterable of all CRS objects associated with the model.
as_graph
([uuids_subset])Return representation of model as nodes and edges, suitable for plotting in a graph.
Methods:
Set model contents to empty.
uuid_is_present
(uuid)Returns True if the uuid is present in the model's catalogue, False otherwise.
Marks the model as having been modified and assigns a new uuid.
Returns set of ints being uuids of objects related to uuid by any category of relationship.
Returns set of ints being uuids of objects which uuid has a reference to.
Returns set of ints being uuids of objects which have a reference to uuid.
Returns set of ints being uuids of objects related to uuid by only a soft relationship.
Checks that model has an xml tree; if not, an empty tree is created; not usually called directly.
load_part
(epc, part_name[, is_rels])Load and parse xml tree for given part name, storing info in parts forest (or rels forest).
set_epc_file_and_directory
(epc_file)Sets the full path and directory of the epc_file.
fell_part
(part_name)Removes the named part from the in-memory parts forest.
Removes the named part from the main (Content_Types) tree.
tidy_up_forests
([tidy_main_tree, ...])Removes any parts that do not have any related data in dictionaries.
load_epc
(epc_file[, full_load, epc_subdir, ...])Load xml parts of model from epc file (HDF5 arrays are not loaded).
parts_list_of_type
([type_of_interest, uuid])Returns a list of part names for parts of type of interest, optionally matching a uuid.
list_of_parts
([only_objects])Return a complete list of parts.
Retuns the number of parts in the model, including external parts such as the link to an hdf5 file.
parts_count_by_type
([type_of_interest])Returns a sorted list of (type, count) for parts.
Returns a dictionary mapping from RESQML object type to count of parts.
parts_list_filtered_by_related_uuid
(...[, ...])From a list of parts, returns a list of those parts which have a relationship with the given uuid.
Returns the uuid of the supporting representation for the part, if found, otherwise None.
From a list of parts, returns a list of those parts which have the given uuid as supporting representation.
parts_list_related_to_uuid_of_type
(uuid[, ...])Returns a list of parts of type of interest that relate to part with given uuid.
Returns a list of part names for external part references.
uuid_for_root
(root_node)Returns the uuid for an object given an xml root node.
tree_for_part
(part_name[, is_rels])Returns parsed xml tree for the named part.
change_hdf5_uuid_in_hdf5_references
(node, ...)Scan node for hdf5 references and set the uuid of the hdf5 file itself to new_uuid.
change_uuid_in_hdf5_references
(node, ...)Scan node for hdf5 references using the old_uuid and replace with the new_uuid.
Look for supporting representation reference using the old_uuid and replace with the new_uuid.
change_filename_in_hdf5_rels
([new_hdf5_filename])Scan relationships forest for hdf5 external parts and patch in a new filename.
copy_part
(existing_uuid, new_uuid[, ...])Makes a new part as a copy of an existing part with only a new uuid set; the new part can then be modified.
root_for_ijk_grid
([uuid, title])Return root for IJK Grid part.
source_for_part
(part)Returns the source string from the part's extra metadata, if present, else None.
set_source_for_part
(part, source)Sets the source string in the part's extra metadata.
source_for_obj
(obj)Returns the source string from the object's extra metadata, if present, else None.
set_source_for_obj
(obj, source)Sets the source string in the object's extra metadata.
root_for_time_series
([uuid])Return root for time series part.
resolve_grid_root
([grid_root, uuid])If grid root argument is None, returns the root for the IJK Grid part instead.
add_grid
(grid_object[, check_for_duplicates])Add grid object to list of shareable grids for this model.
Returns list of uuid's for the grid objects in the cached grid list.
Returns the cached grid object matching the given uuid, if found in the grid list, otherwise None.
resolve_time_series_root
([time_series_root])If time_series_root is None, finds the root for a time series in the model.
h5_set_default_override
(override)Sets the default hdf5 filename override mode for the model.
h5_uuid_and_path_for_node
(node[, tag])Returns a (hdf5_uuid, hdf5_internal_path) pair for an xml array node.
h5_uuid_list
(node)Returns a list of all uuids for hdf5 external part(s) referred to in recursive tree.
h5_uuid
()Returns the uuid of the 'main' hdf5 file.
h5_file_name
([uuid, override, file_must_exist])Returns full path for hdf5 file with given uuid.
h5_access
([uuid, mode, override, file_path])Returns an open h5 file handle for the hdf5 file with the given uuid.
h5_array_shape_and_type
(h5_key_pair)Returns the shape and dtype of the array, as stored in the hdf5 file.
h5_array_element
(h5_key_pair[, index, ...])Returns one element from an hdf5 array and/or caches the array.
h5_array_slice
(h5_key_pair, slice_tuple)Loads a slice of an hdf5 array.
h5_overwrite_array_slice
(h5_key_pair, ...)Overwrites (updates) a slice of an hdf5 array.
h5_overwrite_array
(h5_key_pair, array)Overwrites (updates) the whole of an hdf5 array.
Clears the cached filenames associated with all ext uuids.
Initialises an empty main xml tree for model.
add_part
(content_type, uuid, root[, ...])Adds a (recently created) node as a new part in the model's parts forest.
patch_root_for_part
(part, root)Updates the xml tree for the part without changing the uuid.
remove_part
(part_name[, ...])Removes a part from the parts forest; optionally remove corresponding rels part and other relationships.
new_obj_node
(flavour[, name_space, ...])Creates a new main object element and sets attributes (does not add children).
referenced_node
(ref_node[, consolidate])For a given xml reference node, returns the node for the object referred to, if present.
create_ref_node
(flavour, title, uuid[, ...])Create a reference node, optionally add to root.
uom_node
(root, uom)Add a generic unit of measure sub element to root.
Adds a relationships reference node as a new part in the model's parts forest.
create_citation
([root, title, originator])Creates a citation xml node and optionally appends as a child of root.
create_doc_props
([add_as_part, root, originator])Creates a document properties stub node and optionally adds as child of root and/or to parts forest.
create_crs_reference
([root, crs_uuid])Creates a node refering to an existing crs node and optionally adds as child of root.
create_md_datum_reference
(md_datum_root[, root])Creates a node refering to an existing measured depth datum and optionally adds as child of root.
create_hdf5_ext
([add_as_part, root, title, ...])Creates an hdf5 external node and optionally adds as child of root and/or to parts forest.
create_hdf5_dataset_ref
(hdf5_uuid, ...[, title])Creates a pair of nodes referencing an hdf5 dataset (array) and adds to root.
Craate a supporting representation reference node refering to an IjkGrid and optionally add to root.
create_source
(source[, root])Create an extra meta data node holding information on the source of the data, optionally add to root.
create_patch
(p_uuid[, ext_uuid, root, ...])Create a node for a patch of values, including ref to hdf5 data set, optionally add to root.
create_time_series_ref
(time_series_uuid[, root])Create a reference node to a time series, optionally add to root.
create_solitary_point3d
(flavour, root, xyz)Creates a subelement to root for a solitary point in 3D space.
create_reciprocal_relationship
(node_a, ...)Adds a node to each of a pair of trees in the rels forest, to represent a two-way relationship.
create_reciprocal_relationship_uuids
(uuid_a, ...)Adds a node to each of a pair of trees in the rels forest, to represent a two-way relationship.
duplicate_node
(existing_node[, add_as_part])Creates a deep copy of the xml node (typically from another model) and optionally adds as part.
Force immigrant object to be teated as equivalent to resident during consolidation.
force_consolidation_equivalence_for_class_ignoring_extra_metadata
(...)Force immigrant objects of type to be teated as equivalent where only extra metadata differs during consolidation.
remove_extra_metadata
(uuid)Removes extra metadata from in memory xml for uuid.
copy_part_from_other_model
(other_model, part)Fully copies part in from another model, with referenced parts, hdf5 data and relationships.
copy_uuid_from_other_model
(other_model, uuid)Fully copies part for uuid in from another model, with referenced parts, hdf5 data and relationships.
copy_all_parts_from_other_model
(other_model)Fully copies parts in from another model, with referenced parts, hdf5 data and relationships.
Yields grid connection set objects, one for each gcs in this model.
sort_parts_list_by_timestamp
(parts_list)Returns a copy of the parts list sorted by citation block creation date, with the newest first.
check_catalogue_dictionaries
([...])Checks internal consistency of catalogue dictionaries, raising assertion exception if inconsistent.
- __init__(epc_file: Optional[str] = None, full_load: bool = True, epc_subdir: Optional[Union[str, Iterable]] = None, new_epc: bool = False, create_basics: Optional[bool] = None, create_hdf5_ext: Optional[bool] = None, copy_from: Optional[str] = None, quiet=False)[source]¶
Create an empty model; load it from epc_file if given.
Note
if epc_file is given and the other arguments indicate that it will be a new dataset (new_epc is True or copy_from is given) then any existing .epc and .h5 file(s) with this name will be deleted immediately
- Parameters
epc_file (str, optional) – if present, and new_epc is False and copy_from is None, the name of an existing epc file which is opened, unzipped and parsed to determine the list of parts and relationships comprising the model; if present, and new_epc is True or copy_from is specified, the name of a new file to be created - any existing file (and .h5 paired hdf5 file) will be immediately deleted if None, an empty model is created (ie. with no parts) unless copy_from is present
full_load (boolean) – only relevant if epc_file is not None and new_epc is False (or copy_from is specified); if True (recommended), the xml for each part is parsed and stored in a tree structure in memory; if False, only the list of parts is loaded
epc_subdir (string or list of strings, optional) – if present, parts are only included in the load if they are in the top level directory of the epc internal structure, or in the specified subdirectory (or one of the subdirectories in the case of a list); only relevant if epc_file is not None and new_epc is False (or copy_from is specified)
new_epc (boolean, default False) – if True, a new model is created, empty unless copy_from is given
create_basics (boolean, optional) – if True and epc_file is None or new_epc is True, then the minimum essential parts are added to the empty Model; this is equivalent to calling the create_root(), create_rels_part() and create_doc_props() methods; if None, defaults to the same value as new_epc
create_hdf5_ref (boolean, optional) – if True and new_epc is True and create_basics is True and epc_file is not None, then an hdf5 external part is created, equivalent to calling the create_hdf5_ext() method; an empty hdf5 file is also created; if None, defaults to same value as new_epc
copy_from – (str, optional): if present, and epc_file is also present, then the epc file named in copy_from, together with its paired h5 file, are copied to epc_file (overwriting any previous instances) before epc_file is opened; this argument is primarily to facilitate repeated testing of code that modifies the resqml dataset, eg. by appending new parts
quiet (boolean, default False) – if True, reading and saving info logging messages are suppressed
- Returns
The newly created Model object
- add_grid(grid_object, check_for_duplicates=False)[source]¶
Add grid object to list of shareable grids for this model.
- Parameters
grid_object (grid.Grid object) – the ijk grid object to be added to the list of grids in the model
check_for_duplicates (boolean, default False) – if True, a check is made for any grid objects already in the grid list with the same root as the new grid object
- Returns
None
- add_part(content_type, uuid, root, add_relationship_part=True, epc_subdir=None)[source]¶
Adds a (recently created) node as a new part in the model’s parts forest.
- Parameters
content_type (string) – the resqml object class of the new part
uuid (uuid.UUID) – the uuid for the new part
root – the root node of the xml tree for the new part
add_relationship_part – (boolean, default True): if True, a relationship part is also created to go with the new part (empty of actual relationships)
epc_subdir (string, optional) – if present, the subdirectory path within the epc that the part is to be located within; if None, the xml will reside at the top level of the epc
- Returns
None
Notes
NB: xml tree for part is not written to epc file by this function (store_epc() handles that); do not use this function for the main rels extension part: use create_rels_part() instead
- as_graph(uuids_subset=None)[source]¶
Return representation of model as nodes and edges, suitable for plotting in a graph.
Note
The graph can be most readily visualised with other packages such as NetworkX and HoloViews, which are not part of resqpy.
For a guide to plotting graphs interactively, see: http://holoviews.org/user_guide/Network_Graphs.html
example:
# Create the nodes and edges nodes, edges = model.as_graph() # Load into a NetworkX graph import networkx as nx g = nx.Graph() g.add_nodes_from(nodes.items()) g.add_edges_from(edges) # Import holoviews import holoviews as hv from holoviews import opts hv.extension('bokeh') # Plot hv.Graph.from_networkx(g, nx.layout.spring_layout).opts( tools=['hover'], node_color='resqml_type', cmap='Category10' )
- Parameters
uuids_subset (iterable) – If present, only consider uuids in this list. By default, use all uuids in the model.
- Returns
2-tuple of nodes and edges –
nodes: dict mapping uuid to attributes (e.g. citation title)
edges: set of unordered pairs of uuids, representing relationships
- change_filename_in_hdf5_rels(new_hdf5_filename=None)[source]¶
Scan relationships forest for hdf5 external parts and patch in a new filename.
- Parameters
new_hdf5_filename – the new filename to patch into the xml; if None, the epc filename is used with no directory path and with the extension changed to .h5
- Returns
None
Notes
no check is made that the new filename is for an existing file; all hdf5 file references will be modified
- change_hdf5_uuid_in_hdf5_references(node, old_uuid, new_uuid)[source]¶
Scan node for hdf5 references and set the uuid of the hdf5 file itself to new_uuid.
- Parameters
node – the root node of an xml tree within which hdf5 internal paths are to have hdf5 uuids changed
old_uuid (uuid.UUID or str) – the ext uuid currently to be found in the hdf5 references; if None, all will be replaced
new_uuid (uuid.UUID or str) – the new ext (hdf5) uuid to replace the old one
- Returns
None
Note
use this method when the uuid of the hdf5 ext part is changing; if the uuid of the high level part itself is changing use change_uuid_in_hdf5_references() instead
- change_uuid_in_hdf5_references(node, old_uuid, new_uuid)[source]¶
Scan node for hdf5 references using the old_uuid and replace with the new_uuid.
- Parameters
node – the root node of an xml tree within which hdf5 internal paths are to have uuids changed
old_uuid (uuid.UUID or str) – the uuid currently to be found in the hdf5 references
new_uuid (uuid.UUID or str) – the new uuid to replace the old one
- Returns
None
Notes
use this method when the uuid of the high level part itself is changing; if the uuid of the hdf5 ext part itself is changing, use change_hdf5_uuid_in_hdf5_references() instead; this method does not modify the internal path names in the hdf5 file itself, if that has already been written
- change_uuid_in_supporting_representation_reference(node, old_uuid, new_uuid, new_title=None)[source]¶
Look for supporting representation reference using the old_uuid and replace with the new_uuid.
- Parameters
node – the root node of an xml tree within which the supporting representation uuid is to be changed
old_uuid (uuid.UUID or str) – the uuid currently to be found in the supporting representation reference
new_uuid (uuid.UUID or str) – the new uuid to replace the old one
new_title (string, optional) – if present, the title stored in the xml reference block is changed to this
- Returns
boolean – True if the change was carried out; False otherwise
Notes
this method is typically used to temporarily set a supporting representation to a locally mocked representation object when the actual supporting representation is not present in the dataset
- check_catalogue_dictionaries(referred_parts_must_be_present=True, check_xml=True)[source]¶
Checks internal consistency of catalogue dictionaries, raising assertion exception if inconsistent.
- Parameters
referred_parts_must_be_present (bool, default True) – if True, raises an exception if a referenced part is not present in the model (such a scenario is allowed by the RESQML standard)
check_xml (bool, default True) – if True, xml is scoured to check that references are consistent with the Model uuid_rels_dict internal dictionary
Note
this is a thorough but slow check, use sparing; primarily intended for unit tests and debugging
- copy_all_parts_from_other_model(other_model, realization=None, consolidate=True)[source]¶
Fully copies parts in from another model, with referenced parts, hdf5 data and relationships.
- Parameters
model (other) – the source model from which to copy parts
realization (int, optional) – if present, the realization attribute of property parts will be set to this value, instead of the value in use in the other model if any
consolidate (boolean, default True) – if True, where equivalent part already exists in this model, do not duplicate but instead note uuids as equivalent, modifying references and relationships of other copied parts appropriately
Notes
part names already existing in this model are not duplicated; default hdf5 file used in this model and assumed in other_model
- copy_part(existing_uuid, new_uuid, change_hdf5_refs=False)[source]¶
Makes a new part as a copy of an existing part with only a new uuid set; the new part can then be modified.
- Parameters
existing_uuid (uuid.UUID) – the uuid of the existing part
new_uuid (uuid.UUID) – the uuid to inject into the new part after copying of the xml tree
change_hdf5_refs (boolean) – if True, the new tree is scanned for hdf5 refs using the existing_uuid and they are replaced with the new_uuid
- Returns
string being the new part name
Notes
Resqml objects have a unique identifier and should be considered immutable; therefore to modify an object, it should first be duplicated; this function does some of the xml work needed for such duplication: the xml tree is copied; the uuid attribute in the root node is changed; the new part is added to the parts forest (with its name matched to the new uuid); NB: relationships are not currently copied or modified; also note that hdf5 data and high level objects maintained by other modules are not duplicated here; use this method to duplicate a part within a model prior to modifying the duplicated part in some way; to import a part from another model, use copy_part_from_other_model() instead; for copying a grid it is best to use the higher level derived_model.copy_grid() function
- copy_part_from_other_model(other_model, part, realization=None, consolidate=True, force=False, cut_refs_to_uuids=None, cut_node_types=None, self_h5_file_name=None, h5_uuid=None, other_h5_file_name=None, uuid_int=None)[source]¶
Fully copies part in from another model, with referenced parts, hdf5 data and relationships.
- Parameters
model (other) – the source model from which to copy a part
part (string) – the part name in the other model to copy into this model
realization (int, optional) – if present and the part is a property, the realization will be set to this value, instead of the value in use in the other model if any
consolidate (boolean, default True) – if True and an equivalent part already exists in this model, do not duplicate but instead note uuids as equivalent
force (boolean, default False) – if True, the part itself is copied without much checking and all references are required to be handled by an entry in the consolidation object
cut_refs_to_uuids (list of UUIDs, optional) – if present, then xml reference nodes referencing any of the listed uuids are cut out in the copy; use with caution
cut_node_types (list of str, optional) – if present, any child nodes of a type in the list will be cut out in the copy; use with caution
self_h5_file_name (string, optional) – h5 file name for this model; can be passed as an optimisation when calling method repeatedly
h5_uuid (uuid, optional) – UUID for this model’s hdf5 external part; can be passed as an optimisation when calling method repeatedly
other_h5_file_name (string, optional) – h5 file name for other model; can be passed as an optimisation when calling method repeatedly
uuid_int (int, optional) – if present, the uuid (as int) of part; if uuid already established use this argument as an optimisation; note: no checks for consistency are made here
- Returns
the part name of the part in this model, after copying; may differ from requested part if consolidate is True; None in the case of failure
Notes
if the part name already exists in this model, no action is taken; default hdf5 file used in this model and assumed in other_model
- copy_uuid_from_other_model(other_model, uuid, realization=None, consolidate=True, force=False, cut_refs_to_uuids=None, cut_node_types=None, self_h5_file_name=None, h5_uuid=None, other_h5_file_name=None)[source]¶
Fully copies part for uuid in from another model, with referenced parts, hdf5 data and relationships.
- Parameters
model (other) – the source model from which to copy a part
uuid (UUID) – the uuid of the part in the other model to copy into this model
realization (int, optional) – if present and the part is a property, the realization will be set to this value, instead of the value in use in the other model if any
consolidate (boolean, default True) – if True and an equivalent part already exists in this model, do not duplicate but instead note uuids as equivalent
force (boolean, default False) – if True, the part itself is copied without much checking and all references are required to be handled by an entry in the consolidation object
cut_refs_to_uuids (list of UUIDs, optional) – if present, then xml reference nodes referencing any of the listed uuids are cut out in the copy; use with caution
cut_node_types (list of str, optional) – if present, any child nodes of a type in the list will be cut out in the copy; use with caution
self_h5_file_name (string, optional) – h5 file name for this model; can be passed as an optimisation when calling method repeatedly
h5_uuid (uuid, optional) – UUID for this model’s hdf5 external part; can be passed as an optimisation when calling method repeatedly
other_h5_file_name (string, optional) – h5 file name for other model; can be passed as an optimisation when calling method repeatedly
- Returns
the uuid of the part in this model, after copying; may differ from requested uuid if consolidate is True; None in the case of failure
Notes
if the part already exists in this model, no action is taken; default hdf5 file used in this model and assumed in other_model
- create_citation(root=None, title='', originator=None)[source]¶
Creates a citation xml node and optionally appends as a child of root.
- Parameters
root (optional) – if not None, the newly created citation node is appended as a child to this node
title (string) – the citation title: a human readable string; this is the main point of having a citation node, so the argument should be used wisely
originator (string, optional) – the name of the human being who created the object which this citation is for; default is to use the login name
- Returns
newly created citation xml node
- create_crs_reference(root=None, crs_uuid=None)[source]¶
Creates a node refering to an existing crs node and optionally adds as child of root.
- Parameters
root – the xml node to which the new reference node is to appended as a child (ie. the xml node for the object that is referring to the crs)
crs_uuid – the uuid of the crs
- Returns
newly created crs reference xml node
- create_doc_props(add_as_part=True, root=None, originator=None)[source]¶
Creates a document properties stub node and optionally adds as child of root and/or to parts forest.
- Parameters
add_as_part (boolean, default True) – if True, the newly created node is also added as a part
root (optional, usually None) – if not None, the newly created node is appended to this root as a child
originator (string, optional) – used as the creator in the doc props node; if None, the login name is used
- Returns
the newly created doc props xml node
Note
the doc props part of a resqml dataset is intended to hold documentation and other stuff that is not covered by the standard; there should be exactly one doc props part
- create_hdf5_dataset_ref(hdf5_uuid, object_uuid, group_tail, root, title='Hdf Proxy')[source]¶
Creates a pair of nodes referencing an hdf5 dataset (array) and adds to root.
- Parameters
hdf5_uuid (uuid.UUID) – the uuid of the hdf5 external part being referenced
object_uuid (uuid.UUID) – the uuid of the high level object (part) which owns the hdf5 array being referenced
group_tail (string) – the tail of the hdf5 internal path, which is appended to the part name section of the internal path
root – the xml node to which the newly created hdf5 reference is appended as a child
title (string) – used as the Title text in the citation node, usually left at the default ‘Hdf Proxy’
- Returns
the newly created xml node holding the hdf5 internal path
- create_hdf5_ext(add_as_part=True, root=None, title='Hdf Proxy', originator=None, file_name=None, uuid=None)[source]¶
Creates an hdf5 external node and optionally adds as child of root and/or to parts forest.
- Parameters
add_as_part (boolean, default True) – if True the newly created ext node is added to the model as a part
root (optional, usually None) – if not None, the newly created ext node is appended as a child of this node
title (string) – used as the Title text in the citation node, usually left at the default ‘Hdf Proxy’
originator (string, optional) – the name of the human being who created the ext object; default is to use the login name
file_name (string, optional) – the filename to be stored as the Target in the relationship node; if None, will default to the epc filename with the extenstion replaced with .h5
uuid (uuid.UUID, optional) – the ext uuid tp associate with the external part; if None, a new uuid will be generated
- Returns
newly created hdf5 external part xml node
Note
this method is typically called when creating a new dataset (Model); if the intention is to share an existing hdf5 file, then pass the file_name and (ext) uuid arguments; if the intention is to create a new hdf5 file amongst many used by the Model, then pass the file_name
- create_md_datum_reference(md_datum_root, root=None)[source]¶
Creates a node refering to an existing measured depth datum and optionally adds as child of root.
- Parameters
md_datum_root – the root xml node for the measured depth datum being referenced
root – the xml node to which the new reference node is to appended as a child (ie. the xml node for the object that is referring to the md datum)
- Returns
newly created measured depth datum reference xml node
- create_patch(p_uuid, ext_uuid=None, root=None, patch_index=0, hdf5_type='DoubleHdf5Array', xsd_type='double', null_value=None, const_value=None, const_count=None, points=False)[source]¶
Create a node for a patch of values, including ref to hdf5 data set, optionally add to root.
- Parameters
p_uuid (uuid.UUID) – the uuid of the object for which this patch is a component
ext_uuid (uuid.UUID) – the uuid of the hdf5 external part holding the array; required unless const_value and const_count are not None
root – if not None, the newly created patch of values xml node is appended as a child to this node
patch_index (int, default 0) – the patch index number; patches must be numbered sequentially starting at 0
hdf5_type (string, default 'DoubleHdf5Array') – the type of the hdf5 array; usually one of ‘DoubleHdf5Array’, ‘IntegerHdf5Array’, or ‘BooleanHdf5Array’; replaced with equivalent constant array type if const_value is not None
xsd_type (string, default 'double') – the xsd simple type of each element of the array
null_value – Used in a null value sub-node to specify what value in an array of discrete data represents null; if None, a value of -1 is used for signed integers, 2^32 - 1 for uints (even 64 bit uints!)
const_value (float, int, or bool, optional) – if not None, the patch is created as a constant array; const_count must also be present if const_value is not None
const_count (int, optional) – the number of elements in (size of) the constant array; required if const_value is not None, ignored otherwise
points (bool, default False) – if True, the created node will be for a patch of points, otherwise a patch of values
- Returns
newly created xml node for the patch of values
Note
this function does not write the data to the hdf5; that should be done separately before calling this method; RESQML usually stores array data in the hdf5 file however constant arrays are flagged as such in the xml and no data is stored in the hdf5
- create_reciprocal_relationship(node_a, rel_type_a, node_b, rel_type_b, avoid_duplicates=True)[source]¶
Adds a node to each of a pair of trees in the rels forest, to represent a two-way relationship.
- Parameters
node_a – one of the two xml nodes to be related
rel_type_a (string) – the Type (role) associated with node_a in the relationship; usually ‘sourceObject’ or ‘destinationObject’
node_b – the other xml node to be related
rel_type_b (string) – the Type (role) associated with node_b in the relationship usually ‘sourceObject’ or ‘destinationObject’ (opposite of rel_type_a)
avoid_duplicates (boolean, default True) – if True, xml for a relationship is not added where it already exists; if False, a duplicate will be created in this situation
- Returns
None
Note
this method has the same effect as create_reciprocal_relationship_uuids() but takes xml root nodes rather than uuids as arguments
- create_reciprocal_relationship_uuids(uuid_a, rel_type_a, uuid_b, rel_type_b, avoid_duplicates=True)[source]¶
Adds a node to each of a pair of trees in the rels forest, to represent a two-way relationship.
- Parameters
uuid_a – uuid of one of the two parts to be related
rel_type_a (string) – the Type (role) associated with uuid_a in the relationship; usually ‘sourceObject’ or ‘destinationObject’
uuid_b – uuid of the other part to be related
rel_type_b (string) – the Type (role) associated with uuid_b in the relationship usually ‘sourceObject’ or ‘destinationObject’ (opposite of rel_type_a)
avoid_duplicates (boolean, default True) – if True, xml for a relationship is not added where it already exists; if False, a duplicate will be created in this situation
- Returns
None
Note
this method has the same effect as create_reciprocal_relationship() but takes uuids rather than xml root nodes as arguments
- create_ref_node(flavour, title, uuid, content_type=None, root=None)[source]¶
Create a reference node, optionally add to root.
- Parameters
flavour (string) – the resqml object class (type of part) for which a reference node is required
title (string) – used as the Title subelement text in the reference node
uuid – (uuid.UUID): the uuid of the part being referenced
content_type (string, optional) – if None, the referenced content type is determined from the flavour argument (recommended)
root (optional) – if not None, an xml node to which the reference node is appended as a child
- Returns
newly created reference xml node
- create_rels_part()[source]¶
Adds a relationships reference node as a new part in the model’s parts forest.
- Returns
newly created main relationships reference xml node
Note
there can only be one relationships reference part in the model
- create_root()[source]¶
Initialises an empty main xml tree for model.
Note
not usually called directly
- create_solitary_point3d(flavour, root, xyz)[source]¶
Creates a subelement to root for a solitary point in 3D space.
- Parameters
flavour (string) – the object class (type) of the point node to be created
root – the xml node to which the newly created solitary point node is appended as a child
xyz (triple float) – the x, y, z coordinates of the solitary point
- Returns
the newly created xml node for the solitary point
- create_source(source, root=None)[source]¶
Create an extra meta data node holding information on the source of the data, optionally add to root.
- Parameters
source (string) – text describing the source of an object
root – if not None, the newly created extra metadata node is appended as a child of this node
- Returns
the newly created extra metadata xml node
- create_supporting_representation(grid_root=None, support_uuid=None, root=None, title=None, content_type='obj_IjkGridRepresentation')[source]¶
Craate a supporting representation reference node refering to an IjkGrid and optionally add to root.
- Parameters
grid_root – the xml node of the grid (or other) object which is the supporting representation being referred to; could also be used for other classes of supporting object; this or support_uuid must be provided
support_uuid – the uuid of the grid (or other supporting representation) being referred to; this or grid_root must be provided
root – if not None, the newly created supporting representation node is appended as a child to this node
title – the Title to use in the supporting representation node
content_type – the resqml object class of the supporting representation being referenced; defaults to ‘obj_IjkGridRepresentation’
- Returns
newly created xml node for supporting representation reference
Notes
a property array needs a supporting representation which is the structure that the property values belong to; for example, a grid property array has the grid object as the supporting representation; one of grid_root or support_uuid should be passed when calling this method
- create_time_series_ref(time_series_uuid, root=None)[source]¶
Create a reference node to a time series, optionally add to root.
- Parameters
time_series_uuid (uuid.UUID) – the uuid of the time series part being referenced
root (optional) – if present, the newly created time series reference xml node is added as a child to this node
- Returns
the newly created time series reference xml node
- create_tree_if_none()[source]¶
Checks that model has an xml tree; if not, an empty tree is created; not usually called directly.
- create_unknown(root=None)[source]¶
Creates an Unknown node and optionally adds as child of root.
- Parameters
root (optional) – if present, the newly created Unknown node is appended as a child of this xml node
- Returns
the newly created Unknown xml node
- property crs_root¶
XML node corresponding to self.crs_uuid, the ‘main’ crs for the model.
- duplicate_node(existing_node, add_as_part=True)[source]¶
Creates a deep copy of the xml node (typically from another model) and optionally adds as part.
- Parameters
existing_node – the existing xml node, usually in another model, to be duplicated
add_as_part (boolean, default True) – if True, the newly created xml node is added as a part in this model
- Returns
the newly created duplicate xml node
Notes
hdf5 data is not copied by this function and any reference to hdf5 arrays will be naively duplicated; the uuid of the part is not changed by this function, so if the source and target models are the same, add as part should be set False and calling code will need to assign a new uuid prior to adding as part; if add_as_part is True, the part is only added if the uuid does not already exist in this model
- external_parts_list()[source]¶
Returns a list of part names for external part references.
- Returns
list of strings being the part names for external part references
Note
in practice, external part references are only used for hdf5 files; furthermore, all current datasets have adopted the practice of using a single hdf5 file for a given epc file
- fell_part(part_name)[source]¶
Removes the named part from the in-memory parts forest.
- Parameters
part_name (string) – the name of the part to be removed
Note
no check is made for references or relationships to the part being deleted; not usually called directly
- force_consolidation_equivalence_for_class_ignoring_extra_metadata(other_model, resqpy_class)[source]¶
Force immigrant objects of type to be teated as equivalent where only extra metadata differs during consolidation.
Notes
this method should be called prior to calling copy_part_from_other_model() or copy_uuid_from_other_model() to override the more stringent equivalence checks which include extra metadata; the resqpy class must have an is_equivalent() method which supports the check_extra_metadata boolean argument; typically used for organisational classes such as features and interpretations; an exception is raised if more than one matching part already exists in this model, for a particular immigrant title (for the object type)
- force_consolidation_uuid_equivalence(immigrant_uuid, resident_uuid)[source]¶
Force immigrant object to be teated as equivalent to resident during consolidation.
- grid(title=None, uuid=None, find_properties=True)[source]¶
Returns a shared Grid (or RegularGrid) object for this model, by default the ‘main’ grid.
- Parameters
title (string, optional) – if present, the citation title of the IjkGridRepresentation
uuid (uuid.UUID, optional) – if present, the uuid of the IjkGridRepresentation
find_properties (boolean, default True) – if True, the property_collection attribute of the returned grid object will be populated
- Returns
grid.Grid object for the specified grid or the main ijk grid part in this model
Note
if neither title nor uuid are given, the model should contain just one grid, or a grid named ‘ROOT’; unlike most classes of object, a central list of resqpy Grid objects can be maintained within a Model by using this method which will return a shared object from this list, instantiating a new object and adding it to the list when necessary; an assertion exception will be raised if a suitable grid part is not present in the model
- grid_for_uuid_from_grid_list(uuid)[source]¶
Returns the cached grid object matching the given uuid, if found in the grid list, otherwise None.
- h5_access(uuid=None, mode='r', override='default', file_path=None)[source]¶
Returns an open h5 file handle for the hdf5 file with the given uuid.
- Parameters
uuid (uuid.UUID) – the uuid of the hdf5 external part reference for which the open file handle is required; required if override is False and file_path is None
mode (string) – the hdf5 file mode (‘r’, ‘w’ or ‘a’) with which to open the file
override (str or bool, default 'default') – if str, one of ‘default’, ‘none’, ‘dir’ or ‘full’; if bool (deprecated), False means ‘dir’ and True means ‘full’; if ‘default’, the default h5 override mode for the model is used; if ‘dir’, any directory in the rels hdf5 file name is replaced with the epc’s directory; if ‘full’, the hdf5 full path is generated by using the epc path but replacing the .epc extension with .h5
file_path (string, optional) – if present, is used as the hdf5 file path, otherwise the path will be determined based on the uuid and override arguments
- Returns
a file handle to the opened hdf5 file
Note
an exception will be raised if the hdf5 file cannot be opened; note that sometimes another piece of code accessing the file might cause a ‘resource unavailable’ exception
- h5_array_element(h5_key_pair, index=None, cache_array=False, object=None, array_attribute=None, dtype='float', required_shape=None)[source]¶
Returns one element from an hdf5 array and/or caches the array.
- Parameters
h5_key_pair (uuid.UUID, string) – the uuid of the hdf5 external part reference and the hdf5 internal path for the array
index (pair or triple int, optional) – if None, the only purpose of the call is to ensure that the array is cached in memory; if not None, the (k0, pillar_index) or (k0, j0, i0) index of the cell for which the value is required
cache_array (boolean, default False) – if True, a copy of the whole array is cached in memory as an attribute of the object; if already cached, the array is not uncached, regardless of this argument
object (optional, defaults to self) – the object in which a cached version of the array is an attribute, or will be created as an attribute if cache_array is True
array_attribute (string) – the attribute name to use for the cached version of the array, required to cache or access cached array
dtype (string or data type) – the data type of the elements of the array (need not match hdf5 array in precision)
required_shape (tuple of ints, optional) – if not None, the hdf5 array will be reshaped to this shape; if index is not None, it is taken to be applicable to the required shape; required if the array is bool data that was written with resqpy specific dtype of ‘pack’
- Returns
if index is None, then None; if index is not None, then the value of the array for the cell identified by index
Note
this function can be used to access an individual element from an hdf5 array, or to cache a whole array in memory; when accessing an individual element, the index style must match the array indexing; in particular for IJK grid points, a (k0, pillar_index) is needed when the grid has split pillars, whereas a (k0, j0, i0) is needed when the grid does not have any split pillars
- h5_array_shape_and_type(h5_key_pair)[source]¶
Returns the shape and dtype of the array, as stored in the hdf5 file.
- Parameters
h5_key_pair (uuid.UUID, string) – the uuid of the hdf5 external part reference and the hdf5 internal path for the array
- Returns
(tuple of ints, type) – simply the shape and dtype attributes of the referenced hdf5 array; (None, None) is returned if the hdf5 file is not found, or the array is not found within it
- h5_array_slice(h5_key_pair, slice_tuple)[source]¶
Loads a slice of an hdf5 array.
- Parameters
h5_key_pair (uuid, string) – the uuid of the hdf5 ext part and the hdf5 internal path to the required hdf5 array
slice_tuple (tuple of slice objects) – each element should be constructed using the python built-in function slice()
- Returns
numpy array that is a hyper-slice of the hdf5 array, with the same ndim as the source hdf5 array
Notes
this method always fetches from the hdf5 file and does not attempt local caching; the whole array is not loaded; all axes continue to exist in the returned array, even where the sliced extent of an axis is 1
- h5_file_name(uuid=None, override='default', file_must_exist=True)[source]¶
Returns full path for hdf5 file with given uuid.
- Parameters
uuid (uuid.UUID, optional) – the uuid of the hdf5 external part reference for which the file name is required; if None, the ‘main’ hdf5 uuid is used
override (str or bool, default 'default') – if str, one of ‘default’, ‘none’, ‘dir’ or ‘full’; if bool (deprecated), False means ‘dir’ and True means ‘full’; if ‘default’, the default h5 override mode for the model is used; if ‘dir’, any directory in the rels hdf5 file name is replaced with the epc’s directory; if ‘full’, the hdf5 full path is generated by using the epc path but replacing the .epc extension with .h5
file_must_exist (boolean, default True) – if True, the existence of the hdf5 file is checked
found (upon first call and a FileNotFound exception is raised if the file is not) –
- Returns
string being the full path of the hdf5 file
Notes
in practice, a resqml model usually consists of a pair of files in the same directory, with names like: a.epc and a.h5; to allow copying, moving and renaming of files, the practical approach is simply to assume a one-to-one correspondence between epc and hdf5 files, and assume they are in the same directory, which will be the default behaviour of resqpy; to change the default behaviour for the model, call the h5_set_default_override() method; an hdf5 file name is cached once determined for a given ext uuid; to clear the cache, call the h5_clear_filename_cache() method
- h5_overwrite_array(h5_key_pair, array)[source]¶
Overwrites (updates) the whole of an hdf5 array.
- Parameters
h5_key_pair (uuid, string) – the uuid of the hdf5 ext part and the hdf5 internal path to the required hdf5 array
array (numpy array of shape to match existing hdf5 dataset) – the data to write
Notes
this method naively updates an hdf5 array without using mpi to look after parallel updates; metadata (such as uuid or property min, max values) is not modified in any way by the method
- h5_overwrite_array_slice(h5_key_pair, slice_tuple, array_slice)[source]¶
Overwrites (updates) a slice of an hdf5 array.
- Parameters
h5_key_pair (uuid, string) – the uuid of the hdf5 ext part and the hdf5 internal path to the required hdf5 array
slice_tuple (tuple of slice objects) – each element should be constructed using the python built-in function slice()
array_slice (numpy array of shape to match slice_tuple) – the data to write
Notes
this method naively updates a slice in an hdf5 array without using mpi to look after parallel updates; metadata (such as uuid or property min, max values) is not modified in any way by the method
- h5_set_default_override(override)[source]¶
Sets the default hdf5 filename override mode for the model.
- Parameters
override (str) – ‘none’, ‘dir’ or ‘full’ being the override mode to use by default
Note
this mode will be used by default when determining a filename for accessing hdf5 data; see h5_file_name() notes for more information
- h5_uuid_and_path_for_node(node, tag='Values')[source]¶
Returns a (hdf5_uuid, hdf5_internal_path) pair for an xml array node.
- Parameters
node – xml node for which the array reference is required
tag (string, default 'Values') – the tag of the child of node for which the array reference is required
- Returns
(uuid.UUID, string) pair being the uuid of the hdf5 external part reference and the hdf5 internal path for the array of interest
Note
this method provides the key data needed to actually access array data within the resqml dataset
- h5_uuid_list(node)[source]¶
Returns a list of all uuids for hdf5 external part(s) referred to in recursive tree.
- iter_crs()[source]¶
Iterable of all CRS objects associated with the model.
- Yields
crs – instance of
resqpy.crs.CRS
- iter_grid_connection_sets()[source]¶
Yields grid connection set objects, one for each gcs in this model.
- iter_md_datums()[source]¶
Iterable of all MdDatum objects associated with the model.
- Yields
md_datum – instance of
resqpy.well.MdDatum
- iter_objs(cls)[source]¶
Iterate over all available objects of given resqpy class within the model.
Note
The resqpy class must expose a class attribute resqml_type, and must support being created with the signature: obj = cls(model, uuid=uuid).
example use:
for well in model.iter_objs(cls=resqpy.well.WellboreFeature): print(well.title, well.uuid)
- Parameters
cls – resqpy class to iterate
- Yields
list of instances of cls
- iter_trajectories()[source]¶
Iterable of all trajectories associated with the model.
- Yields
trajectory – instance of
resqpy.well.Trajectory
- iter_wellbore_interpretations()[source]¶
Iterable of all WellboreInterpretations associated with the model.
- Yields
wellbore – instance of
resqpy.organize.WellboreInterpretation
- load_epc(epc_file, full_load=True, epc_subdir=None, copy_from=None, quiet=False)[source]¶
Load xml parts of model from epc file (HDF5 arrays are not loaded).
- Parameters
epc_file (string) – the path of the epc file
full_load (boolean, default True) – if True (recommended), the xml for each part is parsed and stored in a tree structure in memory; if False, only the list of parts is loaded
epc_subdir (string or list of strings, optional) – if present, only parts in the top level directory within the epc structure, or in the specified subdirectory(ies) are included in the load
copy_from (string, optional) – if present, the .epc and .h5 are copied from this source to epc_file (and paired .h5) prior to opening epc_file; any previous files named as epc_file will be overwritten
quiet (boolean, default False) – if True, info logging message is emitted as debug
- Returns
None
Note
when copy_from is specified, the entire contents of the source dataset are copied, regardless of the epc_subdir setting which only affects the subsequent load into memory
- load_part(epc, part_name, is_rels=None)[source]¶
Load and parse xml tree for given part name, storing info in parts forest (or rels forest).
- Parameters
epc – an open ZipFile handle for the epc file
part_name (string) – the name of the ‘file’ within the epc bundle containing the part (or relationship)
is_rels – (boolean, optional): if True, the part to be loaded is a relationship part; if False, it is a main part; if None, its value is derived from the part name
- Returns
boolean – True if part loaded successfully, False if part failed to load
Note
parts forest must already have been initialized before calling this method; if False is returned, calling code should probably delete part from forest; not usually called directly
- new_obj_node(flavour, name_space='resqml2', is_top_lvl_obj=True)[source]¶
Creates a new main object element and sets attributes (does not add children).
- Parameters
flavour (string) – the resqml object class (type of part) for which a new xml tree is required
name_space (string, default 'resqml2') – the xml namespace identifier to use for the node
is_top_lvl_obj (boolean, default True) – if True, the xsi:type is set in the xml node, as required for top level objects (parts); if False, the type atttribute is not set
- Returns
newly created root node for xml tree for flavour of object, without any children
- number_of_parts()[source]¶
Retuns the number of parts in the model, including external parts such as the link to an hdf5 file.
- part(parts_list=None, obj_type=None, uuid=None, title=None, title_mode='is', title_case_sensitive=False, metadata={}, extra={}, related_uuid=None, related_mode=None, epc_subdir=None, multiple_handling='exception')[source]¶
Returns the name of a part matching all of the arguments passed.
- Parameters
parts ((as for) –
multiple_handling (string, default 'exception') – one of ‘exception’, ‘none’, ‘first’, ‘oldest’, ‘newest’
- Returns
string being the part name of the single part matching all of the criteria, or None
Notes
this method can be used where a single part is being identified; if no parts match the criteria, None is returned; if more than one part matches the criteria, the multiple_handling argument determines what happens: ‘exception’ causes a ValueError exception to be raised; ‘none’ causes None to be returned; ‘first’ causes the first part (as stored in the epc file or added) to be returned; ‘oldest’ causes the part with the oldest creation timestamp in the citation block to be returned; ‘newest’ causes the newest part to be returned
- part_for_uuid(uuid)[source]¶
Returns the part name which has the given uuid.
- Parameters
uuid (uuid.UUID object or string) – the uuid of the part of interest
- Returns
a string being the part name which matches the uuid, or None if not found
- parts(parts_list=None, obj_type=None, uuid=None, title=None, title_mode='is', title_case_sensitive=False, metadata={}, extra={}, related_uuid=None, related_mode=None, epc_subdir=None, sort_by=None)[source]¶
Returns a list of parts matching all of the arguments passed.
- Parameters
parts_list (list of strings, optional) – if present, an ‘input’ list of parts to be filtered; if None then all the parts in the model are considered
obj_type (string, optional) – if present, only parts of this resqml type will be included
uuid (uuid.UUID, optional) – if present, the uuid of a part to select
title (string, optional) – if present, a citation title or substring to filter on, based on the title_mode argument
title_mode (string, default 'is') – one of ‘is’, ‘starts’, ‘ends’, ‘contains’, ‘is not’, ‘does not start’, ‘does not end’, or ‘does not contain’; how to compare each part’s citation title with the title argument; ignored if title is None
title_case_sensitive (boolean, default False) – if True, title comparisons are made on a case sensitive basis; otherwise comparisons are insensitive to case
key (extra (dictionary of) – value pairs, optional): if present, only parts which have within their top level metadata all the items in this argument, are included in the filtered list
key – value pairs, optional): if present, only parts which have within their extra metadata all the items in this argument, are included in the filtered list
related_uuid (uuid.UUID, optional) – if present, only parts which are related to this uuid are included in the filtered list
related_mode (Optional[int]) – if provided, filters by the type of relationship. 0 is parts referenced by related_uuid, 1 is parts that reference related_uuid, 2 is other soft related parts.
epc_subdir (string, optional) – if present, only parts which reside within the specified subdirectory path of the epc are included in the filtered list
sort_by (string, optional) – one of ‘newest’, ‘oldest’, ‘title’, ‘uuid’, ‘type’
- Returns
a list of strings being the names of parts which match all filter arguments
Examples
a full list of parts in the model:
model.parts()
a list of IjkGrid parts:
model.parts(obj_type = 'IjkGridRepresentation')
a list containing the part name for a uuid:
model.parts(uuid = 'a869e7cc-5d30-4b31-8502-c74b1d87c777')
a list of IjkGrid parts with titles beginning LGR, sorted by title:
model.parts(obj_type = 'IjkGridRepresentation', title = 'LGR', title_mode = 'starts', sort_by = 'title')
- parts_count_by_type(type_of_interest=None)[source]¶
Returns a sorted list of (type, count) for parts.
- Parameters
type_of_interest (string, optional) – if not None, the returned list only contains one pair, with a count for that type, ie. resqml object class
- Returns
list of pairs, each being (string, int) representing part type, ie. resqml object class, without leading obj underscore, and count
- parts_count_dict()[source]¶
Returns a dictionary mapping from RESQML object type to count of parts.
- Returns
dict mapping string to int with key being RESQML class and value being count of number of parts
Note
only RESQML classes with at least one object present in the model will be included in the dictionary
From a list of parts, returns a list of those parts which have a relationship with the given uuid.
- Parameters
parts_list (list of strings) – input list of parts from which a selection is made
uuid (uuid.UUID) – the uuid of a part for which related parts are required
uuid_is_source (boolean, default None) – if None, relationships in either direction qualify; if True, only those where uuid is sourceObject qualify; if False, only those where uuid is destinationObject qualify
related_mode (Optional[int]) – if provided, filters by the type of relationship. 0 is parts referenced by this uuid, 1 is parts that reference this uuid, 2 is other soft related parts.
- Returns
list of strings being the subset of parts_list which are related to the object with the given uuid
Note
the part to which the given uuid applies might or might not be in the input parts list; this method scans the relationship info for every present part, looking for uuid in rels
- parts_list_filtered_by_supporting_uuid(parts_list, uuid)[source]¶
From a list of parts, returns a list of those parts which have the given uuid as supporting representation.
- Parameters
parts_list (list of strings) – input list of parts from which a selection is made
uuid (uuid.UUID) – the uuid of a supporting representation part for which related parts are required
- Returns
list of strings being the subset of parts_list which have as their supporting representation the object with the given uuid
Note
the part to which the given uuid applies might or might not be in the input parts list
- parts_list_of_type(type_of_interest=None, uuid=None)[source]¶
Returns a list of part names for parts of type of interest, optionally matching a uuid.
- Parameters
type_of_interest (string) – the resqml object class of interest, in string form, eg. ‘obj_IjkGridRepresentation’
uuid (uuid.UUID object, optional) – if present, only a part with this uuid is included in the list
- Returns
a list of strings being the part names which match the arguments
Note
usually either a type of interest or a uuid is passed; if neither are passed, all parts are returned; this method is maintained for backward compatibility and for efficiency reasons; it is equivalent to: self.parts(obj_type = type_of_interest, uuid = uuid)
Returns a list of parts of type of interest that relate to part with given uuid.
- Parameters
uuid (uuid.UUID) – the uuid of a part for which related parts are required
type_of_interest (string) – the type of parts (resqml object class) of the related parts of interest
- Returns
list of strings being the part names of the type of interest, related to the uuid
- patch_root_for_part(part, root)[source]¶
Updates the xml tree for the part without changing the uuid.
- referenced_node(ref_node, consolidate=False)[source]¶
For a given xml reference node, returns the node for the object referred to, if present.
Note
if consolidating and an equivalent referenced object exists, the uuid in the ref_node is modified by this method; it does not update entries in the uuid_rels_dict
- remove_extra_metadata(uuid)[source]¶
Removes extra metadata from in memory xml for uuid.
Note
this method will not modify any resqpy objects already instantiated
- remove_part(part_name, remove_relationship_part=True)[source]¶
Removes a part from the parts forest; optionally remove corresponding rels part and other relationships.
- remove_part_from_main_tree(part)[source]¶
Removes the named part from the main (Content_Types) tree.
Note
not usually called directly
- resolve_grid_root(grid_root=None, uuid=None)[source]¶
If grid root argument is None, returns the root for the IJK Grid part instead.
- Parameters
grid_root (optional) – if not None, this method simply returns this argument
uuid (uuid.UUID, optional) – if present, the uuid of the ijk grid part for which the root is required; if None, an ijk grid part is sought and the root for that part is returned
- Returns
root node in xml tree for the ijk grid part in this model (‘ROOT’ grid if more than one present)
Notes
if grid_root and uuid are both None and there are multiple grids in the model, the oldest grid with a citation title of ‘ROOT’ will be returned; an exception will be raised if no grid part is present in the model
- resolve_time_series_root(time_series_root=None)[source]¶
If time_series_root is None, finds the root for a time series in the model.
- Parameters
time_series_root (optional) – if not None, this method simply returns this argument
- Returns
root node in xml tree for the time series part in this model, or None if there is no time series part
Note
an assertion exception will be raised if time_series_root is None and there is more than one time series part in the model
- root(parts_list=None, obj_type=None, uuid=None, title=None, title_mode='is', title_case_sensitive=False, metadata={}, extra={}, related_uuid=None, related_mode=None, epc_subdir=None, multiple_handling='exception')[source]¶
Returns the xml root node of a part matching all of the arguments passed.
- Parameters
part ((as for) –
- Returns
lxml.etree.Element object being the root node of the xml for the single part matching all of the criteria, or None
- root_for_ijk_grid(uuid=None, title=None)[source]¶
Return root for IJK Grid part.
- Parameters
uuid (uuid.UUID, optional) – if present, the uuid of the ijk grid part for which the root is required; if None, a single ijk grid part is expected and the root for that part is returned
title (string, optional) – if present, the citation title for the grid; defaults to ‘ROOT’ if more than one ijk grid present and no uuid supplied
- Returns
root node in xml tree for the ijk grid part in this model
Notes
if uuid and title are both supplied, they must match in the corresponding grid part; if a title but no uuid is given, the first ijk grid encountered that has a matching title will be returned; if neither title nor uuid are given, the first ijk grid with title ‘ROOT’ will be returned, unless there is only one grid part in which case the root npde for that part is returned regardless; failure to find a matching grid part results in an assertion exception
- root_for_part(part_name, is_rels=None)[source]¶
Returns root of parsed xml tree for the named part.
- Parameters
part_name (string) – the part name for which the root of the xml tree is required
is_rels (boolean, optional) – if True, the part is a relationship part; if False, it is a main part; if None, its value is determined from the part name
- Returns
root node of the parsed xml tree (defined in lxml or ElementTree package) for the named part
- root_for_time_series(uuid=None)[source]¶
Return root for time series part.
- argument:
- uuid (uuid.UUID, optional): if present, the uuid of the time series part for which the root is required;
if None, a single time series part is expected and the root for that part is returned
- Returns
root node in xml tree for the time series part in this model
Note
if no uuid is given and the model contains more than one time series, the one with the earliest creation date is returned
- root_for_uuid(uuid)[source]¶
Returns the xml root for the part which has the given uuid.
- Parameters
uuid (uuid.UUID object or string) – the uuid of the part of interest
- Returns
the xml root node for the part with the given uuid, or None if not found
- roots(parts_list=None, obj_type=None, uuid=None, title=None, title_mode='is', title_case_sensitive=False, metadata={}, extra={}, related_uuid=None, related_mode=None, epc_subdir=None, sort_by=None)[source]¶
Returns a list of xml root nodes of parts matching all of the arguments passed.
- Parameters
parts ((as for) –
- Returns
list of lxml.etree.Element objects
- set_epc_file_and_directory(epc_file)[source]¶
Sets the full path and directory of the epc_file.
- Parameters
epc_file (string) – the path of the epc file
Note
not usually needed to be called directly, except perhaps when creating a new dataset
- set_modified()[source]¶
Marks the model as having been modified and assigns a new uuid.
Note
this modification tracking functionality is not part of the resqml standard and is only loosely applied by the library code; not usually called directly
- set_source_for_obj(obj, source)[source]¶
Sets the source string in the object’s extra metadata.
- Parameters
part (str) – the part for which the source information is to be set
source (str) – text for the extra metadata source item
Notes
this function adds the source item to the in-memory xml extra metadata as well as the object’s extra_metadata dictionary any previous text for the source item (if present) will be replaced; it will be included in the epc if store_epc() is subsequently called
- set_source_for_part(part, source)[source]¶
Sets the source string in the part’s extra metadata.
- Parameters
part (str) – the part for which the source information is to be set
source (str) – text for the extra metadata source item
Notes
this function adds the source item to the in-memory xml extra metadata; any previous text for the source item (if present) will be replaced; it will be included in the epc if store_epc() is subsequently called
- sort_parts_list_by_timestamp(parts_list)[source]¶
Returns a copy of the parts list sorted by citation block creation date, with the newest first.
- source_for_obj(obj)[source]¶
Returns the source string from the object’s extra metadata, if present, else None.
- Parameters
obj (BaseResqpy) – any high level resqpy object (eg. Surface)
- Returns
str being the text of the source extra metadata item for the object, or None
- source_for_part(part)[source]¶
Returns the source string from the part’s extra metadata, if present, else None.
- Parameters
part (str) – the part for which the source information is required
- Returns
str being the text of the source field in the xml extra metadata of the part, or None
- store_epc(epc_file=None, main_xml_name='[Content_Types].xml', only_if_modified=False, quiet=False)[source]¶
Write xml parts of model to epc file (HDF5 arrays are not written here).
- Parameters
epc_file (string) – the name of the output epc file to be written (any existing file will be overwritten)
main_xml_name (string, do not pass) – this argument should not be passed as the resqml standard requires the default value; (the argument exists in code because the resqml standard value is based on a slight misunderstanding of the opc standard, so could perhaps change in future versions of resqml)
only_if_modified (boolean, default False) – if True, the epc file is only written if the model is flagged as having been modified (at least one part added or removed)
quiet (boolean, default False) – if True, info logging is emitted at debug level
- Returns
None
Note
the main tree, parts forest and rels forest must all be up to date before calling this method
- supporting_representation_for_part(part)[source]¶
Returns the uuid of the supporting representation for the part, if found, otherwise None.
- tidy_up_forests(tidy_main_tree=True, tidy_others=False, remove_extended_core=True)[source]¶
Removes any parts that do not have any related data in dictionaries.
Note
not usually called directly
- title(parts_list=None, obj_type=None, uuid=None, title=None, title_mode='is', title_case_sensitive=False, metadata={}, extra={}, related_uuid=None, related_mode=None, epc_subdir=None, multiple_handling='exception')[source]¶
Returns the citation title of a part matching all of the arguments passed.
- Parameters
part ((as for) –
- Returns
string being the citation title of the single part matching all of the criteria, or None
- title_for_part(part_name)[source]¶
Returns the Title text from the Citation for the given main part name (not for rels).
- Parameters
part_name (string) – the name of the part for which the citation title is required
- Returns
string being the Title text from the citation node which is a child of the root xml node for the part, or None if not found
- title_for_root(root=None)[source]¶
Returns the Title text from the Citation within the given root node.
- Parameters
root – the xml node for the object for which the citation title is required
- Returns
string being the Title text from the citation node which is a child of root, or None if not found
- titles(parts_list=None, obj_type=None, uuid=None, title=None, title_mode='is', title_case_sensitive=False, metadata={}, extra={}, related_uuid=None, related_mode=None, epc_subdir=None, sort_by=None)[source]¶
Returns a list of citation titles of parts matching all of the arguments passed.
- Parameters
parts ((as for) –
- Returns
list of strings being the citation titles of matching parts
- tree_for_part(part_name, is_rels=None)[source]¶
Returns parsed xml tree for the named part.
- Parameters
part_name (string) – the part name for which the xml tree is required
is_rels (boolean, optional) – if True, the part is a relationship part; if False, it is a main part; if None, its value is determined from the part name
- Returns
parsed xml tree (defined in lxml or ElementTree package) for the named part
- type_of_part(part_name, strip_obj=False)[source]¶
Returns content type for the named part (does not apply to rels parts).
- Parameters
part_name (string) – the part for which the type is required
strip_obj (boolean, default False) – if True, the leading obj and underscore is removed from the returned string
- Returns
string being the type (resqml object class) for the named part
- type_of_uuid(uuid, strip_obj=False)[source]¶
Returns content type for the uuid.
- Parameters
uuid (uuid.UUID or str) – the uuid for which the type is required
strip_obj (boolean, default False) – if True, the leading obj and underscore is removed from the returned string
- Returns
string being the type (resqml object class) for the named part
- uom_node(root, uom)[source]¶
Add a generic unit of measure sub element to root.
- Parameters
root – xml node to which unit of measure subelement (child) will be added
uom (string) – the resqml unit of measure
- Returns
newly created unit of measure node (having already been added to root)
Note
does not currently check that uom is a valid Energistics unit of measure; use weights_and_measures module functionality to check if needed
- uuid(parts_list=None, obj_type=None, uuid=None, title=None, title_mode='is', title_case_sensitive=False, metadata={}, extra={}, related_uuid=None, related_mode=None, epc_subdir=None, multiple_handling='exception')[source]¶
Returns the uuid of a part matching all of the arguments passed.
- Parameters
part ((as for) –
- Returns
uuid of the single part matching all of the criteria, or None
- uuid_for_part(part_name, is_rels=None)[source]¶
Returns the uuid for the named part.
- Parameters
part_name (string) – the part name for which the uuid is required
is_rels (boolean, optional) – if True, the part is a relationship part; if False, it is a main part; if None, its value is determined from the part name
- Returns
uuid.UUID for the specified part
Note
this method will fail with an exception if the part is not in this model; a quicker alternative to this method is simply to extract the uuid from the part name using olio.xml_et.uuid_in_part_name()
- uuid_for_root(root_node)[source]¶
Returns the uuid for an object given an xml root node.
- Parameters
root_node – the xml root node for the object for which the uuid is required
- Returns
uuid.UUID for the specified object
- uuid_is_present(uuid)[source]¶
Returns True if the uuid is present in the model’s catalogue, False otherwise.
- uuids(parts_list=None, obj_type=None, uuid=None, title=None, title_mode='is', title_case_sensitive=False, metadata={}, extra={}, related_uuid=None, related_mode=None, epc_subdir=None, sort_by=None)[source]¶
Returns a list of uuids of parts matching all of the arguments passed.
- Parameters
parts ((as for) –
- Returns
list of uuids
- uuids_as_int_referenced_by_uuid(uuid)[source]¶
Returns set of ints being uuids of objects which uuid has a reference to.
Note
this method returns a set of ints; use olio.uuid.uuid_from_int() to get a UUID object
- uuids_as_int_referencing_uuid(uuid)[source]¶
Returns set of ints being uuids of objects which have a reference to uuid.
Note
this method returns a set of ints; use olio.uuid.uuid_from_int() to get a UUID object
Returns set of ints being uuids of objects related to uuid by any category of relationship.
Note
this method returns a set of ints; use olio.uuid.uuid_from_int() to get a UUID object
Returns set of ints being uuids of objects related to uuid by only a soft relationship.
Note
resqpy uses the term ‘soft relationship’ for those relationships held in the _rels xml area but not as reference nodes in the main xml of either part involved in the relationship; the Model.create_reciprocal_relationship() and create_reciprocal_relationship_uuid() methods can be used by application code to create such soft relationships; this method returns a set of ints; use olio.uuid.uuid_from_int() to get a UUID object