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:

crs_root

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.

h5_release()

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.

iter_wellbore_interpretations()

Iterable of all WellboreInterpretations associated with the model.

iter_trajectories()

Iterable of all trajectories associated with the model.

iter_md_datums()

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:

initialize()

Set model contents to empty.

uuid_is_present(uuid)

Returns True if the uuid is present in the model's catalogue, False otherwise.

set_modified()

Marks the model as having been modified and assigns a new uuid.

uuids_as_int_related_to_uuid(uuid)

Returns set of ints being uuids of objects related to uuid by any category of relationship.

uuids_as_int_referenced_by_uuid(uuid)

Returns set of ints being uuids of objects which uuid has a reference to.

uuids_as_int_referencing_uuid(uuid)

Returns set of ints being uuids of objects which have a reference to uuid.

uuids_as_int_softly_related_to_uuid(uuid)

Returns set of ints being uuids of objects related to uuid by only a soft relationship.

create_tree_if_none()

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.

remove_part_from_main_tree(part)

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.

number_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.

parts_count_dict()

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.

supporting_representation_for_part(part)

Returns the uuid of the supporting representation for the part, if found, otherwise None.

parts_list_filtered_by_supporting_uuid(...)

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.

external_parts_list()

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.

change_uuid_in_supporting_representation_reference(...)

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.

grid_list_uuid_list()

Returns list of uuid's for the grid objects in the cached grid list.

grid_for_uuid_from_grid_list(uuid)

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.

h5_clear_filename_cache()

Clears the cached filenames associated with all ext uuids.

create_root()

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.

create_rels_part()

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.

create_supporting_representation([...])

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_consolidation_uuid_equivalence(...)

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.

iter_grid_connection_sets()

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

citation_title_for_part(part)[source]

Returns the citation title for the specified part.

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.

grid_list_uuid_list()[source]

Returns list of uuid’s for the grid objects in the cached grid list.

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_clear_filename_cache()[source]

Clears the cached filenames associated with all ext uuids.

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_release()[source]

Releases (closes) the currently open hdf5 file.

Returns

None

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()[source]

Returns the uuid of the ‘main’ hdf5 file.

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.

initialize()[source]

Set model contents to empty.

Note

not usually called directly (semi-private)

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

list_of_parts(only_objects=True)[source]

Return a complete list of parts.

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