Final(?) changes.

pvlib · kandersolar · Dec 12, 2023 · Nov 12, 2023 · Nov 12, 2023 · Nov 12, 2023
commit ae3cdb61e1dc1b83daf5fda6a3304187136adb52
diff --git a/docs/examples/irradiance-transposition/plot_rtranpose_limitations.py b/docs/examples/irradiance-transposition/plot_rtranpose_limitations.py
@@ -28,14 +28,14 @@
 #
 # 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:func:`pvlib.irradiance.rtranspose_driesse_2023` to estimate
+# Then we use :py:func:`pvlib.irradiance.ghi_from_poa_driesse_2023` to estimate
 # the original GHI from POA global.
 #
 # References
 # ----------
-# .. [1] A. Driesse, A. Jensen, R. Perez, A Continuous Form of the Perez
-#     Diffuse Sky Model for Forward and Reverse Transposition, accepted
-#     for publication in the Solar Energy Journal.
+# .. [1] Driesse, A., Jensen, A., Perez, R., 2024. A Continuous form of the
+#     Perez diffuse sky model for forward and reverse transposition.
+#     Solar Energy vol. 267. :doi:`10.1016/j.solener.2023.112093`
 #
 
 import numpy as np
@@ -45,7 +45,7 @@
 
 from pvlib.irradiance import (erbs_driesse,
                               get_total_irradiance,
-                              rtranspose_driesse_2023,
                              ghi_from_poa_driesse_2023,
                               )
 
 matplotlib.rcParams['axes.grid'] = True
@@ -92,11 +92,11 @@
 
 poa_test = 200
 
-ghi_hat = rtranspose_driesse_2023(surface_tilt, surface_azimuth,
-                                  solar_zenith, solar_azimuth,
-                                  poa_test,
-                                  dni_extra,
-                                  full_output=False)
+ghi_hat = ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
+                                    solar_zenith, solar_azimuth,
+                                    poa_test,
+                                    dni_extra,
+                                    full_output=False)
 
 print('Estimated GHI: %.2f W/m².' % ghi_hat)
 
@@ -156,12 +156,12 @@
 # out, other times not.
 #
 
-result = rtranspose_driesse_2023(surface_tilt, surface_azimuth,
-                                 solar_zenith, solar_azimuth,
-                                 poa_global,
-                                 dni_extra,
-                                 full_output=True,
-                                 )
+result = ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
+                                   solar_zenith, solar_azimuth,
+                                   poa_global,
+                                   dni_extra,
+                                   full_output=True,
+                                   )
 
 ghi_hat, conv, niter = result
 correct = np.isclose(ghi, ghi_hat, atol=0.01)

diff --git a/docs/examples/irradiance-transposition/plot_rtranpose_year.py b/docs/examples/irradiance-transposition/plot_rtranpose_year.py
@@ -21,14 +21,14 @@
 # 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:func:`pvlib.irradiance.rtranspose_driesse_2023` to estimate
+# Then we use :py:func:`pvlib.irradiance.ghi_from_poa_driesse_2023` to estimate
 # the original GHI from POA global.  Details of the method found in [1]_.
 #
 # References
 # ----------
-# .. [1] A. Driesse, A. Jensen, R. Perez, A Continuous Form of the Perez
-#     Diffuse Sky Model for Forward and Reverse Transposition, accepted
-#     for publication in the Solar Energy Journal.
+# .. [1] Driesse, A., Jensen, A., Perez, R., 2024. A Continuous form of the
+#     Perez diffuse sky model for forward and reverse transposition.
+#     Solar Energy vol. 267. :doi:`10.1016/j.solener.2023.112093`
 #
 
 import os
@@ -41,7 +41,7 @@
 from pvlib import iotools, location
 from pvlib.irradiance import (get_extra_radiation,
                               get_total_irradiance,
-                              rtranspose_driesse_2023,
+                              ghi_from_poa_driesse_2023,
                               aoi,
                               )
 
