resqpy.well.Trajectory¶
- class resqpy.well.Trajectory(parent_model, uuid=None, crs_uuid=None, md_datum=None, deviation_survey=None, data_frame=None, grid=None, cell_kji0_list=None, wellspec_file=None, spline_mode='cube', ascii_trajectory_file=None, survey_file_space_separated=False, length_uom=None, md_domain=None, represented_interp=None, well_name=None, set_tangent_vectors=False, hdf5_source_model=None, originator=None, extra_metadata=None)¶
Bases:
BaseResqpy
Class for RESQML Wellbore Trajectory Representation (Geometry).
Note
resqml allows trajectory to have different crs to the measured depth datum crs; however, this code requires the trajectory to be in the same crs as the md datum
Public Data Attributes:
resqml_type
Alias for title
Inherited from
BaseResqpy
resqml_type
Standard part name corresponding to self.uuid.
XML node corresponding to self.uuid.
Citation block title equivalent to self.title.
Commonly Used Methods:
__init__
(parent_model[, uuid, crs_uuid, ...])Creates a new trajectory object and optionally loads it from xml, deviation survey, pandas dataframe, or
Iterable of all WellboreFrames associated with a trajectory.
dataframe
([md_col, x_col, y_col, z_col])Returns a pandas data frame containing MD and control points (xyz) data.
xyz_for_md
(md)Returns xyz corresponding to the given measured depth; uses simple linear interpolation between knots.
create_xml
([ext_uuid, wbt_uuid, ...])Create a wellbore trajectory representation node from a Trajectory object, optionally add as part.
write_hdf5
([file_name, mode])Create or append to an hdf5 file, writing datasets for the measured depths, control points and tangent
Methods:
compute_from_deviation_survey
([survey, ...])Derive wellbore trajectory from deviation survey azimuth and inclination data.
load_from_data_frame
(data_frame[, md_col, ...])Load MD and control points (xyz) data from a pandas data frame.
load_from_cell_list
(grid, cell_kji0_list[, ...])Loads the trajectory object based on the centre points of a list of cells.
load_from_wellspec
(grid, wellspec_file, ...)Sets the trajectory data based on visiting the cells identified in a Nexus wellspec keyword.
load_from_ascii_file
(trajectory_file[, ...])Loads the trajectory object from an ascii file with columns for MD, X, Y & Z (and optionally WELL).
set_tangents
([force, write_hdf5, weight])Calculates tangent vectors based on control points.
write_to_ascii_file
(trajectory_file[, mode, ...])Writes trajectory to an ascii file.
Returns a numpy array of inclinations in degrees, zero being vertical, with a value per interval.
splined_trajectory
(well_name[, ...])Creates and returns a new Trajectory derived as a cubic spline of this trajectory.
Sets the measured depths from the start_md value and the control points.
Instantiate new empty WellboreFeature and WellboreInterpretation objects, if a wellboreinterpretation does
__eq__
(other)Implements equals operator.
Inherited from
BaseResqpy
__init__
(parent_model[, uuid, crs_uuid, ...])Creates a new trajectory object and optionally loads it from xml, deviation survey, pandas dataframe, or
Look for an equivalent existing RESQML object and modify the uuid of this object if found.
create_xml
([ext_uuid, wbt_uuid, ...])Create a wellbore trajectory representation node from a Trajectory object, optionally add as part.
append_extra_metadata
(meta_dict)Append a given dictionary of metadata to the existing metadata.
__eq__
(other)Implements equals operator.
__ne__
(other)Implements not equal operator.
__repr__
()String representation.
- __init__(parent_model, uuid=None, crs_uuid=None, md_datum=None, deviation_survey=None, data_frame=None, grid=None, cell_kji0_list=None, wellspec_file=None, spline_mode='cube', ascii_trajectory_file=None, survey_file_space_separated=False, length_uom=None, md_domain=None, represented_interp=None, well_name=None, set_tangent_vectors=False, hdf5_source_model=None, originator=None, extra_metadata=None)[source]¶
Creates a new trajectory object and optionally loads it from xml, deviation survey, pandas dataframe, or
ascii file.
- Parameters
parent_model (model.Model object) – the model which the new trajectory belongs to
uuid (UUID, optional) – if present, the Trajectory is initialised from xml for an existing RESQML object and the remaining arguments are mostly ignored
crs_uuid (UUID, optional) – the uuid of a Crs object to use when generating a new trajectory
md_datum (MdDatum object) – the datum that the depths for this trajectory are measured from; not used if uuid is not None
deviation_survey (DeviationSurvey object, optional) – if present and uuid is None then the trajectory is derived from the deviation survey based on minimum curvature
data_frame (optional) – a pandas dataframe with columns ‘MD’, ‘X’, ‘Y’ and ‘Z’, holding the measured depths, and corresponding node locations; ignored if uuid is not None
grid (grid.Grid object, optional) – only required if initialising from a list of cell indices; ignored otherwise
cell_kji0_list (numpy int array of shape (N, 3)) – ordered list of cell indices to be visited by the trajectory; ignored if uuid is not None
wellspec_file (string, optional) – name of an ascii file containing Nexus WELLSPEC data; well_name and length_uom arguments must be passed
spline_mode (string, default 'cube') – one of ‘none’, ‘linear’, ‘square’, or ‘cube’; affects spline tangent generation; only relevant if initialising from list of cells
ascii_trajectory_file (string) – filename of an ascii file holding the trajectory in a tabular form; ignored if uuid is not None
survey_file_space_separated (boolean, default False) – if True, deviation survey file is space separated; if False, comma separated (csv); ignored unless loading from survey file
length_uom (string, default 'm') – a resqml length unit of measure applicable to the measured depths; should be ‘m’ or ‘ft’
md_domain (string, optional) – if present, must be ‘logger’ or ‘driller’; the source of the original deviation data; ignored if uuid is not None
represented_interp (wellbore interpretation object, optional) – if present, is noted as the wellbore interpretation object which this trajectory relates to; ignored if uuid is not None
well_name (string, optional) – used as citation title
set_tangent_vectors (boolean, default False) – if True and tangent vectors are not loaded then they will be computed from the control points
hdf5_source_model (model.Model, optional) – if present this model is used to determine the hdf5 file name from which to load the trajectory’s array data; if None, the parent_model is used as usual
originator (str, optional) – the name of the person creating the trajectory, defaults to login id; ignored if uuid is not None
extra_metadata (dict, optional) – string key, value pairs to add as extra metadata for the trajectory; ignored if uuid is not None
- Returns
the newly created wellbore trajectory object
Notes
if starting from a deviation survey file, there are two routes: create a deviation survey object first, using the azimuth and inclination data, then generate a trajectory from that based on minimum curvature; or, create a trajectory directly using X, Y, Z data from the deviation survey file (ie. minimum curvature or other algorithm already applied externally); if not loading from xml, then the crs is set to that used by the measured depth datum, or if that is not available then the default crs for the model
- append_extra_metadata(meta_dict)¶
Append a given dictionary of metadata to the existing metadata.
- property citation_title¶
Citation block title equivalent to self.title.
- compute_from_deviation_survey(survey=None, method='minimum curvature', md_domain=None, set_tangent_vectors=True)[source]¶
Derive wellbore trajectory from deviation survey azimuth and inclination data.
- create_feature_and_interpretation()[source]¶
Instantiate new empty WellboreFeature and WellboreInterpretation objects, if a wellboreinterpretation does
not already exist.
Uses the trajectory citation title as the well name
- create_xml(ext_uuid=None, wbt_uuid=None, md_datum_root=None, md_datum_xyz=None, add_as_part=True, add_relationships=True, title=None, originator=None)[source]¶
Create a wellbore trajectory representation node from a Trajectory object, optionally add as part.
Notes
measured depth datum xml node must be in place before calling this function; branching well structures (multi-laterals) are supported by the resqml standard but not yet by this code; optional witsml trajectory reference not yet supported here
- dataframe(md_col='MD', x_col='X', y_col='Y', z_col='Z')[source]¶
Returns a pandas data frame containing MD and control points (xyz) data.
Note
set md_col to None for a dataframe containing only X, Y & Z data
- inclinations()[source]¶
Returns a numpy array of inclinations in degrees, zero being vertical, with a value per interval.
Note
this method returns inclinations of piecewise linear line segments between control points; calling code can alternatively use the tangent vectors at knots to derive similar information
- iter_wellbore_frames()[source]¶
Iterable of all WellboreFrames associated with a trajectory.
- Yields
frame – instance of
resqpy.organize.WellboreFrame
- load_from_ascii_file(trajectory_file, comment_character='#', space_separated_instead_of_csv=False, md_col='MD', x_col='X', y_col='Y', z_col='Z', md_uom='m', md_domain=None, md_datum=None, well_col=None, title=None, set_tangent_vectors=True)[source]¶
Loads the trajectory object from an ascii file with columns for MD, X, Y & Z (and optionally WELL).
- load_from_cell_list(grid, cell_kji0_list, spline_mode='cube', md_uom='m')[source]¶
Loads the trajectory object based on the centre points of a list of cells.
- load_from_data_frame(data_frame, md_col='MD', x_col='X', y_col='Y', z_col='Z', md_uom='m', md_domain=None, md_datum=None, title=None, set_tangent_vectors=True)[source]¶
Load MD and control points (xyz) data from a pandas data frame.
- load_from_wellspec(grid, wellspec_file, well_name, spline_mode='cube', md_uom='m')[source]¶
Sets the trajectory data based on visiting the cells identified in a Nexus wellspec keyword.
- property part¶
Standard part name corresponding to self.uuid.
- property root¶
XML node corresponding to self.uuid.
- set_measured_depths()[source]¶
Sets the measured depths from the start_md value and the control points.
- set_tangents(force=False, write_hdf5=False, weight='cube')[source]¶
Calculates tangent vectors based on control points.
- Parameters
force (boolean, default False) – if False and tangent vectors already exist then the existing ones are used; if True or no tangents vectors exist then they are computed
write_hdf5 (boolean, default False) – if True and new tangent vectors are computed then the array is also written directly to the hdf5 file
weight (string, default 'linear') – one of ‘linear’, ‘square’, ‘cube’; if linear, each tangent is the mean of the direction vectors of the two trjectory segments which meet at the knot; the square and cube options give increased weight to the direction vector of shorter segments (usually better)
- Returns
numpy float array of shape (knot_count, 3) being the tangents in xyz, ‘pointing’ in the direction of increased knot index; the tangents are also stored as an attribute of the object
Note
the write_hdf5() method writes all the array data for the trajectory, including the tangent vectors; only set the write_hdf5 argument to this method to True if the other arrays for the trajectory already exist in the hdf5 file
- splined_trajectory(well_name, min_subdivisions=1, max_segment_length=None, max_degrees_per_knot=5.0, use_tangents_if_present=True, store_tangents_if_calculated=True)[source]¶
Creates and returns a new Trajectory derived as a cubic spline of this trajectory.
- Parameters
well_name (string) – the name to use as the citation title for the new trajectory
min_subdivisions (+ve integer, default 1) – the minimum number of segments in the trajectory for each segment in this trajectory
max_segment_length (float, optional) – if present, each segment of this trajectory is subdivided so that the naive subdivided length is not greater than the specified length
max_degrees_per_knot (float, default 5.0) – the maximum number of degrees
use_tangents_if_present (boolean, default False) – if True, any tangent vectors in this trajectory are used during splining
store_tangents_if_calculated (boolean, default True) – if True any tangents calculated by the method are stored in the object (causing any previous tangents to be discarded); however, the new tangents are not written to the hdf5 file by this method
- Returns
Trajectory object with control points lying on a cubic spline of the points of this trajectory
Notes
this method is typically used to smoothe an artificial or simulator trajectory; measured depths are re-calculated and will differ from those in this trajectory; unexpected behaviour may occur if the z units are different from the xy units in the crs; if tangent vectors for neighbouring points in this trajectory are pointing in opposite directions, the resulting spline is likely to be bad; the max_segment_length is applied when deciding how many subdivisions to make for a segment in this trajectory, based on the stright line segment length; segments in the resulting spline may exceed this length; similarly max_degrees_per_knot assumes a simply bend between neighbouring knots; if the position of the control points results in a loop, the value may be exceeded in the spline; the hdf5 data for the splined trajectory is not written by this method, neither is the xml created; no interpretation object is created by this method NB: direction of tangent vectors affects results, set use_tangents_if_present = False to ensure locally calculated tangent vectors are used
- try_reuse()¶
Look for an equivalent existing RESQML object and modify the uuid of this object if found.
- Returns
boolean – True if an equivalent object was found, False if not
Note
by design this method may change this object’s uuid as a side effect
- property well_name¶
Alias for title
- write_hdf5(file_name=None, mode='a')[source]¶
Create or append to an hdf5 file, writing datasets for the measured depths, control points and tangent
vectors.
- write_to_ascii_file(trajectory_file, mode='w', space_separated_instead_of_csv=False, md_col='MD', x_col='X', y_col='Y', z_col='Z')[source]¶
Writes trajectory to an ascii file.
Note
set md_col to None for a dataframe containing only X, Y & Z data
- xyz_for_md(md)[source]¶
Returns xyz corresponding to the given measured depth; uses simple linear interpolation between knots.
- Parameters
md (float) – measured depth for which xyz location is required; units must be those of self.md_uom
- Returns
triple float being x, y, z coordinates of point on trajectory corresponding to given measured depth
Note
the algorithm uses a simple linear interpolation between neighbouring knots (control points) on the trajectory; if the measured depth is less than zero or greater than the finish md, a single None is returned; if the md is less than the start md then a linear interpolation between the md datum location and the first knot is returned
- title¶
Citation title
- originator¶
Creator of object. By default, user id.
- uuid¶
Unique identifier