Added irradiance_loss_pvsyst function to pvsystem

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

@@ -24,6 +24,10 @@ Enhancements
 * Add :py:func:`pvlib.iam.marion_diffuse` and
   :py:func:`pvlib.iam.marion_integrate` to calculate IAM values for
   diffuse irradiance. (:pull:`984`)
+* Add :py:func:`pvlib.pvsystem.irradiance_losses_pvsyst` and
+  :py:meth:`pvlib.pvsystem.PVSystem.irradiance_losses_pvsyst` to calculate
+  cumulative losses on the effective irradiance with a style similar to PVSyst.
+  Partialy addresses :issue:`988`. Contributed by Brock Taute :ghuser:`btaute`
 
 Bug fixes
 ~~~~~~~~~
@@ -35,6 +39,8 @@ Testing
   applied to functions that require args or kwargs. (:pull:`973`)
 * Test added for :py:class:`pvlib.modelchain.ModelChain` to confirm ValueError when
   ``ac_model`` is an invalid string. (:pull:`886`)
+* Tests added for :py:func:`pvlib.pvsystem.irradiance_losses_pvsyst` and
+  :py:meth:`pvlib.pvsystem.PVSystem.irradiance_losses_pvsyst`
 
 Documentation
 ~~~~~~~~~~~~~

pvlib/pvsystem.py

@@ -849,6 +849,22 @@ def pvwatts_ac(self, pdc):
         return inverter.pvwatts(pdc, self.inverter_parameters['pdc0'],
                                 **kwargs)
 
+    def irradiance_loss_pvsyst(self, effective_irradiance,
+                               irradiance_shading_loss, irradiance_snow_loss,
+                               irradiance_soiling_loss):
+        """
+        Calculates plane of array irradiance losses using a model based on the
+        PVSyst methodology.  A wrapper for
+        :py:func:`pvlib.pvsystem.irradiance_loss_pvsyst`.
+
+        See :py:func:`pvlib.pvsystem.irradiance_loss_pvsyst` for details.
+        """
+
+        return irradiance_loss_pvsyst(effective_irradiance,
+                                      irradiance_shading_loss,
+                                      irradiance_snow_loss,
+                                      irradiance_soiling_loss)
+
     def localize(self, location=None, latitude=None, longitude=None,
                  **kwargs):
         """Creates a LocalizedPVSystem object using this object
@@ -2537,6 +2553,73 @@ def pvwatts_losses(soiling=2, shading=3, snow=0, mismatch=2, wiring=2,
     return losses
 
 
+def irradiance_loss_pvsyst(effective_irradiance, irradiance_shading_loss,
+                           irradiance_snow_loss, irradiance_soiling_loss):
+    r"""
+    Calculates plane of array irradiance losses using a model based on the
+    PVSyst methodology [1]_ of linearly reducing the effective irradiance on a
+    module.  This doesn't account for the electrical losses due to irregular
+    irradiance on different solar cell strings but rather reduces the
+    irradiance input to the single diode equation.
+
+    The losses are compounded using the following equation:
+
+    .. math::
+
+        L_{total}(\%) = 100 [ 1 - \Pi_i ( 1 - \frac{L_i}{100} ) ]
+
+    Note the parameters must each be a series with a DatetimeIndex.  The
+    index of the returned series will be the same as the effective_irradiance
+    index.  All other parameters will be resampled to match this index with
+    a "fill forward" method for filling holes.
+
+    Parameters
+    ----------
+    effective_irradiance : Series
+            The irradiance (W/m2) that is to be reduced.  Plane-of-array
+            irradiance that already accounts for Angle of Incidence and
+            Spectral losses.
+
+    irradiance_shading_loss : Series
+            The fraction of the solar panel that is shaded.
+
+    irradiance_snow_loss : Series
+            The fraction of the solar panel that is covered with snow.
+
+    irradiance_soiling_loss : Series
+            The fraction of the irradiance prevented from reaching the solar
+            cells due to soiling of the solar panel.
+
+    Returns
+    -------
+    losses: Series
+            Irradiance (W/m2) reduction due to compounded losses.
+
+    References
+    ----------
+    .. [1] "Simulation process: Irradiances and PV-array"
+           https://www.pvsyst.com/help/simulation_process.htm
+           (2020).
+
+    """
+
+    fill_method = 'ffill'
+
+    shading_loss = irradiance_shading_loss.reindex_like(effective_irradiance,
+                                                        method=fill_method)
+
+    snow_loss = irradiance_snow_loss.reindex_like(effective_irradiance,
+                                                  method=fill_method)
+
+    soiling_loss = irradiance_soiling_loss.reindex_like(effective_irradiance,
+                                                        method=fill_method)
+
+    irradiance_losses = effective_irradiance * (
+        1 - (1 - shading_loss) * (1 - snow_loss) * (1 - soiling_loss))
+
+    return irradiance_losses
+
+
 ashraeiam = deprecated('0.7', alternative='iam.ashrae', name='ashraeiam',
                        removal='0.8')(iam.ashrae)
 

pvlib/tests/test_pvsystem.py

@@ -1347,6 +1347,38 @@ def test_PVSystem_pvwatts_ac_kwargs(mocker):
     assert out < pdc
 
 
+def make_irradiance_loss_pvsyst_test_series():
+    final_index = pd.date_range(start='1/1/1990 12:00', periods=365, freq='D')
+    effective_irradiance = pd.Series(1000, index=final_index)
+    shading = pd.Series(.1, index=final_index)
+    snow = pd.Series(.05, index=pd.date_range(start='1/1/1990 12:00',
+                                              periods=365*2, freq='D'))
+    soiling = pd.Series(.02, index=pd.date_range(start='1/1/1990',
+                                                 periods=12, freq='MS'))
+    expected = pd.Series(162.1, index=final_index)
+
+    return {'effective_irradiance': effective_irradiance,
+            'shading': shading, 'snow': snow,
+            'soiling': soiling, 'expected': expected}
+
+
+def test_irradiance_loss_pvsyst():
+    params = make_irradiance_loss_pvsyst_test_series()
+    out = pvsystem.irradiance_loss_pvsyst(params['effective_irradiance'],
+                                          params['shading'], params['snow'],
+                                          params['soiling'])
+    assert_series_equal(params['expected'], out)
+
+
+def test_PVSystem_irradiance_loss_pvsyst():
+    system = pvsystem.PVSystem()
+    params = make_irradiance_loss_pvsyst_test_series()
+    out = system.irradiance_loss_pvsyst(params['effective_irradiance'],
+                                        params['shading'], params['snow'],
+                                        params['soiling'])
+    assert_series_equal(params['expected'], out)
+
+
 @fail_on_pvlib_version('0.8')
 def test_deprecated_08():
     # deprecated function pvsystem.sapm_celltemp