pvlib 0.12.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

pvlib/atmosphere.py

@@ -147,20 +147,13 @@ def get_relative_airmass(zenith, model='kastenyoung1989'):
 
         * 'simple' - secant(apparent zenith angle) -
           Note that this gives -Inf at zenith=90
-        * 'kasten1966' - See reference [1] -
-          requires apparent sun zenith
-        * 'youngirvine1967' - See reference [2] -
-          requires true sun zenith
-        * 'kastenyoung1989' (default) - See reference [3] -
-          requires apparent sun zenith
-        * 'gueymard1993' - See reference [4] -
-          requires apparent sun zenith
-        * 'young1994' - See reference [5] -
-          requires true sun zenith
-        * 'pickering2002' - See reference [6] -
-          requires apparent sun zenith
-        * 'gueymard2003' - See references [7] and [8] -
-          requires apparent sun zenith
+        * 'kasten1966' - See [1]_ - requires apparent sun zenith
+        * 'youngirvine1967' - See [2]_ - requires true sun zenith
+        * 'kastenyoung1989' (default) - See [3]_ - requires apparent sun zenith
+        * 'gueymard1993' - See [4]_, [5]_ - requires apparent sun zenith
+        * 'young1994' - See [6]_ - requires true sun zenith
+        * 'pickering2002' - See [7]_ - requires apparent sun zenith
+        * 'gueymard2003' - See [8]_, [9]_ - requires apparent sun zenith
 
     Returns
     -------
@@ -174,41 +167,57 @@ def get_relative_airmass(zenith, model='kastenyoung1989'):
     other models use true (not refraction-adjusted) zenith angle. Apparent
     zenith angles should be calculated at sea level.
 
+    Comparison among several models is reported in [10]_.
+
     References
     ----------
-    .. [1] Fritz Kasten. "A New Table and Approximation Formula for the
-       Relative Optical Air Mass". Technical Report 136, Hanover, N.H.:
-       U.S. Army Material Command, CRREL.
+    .. [1] Fritz Kasten, "A New Table and Approximation Formula for the
+       Relative Optical Air Mass," CRREL (U.S. Army), Hanover, NH, USA,
+       Technical Report 136, 1965.
+       :doi:`11681/5671`
 
     .. [2] A. T. Young and W. M. Irvine, "Multicolor Photoelectric
-       Photometry of the Brighter Planets," The Astronomical Journal, vol.
-       72, pp. 945-950, 1967.
+       Photometry of the Brighter Planets. I. Program and Procedure,"
+       The Astronomical Journal, vol. 72, pp. 945-950, 1967.
+       :doi:`10.1086/110366`
 
-    .. [3] Fritz Kasten and Andrew Young. "Revised optical air mass tables
-       and approximation formula". Applied Optics 28:4735-4738
+    .. [3] Fritz Kasten and Andrew Young, "Revised optical air mass tables
+       and approximation formula," Applied Optics 28:4735-4738, 1989.
+       :doi:`10.1364/AO.28.004735`
 
     .. [4] C. Gueymard, "Critical analysis and performance assessment of
        clear sky solar irradiance models using theoretical and measured
        data," Solar Energy, vol. 51, pp. 121-138, 1993.
+       :doi:`10.1016/0038-092X(93)90074-X`
+
+    .. [5] C. Gueymard, "Development and performance assessment of a clear
+       sky spectral radiation model,” in Proc. of the 22nd ASES Conference,
+       Solar ’93, 1993, pp. 433–438.
 
-    .. [5] A. T. Young, "AIR-MASS AND REFRACTION," Applied Optics, vol. 33,
-       pp. 1108-1110, Feb 1994.
+    .. [6] A. T. Young, "Air-Mass and Refraction," Applied Optics, vol. 33,
+       pp. 1108-1110, Feb. 1994.
+       :doi:`10.1364/AO.33.001108`
 
-    .. [6] Keith A. Pickering. "The Ancient Star Catalog". DIO 12:1, 20,
+    .. [7] Keith A. Pickering, "The Southern Limits of the Ancient Star Catalog
+       and the Commentary of Hipparchos," DIO, vol. 12, pp. 3-27, Sept. 2002.
+       Available at `DIO <http://dioi.org/jc01.pdf>`_
 
