Merge branch 'main' into no_more_parse

Author: kandersolar

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

@@ -17,21 +17,30 @@ Enhancements
 * :py:mod:`pvlib.ivtools.sdm` is now a subpackage. (:issue:`2252`, :pull:`2256`)
 * Add a function for estimating PVsyst SDM parameters from IEC 61853-1 matrix
   data (:py:func:`~pvlib.ivtools.sdm.fit_pvsyst_iec61853_sandia_2025`). (:issue:`2185`, :pull:`2429`)
+* The parameters for the Ix and Ixx points are now optional when using
+  :py:func:`pvlib.pvsystem.sapm` directly and through
+  :py:class:`~pvlib.pvsystem.PVSystem` and :py:class:`~pvlib.modelchain.ModelChain`.
+  (:issue:`2402`, :pull:`2433`)
 * Add optional arguments ``temperature_ref`` and ``irradiance_ref`` to
   :py:func:`~pvlib.pvsystem.sapm`(:issue:`2432`, :pull:`2434`)
 * Add NREL NSRDB PSM v4 API client to :py:mod:`pvlib.iotools`. See
   :py:func:`~pvlib.iotools.get_nsrdb_psm4_aggregated`,
   :py:func:`~pvlib.iotools.get_nsrdb_psm4_tmy`,
   :py:func:`~pvlib.iotools.get_nsrdb_psm4_conus`,
   :py:func:`~pvlib.iotools.get_nsrdb_psm4_full_disc`, and
-  :py:func:`~pvlib.iotools.read_nsrdb_psm4`. (:issue:`2326`, :pull:`2378`,
-  :pull:`2445`)
+  :py:func:`~pvlib.iotools.read_nsrdb_psm4`. (:issue:`2326`, :pull:`2378`, :pull:`2445`)
+* :py:mod:`pvlib.bifacial.infinite_sheds` no longer emits "invalid value" warnings
+  when supplying irradiance arrays with nighttime zero values. (:issue:`2450`, :pull:`2451`)
 
 Documentation
 ~~~~~~~~~~~~~
 * Add a supporting reference to :py:func:`pvlib.atmosphere.get_relative_airmass` (:issue:`2390`, :pull:`2424`)
-* Documented how `np.nan` values are handled by :py:func:`~pvlib.spectrum.average_photon_energy`
+* Document how ``np.nan`` values are handled by :py:func:`~pvlib.spectrum.average_photon_energy`
   (:issue:`2423`, :pull:`2426`)
+* Clarify which SAPM coefficients are required by the ``module`` parameter in
+  :py:func:`~pvlib.pvsystem.sapm` (:issue:`2392`, :pull:`2435`)
+* Update references in :py:func`~pvlib.irradiance.get_extra_radiation`
+  (:issue:`2333`, :pull:`2347`)
 
 Requirements
 ~~~~~~~~~~~~

pvlib/bifacial/infinite_sheds.py

@@ -9,21 +9,23 @@
 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/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 = \

pvlib/modelchain.py

@@ -611,7 +611,7 @@ def infer_dc_model(self):
         """Infer DC power model from Array module parameters."""
         params = _common_keys(
             tuple(array.module_parameters for array in self.system.arrays))
-        if {'A0', 'A1', 'C7'} <= params:
+        if {'A0', 'A1', 'C3'} <= params:
             return self.sapm, 'sapm'
         elif {'a_ref', 'I_L_ref', 'I_o_ref', 'R_sh_ref', 'R_s',
               'Adjust'} <= params:

pvlib/pvsystem.py

@@ -27,10 +27,10 @@
 # a dict of required parameter names for each DC power model
 _DC_MODEL_PARAMS = {
     'sapm': {
-        'C0', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'C7',
+        # i_x and i_xx params (IXO, IXXO, C4-C7) not required
+        'C0', 'C1', 'C2', 'C3',
         'Isco', 'Impo', 'Voco', 'Vmpo', 'Aisc', 'Aimp', 'Bvoco',
-        'Mbvoc', 'Bvmpo', 'Mbvmp', 'N', 'Cells_in_Series',
-        'IXO', 'IXXO'},
+        'Mbvoc', 'Bvmpo', 'Mbvmp', 'N', 'Cells_in_Series'},
     'desoto': {
         'alpha_sc', 'a_ref', 'I_L_ref', 'I_o_ref',
         'R_sh_ref', 'R_s'},
