Change more instances of tilt to slope and update descriptions/depr. versions

Author: echedey-ls

docs/examples/solar-tracking/plot_single_axis_tracking_on_sloped_terrain.py

@@ -77,7 +77,7 @@
 # ---------------
 #
 # Now, let's plot the simple case where the tracker axes are at right angles
-# to the direction of the slope.  In this case, the cross-axis tilt angle
+# to the direction of the slope.  In this case, the cross-axis slope angle
 # is the same as the slope of the terrain and the tracker axis itself is
 # horizontal.
 
@@ -110,7 +110,7 @@
 
     # tracker rotation is undefined at night
     backtracking_position = tracker_data['tracker_theta'].fillna(0)
-    label = 'cross-axis tilt: {}°'.format(cross_axis_slope)
+    label = 'cross-axis slope: {}°'.format(cross_axis_slope)
     backtracking_position.plot(label=label, ax=ax)
 
 plt.legend()
@@ -129,8 +129,8 @@
 # with north-south axes on terrain that slopes down to the south-south-east.
 # Assuming the axes are installed parallel to the ground, the northern ends
 # of the axes will be higher than the southern ends. But because the slope
-# isn't purely parallel or perpendicular to the axes, the axis tilt and
-# cross-axis tilt angles are not immediately obvious. We can use pvlib
+# isn't purely parallel or perpendicular to the axes, the axis slope and
+# cross-axis slope angles are not immediately obvious. We can use pvlib
 # to calculate them for us:
 
 # terrain slopes 10 degrees downward to the south-south-east. note: because
@@ -140,15 +140,15 @@
 slope_tilt = 10
 axis_azimuth = 180  # tracker axis is still N-S
 
-# calculate the tracker axis tilt, assuming that the axis follows the terrain:
+# calculate the tracker axis slope, assuming that the axis follows the terrain:
 axis_slope = tracking.calc_axis_slope(slope_azimuth, slope_tilt, axis_azimuth)
 
-# calculate the cross-axis tilt:
+# calculate the cross-axis slope:
 cross_axis_slope = tracking.calc_cross_axis_slope(slope_azimuth, slope_tilt,
                                                   axis_azimuth, axis_slope)
 
-print('Axis tilt:', '{:0.01f}°'.format(axis_slope))
-print('Cross-axis tilt:', '{:0.01f}°'.format(cross_axis_slope))
+print('Axis slope:', '{:0.01f}°'.format(axis_slope))
+print('Cross-axis slope:', '{:0.01f}°'.format(cross_axis_slope))
 
 # %%
 # And now we can pass use these values to generate the tracker curve as
@@ -167,7 +167,7 @@
 backtracking_position = tracker_data['tracker_theta'].fillna(0)
 backtracking_position.plot()
 
-title_template = 'Axis tilt: {:0.01f}°   Cross-axis tilt: {:0.01f}°'
+title_template = 'Axis slope: {:0.01f}°   Cross-axis slope: {:0.01f}°'
 plt.title(title_template.format(axis_slope, cross_axis_slope))
 plt.show()
 

docs/sphinx/source/user_guide/extras/nomenclature.rst

@@ -69,14 +69,15 @@ There is a convention on consistent variable names throughout the library:
 
     cross_axis_slope
         Cross-axis slope angle. [°]
+
         The angle, relative to horizontal, of the line between the axes of two
         adjacent trackers, in the plane perpendicular to the tracker axes.
         Cross-axis slope should be specified using a right-handed convention.
-
-        For example, trackers with axis azimuth of 180° (N-S rotation axis)
+        
+        For example, trackers whose axis azimuth is 180° (N-S rotation axis)
         will have a negative cross-axis slope if the tracker axes plane slopes
-        down to the east and positive cross-axis slope if the tracker axes plane
-        slopes up to the east.
+        down to the east and positive cross-axis slope if the tracker axes
+        plane slopes down to the west.
 
         .. figure:: ../../_images/Anderson_Mikofski_2020_Fig4.png
             :alt: Two rows of modules, tracker coordinate system and cross-axis slope of the second row w.r.t. the leftmost.

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

@@ -10,7 +10,17 @@ Breaking Changes
 
 Deprecations
 ~~~~~~~~~~~~
+* Rename ``axis_tilt`` and ``cross_axis_tilt`` to ``axis_slope`` and ``cross_axis_slope`` all through the project, while keeping backwards-compatibility. Affects:
 
