responding to comments

- move linear shade loss to shading module
- don't use ternary, doesn't work on vectors, instead use np.where()
- set cross axis default to zero
- test vectors
- update docs

Author: mikofski

docs/sphinx/source/reference/effects_on_pv_system_output/shading.rst

@@ -11,3 +11,6 @@ Shading
    shading.masking_angle_passias
    shading.sky_diffuse_passias
    shading.projected_solar_zenith_angle
+   shading.tracker_shaded_fraction
+   shading.linear_shade_loss
+   

docs/sphinx/source/reference/tracking.rst

@@ -13,5 +13,3 @@ Functions
    tracking.calc_axis_tilt
    tracking.calc_cross_axis_tilt
    tracking.calc_surface_orientation
-   tracking.tracker_shaded_fraction
-   tracking.linear_shade_loss

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

@@ -11,8 +11,8 @@ Deprecations
 
 Enhancements
 ~~~~~~~~~~~~
-* added functions `pvlib.tracking.tracker_shaded_fraction` and
-  `pvlib.tracking.linear_shade_loss` to calculate row-to-row shade and apply
+* added functions `pvlib.shading.tracker_shaded_fraction` and
+  `pvlib.shading.linear_shade_loss` to calculate row-to-row shade and apply
   linear shade loss for thin film CdTe modules like First Solar.
   (:issue:`1689`, :issue:`1690`, :pull:`1725`)
 

pvlib/shading.py

@@ -305,3 +305,88 @@ def projected_solar_zenith_angle(solar_zenith, solar_azimuth,
     # Eq. (5); angle between sun's beam and surface
     theta_T = np.degrees(np.arctan2(sx_prime, sz_prime))
     return theta_T
+
+
+def tracker_shaded_fraction(tracker_theta, gcr, projected_solar_zenith,
+                            cross_axis_slope=0):
+    """
+    Shade fraction (FS) 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
+        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
+        Angle of the plane containing the tracker axes in degrees from
+        horizontal.
+
+    Returns
+    -------
+    shade_fraction : numeric
+        The fraction of the collector width shaded by an adjacent row. A
+        value of 1 is completely shaded and zero is no shade.
+
+    References
+    ----------
+    Mark A. Mikofski, "First Solar Irradiance Shade Losses on Sloped Terrain,"
+    PVPMC, 2023
+    """
+    theta_g_rad = np.radians(cross_axis_slope)
+    # angle opposite shadow cast on the ground, z
+    angle_z = (
+        np.pi / 2 - np.radians(tracker_theta)
+        + np.radians(projected_solar_zenith))
+    # angle opposite the collector width, L
+    angle_gcr = (
+        np.pi / 2 - np.radians(projected_solar_zenith)
+        - theta_g_rad)
+    # ratio of shadow, z, to pitch, P
+    zp = gcr * np.sin(angle_z) / np.sin(angle_gcr)
+    # 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)
+    # shade fraction
+    fs = np.where(zp_cos_g <= 1, 0, 1 - 1/zp_cos_g)
+    return fs
+
+
+def linear_shade_loss(shade_fraction, diffuse_fraction):
+    """
+    Fraction of power lost to linear shade loss applicable to CdTe modules like
+    First Solar.
+
+    Parameters
+    ----------
+    shade_fraction : numeric
+        The fraction of the collector width shaded by an adjacent row. A
+        value of 1 is completely shaded and zero is no shade.
+    diffuse_fraction : numeric
+        The ratio of diffuse plane of array (poa) irradiance to global poa.
+        A value of 1 is completely diffuse and zero is no diffuse.
+
+    Returns
+    -------
+    linear_shade_loss : numeric
+        The fraction of power lost due to linear shading. A value of 1 is all
+        power lost and zero is no loss.
+
+    See also
+    --------
+    pvlib.tracking.tracker_shaded_fraction
+
+    Example
+    -------
+    >>> from pvlib import tracking
+    >>> fs = tracking.tracker_shaded_fraction(45.0, 0.8, 45.0, 0)
+    >>> loss = tracking.linear_shade_loss(fs, 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]
+    """
+    return shade_fraction * (1 - diffuse_fraction)

pvlib/tests/test_shading.py

@@ -223,3 +223,46 @@ def test_projected_solar_zenith_angle_datatypes(
     )
     psz = psz_func(sun_apparent_zenith, axis_azimuth, axis_tilt, axis_azimuth)
     assert isinstance(psz, cast_type)
+
+
+@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)
+    # 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])
+    # 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)

