Clarify Egref and dEgdT values, changes calcparams_desoto api (#471)

cwhanse · wholmgren · commit 8aec26760133 · 2018-06-07T09:09:56.000-07:00
* Fix total_irrad docstring

* Correct formatting in irradiance.py; update whatsnew.rst

* Update irradiance.py

* update CEC module and inverter files

* Add files via upload

* Change pvsystem.calcparams_desoto API to keywords, add _build_kwargs to PVSystem.calcparams_desoto

* Change signature of pvsystem.calcparams_desoto to all keyword arguments, remove M argument, change poa_irradiance to effective_irradiance, and add _build_kwargs to PVSystem.calcparams_desoto

* Change signature of pvsystem.calcparams_desoto to all keyword arguments, remove M argument, change poa_irradiance to effective_irradiance, and add _build_kwargs to PVSystem.calcparams_desoto

* fix merge conflict in irradiance.py

* fix merge conflict in cec inverter file

* fix merge conflicts

* fix typo in test_pvsystem.test_calcparams_desoto

* Correct test condition

* correct alpha_isc to alpha_sc

* update test_singlediode_** for change in calcparams_desoto api

* "Fix merge conflict"

* Change units on effective_irradiance input to calcparams_desoto from suns to W/m2

* Correct irradiance units in test_singlediode_series_ivcurve

* Updates to pvsystem tutorial, modelchain documentation, whatsnew

* Edit whatsnew text, add graceful exit from calcparams_desoto if old arguments detected

* Edits to warning messages in calcparams_desoto

* Improve comments

* Improve comments
diff --git a/docs/sphinx/source/modelchain.ipynb b/docs/sphinx/source/modelchain.ipynb
@@ -730,7 +730,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.1"
+   "version": "3.6.4"
   }
  },
  "nbformat": 4,
diff --git a/docs/sphinx/source/whatsnew/v0.6.0.rst b/docs/sphinx/source/whatsnew/v0.6.0.rst
@@ -5,13 +5,14 @@ v0.6.0 (___, 2018)
 
 API Changes
 ~~~~~~~~~~~
-
+* pvsystem.calcparams_desoto now requires arguments for each module model parameter.
 
 
 Enhancements
 ~~~~~~~~~~~~
 * Add sea surface albedo in irradiance.py (:issue:`458`)
-* Implement first_solar_spectral_loss in modelchain.py (:issue:'359')
+* Implement first_solar_spectral_loss in modelchain.py (:issue:`359`)
+* Clarify arguments Egref and dEgdT for calcparams_desoto (:issue:`462`)
 
 
 Bug fixes
diff --git a/docs/tutorials/pvsystem.ipynb b/docs/tutorials/pvsystem.ipynb
diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py
@@ -279,16 +279,16 @@ def physicaliam(self, aoi):
 
         return physicaliam(aoi, **kwargs)
 
-    def calcparams_desoto(self, poa_global, temp_cell, **kwargs):
+    def calcparams_desoto(self, effective_irradiance, temp_cell, **kwargs):
         """
         Use the :py:func:`calcparams_desoto` function, the input
         parameters and ``self.module_parameters`` to calculate the
         module currents and resistances.
 
         Parameters
         ----------
-        poa_global : float or Series
-            The irradiance (in W/m^2) absorbed by the module.
+        effective_irradiance : numeric
+            The irradiance (W/m2) that is converted to photocurrent.
 
         temp_cell : float or Series
             The average cell temperature of cells within a module in C.
@@ -300,11 +300,12 @@ def calcparams_desoto(self, poa_global, temp_cell, **kwargs):
         -------
         See pvsystem.calcparams_desoto for details
         """
