Add support for diffuse IAM in the Array and PVSystem classes

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

@@ -30,6 +30,10 @@ Breaking Changes
 * Removed the deprecated ``server`` keyword argument from
   :py:func:`pvlib.iotools.sodapro.get_cams`. Use ``url`` instead.
   (:issue:`2767`, :pull:`2766`)
+* Changed the output type of :py:func:`pvlib.iam.marion_ruiz_diffuse`
+  and :py:func:`pvlib.iam.schlick_diffuse` from tuple to ``dict``, to be
+  consistent with :py:func:`pvlib.iam.marion_diffuse`. (:issue:`2837`,
+  :pull:`2842`)
 
 Deprecations
 ~~~~~~~~~~~~
@@ -66,6 +70,9 @@ Enhancements
   (:issue:`2828`, :pull:`2832`)
 * Allow variables from multiple datasets to be requested at once in
   :py:func:`~pvlib.iotools.get_merra2`. (:pull:`2839`)
+* Add support for diffuse IAM in the :py:class:`pvlib.pvsystem.Array` and
+  :py:class:`pvlib.pvsystem.PVSystem` classes (see `pvlib.pvsystem.Array.get_iam_diffuse`
+  and `pvlib.pvsystem.PVSystem.get_iam_diffuse`). (:issue:`2812`, :pull:`2845`)
 
 
 Documentation

pvlib/iam.py

