pvlib 0.10.3__py3-none-any.whl → 0.10.5__py3-none-any.whl

pvlib/irradiance.py

@@ -73,7 +73,7 @@ def get_extra_radiation(datetime_or_doy, solar_constant=1366.1,
        Clear Sky Models: Implementation and Analysis", Sandia National
        Laboratories, SAND2012-2389, 2012.
 
-    .. [2] <http://solardat.uoregon.edu/SolarRadiationBasics.html>, Eqs.
+    .. [2] http://solardata.uoregon.edu/SolarRadiationBasics.html, Eqs.
        SR1 and SR2
 
     .. [3] Partridge, G. W. and Platt, C. M. R. 1976. Radiative Processes
@@ -551,13 +551,16 @@ def poa_components(aoi, dni, poa_sky_diffuse, poa_ground_diffuse):
 
 
 def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None):
-    '''
-    Estimate diffuse irradiance from ground reflections given
-    irradiance, albedo, and surface tilt.
+    r'''
+    Estimate diffuse irradiance on a tilted surface from ground reflections.
+
+    Ground diffuse irradiance is calculated as
+
+    .. math::
+
+       G_{ground} = GHI \times \rho \times \frac{1 - \cos\beta}{2}
 
-    Function to determine the portion of irradiance on a tilted surface
-    due to ground reflections. Any of the inputs may be DataFrames or
-    scalars.
+    where :math:`\rho` is ``albedo`` and :math:`\beta` is ``surface_tilt``.
 
     Parameters
     ----------
@@ -567,13 +570,13 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None):
         (e.g. surface facing up = 0, surface facing horizon = 90).
 
     ghi : numeric
-        Global horizontal irradiance. [W/m^2]
+        Global horizontal irradiance. :math:`W/m^2`
 
     albedo : numeric, default 0.25
         Ground reflectance, typically 0.1-0.4 for surfaces on Earth
         (land), may increase over snow, ice, etc. May also be known as
         the reflection coefficient. Must be >=0 and <=1. Will be
-        overridden if surface_type is supplied.
+        overridden if ``surface_type`` is supplied.
 
     surface_type : string, optional
         If supplied, overrides ``albedo``. ``surface_type`` can be one of
@@ -584,23 +587,23 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None):
     Returns
     -------
     grounddiffuse : numeric
-        Ground reflected irradiance. [W/m^2]
+        Ground reflected irradiance. :math:`W/m^2`
 
+    Notes
+    -----
+    Table of albedo values by ``surface_type`` are from [2]_, [3]_, [4]_;
+    see :py:data:`~pvlib.irradiance.SURFACE_ALBEDOS`.
 
     References
     ----------
     .. [1] Loutzenhiser P.G. et. al. "Empirical validation of models to compute
        solar irradiance on inclined surfaces for building energy simulation"
        2007, Solar Energy vol. 81. pp. 254-267.
-
-    The calculation is the last term of equations 3, 4, 7, 8, 10, 11, and 12.
-
-    .. [2] albedos from:
-       http://files.pvsyst.com/help/albedo.htm
-       and
-       http://en.wikipedia.org/wiki/Albedo
-       and
-       https://doi.org/10.1175/1520-0469(1972)029<0959:AOTSS>2.0.CO;2
+    .. [2] https://www.pvsyst.com/help/albedo.htm Accessed January, 2024.
+    .. [3] http://en.wikipedia.org/wiki/Albedo Accessed January, 2024.
+    .. [4] Payne, R. E. "Albedo of the Sea Surface". J. Atmos. Sci., 29,
+       pp. 959–970, 1972.
+       :doi:`10.1175/1520-0469(1972)029<0959:AOTSS>2.0.CO;2`
     '''
 
     if surface_type is not None:
@@ -1555,8 +1558,8 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
     albedo : numeric, default 0.25
         Ground surface albedo. [unitless]
     xtol : numeric, default 0.01
-        Convergence criterion.  The estimated GHI will be within xtol of the
-        true value. [W/m^2]
+        Convergence criterion. The estimated GHI will be within xtol of the
+        true value. Must be positive. [W/m^2]
     full_output : boolean, default False
         If full_output is False, only ghi is returned, otherwise the return
         value is (ghi, converged, niter). (see Returns section for details).
@@ -1591,13 +1594,16 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
     '''
     # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Nov., 2023
 