-        return calcparams_desoto(poa_global, temp_cell,
-                                 self.module_parameters['alpha_sc'],
-                                 self.module_parameters,
-                                 self.module_parameters['EgRef'],
-                                 self.module_parameters['dEgdT'], **kwargs)
+
+        kwargs = _build_kwargs(['a_ref', 'I_L_ref', 'I_o_ref', 'R_sh_ref',
+                                'R_s', 'alpha_sc', 'EgRef', 'dEgdT'],
+                                self.module_parameters)
+        
+        return calcparams_desoto(effective_irradiance, temp_cell, **kwargs)
 
     def sapm(self, effective_irradiance, temp_cell, **kwargs):
         """
@@ -944,75 +945,60 @@ def physicaliam(aoi, n=1.526, K=4., L=0.002):
     return iam
 
 
-def calcparams_desoto(poa_global, temp_cell, alpha_isc, module_parameters,
-                      EgRef, dEgdT, M=1, irrad_ref=1000, temp_ref=25):
+def calcparams_desoto(effective_irradiance, temp_cell,
+                      alpha_sc, a_ref, I_L_ref, I_o_ref, R_sh_ref, R_s, 
+                      EgRef=1.121, dEgdT=-0.0002677,
+                      irrad_ref=1000, temp_ref=25):
     '''
-    Applies the temperature and irradiance corrections to inputs for
-    singlediode.
-
-    Applies the temperature and irradiance corrections to the IL, I0,
-    Rs, Rsh, and a parameters at reference conditions (IL_ref, I0_ref,
-    etc.) according to the De Soto et. al description given in [1]. The
-    results of this correction procedure may be used in a single diode
-    model to determine IV curves at irradiance = S, cell temperature =
-    Tcell.
+    Calculates five parameter values for the single diode equation at 
+    effective irradiance and cell temperature using the De Soto et al. 
+    model described in [1]. The five values returned by calcparams_desoto
+    can be used by singlediode to calculate an IV curve.
 
     Parameters
     ----------
-    poa_global : numeric
-        The irradiance (in W/m^2) absorbed by the module.
+    effective_irradiance : numeric
+        The irradiance (W/m2) that is converted to photocurrent.
 
     temp_cell : numeric
         The average cell temperature of cells within a module in C.
 
-    alpha_isc : float
+    alpha_sc : float
         The short-circuit current temperature coefficient of the
-        module in units of 1/C.
-
-    module_parameters : dict
-        Parameters describing PV module performance at reference
-        conditions according to DeSoto's paper. Parameters may be
-        generated or found by lookup. For ease of use,
-        retrieve_sam can automatically generate a dict based on the
-        most recent SAM CEC module
-        database. The module_parameters dict must contain the
-        following 5 fields:
-
-            * a_ref - modified diode ideality factor parameter at
-              reference conditions (units of eV), a_ref can be calculated
-              from the usual diode ideality factor (n),
-              number of cells in series (Ns),
-              and cell temperature (Tcell) per equation (2) in [1].
-            * I_L_ref - Light-generated current (or photocurrent)
-              in amperes at reference conditions. This value is referred to
-              as Iph in some literature.
-            * I_o_ref - diode reverse saturation current in amperes,
-              under reference conditions.
-            * R_sh_ref - shunt resistance under reference conditions (ohms).
-            * R_s - series resistance under reference conditions (ohms).
+        module in units of A/C.
+
+    a_ref : float
+        The product of the usual diode ideality factor (n, unitless), 
+        number of cells in series (Ns), and cell thermal voltage at reference
+        conditions, in units of V.
+
+    I_L_ref : float
+        The light-generated current (or photocurrent) at reference conditions,
+        in amperes.
+        
+    I_o_ref : float
+        The dark or diode reverse saturation current at reference conditions,
+        in amperes.
+        
+    R_sh_ref : float
+        The shunt resistance at reference conditions, in ohms.
+        
+    R_s : float
+        The series resistance at reference conditions, in ohms.
 
     EgRef : float
-        The energy bandgap at reference temperature (in eV).
-        1.121 eV for silicon. EgRef must be >0.
+        The energy bandgap at reference temperature in units of eV.
+        1.121 eV for crystalline silicon. EgRef must be >0.  For parameters 
+        from the SAM CEC module database, EgRef=1.121 is implicit for all
+        cell types in the parameter estimation algorithm used by NREL.
 
     dEgdT : float
-        The temperature dependence of the energy bandgap at SRC (in
-        1/C). May be either a scalar value (e.g. -0.0002677 as in [1])
-        or a DataFrame of dEgdT values corresponding to each input
-        condition (this may be useful if dEgdT is a function of
-        temperature).
-
-    M : numeric (optional, default=1)
-        An optional airmass modifier, if omitted, M is given a value of
-        1, which assumes absolute (pressure corrected) airmass = 1.5. In
-        this code, M is equal to M/Mref as described in [1] (i.e. Mref
-        is assumed to be 1). Source [1] suggests that an appropriate
-        value for M as a function absolute airmass (AMa) may be:
-
-        >>> M = np.polyval([-0.000126, 0.002816, -0.024459, 0.086257, 0.918093],
-        ...                AMa) # doctest: +SKIP
-
-        M may be a Series.
+        The temperature dependence of the energy bandgap at reference
+        conditions in units of 1/K. May be either a scalar value 
+        (e.g. -0.0002677 as in [1]) or a DataFrame (this may be useful if 
+        dEgdT is a modeled as a function of temperature). For parameters from
+        the SAM CEC module database, dEgdT=-0.0002677 is implicit for all cell
+        types in the parameter estimation algorithm used by NREL.
 
     irrad_ref : float (optional, default=1000)
         Reference irradiance in W/m^2.
@@ -1090,7 +1076,7 @@ def calcparams_desoto(poa_global, temp_cell, alpha_isc, module_parameters,
     and modifying the reference parameters (for irradiance, temperature,
     and airmass) per DeSoto's equations.
 
-     Silicon (Si):
+     Crystalline Silicon (Si):
          * EgRef = 1.121
          * dEgdT = -0.0002677
 
@@ -1134,26 +1120,54 @@ def calcparams_desoto(poa_global, temp_cell, alpha_isc, module_parameters,
          Source: [4]
     '''
 
-    M = np.maximum(M, 0)
-    a_ref = module_parameters['a_ref']
-    IL_ref = module_parameters['I_L_ref']
-    I0_ref = module_parameters['I_o_ref']
-    Rsh_ref = module_parameters['R_sh_ref']
-    Rs_ref = module_parameters['R_s']
-
+    # test for use of function pre-v0.6.0 API change
+    if isinstance(a_ref, dict) or \
+       (isinstance(a_ref, pd.Series) and ('a_ref' in a_ref.keys())):
+        import warnings
+        warnings.warn('module_parameters detected as fourth positional'
+                      + ' argument of calcparams_desoto. calcparams_desoto'
+                      + ' will require one argument for each module model'
+                      + ' parameter in v0.7.0 and later', DeprecationWarning)
+        try:
+            module_parameters = a_ref
+            a_ref = module_parameters['a_ref']
+            I_L_ref = module_parameters['I_L_ref']
+            I_o_ref = module_parameters['I_o_ref']
+            R_sh_ref = module_parameters['R_sh_ref']
+            R_s = module_parameters['R_s']
+        except Exception as e:
+            raise e('Module parameters could not be extracted from fourth'
+                    + ' positional argument of calcparams_desoto. Check that'
+                    + ' parameters are from the CEC database and/or update'
+                    + ' your code for the new API for calcparams_desoto')
+
+    # Boltzmann constant in eV/K
     k = 8.617332478e-05
+    
+    # reference temperature
     Tref_K = temp_ref + 273.15
     Tcell_K = temp_cell + 273.15
 
     E_g = EgRef * (1 + dEgdT*(Tcell_K - Tref_K))
 
     nNsVth = a_ref * (Tcell_K / Tref_K)
 
-    IL = (poa_global/irrad_ref) * M * (IL_ref + alpha_isc * (Tcell_K - Tref_K))
-    I0 = (I0_ref * ((Tcell_K / Tref_K) ** 3) *
+    # In the equation for IL, the single factor effective_irradiance is 
+    # used, in place of the product S*M in [1]. effective_irradiance is 
+    # equivalent to the product of S (irradiance reaching a module's cells) * 
+    # M (spectral adjustment factor) as described in [1].
+    IL = effective_irradiance / irrad_ref * \
+              (I_L_ref + alpha_sc * (Tcell_K - Tref_K))
+    I0 = (I_o_ref * ((Tcell_K / Tref_K) ** 3) *
           (np.exp(EgRef / (k*(Tref_K)) - (E_g / (k*(Tcell_K))))))
-    Rsh = Rsh_ref * (irrad_ref / poa_global)
-    Rs = Rs_ref
+    # Note that the equation for Rsh differs from [1]. In [1] Rsh is given as
+    # Rsh = Rsh_ref * (S_ref / S) where S is broadband irradiance reaching
+    # the module's cells. If desired this model behavior can be duplicated
+    # by applying reflection and soiling losses to broadband plane of array
+    # irradiance and not applying a spectral loss modifier, i.e., 
+    # spectral_modifier = 1.0.
+    Rsh = R_sh_ref * (irrad_ref / effective_irradiance)
+    Rs = R_s
 
     return IL, I0, Rs, Rsh, nNsVth
 
diff --git a/pvlib/test/test_pvsystem.py b/pvlib/test/test_pvsystem.py
@@ -358,13 +358,18 @@ def test_PVSystem_sapm_effective_irradiance(sapm_module_params):
 
 def test_calcparams_desoto(cec_module_params):
     times = pd.DatetimeIndex(start='2015-01-01', periods=2, freq='12H')
-    poa_data = pd.Series([0, 800], index=times)
+    effective_irradiance = pd.Series([0.0, 800.0], index=times)
+    temp_cell = pd.Series([25, 25], index=times)
 
     IL, I0, Rs, Rsh, nNsVth = pvsystem.calcparams_desoto(
-                                  poa_data,
-                                  temp_cell=25,
-                                  alpha_isc=cec_module_params['alpha_sc'],
-                                  module_parameters=cec_module_params,
+                                  effective_irradiance,
+                                  temp_cell,
+                                  alpha_sc=cec_module_params['alpha_sc'],
+                                  a_ref=cec_module_params['a_ref'],
+                                  I_L_ref=cec_module_params['I_L_ref'],
+                                  I_o_ref=cec_module_params['I_o_ref'],
+                                  R_sh_ref=cec_module_params['R_sh_ref'],
+                                  R_s=cec_module_params['R_s'],
                                   EgRef=1.121,
                                   dEgdT=-0.0002677)
 
@@ -382,10 +387,11 @@ def test_PVSystem_calcparams_desoto(cec_module_params):
     module_parameters['dEgdT'] = -0.0002677
     system = pvsystem.PVSystem(module_parameters=module_parameters)
     times = pd.DatetimeIndex(start='2015-01-01', periods=2, freq='12H')
-    poa_data = pd.Series([0, 800], index=times)
+    effective_irradiance = pd.Series([0.0, 800.0], index=times)
     temp_cell = 25
 
-    IL, I0, Rs, Rsh, nNsVth = system.calcparams_desoto(poa_data, temp_cell)
+    IL, I0, Rs, Rsh, nNsVth = system.calcparams_desoto(effective_irradiance,
+                                                       temp_cell)
 
     assert_series_equal(np.round(IL, 3), pd.Series([0.0, 6.036], index=times))
     # changed value in GH 444 for 2017-6-5 module file
@@ -639,14 +645,18 @@ def test_PVSystem_i_from_v():
 @requires_scipy
 def test_singlediode_series(cec_module_params):
     times = pd.DatetimeIndex(start='2015-01-01', periods=2, freq='12H')
-    poa_data = pd.Series([0, 800], index=times)
+    effective_irradiance = pd.Series([0.0, 800.0], index=times)
     IL, I0, Rs, Rsh, nNsVth = pvsystem.calcparams_desoto(
-                                         poa_data,
-                                         temp_cell=25,
-                                         alpha_isc=cec_module_params['alpha_sc'],
-                                         module_parameters=cec_module_params,
-                                         EgRef=1.121,
-                                         dEgdT=-0.0002677)
+                                          effective_irradiance,
+                                          temp_cell=25,
+                                          alpha_sc=cec_module_params['alpha_sc'],
+                                          a_ref=cec_module_params['a_ref'],
+                                          I_L_ref=cec_module_params['I_L_ref'],
+                                          I_o_ref=cec_module_params['I_o_ref'],
+                                          R_sh_ref=cec_module_params['R_sh_ref'],
+                                          R_s=cec_module_params['R_s'],
+                                          EgRef=1.121,
+                                          dEgdT=-0.0002677)
     out = pvsystem.singlediode(IL, I0, Rs, Rsh, nNsVth)
     assert isinstance(out, pd.DataFrame)
 
@@ -713,12 +723,18 @@ def test_singlediode_floats_ivcurve():
 @requires_scipy
 def test_singlediode_series_ivcurve(cec_module_params):
     times = pd.DatetimeIndex(start='2015-06-01', periods=3, freq='6H')
-    poa_data = pd.Series([0, 400, 800], index=times)
+    effective_irradiance = pd.Series([0.0, 400.0, 800.0], index=times)
     IL, I0, Rs, Rsh, nNsVth = pvsystem.calcparams_desoto(
-                                  poa_data, temp_cell=25,
-                                  alpha_isc=cec_module_params['alpha_sc'],
-                                  module_parameters=cec_module_params,
-                                  EgRef=1.121, dEgdT=-0.0002677)
+                                  effective_irradiance,
+                                  temp_cell=25,
+                                  alpha_sc=cec_module_params['alpha_sc'],
+                                  a_ref=cec_module_params['a_ref'],
+                                  I_L_ref=cec_module_params['I_L_ref'],
+                                  I_o_ref=cec_module_params['I_o_ref'],
+                                  R_sh_ref=cec_module_params['R_sh_ref'],
+                                  R_s=cec_module_params['R_s'],
+                                  EgRef=1.121,
+                                  dEgdT=-0.0002677)
 
     out = pvsystem.singlediode(IL, I0, Rs, Rsh, nNsVth, ivcurve_pnts=3)
 

Original file line number	Diff line number	Diff line change
`@@ -730,7 +730,7 @@`
`730`	`730`	`"name": "python",`
`731`	`731`	`"nbconvert_exporter": "python",`
`732`	`732`	`"pygments_lexer": "ipython3",`
`733`		`- "version": "3.6.1"`
	`733`	`+ "version": "3.6.4"`
`734`	`734`	`}`
`735`	`735`	`},`
`736`	`736`	`"nbformat": 4,`