-    .. [7] C. Gueymard, "Direct solar transmittance and irradiance
+    .. [8] C. Gueymard, "Direct solar transmittance and irradiance
        predictions with broadband models. Part I: detailed theoretical
        performance assessment". Solar Energy, vol 74, pp. 355-379, 2003.
        :doi:`10.1016/S0038-092X(03)00195-6`
 
-    .. [8] C. Gueymard (2019). Clear-Sky Radiation Models and Aerosol Effects.
-       In: Polo, J., Martín-Pomares, L., Sanfilippo, A. (eds) Solar Resources
-       Mapping. Green Energy and Technology. Springer, Cham.
+    .. [9] C. Gueymard, "Clear-Sky Radiation Models and Aerosol Effects", in
+       Solar Resources Mapping: Fundamentals and Applications,
+       Polo, J., Martín-Pomares, L., Sanfilippo, A. (Eds), Cham, CH: Springer,
+       2019, pp. 137-182.
        :doi:`10.1007/978-3-319-97484-2_5`
 
-    .. [9] Matthew J. Reno, Clifford W. Hansen and Joshua S. Stein, "Global
+    .. [10] Matthew J. Reno, Clifford W. Hansen and Joshua S. Stein, "Global
        Horizontal Irradiance Clear Sky Models: Implementation and Analysis"
