ModelChain¶
The ModelChain
class provides a high-level interface for standardized PV modeling. The class aims to automate much of the modeling process while providing user-control and remaining extensible. This guide aims to build users’ understanding of the ModelChain class. It assumes some familiarity with object-oriented code in Python, but most information should be understandable even without a solid understanding of classes.
A ModelChain
is composed of a PVSystem
object and a Location
object. A PVSystem object represents an assembled collection of modules, inverters, etc., a Location object represents a particular place on the planet, and a ModelChain object describes the modeling chain used to calculate a system’s output at that location. The PVSystem and Location objects will be described in detail in another guide.
Modeling with a ModelChain
typically involves 3 steps:
- Creating the
ModelChain
. - Executing the
ModelChain.run_model()
method with prepared weather data. - Examining the model results that
run_model()
stored in attributes of theModelChain
.
A simple ModelChain example¶
Before delving into the intricacies of ModelChain, we provide a brief example of the modeling steps using ModelChain. First, we import pvlib’s objects, module data, and inverter data.
In [1]:
import pandas as pd
import numpy as np
# pvlib imports
import pvlib
from pvlib.pvsystem import PVSystem
from pvlib.location import Location
from pvlib.modelchain import ModelChain
# load some module and inverter specifications
sandia_modules = pvlib.pvsystem.retrieve_sam('SandiaMod')
cec_inverters = pvlib.pvsystem.retrieve_sam('cecinverter')
sandia_module = sandia_modules['Canadian_Solar_CS5P_220M___2009_']
cec_inverter = cec_inverters['ABB__MICRO_0_25_I_OUTD_US_208_208V__CEC_2014_']
Now we create a Location object, a PVSystem object, and a ModelChain object.
In [2]:
location = Location(latitude=32.2, longitude=-110.9)
system = PVSystem(surface_tilt=20, surface_azimuth=200,
module_parameters=sandia_module,
inverter_parameters=cec_inverter)
mc = ModelChain(system, location)
Printing a ModelChain object will display its models.
In [3]:
print(mc)
ModelChain:
name: None
orientation_strategy: None
clearsky_model: ineichen
transposition_model: haydavies
solar_position_method: nrel_numpy
airmass_model: kastenyoung1989
dc_model: sapm
ac_model: snlinverter
aoi_model: sapm_aoi_loss
spectral_model: sapm_spectral_loss
temp_model: sapm_temp
losses_model: no_extra_losses
Next, we run a model with some simple weather data.
In [4]:
weather = pd.DataFrame([[1050, 1000, 100, 30, 5]],
columns=['ghi', 'dni', 'dhi', 'temp_air', 'wind_speed'],
index=[pd.Timestamp('20170401 1200', tz='US/Arizona')])
mc.run_model(times=weather.index, weather=weather);
ModelChain stores the modeling results on a series of attributes. A few examples are shown below.
In [5]:
mc.aoi
Out[5]:
2017-04-01 12:00:00-07:00 15.929176
Name: aoi, dtype: float64
In [6]:
mc.dc
Out[6]:
i_sc | i_mp | v_oc | v_mp | p_mp | i_x | i_xx | |
---|---|---|---|---|---|---|---|
2017-04-01 12:00:00-07:00 | 5.485958 | 4.860317 | 52.319047 | 40.585752 | 197.259628 | 5.363079 | 3.401315 |
In [7]:
mc.ac
Out[7]:
2017-04-01 12:00:00-07:00 189.915445
dtype: float64
The remainder of this guide examines the ModelChain functionality and explores common pitfalls.
Defining a ModelChain¶
A ModelChain
object is defined by:
- The properties of its
PVSystem
andLocation
objects - The keyword arguments passed to it at construction
ModelChain uses the keyword arguments passed to it to determine the models for the simulation. The documentation describes the allowed values for each keyword argument. If a keyword argument is not supplied, ModelChain will attempt to infer the correct set of models by inspecting the Location and PVSystem attributes.
Below, we show some examples of how to define a ModelChain.
Let’s make the most basic Location and PVSystem objects and build from there.
In [8]:
location = Location(32.2, -110.9)
poorly_specified_system = PVSystem()
print(location)
print(poorly_specified_system)
Location:
name: None
latitude: 32.2
longitude: -110.9
altitude: 0
tz: UTC
PVSystem:
name: None
surface_tilt: 0
surface_azimuth: 180
module: None
inverter: None
albedo: 0.25
racking_model: open_rack_cell_glassback
These basic objects do not have enough information for ModelChain to be able to automatically determine its set of models, so the ModelChain will throw an error when we try to create it.
In [9]:
ModelChain(poorly_specified_system, location)
---------------------------------------------------------------------------
ValueError Traceback (most recent call last)
<ipython-input-9-9a298f22525b> in <module>()
----> 1 ModelChain(poorly_specified_system, location)
/home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/conda/v0.5.1/lib/python3.5/site-packages/pvlib-0.5.1-py3.5.egg/pvlib/modelchain.py in __init__(self, system, location, orientation_strategy, clearsky_model, transposition_model, solar_position_method, airmass_model, dc_model, ac_model, aoi_model, spectral_model, temp_model, losses_model, name, **kwargs)
316
317 # calls setters
--> 318 self.dc_model = dc_model
319 self.ac_model = ac_model
320 self.aoi_model = aoi_model
/home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/conda/v0.5.1/lib/python3.5/site-packages/pvlib-0.5.1-py3.5.egg/pvlib/modelchain.py in dc_model(self, model)
370 def dc_model(self, model):
371 if model is None:
--> 372 self._dc_model = self.infer_dc_model()
373 elif isinstance(model, str):
374 model = model.lower()
/home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/conda/v0.5.1/lib/python3.5/site-packages/pvlib-0.5.1-py3.5.egg/pvlib/modelchain.py in infer_dc_model(self)
393 return self.pvwatts_dc
394 else:
--> 395 raise ValueError('could not infer DC model from '
396 'system.module_parameters')
397
ValueError: could not infer DC model from system.module_parameters
If our goal is simply to get the object constructed, we can specify the models that the ModelChain should use. We’ll have to fill in missing data on the PVSystem object later, but maybe that’s desirable in some workflows.
In [10]:
mc = ModelChain(poorly_specified_system, location,
dc_model='singlediode', ac_model='snlinverter',
aoi_model='physical', spectral_model='no_loss')
print(mc)
ModelChain:
name: None
orientation_strategy: None
clearsky_model: ineichen
transposition_model: haydavies
solar_position_method: nrel_numpy
airmass_model: kastenyoung1989
dc_model: singlediode
ac_model: snlinverter
aoi_model: physical_aoi_loss
spectral_model: no_spectral_loss
temp_model: sapm_temp
losses_model: no_extra_losses
As expected, without additional information, the run_model()
method fails at run time.
In [11]:
mc.run_model(times=weather.index, weather=weather)
---------------------------------------------------------------------------
KeyError Traceback (most recent call last)
<ipython-input-11-0323535b081e> in <module>()
----> 1 mc.run_model(times=weather.index, weather=weather)
/home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/conda/v0.5.1/lib/python3.5/site-packages/pvlib-0.5.1-py3.5.egg/pvlib/modelchain.py in run_model(self, times, irradiance, weather)
851 self.effective_irradiance_model()
852 self.temp_model()
--> 853 self.dc_model()
854 self.ac_model()
855 self.losses_model()
/home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/conda/v0.5.1/lib/python3.5/site-packages/pvlib-0.5.1-py3.5.egg/pvlib/modelchain.py in singlediode(self)
408 resistance_shunt, nNsVth) = (
409 self.system.calcparams_desoto(self.effective_irradiance,
--> 410 self.temps['temp_cell']))
411
412 self.desoto = (photocurrent, saturation_current, resistance_series,
/home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/conda/v0.5.1/lib/python3.5/site-packages/pvlib-0.5.1-py3.5.egg/pvlib/pvsystem.py in calcparams_desoto(self, poa_global, temp_cell, **kwargs)
302 """
303 return calcparams_desoto(poa_global, temp_cell,
--> 304 self.module_parameters['alpha_sc'],
305 self.module_parameters,
306 self.module_parameters['EgRef'],
KeyError: 'alpha_sc'
The ModelChain attempted to execute the PVSystem object’s singlediode()
method, and the method failed because the object’s module_parameters
did not include the data necessary to run the model.
Next, we define a PVSystem with a module from the SAPM database and an inverter from the CEC database. ModelChain will examine the PVSystem object’s properties and determine that it should choose the SAPM DC model, AC model, AOI loss model, and spectral loss model.
In [12]:
sapm_system = PVSystem(module_parameters=sandia_module, inverter_parameters=cec_inverter)
mc = ModelChain(system, location)
print(mc)
ModelChain:
name: None
orientation_strategy: None
clearsky_model: ineichen
transposition_model: haydavies
solar_position_method: nrel_numpy
airmass_model: kastenyoung1989
dc_model: sapm
ac_model: snlinverter
aoi_model: sapm_aoi_loss
spectral_model: sapm_spectral_loss
temp_model: sapm_temp
losses_model: no_extra_losses
In [13]:
mc.run_model(times=weather.index, weather=weather)
mc.ac
Out[13]:
2017-04-01 12:00:00-07:00 189.915445
dtype: float64
Alternatively, we could have specified single diode or PVWatts related
information in the PVSystem construction. Here we pass PVWatts data to
the PVSystem. ModelChain will automatically determine that it should
choose PVWatts DC and AC models. ModelChain still needs us to specify
aoi_model
and spectral_model
keyword arguments because the
system.module_parameters
dictionary does not contain enough
information to determine which of those models to choose.
In [14]:
pvwatts_system = PVSystem(module_parameters={'pdc0': 240, 'gamma_pdc': -0.004})
mc = ModelChain(pvwatts_system, location,
aoi_model='physical', spectral_model='no_loss')
print(mc)
ModelChain:
name: None
orientation_strategy: None
clearsky_model: ineichen
transposition_model: haydavies
solar_position_method: nrel_numpy
airmass_model: kastenyoung1989
dc_model: pvwatts_dc
ac_model: pvwatts_inverter
aoi_model: physical_aoi_loss
spectral_model: no_spectral_loss
temp_model: sapm_temp
losses_model: no_extra_losses
In [15]:
mc.run_model(times=weather.index, weather=weather)
mc.ac
Out[15]:
2017-04-01 12:00:00-07:00 198.519999
dtype: float64
User-supplied keyword arguments override ModelChain’s inspection methods. For example, we can tell ModelChain to use different loss functions for a PVSystem that contains SAPM-specific parameters.
In [16]:
sapm_system = PVSystem(module_parameters=sandia_module, inverter_parameters=cec_inverter)
mc = ModelChain(system, location, aoi_model='physical', spectral_model='no_loss')
print(mc)
ModelChain:
name: None
orientation_strategy: None
clearsky_model: ineichen
transposition_model: haydavies
solar_position_method: nrel_numpy
airmass_model: kastenyoung1989
dc_model: sapm
ac_model: snlinverter
aoi_model: physical_aoi_loss
spectral_model: no_spectral_loss
temp_model: sapm_temp
losses_model: no_extra_losses
In [17]:
mc.run_model(times=weather.index, weather=weather)
mc.ac
Out[17]:
2017-04-01 12:00:00-07:00 191.991429
dtype: float64
Of course, these choices can also lead to failure when executing run_model()
if your system objects do not contain the required parameters for running the model.
Demystifying ModelChain internals¶
The ModelChain class has a lot going in inside it in order to make users’ code as simple as possible.
The key parts of ModelChain are:
1. The ModelChain.run_model()
method
1. A set of methods that wrap and call the PVSystem methods.
1. A set of methods that inspect user-supplied objects to determine the appropriate default models.
run_model¶
Most users will only interact with the run_model()
method. The run_model()
method, shown below, calls a series of methods to complete the modeling steps. The first method, prepare_inputs()
, computes parameters such as solar position, airmass, angle of incidence, and plane of array irradiance. The prepare_inputs()
method also assigns default values for irradiance (clear sky), temperature (20 C), and wind speed (0 m/s) if these inputs are not provided.
Next, run_model()
calls the wrapper methods for AOI loss, spectral loss, effective irradiance, cell temperature, DC power, AC power, and other losses. These methods are assigned to standard names, as described in the next section.
The methods called by run_model()
store their results in a series of ModelChain attributes: times
, solar_position
, airmass
, irradiance
, total_irrad
, effective_irradiance
, weather
, temps
, aoi
, aoi_modifier
, spectral_modifier
, dc
, ac
, losses
.
In [18]:
np.source(mc.run_model)
In file: /home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/conda/v0.5.1/lib/python3.5/site-packages/pvlib-0.5.1-py3.5.egg/pvlib/modelchain.py
def run_model(self, times=None, irradiance=None, weather=None):
"""
Run the model.
Parameters
----------
times : None or DatetimeIndex, default None
Times at which to evaluate the model. Can be None if
attribute `times` is already set.
irradiance : None or DataFrame
This parameter is deprecated. Please use `weather` instead.
weather : None or DataFrame, default None
If None, assumes air temperature is 20 C, wind speed is 0
m/s and irradiation calculated from clear sky data. Column
names must be 'wind_speed', 'temp_air', 'dni', 'ghi', 'dhi'.
Do not pass incomplete irradiation data. Use method
:py:meth:`~pvlib.modelchain.ModelChain.complete_irradiance`
instead.
Returns
-------
self
Assigns attributes: times, solar_position, airmass, irradiance,
total_irrad, effective_irradiance, weather, temps, aoi,
aoi_modifier, spectral_modifier, dc, ac, losses.
"""
self.prepare_inputs(times, irradiance, weather)
self.aoi_model()
self.spectral_model()
self.effective_irradiance_model()
self.temp_model()
self.dc_model()
self.ac_model()
self.losses_model()
return self
Finally, the complete_irradiance()
method is available for calculating the full set of GHI, DNI, or DHI if only two of these three series are provided. The completed dataset can then be passed to run_model()
.
Wrapping methods into a unified API¶
Readers may notice that the source code of the ModelChain.run_model
method is model-agnostic. ModelChain.run_model calls generic methods
such as self.dc_model
rather than a specific model such as
singlediode
. So how does the ModelChain.run_model know what models
it’s supposed to run? The answer comes in two parts, and allows us to
explore more of the ModelChain API along the way.
First, ModelChain has a set of methods that wrap the PVSystem methods
that perform the calculations (or further wrap the pvsystem.py module’s
functions). Each of these methods takes the same arguments (self
)
and sets the same attributes, thus creating a uniform API. For example,
the ModelChain.pvwatts_dc method is shown below. Its only argument is
self
, and it sets the dc
attribute.
In [19]:
np.source(mc.pvwatts_dc)
In file: /home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/conda/v0.5.1/lib/python3.5/site-packages/pvlib-0.5.1-py3.5.egg/pvlib/modelchain.py
def pvwatts_dc(self):
self.dc = self.system.pvwatts_dc(self.effective_irradiance,
self.temps['temp_cell'])
return self
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
result to the dc
attribute of the ModelChain object. The code below
shows a simple example of this.
In [20]:
# make the objects
pvwatts_system = PVSystem(module_parameters={'pdc0': 240, 'gamma_pdc': -0.004})
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')])
# run ModelChain.pvwatts_dc and look at the result
mc.pvwatts_dc()
mc.dc
Out[20]:
2017-04-01 12:00:00-07:00 216.0
dtype: float64
The ModelChain.sapm method works similarly to the ModelChain.pvwatts_dc
method. It calls the PVSystem.sapm method using stored data, then
assigns the result to the dc
attribute. The ModelChain.sapm method
differs from the ModelChain.pvwatts_dc method in three notable ways.
First, the PVSystem.sapm method expects different units for effective
irradiance, so ModelChain handles the conversion for us. Second, the
PVSystem.sapm method (and the PVSystem.singlediode method) returns a
DataFrame with current, voltage, and power parameters rather than a
simple Series of power. Finally, this current and voltage information
allows the SAPM and single diode model paths to support the concept of
modules in series and parallel, which is handled by the
PVSystem.scale_voltage_current_power method.
In [21]:
np.source(mc.sapm)
In file: /home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/conda/v0.5.1/lib/python3.5/site-packages/pvlib-0.5.1-py3.5.egg/pvlib/modelchain.py
def sapm(self):
self.dc = self.system.sapm(self.effective_irradiance/1000.,
self.temps['temp_cell'])
self.dc = self.system.scale_voltage_current_power(self.dc)
return self
In [22]:
# make the objects
sapm_system = PVSystem(module_parameters=sandia_module, inverter_parameters=cec_inverter)
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')])
# run ModelChain.sapm and look at the result
mc.sapm()
mc.dc
Out[22]:
i_sc | i_mp | v_oc | v_mp | p_mp | i_x | i_xx | |
---|---|---|---|---|---|---|---|
2017-04-01 12:00:00-07:00 | 5.14168 | 4.566863 | 53.8368 | 42.4284 | 193.764685 | 5.025377 | 3.219662 |
We’ve established that the ModelChain.pvwatts_dc
and
ModelChain.sapm
have the same API: they take the same arugments
(self
) and they both set the dc
attribute.* Because the methods
have the same API, we can call them in the same way. ModelChain includes
a large number of methods that perform the same API-unification roles
for each modeling step.
Again, so how does the ModelChain.run_model know which models it’s supposed to run?
At object construction, ModelChain assigns the desired model’s method
(e.g. ModelChain.pvwatts_dc
) to the corresponding generic attribute
(e.g. ModelChain.dc_model
) using a method described in the next
section.
In [23]:
pvwatts_system = PVSystem(module_parameters={'pdc0': 240, 'gamma_pdc': -0.004})
mc = ModelChain(pvwatts_system, location,
aoi_model='no_loss', spectral_model='no_loss')
mc.dc_model.__func__
Out[23]:
<function pvlib.modelchain.ModelChain.pvwatts_dc>
The ModelChain.run_model method can ignorantly call self.dc_module
because the API is the same for all methods that may be assigned to this
attribute.
* some readers may object that the API is not actually the same
because the type of the dc
attribute is different (Series vs.
DataFrame)!
Inferring models¶
How does ModelChain infer the appropriate model types? ModelChain uses a series of methods (ModelChain.infer_dc_model, ModelChain.infer_ac_model, etc.) that examine the user-supplied PVSystem object. The inference methods use set logic to assign one of the model-specific methods, such as ModelChain.sapm or ModelChain.snlinverter, to the universal method names ModelChain.dc_model and ModelChain.ac_model. A few examples are shown below.
In [24]:
np.source(mc.infer_dc_model)
In file: /home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/conda/v0.5.1/lib/python3.5/site-packages/pvlib-0.5.1-py3.5.egg/pvlib/modelchain.py
def infer_dc_model(self):
params = set(self.system.module_parameters.keys())
if set(['A0', 'A1', 'C7']) <= params:
return self.sapm
elif set(['a_ref', 'I_L_ref', 'I_o_ref', 'R_sh_ref', 'R_s']) <= params:
return self.singlediode
elif set(['pdc0', 'gamma_pdc']) <= params:
return self.pvwatts_dc
else:
raise ValueError('could not infer DC model from '
'system.module_parameters')
In [25]:
np.source(mc.infer_ac_model)
In file: /home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/conda/v0.5.1/lib/python3.5/site-packages/pvlib-0.5.1-py3.5.egg/pvlib/modelchain.py
def infer_ac_model(self):
inverter_params = set(self.system.inverter_parameters.keys())
module_params = set(self.system.module_parameters.keys())
if set(['C0', 'C1', 'C2']) <= inverter_params:
return self.snlinverter
elif set(['ADRCoefficients']) <= inverter_params:
return self.adrinverter
elif set(['pdc0']) <= module_params:
return self.pvwatts_inverter
else:
raise ValueError('could not infer AC model from '
'system.inverter_parameters')
User-defined models¶
Users may also write their own functions and pass them as arguments to ModelChain. The first argument of the function must be a ModelChain instance. For example, the functions below implement the PVUSA model and a wrapper function appropriate for use with ModelChain. This follows the pattern of implementing the core models using the simplest possible functions, and then implementing wrappers to make them easier to use in specific applications. Of course, you could implement it in a single function if you wanted to.
In [26]:
def pvusa(poa_global, wind_speed, temp_air, a, b, c, d):
"""
Calculates system power according to the PVUSA equation
P = I * (a + b*I + c*W + d*T)
where
P is the output power,
I is the plane of array irradiance,
W is the wind speed, and
T is the temperature
a, b, c, d are empirically derived parameters.
"""
return poa_global * (a + b*poa_global + c*wind_speed + d*temp_air)
def pvusa_mc_wrapper(mc):
# calculate the dc power and assign it to mc.dc
mc.dc = pvusa(mc.total_irrad['poa_global'], mc.weather['wind_speed'], mc.weather['temp_air'],
mc.system.module_parameters['a'], mc.system.module_parameters['b'],
mc.system.module_parameters['c'], mc.system.module_parameters['d'])
# returning mc is optional, but enables method chaining
return mc
def pvusa_ac_mc_wrapper(mc):
# keep it simple
mc.ac = mc.dc
return mc
In [27]:
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,
aoi_model='no_loss', spectral_model='no_loss')
A ModelChain object uses Python’s functools.partial function to assign itself as the argument to the user-supplied functions.
In [28]:
mc.dc_model.func
Out[28]:
<function __main__.pvusa_mc_wrapper>
The end result is that ModelChain.run_model works as expected!
In [29]:
mc.run_model(times=weather.index, weather=weather)
mc.dc
Out[29]:
2017-04-01 12:00:00-07:00 209.519752
dtype: float64