Add support for diffuse IAM in the Array and PVSystem classes (#2845)

* Add return_components to isotropic

* Change OrderedDict to dict

* Add tests for isotropic with return_components=True

* Add what's new entry

* Add support for 'return_components'

* Add tests

* Raise error if return_components=True used with king or klucher

* Update pvlib/irradiance.py

Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>

* Adjust docstrings

* Fix list indentation

* Add more tests

* Minor fix

* Add whatsnew entry

* Add get_iam_diffuse to the Array and PVSystem classes

* Set all IAM outputs to dict

* Add whatsnew entry

* Minor change to docstrings

* Docstring changes

* Add schlick_diffuse

* Add error test

* Add Dataframe support

* Add whatsnew entry

* Fix diffuse IAM kwargs

* Add tests to fix codecov

* Fix Array.get_iam_diffuse kwargs

* Implement suggestions by cwhanse

* Apply batched suggestions from code review

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

* Implement suggestions by kandersolar

* Remove marion_diffuse as default

* Fix backticks

---------

Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>
Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

Author: 3 people

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

@@ -89,6 +89,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/pvsystem.py

@@ -306,7 +306,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
@@ -333,6 +333,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 the diffuse irradiance components available
+            from the selected model (e.g., `poa_isotropic`,
+            `poa_circumsolar`, `poa_horizon`).
+            If ``False``, only the total diffuse irradiance is returned.
 
         kwargs
             Extra parameters passed to
@@ -372,7 +377,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
             )
@@ -381,8 +388,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
@@ -410,6 +417,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_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 : numeric or tuple of numeric
+            The tilt angle of the surface in degrees.
+        iam_model : str
+            The IAM model to be used. Valid strings are 'marion_diffuse',
+            'martin_ruiz_diffuse', and 'schlick_diffuse'.
+        marion_model : str, optional
+            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):
@@ -1092,7 +1141,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.
 
@@ -1120,6 +1169,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 the diffuse irradiance components available
+            from the selected model (e.g., ``poa_isotropic``,
+            ``poa_circumsolar``, ``poa_horizon``).
+            If ``False``, only the total diffuse irradiance is returned.
 
         kwargs
             Extra parameters passed to