-       Sandia Report, (2012).
+       Sandia National Laboratories, Albuquerque, NM, USA, SAND2012-2389, 2012.
+       :doi:`10.2172/1039404`
+
     '''
 
     # set zenith values greater than 90 to nans
@@ -236,7 +245,7 @@ def get_relative_airmass(zenith, model='kastenyoung1989'):
               (np.cos(zenith_rad) ** 3 +
               0.149864*(np.cos(zenith_rad) ** 2) +
               0.0102963*(np.cos(zenith_rad)) + 0.000303978))
-    elif 'gueymard1993' == model:
+    elif 'gueymard1993' == model:  # [4], Eq. 22 and [5], Eq. 3b
         am = (1.0 / (np.cos(zenith_rad) +
               0.00176759*(z)*((94.37515 - z) ** - 1.21563)))
     elif 'gueymard2003' == model:

pvlib/bifacial/infinite_sheds.py

@@ -9,21 +9,23 @@ from pvlib.bifacial import utils
 from pvlib.irradiance import beam_component, aoi, haydavies
 
 
-def _poa_ground_shadows(poa_ground, f_gnd_beam, df, vf_gnd_sky):
+def _poa_ground_shadows(ghi, dhi, albedo, f_gnd_beam, vf_gnd_sky):
     """
     Reduce ground-reflected irradiance to the tilted plane (poa_ground) to
     account for shadows on the ground.
 
     Parameters
     ----------
-    poa_ground : numeric
-        Ground reflected irradiance on the tilted surface, assuming full GHI
-        illumination on all of the ground. [W/m^2]
+    ghi : numeric
+        Global horizontal irradiance, with no adjustments. [W/m^2]
+    dhi : numeric
+        Diffuse horizontal irradiance, with no adjustments. [W/m^2]
+    albedo : numeric
+        Ground albedo, the ratio of reflected to incident irradiance of the
+        ground surface. [W/m^2]
     f_gnd_beam : numeric
         Fraction of the distance between rows that is illuminated (unshaded).
         [unitless]
-    df : numeric
-        Diffuse fraction, the ratio of DHI to GHI. [unitless]
     vf_gnd_sky : numeric
         View factor from the ground to the sky, integrated along the distance
         between rows. [unitless]
@@ -35,7 +37,7 @@ def _poa_ground_shadows(poa_ground, f_gnd_beam, df, vf_gnd_sky):
         ground. [W/m^2]
 
     """
-    return poa_ground * (f_gnd_beam*(1 - df) + df*vf_gnd_sky)
+    return albedo * (f_gnd_beam * (ghi - dhi) + vf_gnd_sky * dhi)
 
 
 def _poa_sky_diffuse_pv(dhi, gcr, surface_tilt):
@@ -339,18 +341,11 @@ def get_irradiance_poa(surface_tilt, surface_azimuth, solar_zenith,
     # and restricted views
     # this is a deviation from [1], because the row to ground view factor
     # is accounted for in a different manner
-    ground_diffuse = ghi * albedo
-
-    # diffuse fraction
-    diffuse_fraction = np.clip(dhi / ghi, 0., 1.)
-    # make diffuse fraction 0 when ghi is small
-    diffuse_fraction = np.where(ghi < 0.0001, 0., diffuse_fraction)
-
     # Reduce ground-reflected irradiance because other rows in the array
     # block irradiance from reaching the ground.
     # [2], Eq. 9
-    ground_diffuse = _poa_ground_shadows(
-        ground_diffuse, f_gnd_beam, diffuse_fraction, vf_gnd_sky)
+    ground_diffuse = _poa_ground_shadows(ghi, dhi, albedo, f_gnd_beam,
+                                         vf_gnd_sky)
 
     # Ground-reflected irradiance on the row surface accounting for
     # the view to the ground. This deviates from [1], Eq. 10, 11 and

pvlib/iotools/__init__.py

@@ -11,6 +11,11 @@ from pvlib.iotools.solrad import get_solrad  # noqa: F401
 from pvlib.iotools.psm3 import get_psm3  # noqa: F401
 from pvlib.iotools.psm3 import read_psm3  # noqa: F401
 from pvlib.iotools.psm3 import parse_psm3  # noqa: F401
+from pvlib.iotools.psm4 import get_nsrdb_psm4_aggregated  # noqa: F401
+from pvlib.iotools.psm4 import get_nsrdb_psm4_tmy  # noqa: F401
+from pvlib.iotools.psm4 import get_nsrdb_psm4_conus  # noqa: F401
+from pvlib.iotools.psm4 import get_nsrdb_psm4_full_disc  # noqa: F401
+from pvlib.iotools.psm4 import read_nsrdb_psm4  # noqa: F401
 from pvlib.iotools.pvgis import get_pvgis_tmy, read_pvgis_tmy  # noqa: F401
 from pvlib.iotools.pvgis import read_pvgis_hourly  # noqa: F401
 from pvlib.iotools.pvgis import get_pvgis_hourly  # noqa: F401

pvlib/iotools/bsrn.py

@@ -9,6 +9,9 @@ import warnings
 import io
 import os
 
+from pvlib.tools import _file_context_manager
+from pvlib._deprecation import deprecated
+
 BSRN_FTP_URL = "ftp.bsrn.awi.de"
 
 BSRN_LR0100_COL_SPECS = [(0, 3), (4, 9), (10, 16), (16, 22), (22, 27),
@@ -109,7 +112,7 @@ def get_bsrn(station, start, end, username, password,
     UserWarning
         If one or more requested files are missing a UserWarning is returned
         with a list of the filenames missing. If no files match the specified
-        station and timeframe a seperate UserWarning is given.
+        station and timeframe a separate UserWarning is given.
 
     Notes
     -----
@@ -136,7 +139,7 @@ def get_bsrn(station, start, end, username, password,
 
     See Also
     --------
-    pvlib.iotools.read_bsrn, pvlib.iotools.parse_bsrn
+    pvlib.iotools.read_bsrn
 
     References
     ----------
@@ -159,8 +162,7 @@ def get_bsrn(station, start, end, username, password,
     end = pd.to_datetime(end)
 
     # Generate list files to download based on start/end (SSSMMYY.dat.gz)
-    filenames = pd.date_range(
-        start, end.replace(day=1) + pd.DateOffset(months=1), freq='1M')\
+    filenames = pd.date_range(start.date().replace(day=1), end, freq='1MS')\
         .strftime(f"{station}%m%y.dat.gz").tolist()
 
     # Create FTP connection
@@ -191,7 +193,7 @@ def get_bsrn(station, start, end, username, password,
                 bio.seek(0)  # reset buffer to start of file
                 gzip_file = io.TextIOWrapper(gzip.GzipFile(fileobj=bio),
                                              encoding='latin1')
-                dfi, metadata = parse_bsrn(gzip_file, logical_records)
+                dfi, metadata = _parse_bsrn(gzip_file, logical_records)
                 dfs.append(dfi)
             # FTP client raises an error if the file does not exist on server
             except ftplib.error_perm as e:
@@ -217,7 +219,7 @@ def get_bsrn(station, start, end, username, password,
     return data, metadata
 
 
-def parse_bsrn(fbuf, logical_records=('0100',)):
+def _parse_bsrn(fbuf, logical_records=('0100',)):
     """
     Parse a file-like buffer of a BSRN station-to-archive file.
 
@@ -382,7 +384,7 @@ def read_bsrn(filename, logical_records=('0100',)):
     Parameters
     ----------
     filename: str or path-like
-        Name or path of a BSRN station-to-archive data file
+        Name, path, or in-memory buffer of a BSRN station-to-archive data file
     logical_records: list or tuple, default: ('0100',)
         List of the logical records (LR) to parse. Options include: '0100',
         '0300', and '0500'.
@@ -439,7 +441,7 @@ def read_bsrn(filename, logical_records=('0100',)):
 
     See Also
     --------
-    pvlib.iotools.parse_bsrn, pvlib.iotools.get_bsrn
+    pvlib.iotools.get_bsrn
 
     References
     ----------
@@ -457,7 +459,11 @@ def read_bsrn(filename, logical_records=('0100',)):
     if str(filename).endswith('.gz'):  # check if file is a gzipped (.gz) file
         open_func, mode = gzip.open, 'rt'
     else:
-        open_func, mode = open, 'r'
+        open_func, mode = _file_context_manager, 'r'
     with open_func(filename, mode) as f:
-        content = parse_bsrn(f, logical_records)
+        content = _parse_bsrn(f, logical_records)
     return content
+
+
+parse_bsrn = deprecated(since="0.13.0", name="parse_bsrn",
+                        alternative="read_bsrn")(read_bsrn)

pvlib/iotools/epw.py

@@ -6,6 +6,9 @@ import io
 from urllib.request import urlopen, Request
 import pandas as pd
 
+from pvlib.tools import _file_context_manager
+from pvlib._deprecation import deprecated
+
 
 def read_epw(filename, coerce_year=None):
     r'''
