pvlib 0.11.0a1__py3-none-any.whl → 0.11.2__py3-none-any.whl

pvlib/clearsky.py

@@ -9,7 +9,6 @@ import calendar
 
 import numpy as np
 import pandas as pd
-from scipy.optimize import minimize_scalar
 from scipy.linalg import hankel
 import h5py
 
@@ -169,6 +168,13 @@ def lookup_linke_turbidity(time, latitude, longitude, filepath=None,
     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 +207,7 @@ def lookup_linke_turbidity(time, latitude, longitude, filepath=None,
     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 +253,11 @@ def _interpolate_turbidity(lts, time):
     # Jan 1 - Jan 15 and Dec 16 - Dec 31.
     lts_concat = np.concatenate([[lts[-1]], lts, [lts[0]]])
 
-    # handle leap years
-    try:
-        isleap = time.is_leap_year
-    except AttributeError:
-        year = time.year
-        isleap = _is_leap_year(year)
+    time_utc = tools._pandas_to_utc(time)
+
+    isleap = time_utc.is_leap_year
 
-    dayofyear = time.dayofyear
+    dayofyear = time_utc.dayofyear
     days_leap = _calendar_month_middles(2016)
     days_no_leap = _calendar_month_middles(2015)
 
@@ -324,13 +327,13 @@ def haurwitz(apparent_zenith):
     '''
 
     cos_zenith = tools.cosd(apparent_zenith.values)
-    clearsky_ghi = np.zeros_like(apparent_zenith.values)
+    ghi_clear = np.zeros_like(apparent_zenith.values)
     cos_zen_gte_0 = cos_zenith > 0
-    clearsky_ghi[cos_zen_gte_0] = (1098.0 * cos_zenith[cos_zen_gte_0] *
-                                   np.exp(-0.059/cos_zenith[cos_zen_gte_0]))
+    ghi_clear[cos_zen_gte_0] = (1098.0 * cos_zenith[cos_zen_gte_0] *
+                                np.exp(-0.059/cos_zenith[cos_zen_gte_0]))
 
     df_out = pd.DataFrame(index=apparent_zenith.index,
-                          data=clearsky_ghi,
+                          data=ghi_clear,
                           columns=['ghi'])
 
     return df_out
@@ -680,22 +683,26 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
                     var_diff=0.005, slope_dev=8, max_iterations=20,
                     return_components=False):
     """
-    Detects clear sky times according to the algorithm developed by Reno
-    and Hansen for GHI measurements. The algorithm [1]_ was designed and
-    validated for analyzing GHI time series only. Users may attempt to
-    apply it to other types of time series data using different filter
-    settings, but should be skeptical of the results.
+    Detects clear sky times using the algorithm developed by Reno
+    and Hansen.
+
+    The algorithm [1]_ was designed and
+    validated for analyzing GHI time series. Jordan and Hansen [2]_ extended
+    the algorithm to plane-of-array (POA) irradiance measurements.
 
-    The algorithm detects clear sky times by comparing statistics for a
+    The algorithm [1]_ detects clear sky times by comparing statistics for a
     measured time series and an expected clearsky time series.
     Statistics are calculated using a sliding time window (e.g., 10
     minutes). An iterative algorithm identifies clear periods, uses the
     identified periods to estimate bias in the clearsky data, scales the
     clearsky data and repeats.
 
-    Clear times are identified by meeting 5 criteria. Default values for
+    Clear times are identified by meeting five criteria. Default values for
     these thresholds are appropriate for 10 minute windows of 1 minute
-    GHI data.
+    GHI data. For data at longer intervals, it is recommended
+    to set ``infer_limits=True`` to use the thresholds from [2]_.
+
+    For POA data, ``clearsky`` must be on the same plane as ``measured``.
 
     Parameters
     ----------
@@ -710,8 +717,8 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
         If True, does not use passed in kwargs (or defaults), but instead
         interpolates these values from Table 1 in [2]_.
     window_length : int, default 10
-        Length of sliding time window in minutes. Must be greater than 2
-        periods.
+        Length of sliding time window in minutes. Each window must contain at
+        least three data points.
     mean_diff : float, default 75
         Threshold value for agreement between mean values of measured
         and clearsky in each interval, see Eq. 6 in [1]. [W/m2]
@@ -720,8 +727,6 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
         clearsky values in each interval, see Eq. 7 in [1]. [W/m2]
     lower_line_length : float, default -5
         Lower limit of line length criterion from Eq. 8 in [1].
-        Criterion satisfied when lower_line_length < line length difference
-        < upper_line_length.
     upper_line_length : float, default 10
         Upper limit of line length criterion from Eq. 8 in [1].
     var_diff : float, default 0.005
@@ -733,7 +738,7 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
         change in successive values, see Eqs. 12 through 14 in [1].
     max_iterations : int, default 20
         Maximum number of times to apply a different scaling factor to
-        the clearsky and redetermine clear_samples. Must be 1 or larger.
+        the clearsky and redetermine ``clear_samples``. Must be 1 or larger.
     return_components : bool, default False
         Controls if additional output should be returned. See below.
 
@@ -745,19 +750,23 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
 
     components : OrderedDict, optional
         Dict of arrays of whether or not the given time window is clear
-        for each condition. Only provided if return_components is True.
+        for each condition. Only provided if ``return_components`` is True.
 
     alpha : scalar, optional
-        Scaling factor applied to the clearsky_ghi to obtain the
-        detected clear_samples. Only provided if return_components is
+        Scaling factor applied to ``clearsky`` to obtain the
+        detected ``clear_samples``. Only provided if ``return_components`` is
         True.
 
     Raises
     ------
     ValueError
-        If measured is not a Series and times is not provided
+        If ``measured`` is not a Series and times is not provided.
+    ValueError
+        If a window contains less than three data points.
+    ValueError
+        If the measured data is not sufficient to fill a window.
     NotImplementedError
-        If timestamps are not equally spaced
+        If timestamps are not equally spaced.
 
     References
     ----------
@@ -809,6 +818,13 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
     sample_interval, samples_per_window = \
         tools._get_sample_intervals(times, window_length)
 
+    if samples_per_window < 3:
+        raise ValueError(f"Samples per window of {samples_per_window}"
+                         " found. Each window must contain at least 3 data"
+                         " points."
+                         f" Window length of {window_length} found; increase"
+                         f" window length to {3*sample_interval} or longer.")
+
     # if infer_limits, find threshold values using the sample interval
     if infer_limits:
         window_length, mean_diff, max_diff, lower_line_length, \
@@ -874,25 +890,11 @@ def detect_clearsky(measured, clearsky, times=None, infer_limits=False,
         clear_meas = meas[clear_samples]
         clear_clear = clear[clear_samples]
 
-        def rmse(alpha):
-            return np.sqrt(np.mean((clear_meas - alpha*clear_clear)**2))
-
-        optimize_result = minimize_scalar(rmse)
-        if not optimize_result.success:
-            try:
-                message = "Optimizer exited unsuccessfully: " \
-                           + optimize_result.message
-            except AttributeError:
-                message = "Optimizer exited unsuccessfully: \
-                           No message explaining the failure was returned. \
-                           If you would like to see this message, please \
-                           update your scipy version (try version 1.8.0 \
-                           or beyond)."
-            raise RuntimeError(message)
-
-        else:
-            alpha = optimize_result.x
-
+        # Compute arg min of MSE between model and observations
+        C = (clear_clear**2).sum()
+        if not (pd.isna(C) or C == 0):  # safety check
+            # only update alpha if C is strictly positive
+            alpha = (clear_meas * clear_clear).sum() / C
         if round(alpha*10000) == round(previous_alpha*10000):
             break
     else:
@@ -941,7 +943,7 @@ def bird(zenith, airmass_relative, aod380, aod500, precipitable_water,
     zenith is never explicitly defined in the report, since the purpose
     was to compare existing clear sky models with "rigorous radiative
     transfer models" (RTM) it is possible that apparent zenith was
-    obtained as output from the RTM. However, the implentation presented
+    obtained as output from the RTM. However, the implementation presented
     in PVLIB is tested against the NREL Excel implementation by Daryl
     Myers which uses an analytical expression for solar zenith instead
     of apparent zenith.

pvlib/data/pvgis_tmy_meta.json

@@ -1,93 +1,32 @@
-{
-  "inputs": {
-    "location": {
-      "description": "Selected location",
-      "variables": {
-        "latitude": {
-          "description": "Latitude",
-          "units": "decimal degree"
-        },
-        "longitude": {
-          "description": "Longitude",
-          "units": "decimal degree"
-        },
-        "elevation": {
-          "description": "Elevation",
-          "units": "m"
-        }
-      }
-    },
-    "meteo_data": {
-      "description": "Sources of meteorological data",
-      "variables": {
-        "radiation_db": {
-          "description": "Solar radiation database"
-        },
-        "meteo_db": {
-          "description": "Database used for meteorological variables other than solar radiation"
-        },
-        "year_min": {
-          "description": "First year of the calculations"
-        },
-        "year_max": {
-          "description": "Last year of the calculations"
-        },
-        "use_horizon": {
-          "description": "Include horizon shadows"
-        },
-        "horizon_db": {
-          "description": "Source of horizon data"
-        }
-      }
-    }
-  },
-  "outputs": {
-    "months_selected": {
-      "type": "time series",
-      "timestamp": "monthly",
-      "description": "months selected for the TMY"
-    },
-    "tmy_hourly": {
-      "type": "time series",
-      "timestamp": "hourly",
-      "variables": {
-        "T2m": {
-          "description": "2-m air temperature",
-          "units": "degree Celsius"
-        },
-        "RH": {
-          "description": "relative humidity",
-          "units": "%"
-        },
-        "G(h)": {
-          "description": "Global irradiance on the horizontal plane",
-          "units": "W/m2"
-        },
-        "Gb(n)": {
-          "description": "Beam/direct irradiance on a plane always normal to sun rays",
-          "units": "W/m2"
-        },
-        "Gd(h)": {
-          "description": "Diffuse irradiance on the horizontal plane",
-          "units": "W/m2"
-        },
-        "IR(h)": {
-          "description": "Surface infrared (thermal) irradiance on a horizontal plane",
-          "units": "W/m2"
-        },
-        "WS10m": {
-          "description": "10-m total wind speed",
-          "units": "m/s"
-        },
-        "WD10m": {
-          "description": "10-m wind direction (0 = N, 90 = E)",
-          "units": "degree"
-        },
-        "SP": {
-          "description": "Surface (air) pressure",
-          "units": "Pa"
-        }
-      }
-    }
-  }
-}
+{"inputs": {"location": {"description": "Selected location",
+   "variables": {"latitude": {"description": "Latitude",
+     "units": "decimal degree"},
+    "longitude": {"description": "Longitude", "units": "decimal degree"},
+    "elevation": {"description": "Elevation", "units": "m"}}},
+  "meteo_data": {"description": "Sources of meteorological data",
+   "variables": {"radiation_db": {"description": "Solar radiation database"},
+    "meteo_db": {"description": "Database used for meteorological variables other than solar radiation"},
+    "year_min": {"description": "First year of the calculations"},
+    "year_max": {"description": "Last year of the calculations"},
+    "use_horizon": {"description": "Include horizon shadows"},
+    "horizon_db": {"description": "Source of horizon data"}}}},
+ "outputs": {"months_selected": {"type": "time series",
+   "timestamp": "monthly",
+   "description": "months selected for the TMY"},
+  "tmy_hourly": {"type": "time series",
+   "timestamp": "hourly",
+   "variables": {"T2m": {"description": "2-m air temperature",
+     "units": "degree Celsius"},
+    "RH": {"description": "relative humidity", "units": "%"},
+    "G(h)": {"description": "Global irradiance on the horizontal plane",
+     "units": "W/m2"},
+    "Gb(n)": {"description": "Beam/direct irradiance on a plane always normal to sun rays",
+     "units": "W/m2"},
+    "Gd(h)": {"description": "Diffuse irradiance on the horizontal plane",
+     "units": "W/m2"},
+    "IR(h)": {"description": "Surface infrared (thermal) irradiance on a horizontal plane",
+     "units": "W/m2"},
+    "WS10m": {"description": "10-m total wind speed", "units": "m/s"},
+    "WD10m": {"description": "10-m wind direction (0 = N, 90 = E)",
+     "units": "degree"},
+    "SP": {"description": "Surface (air) pressure", "units": "Pa"}}}}}