move celltemp functions to celltemp.py, expose celltemp.pvsyst in ModelChain (#682)

* move celltemp functions to celltemp.py, fix docstring for pvsystem.PVSystem.sapm

* formatting

* formatting

* initial commit fit_cec_using_sam

* outline ivcurves

* use nrel-pysam

* remove sam_dir

* add Sandia single curve fit

* complete function

* add test, move code to ivtools.py

* remove single files

* fix mock

* add celltemp.pvsyst as a ModelChain option, change order of arguments in celltemp.samp

* lint

* argument order fixes

* another argument order fix

* another argument order fix, change model_params to model in celltemp.pvsyst

* more model_params to model cleanup

* pare back modelchain test

* put test back in to hit ModelChain.pvsyst_temp

* output dataframe from celltemp.pvsyst

* cleanup tests with pvsyst output as dataframe

* fix dataframe creation in celltemp.pvsyst

* fix type checking

* fix test condition

* update api, whatsnew

* comment responses

* change arguments for celltemp.sapm

* fix conflict

* fix kwarg error

* update whatsnew

* test fixes, table formatting

* docstring fixes

* edits to celltemp.pvsyst

* add PVsystem properties, move PVsystem tests back to test_pvsystem.py

* start working on ModelChain

* fix ModelChain tests

* modelchain fixes

* modelchain test fixes

* modelchain test fixes

* more modelchain test fixes

* add infer_temp_model

* lint, test fixes

* yet more modelchain test fixes

* update whatsnew, improve coverage

* fix deprecated test

* fix import

* one more MC test fix

* rename functions, change output type

* change argument names, add parameter_set lookup

* fix function names

* fix function names more

* update modelchain and tests

* more test fixes

* test fixes

* lint

* lint, merge master

* lint, remove pvwatts_dc_pvwatts_ac_system fixture from test_modelchain.py

* rename from celltemp to temperature

* lint, rename test_celltemp.py

* cleanup docstrings

* add invalid test for infer_temp_model

* review comments

* remove unrelated code

* handle deprecated attributes and functions

* test fixes

* fix documentation

* fix infer_temp_model naming, whatsnew

* test fixes and docstring edits

* handle ModelChain deprecated behavior, test type input of _translate functions

* test fixes

* fix tests

* another test fix

* pop unused kwarg

* improve test coverage

* test fixes

* add UserWarning

* improve warnings

* use property setter

* test fixes

* yet another code fix trying to distinguish kwargs from attribute of same name

* still struggling with tests

* reset system between ModelChain init

* infer parameters from racking, module_type

* add the missing colon

* delete vestigial lines

* test fixes

* fix tests, reformat whatsnew section

* test fix

* better handling of deprecated behavior, add consistency check temperature_model vs. temperature_model_parameters

* fix method check

* missing .

* update tests

* remove duplicate test value, clarify TODO comment

* consistent import of tools

* insert blank line

* remove parameter_set arg from PVSystem methods

* lint

Author: cwhanse

docs/sphinx/source/api.rst

@@ -221,6 +221,16 @@ AOI modifiers
    pvsystem.ashraeiam
    pvsystem.sapm_aoi_loss
 
+PV temperature models
+---------------------
+
+.. autosummary::
+   :toctree: generated/
+
+   temperature.sapm_cell
+   temperature.sapm_module
+   temperature.pvsyst_cell
+
 Single diode models
 -------------------
 
@@ -258,29 +268,31 @@ Functions relevant for the SAPM model.
 
    pvsystem.sapm
    pvsystem.sapm_effective_irradiance
-   pvsystem.sapm_celltemp
    pvsystem.sapm_spectral_loss
    pvsystem.sapm_aoi_loss
    pvsystem.snlinverter
+   temperature.sapm_cell
 
-PVWatts model
+Pvsyst model
 -------------
 
+Functions relevant for the Pvsyst model.
+
 .. autosummary::
    :toctree: generated/
 
-   pvsystem.pvwatts_dc
-   pvsystem.pvwatts_ac
-   pvsystem.pvwatts_losses
-   pvsystem.pvwatts_losses
+   temperature.pvsyst_cell
 
-PVsyst model
-------------
+PVWatts model
+-------------
 
 .. autosummary::
    :toctree: generated/
 
-   pvsystem.pvsyst_celltemp
+   pvsystem.pvwatts_dc
+   pvsystem.pvwatts_ac
+   pvsystem.pvwatts_losses
+   pvsystem.pvwatts_losses
 
 Other
 -----
@@ -472,7 +484,7 @@ ModelChain properties that are aliases for your specific modeling functions.
    modelchain.ModelChain.ac_model
    modelchain.ModelChain.aoi_model
    modelchain.ModelChain.spectral_model
-   modelchain.ModelChain.temp_model
+   modelchain.ModelChain.temperature_model
    modelchain.ModelChain.losses_model
    modelchain.ModelChain.effective_irradiance_model
 
@@ -500,6 +512,7 @@ ModelChain model definitions.
    modelchain.ModelChain.sapm_spectral_loss
    modelchain.ModelChain.no_spectral_loss
    modelchain.ModelChain.sapm_temp
+   modelchain.ModelChain.pvsyst_temp
    modelchain.ModelChain.pvwatts_losses
    modelchain.ModelChain.no_extra_losses
 
@@ -516,7 +529,7 @@ on the information in the associated :py:class:`~pvsystem.PVSystem` object.
    modelchain.ModelChain.infer_ac_model
    modelchain.ModelChain.infer_aoi_model
    modelchain.ModelChain.infer_spectral_model
-   modelchain.ModelChain.infer_temp_model
+   modelchain.ModelChain.infer_temperature_model
    modelchain.ModelChain.infer_losses_model
 
 Functions

docs/sphinx/source/clearsky.rst

@@ -68,7 +68,7 @@ returns a :py:class:`pandas.DataFrame`.
 
     In [1]: tus = Location(32.2, -111, 'US/Arizona', 700, 'Tucson')
 
-    In [1]: times = pd.DatetimeIndex(start='2016-07-01', end='2016-07-04', freq='1min', tz=tus.tz)
+    In [1]: times = pd.date_range(start='2016-07-01', end='2016-07-04', freq='1min', tz=tus.tz)
 
     In [1]: cs = tus.get_clearsky(times)  # ineichen with climatology table by default
 
@@ -168,7 +168,7 @@ varies from 300 m to 1500 m.
 
 .. ipython::
 
-    In [1]: times = pd.DatetimeIndex(start='2015-01-01', end='2016-01-01', freq='1D')
+    In [1]: times = pd.date_range(start='2015-01-01', end='2016-01-01', freq='1D')
 
     In [1]: sites = [(32, -111, 'Tucson1'), (32.2, -110.9, 'Tucson2'),
        ...:          (33.5, -112.1, 'Phoenix'), (35.1, -106.6, 'Albuquerque')]
@@ -608,7 +608,7 @@ GHI data. We first generate and plot the clear sky and measured data.
 
     abq = Location(35.04, -106.62, altitude=1619)
 
-    times = pd.DatetimeIndex(start='2012-04-01 10:30:00', tz='Etc/GMT+7', periods=30, freq='1min')
+    times = pd.date_range(start='2012-04-01 10:30:00', tz='Etc/GMT+7', periods=30, freq='1min')
 
     cs = abq.get_clearsky(times)
 

docs/sphinx/source/forecasts.rst

@@ -440,19 +440,18 @@ for details.
 .. ipython:: python
 
     from pvlib.pvsystem import PVSystem, retrieve_sam
+    from pvlib.temperature import TEMPERATURE_MODEL_PARAMETERS
     from pvlib.tracking import SingleAxisTracker
     from pvlib.modelchain import ModelChain
 
     sandia_modules = retrieve_sam('sandiamod')
     cec_inverters = retrieve_sam('cecinverter')
     module = sandia_modules['Canadian_Solar_CS5P_220M___2009_']
     inverter = cec_inverters['SMA_America__SC630CP_US_315V__CEC_2012_']
+    temperature_model_parameters = TEMPERATURE_MODEL_PARAMETERS['sapm']['open_rack_glass_glass']
 
     # model a big tracker for more fun
-    system = SingleAxisTracker(module_parameters=module,
-                               inverter_parameters=inverter,
-                               modules_per_string=15,
-                               strings_per_inverter=300)
+    system = SingleAxisTracker(module_parameters=module, inverter_parameters=inverter, temperature_model_parameters=temperature_model_parameters, modules_per_string=15, strings_per_inverter=300)
 
     # fx is a common abbreviation for forecast
     fx_model = GFS()
@@ -480,9 +479,9 @@ Here's the forecast plane of array irradiance...
 
 .. ipython:: python
 
-    mc.temps.plot();
+    mc.cell_temperature.plot();
     @savefig pv_temps.png width=6in
-    plt.ylabel('Temperature (C)');
+    plt.ylabel('Cell Temperature (C)');
     @suppress
     plt.close();
 

docs/sphinx/source/introexamples.rst

@@ -30,7 +30,7 @@ configuration at a handful of sites listed below.
     import pandas as pd
     import matplotlib.pyplot as plt
 
-    naive_times = pd.DatetimeIndex(start='2015', end='2016', freq='1h')
+    naive_times = pd.date_range(start='2015', end='2016', freq='1h')
 
     # very approximate
     # latitude, longitude, name, altitude, timezone
@@ -46,6 +46,7 @@ configuration at a handful of sites listed below.
     sapm_inverters = pvlib.pvsystem.retrieve_sam('cecinverter')
     module = sandia_modules['Canadian_Solar_CS5P_220M___2009_']
     inverter = sapm_inverters['ABB__MICRO_0_25_I_OUTD_US_208_208V__CEC_2014_']
+    temperature_model_parameters = pvlib.temperature.TEMPERATURE_MODEL_PARAMETERS['sapm']['open_rack_glass_glass']
 
     # specify constant ambient air temp and wind for simplicity
     temp_air = 20
@@ -88,12 +89,13 @@ to accomplish our system modeling goal:
                                                             cs['dni'], cs['ghi'], cs['dhi'],
                                                             dni_extra=dni_extra,
                                                             model='haydavies')
