Move albedo dictionary from pvlib.irradiance to pvlib.albedo

docs/sphinx/source/whatsnew.rst

@@ -6,6 +6,7 @@ What's New
 
 These are new features and improvements of note in each release.
 
+.. include:: whatsnew/v0.11.0.rst
 .. include:: whatsnew/v0.10.5.rst
 .. include:: whatsnew/v0.10.4.rst
 .. include:: whatsnew/v0.10.3.rst

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

@@ -8,18 +8,20 @@ v0.11.0 (Anticipated June, 2024)
 Breaking changes
 ~~~~~~~~~~~~~~~~
 * The deprecated ``pvlib.modelchain.basic_chain`` has now been removed. (:pull:`1862`)
-* Remove the `poa_horizontal_ratio` function and all of its references. (:issue:`1697`, :pull:`2021`)
+* Remove the ``poa_horizontal_ratio`` function and all of its references. (:issue:`1697`, :pull:`2021`)
 * Updated `~pvlib.iotools.MIDC_VARIABLE_MAP`~ to reflect
   changes in instrumentation. (:pull:`2006`)
 * ``pvlib.iotools.read_srml_month_from_solardat`` was deprecated in v0.10.0 and has
   now been completely removed. The function is replaced by :py:func:`~pvlib.iotools.get_srml()`.
   (:pull:`1779`, :pull:`1989`)
-* The `leap_day` parameter in :py:func:`~pvlib.iotools.get_psm3`
+* The ``leap_day`` parameter in :py:func:`~pvlib.iotools.get_psm3`
   now defaults to True instead of False. (:issue:`1481`, :pull:`1991`)
 
 
 Deprecations
 ~~~~~~~~~~~~
+* The ``pvlib.irradiance.SURFACE_ALBEDOS`` dictionary has been moved to
+  :py:const:`pvlib.albedo.SURFACE_ALBEDOS`. (:pull:`2095`)
 * Function :py:func:`pvlib.spectrum.get_am15g` has been deprecated in favor
   of the new function :py:func:`pvlib.spectrum.get_reference_spectra`. Use
   ``pvlib.spectrum.get_reference_spectra(standard="ASTM G173-03")["global"]``

pvlib/albedo.py

@@ -7,6 +7,25 @@
 import pandas as pd
 
 
