DC Ohmic Losses for pvsystem and modelchain (#1168)

* Support functions for ohmic losses

* PVSystem dc ohmic losses and tests

* ModelChain dc ohimc losses as tests

* updates to api.rst for dc_ohmic_losses

* Docstring formatting updates

* make dc_ohms_from_percent work with other dc models

* format fixes

* support for multiple arrays

* added tests for new module parameters

* modelchain tests for multiple array support

* fix api, document render, and use explict variables

* resolve conflict and small format fix

* dc_ohmic_losses as results attribute

* fix tests and None model

* remove none as model option

* remove none from tests

Author: ncroft-b4

docs/sphinx/source/api.rst

@@ -334,6 +334,8 @@ Pvsyst model
    temperature.pvsyst_cell
    pvsystem.calcparams_pvsyst
    pvsystem.singlediode
+   pvsystem.dc_ohms_from_percent
+   pvsystem.dc_ohmic_losses
 
 PVWatts model
 ^^^^^^^^^^^^^
@@ -392,6 +394,7 @@ Loss models
    :toctree: generated/
 
    pvsystem.combine_loss_factors
+   pvsystem.dc_ohms_from_percent
 
 Snow
 ----
@@ -617,6 +620,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
 
@@ -647,6 +651,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

@@ -255,7 +255,8 @@ class ModelChainResult:
     _singleton_tuples: bool = field(default=False)
     _per_array_fields = {'total_irrad', 'aoi', 'aoi_modifier',
                          'spectral_modifier', 'cell_temperature',
-                         'effective_irradiance', 'dc', 'diode_params'}
+                         'effective_irradiance', 'dc', 'diode_params',
+                         'dc_ohmic_losses'}
 
     # system-level information
     solar_position: Optional[pd.DataFrame] = field(default=None)
@@ -275,6 +276,7 @@ class ModelChainResult:
     dc: Optional[PerArray[Union[pd.Series, pd.DataFrame]]] = \
         field(default=None)
     diode_params: Optional[PerArray[pd.DataFrame]] = field(default=None)
