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
In [2]: import numpy as np
# pvlib imports
In [3]: import pvlib
In [4]: from pvlib.pvsystem import PVSystem
In [5]: from pvlib.location import Location
In [6]: from pvlib.modelchain import ModelChain
# load some module and inverter specifications
In [7]: sandia_modules = pvlib.pvsystem.retrieve_sam('SandiaMod')
In [8]: cec_inverters = pvlib.pvsystem.retrieve_sam('cecinverter')
In [9]: sandia_module = sandia_modules['Canadian_Solar_CS5P_220M___2009_']
In [10]: 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 [11]: location = Location(latitude=32.2, longitude=-110.9)
In [12]: system = PVSystem(surface_tilt=20, surface_azimuth=200,
....: module_parameters=sandia_module,
....: inverter_parameters=cec_inverter)
....:
In [13]: mc = ModelChain(system, location)
Printing a ModelChain object will display its models.
In [14]: 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 [15]: weather = pd.DataFrame([[1050, 1000, 100, 30, 5]],
....: columns=['ghi', 'dni', 'dhi', 'temp_air', 'wind_speed'],
....: index=[pd.Timestamp('20170401 1200', tz='US/Arizona')])
....:
In [16]: 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 [17]: mc.aoi
Out[17]:
2017-04-01 12:00:00-07:00 15.929176
Name: aoi, dtype: float64
In [18]: mc.dc
Out[18]:
i_sc i_mp ... i_x i_xx
2017-04-01 12:00:00-07:00 5.485958 4.860317 ... 5.363079 3.401315
[1 rows x 7 columns]
In [19]: mc.ac
Out[19]:
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 [20]: location = Location(32.2, -110.9)
In [21]: poorly_specified_system = PVSystem()
In [22]: print(location)
Location:
name: None
latitude: 32.2
longitude: -110.9
altitude: 0
tz: UTC
In [23]: print(poorly_specified_system)