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

pvlib/iotools/sodapro.py

@@ -7,7 +7,9 @@ import pandas as pd
 import requests
 import io
 import warnings
+from pvlib import tools
 
+from pvlib._deprecation import deprecated, renamed_kwarg_warning
 
 URL = 'api.soda-solardata.com'
 
@@ -43,10 +45,15 @@ SUMMATION_PERIOD_TO_TIME_STEP = {'0 year 0 month 0 day 0 h 1 min 0 s': '1min',
                                  '0 year 1 month 0 day 0 h 0 min 0 s': '1M'}
 
 
+@renamed_kwarg_warning(
+    since='0.13.0',
+    old_param_name='server',
+    new_param_name='url',
+    removal="0.14.0")
 def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
              altitude=None, time_step='1h', time_ref='UT', verbose=False,
              integrated=False, label=None, map_variables=True,
-             server=URL, timeout=30):
+             url=URL, timeout=30):
     """Retrieve irradiance and clear-sky time series from CAMS.
 
     Time-series of radiation and/or clear-sky global, beam, and
@@ -96,7 +103,7 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
     map_variables: bool, default: True
         When true, renames columns of the DataFrame to pvlib variable names
         where applicable. See variable :const:`VARIABLE_MAP`.
-    server: str, default: :const:`pvlib.iotools.sodapro.URL`
+    url: str, default: :const:`pvlib.iotools.sodapro.URL`
         Base url of the SoDa Pro CAMS Radiation API.
     timeout : int, default: 30
         Time in seconds to wait for server response before timeout
@@ -143,9 +150,15 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
     e.g. `sza` becomes `solar_zenith`. See variable :const:`VARIABLE_MAP` for
     the complete mapping.
 
+    For large geospatial areas, CAMS offers a pre-calculated
+    gridded dataset [4]_ over land and coastal areas. This dataset
+    may not include the most recent data coverage and may not be
+    based on the most recent CAMS version. This dataset is not available
+    through pvlib.
+
     See Also
     --------
-    pvlib.iotools.read_cams, pvlib.iotools.parse_cams
+    pvlib.iotools.read_cams
 
     Raises
     ------
@@ -155,13 +168,15 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
 
     References
     ----------
-    .. [1] `CAMS solar radiation documentation
-       <https://atmosphere.copernicus.eu/solar-radiation>`_
+    .. [1] `CAMS solar radiation time-series documentation. Climate Data Store.
+       <https://ads.atmosphere.copernicus.eu/datasets/cams-solar-radiation-timeseries>`_
     .. [2] `CAMS Radiation Automatic Access (SoDa)
        <https://www.soda-pro.com/help/cams-services/cams-radiation-service/automatic-access>`_
     .. [3] A. R. Jensen et al., pvlib iotools — Open-source Python functions
        for seamless access to solar irradiance data. Solar Energy. 2023. Vol
        266, pp. 112092. :doi:`10.1016/j.solener.2023.112092`
+    .. [4] `CAMS gridded solar radiation documentation.
+       <https://ads.atmosphere.copernicus.eu/datasets/cams-gridded-solar-radiation>`_
     """
     try:
         time_step_str = TIME_STEPS_MAP[time_step]
@@ -189,7 +204,7 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
     email = email.replace('@', '%2540')  # Format email address
     identifier = 'get_{}'.format(identifier.lower())  # Format identifier str
 
-    base_url = f"https://{server}/service/wps"
+    base_url = f"https://{url}/service/wps"
 
     data_inputs_dict = {
         'latitude': latitude,
@@ -202,7 +217,7 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
         'username': email,
         'verbose': verbose}
 
-    # Manual formatting of the input parameters seperating each by a semicolon
+    # Manual formatting of the input parameters separating each by a semicolon
     data_inputs = ";".join([f"{key}={value}" for key, value in
                             data_inputs_dict.items()])
 
@@ -214,7 +229,7 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
               }
 
     # The DataInputs parameter of the URL has to be manually formatted and