-        temps = pvlib.pvsystem.sapm_celltemp(total_irrad['poa_global'],
-                                             wind_speed, temp_air)
+        tcell = pvlib.temperature.sapm_cell(total_irrad['poa_global'],
+                                            temp_air, wind_speed,
+                                            **temperature_model_parameters)
         effective_irradiance = pvlib.pvsystem.sapm_effective_irradiance(
             total_irrad['poa_direct'], total_irrad['poa_diffuse'],
             am_abs, aoi, module)
-        dc = pvlib.pvsystem.sapm(effective_irradiance, temps['temp_cell'], module)
+        dc = pvlib.pvsystem.sapm(effective_irradiance, tcell, module)
         ac = pvlib.pvsystem.snlinverter(dc['v_mp'], dc['p_mp'], inverter)
         annual_energy = ac.sum()
         energies[name] = annual_energy
@@ -149,7 +151,8 @@ by examining the parameters defined for the module.
     from pvlib.modelchain import ModelChain
 
     system = PVSystem(module_parameters=module,
-                      inverter_parameters=inverter)
+                      inverter_parameters=inverter,
+                      temperature_model_parameters=temperature_model_parameters)
 
     energies = {}
     for latitude, longitude, name, altitude, timezone in coordinates:
@@ -214,6 +217,7 @@ modeling goal:
     for latitude, longitude, name, altitude, timezone in coordinates:
         localized_system = LocalizedPVSystem(module_parameters=module,
                                              inverter_parameters=inverter,
+                                             temperature_model_parameters=temperature_model_parameters,
                                              surface_tilt=latitude,
                                              surface_azimuth=180,
                                              latitude=latitude,
@@ -229,15 +233,15 @@ modeling goal:
                                                       clearsky['dni'],
                                                       clearsky['ghi'],
                                                       clearsky['dhi'])