@@ -23,7 +26,8 @@ def read_epw(filename, coerce_year=None):
     Parameters
     ----------
     filename : String
-        Can be a relative file path, absolute file path, or url.
+        Can be a relative file path, absolute file path, url, or in-memory
+        file buffer.
 
     coerce_year : int, optional
         If supplied, the year of the data will be set to this value. This can
@@ -43,10 +47,6 @@ def read_epw(filename, coerce_year=None):
     metadata : dict
         The site metadata available in the file.
 
-    See Also
-    --------
-    pvlib.iotools.parse_epw
-
     Notes
     -----
 
@@ -226,18 +226,17 @@ def read_epw(filename, coerce_year=None):
             'Safari/537.36')})
         response = urlopen(request)
         with io.StringIO(response.read().decode(errors='ignore')) as csvdata:
-            data, meta = parse_epw(csvdata, coerce_year)
+            data, meta = _parse_epw(csvdata, coerce_year)
 
     else:
-        # Assume it's accessible via the file system
-        with open(str(filename), 'r') as csvdata:
-            data, meta = parse_epw(csvdata, coerce_year)
-
+        # Assume it's a buffer or accessible via the file system
+        with _file_context_manager(filename, 'r') as csvdata:
+            data, meta = _parse_epw(csvdata, coerce_year)
 
     return data, meta
 
 