@@ -83,7 +83,8 @@
 df['dni_extra'] = get_extra_radiation(df.index)
 
 total_irrad = get_total_irradiance(TILT, ORIENT,
-                                   solpos.apparent_zenith, solpos.azimuth,
+                                   solpos.apparent_zenith,
+                                   solpos.azimuth,
                                    df.dni, df.ghi, df.dhi,
                                    dni_extra=df.dni_extra,
                                    model='perez-driesse')
@@ -105,10 +106,11 @@
 
 start = time.process_time()
 
-df['ghi_rev'] = rtranspose_driesse_2023(TILT, ORIENT,
-                                        solpos.apparent_zenith, solpos.azimuth,
-                                        df.poa_global,
-                                        dni_extra=df.dni_extra)
+df['ghi_rev'] = ghi_from_poa_driesse_2023(TILT, ORIENT,
+                                          solpos.apparent_zenith,
+                                          solpos.azimuth,
+                                          df.poa_global,
+                                          dni_extra=df.dni_extra)
 finish = time.process_time()
 
 print('Elapsed time for reverse transposition: %.1f s' % (finish - start))

diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py
@@ -1381,9 +1381,9 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     References
     ----------
-    .. [1] A. Driesse, A. Jensen, R. Perez, A Continuous Form of the Perez
-        Diffuse Sky Model for Forward and Reverse Transposition, accepted
-        for publication in the Solar Energy Journal.
+    .. [1] Driesse, A., Jensen, A., Perez, R., 2024. A Continuous form of the
+        Perez diffuse sky model for forward and reverse transposition.
+        Solar Energy vol. 267. :doi:`10.1016/j.solener.2023.112093`
 
     .. [2] Perez, R., Ineichen, P., Seals, R., Michalsky, J., Stewart, R.,
        1990. Modeling daylight availability and irradiance components from
@@ -1445,15 +1445,15 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
         return sky_diffuse
 
 
-def _transpose(surface_tilt, surface_azimuth,
-               solar_zenith, solar_azimuth,
-               ghi,
-               dni_extra, airmass, albedo):
+def _poa_from_ghi(surface_tilt, surface_azimuth,
+                  solar_zenith, solar_azimuth,
+                  ghi,
+                  dni_extra, airmass, albedo):
     '''
     Transposition function that includes decomposition of GHI using the
     continuous Erbs-Driesse model.
 
-    Helper function for rtranspose_driesse_2023.
+    Helper function for ghi_from_poa_driesse_2023.
     '''
     # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Nov., 2023
 
