Borehole Module¶

class pygfunction.boreholes.Borehole(H, D, r_b, x, y, tilt=0.0, orientation=0.0)¶

Bases: object

Contains information regarding the dimensions and position of a borehole.

Attributes

Hfloat: Borehole length (in meters).
Dfloat: Borehole buried depth (in meters).
r_bfloat: Borehole radius (in meters).
xfloat: Position (in meters) of the head of the borehole along the x-axis.
yfloat: Position (in meters) of the head of the borehole along the y-axis.
tiltfloat: Angle (in radians) from vertical of the axis of the borehole.
orientationfloat: Direction (in radians) of the tilt of the borehole.

distance(target)¶

Evaluate the distance between the current borehole and a target borehole.

Parameters

targetBorehole object: Target borehole for which the distance is evaluated.

Returns

disfloat: Distance (in meters) between current borehole and target borehole.

Note

The smallest distance returned is equal to the borehole radius. This means that the distance between a borehole and itself is equal to r_b.

Examples

>>> b1 = gt.boreholes.Borehole(H=150., D=4., r_b=0.075, x=0., y=0.)
>>> b2 = gt.boreholes.Borehole(H=150., D=4., r_b=0.075, x=5., y=0.)
>>> b1.distance(b2)
5.0

is_tilted()¶

Returns true if the borehole is inclined.

Returns

bool: True if borehole is inclined.

is_vertical()¶

Returns true if the borehole is vertical.

Returns

bool: True if borehole is vertical.

position()¶

Returns the position of the borehole.

Returns

postuple: Position (x, y) (in meters) of the borehole.

Examples

>>> b1 = gt.boreholes.Borehole(H=150., D=4., r_b=0.075, x=5., y=0.)
>>> b1.position()
(5.0, 0.0)

segments(nSegments, segment_ratios=None)¶

Split a borehole into segments.

Parameters

nSegmentsint: Number of segments.
segment_ratiosarray, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. The shape of the array is of (nSegments,). If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns

boreSegmentslist: List of borehole segments.

Examples

>>> b1 = gt.boreholes.Borehole(H=150., D=4., r_b=0.075, x=5., y=0.)
>>> b1.segments(5)

pygfunction.boreholes.L_shaped_field(N_1, N_2, B_1, B_2, H, D, r_b, tilt=0.0, origin=None)¶

Build a list of boreholes in a L-shaped bore field configuration.

Parameters

N_1int: Number of borehole in the x direction.
N_2int: Number of borehole in the y direction.
B_1float: Distance (in meters) between adjacent boreholes in the x direction.
B_2float: Distance (in meters) between adjacent boreholes in the y direction.
Hfloat: Borehole length (in meters).
Dfloat: Borehole buried depth (in meters).
r_bfloat: Borehole radius (in meters).
tiltfloat, optional: Angle (in radians) from vertical of the axis of the borehole. The orientation of the tilt is orthogonal to the origin coordinate. Default is 0.
origintuple, optional: A coordinate indicating the origin of reference for orientation of boreholes. Default is origin is placed at the center of an assumed rectangle.

Returns

boreFieldlist of Borehole objects: List of boreholes in the L-shaped bore field.

Notes

Boreholes located at the origin will remain vertical.

Examples

>>> boreField = gt.boreholes.L_shaped_field(N_1=3, N_2=2, B_1=5., B_2=5.,
                                            H=100., D=2.5, r_b=0.05)

The bore field is constructed line by line. For N_1=3 and N_2=2, the bore field layout is as follows:

3

0   1   2

pygfunction.boreholes.U_shaped_field(N_1, N_2, B_1, B_2, H, D, r_b, tilt=0.0, origin=None)¶

Build a list of boreholes in a U-shaped bore field configuration.

Parameters

N_1int: Number of borehole in the x direction.
N_2int: Number of borehole in the y direction.
B_1float: Distance (in meters) between adjacent boreholes in the x direction.
B_2float: Distance (in meters) between adjacent boreholes in the y direction.
Hfloat: Borehole length (in meters).
Dfloat: Borehole buried depth (in meters).
r_bfloat: Borehole radius (in meters).
tiltfloat, optional: Angle (in radians) from vertical of the axis of the borehole. The orientation of the tilt is orthogonal to the origin coordinate. Default is 0.
origintuple, optional: A coordinate indicating the origin of reference for orientation of boreholes. Default is the center considering an outer rectangle.

Returns

boreFieldlist of Borehole objects: List of boreholes in the U-shaped bore field.

Notes

Boreholes located at the origin will remain vertical.

Examples

>>> boreField = gt.boreholes.U_shaped_field(N_1=3, N_2=2, B_1=5., B_2=5.,
                                            H=100., D=2.5, r_b=0.05)

The bore field is constructed line by line. For N_1=3 and N_2=2, the bore field layout is as follows:

     4

 1   2

pygfunction.boreholes.box_shaped_field(N_1, N_2, B_1, B_2, H, D, r_b, tilt=0, origin=None)¶

Build a list of boreholes in a box-shaped bore field configuration.

Parameters