+    if xtol <= 0:
+        raise ValueError(f"xtol too small ({xtol:g} <= 0)")
+
     ghi_from_poa_array = np.vectorize(_ghi_from_poa)
 
     ghi, conv, niter = ghi_from_poa_array(surface_tilt, surface_azimuth,
                                           solar_zenith, solar_azimuth,
                                           poa_global,
                                           dni_extra, airmass, albedo,
-                                          xtol=0.01)
+                                          xtol=xtol)
 
     if isinstance(poa_global, pd.Series):
         ghi = pd.Series(ghi, poa_global.index)

pvlib/location.py

@@ -439,8 +439,10 @@ def lookup_altitude(latitude, longitude):
     # 255 is a special value that means nodata. Fallback to 0 if nodata.
     if alt == 255:
         return 0
+    # convert from np.uint8 to float so that the following operations succeed
+    alt = float(alt)
     # Altitude is encoded in 28 meter steps from -450 meters to 6561 meters
     # There are 0-254 possible altitudes, with 255 reserved for nodata.
     alt *= 28
     alt -= 450
-    return float(alt)
+    return alt

pvlib/modelchain.py

@@ -1117,10 +1117,7 @@ class ModelChain:
         temperature_model_parameters = tuple(
             array.temperature_model_parameters for array in self.system.arrays)
         params = _common_keys(temperature_model_parameters)
-        # remove or statement in v0.9
-        if {'a', 'b', 'deltaT'} <= params or (
-                not params and self.system.racking_model is None
-                and self.system.module_type is None):
+        if {'a', 'b', 'deltaT'} <= params:
             return self.sapm_temp
         elif {'u_c', 'u_v'} <= params:
             return self.pvsyst_temp
@@ -1131,11 +1128,15 @@ class ModelChain:
         elif {'noct', 'module_efficiency'} <= params:
             return self.noct_sam_temp
         else:
-            raise ValueError(f'could not infer temperature model from '
-                             f'system.temperature_model_parameters. Check '
-                             f'that all Arrays in system.arrays have '
-                             f'parameters for the same temperature model. '
-                             f'Common temperature model parameters: {params}.')
+            raise ValueError('Could not infer temperature model from '
+                             'ModelChain.system.  '
+                             'If Arrays are used to construct the PVSystem, '
+                             'check that all Arrays in '
+                             'ModelChain.system.arrays '
+                             'have parameters for the same temperature model. '
+                             'If Arrays are not used, check that the PVSystem '
+                             'attributes `racking_model` and `module_type` '
+                             'are valid.')
 
     def _set_celltemp(self, model):
         """Set self.results.cell_temperature using the given cell

pvlib/pvarray.py

@@ -223,3 +223,130 @@ def fit_pvefficiency_adr(effective_irradiance, temp_cell, eta,
         return dict(zip(P_NAMES, popt))
     else:
         return popt
+
+
+def _infer_k_huld(cell_type, pdc0):
+    # from PVGIS documentation, "PVGIS data sources & calculation methods",
+    # Section 5.2.3, accessed 12/22/2023
+    # The parameters in PVGIS' documentation are for a version of Huld's
+    # equation that has factored Pdc0 out of the polynomial:
+    #  P = G/1000 * Pdc0 * (1 + k1 log(Geff) + ...) so these parameters are
+    # multiplied by pdc0
+    huld_params = {'csi': (-0.017237, -0.040465, -0.004702, 0.000149,
+                           0.000170, 0.000005),
+                   'cis': (-0.005554, -0.038724, -0.003723, -0.000905,
+                           -0.001256, 0.000001),
+                   'cdte': (-0.046689, -0.072844, -0.002262, 0.000276,
+                            0.000159, -0.000006)}
+    k = tuple([x*pdc0 for x in huld_params[cell_type.lower()]])
+    return k
+
+
+def huld(effective_irradiance, temp_mod, pdc0, k=None, cell_type=None):
+    r"""
+    Power (DC) using the Huld model.
+
+    The Huld model [1]_ is used by PVGIS and is given by
+
+
+    .. math::
+
+        P_{dc} &= G' ( P_{dc0} + k_1 \log(G') + k_2 \log^2 (G') + k_3 T' +
+                 k_4 T' \log(G') + k_5 T' \log^2 (G') + k_6 T'^2)
+
+        G' &= \frac{G_{poa eff}}{1000}
+
+        T' &= T_{mod} - 25^{\circ}C
+
+
+    Parameters
+    ----------
+    effective_irradiance : numeric
+        The irradiance that is converted to photocurrent. [:math:`W/m^2`]
+    temp_mod: numeric
+        Module back-surface temperature. [C]
+    pdc0: numeric
+        Power of the modules at reference conditions 1000 :math:`W/m^2`
+        and :math:`25^{\circ}C`. [W]
+    k : tuple, optional
+        Empirical coefficients used in the power model. Length 6. If ``k`` is
+        not provided, ``cell_type`` must be specified.
+    cell_type : str, optional
+        If provided, must be one of ``'cSi'``, ``'CIS'``, or ``'CdTe'``.
+        Used to look up default values for ``k`` if ``k`` is not specified.
+
+    Returns
+    -------
+    pdc: numeric
+        DC power. [W]
+
+    Raises
+    ------
+    ValueError
+        If neither ``k`` nor ``cell_type`` are specified.
+
+    Notes
+    -----
+    The equation for :math:`P_{dc}` is from [1]_. The expression used in PVGIS
+    documentation differs by factoring :math:`P_{dc0}` out of the
+    polynomial:
+
+    .. math::
+
+        P_{dc} = G' P_{dc0} (1 + k'_1 \log(G') + k'_2 \log^2 (G') + k'_3 T' +
+                 k'_4 T' \log(G') + k'_5 T' \log^2 (G') + k'_6 T'^2)
+
+
+    PVGIS documentation shows a table of default parameters :math:`k'` for
+    different cell types. The parameters :math:`k'` differ from the parameters
+    :math:`k` for :py:func:`huld` by the factor ``pdc0``, that is,
+
+    .. math::
+
+        k = P_{dc0} k'
+
+    With default values for :math:`k`, at very low irradiance, i.e.,
+    :math:`G' < 20 W/m^2`, :math:`P_{dc}` may be negative
+    due to the terms involving :math:`\log(G')`.
+
+    :py:func:`huld` is a component of the PV performance model implemented in
+    PVGIS. Among other components, the full PVGIS model includes:
+
+    - the Faiman model for module temperature
+      :py:func:`pvlib.temperature.faiman`
+    - the Martin and Ruiz model for the incidence angle modifier (IAM)
+      :py:func:`pvlib.iam.martin_ruiz`
+    - a custom model for a spectral adjustment factor
+
+    The PVGIS API (see :py:func:`pvlib.iotools.get_pvgis_hourly`) returns
+    broadband plane-of-array irradiance (``poa_global``) and DC power (``P``).
+    ``poa_global`` is irradiance before applying the IAM and spectral
+    adjustments. In contrast the ``effective_irradiance`` for :py:func:`huld`
+    should have the IAM and spectral adjustments. Users comparing output of
+    :py:func:`huld` to PVGIS' ``P`` values should expect differences unless
+    ``effective_irradiance`` is computed in the same way as done by PVGIS.
+
+    References
+    ----------
+    .. [1] T. Huld, G. Friesen, A. Skoczek, R. Kenny, T. Sample, M. Field,
+           E. Dunlop. A power-rating model for crystalline silicon PV modules.
+           Solar Energy Materials and Solar Cells 95, (2011), pp. 3359-3369.
+           :doi:`10.1016/j.solmat.2011.07.026`.
+    """
+    if k is None:
+        if cell_type is not None:
+            k = _infer_k_huld(cell_type, pdc0)
+        else:
+            raise ValueError('Either k or cell_type must be specified')
+
+    gprime = effective_irradiance / 1000
+    tprime = temp_mod - 25
+    # accomodate gprime<=0
+    with np.errstate(divide='ignore'):
+        logGprime = np.log(gprime, out=np.zeros_like(gprime),
+                           where=np.array(gprime > 0))
+    # Eq. 1 in [1]
+    pdc = gprime * (pdc0 + k[0] * logGprime + k[1] * logGprime**2 +
+                    k[2] * tprime + k[3] * tprime * logGprime +
+                    k[4] * tprime * logGprime**2 + k[5] * tprime**2)
+    return pdc

pvlib/pvsystem.py

@@ -7,7 +7,7 @@ from collections import OrderedDict
 import functools
 import io
 import itertools
-import os
+from pathlib import Path
 import inspect
 from urllib.request import urlopen
 import numpy as np
@@ -1487,8 +1487,10 @@ def calcparams_desoto(effective_irradiance, temp_cell,
     '''
     Calculates five parameter values for the single diode equation at
     effective irradiance and cell temperature using the De Soto et al.
-    model described in [1]_. The five values returned by calcparams_desoto
-    can be used by singlediode to calculate an IV curve.
+    model. The five values returned by ``calcparams_desoto`` can be used by
+    singlediode to calculate an IV curve.
+
+    The model is described in [1]_.
 
     Parameters
     ----------
@@ -1958,9 +1960,9 @@ def calcparams_pvsyst(effective_irradiance, temp_cell,
 
 
 def retrieve_sam(name=None, path=None):
-    '''
-    Retrieve latest module and inverter info from a local file or the
-    SAM website.
+    """
+    Retrieve latest module and inverter info from a file bundled with pvlib,
+    a path or an URL (like SAM's website).
 
     This function will retrieve either:
 
@@ -1971,10 +1973,14 @@ def retrieve_sam(name=None, path=None):
 
     and return it as a pandas DataFrame.
 
+    .. note::
+        Only provide one of ``name`` or ``path``.
+
     Parameters
     ----------
     name : string, optional
-        Name can be one of:
+        Use one of the following strings to retrieve a database bundled with
+        pvlib:
 
         * 'CECMod' - returns the CEC module database
         * 'CECInverter' - returns the CEC Inverter database
@@ -1985,7 +1991,7 @@ def retrieve_sam(name=None, path=None):
         * 'ADRInverter' - returns the ADR Inverter database
 
     path : string, optional
-        Path to the SAM file. May also be a URL.
+        Path to a CSV file or a URL.
 
     Returns
     -------
@@ -1997,7 +2003,11 @@ def retrieve_sam(name=None, path=None):
     Raises
     ------
     ValueError
-        If no name or path is provided.
+        If no ``name`` or ``path`` is provided.
+    ValueError
+        If both ``name`` and ``path`` are provided.
+    KeyError
+        If the provided ``name`` is not a valid database name.
 
     Notes
     -----
@@ -2030,38 +2040,38 @@ def retrieve_sam(name=None, path=None):
     CEC_Date                     NaN
     CEC_Type     Utility Interactive
     Name: AE_Solar_Energy__AE6_0__277V_, dtype: object
-    '''
-
-    if name is not None:
-        name = name.lower()
-        data_path = os.path.join(
-            os.path.dirname(os.path.abspath(__file__)), 'data')
-        if name == 'cecmod':
-            csvdata = os.path.join(
-                data_path, 'sam-library-cec-modules-2019-03-05.csv')
-        elif name == 'sandiamod':
-            csvdata = os.path.join(
-                data_path, 'sam-library-sandia-modules-2015-6-30.csv')
-        elif name == 'adrinverter':
-            csvdata = os.path.join(
-                data_path, 'adr-library-cec-inverters-2019-03-05.csv')
-        elif name in ['cecinverter', 'sandiainverter']:
-            # Allowing either, to provide for old code,
-            # while aligning with current expectations
-            csvdata = os.path.join(
-                data_path, 'sam-library-cec-inverters-2019-03-05.csv')
-        else:
-            raise ValueError(f'invalid name {name}')
-    elif path is not None:
-        if path.startswith('http'):
-            response = urlopen(path)
-            csvdata = io.StringIO(response.read().decode(errors='ignore'))
-        else:
-            csvdata = path
+    """
+    # error: path was previously silently ignored if name was given GH#2018
+    if name is not None and path is not None:
+        raise ValueError("Please provide either 'name' or 'path', not both.")
     elif name is None and path is None:
-        raise ValueError("A name or path must be provided!")
-
-    return _parse_raw_sam_df(csvdata)
+        raise ValueError("Please provide either 'name' or 'path'.")
+    elif name is not None:
+        internal_dbs = {
+            "cecmod": "sam-library-cec-modules-2019-03-05.csv",
+            "sandiamod": "sam-library-sandia-modules-2015-6-30.csv",
+            "adrinverter": "adr-library-cec-inverters-2019-03-05.csv",
+            # Both 'cecinverter' and 'sandiainverter', point to same database
+            # to provide for old code, while aligning with current expectations
+            "cecinverter": "sam-library-cec-inverters-2019-03-05.csv",
+            "sandiainverter": "sam-library-cec-inverters-2019-03-05.csv",
+        }
+        try:
+            csvdata_path = Path(__file__).parent.joinpath(
+                "data", internal_dbs[name.lower()]
+            )
+        except KeyError:
+            raise KeyError(
+                f"Invalid name {name}. "
+                + f"Provide one of {list(internal_dbs.keys())}."
+            ) from None
+    else:  # path is not None
+        if path.lower().startswith("http"):  # URL check is not case-sensitive
+            response = urlopen(path)  # URL is case-sensitive
+            csvdata_path = io.StringIO(response.read().decode(errors="ignore"))
+        else:
+            csvdata_path = path
+    return _parse_raw_sam_df(csvdata_path)
 
 
 def _normalize_sam_product_names(names):
@@ -2254,10 +2264,9 @@ def sapm(effective_irradiance, temp_cell, module):
         module['IXO'] * (module['C4']*Ee + module['C5']*(Ee**2)) *
         (1 + module['Aisc']*(temp_cell - temp_ref)))
 
-    # the Ixx calculation in King 2004 has a typo (mixes up Aisc and Aimp)
     out['i_xx'] = (
         module['IXXO'] * (module['C6']*Ee + module['C7']*(Ee**2)) *
-        (1 + module['Aisc']*(temp_cell - temp_ref)))
+        (1 + module['Aimp']*(temp_cell - temp_ref)))
 
     if isinstance(out['i_sc'], pd.Series):
         out = pd.DataFrame(out)
@@ -2536,7 +2545,7 @@ def singlediode(photocurrent, saturation_current, resistance_series,
 
 
 def max_power_point(photocurrent, saturation_current, resistance_series,
-                    resistance_shunt, nNsVth, d2mutau=0, NsVbi=np.Inf,
+                    resistance_shunt, nNsVth, d2mutau=0, NsVbi=np.inf,
                     method='brentq'):
     """
     Given the single diode equation coefficients, calculates the maximum power

pvlib/scaling.py

@@ -13,8 +13,10 @@ from scipy.spatial.distance import pdist
 def wvm(clearsky_index, positions, cloud_speed, dt=None):
     """
     Compute spatial aggregation time series smoothing on clear sky index based
-    on the Wavelet Variability model of Lave et al. [1]_, [2]_. Implementation
-    is basically a port of the Matlab version of the code [3]_.
+    on the Wavelet Variability model.
+
+    This model is described in Lave et al. [1]_, [2]_.
+    Implementation is basically a port of the Matlab version of the code [3]_.
 
     Parameters
     ----------

pvlib/shading.py

@@ -232,3 +232,113 @@ def sky_diffuse_passias(masking_angle):
        Available at https://www.nrel.gov/docs/fy18osti/67399.pdf
     """
     return 1 - cosd(masking_angle/2)**2
+
+
+def projected_solar_zenith_angle(solar_zenith, solar_azimuth,
+                                 axis_tilt, axis_azimuth):
+    r"""
+    Calculate projected solar zenith angle in degrees.
+
+    This solar zenith angle is projected onto the plane whose normal vector is
+    defined by ``axis_tilt`` and ``axis_azimuth``. The normal vector is in the
+    direction of ``axis_azimuth`` (clockwise from north) and tilted from
+    horizontal by ``axis_tilt``. See Figure 5 in [1]_:
+
+    .. figure:: ../../_images/Anderson_Mikofski_2020_Fig5.jpg
+       :alt: Wire diagram of coordinates systems to obtain the projected angle.
+       :align: center
+       :scale: 50 %
+
+       Fig. 5, [1]_: Solar coordinates projection onto tracker rotation plane.
+
+    Parameters
+    ----------
+    solar_zenith : numeric
+        Sun's apparent zenith in degrees.
+    solar_azimuth : numeric
+        Sun's azimuth in degrees.
+    axis_tilt : numeric
+        Axis tilt angle in degrees. From horizontal plane to array plane.
+    axis_azimuth : numeric
+        Axis azimuth angle in degrees.
+        North = 0°; East = 90°; South = 180°; West = 270°
+
+    Returns
+    -------
+    Projected_solar_zenith : numeric
+        In degrees.
+
+    Notes
+    -----
+    This projection has a variety of applications in PV. For example:
+
+    - Projecting the sun's position onto the plane perpendicular to
+      the axis of a single-axis tracker (i.e. the plane
+      whose normal vector coincides with the tracker torque tube)
+      yields the tracker rotation angle that maximizes direct irradiance
+      capture. This tracking strategy is called *true-tracking*. Learn more
+      about tracking in
+      :ref:`sphx_glr_gallery_solar-tracking_plot_single_axis_tracking.py`.
+
+    - Self-shading in large PV arrays is often modeled by assuming
+      a simplified 2-D array geometry where the sun's position is
+      projected onto the plane perpendicular to the PV rows.
+      The projected zenith angle is then used for calculations
+      regarding row-to-row shading.
+
+    Examples
+    --------
+    Calculate the ideal true-tracking angle for a horizontal north-south
+    single-axis tracker:
+
+    >>> rotation = projected_solar_zenith_angle(solar_zenith, solar_azimuth,
+    >>>                                         axis_tilt=0, axis_azimuth=180)
+
+    Calculate the projected zenith angle in a south-facing fixed tilt array
+    (note: the ``axis_azimuth`` of a fixed-tilt row points along the length
+    of the row):
+
+    >>> psza = projected_solar_zenith_angle(solar_zenith, solar_azimuth,
+    >>>                                     axis_tilt=0, axis_azimuth=90)
+
+    References
+    ----------
+    .. [1] K. Anderson and M. Mikofski, 'Slope-Aware Backtracking for
+       Single-Axis Trackers', National Renewable Energy Lab. (NREL), Golden,
+       CO (United States);
+       NREL/TP-5K00-76626, Jul. 2020. :doi:`10.2172/1660126`.
+
+    See Also
+    --------
+    pvlib.solarposition.get_solarposition
+    """
+    # Assume the tracker reference frame is right-handed. Positive y-axis is
+    # oriented along tracking axis; from north, the y-axis is rotated clockwise
+    # by the axis azimuth and tilted from horizontal by the axis tilt. The
+    # positive x-axis is 90 deg clockwise from the y-axis and parallel to
+    # horizontal (e.g., if the y-axis is south, the x-axis is west); the
+    # positive z-axis is normal to the x and y axes, pointed upward.
+
+    # Since elevation = 90 - zenith, sin(90-x) = cos(x) & cos(90-x) = sin(x):
+    # Notation from [1], modified to use zenith instead of elevation
+    # cos(elevation) = sin(zenith) and sin(elevation) = cos(zenith)
+    # Avoid recalculating these values
+    sind_solar_zenith = sind(solar_zenith)
+    cosd_axis_azimuth = cosd(axis_azimuth)
+    sind_axis_azimuth = sind(axis_azimuth)
+    sind_axis_tilt = sind(axis_tilt)
+
+    # Sun's x, y, z coords
+    sx = sind_solar_zenith * sind(solar_azimuth)
+    sy = sind_solar_zenith * cosd(solar_azimuth)
+    sz = cosd(solar_zenith)
+    # Eq. (4); sx', sz' values from sun coordinates projected onto surface
+    sx_prime = sx * cosd_axis_azimuth - sy * sind_axis_azimuth
+    sz_prime = (
+        sx * sind_axis_azimuth * sind_axis_tilt
+        + sy * sind_axis_tilt * cosd_axis_azimuth
+        + sz * cosd(axis_tilt)
+    )
+    # Eq. (5); angle between sun's beam and surface
+    theta_T = np.degrees(np.arctan2(sx_prime, sz_prime))
+    return theta_T