@@ -1471,15 +1471,15 @@ def _transpose(surface_tilt, surface_azimuth,
     return irrads['poa_global']
 
 
-def _rtranspose(surface_tilt, surface_azimuth,
-                solar_zenith, solar_azimuth,
-                poa_global,
-                dni_extra, airmass, albedo,
-                xtol=0.01):
+def _ghi_from_poa(surface_tilt, surface_azimuth,
+                  solar_zenith, solar_azimuth,
+                  poa_global,
+                  dni_extra, airmass, albedo,
+                  xtol=0.01):
     '''
     Reverse transposition function that uses the scalar bisection from scipy.
 
-    Helper function for rtranspose_driesse_2023.
+    Helper function for ghi_from_poa_driesse_2023.
     '''
     # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Nov., 2023
 
@@ -1491,10 +1491,10 @@ def _rtranspose(surface_tilt, surface_azimuth,
 
     # function whose root needs to be found
     def poa_error(ghi):
-        poa_hat = _transpose(surface_tilt, surface_azimuth,
-                             solar_zenith, solar_azimuth,
-                             ghi,
-                             dni_extra, airmass, albedo)
+        poa_hat = _poa_from_ghi(surface_tilt, surface_azimuth,
+                                solar_zenith, solar_azimuth,
+                                ghi,
+                                dni_extra, airmass, albedo)
         return poa_hat - poa_global
 
     # calculate an upper bound for ghi using clearness index 1.25
@@ -1523,12 +1523,12 @@ def poa_error(ghi):
     return ghi, conv, niter
 
 
-def rtranspose_driesse_2023(surface_tilt, surface_azimuth,
-                            solar_zenith, solar_azimuth,
-                            poa_global,
-                            dni_extra=None, airmass=None, albedo=0.25,
-                            xtol=0.01,
-                            full_output=False):
+def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
+                              solar_zenith, solar_azimuth,
+                              poa_global,
+                              dni_extra=None, airmass=None, albedo=0.25,
+                              xtol=0.01,
+                              full_output=False):
     '''
     Estimate global horizontal irradiance (GHI) from global plane-of-array
     (POA) irradiance.  This reverse transposition algorithm uses a bisection
@@ -1578,9 +1578,9 @@ def rtranspose_driesse_2023(surface_tilt, surface_azimuth,
 
     References
     ----------
-    .. [1] A. Driesse, A. Jensen, R. Perez, A Continuous Form of the Perez
-        Diffuse Sky Model for Forward and Reverse Transposition, accepted
-        for publication in the Solar Energy Journal.
+    .. [1] Driesse, A., Jensen, A., Perez, R., 2024. A Continuous form of the
+        Perez diffuse sky model for forward and reverse transposition.
+        Solar Energy vol. 267. :doi:`10.1016/j.solener.2023.112093`
 
     See also
     --------
@@ -1590,13 +1590,13 @@ def rtranspose_driesse_2023(surface_tilt, surface_azimuth,
     '''
     # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Nov., 2023
 
-    rtranspose_array = np.vectorize(_rtranspose)
+    ghi_from_poa_array = np.vectorize(_ghi_from_poa)
 
-    ghi, conv, niter = rtranspose_array(surface_tilt, surface_azimuth,
-                                        solar_zenith, solar_azimuth,
-                                        poa_global,
-                                        dni_extra, airmass, albedo,
-                                        xtol=0.01)
+    ghi, conv, niter = ghi_from_poa_array(surface_tilt, surface_azimuth,
+                                          solar_zenith, solar_azimuth,
+                                          poa_global,
+                                          dni_extra, airmass, albedo,
+  
F5B5
                                        xtol=0.01)
 
     if isinstance(poa_global, pd.Series):
         ghi = pd.Series(ghi, poa_global.index)

diff --git a/pvlib/tests/test_irradiance.py b/pvlib/tests/test_irradiance.py
@@ -782,7 +782,7 @@ def test_dirint_min_cos_zenith_max_zenith():
     assert_series_equal(out, expected, check_less_precise=True)
 
 
-def test_rtranspose_driesse():
+def test_ghi_from_poa_driesse():
     # inputs copied from test_gti_dirint
     times = pd.DatetimeIndex(
         ['2014-06-24T06-0700', '2014-06-24T09-0700', '2014-06-24T12-0700'])
@@ -793,7 +793,7 @@ def test_rtranspose_driesse():
     surface_azimuth = 180
 
     # test core function
-    output = irradiance.rtranspose_driesse_2023(
+    output = irradiance.ghi_from_poa_driesse_2023(
         surface_tilt, surface_azimuth, zenith, azimuth,
         poa_global, dni_extra=1366.1)
 
@@ -803,7 +803,7 @@ def test_rtranspose_driesse():
     # test series output
     poa_global = pd.Series([20, 300, 1000], index=times)
 
-    output = irradiance.rtranspose_driesse_2023(
+    output = irradiance.ghi_from_poa_driesse_2023(
         surface_tilt, surface_azimuth, zenith, azimuth,
         poa_global, dni_extra=1366.1)
 
@@ -812,7 +812,7 @@ def test_rtranspose_driesse():
     # test full_output option and special cases
     poa_global = np.array([0, 1500, np.nan])
 
-    ghi, conv, niter = irradiance.rtranspose_driesse_2023(
+    ghi, conv, niter = irradiance.ghi_from_poa_driesse_2023(
         surface_tilt, surface_azimuth, zenith, azimuth,
         poa_global, dni_extra=1366.1, full_output=True)