-def parse_epw(csvdata, coerce_year=None):
+def _parse_epw(csvdata, coerce_year=None):
     """
     Given a file-like buffer with data in Energy Plus Weather (EPW) format,
     parse the data into a dataframe.
@@ -310,3 +309,7 @@ def parse_epw(csvdata, coerce_year=None):
     data.index = idx
 
     return data, meta
+
+
+parse_epw = deprecated(since="0.13.0", name="parse_epw",
+                       alternative="read_epw")(read_epw)

pvlib/iotools/psm3.py

@@ -7,8 +7,8 @@ import io
 import requests
 import pandas as pd
 from json import JSONDecodeError
-import warnings
-from pvlib._deprecation import pvlibDeprecationWarning
+from pvlib._deprecation import deprecated
+from pvlib import tools
 
 NSRDB_API_BASE = "https://developer.nrel.gov"
 PSM_URL = NSRDB_API_BASE + "/api/nsrdb/v2/solar/psm3-2-2-download.csv"
@@ -127,7 +127,7 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
         timeseries data from NREL PSM3
     metadata : dict
         metadata from NREL PSM3 about the record, see
-        :func:`pvlib.iotools.parse_psm3` for fields
+        :func:`pvlib.iotools.read_psm3` for fields
 
     Raises
     ------
@@ -152,7 +152,7 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
 
     See Also
     --------
-    pvlib.iotools.read_psm3, pvlib.iotools.parse_psm3
+    pvlib.iotools.read_psm3
 
     References
     ----------
@@ -216,12 +216,12 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
     # the CSV is in the response content as a UTF-8 bytestring
     # to use pandas we need to create a file buffer from the response
     fbuf = io.StringIO(response.content.decode('utf-8'))
-    return parse_psm3(fbuf, map_variables)
+    return read_psm3(fbuf, map_variables)
 
 
-def parse_psm3(fbuf, map_variables=True):
+def read_psm3(filename, map_variables=True):
     """
-    Parse an NSRDB PSM3 weather file (formatted as SAM CSV). The NSRDB
+    Read an NSRDB PSM3 weather file (formatted as SAM CSV). The NSRDB
     is described in [1]_ and the SAM CSV format is described in [2]_.
 
     .. versionchanged:: 0.9.0
@@ -231,8 +231,8 @@ def parse_psm3(fbuf, map_variables=True):
 
     Parameters
     ----------
-    fbuf: file-like object
-        File-like object containing data to read.
+    filename: str, path-like, or buffer
+        Filename or in-memory buffer of a file containing data to read.
     map_variables: bool, default True
         When true, renames columns of the Dataframe to pvlib variable names
         where applicable. See variable :const:`VARIABLE_MAP`.
@@ -302,12 +302,15 @@ def parse_psm3(fbuf, map_variables=True):
     Examples
     --------
     >>> # Read a local PSM3 file:
+    >>> df, metadata = iotools.read_psm3("data.csv")  # doctest: +SKIP
+
+    >>> # Read a file object or an in-memory buffer:
     >>> with open(filename, 'r') as f:  # doctest: +SKIP
-    ...     df, metadata = iotools.parse_psm3(f)  # doctest: +SKIP
+    ...     df, metadata = iotools.read_psm3(f)  # doctest: +SKIP
 
     See Also
     --------
-    pvlib.iotools.read_psm3, pvlib.iotools.get_psm3
+    pvlib.iotools.get_psm3
 
     References
     ----------
