Rename solar position inputs in tracking.singleaxis (#2480)

* Rename solar position inputs in tracking.singleaxis

* Update v0.13.1.rst

* Revert solar_zenith to apparent_zenith

* One more fix

* One more more fix

* Apply suggestions from code review

Co-authored-by: Kevin Anderson <[email protected]>

---------

Co-authored-by: Kevin Anderson <[email protected]>

Author: AdamRJensen

docs/examples/agrivoltaics/plot_agrivoltaics_ground_irradiance.py

@@ -59,7 +59,7 @@
 
 tracking_orientations = pvlib.tracking.singleaxis(
     apparent_zenith=solpos['apparent_zenith'],
-    apparent_azimuth=solpos['azimuth'],
+    solar_azimuth=solpos['azimuth'],
     axis_azimuth=axis_azimuth,
     max_angle=max_angle,
     backtrack=True,

docs/examples/shading/plot_martinez_shade_loss.py

@@ -90,7 +90,7 @@
 
 tracking_result = pvlib.tracking.singleaxis(
     apparent_zenith=solar_apparent_zenith,
-    apparent_azimuth=solar_azimuth,
+    solar_azimuth=solar_azimuth,
     axis_tilt=axis_tilt,
     axis_azimuth=axis_azimuth,
     max_angle=(-90 + cross_axis_tilt, 90 + cross_axis_tilt),  # (min, max)

docs/examples/solar-tracking/plot_single_axis_tracking.py

@@ -33,7 +33,7 @@
 
 truetracking_angles = tracking.singleaxis(
     apparent_zenith=solpos['apparent_zenith'],
-    apparent_azimuth=solpos['azimuth'],
+    solar_azimuth=solpos['azimuth'],
     axis_tilt=0,
     axis_azimuth=180,
     max_angle=90,
@@ -61,7 +61,7 @@
 for gcr in [0.2, 0.4, 0.6]:
     backtracking_angles = tracking.singleaxis(
         apparent_zenith=solpos['apparent_zenith'],
-        apparent_azimuth=solpos['azimuth'],
+        solar_azimuth=solpos['azimuth'],
         axis_tilt=0,
         axis_azimuth=180,
         max_angle=90,

docs/examples/solar-tracking/plot_single_axis_tracking_on_sloped_terrain.py

@@ -100,7 +100,7 @@
 for cross_axis_tilt in [0, 5, 10]:
     tracker_data = tracking.singleaxis(
         apparent_zenith=solpos['apparent_zenith'],
-        apparent_azimuth=solpos['azimuth'],
+        solar_azimuth=solpos['azimuth'],
         axis_tilt=0,  # flat because the axis is perpendicular to the slope
         axis_azimuth=180,  # N-S axis, azimuth facing south
         max_angle=90,
@@ -156,7 +156,7 @@
 
 tracker_data = tracking.singleaxis(
     apparent_zenith=solpos['apparent_zenith'],
-    apparent_azimuth=solpos['azimuth'],
+    solar_azimuth=solpos['azimuth'],
     axis_tilt=axis_tilt,  # no longer flat because the terrain imparts a tilt
     axis_azimuth=axis_azimuth,
     max_angle=90,

docs/sphinx/source/whatsnew/v0.13.1.rst

@@ -10,7 +10,8 @@ Breaking Changes
 
 Deprecations
 ~~~~~~~~~~~~
-
+* Rename parameter name ``aparent_azimuth`` to ``solar_azimuth`` in :py:func:`~pvlib.tracking.singleaxis`.
+  (:issue:`2479`, :pull:`2480`)
 
 Bug fixes
 ~~~~~~~~~

pvlib/tracking.py

@@ -4,9 +4,14 @@
 from pvlib.tools import cosd, sind, tand, acosd, asind
 from pvlib import irradiance
 from pvlib import shading
+from pvlib._deprecation import renamed_kwarg_warning
 
 
-def singleaxis(apparent_zenith, apparent_azimuth,
+@renamed_kwarg_warning(
+    since='0.13.1',
+    old_param_name='apparent_azimuth',
+    new_param_name='solar_azimuth')
+def singleaxis(apparent_zenith, solar_azimuth,
                axis_tilt=0, axis_azimuth=0, max_angle=90,
                backtrack=True, gcr=2.0/7.0, cross_axis_tilt=0):
     """
@@ -33,7 +38,7 @@ def singleaxis(apparent_zenith, apparent_azimuth,
     apparent_zenith : float, 1d array, or Series
         Solar apparent zenith angles in decimal degrees.
 
-    apparent_azimuth : float, 1d array, or Series
+    solar_azimuth : float, 1d array, or Series
         Solar apparent azimuth angles in decimal degrees.
 
     axis_tilt : float, default 0
@@ -123,10 +128,10 @@ def singleaxis(apparent_zenith, apparent_azimuth,
         index = None
 
     # convert scalars to arrays
-    apparent_azimuth = np.atleast_1d(apparent_azimuth)
+    solar_azimuth = np.atleast_1d(solar_azimuth)
     apparent_zenith = np.atleast_1d(apparent_zenith)
 
-    if apparent_azimuth.ndim > 1 or apparent_zenith.ndim > 1:
+    if solar_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
@@ -142,7 +147,7 @@ def singleaxis(apparent_zenith, apparent_azimuth,
         axis_tilt=axis_tilt,
         axis_azimuth=axis_azimuth,
         solar_zenith=apparent_zenith,
-        solar_azimuth=apparent_azimuth,
+        solar_azimuth=solar_azimuth,
     )
 
     # filter for sun above panel horizon
@@ -191,7 +196,7 @@ def singleaxis(apparent_zenith, apparent_azimuth,
     surface_tilt = surface['surface_tilt']
     surface_azimuth = surface['surface_azimuth']
     aoi = irradiance.aoi(surface_tilt, surface_azimuth,
-                         apparent_zenith, apparent_azimuth)
+                         apparent_zenith, solar_azimuth)
 
     # Bundle DataFrame for return values and filter for sun below horizon.
     out = {'tracker_theta': tracker_theta, 'aoi': aoi,