-        temps = localized_system.sapm_celltemp(total_irrad['poa_global'],
-                                               wind_speed, temp_air)
+        tcell = localized_system.sapm_celltemp(total_irrad['poa_global'],
+                                               temp_air, wind_speed)
         aoi = localized_system.get_aoi(solar_position['apparent_zenith'],
                                        solar_position['azimuth'])
         airmass = localized_system.get_airmass(solar_position=solar_position)
         effective_irradiance = localized_system.sapm_effective_irradiance(
             total_irrad['poa_direct'], total_irrad['poa_diffuse'],
             airmass['airmass_absolute'], aoi)
-        dc = localized_system.sapm(effective_irradiance, temps['temp_cell'])
+        dc = localized_system.sapm(effective_irradiance, tcell)
         ac = localized_system.snlinverter(dc['v_mp'], dc['p_mp'])
         annual_energy = ac.sum()
         energies[name] = annual_energy

docs/sphinx/source/modelchain.rst

@@ -45,6 +45,8 @@ objects, module data, and inverter data.
     from pvlib.pvsystem import PVSystem
     from pvlib.location import Location
     from pvlib.modelchain import ModelChain
+    from pvlib.temperature import TEMPERATURE_MODEL_PARAMETERS
+    temperature_model_parameters = TEMPERATURE_MODEL_PARAMETERS['sapm']['open_rack_glass_glass']
 
     # load some module and inverter specifications
     sandia_modules = pvlib.pvsystem.retrieve_sam('SandiaMod')