+# Sources of for the albedo values are provided in
+# pvlib.irradiance.get_ground_diffuse.
+SURFACE_ALBEDOS = {
+    'urban': 0.18,
+    'grass': 0.20,
+    'fresh grass': 0.26,
+    'soil': 0.17,
+    'sand': 0.40,
+    'snow': 0.65,
+    'fresh snow': 0.75,
+    'asphalt': 0.12,
+    'concrete': 0.30,
+    'aluminum': 0.85,
+    'copper': 0.74,
+    'fresh steel': 0.35,
+    'dirty steel': 0.08,
+    'sea': 0.06,
+}
+
 WATER_COLOR_COEFFS = {
     'clear_water_no_waves': 0.13,
     'clear_water_ripples_up_to_2.5cm': 0.16,
@@ -33,7 +52,7 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
 
     The available surface conditions are for inland water bodies, e.g., lakes
     and ponds. For ocean/open sea, see
-    :const:`pvlib.irradiance.SURFACE_ALBEDOS`.
+    :py:const:`pvlib.albedo.SURFACE_ALBEDOS`.
 
     Parameters
     ----------

pvlib/irradiance.py

@@ -16,22 +16,18 @@
 from pvlib import atmosphere, solarposition, tools
 import pvlib  # used to avoid dni name collision in complete_irradiance
 
+from pvlib._deprecation import pvlibDeprecationWarning
+import warnings
 
-# see References section of get_ground_diffuse function
-SURFACE_ALBEDOS = {'urban': 0.18,
-                   'grass': 0.20,
-                   'fresh grass': 0.26,
-                   'soil': 0.17,
-                   'sand': 0.40,
-                   'snow': 0.65,
-                   'fresh snow': 0.75,
-                   'asphalt': 0.12,
-                   'concrete': 0.30,
-                   'aluminum': 0.85,
-                   'copper': 0.74,
-                   'fresh steel': 0.35,
-                   'dirty steel': 0.08,
-                   'sea': 0.06}
+
+# Deprecation warning based on https://peps.python.org/pep-0562/
+def __getattr__(attr):
+    if attr == 'SURFACE_ALBEDOS':
+        warnings.warn(f"{attr} has been moved to the albedo module as of "
+                      "v0.11.0. Please use pvlib.albedo.SURFACE_ALBEDOS.",
+                      pvlibDeprecationWarning)
+        return pvlib.albedo.SURFACE_ALBEDOS
+    raise AttributeError(f"module {__name__!r} has no attribute {attr!r}")
 
 
 def get_extra_radiation(datetime_or_doy, solar_constant=1366.1,
@@ -550,7 +546,7 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None):
     Notes
     -----
     Table of albedo values by ``surface_type`` are from [2]_, [3]_, [4]_;
-    see :py:data:`~pvlib.irradiance.SURFACE_ALBEDOS`.
+    see :py:const:`~pvlib.albedo.SURFACE_ALBEDOS`.
 
     References
     ----------
@@ -565,7 +561,7 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None):
     '''
 
     if surface_type is not None:
-        albedo = SURFACE_ALBEDOS[surface_type]
+        albedo = pvlib.albedo.SURFACE_ALBEDOS[surface_type]
 
     diffuse_irrad = ghi * albedo * (1 - np.cos(np.radians(surface_tilt))) * 0.5
 
@@ -2442,7 +2438,6 @@ def _gti_dirint_lt_90(poa_global, aoi, aoi_lt_90, solar_zenith, solar_azimuth,
     else:
         # we are here because we ran out of coeffs to loop over and
         # therefore we have exceeded max_iterations
-        import warnings
         failed_points = best_diff[aoi_lt_90][~best_diff_lte_1_lt_90]
         warnings.warn(
             ('%s points failed to converge after %s iterations. best_diff:\n%s'
@@ -2806,8 +2801,8 @@ def orgill_hollands(ghi, zenith, datetime_or_doy, dni_extra=None,
     References
     ----------
     .. [1] Orgill, J.F., Hollands, K.G.T., Correlation equation for hourly
-      diffuse radiation on a horizontal surface, Solar Energy 19(4), pp 357–359,
-      1977. Eqs. 3(a), 3(b) and 3(c)
+      diffuse radiation on a horizontal surface, Solar Energy 19(4),
+      pp 357–359, 1977. Eqs. 3(a), 3(b) and 3(c)
       :doi:`10.1016/0038-092X(77)90006-8`
 
     See Also

pvlib/pvsystem.py

@@ -19,6 +19,7 @@
 
 from pvlib._deprecation import deprecated, warn_deprecated
 
+import pvlib  # used to avoid albedo name collision in the Array class
 from pvlib import (atmosphere, iam, inverter, irradiance,
                    singlediode as _singlediode, spectrum, temperature)
 from pvlib.tools import _build_kwargs, _build_args
@@ -131,13 +132,13 @@ class PVSystem:
 
     albedo : float, optional
         Ground surface albedo. If not supplied, then ``surface_type`` is used
-        to look up a value in ``irradiance.SURFACE_ALBEDOS``.
+        to look up a value in  :py:const:`pvlib.albedo.SURFACE_ALBEDOS`.
         If ``surface_type`` is also not supplied then a ground surface albedo
         of 0.25 is used.
 
     surface_type : string, optional
-        The ground surface type. See ``irradiance.SURFACE_ALBEDOS`` for
-        valid values.
+        The ground surface type. See  :py:const:`pvlib.albedo.SURFACE_ALBEDOS`
+        for valid values.
 
     module : string, optional
         The model name of the modules.
@@ -907,13 +908,13 @@ class Array:
 
     albedo : float, optional
         Ground surface albedo. If not supplied, then ``surface_type`` is used
-        to look up a value in ``irradiance.SURFACE_ALBEDOS``.
+        to look up a value in  :py:const:`pvlib.albedo.SURFACE_ALBEDOS`.
         If ``surface_type`` is also not supplied then a ground surface albedo
         of 0.25 is used.
 
     surface_type : string, optional
-        The ground surface type. See ``irradiance.SURFACE_ALBEDOS`` for valid
-        values.
+        The ground surface type. See  :py:const:`pvlib.albedo.SURFACE_ALBEDOS`
+        for valid values.
 
     module : string, optional
         The model name of the modules.
@@ -956,7 +957,7 @@ def __init__(self, mount,
 
         self.surface_type = surface_type
         if albedo is None:
-            self.albedo = irradiance.SURFACE_ALBEDOS.get(surface_type, 0.25)
+            self.albedo = pvlib.albedo.SURFACE_ALBEDOS.get(surface_type, 0.25)
         else:
             self.albedo = albedo
 

pvlib/tests/test_irradiance.py

@@ -9,7 +9,7 @@
 import pytest
 from numpy.testing import (assert_almost_equal,
                            assert_allclose)
-from pvlib import irradiance
+from pvlib import irradiance, albedo
 
 from .conftest import (
     assert_frame_equal,
@@ -18,6 +18,7 @@
     requires_numba
 )
 
+from pvlib._deprecation import pvlibDeprecationWarning
 
 # fixtures create realistic test input data
 # test input data generated at Location(32.2, -111, 'US/Arizona', 700)
@@ -1406,3 +1407,15 @@ def test_louche():
     out = irradiance.louche(ghi, zenith, index)
 
     assert_frame_equal(out, expected)
+
+
+def test_SURFACE_ALBEDOS_deprecated():
+    with pytest.warns(pvlibDeprecationWarning, match='SURFACE_ALBEDOS has been'
+                      ' moved to the albedo module as of v0.11.0. Please use'
+                      ' pvlib.albedo.SURFACE_ALBEDOS.'):
+        irradiance.SURFACE_ALBEDOS
+
+
+@pytest.mark.filterwarnings("ignore:SURFACE_ALBEDOS")
+def test_SURFACE_ALBEDO_equals():
+    assert irradiance.SURFACE_ALBEDOS == albedo.SURFACE_ALBEDOS