pvlib/tests/test_tracking.py

@@ -472,28 +472,3 @@ def test_calc_surface_orientation_special():
         # in a modulo-360 sense.
         np.testing.assert_allclose(np.round(out['surface_azimuth'], 4) % 360,
                                    expected_azimuths, rtol=1e-5, atol=1e-5)
-
-
-@pytest.fixture
-def expected_fs():
-    # trivial case, 80% gcr, no slope, trackers & psz at 45-deg
-    z = np.sqrt(2*0.8*0.8)
-    return 1 - 1/z
-
-
-def test_tracker_shade_fraction(expected_fs):
-    """closes gh1690"""
-    fs = tracking.tracker_shaded_fraction(45.0, 0.8, 45.0, 0)
-    assert np.isclose(fs, expected_fs)
-    # same trivial case with 40%, shadow is only 0.565-m long < 1-m r2r P
-    zero_fs = tracking.tracker_shaded_fraction(45.0, 0.4, 45.0, 0)
-    assert np.isclose(zero_fs, 0)
-
-
-def test_linear_shade_loss(expected_fs):
-    loss = tracking.linear_shade_loss(expected_fs, 0.2)
-    assert np.isclose(loss, 0.09289321881345258)
-    loss_no_df = tracking.linear_shade_loss(expected_fs, 0)
-    assert np.isclose(loss_no_df, expected_fs)
-    no_loss = tracking.linear_shade_loss(expected_fs, 1.0)
-    assert np.isclose(no_loss, 0)

pvlib/tracking.py

@@ -406,88 +406,3 @@ def calc_cross_axis_tilt(
     # equation 26
     beta_c = _calc_beta_c(v, delta_gamma, axis_tilt)
     return np.degrees(beta_c)
-
-
-def tracker_shaded_fraction(tracker_theta, gcr, projected_solar_zenith,
-                            cross_axis_slope):
-    """
-    Shade fraction (FS) 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
-        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
-        Angle of the plane containing the tracker axes in degrees from
-        horizontal.
-
-    Returns
-    -------
-    shade_fraction : numeric
-        The fraction of the collector width shaded by an adjacent row. A
-        value of 1 is completely shaded and zero is no shade.
-
-    References
-    ----------
-    Mark A. Mikofski, "First Solar Irradiance Shade Losses on Sloped Terrain,"
-    PVPMC, 2023
-    """
-    theta_g_rad = np.radians(cross_axis_slope)
-    # angle opposite shadow cast on the ground, z
-    angle_z = (
-        np.pi / 2 - np.radians(tracker_theta)
-        + np.radians(projected_solar_zenith))
-    # angle opposite the collector width, L
-    angle_gcr = (
-        np.pi / 2 - np.radians(projected_solar_zenith)
-        - theta_g_rad)
-    # ratio of shadow, z, to pitch, P
-    zp = gcr * np.sin(angle_z) / np.sin(angle_gcr)
-    # 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)
-    # shade fraction
-    fs = 0 if zp_cos_g <= 1 else 1 - 1/zp_cos_g
-    return fs
-
-
-def linear_shade_loss(shade_fraction, diffuse_fraction):
-    """
-    Fraction of power lost to linear shade loss applicable to CdTe modules like
-    First Solar.
-
-    Parameters
-    ----------
-    shade_fraction : numeric
-        The fraction of the collector width shaded by an adjacent row. A
-        value of 1 is completely shaded and zero is no shade.
-    diffuse_fraction : numeric
-        The ratio of diffuse plane of array (poa) irradiance to global poa.
-        A value of 1 is completely diffuse and zero is no diffuse.
-
-    Returns
-    -------
-    linear_shade_loss : numeric
-        The fraction of power lost due to linear shading. A value of 1 is all
-        power lost and zero is no loss.
-
-    See also
-    --------
-    pvlib.tracking.tracker_shaded_fraction
-
-    Example
-    -------
-    >>> from pvlib import tracking
-    >>> fs = tracking.tracker_shaded_fraction(45.0, 0.8, 45.0, 0)
-    >>> loss = tracking.linear_shade_loss(fs, 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]
-    """
-    return shade_fraction * (1 - diffuse_fraction)