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
well_name	Alias for title

Inherited from BaseResqpy

resqml_type
part	Standard part name corresponding to self.uuid.
root	XML node corresponding to self.uuid.
citation_title	Citation block title equivalent to self.title.

Commonly Used Methods:

__init__(parent_model[, uuid, crs_uuid, ...])	Creates a new trajectory object and optionally loads it from xml, deviation survey, pandas dataframe, or
iter_wellbore_frames()	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.
inclinations()	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.
set_measured_depths()	Sets the measured depths from the start_md value and the control points.
create_feature_and_interpretation()	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
try_reuse()	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)

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)

Derive wellbore trajectory from deviation survey azimuth and inclination data.

create_feature_and_interpretation()

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)

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')

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

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

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)

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')

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)

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')

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

Sets the measured depths from the start_md value and the control points.

set_tangents(force=False, write_hdf5=False, weight='cube')

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)

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')

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')

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)

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