diff --git a/docs/sphinx/source/whatsnew/v0.9.6.rst b/docs/sphinx/source/whatsnew/v0.9.6.rst index a310dc2116..d5304de1a6 100644 --- a/docs/sphinx/source/whatsnew/v0.9.6.rst +++ b/docs/sphinx/source/whatsnew/v0.9.6.rst @@ -7,9 +7,11 @@ v0.9.6 (Anticipated June 2023) Breaking Changes ~~~~~~~~~~~~~~~~ +* Modified the ``surface_azimuth`` parameter in :py:func:`pvlib.iotools.get_pvgis_hourly` to conform to the + pvlib azimuth convention (counterclockwise from north). Previously 0 degrees represented south. + (:issue:`1724`, :pull:`1739`) * For consistency with the rest of pvlib, the ``tilt`` parameter is renamed to ``surface_tilt`` in :py:func:`pvlib.soiling.hsu`. (:issue:`1717`, :pull:`1738`) - Deprecations ~~~~~~~~~~~~ diff --git a/pvlib/iotools/pvgis.py b/pvlib/iotools/pvgis.py index edfb28c124..268d52e2ef 100644 --- a/pvlib/iotools/pvgis.py +++ b/pvlib/iotools/pvgis.py @@ -45,7 +45,7 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None, raddatabase=None, components=True, - surface_tilt=0, surface_azimuth=0, + surface_tilt=0, surface_azimuth=180, outputformat='json', usehorizon=True, userhorizon=None, pvcalculation=False, @@ -76,9 +76,15 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None, Otherwise only global irradiance is returned. surface_tilt: float, default: 0 Tilt angle from horizontal plane. Ignored for two-axis tracking. - surface_azimuth: float, default: 0 - Orientation (azimuth angle) of the (fixed) plane. 0=south, 90=west, - -90: east. Ignored for tracking systems. + surface_azimuth: float, default: 180 + Orientation (azimuth angle) of the (fixed) plane. Counter-clockwise + from north (north=0, south=180). This is offset 180 degrees from + the convention used by PVGIS. Ignored for tracking systems. + + .. versionchanged:: 0.10.0 + The `surface_azimuth` parameter now follows the pvlib convention, which + is counterclockwise from north. However, the convention used by the + PVGIS website and pvlib<=0.9.5 is offset by 180 degrees. usehorizon: bool, default: True Include effects of horizon userhorizon: list of float, default: None @@ -144,6 +150,13 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None, time stamp convention, e.g., SARAH and SARAH2 provide instantaneous values, whereas values from ERA5 are averages for the hour. + Warning + ------- + The azimuth orientation specified in the output metadata does not + correspond to the pvlib convention, but is offset 180 degrees. This is + despite the fact that the input parameter `surface_tilt` has to be + specified according to the pvlib convention. + Notes ----- data includes the following fields: @@ -191,7 +204,7 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None, """ # noqa: E501 # use requests to format the query string by passing params dictionary params = {'lat': latitude, 'lon': longitude, 'outputformat': outputformat, - 'angle': surface_tilt, 'aspect': surface_azimuth, + 'angle': surface_tilt, 'aspect': surface_azimuth-180, 'pvcalculation': int(pvcalculation), 'pvtechchoice': pvtechchoice, 'mountingplace': mountingplace, 'trackingtype': trackingtype, 'components': int(components), @@ -315,6 +328,11 @@ def read_pvgis_hourly(filename, pvgis_format=None, map_variables=True): metadata : dict metadata + Warning + ------- + The azimuth orientation specified in the output metadata does not + correspond to the pvlib convention, but is offset 180 degrees. + Raises ------ ValueError diff --git a/pvlib/tests/iotools/test_pvgis.py b/pvlib/tests/iotools/test_pvgis.py index 579c26914c..2b6b49b6cc 100644 --- a/pvlib/tests/iotools/test_pvgis.py +++ b/pvlib/tests/iotools/test_pvgis.py @@ -206,14 +206,14 @@ def test_read_pvgis_hourly_bad_extension(): args_radiation_csv = { - 'surface_tilt': 30, 'surface_azimuth': 0, 'outputformat': 'csv', + 'surface_tilt': 30, 'surface_azimuth': 180, 'outputformat': 'csv', 'usehorizon': False, 'userhorizon': None, 'raddatabase': 'PVGIS-SARAH', 'start': 2016, 'end': 2016, 'pvcalculation': False, 'components': True} url_hourly_radiation_csv = 'https://re.jrc.ec.europa.eu/api/seriescalc?lat=45&lon=8&outputformat=csv&angle=30&aspect=0&usehorizon=0&pvtechchoice=crystSi&mountingplace=free&trackingtype=0&components=1&raddatabase=PVGIS-SARAH&startyear=2016&endyear=2016' # noqa: E501 args_pv_json = { - 'surface_tilt': 30, 'surface_azimuth': 0, 'outputformat': 'json', + 'surface_tilt': 30, 'surface_azimuth': 180, 'outputformat': 'json', 'usehorizon': True, 'userhorizon': None, 'raddatabase': 'PVGIS-SARAH2', 'start': pd.Timestamp(2013, 1, 1), 'end': pd.Timestamp(2014, 5, 1), 'pvcalculation': True, 'peakpower': 10, 'pvtechchoice': 'CIS', 'loss': 5,