From cbf728cd96cab1606d63990e3f137cff99ace892 Mon Sep 17 00:00:00 2001 From: Matt Mitchell Date: Tue, 12 Nov 2024 10:05:53 -0700 Subject: [PATCH] add docstrings and other documenting comments --- pygfunction/api.py | 41 ++++++++++++++++++++++++----------------- tests/test_api.py | 5 ++++- 2 files changed, 28 insertions(+), 18 deletions(-) diff --git a/pygfunction/api.py b/pygfunction/api.py index f4b41e3..43389cd 100644 --- a/pygfunction/api.py +++ b/pygfunction/api.py @@ -1,7 +1,7 @@ from pygfunction.gfunction import gFunction from pygfunction.boreholes import Borehole -from typing import Union, List, Tuple, Dict, Iterable +from typing import Union, List, Tuple, Dict FloatOrList = Union[float, List[float]] @@ -10,13 +10,13 @@ class BoreholeFieldParameters: """This class represents the borehole field and can generate inputs for pygfunction""" def __init__(self): - self.height_list: List[float] = [] # TODO: Document the units - self.depth_list: List[float] = [] - self.bh_radius_list: List[float] = [] - self.tilt_angle_list: List[float] = [] # TODO: Is this degrees? And I assume from vertical? - self.orientation_angle_list: List[float] = [] # TODO: Same question - self.x_coords: List[float] = [] # TODO: What are the units here, I'm assuming meters - self.y_coords: List[float] = [] # TODO: Same question + self.height_list: List[float] = [] # list of borehole heights, in meters + self.depth_list: List[float] = [] # list of depth of borehole head, in meters + self.bh_radius_list: List[float] = [] # list of borehole radii + self.tilt_angle_list: List[float] = [] # list of borehole tilt angles from vertical, in radians + self.orientation_angle_list: List[float] = [] # list of direction of borehole tilt angles, in radians + self.x_coords: List[float] = [] # list of borehole x-axis coordinates, in meters + self.y_coords: List[float] = [] # list of borehole y-axis coordinates, in meters def initialize_borehole_field_generic( self, xy_coord_pairs: List[Tuple[float, float]], @@ -28,16 +28,23 @@ def initialize_borehole_field_generic( Any scalar arguments are extended to the size of the coordinates list to cover each borehole. List arguments must be sized to match the size of the coordinate list. - Parameters + Attributes ---------- - xy_coord_pairs - height - depth - borehole_radius - tilt_angle - orientation_angle - - Returns + xy_coord_pairs: list[tuple[float, float]] or list[list[float, float]] + Position (in meters) of the head of the borehole along the x- and y-axis. + height : float + Borehole length (in meters). + depth : float + Borehole buried depth (in meters). + borehole_radius : float + Borehole radius (in meters). + tilt_angle : float, optional + Angle (in radians) from vertical of the axis of the borehole. + Default is 0. + orientation_angle : float, optional + Direction (in radians) of the tilt of the borehole. Defaults to zero + if the borehole is vertical. + Default is 0. ------- """ diff --git a/tests/test_api.py b/tests/test_api.py index b2fc1a9..acf5cf0 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -34,6 +34,8 @@ def setUp(self): 15.103960182529738, 15.135243749367413, 15.185795927543893 ] + self.deg_to_rad = np.pi / 180 + def test_compute_vertical_g_functions_from_api(self): def run_test(xy): # compute g-functions @@ -66,7 +68,8 @@ def test_compute_inclined_g_functions_from_api(self): # compute g-functions bh_field_params = BoreholeFieldParameters() bh_field_params.initialize_borehole_field_generic( - xy_coords, self.height, self.depth, self.bh_radius, tilt_angle=20, orientation_angle=20 + xy_coords, self.height, self.depth, self.bh_radius, + tilt_angle=20*self.deg_to_rad, orientation_angle=20*self.deg_to_rad ) g = GFunctionGenerator(bh_field_params, self.alpha, self.time, solver_method="detailed")