Perform dayofyear-based calculations according to UTC, not local time

benchmarks/benchmarks/solarposition.py

@@ -5,7 +5,7 @@
 import datetime
 import pandas as pd
 import pvlib
-from pvlib import solarposition
+from pvlib import solarposition, tools
 
 from packaging.version import Version
 
@@ -51,7 +51,7 @@ def time_sun_rise_set_transit_ephem(self, ndays):
             self.times_daily, self.lat, self.lon)
 
     def time_sun_rise_set_transit_geometric_full_comparison(self, ndays):
-        dayofyear = self.times_daily.dayofyear
+        dayofyear = tools._pandas_to_doy(self.times_daily)
         declination = solarposition.declination_spencer71(dayofyear)
         equation_of_time = solarposition.equation_of_time_spencer71(dayofyear)
         solarposition.sun_rise_set_transit_geometric(

docs/examples/irradiance-transposition/plot_seasonal_tilt.py

@@ -13,7 +13,7 @@
 # with :py:class:`~pvlib.modelchain.ModelChain`.
 
 import pvlib
-from pvlib import pvsystem, location, modelchain, iotools
+from pvlib import pvsystem, location, modelchain, iotools, tools
 from pvlib.temperature import TEMPERATURE_MODEL_PARAMETERS
 import pandas as pd
 import pathlib
@@ -32,7 +32,8 @@ class SeasonalTiltMount(pvsystem.AbstractMount):
     surface_azimuth: float = 180.0
 
     def get_orientation(self, solar_zenith, solar_azimuth):
-        tilts = [self.monthly_tilts[m-1] for m in solar_zenith.index.month]
+        tilts = [self.monthly_tilts[m-1]
+                 for m in tools._pandas_to_utc(solar_zenith.index).month]
         return pd.DataFrame({
             'surface_tilt': tilts,
             'surface_azimuth': self.surface_azimuth,

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

@@ -33,6 +33,11 @@ Enhancements
 
 Bug fixes
 ~~~~~~~~~
+* Changes clearsky.lookup_linke_turbidity and irradiance.get_extra_radiation to use UTC instead of local
+  timezone when determining day of year. pandas does not account for timezone when computing day of year.
+  Instead, pandas returns the DOY using only the time part of the datetime. As a consequence the same
+  datetime with different localizations can yield different DOY values, which can cause small inconsistencies
+  in some solar position and clear sky calculations. (:issue:`2054`, :pull:`2055`)
 
 
 Testing
@@ -61,6 +66,7 @@ Requirements
 Contributors
 ~~~~~~~~~~~~
 * Echedey Luis (:ghuser:`echedey-ls`)
+* Yunho Kee (:ghuser:`yhkee0404`)
 * Chris Deline (:ghuser:`cdeline`)
 * Ioannis Sifnaios (:ghuser:`IoannisSifnaios`)
 * Leonardo Micheli (:ghuser:`lmicheli`)

docs/tutorials/irradiance.ipynb

@@ -16,7 +16,8 @@
     "This tutorial requires pvlib >= 0.6.0.\n",
     "\n",
     "Authors:\n",
-    "* Will Holmgren (@wholmgren), University of Arizona. July 2014, April 2015, July 2015, March 2016, July 2016, February 2017, August 2018."
+    "* Will Holmgren (@wholmgren), University of Arizona. July 2014, April 2015, July 2015, March 2016, July 2016, February 2017, August 2018.\n",
+    "* Yunho Kee (@yhkee0404), Haezoom. Jun 2024."
    ]
   },
   {
@@ -393,6 +394,7 @@
    "source": [
     "tus = pvlib.location.Location(32.2, -111, 'US/Arizona', 700, 'Tucson')\n",
     "times = pd.date_range(start='2016-01-01', end='2016-01-02', freq='1min', tz=tus.tz)\n",
+    "times_utc = times.tz_convert('UTC')\n",
     "ephem_data = tus.get_solarposition(times)\n",
     "irrad_data = tus.get_clearsky(times)\n",
     "irrad_data.plot()\n",
@@ -810,7 +812,7 @@
     "                                            ephem_data['apparent_zenith'], ephem_data['azimuth'])\n",
     "klucher_diffuse.plot(label='klucher diffuse')\n",
     "\n",
-    "dni_et = pvlib.irradiance.get_extra_radiation(times.dayofyear)\n",
+    "dni_et = pvlib.irradiance.get_extra_radiation(times_utc.dayofyear)\n",
     "reindl_diffuse = pvlib.irradiance.reindl(surf_tilt, surf_az, \n",
     "                                          irrad_data['dhi'], irrad_data['dni'], irrad_data['ghi'], dni_et,\n",
     "                                          ephem_data['apparent_zenith'], ephem_data['azimuth'])\n",
@@ -858,7 +860,7 @@
     "                                            ephem_data['apparent_zenith'], ephem_data['azimuth'])\n",
     "klucher_diffuse.plot(label='klucher diffuse')\n",
     "\n",
-    "dni_et = pvlib.irradiance.get_extra_radiation(times.dayofyear)\n",
+    "dni_et = pvlib.irradiance.get_extra_radiation(times_utc.dayofyear)\n",
     "reindl_diffuse = pvlib.irradiance.reindl(surf_tilt, surf_az, \n",
     "                                          irrad_data['dhi'], irrad_data['dni'], irrad_data['ghi'], dni_et,\n",
     "                                          ephem_data['apparent_zenith'], ephem_data['azimuth'])\n",
@@ -913,7 +915,7 @@
     "                                            ephem_data['apparent_zenith'], ephem_data['azimuth'])\n",
     "klucher_diffuse.plot(label='klucher diffuse')\n",
     "\n",
-    "dni_et = pvlib.irradiance.get_extra_radiation(times.dayofyear)\n",
+    "dni_et = pvlib.irradiance.get_extra_radiation(times_utc.dayofyear)\n",
     "\n",
     "haydavies_diffuse = pvlib.irradiance.haydavies(surf_tilt, surf_az, \n",
     "                                                irrad_data['dhi'], irrad_data['dni'], dni_et,\n",
@@ -967,7 +969,7 @@
     "                                            ephem_data['apparent_zenith'], ephem_data['azimuth'])\n",
     "klucher_diffuse.plot(label='klucher diffuse')\n",
     "\n",
-    "dni_et = pvlib.irradiance.get_extra_radiation(times.dayofyear)\n",
+    "dni_et = pvlib.irradiance.get_extra_radiation(times_utc.dayofyear)\n",
     "\n",
     "haydavies_diffuse = pvlib.irradiance.haydavies(surf_tilt, surf_az, \n",
     "                                                irrad_data['dhi'], irrad_data['dni'], dni_et,\n",
@@ -1028,7 +1030,7 @@
     "                                            ephem_data['apparent_zenith'], ephem_data['azimuth'])\n",
     "klucher_diffuse.plot(label='klucher diffuse')\n",
     "\n",
-    "dni_et = pvlib.irradiance.get_extra_radiation(times.dayofyear)\n",
+    "dni_et = pvlib.irradiance.get_extra_radiation(times_utc.dayofyear)\n",
     "\n",
     "haydavies_diffuse = pvlib.irradiance.haydavies(surf_tilt, surf_az, \n",
     "                                                irrad_data['dhi'], irrad_data['dni'], dni_et,\n",
@@ -1067,7 +1069,7 @@
     "sun_az = ephem_data['azimuth']\n",
     "DNI = irrad_data['dni']\n",
     "DHI = irrad_data['dhi']\n",
-    "DNI_ET = pvlib.irradiance.get_extra_radiation(times.dayofyear)\n",
+    "DNI_ET = pvlib.irradiance.get_extra_radiation(times_utc.dayofyear)\n",
     "AM = pvlib.atmosphere.get_relative_airmass(sun_zen)\n",
     "\n",
     "surf_tilt = 32\n",
@@ -1316,7 +1318,7 @@
     "sun_az = ephem_data['azimuth']\n",
     "DNI = irrad_data['dni']\n",
     "DHI = irrad_data['dhi']\n",
-    "DNI_ET = pvlib.irradiance.get_extra_radiation(times.dayofyear)\n",
+    "DNI_ET = pvlib.irradiance.get_extra_radiation(times_utc.dayofyear)\n",
     "AM = pvlib.atmosphere.get_relative_airmass(sun_zen)\n",
     "\n",
     "surf_tilt = 32\n",
@@ -1330,7 +1332,7 @@
     "                                            ephem_data['apparent_zenith'], ephem_data['azimuth'])\n",
     "klucher_diffuse.plot(label='klucher diffuse')\n",
     "\n",
-    "dni_et = pvlib.irradiance.get_extra_radiation(times.dayofyear)\n",
+    "dni_et = pvlib.irradiance.get_extra_radiation(times_utc.dayofyear)\n",
     "\n",
     "haydavies_diffuse = pvlib.irradiance.haydavies(surf_tilt, surf_az, \n",
     "                                                irrad_data['dhi'], irrad_data['dni'], dni_et,\n",
@@ -1371,7 +1373,7 @@
     "sun_az = ephem_data['azimuth']\n",
     "DNI = irrad_data['dni']\n",
     "DHI = irrad_data['dhi']\n",
-    "DNI_ET = pvlib.irradiance.get_extra_radiation(times.dayofyear)\n",
+    "DNI_ET = pvlib.irradiance.get_extra_radiation(times_utc.dayofyear)\n",
     "AM = pvlib.atmosphere.get_relative_airmass(sun_zen)\n",
     "\n",
     "surf_tilt = 32\n",
@@ -1385,7 +1387,7 @@
     "                                            ephem_data['apparent_zenith'], ephem_data['azimuth'])\n",
     "klucher_diffuse.plot(label='klucher diffuse')\n",
     "\n",
-    "dni_et = pvlib.irradiance.get_extra_radiation(times.dayofyear)\n",
+    "dni_et = pvlib.irradiance.get_extra_radiation(times_utc.dayofyear)\n",
     "\n",
     "haydavies_diffuse = pvlib.irradiance.haydavies(surf_tilt, surf_az, \n",
     "                                                irrad_data['dhi'], irrad_data['dni'], dni_et,\n",

pvlib/clearsky.py

@@ -169,6 +169,13 @@
     Returns
     -------
     turbidity : Series
+
+    Notes
+    -----
+    Linke turbidity is obtained from a file of historical monthly averages.
+    The returned value for each time is either the monthly value or an
+    interpolated value to smooth the transition between months.
+    Interpolation is done on the day of year as determined by UTC.
     """
 
     # The .h5 file 'LinkeTurbidities.h5' contains a single 2160 x 4320 x 12
@@ -201,7 +208,7 @@
     if interp_turbidity:
         linke_turbidity = _interpolate_turbidity(lts, time)
     else:
-        months = time.month - 1
+        months = tools._pandas_to_utc(time).month - 1
         linke_turbidity = pd.Series(lts[months], index=time)
 
     linke_turbidity /= 20.
@@ -247,14 +254,16 @@
     # Jan 1 - Jan 15 and Dec 16 - Dec 31.
     lts_concat = np.concatenate([[lts[-1]], lts, [lts[0]]])
 
+    time_utc = tools._pandas_to_utc(time)
+
     # handle leap years
     try:
-        isleap = time.is_leap_year
+        isleap = time_utc.is_leap_year
     except AttributeError:
-        year = time.year
+        year = time_utc.year
         isleap = _is_leap_year(year)
 
-    dayofyear = time.dayofyear
+    dayofyear = time_utc.dayofyear
     days_leap = _calendar_month_middles(2016)
     days_no_leap = _calendar_month_middles(2015)
 

pvlib/iotools/solrad.py

@@ -193,9 +193,9 @@ def get_solrad(station, start, end,
     # Use pd.to_datetime so that strings (e.g. '2021-01-01') are accepted
     start = pd.to_datetime(start)
     end = pd.to_datetime(end)
+    dates = pd.date_range(start.floor('d'), end, freq='d')
 
     # Generate list of filenames
-    dates = pd.date_range(start.floor('d'), end, freq='d')
     station = station.lower()
     filenames = [
         f"{station}/{d.year}/{station}{d.strftime('%y')}{d.dayofyear:03}.dat"