-    # added to the base URL as it contains sub-parameters seperated by
+    # added to the base URL as it contains sub-parameters separated by
     # semi-colons, which gets incorrectly formatted by the requests function
     # if passed using the params argument.
     res = requests.get(base_url + '?DataInputs=' + data_inputs, params=params,
@@ -231,20 +246,22 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
     # Successful requests returns a csv data file
     else:
         fbuf = io.StringIO(res.content.decode('utf-8'))
-        data, metadata = parse_cams(fbuf, integrated=integrated, label=label,
-                                    map_variables=map_variables)
+        data, metadata = read_cams(fbuf, integrated=integrated, label=label,
+                                   map_variables=map_variables)
         return data, metadata
 
 
-def parse_cams(fbuf, integrated=False, label=None, map_variables=True):
+def read_cams(filename, integrated=False, label=None, map_variables=True):
     """
-    Parse a file-like buffer with data in the format of a CAMS Radiation or
-    McClear file. The CAMS solar radiation services are described in [1]_.
+    Read a file or file-like buffer with data in the format of a CAMS
+    Radiation or McClear file.
+
+    The CAMS solar radiation services are described in [1]_.
 
     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.
     integrated: boolean, default False
         Whether to return radiation parameters as integrated values (Wh/m^2)
         or as average irradiance values (W/m^2) (pvlib preferred units)
@@ -264,23 +281,31 @@ def parse_cams(fbuf, integrated=False, label=None, map_variables=True):
 
     See Also
     --------
-    pvlib.iotools.read_cams, pvlib.iotools.get_cams
+    pvlib.iotools.get_cams
 
     References
     ----------
-    .. [1] `CAMS solar radiation documentation
-       <https://atmosphere.copernicus.eu/solar-radiation>`_
+    .. [1] `CAMS solar radiation time-series documentation. Climate Data Store.
+       <https://ads.atmosphere.copernicus.eu/datasets/cams-solar-radiation-timeseries>`_
     """
     metadata = {}
-    # Initial lines starting with # contain metadata
-    while True:
-        line = fbuf.readline().rstrip('\n')
-        if line.startswith('# Observation period'):
-            # The last line of the metadata section contains the column names
-            names = line.lstrip('# ').split(';')
-            break  # End of metadata section has been reached
-        elif ': ' in line:
-            metadata[line.split(': ')[0].lstrip('# ')] = line.split(': ')[1]
+
+    with tools._file_context_manager(filename) as fbuf:
+
+        # Initial lines starting with # contain metadata
+        while True:
+            line = fbuf.readline().rstrip('\n')
+            if line.startswith('# Observation period'):
+                # The last line of the metadata section has the column names
+                names = line.lstrip('# ').split(';')
+                break  # End of metadata section has been reached
+            elif ': ' in line:
+                key = line.split(': ')[0].lstrip('# ')
+                value = line.split(': ')[1]
+                metadata[key] = value
+
+        data = pd.read_csv(fbuf, sep=';', comment='#', header=None,
+                           names=names)
 
     # Convert latitude, longitude, and altitude values from strings to floats
     for k_old in list(metadata.keys()):
@@ -296,8 +321,6 @@ def parse_cams(fbuf, integrated=False, label=None, map_variables=True):
         metadata['Summarization (integration) period']]
     metadata['time_step'] = time_step
 
-    data = pd.read_csv(fbuf, sep=';', comment='#', header=None, names=names)
-
     obs_period = data['Observation period'].str.split('/')
 
     # Set index as the start observation time (left) and localize to UTC
@@ -336,43 +359,5 @@ def parse_cams(fbuf, integrated=False, label=None, map_variables=True):
     return data, metadata
 
 
-def read_cams(filename, integrated=False, label=None, map_variables=True):
-    """
-    Read a CAMS Radiation or McClear file into a pandas DataFrame.
-
-    CAMS Radiation and McClear are described in [1]_.
-
-    Parameters
-    ----------
-    filename: str
-        Filename of a file containing data to read.
-    integrated: boolean, default False
-        Whether to return radiation parameters as integrated values (Wh/m^2)
-        or as average irradiance values (W/m^2) (pvlib preferred units)
-    label : {'right', 'left}, optional
-        Which bin edge label to label time-step with. The default is 'left' for
-        all time steps except for '1M' which has a default of 'right'.
-    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 CAMS Radiation or McClear.
-        See :func:`pvlib.iotools.get_cams` for fields.
-    metadata: dict
-        Metadata available in the file.
-
-    See Also
-    --------
-    pvlib.iotools.parse_cams, pvlib.iotools.get_cams
-
-    References
-    ----------
-    .. [1] `CAMS solar radiation documentation
-       <https://atmosphere.copernicus.eu/solar-radiation>`_
-    """
-    with open(str(filename), 'r') as fbuf:
-        content = parse_cams(fbuf, integrated, label, map_variables)
-    return content
+parse_cams = deprecated(since="0.13.0", name="parse_cams",
+                        alternative="read_cams")(read_cams)

pvlib/iotools/srml.py