N_1int: Number of borehole in the x direction.
N_2int: Number of borehole in the y direction.
B_1float: Distance (in meters) between adjacent boreholes in the x direction.
B_2float: Distance (in meters) between adjacent boreholes in the y direction.
Hfloat: Borehole length (in meters).
Dfloat: Borehole buried depth (in meters).
r_bfloat: Borehole radius (in meters).
tiltfloat, optional: Angle (in radians) from vertical of the axis of the borehole. The orientation of the tilt is orthogonal to the origin coordinate. Default is 0.
origintuple, optional: A coordinate indicating the origin of reference for orientation of boreholes. Default is the center of the box.

Returns

boreFieldlist of Borehole objects: List of boreholes in the box-shaped bore field.

Notes

Boreholes located at the origin will remain vertical.

Examples

>>> boreField = gt.boreholes.box_shaped_field(N_1=4, N_2=3, B_1=5., B_2=5.,
                                              H=100., D=2.5, r_b=0.05)

The bore field is constructed line by line. For N_1=4 and N_2=3, the bore field layout is as follows:

pygfunction.boreholes.circle_field(N, R, H, D, r_b, tilt=0.0, origin=None)¶

Build a list of boreholes in a circular field configuration.

Parameters

Nint: Number of boreholes in the bore field.
Rfloat: Distance (in meters) of the boreholes from the center of the field.
Hfloat: Borehole length (in meters).
Dfloat: Borehole buried depth (in meters).
r_bfloat: Borehole radius (in meters).
tiltfloat, optional: Angle (in radians) from vertical of the axis of the borehole. The orientation of the tilt is towards the exterior of the bore field. Default is 0.
origintuple: A coordinate indicating the origin of reference for orientation of boreholes. Default is the origin (0, 0).

Returns

boreFieldlist of Borehole objects: List of boreholes in the circular shaped bore field.

Notes

Boreholes located at the origin will remain vertical.

Examples

>>> boreField = gt.boreholes.circle_field(N=8, R = 5., H=100., D=2.5,
                                          r_b=0.05)

The bore field is constructed counter-clockwise. For N=8, the bore field layout is as follows:

      2
  3       1

4           0

  5       7
      6

pygfunction.boreholes.field_from_file(filename)¶

Build a list of boreholes given coordinates and dimensions provided in a text file.

Parameters

filenamestr: Absolute path to text file.

Returns

boreFieldlist of Borehole objects: List of boreholes in the bore field.

Notes

The text file should be formatted as follows:

# x   y     H     D     r_b     tilt   orientation
   0.    100.  2.5   0.075   0.     0.
   0.    100.  2.5   0.075   0.     0.
   5.    100.  2.5   0.075   0.     0.
   10.   100.  2.5   0.075   0.     0.
   20.   100.  2.5   0.075   0.     0.

pygfunction.boreholes.find_duplicates(boreField, disp=False)¶

The distance method Borehole.distance() is utilized to find all duplicate boreholes in a boreField. This function considers a duplicate to be any pair of points that fall within each others radius. The lower index (i) is always stored in the 0 position of the tuple, while the higher index (j) is stored in the 1 position.

Parameters

boreFieldlist: A list of Borehole objects
dispbool, optional: Set to true to print progression messages. Default is False.

Returns

duplicate_pairslist: A list of tuples where the tuples are pairs of duplicates

pygfunction.boreholes.rectangle_field(N_1, N_2, B_1, B_2, H, D, r_b, tilt=0.0, origin=None)¶

Build a list of boreholes in a rectangular bore field configuration.

Parameters

N_1int: Number of borehole in the x direction.
N_2int: Number of borehole in the y direction.
B_1float: Distance (in meters) between adjacent boreholes in the x direction.
B_2float: Distance (in meters) between adjacent boreholes in the y direction.
Hfloat: Borehole length (in meters).
Dfloat: Borehole buried depth (in meters).
r_bfloat: Borehole radius (in meters).
tiltfloat, optional: Angle (in radians) from vertical of the axis of the borehole. The orientation of the tilt is orthogonal to the origin coordinate. Default is 0.
origintuple, optional: A coordinate indicating the origin of reference for orientation of boreholes. Default is the center of the rectangle.

Returns

boreFieldlist of Borehole objects: List of boreholes in the rectangular bore field.

Notes

Boreholes located at the origin will remain vertical.

Examples

>>> boreField = gt.boreholes.rectangle_field(N_1=3, N_2=2, B_1=5., B_2=5.,
                                             H=100., D=2.5, r_b=0.05)

The bore field is constructed line by line. For N_1=3 and N_2=2, the bore field layout is as follows:

 4   5

 1   2

pygfunction.boreholes.remove_duplicates(boreField, disp=False)¶

Removes all of the duplicates found from the duplicate pairs returned in check_duplicates().

For each pair of duplicates, the first borehole (with the lower index) is kept and the other (with the higher index) is removed.

Parameters

boreFieldlist: A list of Borehole objects
dispbool, optional: Set to true to print progression messages. Default is False.

Returns

new_boreFieldlist: A boreField without duplicates

pygfunction.boreholes.visualize_field(borefield, viewTop=True, view3D=True, labels=True, showTilt=True)¶

Plot the top view and 3D view of borehole positions.

Parameters

borefieldlist: List of boreholes in the bore field.
viewTopbool, optional: Set to True to plot top view. Default is True
view3Dbool, optional: Set to True to plot 3D view. Default is True
labelsbool, optional: Set to True to annotate borehole indices to top view plot. Default is True
showTiltbool, optional: Set to True to show borehole inclination on top view plot. Default is True

Returns

figfigure: Figure object (matplotlib).