Adopt dni_clear variable name for clearsky DNI

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

@@ -6,6 +6,9 @@ v0.11.2 (Anticipated December, 2024)
 
 Deprecations
 ~~~~~~~~~~~~
+* Deprecated terms ``dni_clearsky`` and ``clearsky_dni``, replaced with ``dni_clear``.
+  Affected functions are :py:func:`~pvlib.irradiance.dirindex` and :py:func:`~pvlib.irradiance.dni`.
+  (:issue:`2272`, :pull:`2274`)
 
 
 Enhancements

pvlib/irradiance.py

@@ -16,7 +16,7 @@
 from pvlib import atmosphere, solarposition, tools
 import pvlib  # used to avoid dni name collision in complete_irradiance
 
-from pvlib._deprecation import pvlibDeprecationWarning
+from pvlib._deprecation import pvlibDeprecationWarning, renamed_kwarg_warning
 import warnings
 
 
@@ -2151,7 +2151,12 @@ def _dirint_bins(times, kt_prime, zenith, w, delta_kt_prime):
     return kt_prime_bin, zenith_bin, w_bin, delta_kt_prime_bin
 
 
-def dirindex(ghi, ghi_clearsky, dni_clearsky, zenith, times, pressure=101325.,
+@renamed_kwarg_warning(
+    since='0.11.2',
+    old_param_name='dni_clearsky',
+    new_param_name='dni_clear',
+    removal="0.13.0")
+def dirindex(ghi, ghi_clearsky, dni_clear, zenith, times, pressure=101325.,
              use_delta_kt_prime=True, temp_dew=None, min_cos_zenith=0.065,
              max_zenith=87):
     """
@@ -2173,9 +2178,12 @@ def dirindex(ghi, ghi_clearsky, dni_clearsky, zenith, times, pressure=101325.,
     ghi_clearsky : array-like
         Global horizontal irradiance from clear sky model. [Wm⁻²]
 
-    dni_clearsky : array-like
+    dni_clear : array-like
         Direct normal irradiance from clear sky model. [Wm⁻²]
 
+        .. versionchanged:: 0.11.2
+            Renamed from ``dni_clearsky`` to ``dni_clear``.
+
     zenith : array-like
         True (not refraction-corrected) zenith angles in decimal
         degrees. If Z is a vector it must be of the same size as all
@@ -2239,7 +2247,7 @@ def dirindex(ghi, ghi_clearsky, dni_clearsky, zenith, times, pressure=101325.,
                                  min_cos_zenith=min_cos_zenith,
                                  max_zenith=max_zenith)
 
-    dni_dirindex = dni_clearsky * dni_dirint / dni_dirint_clearsky
+    dni_dirindex = dni_clear * dni_dirint / dni_dirint_clearsky
 
     dni_dirindex[dni_dirindex < 0] = 0.
 
@@ -3611,7 +3619,12 @@ def _get_dirint_coeffs():
     return coeffs[1:, 1:, :, :]
 
 
-def dni(ghi, dhi, zenith, clearsky_dni=None, clearsky_tolerance=1.1,
+@renamed_kwarg_warning(
+    since='0.11.2',
+    old_param_name='clearsky_dni',
+    new_param_name='dni_clear',
+    removal="0.13.0")
+def dni(ghi, dhi, zenith, dni_clear=None, clearsky_tolerance=1.1,
         zenith_threshold_for_zero_dni=88.0,
         zenith_threshold_for_clearsky_limit=80.0):
     """
@@ -3635,11 +3648,14 @@ def dni(ghi, dhi, zenith, clearsky_dni=None, clearsky_tolerance=1.1,
         True (not refraction-corrected) zenith angles in decimal
         degrees. Angles must be >=0 and <=180.
 
-    clearsky_dni : Series, optional
-        Clearsky direct normal irradiance.
+    dni_clear : Series, optional
+        Clearsky direct normal irradiance. [Wm⁻²]
+
+        .. versionchanged:: 0.11.2
+            Renamed from ``clearsky_dni`` to ``dni_clear``.
 
     clearsky_tolerance : float, default 1.1
-        If 'clearsky_dni' is given this parameter can be used to allow a
+        If ``dni_clear`` is given this parameter can be used to allow a
         tolerance by how much the calculated DNI value can be greater than
         the clearsky value before it is identified as an unreasonable value.
 
@@ -3652,7 +3668,7 @@ def dni(ghi, dhi, zenith, clearsky_dni=None, clearsky_tolerance=1.1,
         'zenith_threshold_for_clearsky_limit' and smaller the
         'zenith_threshold_for_zero_dni' that are greater than the clearsky DNI
         (times allowed tolerance) will be corrected. Only applies if
-        'clearsky_dni' is not None.
+        ``dni_clear`` is not None.
 
     Returns
     -------
@@ -3674,8 +3690,8 @@ def dni(ghi, dhi, zenith, clearsky_dni=None, clearsky_tolerance=1.1,
     # zenith_threshold_for_clearsky_limit and smaller than the
     # upper_cutoff_zenith that are greater than the clearsky DNI (times
     # clearsky_tolerance)
-    if clearsky_dni is not None:
-        max_dni = clearsky_dni * clearsky_tolerance
+    if dni_clear is not None:
+        max_dni = dni_clear * clearsky_tolerance
         dni[(zenith >= zenith_threshold_for_clearsky_limit) &
             (zenith < zenith_threshold_for_zero_dni) &
             (dni > max_dni)] = max_dni
@@ -3716,8 +3732,8 @@ def complete_irradiance(solar_zenith,
         Pandas series of dni data, with datetime index. Must have the same
         datetime index as ghi, dhi, and zenith series, when available.
     dni_clear : Series, optional
-        Pandas series of clearsky dni data. Must have the same datetime index
-        as ghi, dhi, dni, and zenith series, when available. See
+        Pandas series of clearsky dni data [Wm⁻²]. Must have the same datetime
+        index as ghi, dhi, dni, and zenith series, when available. See
         :py:func:`dni` for details.
 
     Returns
@@ -3727,7 +3743,7 @@ def complete_irradiance(solar_zenith,
     """
     if ghi is not None and dhi is not None and dni is None:
         dni = pvlib.irradiance.dni(ghi, dhi, solar_zenith,
-                                   clearsky_dni=dni_clear,
+                                   dni_clear=dni_clear,
                                    clearsky_tolerance=1.1)
     elif dni is not None and dhi is not None and ghi is None:
         ghi = (dhi + dni * tools.cosd(solar_zenith))

pvlib/tests/test_irradiance.py

@@ -15,7 +15,8 @@
     assert_frame_equal,
     assert_series_equal,
     requires_ephem,
-    requires_numba
+    requires_numba,
+    fail_on_pvlib_version,
 )
 
 from pvlib._deprecation import pvlibDeprecationWarning
@@ -1063,7 +1064,7 @@ def test_dirindex(times):
         np.array([0., 79.73860422, 1042.48031487, 257.20751138]),
         index=times
     )
-    dni_clearsky = pd.Series(
+    dni_clear = pd.Series(
         np.array([0., 316.1949056, 939.95469881, 646.22886049]),
         index=times
     )
@@ -1073,7 +1074,7 @@ def test_dirindex(times):
     )
     pressure = 93193.
     tdew = 10.
-    out = irradiance.dirindex(ghi, ghi_clearsky, dni_clearsky,
+    out = irradiance.dirindex(ghi, ghi_clearsky, dni_clear,
                               zenith, times, pressure=pressure,
                               temp_dew=tdew)
     dirint_close_values = irradiance.dirint(ghi, zenith, times,
@@ -1101,38 +1102,51 @@ def test_dirindex_min_cos_zenith_max_zenith():
     times = pd.DatetimeIndex(['2014-06-24T12-0700', '2014-06-24T18-0700'])
     ghi = pd.Series([0, 1], index=times)
     ghi_clearsky = pd.Series([0, 1], index=times)
-    dni_clearsky = pd.Series([0, 5], index=times)
+    dni_clear = pd.Series([0, 5], index=times)
     solar_zenith = pd.Series([90, 89.99], index=times)
 
-    out = irradiance.dirindex(ghi, ghi_clearsky, dni_clearsky, solar_zenith,
+    out = irradiance.dirindex(ghi, ghi_clearsky, dni_clear, solar_zenith,
                               times)
     expected = pd.Series([nan, nan], index=times)
     assert_series_equal(out, expected)
 
-    out = irradiance.dirindex(ghi, ghi_clearsky, dni_clearsky, solar_zenith,
+    out = irradiance.dirindex(ghi, ghi_clearsky, dni_clear, solar_zenith,
                               times, min_cos_zenith=0)
     expected = pd.Series([nan, nan], index=times)
     assert_series_equal(out, expected)
 
-    out = irradiance.dirindex(ghi, ghi_clearsky, dni_clearsky, solar_zenith,
+    out = irradiance.dirindex(ghi, ghi_clearsky, dni_clear, solar_zenith,
                               times, max_zenith=90)
     expected = pd.Series([nan, nan], index=times)
     assert_series_equal(out, expected)
 
-    out = irradiance.dirindex(ghi, ghi_clearsky, dni_clearsky, solar_zenith,
+    out = irradiance.dirindex(ghi, ghi_clearsky, dni_clear, solar_zenith,
                               times, min_cos_zenith=0, max_zenith=100)
     expected = pd.Series([nan, 5.], index=times)
     assert_series_equal(out, expected)
 
 
+@fail_on_pvlib_version("0.13")
+def test_dirindex_dni_clearsky_deprecation():
+    times = pd.DatetimeIndex(['2014-06-24T12-0700', '2014-06-24T18-0700'])
+    ghi = pd.Series([0, 1], index=times)
+    ghi_clearsky = pd.Series([0, 1], index=times)
+    dni_clear = pd.Series([0, 5], index=times)
+    solar_zenith = pd.Series([90, 89.99], index=times)
+    with pytest.warns(pvlibDeprecationWarning, match='dni_clear'):
+        irradiance.dirindex(ghi, ghi_clearsky, dni_clearsky=dni_clear,
+                            zenith=solar_zenith, times=times,
+                            min_cos_zenith=0)
+
+
 def test_dni():
     ghi = pd.Series([90, 100, 100, 100, 100])
     dhi = pd.Series([100, 90, 50, 50, 50])
     zenith = pd.Series([80, 100, 85, 70, 85])
-    clearsky_dni = pd.Series([50, 50, 200, 50, 300])
+    dni_clear = pd.Series([50, 50, 200, 50, 300])
 
     dni = irradiance.dni(ghi, dhi, zenith,
-                         clearsky_dni=clearsky_dni, clearsky_tolerance=2)
+                         dni_clear=dni_clear, clearsky_tolerance=2)
     assert_series_equal(dni,
                         pd.Series([float('nan'), float('nan'), 400,
                                    146.190220008, 573.685662283]))
@@ -1143,6 +1157,17 @@ def test_dni():
                                    146.190220008, 573.685662283]))
 
 
+@fail_on_pvlib_version("0.13")
+def test_dni_dni_clearsky_deprecation():
+    ghi = pd.Series([90, 100, 100, 100, 100])
+    dhi = pd.Series([100, 90, 50, 50, 50])
+    zenith = pd.Series([80, 100, 85, 70, 85])
+    dni_clear = pd.Series([50, 50, 200, 50, 300])
+    with pytest.warns(pvlibDeprecationWarning, match='dni_clear'):
+        irradiance.dni(ghi, dhi, zenith,
+                       clearsky_dni=dni_clear, clearsky_tolerance=2)
+
+
 @pytest.mark.parametrize(
     'surface_tilt,surface_azimuth,solar_zenith,' +
     'solar_azimuth,aoi_expected,aoi_proj_expected',