@@ -236,8 +236,7 @@ def get_srml(station, start, end, filetype='PO', map_variables=True,
     end = pd.to_datetime(end)
 
     # Generate list of months
-    months = pd.date_range(
-        start, end.replace(day=1) + pd.DateOffset(months=1), freq='1M')
+    months = pd.date_range(start.date().replace(day=1), end, freq='1MS')
     months_str = months.strftime('%y%m')
 
     # Generate list of filenames

pvlib/irradiance.py

@@ -35,25 +35,30 @@ def get_extra_radiation(datetime_or_doy, solar_constant=1366.1,
     """
     Determine extraterrestrial radiation from day of year.
 
+    Specific references for each method are cited in the parameter descriptions
+    below, while a more general discussion of the different models may also be
+    found in [1]_ and [2]_.
+
     Parameters
     ----------
     datetime_or_doy : numeric, array, date, datetime, Timestamp, DatetimeIndex
         Day of year, array of days of year, or datetime-like object
 
     solar_constant : float, default 1366.1
-        The solar constant.
+        The solar constant. [Wm⁻²]
 
-    method : string, default 'spencer'
-        The method by which the ET radiation should be calculated.
-        Options include ``'pyephem', 'spencer', 'asce', 'nrel'``.
+    method : string, default `spencer`
+        The method by which the extraterrestrial radiation should be
+        calculated. Options include: `pyephem`, `spencer` [3]_, `asce` [4]_,
+        'nrel' [6]_.
 
     epoch_year : int, default 2014
         The year in which a day of year input will be calculated. Only
-        applies to day of year input used with the pyephem or nrel
+        applies to day of year input used with the `pyephem` or `nrel`
         methods.
 
     kwargs :
-        Passed to solarposition.nrel_earthsun_distance
+        Passed to :py:func:`~pvlib.solarposition.nrel_earthsun_distance`.
 
     Returns
     -------
@@ -68,19 +73,23 @@ def get_extra_radiation(datetime_or_doy, solar_constant=1366.1,
     .. [1] M. Reno, C. Hansen, and J. Stein, "Global Horizontal Irradiance
        Clear Sky Models: Implementation and Analysis", Sandia National
        Laboratories, SAND2012-2389, 2012.
+       :doi:`10.2172/1039404`
 
-    .. [2] http://solardata.uoregon.edu/SolarRadiationBasics.html, Eqs.
-       SR1 and SR2
+    .. [2] J. A. Duffie, W. A. Beckman, N. Blair, "Solar Radiation", in Solar
+       Engineering of Thermal Processes, Photovoltaics and Wind, 5th ed,
+       New York, USA: J. Wiley and Sons, 2020, pp. 3-44.
+       :doi:`10.1002/9781119540328`
 
-    .. [3] Partridge, G. W. and Platt, C. M. R. 1976. Radiative Processes
-       in Meteorology and Climatology.
+    .. [3] J. W. Spencer, "Fourier series representation of the sun," Search,
+       vol. 2, p. 172, 1971.
 
-    .. [4] Duffie, J. A. and Beckman, W. A. 1991. Solar Engineering of
-       Thermal Processes, 2nd edn. J. Wiley and Sons, New York.
+    .. [4] R. G. Allen et al., Eds. The ASCE standardized reference
+       evapotranspiration equation. Reston, Va.: American Society of Civil
+       Engineers, 2005. :doi:`10.1061/9780784408056`
 
-    .. [5] ASCE, 2005. The ASCE Standardized Reference Evapotranspiration
-       Equation, Environmental and Water Resources Institute of the American
-       Civil Engineers, Ed. R. G. Allen et al.
+    .. [6] I. Reda, A. Andreas, "Solar position algorithm for solar
+       radiation applications" NREL Golden, USA. NREL/TP-560-34302,
+       Revised 2008. :doi:`10.2172/15003974`
     """
 
     to_doy, to_datetimeindex, to_output = \
@@ -1618,7 +1627,7 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
     since='0.11.2',
     old_param_name='clearsky_ghi',
     new_param_name='ghi_clear',
-    removal="0.13.0")
+    removal="0.14.0")
 def clearsky_index(ghi, ghi_clear, max_clearsky_index=2.0):
     """
     Calculate the clearsky index.
@@ -2163,12 +2172,12 @@ def _dirint_bins(times, kt_prime, zenith, w, delta_kt_prime):
     since='0.11.2',
     old_param_name='ghi_clearsky',
     new_param_name='ghi_clear',
-    removal="0.13.0")
+    removal="0.14.0")
 @renamed_kwarg_warning(
     since='0.11.2',
     old_param_name='dni_clearsky',
     new_param_name='dni_clear',
-    removal="0.13.0")
+    removal="0.14.0")
 def dirindex(ghi, ghi_clear, dni_clear, zenith, times, pressure=101325.,
              use_delta_kt_prime=True, temp_dew=None, min_cos_zenith=0.065,
              max_zenith=87):
@@ -3653,7 +3662,7 @@ def _get_dirint_coeffs():
     since='0.11.2',
     old_param_name='clearsky_dni',
     new_param_name='dni_clear',
-    removal="0.13.0")
+    removal="0.14.0")
 def dni(ghi, dhi, zenith, dni_clear=None, clearsky_tolerance=1.1,
         zenith_threshold_for_zero_dni=88.0,
         zenith_threshold_for_clearsky_limit=80.0):

pvlib/ivtools/sdm/__init__.py

@@ -0,0 +1,20 @@
+"""
+The ``sdm`` package contains functions to fit single diode models.
+Function names should follow the pattern "fit_" + name of model + "_" +
+ fitting method.
+"""
+
+from pvlib.ivtools.sdm.cec import (  # noqa: F401
+    fit_cec_sam,
+)
+
+from pvlib.ivtools.sdm.desoto import (  # noqa: F401
+    fit_desoto,
+    fit_desoto_sandia
+)
+
+from pvlib.ivtools.sdm.pvsyst import (  # noqa: F401
+    fit_pvsyst_sandia,
+    fit_pvsyst_iec61853_sandia_2025,
+    pvsyst_temperature_coeff,
+)