+  - :py:func:`pvlib.shading.shaded_fraction1d` parameters ``cross_axis_tilt`` and ``axis_tilt``
+  - :py:func:`pvlib.shading.projected_solar_zenith_angle` parameter ``axis_tilt``
+  - :py:func:`pvlib.tracking.singleaxis` parameters ``cross_axis_tilt`` and ``axis_tilt``
+  - :py:func:`pvlib.tracking.calc_surface_orientation` parameter ``axis_tilt``
+  - :py:func:`!pvlib.tracking.calc_axis_tilt` function is renamed to :py:func:`~pvlib.tracking.calc_axis_slope`
+  - :py:func:`!pvlib.tracking.calc_cross_axis_tilt` function is renamed to :py:func:`~pvlib.tracking.calc_cross_axis_slope`, and its parameter ``axis_tilt``
+  - :py:class:`pvlib.pvsystem.SingleAxisTrackerMount` dataclass fields ``axis_tilt`` and ``cross_axis_tilt``
+
+  (:issue:`2334`, :pull:`2543`)
 
 Bug fixes
 ~~~~~~~~~

pvlib/pvsystem.py

@@ -1473,7 +1473,7 @@ class SingleAxisTrackerMount(AbstractMount):
         The tilt of the axis of rotation (i.e, the y-axis defined by
         axis_azimuth) with respect to horizontal. [degrees]
 
-        .. versionchanged:: 0.14.0
+        .. versionchanged:: 0.16.0
             Renamed from ``axis_tilt`` to ``axis_slope``.
 
     axis_azimuth : float, default 180
@@ -1510,10 +1510,9 @@ class SingleAxisTrackerMount(AbstractMount):
         provided, a gcr of 2/7 is default. gcr must be <=1. [unitless]
 
     cross_axis_slope : float, default 0.0
-        In degrees :math:`^{\circ}`.
-        See :term:`cross_axis_slope`.
+        See :term:`cross_axis_slope`. [degrees]
 
-        .. versionchanged:: 0.14.0
+        .. versionchanged:: 0.16.0
             Renamed from ``cross_axis_tilt`` to ``cross_axis_slope``.
 
     racking_model : str, optional

pvlib/shading.py

