Improve clarity of code in pvsyst_celltemp (names and doc)

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

@@ -101,3 +101,4 @@ Contributors
 * Cameron Stark (:ghuser:`camerontstark`)
 * Jonathan Gaffiot (:ghuser:`jgaffiot`)
 * Marc Anoma (:ghuser:`anomam`)
+* Anton Driesse (:ghuser:`adriesse`)

pvlib/pvsystem.py

@@ -46,7 +46,7 @@
 }
 
 
-TEMP_MODELS = {
+TEMP_MODEL_PARAMS = {
     'sapm': {'open_rack_cell_glassback': (-3.47, -.0594, 3),
              'roof_mount_cell_glassback': (-2.98, -.0471, 1),
              'open_rack_cell_polymerback': (-3.56, -.0750, 3),
@@ -536,7 +536,7 @@ def pvsyst_celltemp(self, poa_global, wind_speed, temp_air):
         kwargs = _build_kwargs(['eta_m', 'alpha_absorption'],
                                self.module_parameters)
         return pvsyst_celltemp(poa_global, wind_speed, temp_air,
-                               loss_factors=self.racking_model, **kwargs)
+                               model_params=self.racking_model, **kwargs)
 
     def first_solar_spectral_loss(self, pw, airmass_absolute):
 
@@ -1887,7 +1887,7 @@ def sapm_celltemp(poa_global, wind_speed, temp_air,
     sapm
     '''
 
-    temp_models = TEMP_MODELS['sapm']
+    temp_models = TEMP_MODEL_PARAMS['sapm']
 
     if isinstance(model, str):
         model = temp_models[model.lower()]
@@ -1908,33 +1908,36 @@ def sapm_celltemp(poa_global, wind_speed, temp_air,
     return pd.DataFrame({'temp_cell': temp_cell, 'temp_module': temp_module})
 
 
-def pvsyst_celltemp(poa_global, wind_speed, temp_air, eta_m=0.1,
-                    alpha_absorption=0.9, loss_factors="freestanding"):
+def pvsyst_celltemp(poa_global, temp_air, wind_speed=1.0, eta_m=0.1,
+                    alpha_absorption=0.9, model_params='freestanding'):
     """
     Calculate cell temperature using an emperical heat loss factor model
     as implemented in PVsyst.
 
-    The heat loss factors represent the combined effect of convection,
-    radiation and conduction, and their values are experimentally determined.
+    The heat loss factors provided through the 'model_params' argument
+    represent the combined effect of convection, radiation and conduction, 
+    and their values are experimentally determined.
 
     Parameters
     ----------
     poa_global : numeric
         Total incident irradiance in W/m^2.
 
-    wind_speed : numeric
-        Wind speed in m/s at a height of 10 meters.
-
     temp_air : numeric
         Ambient dry bulb temperature in degrees C.
 
+    wind_speed : numeric
+        Wind speed in m/s measured at the same height for which the wind loss 
+        factor was determined.  The default value is 1.0, which is the wind 
+        speed at module height used to determine NOCT.   (Sorry André!).
+
     eta_m : numeric
         Module external efficiency as a fraction, i.e., DC power / poa_global.
 
     alpha_absorption : float
         Absorption coefficient, default is 0.9.
 
-    loss_factors : string, tuple, or list, default 'freestanding' (no dict)
+    model_params : string, tuple, or list, default 'freestanding' (no dict)
         Heat loss factors to be used.
 
         If string, can be:
@@ -1949,8 +1952,8 @@ def pvsyst_celltemp(poa_global, wind_speed, temp_air, eta_m=0.1,
         If tuple/list, supply parameters in the following order:
 
             * constant_loss_factor : float
-                Combined heat loss factor coefficient. Freestanding default is 29,
-                fully insulated arrays is 15.
+                Combined heat loss factor coefficient. Freestanding 
+                default is 29, fully insulated arrays is 15.
 
             * wind_loss_factor : float
                 Combined heat loss factor influenced by wind. Default is 0.
@@ -1969,17 +1972,16 @@ def pvsyst_celltemp(poa_global, wind_speed, temp_air, eta_m=0.1,
     photovoltaic modules." Progress in Photovoltaics 16(4): 307-315.
     """
 
-    pvsyst_defaults = {"freestanding": (29.0, 0), "insulated": (15.0, 0)}
+    pvsyst_presets = TEMP_MODEL_PARAMS['pvsyst']
 
-    if isinstance(loss_factors, str):
-        constant_loss_factor, wind_loss_factor = pvsyst_defaults[
-            loss_factors.lower()
-        ]
-    elif isinstance(loss_factors, (tuple, list)):
-        constant_loss_factor, wind_loss_factor = loss_factors
+    if isinstance(model_params, str):
+        model_params = model_params.lower()
+        constant_loss_factor, wind_loss_factor = pvsyst_presets[model_params]
+    elif isinstance(model_params, (tuple, list)):
+        constant_loss_factor, wind_loss_factor = model_params
     else:
         raise TypeError(
-            "Please format loss_factors as a str, or tuple/list."
+            "Please provide model_params as a str, or tuple/list."
         )
 
     total_loss_factor = wind_loss_factor * wind_speed + constant_loss_factor

pvlib/test/test_pvsystem.py

@@ -1079,32 +1079,32 @@ def test_PVSystem_sapm_celltemp(mocker):
 
 
 def test_pvsyst_celltemp_default():
-    default = pvsystem.pvsyst_celltemp(900, 5, 20)
+    default = pvsystem.pvsyst_celltemp(900, 20, 5)
     assert_allclose(default, 45.137, 0.001)
 
 
 def test_pvsyst_celltemp_non_model():
-    tup_non_model = pvsystem.pvsyst_celltemp(900, 5, 20, 0.1,
-                                             loss_factors=(23.5, 6.25))
+    tup_non_model = pvsystem.pvsyst_celltemp(900, 20, 5, 0.1,
+                                             model_params=(23.5, 6.25))
     assert_allclose(tup_non_model, 33.315, 0.001)
 
-    list_non_model = pvsystem.pvsyst_celltemp(900, 5, 20, 0.1,
-                                              loss_factors=[26.5, 7.68])
+    list_non_model = pvsystem.pvsyst_celltemp(900, 20, 5, 0.1,
+                                              model_params=[26.5, 7.68])
     assert_allclose(list_non_model, 31.233, 0.001)
 
 
 def test_pvsyst_celltemp_model_wrong_type():
     with pytest.raises(TypeError):
         pvsystem.pvsyst_celltemp(
-            900, 5, 20, 0.1,
-            loss_factors={"won't": 23.5, "work": 7.68})
+            900, 20, 5, 0.1,
+            model_params={"won't": 23.5, "work": 7.68})
 
 
 def test_pvsyst_celltemp_model_non_option():
     with pytest.raises(KeyError):
         pvsystem.pvsyst_celltemp(
-            900, 5, 20, 0.1,
-            loss_factors="not_an_option")
+            900, 20, 5, 0.1,
+            model_params="not_an_option")
 
 
 def test_pvsyst_celltemp_with_index():
@@ -1113,7 +1113,7 @@ def test_pvsyst_celltemp_with_index():
     irrads = pd.Series([0, 500, 0], index=times)
     winds = pd.Series([10, 5, 0], index=times)
 
-    pvtemps = pvsystem.pvsyst_celltemp(irrads, winds, temps)
+    pvtemps = pvsystem.pvsyst_celltemp(irrads, temps, winds)
     expected = pd.Series([0.0, 23.96551, 5.0], index=times)
     assert_series_equal(expected, pvtemps)
 
@@ -1131,7 +1131,7 @@ def test_PVSystem_pvsyst_celltemp(mocker):
     irrad = 800
     temp = 45
     wind = 0.5
-    out = system.pvsyst_celltemp(irrad, wind, temp)
+    out = system.pvsyst_celltemp(irrad, temp, wind)
     pvsystem.pvsyst_celltemp.assert_called_once_with(
         irrad, wind, temp, eta_m, alpha_absorption, racking_model)
     assert isinstance(out, float)