@@ -61,7 +63,8 @@ object.
     location = Location(latitude=32.2, longitude=-110.9)
     system = PVSystem(surface_tilt=20, surface_azimuth=200,
                       module_parameters=sandia_module,
-                      inverter_parameters=cec_inverter)
+                      inverter_parameters=cec_inverter,
+                      temperature_model_parameters=temperature_model_parameters)
     mc = ModelChain(system, location)
 
 Printing a ModelChain object will display its models.
@@ -87,6 +90,10 @@ examples are shown below.
 
     mc.aoi
 
+.. ipython:: python
+
+    mc.cell_temperature
+
 .. ipython:: python
 
     mc.dc
@@ -141,8 +148,11 @@ model, AC model, AOI loss model, and spectral loss model.
 
 .. ipython:: python
 
-    sapm_system = PVSystem(module_parameters=sandia_module, inverter_parameters=cec_inverter)
-    mc = ModelChain(system, location)
+    sapm_system = PVSystem(
+        module_parameters=sandia_module,
+        inverter_parameters=cec_inverter,
+        temperature_model_parameters=temperature_model_parameters)
+    mc = ModelChain(sapm_system, location)
     print(mc)
 
 .. ipython:: python
@@ -160,7 +170,10 @@ information to determine which of those models to choose.
 
 .. ipython:: python
 
-    pvwatts_system = PVSystem(module_parameters={'pdc0': 240, 'gamma_pdc': -0.004})
+    pvwatts_system = PVSystem(
+        module_parameters={'pdc0': 240, 'gamma_pdc': -0.004},
+        inverter_parameters={'pdc0': 240},
+        temperature_model_parameters=temperature_model_parameters)
     mc = ModelChain(pvwatts_system, location,
                     aoi_model='physical', spectral_model='no_loss')
     print(mc)
@@ -176,8 +189,11 @@ functions for a PVSystem that contains SAPM-specific parameters.
 
 .. ipython:: python
 
-    sapm_system = PVSystem(module_parameters=sandia_module, inverter_parameters=cec_inverter)
-    mc = ModelChain(system, location, aoi_model='physical', spectral_model='no_loss')
+    sapm_system = PVSystem(
+        module_parameters=sandia_module,
+        inverter_parameters=cec_inverter,
+        temperature_model_parameters=temperature_model_parameters)
+    mc = ModelChain(sapm_system, location, aoi_model='physical', spectral_model='no_loss')
     print(mc)
 
 .. ipython:: python
@@ -264,21 +280,24 @@ the ModelChain.pvwatts_dc method is shown below. Its only argument is
 
 The ModelChain.pvwatts_dc method calls the pvwatts_dc method of the
 PVSystem object that we supplied using data that is stored in its own