@@ -265,9 +265,9 @@ def projected_solar_zenith_angle(solar_zenith, solar_azimuth,
     solar_azimuth : numeric
         Sun's azimuth in degrees.
     axis_slope : numeric
-        Axis tilt angle in degrees. From horizontal plane to array plane.
+        Axis slope angle in degrees. From horizontal plane to array plane.
 
-        .. versionchanged:: 0.14.0
+        .. versionchanged:: 0.16.0
             Renamed from ``axis_tilt`` to ``axis_slope``
 
     axis_azimuth : numeric
@@ -325,7 +325,7 @@ def projected_solar_zenith_angle(solar_zenith, solar_azimuth,
     """
     # Assume the tracker reference frame is right-handed. Positive y-axis is
     # oriented along tracking axis; from north, the y-axis is rotated clockwise
-    # by the axis azimuth and tilted from horizontal by the axis tilt. The
+    # by the axis azimuth and tilted from horizontal by the axis slope. The
     # positive x-axis is 90 deg clockwise from the y-axis and parallel to
     # horizontal (e.g., if the y-axis is south, the x-axis is west); the
     # positive z-axis is normal to the x and y axes, pointed upward.
@@ -416,17 +416,16 @@ def shaded_fraction1d(
     axis_slope : numeric, default 0
         Tilt of the rows axis from horizontal. In degrees :math:`^{\circ}`.
 
-        .. versionchanged:: 0.14.0
+        .. versionchanged:: 0.16.0
             Renamed from ``axis_tilt`` to ``axis_slope``
 
     surface_to_axis_offset : numeric, default 0
         Distance between the rotating axis and the collector surface.
         May be used to account for a torque tube offset.
     cross_axis_slope : numeric, default 0
-        In degrees :math:`^{\circ}`.
-        See :term:`cross_axis_slope`.
+        See :term:`cross_axis_slope`. In degrees :math:`^{\circ}`.
 
-        .. versionchanged:: 0.14.0
+        .. versionchanged:: 0.16.0
             Renamed from ``cross_axis_tilt`` to ``cross_axis_slope``
 
     shading_row_rotation : numeric, optional

pvlib/tracking.py

@@ -93,15 +93,7 @@ def singleaxis(apparent_zenith, solar_azimuth,
         2/7 is default. ``gcr`` must be <=1.
         
     cross_axis_slope : 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. 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]
+        See :term:`cross_axis_slope`. [degrees]
 
         .. versionchanged:: 0.16.0
             Renamed from ``cross_axis_tilt`` to ``cross_axis_slope``.
@@ -174,7 +166,7 @@ def singleaxis(apparent_zenith, solar_azimuth,
     # Account for backtracking
     if backtrack:
         # distance between rows in terms of rack lengths relative to cross-axis
-        # tilt
+        # slope
         axes_distance = 1/(gcr * cosd(cross_axis_slope))
 
         # NOTE: account for rare angles below array, see GH 824
@@ -335,8 +327,8 @@ def calc_surface_orientation(tracker_theta, axis_slope=0, axis_azimuth=0):
 
 def calc_axis_slope(slope_azimuth, slope_tilt, axis_azimuth):
     """
-    Calculate tracker axis tilt in the global reference frame when on a sloped
-    plane. Axis tilt is the inclination of the tracker rotation axis with
+    Calculate tracker axis slope in the global reference frame when on a sloped
+    plane. Axis slope is the inclination of the tracker rotation axis with
     respect to horizontal, ranging from 0 degrees (horizontal axis) to 90
     degrees (vertical axis).
 
@@ -386,7 +378,7 @@ def _calc_tracker_norm(ba, bg, dg):
     Parameters
     ----------
     ba : float
-        axis tilt [degrees]
+        axis slope [degrees]
     bg : float
         ground tilt [degrees]
     dg : float
@@ -409,7 +401,7 @@ def _calc_tracker_norm(ba, bg, dg):
 
 def _calc_beta_c(v, dg, ba):
     """
-    Calculate the cross-axis tilt angle.
+    Calculate the cross-axis slope angle.
 
     Parameters
     ----------
@@ -418,12 +410,12 @@ def _calc_beta_c(v, dg, ba):
     dg : float
         delta gamma, difference between axis and ground azimuths [degrees]
     ba : float
-        axis tilt [degrees]
+        axis slope [degrees]
 
     Returns
     -------
     beta_c : float
-        cross-axis tilt angle [radians]
+        cross-axis slope angle [radians]
     """
     vnorm = np.sqrt(np.dot(v, v))
     beta_c = np.arcsin(
@@ -443,12 +435,12 @@ def calc_cross_axis_slope(
     intersection between the slope containing the tracker axes and a plane
     perpendicular to the tracker axes.
 
-    Use the cross-axis tilt to avoid row-to-row shade when backtracking on a
-    slope not parallel with the axis azimuth. Cross-axis tilt should be
+    Use the cross-axis slope to avoid row-to-row shade when backtracking on a
+    slope not parallel with the axis azimuth. Cross-axis slope 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.
+    azimuth of 180 degrees (heading south) will have a negative cross-axis
+    slope if the tracker axes plane slopes down to the east and positive
+    cross-axis slope if the tracker axes plane slopes down to the west.
 
     .. versionchanged:: 0.16.0
         Renamed function ``calc_cross_axis_tilt`` to ``calc_cross_axis_slope``.
@@ -472,9 +464,7 @@ def calc_cross_axis_slope(
     Returns
     -------
     cross_axis_slope : float
-        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 [degrees]
+        See :term:`cross_axis_slope`. [degrees]
 
     See also
     --------

tests/test_tracking.py

@@ -394,7 +394,7 @@ def test_calc_axis_slope():
     axis_slope = tracking.calc_axis_slope(
         slope_azimuth, slope_tilt, axis_azimuth=axis_azimuth)
     assert np.isclose(axis_slope, expected_axis_slope)
-    # calculate cross-axis tilt and relative rotation
+    # calculate cross-axis slope and relative rotation
     cross_axis_slope = tracking.calc_cross_axis_slope(
         slope_azimuth, slope_tilt, axis_azimuth, axis_slope)
     assert np.isclose(cross_axis_slope, expected_side_slope)
@@ -515,7 +515,7 @@ def test_calc_surface_orientation_types():
 
 
 def test_calc_surface_orientation_kwargs():
-    # non-default axis tilt & azimuth
+    # non-default axis slope & azimuth
     rotations = np.array([-10, 0, 10])
     expected_tilts = np.array([22.2687445, 20.0, 22.2687445])
     expected_azimuths = np.array([152.72683041, 180.0, 207.27316959])