@@ -316,9 +316,12 @@ def martin_ruiz(aoi, a_r=0.16):
 
 def martin_ruiz_diffuse(surface_tilt, a_r=0.16, c1=0.4244, c2=None):
     '''
-    Determine the incidence angle modifiers (iam) for diffuse sky and
+    Determine the incidence angle modifiers (IAM) for sky diffuse and
     ground-reflected irradiance using the Martin and Ruiz incident angle model.
 
+    As described in [1]_, the IAMs result from integrals that assume the
+    incoming sky diffuse and ground-reflected irradiance are isotropic.
+
     Parameters
     ----------
     surface_tilt: float or array-like, default 0
@@ -346,11 +349,12 @@ def martin_ruiz_diffuse(surface_tilt, a_r=0.16, c1=0.4244, c2=None):
 
     Returns
     -------
-    iam_sky : numeric
-        The incident angle modifier for sky diffuse
+    iam : dict
+        Incident Angle Modifier (see :term:`iam`) values for each type of
+        diffuse irradiance:
 
-    iam_ground : numeric
-        The incident angle modifier for ground-reflected diffuse
+        * 'sky': radiation from the sky dome
+        * 'ground': radiation reflected from the ground
 
     Notes
     -----
@@ -419,7 +423,9 @@ def martin_ruiz_diffuse(surface_tilt, a_r=0.16, c1=0.4244, c2=None):
         iam_sky = pd.Series(iam_sky, index=out_index, name='iam_sky')
         iam_gnd = pd.Series(iam_gnd, index=out_index, name='iam_ground')
 
-    return iam_sky, iam_gnd
+    iam = {'sky': iam_sky, 'ground': iam_gnd}
+
+    return iam
 
 
 def interp(aoi, theta_ref, iam_ref, method='linear', normalize=True):
@@ -583,8 +589,8 @@ def sapm(aoi, module, upper=None):
 
 def marion_diffuse(model, surface_tilt, **kwargs):
     """
-    Determine diffuse irradiance incidence angle modifiers using Marion's
-    method of integrating over solid angle.
+    Determine diffuse irradiance incidence angle modifiers (IAM) using
+    Marion's method of integrating over solid angle.
 
     Parameters
     ----------
@@ -603,7 +609,8 @@ def marion_diffuse(model, surface_tilt, **kwargs):
     Returns
     -------
     iam : dict
-        IAM values for each type of diffuse irradiance:
+        Incident Angle Modifier (see :term:`iam`) values for each type of
+        diffuse irradiance:
 
         * 'sky': radiation from the sky dome (zenith <= 90)
         * 'horizon': radiation from the region of the sky near the horizon
@@ -859,7 +866,7 @@ def schlick(aoi):
 
 def schlick_diffuse(surface_tilt):
     r"""
-    Determine the incidence angle modifiers (IAM) for diffuse sky and
+    Determine the incidence angle modifiers (IAM) for sky diffuse and
     ground-reflected irradiance on a tilted surface using the Schlick
     incident angle model.
 
@@ -890,11 +897,12 @@ def schlick_diffuse(surface_tilt):
 
     Returns
     -------
-    iam_sky : numeric
-        The incident angle modifier for sky diffuse.
+    iam : dict
+        Incident Angle Modifier (see :term:`iam`) values for each type of
+        diffuse irradiance:
 
-    iam_ground : numeric
-        The incident angle modifier for ground-reflected diffuse.
+        * 'sky': radiation from the sky dome
+        * 'ground': radiation reflected from the ground
 
     See Also
     --------
@@ -961,7 +969,9 @@ def schlick_diffuse(surface_tilt):
         cuk = pd.Series(cuk, surface_tilt.index)
         cug = pd.Series(cug, surface_tilt.index)
 
-    return cuk, cug
+    iam = {'sky': cuk, 'ground': cug}
+
+    return iam
 
 
 def _get_model(model_name):

pvlib/irradiance.py

@@ -697,6 +697,11 @@ def isotropic(surface_tilt, dhi, return_components=False):
             * poa_isotropic: The portion of sky diffuse irradiance on a tilted
               plane from the isotropic sky dome. [Wm⁻²]
 
+    diffuse_components : Dict (array input) or DataFrame (Series input)
+        Keys/columns are:
+            * poa_sky_diffuse: Total sky diffuse
+            * poa_isotropic
+
     References
     ----------
     .. [1] Loutzenhiser P.G. et al. "Empirical validation of models to

pvlib/pvsystem.py

@@ -307,7 +307,7 @@ def get_aoi(self, solar_zenith, solar_azimuth):
     @_unwrap_single_value
     def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi,
                        dni_extra=None, airmass=None, albedo=None,
-                       model='haydavies', **kwargs):
+                       model='haydavies', diffuse_components=False, **kwargs):
         """
         Uses :py:func:`pvlib.irradiance.get_total_irradiance` to
         calculate the plane of array irradiance components on the tilted
@@ -334,6 +334,11 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi,
             Ground surface albedo. [unitless]
         model : String, default 'haydavies'
             Irradiance model.
+        diffuse_components : bool, default False
+            If `True`, returns values for the different diffuse irradiance
+            components available from the selected model
+            (e.g., isotropic, circumsolar, horizon brightening).
+            If `False`, only the total diffuse irradiance is returned.
 
         kwargs
             Extra parameters passed to
@@ -373,7 +378,9 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi,
             array.get_irradiance(solar_zenith, solar_azimuth,
                                  dni, ghi, dhi,
                                  dni_extra=dni_extra, airmass=airmass,
-                                 albedo=albedo, model=model, **kwargs)
+                                 albedo=albedo, model=model,
+                                 diffuse_components=diffuse_components,
+                                 **kwargs)
             for array, dni, ghi, dhi, albedo in zip(
                 self.arrays, dni, ghi, dhi, albedo
             )
@@ -382,8 +389,8 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi,
     @_unwrap_single_value
     def get_iam(self, aoi, iam_model='physical'):
         """
-        Determine the incidence angle modifier using the method specified by
-        ``iam_model``.
+        Determine the incidence angle modifier for direct irradiance
+        using the method specified by ``iam_model``.
 
         Parameters for the selected IAM model are expected to be in
         ``PVSystem.module_parameters``. Default parameters are available for
@@ -411,6 +418,48 @@ def get_iam(self, aoi, iam_model='physical'):
         return tuple(array.get_iam(aoi, iam_model)
                      for array, aoi in zip(self.arrays, aoi))
 
+    @_unwrap_single_value
+    def get_iam_diffuse(self, surface_tilt, iam_model='marion_diffuse',
+                        marion_model=None, **kwargs):
+        """
+        Determine the incidence angle modifier for diffuse irradiance using the
+        method specified by ``iam_model``.
+
+        Parameters for the selected IAM model are expected to be in
+        ``Array.module_parameters``. Default parameters are available for
+        the 'marion_diffuse' and 'martin_ruiz_diffuse' models.
+
+        Parameters
+        ----------
+        surface_tilt : float or Series
+            The tilt angle of the surface in degrees.
+        iam_model : string, default 'marion_diffuse'
+            The IAM model to be used. Valid strings are 'marion_diffuse',
+            'martin_ruiz_diffuse', and 'schlick_diffuse'.
+        marion_model : string, default None
+            The IAM function to evaluate across a solid angle. Only used when
+            ``iam_model='marion_diffuse'``. Must be one of 'ashrae',
+            'physical', 'martin_ruiz', 'sapm', and 'schlick'.
+
+        kwargs : dict, optional
+            Additional keyword arguments passed to the IAM model function.
+
+        Returns
+        -------
+        iam_diffuse : dict or DataFrame
+            The AOI modifiers for different diffuse irradiance components.
+            Included components depend on the selected ``iam_model``.
+
+        Raises
+        ------
+        ValueError
+            if `iam_model` is not a valid model name.
+        """
+        surface_tilt = self._validate_per_array(surface_tilt)
+        return tuple(array.get_iam_diffuse(tilt, iam_model=iam_model,
+                                           marion_model=marion_model, **kwargs)
+                     for array, tilt in zip(self.arrays, surface_tilt))
+
     @_unwrap_single_value
     def get_cell_temperature(self, poa_global, temp_air, wind_speed, model,
                              effective_irradiance=None, longwave_down=None):
@@ -1093,7 +1142,7 @@ def get_aoi(self, solar_zenith, solar_azimuth):
 
     def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi,
                        dni_extra=None, airmass=None, albedo=None,
-                       model='haydavies', **kwargs):
+                       model='haydavies', diffuse_components=False, **kwargs):
         """
         Get plane of array irradiance components.
 
@@ -1121,6 +1170,11 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi,
             Ground surface albedo. [unitless]
         model : String, default 'haydavies'
             Irradiance model.
+        diffuse_components : bool, default False
+            If `True`, returns values for the different diffuse irradiance
+            components available from the selected model
+            (e.g., isotropic, circumsolar, horizon brightening).
+            If `False`, only the total diffuse irradiance is returned.
 
         kwargs
             Extra parameters passed to
@@ -1161,20 +1215,23 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi,
             airmass = atmosphere.get_relative_airmass(solar_zenith)
 
         orientation = self.mount.get_orientation(solar_zenith, solar_azimuth)
-        return irradiance.get_total_irradiance(orientation['surface_tilt'],
-                                               orientation['surface_azimuth'],
-                                               solar_zenith, solar_azimuth,
-                                               dni, ghi, dhi,
-                                               dni_extra=dni_extra,
-                                               airmass=airmass,
-                                               albedo=albedo,
-                                               model=model,
-                                               **kwargs)
+        return irradiance.get_total_irradiance(
+            orientation['surface_tilt'],
+            orientation['surface_azimuth'],
+            solar_zenith, solar_azimuth,
+            dni, ghi, dhi,
+            dni_extra=dni_extra,
+            airmass=airmass,
+            albedo=albedo,
+            model=model,
+            diffuse_components=diffuse_components,
+            **kwargs
+        )
 
     def get_iam(self, aoi, iam_model='physical'):
         """
-        Determine the incidence angle modifier using the method specified by
-        ``iam_model``.
+        Determine the incidence angle modifier for direct irradiance
+        using the method specified by ``iam_model``.
 
         Parameters for the selected IAM model are expected to be in
         ``Array.module_parameters``. Default parameters are available for
@@ -1213,6 +1270,68 @@ def get_iam(self, aoi, iam_model='physical'):
         else:
             raise ValueError(model + ' is not a valid IAM model')
 
+    def get_iam_diffuse(self, surface_tilt, iam_model='marion_diffuse',
+                        marion_model=None, **kwargs):
+        """
+        Determine the incidence angle modifier for various diffuse irradiance
+        components using the method specified by ``iam_model``.
+
+        Parameters for the selected IAM model are expected to be in
+        ``Array.module_parameters``. Default parameters are available for
+        the 'marion_diffuse' and 'martin_ruiz_diffuse' models.
+
+        Parameters
+        ----------
+        surface_tilt : float or Series
+            The tilt angle of the surface in degrees.
+        iam_model : string, default 'marion_diffuse'
+            The IAM model to be used. Valid strings are 'marion_diffuse',
+            'martin_ruiz_diffuse' and 'schlick_diffuse'.
+        marion_model : string, default None
+            The IAM function to evaluate across a solid angle. Only used when
+            ``iam_model='marion_diffuse'``. Must be one of 'ashrae',
+            'physical', 'martin_ruiz' and 'sapm'.
+
+        kwargs : dict, optional
+            Additional keyword arguments passed to the IAM model function.
+
+        Returns
+        -------
+        iam_diffuse : dict or DataFrame
+            The AOI modifiers for different diffuse irradiance components.
+            Included components depend on the selected ``iam_model``.
+
+        Raises
+        ------
+        ValueError
+            if `iam_model` is not a valid model name.
+        ValueError
+            if `iam_model` is 'marion_diffuse' and `marion_model` is None.
+        """
+        model = iam_model.lower()
+        if model == 'marion_diffuse' and marion_model is None:
+            raise ValueError('marion_model must be specified when '
+                             'iam_model="marion_diffuse"')
+        if model in ['marion_diffuse', 'martin_ruiz_diffuse',
+                     'schlick_diffuse']:
+            func = getattr(iam, model)  # get function at pvlib.iam
+            # get all parameters from function signature to retrieve them from
+            # module_parameters if present
+            params = set(inspect.signature(func).parameters.keys())
+            kwargs.update(_build_kwargs(params, self.module_parameters))
+            if iam_model == 'marion_diffuse':
+                iams = func(model=marion_model, surface_tilt=surface_tilt,
+                            **kwargs)
+            else:
+                iams = func(surface_tilt=surface_tilt, **kwargs)
+        else:
+            raise ValueError(model + ' is not a valid diffuse IAM model')
+
+        if isinstance(surface_tilt, pd.Series):
+            iams = pd.DataFrame(iams, index=surface_tilt.index)
+
+        return iams
+
     def get_cell_temperature(self, poa_global, temp_air, wind_speed, model,
                              effective_irradiance=None, longwave_down=None):
         """