Update implementation based on PSZ PR. See description.

Commit highlights ✨ :
* I think I made all the code a bit more legible; sorry for the big changes @mikofski
* Tests a bit more complete (not much, still consider the same test data)
* Rename shaded fraction acronym from `fs` to `sf`
* Asserts changed to `assert_allclose` for a more legible output in case of failure

Co-Authored-By: Mark Mikofski <[email protected]>

Author: echedey-ls

pvlib/shading.py

@@ -307,22 +307,25 @@ def projected_solar_zenith_angle(solar_zenith, solar_azimuth,
     return theta_T
 
 
-def tracker_shaded_fraction(tracker_theta, gcr, projected_solar_zenith,
-                            cross_axis_slope=0):
+def tracker_shaded_fraction(solar_zenith, solar_azimuth, tracker_tilt,
+                            tracker_azimuth, gcr, cross_axis_slope=0):
     r"""
     Shaded fraction for trackers with a common angle on an east-west slope.
 
     Parameters
     ----------
-    tracker_theta : numeric
-        The tracker rotation angle in degrees from horizontal.
-    gcr : float
+    solar_zenith : numeric
+        Solar position zenith, in degrees.
+    solar_azimuth : numeric
+        Solar position azimuth, in degrees.
+    tracker_tilt : numeric
+        In degrees.
+    tracker_azimuth : numeric
+        In degrees. North=0º, South=180º, East=90º, West=270º.
+    gcr : numeric
         The ground coverage ratio as a fraction equal to the collector width
         over the horizontal row-to-row pitch.
-    projected_solar_zenith : numeric
-        Zenith angle in degrees of the solar vector projected into the plane
-        perpendicular to the tracker axes.
-    cross_axis_slope : float, default 0
+    cross_axis_slope : numeric, default 0
         Angle of the plane containing the tracker axes in degrees from
         horizontal.
 
@@ -368,9 +371,19 @@ def tracker_shaded_fraction(tracker_theta, gcr, projected_solar_zenith,
     PVPMC, 2023
     """
     theta_g_rad = np.radians(cross_axis_slope)
+    # projected solar zenith:
+    # consider the angle the sun direct beam has on the vertical plane which
+    # contains the tracker normal vector, with respect to a horizontal line
+    projected_solar_zenith = projected_solar_zenith_angle(
+        0,  # no rotation from the horizontal
+        # the vector that defines the projection plane for prior conditions
+        tracker_azimuth-90,
+        solar_zenith,
+        solar_azimuth
+    )
     # angle opposite shadow cast on the ground, z
     angle_z = (
-        np.pi / 2 - np.radians(tracker_theta)
+        np.pi / 2 - np.radians(tracker_tilt)
         + np.radians(projected_solar_zenith))
     # angle opposite the collector width, L
     angle_gcr = (
@@ -381,9 +394,9 @@ def tracker_shaded_fraction(tracker_theta, gcr, projected_solar_zenith,
     # there's only row-to-row shade loss if the shadow on the ground, z, is
     # longer than row-to-row pitch projected on the ground, P*cos(theta_g)
     zp_cos_g = zp*np.cos(theta_g_rad)
-    # shaded fraction (fs)
-    fs = np.where(zp_cos_g <= 1, 0, 1 - 1/zp_cos_g)
-    return fs
+    # shaded fraction (sf)
+    sf = np.where(zp_cos_g <= 1, 0, 1 - 1/zp_cos_g)
+    return sf
 
 
 def linear_shade_loss(shaded_fraction, diffuse_fraction):
@@ -414,8 +427,8 @@ def linear_shade_loss(shaded_fraction, diffuse_fraction):
     Example
     -------
     >>> from pvlib import shading
-    >>> fs = shading.tracker_shaded_fraction(45.0, 0.8, 45.0, 0)
-    >>> loss = shading.linear_shade_loss(fs, 0.2)
+    >>> sf = shading.tracker_shaded_fraction(45.0, 0.8, 45.0, 0)
+    >>> loss = shading.linear_shade_loss(sf, 0.2)
     >>> P_no_shade = 100  # [kWdc]  DC output from modules
     >>> P_linear_shade = P_no_shade * (1-loss)  # [kWdc] output after loss
     # 90.71067811865476 [kWdc]

pvlib/tests/test_shading.py

@@ -226,43 +226,55 @@ def test_projected_solar_zenith_angle_datatypes(
 
 
 @pytest.fixture
-def expected_fs():
-    # trivial case, 80% gcr, no slope, trackers & psz at 45-deg
-    z0 = np.sqrt(2*0.8*0.8)
-    # another trivial case, 60% gcr, no slope, trackers & psz at 60-deg
-    z1 = 2*0.6
-    # 30-deg isosceles, 60% gcr, no slope, 30-deg trackers, psz at 60-deg
-    z2 = 0.6*np.sqrt(3)
-    z = np.array([z0, z1, z2])
-    return 1 - 1/z
-
-
-def test_tracker_shade_fraction(expected_fs):
-    """closes gh1690"""
-    fs = shading.tracker_shaded_fraction(45.0, 0.8, 45.0)
-    assert np.isclose(fs, expected_fs[0])
-    # same trivial case with 40%, shadow is only 0.565-m long < 1-m r2r P
-    zero_fs = shading.tracker_shaded_fraction(45.0, 0.4, 45.0)
-    assert np.isclose(zero_fs, 0)
-    # test vectors
-    tracker_theta = [45.0, 60.0, 30.0]
-    gcr = [0.8, 0.6, 0.6]
-    psz = [45.0, 60.0, 60.0]
-    slope = [0]*3
-    fs_vec = shading.tracker_shaded_fraction(
-        tracker_theta, gcr, psz, slope)
-    assert np.allclose(fs_vec, expected_fs)
-
-
-def test_linear_shade_loss(expected_fs):
-    loss = shading.linear_shade_loss(expected_fs[0], 0.2)
-    assert np.isclose(loss, 0.09289321881345258)
+def sf_premises_and_expected():
+    """Data comprised of solar position, tracker orientations, ground coverage
+    ratios and terrain slopes with respective shade fractions (sf)"""   
+    # preserve tracker_shade_fraction's args order and append shadow depth, z
+    premises_and_results = pd.DataFrame(
+        columns=["solar_zenith", "solar_azimuth", "tracker_tilt",
+                 "tracker_azimuth", "gcr", "cross_axis_slope", "z"],
+        data=(
+            # trivial case, 80% gcr, no slope, trackers & psz at 45-deg
+            (45, 90., 45, 90., 0.8, 0, np.sqrt(2*0.8*0.8)),
+            # another trivial case, 60% gcr, no slope, trackers & psz at 60-deg
+            (60, 120, 60, 120, 0.6, 0, 2*0.6),
+            # 30-deg isosceles, 60% gcr, no slope, 30-deg trackers, psz 60-deg
+            (60, 135, 30, 135, 0.6, 0, 0.6*np.sqrt(3)),
+            # no shading, 40% gcr, shadow is only 0.565-m long < 1-m r2r P
+            (45, 180, 45, 180, 0.4, 0, 1)  # z := 1 means no shadow
+        ))
+    # append shaded fraction
+    premises_and_results["shaded_fraction"] = 1 - 1/premises_and_results["z"]
+    return premises_and_results
+
+
+def test_tracker_shade_fraction(sf_premises_and_expected):
+    """Tests tracker_shade_fraction"""
+    # unwrap sf_premises_and_expected values premises and expected results
+    premises = sf_premises_and_expected.drop(columns=["z", "shaded_fraction"])
+    expected_sf_array = sf_premises_and_expected["shaded_fraction"]
+    # test scalar inputs from the row iterator
+    # series label := corresponding index in expected_sf_array
+    for index, premise in premises.iterrows():
+        expected_result = expected_sf_array[index]
+        sf = shading.tracker_shaded_fraction(**premise)
+        assert_allclose(sf, expected_result)
+
+    # test vector inputs
+    sf_vec = shading.tracker_shaded_fraction(**premises)
+    assert_allclose(sf_vec, expected_sf_array)
+
+
+def test_linear_shade_loss(sf_premises_and_expected):
+    expected_sf_array = sf_premises_and_expected["shaded_fraction"]
+    loss = shading.linear_shade_loss(expected_sf_array[0], 0.2)
+    assert_allclose(loss, 0.09289321881345258)
     # if no diffuse, shade fraction is the loss
-    loss_no_df = shading.linear_shade_loss(expected_fs[0], 0)
-    assert np.isclose(loss_no_df, expected_fs[0])
+    loss_no_df = shading.linear_shade_loss(expected_sf_array[0], 0)
+    assert_allclose(loss_no_df, expected_sf_array[0])
     # if all diffuse, no shade loss
-    no_loss = shading.linear_shade_loss(expected_fs[0], 1.0)
-    assert np.isclose(no_loss, 0)
-    vec_loss = shading.linear_shade_loss(expected_fs, 0.2)
-    expected_loss = np.array([0.09289322, 0.13333333, 0.03019964])
-    assert np.allclose(vec_loss, expected_loss)
+    no_loss = shading.linear_shade_loss(expected_sf_array[0], 1.0)
+    assert_allclose(no_loss, 0)
+    vec_loss = shading.linear_shade_loss(expected_sf_array, 0.2)
+    expected_loss = np.array([0.09289322, 0.13333333, 0.03019964, 0.0])
+    assert_allclose(vec_loss, expected_loss)