@@ -1160,20 +1214,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
@@ -1212,6 +1269,81 @@ 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_model=None, **kwargs):
+        """
+        Determine the incidence angle modifier for various diffuse irradiance
+        components using the method specified by ``iam_model``.
+
+        Parameters for ``iam_model`` are used from ``Array.module_parameters``
+        if found. If parameters are not found in ``Array.module_parameters``,
+        default parameters for ``iam_model`` are used.
+
+        Parameters
+        ----------
+        surface_tilt : numeric
+            The tilt angle of the surface in degrees.
+        iam_model : str
+            The IAM model to be used. Valid strings are 'marion_diffuse',
+            'martin_ruiz_diffuse' and 'schlick_diffuse'.
+        marion_model : str, optional
+            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'.
+
+        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 not
+            a valid model name.
+        """
+        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 == 'marion_diffuse':
+            if marion_model in ['ashrae', 'physical', 'martin_ruiz',
+                                'schlick']:
+                func = getattr(iam, marion_model)
+                params = iam._IAM_MODEL_PARAMS[marion_model]
+                params.discard('aoi')
+                kwargs = _build_kwargs(params, self.module_parameters)
+                iams = iam.marion_diffuse(model=marion_model,
+                                          surface_tilt=surface_tilt,
+                                          **kwargs)
+            elif marion_model == 'sapm':
+                iams = iam.marion_diffuse(model='sapm',
+                                          surface_tilt=surface_tilt,
+                                          module=self.module_parameters,
+                                          **kwargs)
+            else:
+                raise ValueError(marion_model + ' is not a valid IAM model')
+        elif model == 'martin_ruiz_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())
+            params.discard('aoi')
+            kwargs = _build_kwargs(params, self.module_parameters)
+            iams = iam.martin_ruiz_diffuse(surface_tilt=surface_tilt, **kwargs)
+        elif model == 'schlick_diffuse':
+            iams = iam.schlick_diffuse(surface_tilt=surface_tilt)
+        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):
         """

tests/test_pvsystem.py

@@ -112,6 +112,76 @@ def test_PVSystem_get_iam_invalid(sapm_module_params, mocker):
         system.get_iam(45, iam_model='not_a_model')
 
 
+def test_PVSystem_get_iam_diffuse_marion(sapm_module_params, mocker):
+    model_params = {'b': 0.05}
+    m = mocker.spy(_iam, 'marion_diffuse')
+    system = pvsystem.PVSystem(module_parameters=model_params)
+    tilt = 30
+    iam = system.get_iam_diffuse(tilt, iam_model='marion_diffuse',
+                                 marion_model='ashrae')
+    m.assert_called_with(model='ashrae', surface_tilt=tilt,
+                         **model_params)
+    assert isinstance(iam, dict)
+    assert set(iam.keys()) == {'sky', 'ground', 'horizon'}
+
+    system = pvsystem.PVSystem(module_parameters=sapm_module_params)
+    tilt = pd.Series([30, 60])
+    iam = system.get_iam_diffuse(tilt, iam_model='marion_diffuse',
+                                 marion_model='sapm')
+    assert isinstance(iam, pd.DataFrame)
+
+
+@pytest.mark.parametrize('iam_model', ['martin_ruiz_diffuse',
+                                       'schlick_diffuse'])
+def test_PVSystem_get_iam_diffuse(iam_model, mocker):
+    model_params = {'a_r': 0.16} if iam_model == 'martin_ruiz_diffuse' else {}
+    m = mocker.spy(_iam, iam_model)
+    system = pvsystem.PVSystem(module_parameters=model_params)
+    tilt = 30
+    iam = system.get_iam_diffuse(tilt, iam_model=iam_model)
+    m.assert_called_with(surface_tilt=tilt, **model_params)
+    assert isinstance(iam, dict)
+
+
+def test_PVSystem_multi_array_get_iam_diffuse():
+    model_params = {'b': 0.05}
+    system = pvsystem.PVSystem(
+        arrays=[pvsystem.Array(mount=pvsystem.FixedMount(0, 180),
+                               module_parameters=model_params),
+                pvsystem.Array(mount=pvsystem.FixedMount(0, 180),
+                               module_parameters=model_params)]
+    )
+    iam = system.get_iam_diffuse((30, 60), iam_model='marion_diffuse',
+                                 marion_model='ashrae')
+    assert len(iam) == 2
+    assert iam[0] != iam[1]
+    with pytest.raises(ValueError,
+                       match="Length mismatch for per-array parameter"):
+        system.get_iam_diffuse((30,), iam_model='marion_diffuse',
+                               marion_model='ashrae')
+
+
+def test_PVSystem_get_iam_diffuse_invalid(sapm_module_params):
+    system = pvsystem.PVSystem(module_parameters=sapm_module_params)
+    msg = 'not a valid diffuse IAM model'
+    with pytest.raises(ValueError, match=msg):
+        system.get_iam_diffuse(45, iam_model='not_a_model')
+
+
+def test_PVSystem_get_iam_diffuse_marion_invalid(sapm_module_params):
+    system = pvsystem.PVSystem(module_parameters=sapm_module_params)
+    msg = 'not a valid IAM model'
+    with pytest.raises(ValueError, match=msg):
+        system.get_iam_diffuse(45, iam_model='marion_diffuse',
+                               marion_model='not_a_model')
+
+
+def test_PVSystem_get_iam_diffuse_marion_missing_model(sapm_module_params):
+    system = pvsystem.PVSystem(module_parameters=sapm_module_params)
+    with pytest.raises(ValueError, match="marion_model must be specified"):
+        system.get_iam_diffuse(45, iam_model='marion_diffuse')
+
+
 def test_retrieve_sam_raises_exceptions():
     """
     Raise an exception if an invalid parameter is provided to `retrieve_sam()`.