-``effective_irradiance`` and ``temps`` attributes. Then it assigns the
+``effective_irradiance`` and ``cell_temperature`` attributes. Then it assigns the
 result to the ``dc`` attribute of the ModelChain object. The code below
 shows a simple example of this.
 
 .. ipython:: python
 
     # make the objects
-    pvwatts_system = PVSystem(module_parameters={'pdc0': 240, 'gamma_pdc': -0.004})
+    pvwatts_system = PVSystem(
+        module_parameters={'pdc0': 240, 'gamma_pdc': -0.004},
+        inverter_parameters={'pdc0': 240},
+        temperature_model_parameters=temperature_model_parameters)
     mc = ModelChain(pvwatts_system, location,
                     aoi_model='no_loss', spectral_model='no_loss')
 
     # manually assign data to the attributes that ModelChain.pvwatts_dc will need.
     # for standard workflows, run_model would assign these attributes.
     mc.effective_irradiance = pd.Series(1000, index=[pd.Timestamp('20170401 1200-0700')])
-    mc.temps = pd.DataFrame({'temp_cell': 50, 'temp_module': 50}, index=[pd.Timestamp('20170401 1200-0700')])
+    mc.cell_temperature = pd.Series(50, index=[pd.Timestamp('20170401 1200-0700')])
 
     # run ModelChain.pvwatts_dc and look at the result
     mc.pvwatts_dc();
@@ -304,13 +323,16 @@ PVSystem.scale_voltage_current_power method.
 .. ipython:: python
 
     # make the objects
-    sapm_system = PVSystem(module_parameters=sandia_module, inverter_parameters=cec_inverter)
+    sapm_system = PVSystem(
+        module_parameters=sandia_module,
+        inverter_parameters=cec_inverter,
+        temperature_model_parameters=temperature_model_parameters)
     mc = ModelChain(sapm_system, location)
 
     # manually assign data to the attributes that ModelChain.sapm will need.
     # for standard workflows, run_model would assign these attributes.
     mc.effective_irradiance = pd.Series(1000, index=[pd.Timestamp('20170401 1200-0700')])
-    mc.temps = pd.DataFrame({'temp_cell': 50, 'temp_module': 50}, index=[pd.Timestamp('20170401 1200-0700')])
+    mc.cell_temperature = pd.Series(50, index=[pd.Timestamp('20170401 1200-0700')])
 
     # run ModelChain.sapm and look at the result
     mc.sapm();
@@ -333,7 +355,10 @@ section.
 
 .. ipython:: python
 
-    pvwatts_system = PVSystem(module_parameters={'pdc0': 240, 'gamma_pdc': -0.004})
+    pvwatts_system = PVSystem(
+        module_parameters={'pdc0': 240, 'gamma_pdc': -0.004},
+        inverter_parameters={'pdc0': 240},
+        temperature_model_parameters=temperature_model_parameters)
     mc = ModelChain(pvwatts_system, location,
                     aoi_model='no_loss', spectral_model='no_loss')
     mc.dc_model.__func__
@@ -403,18 +428,26 @@ function if you wanted to.
         return mc
 
 
-    def pvusa_ac_mc_wrapper(mc):
+    def pvusa_ac_mc(mc):
         # keep it simple
         mc.ac = mc.dc
         return mc
 
+
+    def no_loss_temperature(mc):
+        # keep it simple
+        mc.cell_temperature = mc.weather['temp_air']
+        return mc
+
+
 .. ipython:: python
 
     module_parameters = {'a': 0.2, 'b': 0.00001, 'c': 0.001, 'd': -0.00005}
     pvusa_system = PVSystem(module_parameters=module_parameters)
 
     mc = ModelChain(pvusa_system, location,
-                    dc_model=pvusa_mc_wrapper, ac_model=pvusa_ac_mc_wrapper,
+                    dc_model=pvusa_mc_wrapper, ac_model=pvusa_ac_mc,
+                    temperature_model=no_loss_temperature,
                     aoi_model='no_loss', spectral_model='no_loss')
 
 A ModelChain object uses Python’s functools.partial function to assign