"""
The ``modelchain`` module contains functions and classes that combine
many of the PV power modeling steps. These tools make it easy to
get started with pvlib and demonstrate standard ways to use the
library. With great power comes great responsibility: users should take
the time to read the source code for the module.
"""
from functools import partial
import itertools
import warnings
import pandas as pd
from dataclasses import dataclass, field
from typing import Union, Tuple, Optional, TypeVar
from pvlib import pvsystem, iam
import pvlib.irradiance # avoid name conflict with full import
from pvlib.pvsystem import _DC_MODEL_PARAMS
from pvlib.tools import _build_kwargs
# keys that are used to detect input data and assign data to appropriate
# ModelChain attribute
# for ModelChain.weather
WEATHER_KEYS = ('ghi', 'dhi', 'dni', 'wind_speed', 'temp_air',
'precipitable_water')
# for ModelChain.total_irrad
POA_KEYS = ('poa_global', 'poa_direct', 'poa_diffuse')
# Optional keys to communicate temperature data. If provided,
# 'cell_temperature' overrides ModelChain.temperature_model and sets
# ModelChain.cell_temperature to the data. If 'module_temperature' is provdied,
# overrides ModelChain.temperature_model with
# pvlib.temperature.sapm_celL_from_module
TEMPERATURE_KEYS = ('module_temperature', 'cell_temperature')
DATA_KEYS = WEATHER_KEYS + POA_KEYS + TEMPERATURE_KEYS
# these dictionaries contain the default configuration for following
# established modeling sequences. They can be used in combination with
# ModelChain, particularly they are used by the methods
# ModelChain.with_pvwatts, ModelChain.with_sapm, etc.
# pvwatts documentation states that it uses the following reference for
# a temperature model: Fuentes, M. K. (1987). A Simplified Thermal Model
# for Flat-Plate Photovoltaic Arrays. SAND85-0330. Albuquerque, NM:
# Sandia National Laboratories. Accessed September 3, 2013:
# http://prod.sandia.gov/techlib/access-control.cgi/1985/850330.pdf
# pvlib python does not implement that model, so use the SAPM instead.
PVWATTS_CONFIG = dict(
dc_model='pvwatts', ac_model='pvwatts', losses_model='pvwatts',
transposition_model='perez', aoi_model='physical',
spectral_model='no_loss', temperature_model='sapm'
)
SAPM_CONFIG = dict(
dc_model='sapm', ac_model='sandia', losses_model='no_loss',
aoi_model='sapm', spectral_model='sapm', temperature_model='sapm'
)
[docs]
def get_orientation(strategy, **kwargs):
"""
Determine a PV system's surface tilt and surface azimuth
using a named strategy.
Parameters
----------
strategy: str
The orientation strategy.
Allowed strategies include 'flat', 'south_at_latitude_tilt'.
**kwargs:
Strategy-dependent keyword arguments. See code for details.
Returns
-------
surface_tilt, surface_azimuth
"""
if strategy == 'south_at_latitude_tilt':
surface_azimuth = 180
surface_tilt = kwargs['latitude']
elif strategy == 'flat':
surface_azimuth = 180
surface_tilt = 0
else:
raise ValueError('invalid orientation strategy. strategy must '
'be one of south_at_latitude, flat,')
return surface_tilt, surface_azimuth
def _getmcattr(self, attr):
"""
Helper for __repr__ methods, needed to avoid recursion in property
lookups
"""
out = getattr(self, attr)
try:
out = out.__name__
except AttributeError:
pass
return out
def _mcr_repr(obj):
'''
Helper for ModelChainResult.__repr__
'''
if isinstance(obj, tuple):
return "Tuple (" + ", ".join([_mcr_repr(o) for o in obj]) + ")"
if isinstance(obj, pd.DataFrame):
return "DataFrame ({} rows x {} columns)".format(*obj.shape)
if isinstance(obj, pd.Series):
return "Series (length {})".format(len(obj))
# scalar, None, other?
return repr(obj)
# Type for fields that vary between arrays
T = TypeVar('T')
PerArray = Union[T, Tuple[T, ...]]
[docs]
@dataclass
class ModelChainResult:
# these attributes are used in __setattr__ to determine the correct type.
_singleton_tuples: bool = field(default=False)
_per_array_fields = {'total_irrad', 'aoi', 'aoi_modifier',
'spectral_modifier', 'cell_temperature',
'effective_irradiance', 'dc', 'diode_params',
'dc_ohmic_losses', 'weather', 'albedo'}
# system-level information
solar_position: Optional[pd.DataFrame] = field(default=None)
"""Solar position in a DataFrame containing columns ``'apparent_zenith'``,
``'zenith'``, ``'apparent_elevation'``, ``'elevation'``, ``'azimuth'``
(all in degrees), with possibly other columns depending on the solar
position method; see :py:func:`~pvlib.solarposition.get_solarposition`
for details."""
airmass: Optional[pd.DataFrame] = field(default=None)
"""Air mass in a DataFrame containing columns ``'airmass_relative'``,
``'airmass_absolute'`` (unitless); see
:py:meth:`~pvlib.location.Location.get_airmass` for details."""
ac: Optional[pd.Series] = field(default=None)
"""AC power from the PV system, in a Series [W]"""
tracking: Optional[pd.DataFrame] = field(default=None)
"""Orientation of modules on a single axis tracker, in a DataFrame with
columns ``'surface_tilt'``, ``'surface_azimuth'``, ``'aoi'``; see
:py:func:`~pvlib.tracking.singleaxis` for details.
"""
losses: Optional[Union[pd.Series, float]] = field(default=None)
"""Series containing DC loss as a fraction of total DC power, as
calculated by ``ModelChain.losses_model``.
"""
# per DC array information
total_irrad: Optional[PerArray[pd.DataFrame]] = field(default=None)
""" DataFrame (or tuple of DataFrame, one for each array) containing
columns ``'poa_global'``, ``'poa_direct'`` ``'poa_diffuse'``,
``poa_sky_diffuse'``, ``'poa_ground_diffuse'`` (W/m2); see
:py:func:`~pvlib.irradiance.get_total_irradiance` for details.
"""
aoi: Optional[PerArray[pd.Series]] = field(default=None)
"""
Series (or tuple of Series, one for each array) containing angle of
incidence (degrees); see :py:func:`~pvlib.irradiance.aoi` for details.
"""
aoi_modifier: Optional[PerArray[Union[pd.Series, float]]] = \
field(default=None)
"""Series (or tuple of Series, one for each array) containing angle of
incidence modifier (unitless) calculated by ``ModelChain.aoi_model``,
which reduces direct irradiance for reflections;
see :py:meth:`~pvlib.pvsystem.PVSystem.get_iam` for details.
"""
spectral_modifier: Optional[PerArray[Union[pd.Series, float]]] = \
field(default=None)
"""Series (or tuple of Series, one for each array) containing spectral
modifier (unitless) calculated by ``ModelChain.spectral_model``, which
adjusts broadband plane-of-array irradiance for spectral content.
"""
cell_temperature: Optional[PerArray[pd.Series]] = field(default=None)
"""Series (or tuple of Series, one for each array) containing cell
temperature (C).
"""
effective_irradiance: Optional[PerArray[pd.Series]] = field(default=None)
"""Series (or tuple of Series, one for each array) containing effective
irradiance (W/m2) which is total plane-of-array irradiance adjusted for
reflections and spectral content.
"""
dc: Optional[PerArray[Union[pd.Series, pd.DataFrame]]] = \
field(default=None)
"""Series or DataFrame (or tuple of Series or DataFrame, one for
each array) containing DC power (W) for each array, calculated by
``ModelChain.dc_model``.
"""
diode_params: Optional[PerArray[pd.DataFrame]] = field(default=None)
"""DataFrame (or tuple of DataFrame, one for each array) containing diode
equation parameters (columns ``'I_L'``, ``'I_o'``, ``'R_s'``, ``'R_sh'``,
``'nNsVth'``, present when ModelChain.dc_model is a single diode model;
see :py:func:`~pvlib.pvsystem.singlediode` for details.
"""
dc_ohmic_losses: Optional[PerArray[pd.Series]] = field(default=None)
"""Series (or tuple of Series, one for each array) containing DC ohmic
loss (W) calculated by ``ModelChain.dc_ohmic_model``.
"""
# copies of input data, for user convenience
weather: Optional[PerArray[pd.DataFrame]] = None
"""DataFrame (or tuple of DataFrame, one for each array) contains a
copy of the input weather data.
"""
times: Optional[pd.DatetimeIndex] = None
"""DatetimeIndex containing a copy of the index of the input weather data.
"""
albedo: Optional[PerArray[pd.Series]] = None
"""Series (or tuple of Series, one for each array) containing albedo.
"""
def _result_type(self, value):
"""Coerce `value` to the correct type according to
``self._singleton_tuples``."""
# Allow None to pass through without being wrapped in a tuple
if (self._singleton_tuples
and not isinstance(value, tuple)
and value is not None):
return (value,)
return value
def __setattr__(self, key, value):
if key in ModelChainResult._per_array_fields:
value = self._result_type(value)
super().__setattr__(key, value)
def __repr__(self):
mc_attrs = dir(self)
def _head(obj):
try:
return obj[:3]
except:
return obj
if type(self.dc) is tuple:
num_arrays = len(self.dc)
else:
num_arrays = 1
desc1 = ('=== ModelChainResult === \n')
desc2 = (f'Number of Arrays: {num_arrays} \n')
attr = 'times'
desc3 = ('times (first 3)\n' +
f'{_head(_getmcattr(self, attr))}' +
'\n')
lines = []
for attr in mc_attrs:
if not (attr.startswith('_') or attr=='times'):
lines.append(f' {attr}: ' + _mcr_repr(getattr(self, attr)))
desc4 = '\n'.join(lines)
return (desc1 + desc2 + desc3 + desc4)
[docs]
class ModelChain:
"""
The ModelChain class to provides a standardized, high-level
interface for all of the modeling steps necessary for calculating PV
power from a time series of weather inputs. The same models are applied
to all ``pvsystem.Array`` objects, so each Array must contain the
appropriate model parameters. For example, if ``dc_model='pvwatts'``,
then each ``Array.module_parameters`` must contain ``'pdc0'``.
See :ref:`modelchaindoc` for examples.
Parameters
----------
system : PVSystem
A :py:class:`~pvlib.pvsystem.PVSystem` object that represents
the connected set of modules, inverters, etc.
location : Location
A :py:class:`~pvlib.location.Location` object that represents
the physical location at which to evaluate the model.
clearsky_model : str, default 'ineichen'
Passed to location.get_clearsky. Only used when DNI is not found in
the weather inputs.
transposition_model : str, default 'haydavies'
Passed to system.get_irradiance.
solar_position_method : str, default 'nrel_numpy'
Passed to location.get_solarposition.
airmass_model : str, default 'kastenyoung1989'
Passed to location.get_airmass.
dc_model : str, or function, optional
If not specified, the model will be inferred from the parameters that
are common to all of system.arrays[i].module_parameters.
Valid strings are 'sapm', 'desoto', 'cec', 'pvsyst', 'pvwatts'.
The ModelChain instance will be passed as the first argument
to a user-defined function.
ac_model : str, or function, optional
If not specified, the model will be inferred from the parameters that
are common to all of system.inverter_parameters.
Valid strings are 'sandia', 'adr', 'pvwatts'. The
ModelChain instance will be passed as the first argument to a
user-defined function.
aoi_model : str, or function, optional
If not specified, the model will be inferred from the parameters that
are common to all of system.arrays[i].module_parameters.
Valid strings are 'physical', 'ashrae', 'sapm', 'martin_ruiz',
'interp' and 'no_loss'. The ModelChain instance will be passed as the
first argument to a user-defined function.
spectral_model : str, or function, optional
If not specified, the model will be inferred from the parameters that
are common to all of system.arrays[i].module_parameters.
Valid strings are 'sapm', 'first_solar', 'no_loss'.
The ModelChain instance will be passed as the first argument to
a user-defined function.
temperature_model : str or function, optional
Valid strings are: 'sapm', 'pvsyst', 'faiman', 'fuentes', 'noct_sam'.
The ModelChain instance will be passed as the first argument to a
user-defined function.
dc_ohmic_model: str or function, default 'no_loss'
Valid strings are 'dc_ohms_from_percent', 'no_loss'. The ModelChain
instance will be passed as the first argument to a user-defined
function.
losses_model: str or function, default 'no_loss'
Valid strings are 'pvwatts', 'no_loss'. The ModelChain instance
will be passed as the first argument to a user-defined function.
name : str, optional
Name of ModelChain instance.
"""
[docs]
def __init__(self, system, location,
clearsky_model='ineichen',
transposition_model='haydavies',
solar_position_method='nrel_numpy',
airmass_model='kastenyoung1989',
dc_model=None, ac_model=None, aoi_model=None,
spectral_model=None, temperature_model=None,
dc_ohmic_model='no_loss',
losses_model='no_loss', name=None):
self.name = name
self.system = system
self.location = location
self.clearsky_model = clearsky_model
self.transposition_model = transposition_model
self.solar_position_method = solar_position_method
self.airmass_model = airmass_model
# calls setters
self.dc_model = dc_model
self.ac_model = ac_model
self.aoi_model = aoi_model
self.spectral_model = spectral_model
self.temperature_model = temperature_model
self.dc_ohmic_model = dc_ohmic_model
self.losses_model = losses_model
self.results = ModelChainResult()
[docs]
@classmethod
def with_pvwatts(cls, system, location,
clearsky_model='ineichen',
airmass_model='kastenyoung1989',
name=None,
**kwargs):
"""
ModelChain that follows the PVWatts methods.
Parameters
----------
system : PVSystem
A :py:class:`~pvlib.pvsystem.PVSystem` object that represents
the connected set of modules, inverters, etc.
location : Location
A :py:class:`~pvlib.location.Location` object that represents
the physical location at which to evaluate the model.
clearsky_model : str, default 'ineichen'
Passed to location.get_clearsky.
airmass_model : str, default 'kastenyoung1989'
Passed to location.get_airmass.
name : str, optional
Name of ModelChain instance.
**kwargs
Parameters supplied here are passed to the ModelChain
constructor and take precedence over the default
configuration.
Warning
-------
The PVWatts model defaults to 14 % total system losses. The PVWatts
losses are fractions of DC power and can be modified, as shown in the
example below.
Examples
--------
>>> from pvlib import temperature, pvsystem, location, modelchain
>>> module_parameters = dict(gamma_pdc=-0.003, pdc0=4500)
>>> inverter_parameters = dict(pdc0=4000)
>>> tparams = temperature.TEMPERATURE_MODEL_PARAMETERS['sapm']['open_rack_glass_glass']
>>> system = pvsystem.PVSystem(
>>> surface_tilt=30, surface_azimuth=180,
>>> module_parameters=module_parameters,
>>> inverter_parameters=inverter_parameters,
>>> temperature_model_parameters=tparams)
>>> loc = location.Location(32.2, -110.9)
>>> modelchain.ModelChain.with_pvwatts(system, loc)
The following example is a modification of the example above but where
custom losses have been specified.
>>> pvwatts_losses = {'soiling': 2, 'shading': 3, 'snow': 0, 'mismatch': 2,
>>> 'wiring': 2, 'connections': 0.5, 'lid': 1.5,
>>> 'nameplate_rating': 1, 'age': 0, 'availability': 30}
>>> system_with_custom_losses = pvsystem.PVSystem(
>>> surface_tilt=30, surface_azimuth=180,
>>> module_parameters=module_parameters,
>>> inverter_parameters=inverter_parameters,
>>> temperature_model_parameters=tparams,
>>> losses_parameters=pvwatts_losses)
>>> modelchain.ModelChain.with_pvwatts(system_with_custom_losses, loc)
ModelChain:
name: None
clearsky_model: ineichen
transposition_model: perez
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
temperature_model: sapm_temp
losses_model: pvwatts_losses
""" # noqa: E501
config = PVWATTS_CONFIG.copy()
config.update(kwargs)
return ModelChain(
system, location,
clearsky_model=clearsky_model,
airmass_model=airmass_model,
name=name,
**config
)
[docs]
@classmethod
def with_sapm(cls, system, location,
clearsky_model='ineichen',
transposition_model='haydavies',
solar_position_method='nrel_numpy',
airmass_model='kastenyoung1989',
name=None,
**kwargs):
"""
ModelChain that follows the Sandia Array Performance Model
(SAPM) methods.
Parameters
----------
system : PVSystem
A :py:class:`~pvlib.pvsystem.PVSystem` object that represents
the connected set of modules, inverters, etc.
location : Location
A :py:class:`~pvlib.location.Location` object that represents
the physical location at which to evaluate the model.
clearsky_model : str, default 'ineichen'
Passed to location.get_clearsky.
transposition_model : str, default 'haydavies'
Passed to system.get_irradiance.
solar_position_method : str, default 'nrel_numpy'
Passed to location.get_solarposition.
airmass_model : str, default 'kastenyoung1989'
Passed to location.get_airmass.
name : str, optional
Name of ModelChain instance.
**kwargs
Parameters supplied here are passed to the ModelChain
constructor and take precedence over the default
configuration.
Examples
--------
>>> mods = pvlib.pvsystem.retrieve_sam('sandiamod')
>>> invs = pvlib.pvsystem.retrieve_sam('cecinverter')
>>> module_parameters = mods['Canadian_Solar_CS5P_220M___2009_']
>>> inverter_parameters = invs['ABB__MICRO_0_25_I_OUTD_US_240__240V_']
>>> tparams = TEMPERATURE_MODEL_PARAMETERS['sapm']['open_rack_glass_glass']
>>> system = PVSystem(surface_tilt=30, surface_azimuth=180,
... module_parameters=module_parameters,
... inverter_parameters=inverter_parameters,
... temperature_model_parameters=tparams)
>>> location = Location(32.2, -110.9)
>>> ModelChain.with_sapm(system, location)
ModelChain:
name: 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
temperature_model: sapm_temp
losses_model: no_extra_losses
""" # noqa: E501
config = SAPM_CONFIG.copy()
config.update(kwargs)
return ModelChain(
system, location,
clearsky_model=clearsky_model,
transposition_model=transposition_model,
solar_position_method=solar_position_method,
airmass_model=airmass_model,
name=name,
**config
)
def __repr__(self):
attrs = [
'name', 'clearsky_model',
'transposition_model', 'solar_position_method',
'airmass_model', 'dc_model', 'ac_model', 'aoi_model',
'spectral_model', 'temperature_model', 'losses_model'
]
return ('ModelChain: \n ' + '\n '.join(
f'{attr}: {_getmcattr(self, attr)}' for attr in attrs))
@property
def dc_model(self):
return self._dc_model
@dc_model.setter
def dc_model(self, model):
# guess at model if None
if model is None:
self._dc_model, model = self.infer_dc_model()
# Set model and validate parameters
if isinstance(model, str):
model = model.lower()
if model in _DC_MODEL_PARAMS.keys():
# validate module parameters
module_parameters = tuple(
array.module_parameters for array in self.system.arrays)
missing_params = (
_DC_MODEL_PARAMS[model] - _common_keys(module_parameters))
if missing_params: # some parameters are not in module.keys()
raise ValueError(model + ' selected for the DC model but '
'one or more Arrays are missing '
'one or more required parameters '
' : ' + str(missing_params))
if model == 'sapm':
self._dc_model = self.sapm
elif model == 'desoto':
self._dc_model = self.desoto
elif model == 'cec':
self._dc_model = self.cec
elif model == 'pvsyst':
self._dc_model = self.pvsyst
elif model == 'pvwatts':
self._dc_model = self.pvwatts_dc
else:
raise ValueError(model + ' is not a valid DC power model')
else:
self._dc_model = partial(model, self)
[docs]
def infer_dc_model(self):
"""Infer DC power model from Array module parameters."""
params = _common_keys(
tuple(array.module_parameters for array in self.system.arrays))
if {'A0', 'A1', 'C7'} <= params:
return self.sapm, 'sapm'
elif {'a_ref', 'I_L_ref', 'I_o_ref', 'R_sh_ref', 'R_s',
'Adjust'} <= params:
return self.cec, 'cec'
elif {'a_ref', 'I_L_ref', 'I_o_ref', 'R_sh_ref', 'R_s'} <= params:
return self.desoto, 'desoto'
elif {'gamma_ref', 'mu_gamma', 'I_L_ref', 'I_o_ref', 'R_sh_ref',
'R_sh_0', 'R_sh_exp', 'R_s'} <= params:
return self.pvsyst, 'pvsyst'
elif {'pdc0', 'gamma_pdc'} <= params:
return self.pvwatts_dc, 'pvwatts'
else:
raise ValueError(
'Could not infer DC model from the module_parameters '
'attributes of system.arrays. Check the module_parameters '
'attributes or explicitly set the model with the dc_model '
'keyword argument.')
[docs]
def sapm(self):
dc = self.system.sapm(self.results.effective_irradiance,
self.results.cell_temperature)
self.results.dc = self.system.scale_voltage_current_power(dc)
return self
def _singlediode(self, calcparams_model_function):
def _make_diode_params(photocurrent, saturation_current,
resistance_series, resistance_shunt,
nNsVth):
return pd.DataFrame(
{'I_L': photocurrent, 'I_o': saturation_current,
'R_s': resistance_series, 'R_sh': resistance_shunt,
'nNsVth': nNsVth}
)
params = calcparams_model_function(self.results.effective_irradiance,
self.results.cell_temperature,
unwrap=False)
self.results.diode_params = tuple(itertools.starmap(
_make_diode_params, params))
self.results.dc = tuple(itertools.starmap(
self.system.singlediode, params))
self.results.dc = self.system.scale_voltage_current_power(
self.results.dc,
unwrap=False
)
self.results.dc = tuple(dc.fillna(0) for dc in self.results.dc)
# If the system has one Array, unwrap the single return value
# to preserve the original behavior of ModelChain
if self.system.num_arrays == 1:
self.results.diode_params = self.results.diode_params[0]
self.results.dc = self.results.dc[0]
return self
[docs]
def desoto(self):
return self._singlediode(self.system.calcparams_desoto)
[docs]
def cec(self):
return self._singlediode(self.system.calcparams_cec)
[docs]
def pvsyst(self):
return self._singlediode(self.system.calcparams_pvsyst)
[docs]
def pvwatts_dc(self):
"""Calculate DC power using the PVWatts model.
Results are stored in ModelChain.results.dc. DC power is computed
from PVSystem.arrays[i].module_parameters['pdc0'] and then scaled by
PVSystem.modules_per_string and PVSystem.strings_per_inverter.
Returns
-------
self
See also
--------
pvlib.pvsystem.PVSystem.pvwatts_dc
pvlib.pvsystem.PVSystem.scale_voltage_current_power
"""
dc = self.system.pvwatts_dc(
self.results.effective_irradiance,
self.results.cell_temperature,
unwrap=False
)
p_mp = tuple(pd.DataFrame(s, columns=['p_mp']) for s in dc)
scaled = self.system.scale_voltage_current_power(p_mp)
self.results.dc = _tuple_from_dfs(scaled, "p_mp")
return self
@property
def ac_model(self):
return self._ac_model
@ac_model.setter
def ac_model(self, model):
if model is None:
self._ac_model = self.infer_ac_model()
elif isinstance(model, str):
model = model.lower()
if model == 'sandia':
self._ac_model = self.sandia_inverter
elif model in 'adr':
self._ac_model = self.adr_inverter
elif model == 'pvwatts':
self._ac_model = self.pvwatts_inverter
else:
raise ValueError(model + ' is not a valid AC power model')
else:
self._ac_model = partial(model, self)
[docs]
def infer_ac_model(self):
"""Infer AC power model from system attributes."""
inverter_params = set(self.system.inverter_parameters.keys())
if _snl_params(inverter_params):
return self.sandia_inverter
if _adr_params(inverter_params):
if self.system.num_arrays > 1:
raise ValueError(
'The adr inverter function cannot be used for an inverter',
' with multiple MPPT inputs')
else:
return self.adr_inverter
if _pvwatts_params(inverter_params):
return self.pvwatts_inverter
raise ValueError('could not infer AC model from '
'system.inverter_parameters. Check '
'system.inverter_parameters or explicitly '
'set the model with the ac_model kwarg.')
[docs]
def sandia_inverter(self):
self.results.ac = self.system.get_ac(
'sandia',
_tuple_from_dfs(self.results.dc, 'p_mp'),
v_dc=_tuple_from_dfs(self.results.dc, 'v_mp')
)
return self
[docs]
def adr_inverter(self):
self.results.ac = self.system.get_ac(
'adr',
self.results.dc['p_mp'],
v_dc=self.results.dc['v_mp']
)
return self
[docs]
def pvwatts_inverter(self):
ac = self.system.get_ac('pvwatts', self.results.dc)
self.results.ac = ac.fillna(0)
return self
@property
def aoi_model(self):
return self._aoi_model
@aoi_model.setter
def aoi_model(self, model):
if model is None:
self._aoi_model = self.infer_aoi_model()
elif isinstance(model, str):
model = model.lower()
if model == 'ashrae':
self._aoi_model = self.ashrae_aoi_loss
elif model == 'physical':
self._aoi_model = self.physical_aoi_loss
elif model == 'sapm':
self._aoi_model = self.sapm_aoi_loss
elif model == 'martin_ruiz':
self._aoi_model = self.martin_ruiz_aoi_loss
elif model == 'interp':
self._aoi_model = self.interp_aoi_loss
elif model == 'no_loss':
self._aoi_model = self.no_aoi_loss
else:
raise ValueError(model + ' is not a valid aoi loss model')
else:
self._aoi_model = partial(model, self)
[docs]
def infer_aoi_model(self):
module_parameters = tuple(
array.module_parameters for array in self.system.arrays)
params = _common_keys(module_parameters)
if iam._IAM_MODEL_PARAMS['physical'] <= params:
return self.physical_aoi_loss
elif iam._IAM_MODEL_PARAMS['sapm'] <= params:
return self.sapm_aoi_loss
elif iam._IAM_MODEL_PARAMS['ashrae'] <= params:
return self.ashrae_aoi_loss
elif iam._IAM_MODEL_PARAMS['martin_ruiz'] <= params:
return self.martin_ruiz_aoi_loss
elif iam._IAM_MODEL_PARAMS['interp'] <= params:
return self.interp_aoi_loss
else:
raise ValueError('could not infer AOI model from '
'system.arrays[i].module_parameters. Check that '
'the module_parameters for all Arrays in '
'system.arrays contain parameters for the '
'physical, aoi, ashrae, martin_ruiz or interp '
'model; explicitly set the model with the '
'aoi_model kwarg; or set aoi_model="no_loss".')
[docs]
def ashrae_aoi_loss(self):
self.results.aoi_modifier = self.system.get_iam(
self.results.aoi,
iam_model='ashrae'
)
return self
[docs]
def physical_aoi_loss(self):
self.results.aoi_modifier = self.system.get_iam(
self.results.aoi,
iam_model='physical'
)
return self
[docs]
def sapm_aoi_loss(self):
self.results.aoi_modifier = self.system.get_iam(
self.results.aoi,
iam_model='sapm'
)
return self
[docs]
def martin_ruiz_aoi_loss(self):
self.results.aoi_modifier = self.system.get_iam(
self.results.aoi, iam_model='martin_ruiz'
)
return self
[docs]
def interp_aoi_loss(self):
self.results.aoi_modifier = self.system.get_iam(
self.results.aoi,
iam_model='interp'
)
return self
[docs]
def no_aoi_loss(self):
if self.system.num_arrays == 1:
self.results.aoi_modifier = 1.0
else:
self.results.aoi_modifier = (1.0,) * self.system.num_arrays
return self
@property
def spectral_model(self):
return self._spectral_model
@spectral_model.setter
def spectral_model(self, model):
if model is None:
self._spectral_model = self.infer_spectral_model()
elif isinstance(model, str):
model = model.lower()
if model == 'first_solar':
self._spectral_model = self.first_solar_spectral_loss
elif model == 'sapm':
self._spectral_model = self.sapm_spectral_loss
elif model == 'no_loss':
self._spectral_model = self.no_spectral_loss
else:
raise ValueError(model + ' is not a valid spectral loss model')
else:
self._spectral_model = partial(model, self)
[docs]
def infer_spectral_model(self):
"""Infer spectral model from system attributes."""
module_parameters = tuple(
array.module_parameters for array in self.system.arrays)
params = _common_keys(module_parameters)
if {'A4', 'A3', 'A2', 'A1', 'A0'} <= params:
return self.sapm_spectral_loss
elif ((('Technology' in params or
'Material' in params) and
(self.system._infer_cell_type() is not None)) or
'first_solar_spectral_coefficients' in params):
return self.first_solar_spectral_loss
else:
raise ValueError('could not infer spectral model from '
'system.arrays[i].module_parameters. Check that '
'the module_parameters for all Arrays in '
'system.arrays contain valid '
'first_solar_spectral_coefficients, a valid '
'Material or Technology value, or set '
'spectral_model="no_loss".')
[docs]
def first_solar_spectral_loss(self):
self.results.spectral_modifier = self.system.first_solar_spectral_loss(
_tuple_from_dfs(self.results.weather, 'precipitable_water'),
self.results.airmass['airmass_absolute']
)
return self
[docs]
def sapm_spectral_loss(self):
self.results.spectral_modifier = self.system.sapm_spectral_loss(
self.results.airmass['airmass_absolute']
)
return self
[docs]
def no_spectral_loss(self):
if self.system.num_arrays == 1:
self.results.spectral_modifier = 1
else:
self.results.spectral_modifier = (1,) * self.system.num_arrays
return self
@property
def temperature_model(self):
return self._temperature_model
@temperature_model.setter
def temperature_model(self, model):
if model is None:
self._temperature_model = self.infer_temperature_model()
elif isinstance(model, str):
model = model.lower()
if model == 'sapm':
self._temperature_model = self.sapm_temp
elif model == 'pvsyst':
self._temperature_model = self.pvsyst_temp
elif model == 'faiman':
self._temperature_model = self.faiman_temp
elif model == 'fuentes':
self._temperature_model = self.fuentes_temp
elif model == 'noct_sam':
self._temperature_model = self.noct_sam_temp
else:
raise ValueError(model + ' is not a valid temperature model')
# check system.temperature_model_parameters for consistency
name_from_params = self.infer_temperature_model().__name__
if self._temperature_model.__name__ != name_from_params:
common_params = _common_keys(tuple(
array.temperature_model_parameters
for array in self.system.arrays))
raise ValueError(
f'Temperature model {self._temperature_model.__name__} is '
f'inconsistent with PVSystem temperature model '
f'parameters. All Arrays in system.arrays must have '
f'consistent parameters. Common temperature model '
f'parameters: {common_params}'
)
else:
self._temperature_model = partial(model, self)
[docs]
def infer_temperature_model(self):
"""Infer temperature model from system attributes."""
temperature_model_parameters = tuple(
array.temperature_model_parameters for array in self.system.arrays)
params = _common_keys(temperature_model_parameters)
if {'a', 'b', 'deltaT'} <= params:
return self.sapm_temp
elif {'u_c', 'u_v'} <= params:
return self.pvsyst_temp
elif {'u0', 'u1'} <= params:
return self.faiman_temp
elif {'noct_installed'} <= params:
return self.fuentes_temp
elif {'noct', 'module_efficiency'} <= params:
return self.noct_sam_temp
else:
raise ValueError('Could not infer temperature model from '
'ModelChain.system. '
'If Arrays are used to construct the PVSystem, '
'check that all Arrays in '
'ModelChain.system.arrays '
'have parameters for the same temperature model. '
'If Arrays are not used, check that the PVSystem '
'attributes `racking_model` and `module_type` '
'are valid.')
def _set_celltemp(self, model):
"""Set self.results.cell_temperature using the given cell
temperature model.
Parameters
----------
model : str
A cell temperature model name to pass to
:py:meth:`pvlib.pvsystem.PVSystem.get_cell_temperature`.
Valid names are 'sapm', 'pvsyst', 'faiman', 'fuentes', 'noct_sam'
Returns
-------
self
"""
poa = _irrad_for_celltemp(self.results.total_irrad,
self.results.effective_irradiance)
temp_air = _tuple_from_dfs(self.results.weather, 'temp_air')
wind_speed = _tuple_from_dfs(self.results.weather, 'wind_speed')
kwargs = {}
if model == 'noct_sam':
kwargs['effective_irradiance'] = self.results.effective_irradiance
self.results.cell_temperature = self.system.get_cell_temperature(
poa, temp_air, wind_speed, model=model, **kwargs)
return self
[docs]
def sapm_temp(self):
return self._set_celltemp('sapm')
[docs]
def pvsyst_temp(self):
return self._set_celltemp('pvsyst')
[docs]
def faiman_temp(self):
return self._set_celltemp('faiman')
[docs]
def fuentes_temp(self):
return self._set_celltemp('fuentes')
[docs]
def noct_sam_temp(self):
return self._set_celltemp('noct_sam')
@property
def dc_ohmic_model(self):
return self._dc_ohmic_model
@dc_ohmic_model.setter
def dc_ohmic_model(self, model):
if isinstance(model, str):
model = model.lower()
if model == 'dc_ohms_from_percent':
self._dc_ohmic_model = self.dc_ohms_from_percent
elif model == 'no_loss':
self._dc_ohmic_model = self.no_dc_ohmic_loss
else:
raise ValueError(model + ' is not a valid losses model')
else:
self._dc_ohmic_model = partial(model, self)
[docs]
def dc_ohms_from_percent(self):
"""
Calculate time series of ohmic losses and apply those to the mpp power
output of the `dc_model` based on the pvsyst equivalent resistance
method. Uses a `dc_ohmic_percent` parameter in the `losses_parameters`
of the PVsystem.
"""
Rw = self.system.dc_ohms_from_percent()
if isinstance(self.results.dc, tuple):
self.results.dc_ohmic_losses = tuple(
pvsystem.dc_ohmic_losses(Rw, df['i_mp'])
for Rw, df in zip(Rw, self.results.dc)
)
for df, loss in zip(self.results.dc, self.results.dc_ohmic_losses):
df['p_mp'] = df['p_mp'] - loss
else:
self.results.dc_ohmic_losses = pvsystem.dc_ohmic_losses(
Rw, self.results.dc['i_mp']
)
self.results.dc['p_mp'] = (self.results.dc['p_mp']
- self.results.dc_ohmic_losses)
return self
[docs]
def no_dc_ohmic_loss(self):
return self
@property
def losses_model(self):
return self._losses_model
@losses_model.setter
def losses_model(self, model):
if model is None:
self._losses_model = self.infer_losses_model()
elif isinstance(model, str):
model = model.lower()
if model == 'pvwatts':
self._losses_model = self.pvwatts_losses
elif model == 'no_loss':
self._losses_model = self.no_extra_losses
else:
raise ValueError(model + ' is not a valid losses model')
else:
self._losses_model = partial(model, self)
[docs]
def infer_losses_model(self):
raise NotImplementedError
[docs]
def pvwatts_losses(self):
self.results.losses = (100 - self.system.pvwatts_losses()) / 100.
if isinstance(self.results.dc, tuple):
for dc in self.results.dc:
dc *= self.results.losses
else:
self.results.dc *= self.results.losses
return self
[docs]
def effective_irradiance_model(self):
def _eff_irrad(module_parameters, total_irrad, spect_mod, aoi_mod):
fd = module_parameters.get('FD', 1.)
return spect_mod * (total_irrad['poa_direct'] * aoi_mod +
fd * total_irrad['poa_diffuse'])
if isinstance(self.results.total_irrad, tuple):
self.results.effective_irradiance = tuple(
_eff_irrad(array.module_parameters, ti, sm, am) for
array, ti, sm, am in zip(
self.system.arrays, self.results.total_irrad,
self.results.spectral_modifier, self.results.aoi_modifier))
else:
self.results.effective_irradiance = _eff_irrad(
self.system.arrays[0].module_parameters,
self.results.total_irrad,
self.results.spectral_modifier,
self.results.aoi_modifier
)
return self
[docs]
def complete_irradiance(self, weather):
"""
Determine the missing irradiation columns. Only two of the
following data columns (dni, ghi, dhi) are needed to calculate
the missing data.
This function is not safe at the moment. Results can be too high
or negative. Please contribute and help to improve this function
on https://github.com/pvlib/pvlib-python
Parameters
----------
weather : DataFrame, or tuple or list of DataFrame
Column names must be ``'dni'``, ``'ghi'``, ``'dhi'``,
``'wind_speed'``, ``'temp_air'``. All irradiance components
are required. Air temperature of 20 C and wind speed
of 0 m/s will be added to the DataFrame if not provided.
If `weather` is a tuple it must be the same length as the number
of Arrays in the system and the indices for each DataFrame must
be the same.
Returns
-------
self
Raises
------
ValueError
if the number of dataframes in `weather` is not the same as the
number of Arrays in the system or if the indices of all elements
of `weather` are not the same.
Notes
-----
Assigns attributes to ``results``: ``times``, ``weather``
Examples
--------
This example does not work until the parameters `my_system`,
`my_location`, and `my_weather` are defined but shows the basic idea
how this method can be used.
>>> from pvlib.modelchain import ModelChain
>>> # my_weather containing 'dhi' and 'ghi'.
>>> mc = ModelChain(my_system, my_location) # doctest: +SKIP
>>> mc.complete_irradiance(my_weather) # doctest: +SKIP
>>> mc.run_model(mc.results.weather) # doctest: +SKIP
>>> # my_weather containing 'dhi', 'ghi' and 'dni'.
>>> mc = ModelChain(my_system, my_location) # doctest: +SKIP
>>> mc.run_model(my_weather) # doctest: +SKIP
"""
weather = _to_tuple(weather)
self._check_multiple_input(weather)
# Don't use ModelChain._assign_weather() here because it adds
# temperature and wind-speed columns which we do not need here.
self.results.weather = _copy(weather)
self._assign_times()
self.results.solar_position = self.location.get_solarposition(
self.results.times, method=self.solar_position_method)
# Calculate the irradiance using the component sum equations,
# if needed
if isinstance(weather, tuple):
for w in self.results.weather:
self._complete_irradiance(w)
else:
self._complete_irradiance(self.results.weather)
return self
def _complete_irradiance(self, weather):
icolumns = set(weather.columns)
wrn_txt = ("This function is not safe at the moment.\n" +
"Results can be too high or negative.\n" +
"Help to improve this function on github:\n" +
"https://github.com/pvlib/pvlib-python \n")
if {'ghi', 'dhi'} <= icolumns and 'dni' not in icolumns:
clearsky = self.location.get_clearsky(
weather.index, model=self.clearsky_model,
solar_position=self.results.solar_position)
complete_irrad_df = pvlib.irradiance.complete_irradiance(
solar_zenith=self.results.solar_position.zenith,
ghi=weather.ghi,
dhi=weather.dhi,
dni=None,
dni_clear=clearsky.dni)
weather.loc[:, 'dni'] = complete_irrad_df.dni
elif {'dni', 'dhi'} <= icolumns and 'ghi' not in icolumns:
warnings.warn(wrn_txt, UserWarning)
complete_irrad_df = pvlib.irradiance.complete_irradiance(
solar_zenith=self.results.solar_position.zenith,
ghi=None,
dhi=weather.dhi,
dni=weather.dni)
weather.loc[:, 'ghi'] = complete_irrad_df.ghi
elif {'dni', 'ghi'} <= icolumns and 'dhi' not in icolumns:
warnings.warn(wrn_txt, UserWarning)
complete_irrad_df = pvlib.irradiance.complete_irradiance(
solar_zenith=self.results.solar_position.zenith,
ghi=weather.ghi,
dhi=None,
dni=weather.dni)
weather.loc[:, 'dhi'] = complete_irrad_df.dhi
def _prep_inputs_solar_pos(self, weather):
"""
Assign solar position
"""
# build weather kwargs for solar position calculation
kwargs = _build_kwargs(['pressure', 'temp_air'],
weather[0] if isinstance(weather, tuple)
else weather)
try:
kwargs['temperature'] = kwargs.pop('temp_air')
except KeyError:
pass
self.results.solar_position = self.location.get_solarposition(
self.results.times, method=self.solar_position_method,
**kwargs)
return self
def _prep_inputs_albedo(self, weather):
"""
Get albedo from weather
"""
try:
self.results.albedo = _tuple_from_dfs(weather, 'albedo')
except KeyError:
self.results.albedo = tuple([
a.albedo for a in self.system.arrays])
return self
def _prep_inputs_airmass(self):
"""
Assign airmass
"""
self.results.airmass = self.location.get_airmass(
solar_position=self.results.solar_position,
model=self.airmass_model)
return self
def _prep_inputs_tracking(self):
"""
Calculate tracker position and AOI
"""
self.results.tracking = self.system.singleaxis(
self.results.solar_position['apparent_zenith'],
self.results.solar_position['azimuth'])
self.results.tracking['surface_tilt'] = (
self.results.tracking['surface_tilt']
.fillna(self.system.axis_tilt))
self.results.tracking['surface_azimuth'] = (
self.results.tracking['surface_azimuth']
.fillna(self.system.axis_azimuth))
self.results.aoi = self.results.tracking['aoi']
return self
def _prep_inputs_fixed(self):
"""
Calculate AOI for fixed tilt system
"""
self.results.aoi = self.system.get_aoi(
self.results.solar_position['apparent_zenith'],
self.results.solar_position['azimuth'])
return self
def _verify_df(self, data, required):
""" Checks data for column names in required
Parameters
----------
data : Dataframe
required : List of str
Raises
------
ValueError if any of required are not in data.columns.
"""
def _verify(data, index=None):
if not set(required) <= set(data.columns):
tuple_txt = "" if index is None else f"in element {index} "
raise ValueError(
"Incomplete input data. Data needs to contain "
f"{required}. Detected data {tuple_txt}contains: "
f"{list(data.columns)}")
if not isinstance(data, tuple):
_verify(data)
else:
for (i, array_data) in enumerate(data):
_verify(array_data, i)
def _configure_results(self, per_array_data):
"""Configure the type used for per-array fields in
ModelChainResult.
If ``per_array_data`` is True and the number of arrays in the
system is 1, then per-array results are stored as length-1
tuples. This overrides the PVSystem defaults of unpacking a 1
length tuple into a singleton.
Parameters
----------
per_array_data : bool
If input data is provided for each array, pass True. If a
single input data is provided for all arrays, pass False.
"""
self.results._singleton_tuples = (
self.system.num_arrays == 1 and per_array_data
)
def _assign_weather(self, data):
def _build_weather(data):
key_list = [k for k in WEATHER_KEYS if k in data]
weather = data[key_list].copy()
if weather.get('wind_speed') is None:
weather['wind_speed'] = 0
if weather.get('temp_air') is None:
weather['temp_air'] = 20
return weather
if isinstance(data, tuple):
weather = tuple(_build_weather(wx) for wx in data)
self._configure_results(per_array_data=True)
else:
weather = _build_weather(data)
self._configure_results(per_array_data=False)
self.results.weather = weather
self._assign_times()
return self
def _assign_total_irrad(self, data):
def _build_irrad(data):
key_list = [k for k in POA_KEYS if k in data]
return data[key_list].copy()
if isinstance(data, tuple):
self.results.total_irrad = tuple(
_build_irrad(irrad_data) for irrad_data in data
)
return self
self.results.total_irrad = _build_irrad(data)
return self
def _assign_times(self):
"""Assign self.results.times according the index of
self.results.weather.
If there are multiple DataFrames in self.results.weather then
the index of the first one is assigned. It is assumed that the
indices of each DataFrame in self.results.weather are the same.
This can be verified by calling :py:func:`_all_same_index` or
:py:meth:`self._check_multiple_weather` before calling this
method.
"""
if isinstance(self.results.weather, tuple):
self.results.times = self.results.weather[0].index
else:
self.results.times = self.results.weather.index
def _check_multiple_input(self, data, strict=True):
"""Check that the number of elements in `data` is the same as
the number of Arrays in `self.system`.
In most cases if ``self.system.num_arrays`` is greater than 1 we
want to raise an error when `data` is not a tuple; however, that
behavior can be suppressed by setting ``strict=False``. This is
useful for validating inputs such as GHI, DHI, DNI, wind speed, or
air temperature that can be applied a ``PVSystem`` as a system-wide
input. In this case we want to ensure that when a tuple is provided
it has the same length as the number of Arrays, but we do not want
to fail if the input is not a tuple.
"""
if (not strict or self.system.num_arrays == 1) \
and not isinstance(data, tuple):
return
if strict and not isinstance(data, tuple):
raise TypeError("Input must be a tuple of length "
f"{self.system.num_arrays}, "
f"got {type(data).__name__}.")
if len(data) != self.system.num_arrays:
raise ValueError("Input must be same length as number of Arrays "
f"in system. Expected {self.system.num_arrays}, "
f"got {len(data)}.")
_all_same_index(data)
def _get_cell_temperature(self, data,
poa, temperature_model_parameters):
"""Extract the cell temperature data from a DataFrame.
If 'cell_temperature' column exists in data then it is returned. If
'module_temperature' column exists in data, then it is used with poa to
calculate the cell temperature. If neither column exists then None is
returned.
Parameters
----------
data : DataFrame (not a tuple of DataFrame)
poa : Series (not a tuple of Series)
Returns
-------
Series
"""
if 'cell_temperature' in data:
return data['cell_temperature']
# cell_temperature is not in input. Calculate cell_temperature using
# a temperature_model.
# If module_temperature is in input data we can use the SAPM cell
# temperature model.
if (('module_temperature' in data) and
(self.temperature_model == self.sapm_temp)):
# use SAPM cell temperature model only
return pvlib.temperature.sapm_cell_from_module(
module_temperature=data['module_temperature'],
poa_global=poa,
deltaT=temperature_model_parameters['deltaT'])
def _prepare_temperature_single_array(self, data, poa):
"""Set cell_temperature using a single data frame."""
self.results.cell_temperature = self._get_cell_temperature(
data,
poa,
self.system.arrays[0].temperature_model_parameters
)
if self.results.cell_temperature is None:
self.temperature_model()
return self
def _prepare_temperature(self, data):
"""
Sets cell_temperature using inputs in data and the specified
temperature model.
If 'data' contains 'cell_temperature', these values are assigned to
attribute ``cell_temperature``. If 'data' contains 'module_temperature`
and `temperature_model' is 'sapm', cell temperature is calculated using
:py:func:`pvlib.temperature.sapm_cell_from_module`. Otherwise, cell
temperature is calculated by 'temperature_model'.
Parameters
----------
data : DataFrame
May contain columns ``'cell_temperature'`` or
``'module_temperaure'``.
Returns
-------
self
Assigns attribute ``results.cell_temperature``.
"""
poa = _irrad_for_celltemp(self.results.total_irrad,
self.results.effective_irradiance)
# handle simple case first, single array, data not iterable
if not isinstance(data, tuple) and self.system.num_arrays == 1:
return self._prepare_temperature_single_array(data, poa)
if not isinstance(data, tuple):
# broadcast data to all arrays
data = (data,) * self.system.num_arrays
# data is tuple, so temperature_model_parameters must also be
# tuple. system.temperature_model_parameters is reduced to a dict
# if system.num_arrays == 1, so manually access parameters. GH 1192
t_mod_params = tuple(array.temperature_model_parameters
for array in self.system.arrays)
# find where cell or module temperature is specified in input data
given_cell_temperature = tuple(itertools.starmap(
self._get_cell_temperature, zip(data, poa, t_mod_params)
))
# If cell temperature has been specified for all arrays return
# immediately and do not try to compute it.
if all(cell_temp is not None for cell_temp in given_cell_temperature):
self.results.cell_temperature = given_cell_temperature
return self
# Calculate cell temperature from weather data. If cell_temperature
# has not been provided for some arrays then it is computed.
self.temperature_model()
# replace calculated cell temperature with temperature given in `data`
# where available.
self.results.cell_temperature = tuple(
itertools.starmap(
lambda given, modeled: modeled if given is None else given,
zip(given_cell_temperature, self.results.cell_temperature)
)
)
return self
[docs]
def run_model(self, weather):
"""
Run the model chain starting with broadband global, diffuse and/or
direct irradiance.
Parameters
----------
weather : DataFrame, or tuple or list of DataFrame
Column names must include:
- ``'dni'``
- ``'ghi'``
- ``'dhi'``
Optional columns are:
- ``'temp_air'``
- ``'cell_temperature'``
- ``'module_temperature'``
- ``'wind_speed'``
- ``'albedo'``
If optional columns ``'temp_air'`` and ``'wind_speed'``
are not provided, air temperature of 20 C and wind speed of 0 m/s
are added to the DataFrame. If optional column
``'cell_temperature'`` is provided, these values are used instead
of `temperature_model`. If optional column ``'module_temperature'``
is provided, ``temperature_model`` must be ``'sapm'``.
If optional column ``'albedo'`` is provided, ``'albedo'`` may not
be present on the ModelChain's PVSystem.Arrays.
If weather is a list or tuple, it must be of the same length and
order as the Arrays of the ModelChain's PVSystem.
Returns
-------
self
Raises
------
ValueError
If the number of DataFrames in `data` is different than the number
of Arrays in the PVSystem.
ValueError
If the DataFrames in `data` have different indexes.
Notes
-----
Assigns attributes to ``results``: ``times``, ``weather``,
``solar_position``, ``airmass``, ``total_irrad``, ``aoi``,
``aoi_modifier``, ``spectral_modifier``, and
``effective_irradiance``, ``cell_temperature``, ``dc``, ``ac``,
``losses``, ``diode_params`` (if dc_model is a single diode
model).
See also
--------
pvlib.modelchain.ModelChain.run_model_from_poa
pvlib.modelchain.ModelChain.run_model_from_effective_irradiance
"""
weather = _to_tuple(weather)
self.prepare_inputs(weather)
self.aoi_model()
self.spectral_model()
self.effective_irradiance_model()
self._run_from_effective_irrad(weather)
return self
[docs]
def run_model_from_poa(self, data):
"""
Run the model starting with broadband irradiance in the plane of array.
Data must include direct, diffuse and total irradiance (W/m2) in the
plane of array. Reflections and spectral adjustments are made to
calculate effective irradiance (W/m2).
Parameters
----------
data : DataFrame, or tuple or list of DataFrame
Required column names include ``'poa_global'``,
``'poa_direct'`` and ``'poa_diffuse'``. If optional columns
``'temp_air'`` and ``'wind_speed'`` are not provided, air
temperature of 20 C and wind speed of 0 m/s are assumed.
If optional column ``'cell_temperature'`` is provided, these values
are used instead of `temperature_model`. If optional column
``'module_temperature'`` is provided, `temperature_model` must be
``'sapm'``.
If the ModelChain's PVSystem has multiple arrays, `data` must be a
list or tuple with the same length and order as the PVsystem's
Arrays. Each element of `data` provides the irradiance and weather
for the corresponding array.
Returns
-------
self
Raises
------
ValueError
If the number of DataFrames in `data` is different than the number
of Arrays in the PVSystem.
ValueError
If the DataFrames in `data` have different indexes.
Notes
-----
Assigns attributes to results: ``times``, ``weather``,
``solar_position``, ``airmass``, ``total_irrad``, ``aoi``,
``aoi_modifier``, ``spectral_modifier``, and
``effective_irradiance``, ``cell_temperature``, ``dc``, ``ac``,
``losses``, ``diode_params`` (if dc_model is a single diode
model).
See also
--------
pvlib.modelchain.ModelChain.run_model
pvlib.modelchain.ModelChain.run_model_from_effective_irradiance
"""
data = _to_tuple(data)
self.prepare_inputs_from_poa(data)
self.aoi_model()
self.spectral_model()
self.effective_irradiance_model()
self._run_from_effective_irrad(data)
return self
def _run_from_effective_irrad(self, data):
"""
Executes the temperature, DC, losses and AC models.
Parameters
----------
data : DataFrame, or tuple of DataFrame
If optional column ``'cell_temperature'`` is provided, these values
are used instead of `temperature_model`. If optional column
`module_temperature` is provided, `temperature_model` must be
``'sapm'``.
Returns
-------
self
Notes
-----
Assigns attributes:``cell_temperature``, ``dc``, ``ac``, ``losses``,
``diode_params`` (if dc_model is a single diode model).
"""
self._prepare_temperature(data)
self.dc_model()
self.dc_ohmic_model()
self.losses_model()
self.ac_model()
return self
[docs]
def run_model_from_effective_irradiance(self, data):
"""
Run the model starting with effective irradiance in the plane of array.
Effective irradiance is irradiance in the plane-of-array after any
adjustments for soiling, reflections and spectrum.
Parameters
----------
data : DataFrame, or list or tuple of DataFrame
Required column is ``'effective_irradiance'``.
Optional columns include ``'cell_temperature'``,
``'module_temperature'`` and ``'poa_global'``.
If the ModelChain's PVSystem has multiple arrays, `data` must be a
list or tuple with the same length and order as the PVsystem's
Arrays. Each element of `data` provides the irradiance and weather
for the corresponding array.
Returns
-------
self
Raises
------
ValueError
If the number of DataFrames in `data` is different than the number
of Arrays in the PVSystem.
ValueError
If the DataFrames in `data` have different indexes.
Notes
-----
Optional ``data`` columns ``'cell_temperature'``,
``'module_temperature'`` and ``'poa_global'`` are used for determining
cell temperature.
* If optional column ``'cell_temperature'`` is present, these values
are used and `temperature_model` is ignored.
* If optional column ``'module_temperature'`` is preset,
`temperature_model` must be ``'sapm'``.
* Otherwise, cell temperature is calculated using `temperature_model`.
The cell temperature models require plane-of-array irradiance as input.
If optional column ``'poa_global'`` is present, these data are used.
If ``'poa_global'`` is not present, ``'effective_irradiance'`` is used.
Assigns attributes to results: ``times``, ``weather``, ``total_irrad``,
``effective_irradiance``, ``cell_temperature``, ``dc``, ``ac``,
``losses``, ``diode_params`` (if dc_model is a single diode model).
See also
--------
pvlib.modelchain.ModelChain.run_model
pvlib.modelchain.ModelChain.run_model_from_poa
"""
data = _to_tuple(data)
self._check_multiple_input(data)
self._verify_df(data, required=['effective_irradiance'])
self._assign_weather(data)
self._assign_total_irrad(data)
self.results.effective_irradiance = _tuple_from_dfs(
data, 'effective_irradiance')
self._run_from_effective_irrad(data)
return self
def _irrad_for_celltemp(total_irrad, effective_irradiance):
"""
Determine irradiance to use for cell temperature models, in order
of preference 'poa_global' then 'effective_irradiance'
Returns
-------
Series or tuple of Series
tuple if total_irrad is a tuple of DataFrame
"""
if isinstance(total_irrad, tuple):
if all('poa_global' in df for df in total_irrad):
return _tuple_from_dfs(total_irrad, 'poa_global')
else:
return effective_irradiance
else:
if 'poa_global' in total_irrad:
return total_irrad['poa_global']
else:
return effective_irradiance
def _snl_params(inverter_params):
"""Return True if `inverter_params` includes parameters for the
Sandia inverter model."""
return {'C0', 'C1', 'C2'} <= inverter_params
def _adr_params(inverter_params):
"""Return True if `inverter_params` includes parameters for the ADR
inverter model."""
return {'ADRCoefficients'} <= inverter_params
def _pvwatts_params(inverter_params):
"""Return True if `inverter_params` includes parameters for the
PVWatts inverter model."""
return {'pdc0'} <= inverter_params
def _copy(data):
"""Return a copy of each DataFrame in `data` if it is a tuple,
otherwise return a copy of `data`."""
if not isinstance(data, tuple):
return data.copy()
return tuple(df.copy() for df in data)
def _all_same_index(data):
"""Raise a ValueError if all DataFrames in `data` do not have the
same index."""
indexes = map(lambda df: df.index, data)
next(indexes, None)
for index in indexes:
if not index.equals(data[0].index):
raise ValueError("Input DataFrames must have same index.")
def _common_keys(dicts):
"""Return the intersection of the set of keys for each dictionary
in `dicts`"""
def _keys(x):
return set(x.keys())
if isinstance(dicts, tuple):
return set.intersection(*map(_keys, dicts))
return _keys(dicts)
def _tuple_from_dfs(dfs, name):
"""Extract a column from each DataFrame in `dfs` if `dfs` is a tuple.
Returns a tuple of Series if `dfs` is a tuple or a Series if `dfs` is
a DataFrame.
"""
if isinstance(dfs, tuple):
return tuple(df[name] for df in dfs)
else:
return dfs[name]
def _to_tuple(x):
if not isinstance(x, (tuple, list)):
return x
return tuple(x)