DC Ohmic Losses for pvsystem and modelchain

docs/sphinx/source/api.rst

@@ -331,6 +331,7 @@ Pvsyst model
    temperature.pvsyst_cell
    pvsystem.calcparams_pvsyst
    pvsystem.singlediode
+   pvsystem.dc_ohms_from_percent
 
 PVWatts model
 ^^^^^^^^^^^^^
@@ -389,6 +390,8 @@ Loss models
    :toctree: generated/
 
    pvsystem.combine_loss_factors
+   pvsystem.dc_ohms_from_percent
+   modelchain.ModelChain.dc_ohmic_model
 
 Snow
 ----
@@ -615,6 +618,7 @@ ModelChain properties that are aliases for your specific modeling functions.
    modelchain.ModelChain.aoi_model
    modelchain.ModelChain.spectral_model
    modelchain.ModelChain.temperature_model
+   modelchain.ModelChain.dc_ohmic_model
    modelchain.ModelChain.losses_model
    modelchain.ModelChain.effective_irradiance_model
 
@@ -645,6 +649,8 @@ ModelChain model definitions.
    modelchain.ModelChain.pvsyst_temp
    modelchain.ModelChain.faiman_temp
    modelchain.ModelChain.fuentes_temp
+   modelchain.ModelChain.dc_ohmic_model
+   modelchain.ModelChain.no_dc_ohmic_loss
    modelchain.ModelChain.pvwatts_losses
    modelchain.ModelChain.no_extra_losses
 

pvlib/modelchain.py

@@ -380,6 +380,11 @@ class ModelChain:
         The ModelChain instance will be passed as the first argument to a
         user-defined function.
 
+    dc_ohmic_model: None, str or function, default None
+        Valid strings are 'dc_ohms_from_percent', 'no_loss'. The ModelChain
+        instance will be passed as the first argument to a user-defined
+        function.
+
     losses_model: str or function, default 'no_loss'
         Valid strings are 'pvwatts', 'no_loss'. The ModelChain instance
         will be passed as the first argument to a user-defined function.
@@ -402,6 +407,7 @@ def __init__(self, system, location,
                  airmass_model='kastenyoung1989',
                  dc_model=None, ac_model=None, aoi_model=None,
                  spectral_model=None, temperature_model=None,
+                 dc_ohmic_model=None,
                  losses_model='no_loss', name=None):
 
         self.name = name
