Merge branch 'main' into replace_pytz_with_zoneinfo

Author: kandersolar

docs/examples/irradiance-transposition/plot_rtranpose_limitations.py

@@ -28,7 +28,7 @@
 #
 # In this example we look at a single point in time and consider a full range
 # of possible GHI and POA global values as shown in figures 3 and 4 of [1]_.
-# Then we use :py:meth:`pvlib.irradiance.ghi_from_poa_driesse_2023` to estimate
+# Then we use :py:meth:`pvlib.irradiance.ghi_from_poa_driesse_2024` to estimate
 # the original GHI from POA global.
 #
 # References
@@ -45,7 +45,7 @@
 
 from pvlib.irradiance import (erbs_driesse,
                               get_total_irradiance,
-                              ghi_from_poa_driesse_2023,
+                              ghi_from_poa_driesse_2024,
                               )
 
 matplotlib.rcParams['axes.grid'] = True
@@ -92,7 +92,7 @@
 
 poa_test = 200
 
-ghi_hat = ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
+ghi_hat = ghi_from_poa_driesse_2024(surface_tilt, surface_azimuth,
                                     solar_zenith, solar_azimuth,
                                     poa_test,
                                     dni_extra,
@@ -156,7 +156,7 @@
 # out, other times not.
 #
 
-result = ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
+result = ghi_from_poa_driesse_2024(surface_tilt, surface_azimuth,
                                    solar_zenith, solar_azimuth,
                                    poa_global,
                                    dni_extra,

docs/examples/irradiance-transposition/plot_rtranpose_year.py

@@ -21,7 +21,7 @@
 # Recovering GHI from POA irradiance is termed "reverse transposition."
 #
 # In this example we start with a TMY file and calculate POA global irradiance.
-# Then we use :py:meth:`pvlib.irradiance.ghi_from_poa_driesse_2023` to estimate
+# Then we use :py:meth:`pvlib.irradiance.ghi_from_poa_driesse_2024` to estimate
 # the original GHI from POA global.  Details of the method found in [1]_.
 #
 # Another method for reverse tranposition called GTI-DIRINT is also
@@ -49,7 +49,7 @@
 from pvlib import iotools, location
 from pvlib.irradiance import (get_extra_radiation,
                               get_total_irradiance,
-                              ghi_from_poa_driesse_2023,
+                              ghi_from_poa_driesse_2024,
                               aoi,
                               )
 
@@ -114,7 +114,7 @@
 
 start = time.process_time()
 
-df['ghi_rev'] = ghi_from_poa_driesse_2023(TILT, ORIENT,
+df['ghi_rev'] = ghi_from_poa_driesse_2024(TILT, ORIENT,
                                           solpos.apparent_zenith,
                                           solpos.azimuth,
                                           df.poa_global,

docs/sphinx/source/reference/irradiance/reverse-transposition.rst

@@ -6,5 +6,5 @@ Reverse transposition models
 .. autosummary::
    :toctree: ../generated/
 
-   irradiance.ghi_from_poa_driesse_2023
+   irradiance.ghi_from_poa_driesse_2024
    irradiance.gti_dirint

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

@@ -12,10 +12,17 @@ Deprecations
 ~~~~~~~~~~~~
 * :py:attr:`pvlib.location.Location.pytz` is deprecated and will be removed in a future release. Use :py:attr:`~pvlib.location.Location.tz` instead.
   (:issue:`2343`, :pull:`2757`)
+* Rename :py:func:`!pvlib.irradiance.ghi_from_poa_driesse_2023` to
+  :py:func:`~pvlib.irradiance.ghi_from_poa_driesse_2024`. The year now reflects
+  the publication date. The old name will be removed in v0.17.0.
+  (:issue:`2774`, :pull:`2777`)
 
 
 Bug fixes
 ~~~~~~~~~
+* Added test coverage for :py:func:`pvlib.irradiance.dirint` with
+  ``np.array`` and ``pd.Series`` inputs. 
+  (:issue:`2751`, :pull:`2752`)
 * Corrects a bug in :py:func:`pvlib.temperature.fuentes`. If inputs were
   data type integer, users can expect modeled cell temperature values to
   increase slightly.
@@ -24,12 +31,22 @@ Bug fixes
   introduced in v0.15.1 (:pull:`2702`) that caused a broadcasting
   ``ValueError`` when ``tracker_theta`` was a 2-D (or higher rank) array.
   (:issue:`2747`, :pull:`2749`)
+* Document that timestamps returned by :py:func:`~pvlib.iotools.get_era5`
+  represent the end of the averaging interval, consistent with ERA5
+  conventions. (:issue:`2772`, :pull:`2773`)
+
+* :py:func:`pvlib.iotools.read_nsrdb_psm4` now parses the file header with the
+  :py:mod:`csv` module instead of a naive ``str.split(',')``, so quoted column
+  names containing commas (e.g. the material names in spectral-on-demand files)
+  are no longer split into spurious columns. (:issue:`2736`, :pull:`2771`)
 
 Enhancements
 ~~~~~~~~~~~~
-* Added mapping of the parameter ``"albedo"`` in
-  :py:func:`~pvlib.iotools.get_nasa_power` when ``map_variables=True``
-  (:pull:`2753`)
+* Add the following parameters to :py:func:`~pvlib.iotools.get_nasa_power`
+  when ``map_variables=True``: ``temp_dew``, ``precipitable_water``,
+  ``relative_humidity``, ``ghi_extra``, ``dhi_clear``, ``longwave_down``,
+  and ``albedo``.
+  (:issue:`2731`, :pull:`2753`, :pull:`2762`)
 
 
 Documentation
@@ -61,8 +78,11 @@ Maintenance
 Contributors
 ~~~~~~~~~~~~
 * :ghuser:`Omesh37`
+* :ghuser:`gaoflow`
 * Cliff Hansen (:ghuser:`cwhanse`)
+* :ghuser:`shethkajal7`
 * Arthur Onno (:ghuser:`ArthurOnnoTerabase`)
 * Adam R. Jensen (:ghuser:`AdamRJensen`)
 * :ghuser:`JoLo90`
-
+* Karl Hill (:ghuser:`karlhillx`)
+* Rajiv Daxini (:ghuser:`RDaxini`)

pvlib/iotools/era5.py

@@ -102,7 +102,7 @@ def get_era5(latitude, longitude, start, end, variables, api_key,
     Returns
     -------
     data : pd.DataFrame
-        Time series data. The index corresponds to the start of the interval.
+        Time series data. The index corresponds to the end of the interval.
     meta : dict
         Metadata.
 

pvlib/iotools/nasa_power.py

@@ -14,11 +14,19 @@
     'ALLSKY_SFC_SW_DWN': 'ghi',
     'ALLSKY_SFC_SW_DIFF': 'dhi',
     'ALLSKY_SFC_SW_DNI': 'dni',
+    'ALLSKY_SRF_ALB': 'albedo',
+    'ALLSKY_SFC_LW_DWN': 'longwave_down',
+    'CLRSKY_SFC_SW_DIFF': 'dhi_clear',
+    'CLRSKY_SFC_SW_DNI': 'dni_clear',
     'CLRSKY_SFC_SW_DWN': 'ghi_clear',
+    'PS': 'pressure',
+    'RH2M': 'relative_humidity',
     'T2M': 'temp_air',
+    'T2MDEW': 'temp_dew',
+    'TQV': 'precipitable_water',
+    'TOA_SW_DWN': 'ghi_extra',
     'WS2M': 'wind_speed_2m',
     'WS10M': 'wind_speed',
-    'ALLSKY_SRF_ALB': 'albedo',
 }
 
 
@@ -82,6 +90,12 @@ def get_nasa_power(latitude, longitude, start, end,
     requests.HTTPError
         Raises an error when an incorrect request is made.
 
+    Notes
+    -----
+    When ``map_variables=True`` the following unit conversions are applied:
+    pressure is converted from kPa to Pa, and precipitable water
+    is converted from kg/m² (mm) to cm.
+
     Returns
     -------
     data : pd.DataFrame
@@ -150,5 +164,11 @@ def get_nasa_power(latitude, longitude, start, end,
     # Rename according to pvlib convention
     if map_variables:
         df = df.rename(columns=VARIABLE_MAP)
+        # PS is returned in kPa; convert to Pa for pvlib compatibility.
+        if 'pressure' in df.columns:
+            df['pressure'] = df['pressure'] * 1000
+        # TQV is returned in kg/m^2 (=mm); convert to cm for compatibility
+        if 'precipitable_water' in df.columns:
+            df['precipitable_water'] = df['precipitable_water'] / 10
 
     return df, meta

pvlib/iotools/psm4.py

@@ -6,6 +6,7 @@
 https://developer.nlr.gov/docs/solar/nsrdb/nsrdb-GOES-full-disc-v4-0-0-download/
 """
 
+import csv
 import io
 from urllib.parse import urljoin
 import requests
@@ -723,11 +724,16 @@ def read_nsrdb_psm4(filename, map_variables=True):
        <https://web.archive.org/web/20170207203107/https://sam.nrel.gov/sites/default/files/content/documents/pdf/wfcsv.pdf>`_
     """
     with tools._file_context_manager(filename) as fbuf:
+        # The first 3 header lines are parsed with the csv module rather than a
+        # naive str.split(',') so that quoted fields containing commas are kept
+        # intact.  Spectral-on-demand files, for instance, have column names
+        # like '"GaAs (Bauhuis et al., 2009)"' whose embedded commas would
+        # otherwise be split into spurious columns (see GH #2736).
         # The first 2 lines of the response are headers with metadata
-        metadata_fields = fbuf.readline().split(',')
-        metadata_values = fbuf.readline().split(',')
+        metadata_fields = next(csv.reader([fbuf.readline()]))
+        metadata_values = next(csv.reader([fbuf.readline()]))
         # get the column names so we can set the dtypes
-        columns = fbuf.readline().split(',')
+        columns = next(csv.reader([fbuf.readline()]))
         columns[-1] = columns[-1].strip()  # strip trailing newline
         # Since the header has so many columns, excel saves blank cols in the
         # data below the header lines.

pvlib/irradiance.py

@@ -16,7 +16,7 @@
 from pvlib import atmosphere, solarposition, tools
 import pvlib  # used to avoid dni name collision in complete_irradiance
 
-from pvlib._deprecation import pvlibDeprecationWarning
+from pvlib._deprecation import pvlibDeprecationWarning, deprecated
 import warnings
 
 
@@ -132,7 +132,9 @@ def _handle_extra_radiation_types(datetime_or_doy, epoch_year):
     # a better way to do it.
     if isinstance(datetime_or_doy, pd.DatetimeIndex):
         to_doy = tools._pandas_to_doy  # won't be evaluated unless necessary
-        def to_datetimeindex(x): return x                       # noqa: E306
+
+        def to_datetimeindex(x):
+            return x                       # noqa: E306
         to_output = partial(pd.Series, index=datetime_or_doy)
     elif isinstance(datetime_or_doy, pd.Timestamp):
         to_doy = tools._pandas_to_doy
@@ -146,12 +148,14 @@ def to_datetimeindex(x): return x                       # noqa: E306
             tools._datetimelike_scalar_to_datetimeindex
         to_output = tools._scalar_out
     elif np.isscalar(datetime_or_doy):  # ints and floats of various types
-        def to_doy(x): return x                                 # noqa: E306
+        def to_doy(x):
+            return x                                 # noqa: E306
         to_datetimeindex = partial(tools._doy_to_datetimeindex,
                                    epoch_year=epoch_year)
         to_output = tools._scalar_out
     else:  # assume that we have an array-like object of doy
-        def to_doy(x): return x                                 # noqa: E306
+        def to_doy(x):
+            return x                                 # noqa: E306
         to_datetimeindex = partial(tools._doy_to_datetimeindex,
                                    epoch_year=epoch_year)
         to_output = tools._array_out
@@ -944,15 +948,18 @@ def reindl(surface_tilt, surface_azimuth, dhi, dni, ghi, dni_extra,
 
     References
     ----------
-    .. [1] Reindl, D. T., Beckmann, W. A., Duffie, J. A., 1990a. Diffuse
-       fraction correlations. Solar Energy 45(1), 1-7.
-       :doi:`10.1016/0038-092X(90)90060-P`
-    .. [2] Reindl, D. T., Beckmann, W. A., Duffie, J. A., 1990b. Evaluation of
-       hourly tilted surface radiation models. Solar Energy 45(1), 9-17.
+    .. [1] D. T. Reindl, "Estimating diffuse radiation on horizontal surfaces
+       and total radiation on tilted surfaces," M.S. thesis, University of
+       Wisconsin-Madison, Madison, WI, USA, 1988. Available:
+       https://web.archive.org/web/20240709013622/https://minds.wisconsin.edu/bitstream/handle/1793/47852/0001.pdf
+    .. [2] D. T. Reindl, W. A. Beckmann, and J. A. Duffie, "Evaluation of
+       hourly tilted surface radiation models," Solar Energy, vol. 45,
+       no. 1, pp. 9–17, 1990.
        :doi:`10.1016/0038-092X(90)90061-G`
-    .. [3] Loutzenhiser P. G. et. al., 2007. Empirical validation of models to
+    .. [3] P. G. Loutzenhiser, H. Manz, C. Felsmann, P. A. Strachan,
+       T. Frank, and G. M. Maxwell, "Empirical validation of models to
        compute solar irradiance on inclined surfaces for building energy
-       simulation. Solar Energy 81(2), 254-267
+       simulation," Solar Energy, vol. 81, no. 2, pp. 254–267, 2007.
        :doi:`10.1016/j.solener.2006.03.009`
     '''
 
@@ -1075,7 +1082,7 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
     airmass : numeric
         Relative (not pressure-corrected) airmass values. If AM is a
         DataFrame it must be of the same size as all other DataFrame
-        inputs. AM must be >=0 (careful using the 1/sec(z) model of AM
+        inputs. AM must be >=0 (careful using the 1/cos(z) model of AM
         generation). [unitless]
 
     model : string, default 'allsitescomposite1990'
@@ -1335,7 +1342,7 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
     airmass : numeric, optional
         Relative (not pressure-corrected) airmass values. If ``airmass`` is a
         DataFrame it must be of the same size as all other DataFrame
-        inputs. AM must be >=0 (careful using the 1/sec(z) model of AM
+        inputs. AM must be >=0 (careful using the 1/cos(z) model of AM
         generation). [unitless]
 
     return_components: bool (optional, default=False)
@@ -1442,7 +1449,7 @@ def _poa_from_ghi(surface_tilt, surface_azimuth,
     Transposition function that includes decomposition of GHI using the
     continuous Erbs-Driesse model.
 
-    Helper function for ghi_from_poa_driesse_2023.
+    Helper function for ghi_from_poa_driesse_2024.
     '''
     # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Nov., 2023
 
@@ -1468,7 +1475,7 @@ def _ghi_from_poa(surface_tilt, surface_azimuth,
     '''
     Reverse transposition function that uses the scalar bisection from scipy.
 
-    Helper function for ghi_from_poa_driesse_2023.
+    Helper function for ghi_from_poa_driesse_2024.
     '''
     # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Nov., 2023
 
@@ -1512,7 +1519,7 @@ def poa_error(ghi):
     return ghi, conv, niter
 
 
-def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
+def ghi_from_poa_driesse_2024(surface_tilt, surface_azimuth,
                               solar_zenith, solar_azimuth,
                               poa_global,
                               dni_extra, airmass=None, albedo=0.25,
@@ -1614,6 +1621,14 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
         return ghi
 
 
+ghi_from_poa_driesse_2023 = deprecated(
+    since="0.15.2",
+    name="pvlib.irradiance.ghi_from_poa_driesse_2023",
+    alternative="pvlib.irradiance.ghi_from_poa_driesse_2024",
+    removal="0.17.0",
+)(ghi_from_poa_driesse_2024)
+
+
 def clearsky_index(ghi, ghi_clear, max_clearsky_index=2.0):
     """
     Calculate the clearsky index.
@@ -1964,14 +1979,14 @@ def dirint(ghi, solar_zenith, times, pressure=101325., use_delta_kt_prime=True,
 
     Returns
     -------
-    dni : array-like
-        The modeled direct normal irradiance, as provided by the
-        DIRINT model. [Wm⁻²]
+    dni : pd.Series
+        Estimated direct normal irradiance. [Wm⁻²]
 
     Notes
     -----
-    DIRINT model requires time series data (ie. one of the inputs must
-    be a vector of length > 2).
+    The DIRINT model was developed for time series data with length > 2.
+    The implementation in pvlib assumes the data are periodic which may
+    affect the first and last DNI values.
 
     References
     ----------
@@ -2109,6 +2124,7 @@ def _dirint_bins(times, kt_prime, zenith, w, delta_kt_prime):
     -------
     tuple of kt_prime_bin, zenith_bin, w_bin, delta_kt_prime_bin
     """
+
     # @wholmgren: the following bin assignments use MATLAB's 1-indexing.
     # Later, we'll subtract 1 to conform to Python's 0-indexing.