add tests, update docs, what's new

pvlib · mikofski · May 4, 2023 · May 4, 2023 · May 4, 2023 · May 4, 2023
commit 778b3ebf4dc910dffd58ac7059fd5db3504b53d2
diff --git a/docs/sphinx/source/reference/tracking.rst b/docs/sphinx/source/reference/tracking.rst
@@ -26,3 +26,5 @@ Functions
    tracking.calc_axis_tilt
    tracking.calc_cross_axis_tilt
    tracking.calc_surface_orientation
+   tracking.tracker_shaded_fraction
+   tracking.linear_shade_loss
diff --git a/docs/sphinx/source/whatsnew/v0.9.6.rst b/docs/sphinx/source/whatsnew/v0.9.6.rst
@@ -11,12 +11,16 @@ Deprecations
 
 Enhancements
 ~~~~~~~~~~~~
-
+* added functions `pvlib.tracking.tracker_shaded_fraction` and
+  `pvlib.tracking.linear_shade_loss` to calculate row-to-row shade and apply
+  linear shade loss for thin film CdTe modules like First Solar.
+  (:issue:`1689`, :pull:`1690`)
 
 Bug fixes
 ~~~~~~~~~
 * `data` can no longer be left unspecified in
-  :py:meth:`pvlib.modelchain.ModelChain.run_model_from_effective_irradiance`. (:issue:`1713`, :pull:`1720`)
+  :py:meth:`pvlib.modelchain.ModelChain.run_model_from_effective_irradiance`.
+  (:issue:`1713`, :pull:`1720`)
 
 Testing
 ~~~~~~~
@@ -39,3 +43,4 @@ Contributors
 ~~~~~~~~~~~~
 * Adam R. Jensen (:ghuser:`adamrjensen`)
 * Siddharth Kaul (:ghuser:`k10blogger`)
+* Mark A. Mikofski (:ghuser:`mikofski`)
diff --git a/pvlib/tests/test_tracking.py b/pvlib/tests/test_tracking.py
@@ -605,3 +605,28 @@ 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)
diff --git a/pvlib/tracking.py b/pvlib/tracking.py
@@ -757,9 +757,17 @@ def linear_shade_loss(shade_fraction, diffuse_fraction):
         The fraction of power lost due to linear shading. A value of 1 is all
         power lost and zero is no loss.
 
-    References
-    ----------
-    Mark A. Mikofski, "First Solar Irradiance Shade Losses on Sloped Terrain,"
-    PVPMC, 2023
+    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 1 - shade_fraction * (1 - diffuse_fraction)
+    return shade_fraction * (1 - diffuse_fraction)