diff --git a/docs/sphinx/source/whatsnew/v0.11.2.rst b/docs/sphinx/source/whatsnew/v0.11.2.rst index 431358459b..d5277ac183 100644 --- a/docs/sphinx/source/whatsnew/v0.11.2.rst +++ b/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 diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index cecba6237b..1c735eb454 100644 --- a/pvlib/irradiance.py +++ b/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)) diff --git a/pvlib/tests/test_irradiance.py b/pvlib/tests/test_irradiance.py index 64f7d27b5e..c39191ba18 100644 --- a/pvlib/tests/test_irradiance.py +++ b/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',