Rename ghi_from_poa_driesse_2023 to ghi_from_poa_driesse_2024 (#2777)

* Update irradiance.py

* Update test_irradiance.py

* update sphinx refs, examples

* Update v0.15.2.rst

* flake8

* test deprecation

* Update v0.15.2.rst

Author: RDaxini

docs/examples/irradiance-transposition/plot_rtranpose_limitations.py

@@ -28,7 +28,7 @@
 #
 # In this example we look at a single point in time and consider a full range
 # of possible GHI and POA global values as shown in figures 3 and 4 of [1]_.
-# Then we use :py:meth:`pvlib.irradiance.ghi_from_poa_driesse_2023` to estimate
+# Then we use :py:meth:`pvlib.irradiance.ghi_from_poa_driesse_2024` to estimate
 # the original GHI from POA global.
 #
 # References
@@ -45,7 +45,7 @@
 
 from pvlib.irradiance import (erbs_driesse,
                               get_total_irradiance,
-                              ghi_from_poa_driesse_2023,
+                              ghi_from_poa_driesse_2024,
                               )
 
 matplotlib.rcParams['axes.grid'] = True
@@ -92,7 +92,7 @@
 
 poa_test = 200
 
-ghi_hat = ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
+ghi_hat = ghi_from_poa_driesse_2024(surface_tilt, surface_azimuth,
                                     solar_zenith, solar_azimuth,
                                     poa_test,
                                     dni_extra,
@@ -156,7 +156,7 @@
 # out, other times not.
 #
 
-result = ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
+result = ghi_from_poa_driesse_2024(surface_tilt, surface_azimuth,
                                    solar_zenith, solar_azimuth,
                                    poa_global,
                                    dni_extra,

docs/examples/irradiance-transposition/plot_rtranpose_year.py

@@ -21,7 +21,7 @@
 # Recovering GHI from POA irradiance is termed "reverse transposition."
 #
 # In this example we start with a TMY file and calculate POA global irradiance.
-# Then we use :py:meth:`pvlib.irradiance.ghi_from_poa_driesse_2023` to estimate
+# Then we use :py:meth:`pvlib.irradiance.ghi_from_poa_driesse_2024` to estimate
 # the original GHI from POA global.  Details of the method found in [1]_.
 #
 # Another method for reverse tranposition called GTI-DIRINT is also
@@ -49,7 +49,7 @@
 from pvlib import iotools, location
 from pvlib.irradiance import (get_extra_radiation,
                               get_total_irradiance,
-                              ghi_from_poa_driesse_2023,
+                              ghi_from_poa_driesse_2024,
                               aoi,
                               )
 
@@ -114,7 +114,7 @@
 
 start = time.process_time()
 
-df['ghi_rev'] = ghi_from_poa_driesse_2023(TILT, ORIENT,
+df['ghi_rev'] = ghi_from_poa_driesse_2024(TILT, ORIENT,
                                           solpos.apparent_zenith,
                                           solpos.azimuth,
                                           df.poa_global,

docs/sphinx/source/reference/irradiance/reverse-transposition.rst

@@ -6,5 +6,5 @@ Reverse transposition models
 .. autosummary::
    :toctree: ../generated/
 
-   irradiance.ghi_from_poa_driesse_2023
+   irradiance.ghi_from_poa_driesse_2024
    irradiance.gti_dirint

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

@@ -10,6 +10,10 @@ Breaking Changes
 
 Deprecations
 ~~~~~~~~~~~~
+* Rename :py:func:`!pvlib.irradiance.ghi_from_poa_driesse_2023` to
+  :py:func:`~pvlib.irradiance.ghi_from_poa_driesse_2024`. The year now reflects
+  the publication date. The old name will be removed in v0.17.0.
+  (:issue:`2774`, :pull:`2777`)
 
 
 Bug fixes
@@ -76,3 +80,4 @@ Contributors
 * :ghuser:`shethkajal7`
 * Arthur Onno (:ghuser:`ArthurOnnoTerabase`)
 * Adam R. Jensen (:ghuser:`AdamRJensen`)
+* Rajiv Daxini (:ghuser:`RDaxini`)

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, deprecated
 import warnings
 
 
@@ -1442,7 +1442,7 @@ def _poa_from_ghi(surface_tilt, surface_azimuth,
     Transposition function that includes decomposition of GHI using the
     continuous Erbs-Driesse model.
 
-    Helper function for ghi_from_poa_driesse_2023.
+    Helper function for ghi_from_poa_driesse_2024.
     '''
     # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Nov., 2023
 
@@ -1468,7 +1468,7 @@ def _ghi_from_poa(surface_tilt, surface_azimuth,
     '''
     Reverse transposition function that uses the scalar bisection from scipy.
 
-    Helper function for ghi_from_poa_driesse_2023.
+    Helper function for ghi_from_poa_driesse_2024.
     '''
     # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Nov., 2023
 
@@ -1512,7 +1512,7 @@ def poa_error(ghi):
     return ghi, conv, niter
 
 
-def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
+def ghi_from_poa_driesse_2024(surface_tilt, surface_azimuth,
                               solar_zenith, solar_azimuth,
                               poa_global,
                               dni_extra, airmass=None, albedo=0.25,
@@ -1614,6 +1614,14 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
         return ghi
 
 
+ghi_from_poa_driesse_2023 = deprecated(
+    since="0.15.2",
+    name="pvlib.irradiance.ghi_from_poa_driesse_2023",
+    alternative="pvlib.irradiance.ghi_from_poa_driesse_2024",
+    removal="0.17.0",
+)(ghi_from_poa_driesse_2024)
+
+
 def clearsky_index(ghi, ghi_clear, max_clearsky_index=2.0):
     """
     Calculate the clearsky index.

tests/test_irradiance.py

@@ -792,7 +792,7 @@ def test_ghi_from_poa_driesse(mocker):
     surface_azimuth = 180
 
     # test core function
-    output = irradiance.ghi_from_poa_driesse_2023(
+    output = irradiance.ghi_from_poa_driesse_2024(
         surface_tilt, surface_azimuth, zenith, azimuth,
         poa_global, dni_extra=1366.1)
 
@@ -802,7 +802,7 @@ def test_ghi_from_poa_driesse(mocker):
     # test series output
     poa_global = pd.Series([20, 300, 1000], index=times)
 
-    output = irradiance.ghi_from_poa_driesse_2023(
+    output = irradiance.ghi_from_poa_driesse_2024(
         surface_tilt, surface_azimuth, zenith, azimuth,
         poa_global, dni_extra=1366.1)
 
@@ -811,7 +811,7 @@ def test_ghi_from_poa_driesse(mocker):
     # test full_output option and special cases
     poa_global = np.array([0, 1500, np.nan])
 
-    ghi, conv, niter = irradiance.ghi_from_poa_driesse_2023(
+    ghi, conv, niter = irradiance.ghi_from_poa_driesse_2024(
         surface_tilt, surface_azimuth, zenith, azimuth,
         poa_global, dni_extra=1366.1, full_output=True)
 
@@ -828,19 +828,26 @@ def test_ghi_from_poa_driesse(mocker):
     poa_global = pd.Series([20, 300, 1000], index=times)
     # test exception
     xtol = -3.14159  # negative value raises exception in scipy.optimize.bisect
-    with pytest.raises(ValueError, match=rf"xtol too small \({xtol:g} <= 0\)"):
-        output = irradiance.ghi_from_poa_driesse_2023(
+    with pytest.raises(ValueError, match=rf"xtol too small \({xtol} <= 0\)"):
+        output = irradiance.ghi_from_poa_driesse_2024(
             surface_tilt, surface_azimuth, zenith, azimuth,
             poa_global, dni_extra=1366.1, xtol=xtol)
     # test propagation
     xtol = 3.141592
     bisect_spy = mocker.spy(irradiance, "bisect")
-    output = irradiance.ghi_from_poa_driesse_2023(
+    output = irradiance.ghi_from_poa_driesse_2024(
         surface_tilt, surface_azimuth, zenith, azimuth,
         poa_global, dni_extra=1366.1, xtol=xtol)
     assert bisect_spy.call_args[1]["xtol"] == xtol
 
 
+def test_ghi_from_poa_driesse_2023_deprecated():
+    with pytest.warns(pvlibDeprecationWarning,
+                      match="ghi_from_poa_driesse_2024"):
+        irradiance.ghi_from_poa_driesse_2023(
+            30, 180, 20, 180, 500, dni_extra=1366.1)
+
+
 def test_gti_dirint():
     times = pd.DatetimeIndex(
         ['2014-06-24T06-0700', '2014-06-24T09-0700', '2014-06-24T12-0700'])