+    dc_ohmic_losses: Optional[PerArray[pd.Series]] = field(default=None)
 
     def _result_type(self, value):
         """Coerce `value` to the correct type according to
@@ -356,6 +358,11 @@ class ModelChain:
         The ModelChain instance will be passed as the first argument to a
         user-defined function.
 
+    dc_ohmic_model: str or function, default 'no_loss'
+        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.
@@ -377,6 +384,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='no_loss',
                  losses_model='no_loss', name=None):
 
         self.name = name
@@ -395,6 +403,7 @@ 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.weather = None
@@ -1020,6 +1029,49 @@ def fuentes_temp(self):
     def noct_sam_temp(self):
         return self._set_celltemp(self.system.noct_sam_celltemp)
 
+    @property
+    def dc_ohmic_model(self):
+        return self._dc_ohmic_model
+
+    @dc_ohmic_model.setter
+    def dc_ohmic_model(self, model):
+        if 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()
+        if isinstance(self.results.dc, tuple):
+            self.results.dc_ohmic_losses = tuple(
+                pvsystem.dc_ohmic_losses(Rw, df['i_mp'])
+                for Rw, df in zip(Rw, self.results.dc)
+            )
+            for df, loss in zip(self.results.dc, self.results.dc_ohmic_losses):
+                df['p_mp'] = df['p_mp'] - loss
+        else:
+            self.results.dc_ohmic_losses = pvsystem.dc_ohmic_losses(
+                Rw, self.results.dc['i_mp']
+            )
+            self.results.dc['p_mp'] = (self.results.dc['p_mp']
+                                       - self.results.dc_ohmic_losses)
+        return self
+
+    def no_dc_ohmic_loss(self):
+        return self
+
     @property
     def losses_model(self):
         return self._losses_model
@@ -1693,6 +1745,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

@@ -191,6 +191,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,
@@ -202,7 +207,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)
@@ -1092,6 +1098,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):
@@ -1224,6 +1241,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,
@@ -1233,7 +1253,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
 
@@ -1261,6 +1282,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):
@@ -1447,6 +1473,72 @@ 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`
+
+        Makes use of array module parameters according to the
+        following DC models:
+
+        CEC:
+
+            * `self.module_parameters["V_mp_ref"]`
+            * `self.module_parameters["I_mp_ref"]`
+
+        SAPM:
+
+            * `self.module_parameters["Vmpo"]`
+            * `self.module_parameters["Impo"]`
+
+        PVsyst-like or other:
+
+            * `self.module_parameters["Vmpp"]`
+            * `self.module_parameters["Impp"]`
+
+        Other array parameters that are used are:
+        `self.losses_parameters["dc_ohmic_percent"]`,
+        `self.modules_per_string`, and
+        `self.strings`.
+
+        See :py:func:`pvlib.pvsystem.dc_ohms_from_percent` for more details.
+        """
+
+        # get relevent Vmp and Imp parameters from CEC parameters
+        if all([elem in self.module_parameters
+                for elem in ['V_mp_ref', 'I_mp_ref']]):
+            vmp_ref = self.module_parameters['V_mp_ref']
+            imp_ref = self.module_parameters['I_mp_ref']
+
+        # get relevant Vmp and Imp parameters from SAPM parameters
+        elif all([elem in self.module_parameters
+                  for elem in ['Vmpo', 'Impo']]):
+            vmp_ref = self.module_parameters['Vmpo']
+            imp_ref = self.module_parameters['Impo']
+
+        # get relevant Vmp and Imp parameters if they are PVsyst-like
+        elif all([elem in self.module_parameters
+                  for elem in ['Vmpp', 'Impp']]):
+            vmp_ref = self.module_parameters['Vmpp']
+            imp_ref = self.module_parameters['Impp']
+
+        # raise error if relevant Vmp and Imp parameters are not found
+        else:
+            raise ValueError('Parameters for Vmp and Imp could not be found '
+                             'in the array module parameters. Module '
+                             'parameters must include one set of '
+                             '{"V_mp_ref", "I_mp_Ref"}, '
+                             '{"Vmpo", "Impo"}, or '
+                             '{"Vmpp", "Impp"}.'
+                             )
+
+        return dc_ohms_from_percent(
+            vmp_ref,
+            imp_ref,
+            self.array_losses_parameters['dc_ohmic_percent'],
+            self.modules_per_string,
+            self.strings)
+
 
 def calcparams_desoto(effective_irradiance, temp_cell,
                       alpha_sc, a_ref, I_L_ref, I_o_ref, R_sh_ref, R_s,
@@ -2885,6 +2977,80 @@ def pvwatts_losses(soiling=2, shading=3, snow=0, mismatch=2, wiring=2,
     return losses
 
 
+def dc_ohms_from_percent(vmp_ref, imp_ref, dc_ohmic_percent,
+                         modules_per_string=1,
+                         strings=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:`Rw` is the equivalent resistance in ohms
+    :math:`Varray` is the Vmp of the modules times modules per string
+    :math:`Iarray` is the Imp of the modules times strings per array
+    :math:`L_{stc}` is the input dc loss percent
+
+    Parameters
+    ----------
+    vmp_ref: numeric
+        Voltage at maximum power in reference conditions [V]
+    imp_ref: numeric
+        Current at maximum power in reference conditions [V]
+    dc_ohmic_percent: numeric, default 0
+        input dc loss as a percent, e.g. 1.5% loss is input as 1.5
+    modules_per_string: int, default 1
+        Number of modules per string in the array.
+    strings: int, default 1
+        Number of parallel strings in the array.
+
+    Returns
+    ----------
+    Rw: numeric
+        Equivalent resistance [ohm]
+
+    References
+    ----------
+    .. [1] PVsyst 7 Help. "Array ohmic wiring loss".
+       https://www.pvsyst.com/help/ohmic_loss.htm
+    """
+    vmp = modules_per_string * vmp_ref
+
+    imp = strings * imp_ref
+
+    Rw = (dc_ohmic_percent / 100) * (vmp / imp)
+
+    return Rw
+
+
+def dc_ohmic_losses(resistance, current):
+    """
+    Returns ohmic losses in units of power from the equivalent
+    resistance of the wires and the operating current.
+
+    Parameters
+    ----------
+    resistance: numeric
+        Equivalent resistance of wires [ohm]
+    current: numeric, float or array-like
+        Operating current [A]
+
+    Returns
+    ----------
+    loss: numeric
+        Power Loss [W]
+
+    References
+    ----------
+    .. [1] PVsyst 7 Help. "Array ohmic wiring loss".
+       https://www.pvsyst.com/help/ohmic_loss.htm
+    """
+    return resistance * current * current
+
+
 def combine_loss_factors(index, *losses, fill_method='ffill'):
     r"""
     Combines Series loss fractions while setting a common index.