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