Add reference to tracking.singleaxis (#2198)

* Update tracking.py Added reference where omega_ideal is used minor edits e.g. adding `` `` around function arguments * Update tracking.py * Update tracking.py degree->degrees * Update pvlib/tracking.py Co-authored-by: Kevin Anderson <[email protected]> * linter, one more `` --------- Co-authored-by: Kevin Anderson <[email protected]>
pvlib · Sep 9, 2024 · a14e95e · a14e95e
1 parent 524fa55
commit a14e95e
Showing 1 changed file with 37 additions and 35 deletions.
diff --git a/pvlib/tracking.py b/pvlib/tracking.py
@@ -13,20 +13,20 @@ def singleaxis(apparent_zenith, apparent_azimuth,
     Determine the rotation angle of a single-axis tracker when given particular
     solar zenith and azimuth angles.
 
-    See [1]_ for details about the equations. Backtracking may be specified,
-    and if so, a ground coverage ratio is required.
+    See [1]_ and [2]_ for details about the equations. Backtracking may be
+    specified, in which case a ground coverage ratio is required.
 
     Rotation angle is determined in a right-handed coordinate system. The
-    tracker `axis_azimuth` defines the positive y-axis, the positive x-axis is
-    90 degrees clockwise from the y-axis and parallel to the Earth's surface,
-    and the positive z-axis is normal to both x & y-axes and oriented skyward.
-    Rotation angle `tracker_theta` is a right-handed rotation around the y-axis
-    in the x, y, z coordinate system and indicates tracker position relative to
-    horizontal. For example, if tracker `axis_azimuth` is 180 (oriented south)
-    and `axis_tilt` is zero, then a `tracker_theta` of zero is horizontal, a
-    `tracker_theta` of 30 degrees is a rotation of 30 degrees towards the west,
-    and a `tracker_theta` of -90 degrees is a rotation to the vertical plane
-    facing east.
+    tracker ``axis_azimuth`` defines the positive y-axis, the positive x-axis
+    is 90 degrees clockwise from the y-axis and parallel to the Earth's
+    surface, and the positive z-axis is normal to both x and y-axes and
+    oriented skyward. Rotation angle ``tracker_theta`` is a right-handed
+    rotation around the y-axis in the x, y, z coordinate system and indicates
+    tracker position relative to horizontal. For example, if tracker
+    ``axis_azimuth`` is 180 (oriented south) and ``axis_tilt`` is zero, then a
+    ``tracker_theta`` of zero is horizontal, a ``tracker_theta`` of 30 degrees
+    is a rotation of 30 degrees towards the west, and a ``tracker_theta`` of
+    -90 degrees is a rotation to the vertical plane facing east.
 
     Parameters
     ----------
@@ -39,7 +39,7 @@ def singleaxis(apparent_zenith, apparent_azimuth,
     axis_tilt : float, default 0
         The tilt of the axis of rotation (i.e, the y-axis defined by
         ``axis_azimuth``) with respect to horizontal.
-        ``axis_tilt`` must be >= 0 and <= 90. [degree]
+        ``axis_tilt`` must be >= 0 and <= 90. [degrees]
 
     axis_azimuth : float, default 0
         A value denoting the compass direction along which the axis of
@@ -53,37 +53,37 @@ def singleaxis(apparent_zenith, apparent_azimuth,
         opposite of the maximum angle. If a tuple of (min_angle, max_angle) is
         provided, it represents both the minimum and maximum rotation angles.
 
-        A rotation to 'max_angle' is a counter-clockwise rotation about the
+        A rotation to ``max_angle`` is a counter-clockwise rotation about the
         y-axis of the tracker coordinate system. For example, for a tracker
-        with 'axis_azimuth' oriented to the south, a rotation to 'max_angle'
-        is towards the west, and a rotation toward 'min_angle' is in the
-        opposite direction, toward the east. Hence a max_angle of 180 degrees
-        (equivalent to max_angle = (-180, 180)) allows the tracker to achieve
-        its full rotation capability.
+        with ``axis_azimuth`` oriented to the south, a rotation to
+        ``max_angle`` is towards the west, and a rotation toward ``-max_angle``
+        is in the opposite direction, toward the east. Hence, a ``max_angle``
+        of 180 degrees (equivalent to max_angle = (-180, 180)) allows the
+        tracker to achieve its full rotation capability.
 
     backtrack : bool, default True
         Controls whether the tracker has the capability to "backtrack"
         to avoid row-to-row shading. False denotes no backtrack
         capability. True denotes backtrack capability.
 
     gcr : float, default 2.0/7.0
-        A value denoting the ground coverage ratio of a tracker system
-        which utilizes backtracking; i.e. the ratio between the PV array
-        surface area to total ground area. A tracker system with modules
-        2 meters wide, centered on the tracking axis, with 6 meters
-        between the tracking axes has a gcr of 2/6=0.333. If gcr is not
-        provided, a gcr of 2/7 is default. gcr must be <=1.
+        A value denoting the ground coverage ratio of a tracker system that
+        utilizes backtracking; i.e. the ratio between the PV array surface area
+        to the total ground area. A tracker system with modules 2 meters wide,
+        centered on the tracking axis, with 6 meters between the tracking axes
+        has a ``gcr`` of 2/6=0.333. If ``gcr`` is not provided, a ``gcr`` of
+        2/7 is default. ``gcr`` must be <=1.
 
     cross_axis_tilt : float, default 0.0
         The angle, relative to horizontal, of the line formed by the
         intersection between the slope containing the tracker axes and a plane
-        perpendicular to the tracker axes. Cross-axis tilt should be specified
-        using a right-handed convention. For example, trackers with axis
-        azimuth of 180 degrees (heading south) will have a negative cross-axis
-        tilt if the tracker axes plane slopes down to the east and positive
-        cross-axis tilt if the tracker axes plane slopes down to the west. Use
-        :func:`~pvlib.tracking.calc_cross_axis_tilt` to calculate
-        `cross_axis_tilt`. [degrees]
+        perpendicular to the tracker axes. The cross-axis tilt should be
+        specified using a right-handed convention. For example, trackers with
+        axis azimuth of 180 degrees (heading south) will have a negative
+        cross-axis tilt if the tracker axes plane slopes down to the east and
+        positive cross-axis tilt if the tracker axes plane slopes down to the
+        west. Use :func:`~pvlib.tracking.calc_cross_axis_tilt` to calculate
+        ``cross_axis_tilt``. [degrees]
 
     Returns
     -------
@@ -107,9 +107,11 @@ def singleaxis(apparent_zenith, apparent_azimuth,
 
     References
     ----------
-    .. [1] Kevin Anderson and Mark Mikofski, "Slope-Aware Backtracking for
+    .. [1] Anderson, K., and Mikofski, M., "Slope-Aware Backtracking for
        Single-Axis Trackers", Technical Report NREL/TP-5K00-76626, July 2020.
        https://www.nrel.gov/docs/fy20osti/76626.pdf
+    .. [2] Lorenzo, E., Narvarte, L., and Muñoz, J. (2011). Tracking and
+       back-tracking 19(6), 747–753. :doi:`10.1002/pip.1085`
     """
 
     # MATLAB to Python conversion by
@@ -127,9 +129,9 @@ def singleaxis(apparent_zenith, apparent_azimuth,
     if apparent_azimuth.ndim > 1 or apparent_zenith.ndim > 1:
         raise ValueError('Input dimensions must not exceed 1')
 
-    # The ideal tracking angle omega_ideal is the rotation to place the sun
+    # The ideal tracking angle, omega_ideal, is the rotation to place the sun
     # position vector (xp, yp, zp) in the (x, z) plane, which is normal to
-    # the panel and contains the axis of rotation.  omega_ideal= 0 indicates
+    # the panel and contains the axis of rotation. omega_ideal=0 indicates
     # that the panel is horizontal. Here, our convention is that a clockwise
     # rotation is positive, to view rotation angles in the same frame of
     # reference as azimuth. For example, for a system with tracking