diff --git a/docs/sphinx/source/whatsnew.rst b/docs/sphinx/source/whatsnew.rst index 66c7196333..6baff55247 100644 --- a/docs/sphinx/source/whatsnew.rst +++ b/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 diff --git a/docs/sphinx/source/whatsnew/v0.11.0.rst b/docs/sphinx/source/whatsnew/v0.11.0.rst index 791cd5fc4d..dc98410485 100644 --- a/docs/sphinx/source/whatsnew/v0.11.0.rst +++ b/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"]`` diff --git a/pvlib/albedo.py b/pvlib/albedo.py index 98b920dddb..2dca47ef3d 100644 --- a/pvlib/albedo.py +++ b/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 ---------- diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index fadc80b136..73448b6d6d 100644 --- a/pvlib/irradiance.py +++ b/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 diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 0f0a41c87a..385760c967 100644 --- a/pvlib/pvsystem.py +++ b/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 diff --git a/pvlib/tests/test_irradiance.py b/pvlib/tests/test_irradiance.py index c855c88d73..19ce0790ee 100644 --- a/pvlib/tests/test_irradiance.py +++ b/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