Merge remote-tracking branch 'upstream/main' into ants2d

Author: kandersolar

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

@@ -42,6 +42,20 @@ Enhancements
 * Accelerate :py:func:`~pvlib.bifacial.utils.vf_ground_sky_2d_integ` by one or
   two orders of magnitude. This also makes :py:mod:`pvlib.bifacial.infinite_sheds` faster.
   (:pull:`2740`)
+* Fixes a regression in :py:func:`pvlib.tracking.calc_surface_orientation`
+  introduced in v0.15.1 (:pull:`2702`) that caused a broadcasting
+  ``ValueError`` when ``tracker_theta`` was a 2-D (or higher rank) array.
+  (:issue:`2747`, :pull:`2749`)
+
+Enhancements
+~~~~~~~~~~~~
+* Add the ``front_side_fraction`` parameter to
+  :py:func:`pvlib.snow.loss_townsend` to support Townsend snow-loss
+  workflows for bifacial systems. (:issue:`2755`, :pull:`2756`)
+  
+* Added mapping of the parameter ``"albedo"`` in
+  :py:func:`~pvlib.iotools.get_nasa_power` when ``map_variables=True``
+  (:pull:`2753`)
 
 
 Documentation
@@ -74,3 +88,6 @@ Contributors
 ~~~~~~~~~~~~
 * :ghuser:`Omesh37`
 * Cliff Hansen (:ghuser:`cwhanse`)
+* :ghuser:`shethkajal7`
+* Arthur Onno (:ghuser:`ArthurOnnoTerabase`)
+* Adam R. Jensen (:ghuser:`AdamRJensen`)

pvlib/iotools/nasa_power.py

@@ -18,6 +18,7 @@
     'T2M': 'temp_air',
     'WS2M': 'wind_speed_2m',
     'WS10M': 'wind_speed',
+    'ALLSKY_SRF_ALB': 'albedo',
 }
 
 

pvlib/snow.py

@@ -248,7 +248,8 @@ def _townsend_effective_snow(snow_total, snow_events):
 
 def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
                   temp_air, poa_global, slant_height, lower_edge_height,