@@ -316,11 +319,25 @@ def parse_psm3(fbuf, map_variables=True):
     .. [2] `Standard Time Series Data File Format
        <https://web.archive.org/web/20170207203107/https://sam.nrel.gov/sites/default/files/content/documents/pdf/wfcsv.pdf>`_
     """
-    # The first 2 lines of the response are headers with metadata
-    metadata_fields = fbuf.readline().split(',')
-    metadata_fields[-1] = metadata_fields[-1].strip()  # strip trailing newline
-    metadata_values = fbuf.readline().split(',')
-    metadata_values[-1] = metadata_values[-1].strip()  # strip trailing newline
+    with tools._file_context_manager(filename) as fbuf:
+        # The first 2 lines of the response are headers with metadata
+        metadata_fields = fbuf.readline().split(',')
+        metadata_values = fbuf.readline().split(',')
+        # get the column names so we can set the dtypes
+        columns = fbuf.readline().split(',')
+        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.
+        columns = [col for col in columns if col != '']
+        dtypes = dict.fromkeys(columns, float)  # all floats except datevec
+        dtypes.update({'Year': int, 'Month': int, 'Day': int, 'Hour': int,
+                       'Minute': int, 'Cloud Type': int, 'Fill Flag': int})
+        data = pd.read_csv(
+            fbuf, header=None, names=columns, usecols=columns, dtype=dtypes,
+            delimiter=',', lineterminator='\n')  # skip carriage returns \r
+
+    metadata_fields[-1] = metadata_fields[-1].strip()  # trailing newline
+    metadata_values[-1] = metadata_values[-1].strip()  # trailing newline
     metadata = dict(zip(metadata_fields, metadata_values))
     # the response is all strings, so set some metadata types to numbers
     metadata['Local Time Zone'] = int(metadata['Local Time Zone'])
@@ -328,22 +345,9 @@ def parse_psm3(fbuf, map_variables=True):
     metadata['Latitude'] = float(metadata['Latitude'])
     metadata['Longitude'] = float(metadata['Longitude'])
     metadata['Elevation'] = int(metadata['Elevation'])
-    # get the column names so we can set the dtypes
-    columns = fbuf.readline().split(',')
-    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.
-    columns = [col for col in columns if col != '']
-    dtypes = dict.fromkeys(columns, float)  # all floats except datevec
-    dtypes.update(Year=int, Month=int, Day=int, Hour=int, Minute=int)
-    dtypes['Cloud Type'] = int
-    dtypes['Fill Flag'] = int
-    data = pd.read_csv(
-        fbuf, header=None, names=columns, usecols=columns, dtype=dtypes,
-        delimiter=',', lineterminator='\n')  # skip carriage returns \r
+
     # the response 1st 5 columns are a date vector, convert to datetime
-    dtidx = pd.to_datetime(
-        data[['Year', 'Month', 'Day', 'Hour', 'Minute']])
+    dtidx = pd.to_datetime(data[['Year', 'Month', 'Day', 'Hour', 'Minute']])
     # in USA all timezones are integers
     tz = 'Etc/GMT%+d' % -metadata['Time Zone']
     data.index = pd.DatetimeIndex(dtidx).tz_localize(tz)
@@ -357,43 +361,5 @@ def parse_psm3(fbuf, map_variables=True):
     return data, metadata
 
 
-def read_psm3(filename, map_variables=True):
-    """
-    Read an NSRDB PSM3 weather file (formatted as SAM CSV). The NSRDB
-    is described in [1]_ and the SAM CSV format is described in [2]_.
-
-    .. versionchanged:: 0.9.0
-       The function now returns a tuple where the first element is a dataframe
-       and the second element is a dictionary containing metadata. Previous
-       versions of this function had the return values switched.
-
-    Parameters
-    ----------
-    filename: str
-        Filename of a file containing data to read.
-    map_variables: bool, default True
-        When true, renames columns of the Dataframe to pvlib variable names
-        where applicable. See variable :const:`VARIABLE_MAP`.
-
-    Returns
-    -------
-    data : pandas.DataFrame
-        timeseries data from NREL PSM3
-    metadata : dict
-        metadata from NREL PSM3 about the record, see
-        :func:`pvlib.iotools.parse_psm3` for fields
-
-    See Also
-    --------
-    pvlib.iotools.parse_psm3, pvlib.iotools.get_psm3
-
-    References
-    ----------
-    .. [1] `NREL National Solar Radiation Database (NSRDB)
-       <https://nsrdb.nrel.gov/>`_
-    .. [2] `Standard Time Series Data File Format
-       <https://web.archive.org/web/20170207203107/https://sam.nrel.gov/sites/default/files/content/documents/pdf/wfcsv.pdf>`_
-    """
-    with open(str(filename), 'r') as fbuf:
-        content = parse_psm3(fbuf, map_variables)
-    return content
+parse_psm3 = deprecated(since="0.13.0", name="parse_psm3",
+                        alternative="read_psm3")(read_psm3)