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, optional: Angle (in radians) from vertical of the axis of the borehole. Default is 0.
orientationfloat, optional: Direction (in radians) of the tilt of the borehole. Defaults to zero if the borehole is vertical. Default is 0.

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.dense_rectangle_field(N_1, N_2, B, H, D, r_b, include_last_borehole, tilt=0.0, origin=None)¶

Build a list of boreholes in a rectangular bore field configuration, with boreholes placed in a staggered configuration with uniform spacing between boreholes.

Parameters:

N_1int: Number of borehole in the x direction.
N_2int: Number of borehole in the y direction.
Bfloat: Distance (in meters) between adjacent boreholes.
Hfloat: Borehole length (in meters).
Dfloat: Borehole buried depth (in meters).
r_bfloat: Borehole radius (in meters).
include_last_boreholebool: If True, then each row of boreholes has equal numbers of boreholes. If False, then the staggered rows have one borehole less so they are contained within the imaginary ‘box’ around the borefield.
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,
        include_last_borehole=True)

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

  7    8
  4    5
  1    2

and if include_last_borehole is False:

  6    7
  4
  1    2

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.staggered_rectangle_field(N_1, N_2, B_1, B_2, H, D, r_b, include_last_borehole, tilt=0.0, origin=None)¶

Build a list of boreholes in a rectangular bore field configuration, with boreholes placed in a staggered 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).
include_last_boreholebool: If True, then each row of boreholes has equal numbers of boreholes. If False, then the staggered rows have one borehole less so they are contained within the imaginary ‘box’ around the borefield.
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=3, the bore field layout is as follows, if include_last_borehole is True:

  7    8
  4    5
  1    2

and if include_last_borehole is False:

  6    7
  4
  1    2

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

Borehole Module¶

Table of Contents

Previous topic

Next topic

This Page