add SDM parameter estimation and key point functions

Author: kandersolar

docs/sphinx/source/reference/pv_modeling/sdm.rst

@@ -17,6 +17,7 @@ Functions relevant for single diode models.
    pvsystem.v_from_i
    pvsystem.max_power_point
    ivtools.sdm.pvsyst_temperature_coeff
+   singlediode.batzelis_keypoints
 
 Low-level functions for solving the single diode equation.
 
@@ -37,3 +38,4 @@ Functions for fitting diode models
     ivtools.sde.fit_sandia_simple
     ivtools.sdm.fit_cec_sam
     ivtools.sdm.fit_desoto
+    ivtools.sdm.fit_desoto_batzelis

pvlib/ivtools/sdm/__init__.py

@@ -4,6 +4,10 @@
  fitting method.
 """
 
+from pvlib.ivtools.sdm.batzelis import (  # noqa: F401
+    fit_desoto_batzelis,
+)
+
 from pvlib.ivtools.sdm.cec import (  # noqa: F401
     fit_cec_sam,
 )

pvlib/ivtools/sdm/batzelis.py

@@ -0,0 +1,68 @@
+"""
+Batzelis's method for estimating single-diode model parameters from
+datasheet values.
+"""
+
+import numpy as np
+from scipy.special import lambertw
+
+
+def fit_desoto_batzelis(isc0, voc0, imp0, vmp0, alpha_sc, beta_voc):
+    """
+    Determine De Soto single-diode model parameters from datasheet values
+    using Batzelis's method.
+
+    This method is described in Section II.C of [1]_.
+
+    Parameters
+    ----------
+    isc0 : float
+        Short-circuit current at STC. [A]
+    voc0 : float
+        Open-circuit voltage at STC. [V]
+    imp0 : float
+        Maximum power point current at STC. [A]
+    vmp0 : float
+        Maximum power point voltage at STC. [V]
+    alpha_sc : float
+        Short-circuit current temperature coefficient at STC. [1/K]
+    beta_voc : float
+        Open-circuit voltage temperature coefficient at STC. [1/K]    
+
+    Returns
+    -------
+    dict
+        The returned dict contains the keys:
+
+        * ``alpha_sc`` [A/K]
+        * ``a_ref`` [V]
+        * ``I_L_ref`` [A]
+        * ``I_o_ref`` [A]
+        * ``R_sh_ref`` [Ohm]
+        * ``R_s`` [Ohm]
+
+    References
+    ----------
+    .. [1] E. I. Batzelis, "Simple PV Performance Equations Theoretically Well
+       Founded on the Single-Diode Model," Journal of Photovoltaics vol. 7, 
+       no. 5, pp. 1400-1409, Sep 2017, :doi:`10.1109/JPHOTOV.2017.2711431`
+    """
+    t0 = 298.15  # K
+    del0 = (1 - beta_voc * t0) / (50.1 - alpha_sc * t0)  # Eq 9
+    w0 = lambertw(np.exp(1/del0 + 1)).real
+
+    # Eqs 11-15
+    a0 = del0 * voc0
+    Rs0 = (a0 * (w0 - 1) - vmp0) / imp0
+    Rsh0 = a0 * (w0 - 1) / (isc0 * (1 - 1/w0) - imp0)
+    Iph0 = (1 + Rs0 / Rsh0) * isc0
+    Isat0 = Iph0 * np.exp(-1/del0)
+
+    return {
+        'alpha_sc': alpha_sc * isc0,  # convert 1/K to A/K
+        'a_ref': a0,
+        'I_L_ref': Iph0,
+        'I_o_ref': Isat0,
+        'R_sh_ref': Rsh0,
+        'R_s': Rs0,
+    }

pvlib/pvarray.py

@@ -429,13 +429,13 @@ def batzelis(effective_irradiance, temp_cell,
     Returns
     -------
     dict
-        The returned dict-like object always contains the keys/columns:
+        The returned dict-like object contains the keys/columns:
 
-        * p_mp - power at maximum power point. [W]
-        * i_mp - current at maximum power point. [A]
-        * v_mp - voltage at maximum power point. [V]
-        * i_sc - short circuit current. [A]
-        * v_oc - open circuit voltage. [V]
+        * ``p_mp`` - power at maximum power point. [W]
+        * ``i_mp`` - current at maximum power point. [A]
+        * ``v_mp`` - voltage at maximum power point. [V]
+        * ``i_sc`` - short circuit current. [A]
+        * ``v_oc`` - open circuit voltage. [V]
 
     Notes
     -----
@@ -505,6 +505,7 @@ def batzelis(effective_irradiance, temp_cell,
     vmp = np.clip(vmp, a_min=0, a_max=None)
     voc = np.clip(voc, a_min=0, a_max=None)
 
+    # TODO return dataframe for is_pandas
     return {
         'p_mp': vmp * imp,
         'i_mp': imp,

pvlib/singlediode.py

@@ -861,3 +861,73 @@ def _pwr_optfcn(df, loc):
                                  df['resistance_shunt'], df['nNsVth'])
 
     return current * df[loc]
+
+
+def batzelis_keypoints(photocurrent, saturation_current, resistance_series,
+                       resistance_shunt, nNsVth):
+    """
+    Estimate maximum power, open-circuit, and short-circuit values
+    using Batzelis's method.
+
+    This method is described in Section II.B of [1]_.
+
+    Parameters
+    ----------
+    photocurrent : numeric
+        Light-generated current. [A]
+    
+    saturation_current : numeric
+        Diode saturation current. [A]
+    
+    resistance_series : numeric
+        Series resistance. [Ohm]
+    
+    resistance_shunt : numeric
+        Shunt resistance. [Ohm]
+    
+    nNsVth : numeric
+        The product of the usual diode ideality factor (n, unitless),
+        number of cells in series (Ns), and cell thermal voltage at
+        specified effective irradiance and cell temperature. [V]
+
+    Returns
+    -------
+    dict
+        The returned dict-like object contains the keys/columns:
+
+        * ``p_mp`` - power at maximum power point. [W]
+        * ``i_mp`` - current at maximum power point. [A]
+        * ``v_mp`` - voltage at maximum power point. [V]
+        * ``i_sc`` - short circuit current. [A]
+        * ``v_oc`` - open circuit voltage. [V]
+
+    References
+    ----------
+    .. [1] E. I. Batzelis, "Simple PV Performance Equations Theoretically Well
+       Founded on the Single-Diode Model," Journal of Photovoltaics vol. 7, 
+       no. 5, pp. 1400-1409, Sep 2017, :doi:`10.1109/JPHOTOV.2017.2711431`
+    """
+    # convenience variables
+    Iph = photocurrent
+    Is = saturation_current
+    Rsh = resistance_shunt
+    Rs = resistance_series
+    a = nNsVth
+
+    # Eqs 3-4
+    isc = Iph * Rsh / (Rs + Rsh)
+    voc = a * np.log(Iph / Is)
+
+    # Eqs 5-8
+    w = lambertw(np.e * Iph / Is).real
+    #vmp = (1 + Rs/Rsh) * a * (w - 1) - Rs * Iph * (1 - 1/w)  # not needed
+    imp = Iph * (1 - 1/w) - a * (w - 1) / Rsh
+    vmp = a * (w - 1) - Rs * imp
+
+    return {
+        'p_mp': imp * vmp,
+        'i_mp': imp,
+        'v_mp': vmp,
+        'i_sc': isc,
+        'v_oc': voc,
+    }