@@ -2229,18 +2229,33 @@ def sapm(effective_irradiance, temp_cell, module, *, temperature_ref=25,
         * v_mp : Voltage at maximum-power point (V)
         * p_mp : Power at maximum-power point (W)
         * i_x : Current at module V = 0.5Voc, defines 4th point on I-V
-          curve for modeling curve shape
+          curve for modeling curve shape.  Omitted if ``IXO``, ``C4``, and
+          ``C5`` parameters are not supplied.
         * i_xx : Current at module V = 0.5(Voc+Vmp), defines 5th point on
-          I-V curve for modeling curve shape
+          I-V curve for modeling curve shape.  Omitted if ``IXXO``, ``C6``,
+          and ``C7`` parameters are not supplied.
 
     Notes
     -----
-    The SAPM parameters which are required in ``module`` are
-    listed in the following table.
-
     The Sandia module database contains parameter values for a limited set
     of modules. The CEC module database does not contain these parameters.
-    Both databases can be accessed using :py:func:`retrieve_sam`.
+    Both databases can be accessed using :py:func:`retrieve_sam`. The full list
+    of SAPM parameters is presented in the table below. Those that are required
+    in the ``module`` parameter to run this model are as follows:
+
+    * ``C0``, ``C1``, ``C2``, ``C3``
+    * ``Isco``
+    * ``Impo``
+    * ``Voco``
+    * ``Vmpo``
+    * ``Aisc``
+    * ``Aimp``
+    * ``Bvoco``
+    * ``Mbvoc``
+    * ``Bvmpo``
+    * ``Mbvmp``
+    * ``N``
+    * ``Cells_in_series``
 
     ================   ========================================================
     Key                Description
@@ -2335,13 +2350,15 @@ def sapm(effective_irradiance, temp_cell, module, *, temperature_ref=25,
 
     out['p_mp'] = out['i_mp'] * out['v_mp']
 
-    out['i_x'] = (
-        module['IXO'] * (module['C4']*Ee + module['C5']*(Ee**2)) *
-        (1 + module['Aisc']*(temp_cell - temperature_ref)))
+    if 'IXO' in module and 'C4' in module and 'C5' in module:
+        out['i_x'] = (
+            module['IXO'] * (module['C4']*Ee + module['C5']*(Ee**2)) *
+            (1 + module['Aisc']*(temp_cell - temperature_ref)))
 
-    out['i_xx'] = (
-        module['IXXO'] * (module['C6']*Ee + module['C7']*(Ee**2)) *
-        (1 + module['Aimp']*(temp_cell - temperature_ref)))
+    if 'IXXO' in module and 'C6' in module and 'C7' in module:
+        out['i_xx'] = (
+            module['IXXO'] * (module['C6']*Ee + module['C7']*(Ee**2)) *
+            (1 + module['Aimp']*(temp_cell - temperature_ref)))
 
     if isinstance(out['i_sc'], pd.Series):
         out = pd.DataFrame(out)

tests/bifacial/test_infinite_sheds.py

@@ -42,19 +42,20 @@ def test_system():
 
 
 def test__poa_ground_shadows():
-    poa_ground, f_gnd_beam, df, vf_gnd_sky = (300., 0.5, 0.5, 0.2)
-    result = infinite_sheds._poa_ground_shadows(
-        poa_ground, f_gnd_beam, df, vf_gnd_sky)
-    expected = 300. * (0.5 * 0.5 + 0.5 * 0.2)
+    ghi, dhi, albedo, f_gnd_beam, vf_gnd_sky = (300., 100, 0.3, 0.5, 0.2)
+    result = infinite_sheds._poa_ground_shadows(ghi, dhi, albedo, f_gnd_beam,
+                                                vf_gnd_sky)
+
+    expected = 0.3 * (200 * 0.5 + 100 * 0.2)
     assert np.isclose(result, expected)
     # vector inputs
-    poa_ground = np.array([300., 300.])
-    f_gnd_beam = np.array([0.5, 0.5])
-    df = np.array([0.5, 0.])
-    vf_gnd_sky = np.array([0.2, 0.2])
-    result = infinite_sheds._poa_ground_shadows(
-        poa_ground, f_gnd_beam, df, vf_gnd_sky)
-    expected_vec = np.array([expected, 300. * 0.5])
+    ghi = np.array([ghi, ghi])
+    dhi = np.array([dhi, 0])
+    f_gnd_beam = np.array([f_gnd_beam, f_gnd_beam])
+    vf_gnd_sky = np.array([vf_gnd_sky, vf_gnd_sky])
+    result = infinite_sheds._poa_ground_shadows(ghi, dhi, albedo, f_gnd_beam,
+                                                vf_gnd_sky)
+    expected_vec = np.array([expected, 300. * 0.5 * 0.3])
     assert np.allclose(result, expected_vec)
 
 

tests/test_modelchain.py

@@ -1762,6 +1762,16 @@ def test_invalid_dc_model_params(sapm_dc_snl_ac_system, cec_dc_snl_ac_system,
         ModelChain(pvwatts_dc_pvwatts_ac_system, location, **kwargs)
 
 
+def test_sapm_optional_params(sapm_dc_snl_ac_system, location):
+    # inference works when the optional (i_x, i_xx) SAPM parameters are missing
+    for array in sapm_dc_snl_ac_system.arrays:
+        for key in ['IXO', 'IXXO', 'C4', 'C5', 'C6', 'C7']:
+            array.module_parameters.pop(key)
+
+    # no error:
+    ModelChain(sapm_dc_snl_ac_system, location)
+
+
 @pytest.mark.parametrize('model', [
     'dc_model', 'ac_model', 'aoi_model', 'spectral_model',
     'temperature_model', 'losses_model'

tests/test_pvsystem.py

@@ -17,7 +17,6 @@
 from pvlib.location import Location
 from pvlib.pvsystem import FixedMount
 from pvlib import temperature
-from pvlib._deprecation import pvlibDeprecationWarning
 from pvlib.tools import cosd
 from pvlib.singlediode import VOLTAGE_BUILTIN
 
@@ -197,6 +196,15 @@ def test_sapm(sapm_module_params):
     pvsystem.sapm(effective_irradiance, temp_cell,
                   pd.Series(sapm_module_params))
 
+    # ensure C4-C7 are optional
+    optional_keys = ['IXO', 'IXXO', 'C4', 'C5', 'C6', 'C7']
+    params_no_c4c7 = {
+        k: v for k, v in sapm_module_params.items() if k not in optional_keys
+    }
+    out = pvsystem.sapm(effective_irradiance, temp_cell, params_no_c4c7)
+    assert 'i_x' not in out.keys()
+    assert 'i_xx' not in out.keys()
+
 
 def test_PVSystem_sapm(sapm_module_params, mocker):
     mocker.spy(pvsystem, 'sapm')