-                  string_factor=1.0, angle_of_repose=40):
+                  string_factor=1.0, angle_of_repose=40,
+                  front_side_fraction=1.0):
     '''
     Calculates monthly snow loss based on the Townsend monthly snow loss
     model.
@@ -293,6 +294,12 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
         Piled snow angle, assumed to stabilize at 40°, the midpoint of
         25°-55° avalanching slope angles. [deg]
 
+    front_side_fraction : numeric or array-like, default 1.0
+        Fraction of monthly energy from front-side insolation. [unitless]
+        Multiplies the calculated loss fraction. For example,
+        use 0.9 when 90% of monthly energy is from the front side
+        of a bifacial system and 10% is from the rear side.
+
     Returns
     -------
     loss : array-like
@@ -310,6 +317,10 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
     publication of [1]_, as described in [2]_.
     The definition for snow events documented above is based on [3]_.
 
+    For bifacial systems, [2]_ recommends including both front-side and
+    rear-side insolation in ``poa_global``. The resulting loss is
+    scaled by the front-side energy fraction ``front_side_fraction``.
+
     References
     ----------
     .. [1] Townsend, Tim & Powers, Loren. (2011). Photovoltaics and snow: An
@@ -384,4 +395,6 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
         * string_factor
     )
 
+    loss_fraction = loss_fraction * front_side_fraction
+
     return np.clip(loss_fraction, 0, 1)

pvlib/tracking.py

@@ -233,10 +233,11 @@ def _unit_normal(axis_azimuth, axis_tilt, theta):
     Returns
     -------
     ndarray
-        Shape (N,3) where theta has length N
+        Shape ``theta.shape + (3,)``, with a minimum rank of 2.  For 1-D
+        ``theta`` of length N this is ``(N, 3)``.
     """
 
-    theta = np.asarray(theta)
+    theta = np.atleast_1d(np.asarray(theta))
 
     cA, sA = cosd(-axis_azimuth), sind(-axis_azimuth)
     cT, sT = cosd(-axis_tilt), sind(-axis_tilt)
@@ -248,7 +249,7 @@ def _unit_normal(axis_azimuth, axis_tilt, theta):
     y = sA * sTh - cA * sT * cTh
     z = cT * cTh
 
-    result = np.column_stack((x, y, z))
+    result = np.stack((x, y, z), axis=-1)
 
     return result
 
@@ -296,7 +297,7 @@ def calc_surface_orientation(tracker_theta, axis_tilt=0, axis_azimuth=0):
 
     # project unit_normal to x-y plane to calculate azimuth
     surface_azimuth = np.degrees(
-        np.arctan2(unit_normal[:, 0], unit_normal[:, 1]))
+        np.arctan2(unit_normal[..., 0], unit_normal[..., 1]))
 
     surface_azimuth = np.where(surface_tilt == 0., axis_azimuth - 90.,
                                surface_azimuth)

tests/iotools/test_meteonorm.py

@@ -34,11 +34,11 @@ def expected_meta():
             'description': 'Global horizontal irradiance',
             'name': 'global_horizontal_irradiance',
             'unit': {
-                'description': 'Watt per square meter', 'name': 'W/m**2'}},
+                'description': 'watt per square meter', 'name': 'W/m**2'}},
            {'aggregation_method': 'average',
             'description': 'Global horizontal irradiance with shading taken into account',  # noqa: E501
             'name': 'global_horizontal_irradiance_with_shading',
-            'unit': {'description': 'Watt per square meter',
+            'unit': {'description': 'watt per square meter',
                      'name': 'W/m**2'}},
         ],
         'surface_azimuth': 180,
@@ -245,7 +245,7 @@ def expected_meteonorm_tmy_meta():
             'aggregation_method': 'average',
             'description': 'Diffuse horizontal irradiance',
             'name': 'diffuse_horizontal_irradiance',
-            'unit': {'description': 'Watt per square meter',
+            'unit': {'description': 'watt per square meter',
                      'name': 'W/m**2'},
         }],
         'surface_azimuth': 90,

tests/test_snow.py

@@ -247,3 +247,28 @@ def test_loss_townsend_cases(poa_global, surface_tilt, slant_height,
         poa_global, slant_height, lower_edge_height, string_factor)
     actual = np.around(actual * 100)
     assert np.allclose(expected, actual)
+
+
+def test_loss_townsend_front_side_fraction():
+    snow_total = np.array([25.4, 25.4, 12.7, 2.54, 0, 0, 0, 0, 0, 0, 12.7,
+                           25.4])
+    snow_events = np.array([2, 2, 1, 0, 0, 0, 0, 0, 0, 0, 2, 3])
+    surface_tilt = 20
+    relative_humidity = np.full(12, 80)
+    temp_air = np.full(12, 0)
+    poa_global = np.full(12, 350000)
+    slant_height = 2.54
+    lower_edge_height = 0.254
+    front_side_fraction = 0.9
+
+    unadjusted = snow.loss_townsend(
+        snow_total, snow_events, surface_tilt, relative_humidity, temp_air,
+        poa_global, slant_height, lower_edge_height)
+
+    adjusted = snow.loss_townsend(
+        snow_total, snow_events, surface_tilt, relative_humidity, temp_air,
+        poa_global, slant_height, lower_edge_height,
+        front_side_fraction=front_side_fraction)
+
+    np.testing.assert_allclose(adjusted, unadjusted * front_side_fraction)
+

tests/test_tracking.py

@@ -557,3 +557,31 @@ 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.mark.parametrize('shape', [(3, 5), (1, 7), (4, 1), (2, 3, 4)])
+def test_calc_surface_orientation_2d(shape):
+    # Regression test for GH#2747: calc_surface_orientation must accept
+    # tracker_theta of arbitrary rank, not just 1-D.  Compare the >1-D result
+    # to the 1-D result computed on the flattened input.
+    rotations_flat = np.linspace(-90, 90, int(np.prod(shape)))
+    rotations_nd = rotations_flat.reshape(shape)
+
+    out_1d = tracking.calc_surface_orientation(rotations_flat,
+                                               axis_tilt=20,
+                                               axis_azimuth=180)
+    out_nd = tracking.calc_surface_orientation(rotations_nd,
+                                               axis_tilt=20,
+                                               axis_azimuth=180)
+
+    assert out_nd['surface_tilt'].shape == shape
+    assert out_nd['surface_azimuth'].shape == shape
+    np.testing.assert_allclose(out_nd['surface_tilt'].reshape(-1),
+                               out_1d['surface_tilt'])
+    np.testing.assert_allclose(out_nd['surface_azimuth'].reshape(-1),
+                               out_1d['surface_azimuth'])
+
+    # _unit_normal must preserve the input rank, appending a trailing axis
+    # of length 3.
+    unorm = tracking._unit_normal(180., 20., rotations_nd)
+    assert unorm.shape == shape + (3,)