@@ -420,7 +426,9 @@ def __init__(self, system, location,
         self.spectral_model = spectral_model
         self.temperature_model = temperature_model
 
+        self.dc_ohmic_model = dc_ohmic_model
         self.losses_model = losses_model
+
         self.orientation_strategy = orientation_strategy
 
         self.weather = None
@@ -1068,6 +1076,40 @@ def faiman_temp(self):
     def fuentes_temp(self):
         return self._set_celltemp(self.system.fuentes_celltemp)
 
+    @property
+    def dc_ohmic_model(self):
+        return self._dc_ohmic_model
+
+    @dc_ohmic_model.setter
+    def dc_ohmic_model(self, model):
+        if model is None:
+            self._dc_ohmic_model = self.no_dc_ohmic_loss
+        elif isinstance(model, str):
+            model = model.lower()
+            if model == 'dc_ohms_from_percent':
+                self._dc_ohmic_model = self.dc_ohms_from_percent
+            elif model == 'no_loss':
+                self._dc_ohmic_model = self.no_dc_ohmic_loss
+            else:
+                raise ValueError(model + ' is not a valid losses model')
+        else:
+            self._dc_ohmic_model = partial(model, self)
+
+    def dc_ohms_from_percent(self):
+        """
+        Calculate time series of ohmic losses and apply those to the mpp power
+        output of the `dc_model` based on the pvsyst equivalent resistance
+        method. Uses a `dc_ohmic_percent` parameter in the `losses_parameters`
+        of the PVsystem.
+        """
+        Rw = self.system.dc_ohms_from_percent()
+        self.dc_ohmic_losses = pvsystem.dc_ohmic_losses(Rw, self.dc['i_mp'])
+        self.dc['p_mp'] = self.dc['p_mp'] - self.dc_ohmic_losses
+        return self
+
+    def no_dc_ohmic_loss(self):
+        return self
+
     @property
     def losses_model(self):
         return self._losses_model
@@ -1737,6 +1779,7 @@ def _run_from_effective_irrad(self, data=None):
         """
         self._prepare_temperature(data)
         self.dc_model()
+        self.dc_ohmic_model()
         self.losses_model()
         self.ac_model()
 

pvlib/pvsystem.py

@@ -190,6 +190,11 @@ def __init__(self,
                  racking_model=None, losses_parameters=None, name=None):
 
         if arrays is None:
+            if losses_parameters is None:
+                array_losses_parameters = {}
+            else:
+                array_losses_parameters = _build_kwargs(['dc_ohmic_percent'],
+                                                        losses_parameters)
             self.arrays = (Array(
                 surface_tilt,
                 surface_azimuth,
@@ -201,7 +206,8 @@ def __init__(self,
                 temperature_model_parameters,
                 modules_per_string,
                 strings_per_inverter,
-                racking_model
+                racking_model,
+                array_losses_parameters,
             ),)
         else:
             self.arrays = tuple(arrays)
@@ -1017,6 +1023,17 @@ def pvwatts_ac(self, pdc):
         return inverter.pvwatts(pdc, self.inverter_parameters['pdc0'],
                                 **kwargs)
 
+    @_unwrap_single_value
+    def dc_ohms_from_percent(self):
+        """
+        Calculates the equivalent resistance of the wires for each array using
+        :py:func:`pvlib.pvsystem.dc_ohms_from_percent`
+
+        See :py:func:`pvlib.pvsystem.dc_ohms_from_percent` for details.
+        """
+
+        return tuple(array.dc_ohms_from_percent() for array in self.arrays)
+
     @property
     @_unwrap_single_value
     def module_parameters(self):
@@ -1149,6 +1166,9 @@ class Array:
         Valid strings are 'open_rack', 'close_mount', and 'insulated_back'.
         Used to identify a parameter set for the SAPM cell temperature model.
 
+    array_losses_parameters: None, dict or Series, default None.
+        Supported keys are dc_ohmic_percent.
+
     """
 
     def __init__(self,
@@ -1158,7 +1178,8 @@ def __init__(self,
                  module_parameters=None,
                  temperature_model_parameters=None,
                  modules_per_string=1, strings=1,
-                 racking_model=None, name=None):
+                 racking_model=None, array_losses_parameters=None,
+                 name=None):
         self.surface_tilt = surface_tilt
         self.surface_azimuth = surface_azimuth
 
@@ -1186,6 +1207,11 @@ def __init__(self,
         else:
             self.temperature_model_parameters = temperature_model_parameters
 
+        if array_losses_parameters is None:
+            self.array_losses_parameters = {}
+        else:
+            self.array_losses_parameters = array_losses_parameters
+
         self.name = name
 
     def __repr__(self):
@@ -1372,6 +1398,28 @@ def get_iam(self, aoi, iam_model='physical'):
         else:
             raise ValueError(model + ' is not a valid IAM model')
 
+    def dc_ohms_from_percent(self):
+        """
+        Calculates the equivalent resistance of the wires using
+        :py:func:`pvlib.pvsystem.dc_ohms_from_percent`,
+        `self.losses_parameters["dc_ohmic_percent"]`,
+        `self.module_parameters["V_mp_ref"]`,
+        `self.module_parameters["I_mp_ref"]`,
+        `self.modules_per_string`, and `self.strings_per_inverter`.
+        See :py:func:`pvlib.pvsystem.dc_ohms_from_percent` for details.
+        """
+
+        kwargs = _build_kwargs(['dc_ohmic_percent'],
+                               self.array_losses_parameters)
+
+        kwargs.update(_build_kwargs(['V_mp_ref', 'I_mp_ref'],
+                                    self.module_parameters))
+
+        kwargs.update({'modules_per_string': self.modules_per_string,
+                       'strings_per_inverter': self.strings})
+
+        return dc_ohms_from_percent(**kwargs)
+
 
 def calcparams_desoto(effective_irradiance, temp_cell,
                       alpha_sc, a_ref, I_L_ref, I_o_ref, R_sh_ref, R_s,
@@ -2810,6 +2858,71 @@ def pvwatts_losses(soiling=2, shading=3, snow=0, mismatch=2, wiring=2,
     return losses
 
 
+def dc_ohms_from_percent(V_mp_ref, I_mp_ref, dc_ohmic_percent,
+                         modules_per_string=1,
+                         strings_per_inverter=1):
+    """
+    Calculates the equivalent resistance of the wires from a percent
+    ohmic loss at STC.
+
+    Equivalent resistance is calculated with the function:
+
+    .. math::
+        Rw = (L_{stc} / 100) * (Varray / Iarray)
+
+    :math:`L_{stc}` is the input dc loss as a percent, e.g. 1.5% loss is
+    input as 1.5
+
+    Parameters
+    ----------
+    V_mp_ref: numeric
+    I_mp_ref: numeric
+    dc_ohmic_percent: numeric, default 0
+    modules_per_string: numeric, default 1
+    strings_per_inverter: numeric, default 1
+
+    Returns
+    ----------
+    Rw: numeric
+        Equivalent resistance in ohms
+
+    References
+    ----------
+    -- [1] PVsyst 7 Help. "Array ohmic wiring loss".
+            https://www.pvsyst.com/help/ohmic_loss.htm
+    """
+    vmp = modules_per_string * V_mp_ref
+
+    imp = strings_per_inverter * I_mp_ref
+
+    Rw = (dc_ohmic_percent / 100) * (vmp / imp)
+
+    return Rw
+
+
+def dc_ohmic_losses(ohms, current):
+    """
+    Returns ohmic losses in in units of power from the equivalent
+    resistance of of the wires and the operating current.
+
+    Parameters
+    ----------
+    ohms: numeric, float
+    current: numeric, float or array-like
+
+    Returns
+    ----------
+    numeric
+        Single or array-like value of the losses in units of power
+
+    References
+    ----------
+    -- [1] PVsyst 7 Help. "Array ohmic wiring loss".
+            https://www.pvsyst.com/help/ohmic_loss.htm
+    """
+    return ohms * current * current
+
+
 def combine_loss_factors(index, *losses, fill_method='ffill'):
     r"""
     Combines Series loss fractions while setting a common index.

pvlib/tests/test_modelchain.py

@@ -1491,6 +1491,73 @@ def constant_losses(mc):
     mc.results.dc *= mc.losses
 
 
+def dc_constant_losses(mc):
+    mc.results.dc['p_mp'] *= 0.9
+
+
+def test_dc_ohmic_model_ohms_from_percent(cec_dc_snl_ac_system,
+                                          location,
+                                          weather,
+                                          mocker):
+
+    m = mocker.spy(pvsystem, 'dc_ohms_from_percent')
+
+    system = cec_dc_snl_ac_system
+
+    for array in system.arrays:
+        array.array_losses_parameters = dict(dc_ohmic_percent=3)
+
+    mc = ModelChain(system, location,
+                    aoi_model='no_loss',
+                    spectral_model='no_loss',
+                    dc_ohmic_model='dc_ohms_from_percent')
+    mc.run_model(weather)
+
+    assert m.call_count == 1
+
+    assert isinstance(mc.dc_ohmic_losses, pd.Series)
+
+
+def test_dc_ohmic_model_no_dc_ohmic_loss(cec_dc_snl_ac_system,
+                                         location,
+                                         weather,
+                                         mocker):
+
+    m = mocker.spy(modelchain.ModelChain, 'no_dc_ohmic_loss')
+    mc = ModelChain(cec_dc_snl_ac_system, location,
+                    aoi_model='no_loss',
+                    spectral_model='no_loss',
+                    dc_ohmic_model='no_loss')
+    mc.run_model(weather)
+
+    assert m.call_count == 1
+    assert hasattr(mc, 'dc_ohmic_losses') is False
+
+
+def test_dc_ohmic_ext_def(cec_dc_snl_ac_system, location,
+                          weather, mocker):
+    m = mocker.spy(sys.modules[__name__], 'dc_constant_losses')
+    mc = ModelChain(cec_dc_snl_ac_system, location,
+                    aoi_model='no_loss',
+                    spectral_model='no_loss',
+                    dc_ohmic_model=dc_constant_losses)
+    mc.run_model(weather)
+
+    assert m.call_count == 1
+    assert isinstance(mc.results.ac, (pd.Series, pd.DataFrame))
+    assert not mc.results.ac.empty
+
+
+def test_dc_ohmic_not_a_model(cec_dc_snl_ac_system, location,
+                              weather, mocker):
+    exc_text = 'not_a_dc_model is not a valid losses model'
+    with pytest.raises(ValueError, match=exc_text):
+        ModelChain(cec_dc_snl_ac_system, location,
+                   aoi_model='no_loss',
+                   spectral_model='no_loss',
+                   dc_ohmic_model='not_a_dc_model')
+
+
 def test_losses_models_pvwatts(pvwatts_dc_pvwatts_ac_system, location, weather,
                                mocker):
     age = 1