Classes¶
pvlib-python provides a collection of classes for users that prefer object-oriented programming. These classes can help users keep track of data in a more organized way, and can help to simplify the modeling process. The classes do not add any functionality beyond the procedural code. Most of the object methods are simple wrappers around the corresponding procedural code.
Location¶
-
class
pvlib.location.
Location
(latitude, longitude, tz='UTC', altitude=0, name=None, **kwargs)[source] Bases:
object
Location objects are convenient containers for latitude, longitude, timezone, and altitude data associated with a particular geographic location. You can also assign a name to a location object.
Location objects have two timezone attributes:
tz
is a IANA timezone string.pytz
is a pytz timezone object.
Location objects support the print method.
Parameters: latitude : float.
Positive is north of the equator. Use decimal degrees notation.
longitude : float.
Positive is east of the prime meridian. Use decimal degrees notation.
tz : str, int, float, or pytz.timezone.
See http://en.wikipedia.org/wiki/List_of_tz_database_time_zones for a list of valid time zones. pytz.timezone objects will be converted to strings. ints and floats must be in hours from UTC.
alitude : float.
Altitude from sea level in meters.
name : None or string.
Sets the name attribute of the Location object.
**kwargs
Arbitrary keyword arguments. Included for compatibility, but not used.
See also
pvsystem.PVSystem
-
classmethod
from_tmy
(tmy_metadata, tmy_data=None, **kwargs)[source] Create an object based on a metadata dictionary from tmy2 or tmy3 data readers.
Parameters: tmy_metadata : dict
Returned from tmy.readtmy2 or tmy.readtmy3
tmy_data : None or DataFrame
Optionally attach the TMY data to this object.
Returns: Location object (or the child class of Location that you
called this method from).
-
get_airmass
(times=None, solar_position=None, model='kastenyoung1989')[source] Calculate the relative and absolute airmass.
Automatically chooses zenith or apparant zenith depending on the selected model.
Parameters: times : None or DatetimeIndex
Only used if solar_position is not provided.
solar_position : None or DataFrame
DataFrame with with columns ‘apparent_zenith’, ‘zenith’.
model : str
Relative airmass model
Returns: airmass : DataFrame
Columns are ‘airmass_relative’, ‘airmass_absolute’
-
get_clearsky
(times, model='ineichen', solar_position=None, dni_extra=None, **kwargs)[source] Calculate the clear sky estimates of GHI, DNI, and/or DHI at this location.
Parameters: times: DatetimeIndex
model: str
The clear sky model to use. Must be one of ‘ineichen’, ‘haurwitz’, ‘simplified_solis’.
solar_position : None or DataFrame
DataFrame with with columns ‘apparent_zenith’, ‘zenith’, ‘apparent_elevation’.
dni_extra: None or numeric
If None, will be calculated from times.
kwargs passed to the relevant functions. Climatological values
are assumed in many cases. See source code for details!
Returns: clearsky : DataFrame
Column names are:
ghi, dni, dhi
.
-
get_solarposition
(times, pressure=None, temperature=12, **kwargs)[source] Uses the
solarposition.get_solarposition()
function to calculate the solar zenith, azimuth, etc. at this location.Parameters: times : DatetimeIndex
pressure : None, float, or array-like
If None, pressure will be calculated using
atmosphere.alt2pres()
andself.altitude
.temperature : None, float, or array-like
kwargs passed to :py:func:`solarposition.get_solarposition`
Returns: solar_position : DataFrame
Columns depend on the
method
kwarg, but always includezenith
andazimuth
.
PVSystem¶
-
class
pvlib.pvsystem.
PVSystem
(surface_tilt=0, surface_azimuth=180, albedo=None, surface_type=None, module=None, module_parameters=None, modules_per_string=1, strings_per_inverter=1, inverter=None, inverter_parameters=None, racking_model='open_rack_cell_glassback', **kwargs)[source] Bases:
object
The PVSystem class defines a standard set of PV system attributes and modeling functions. This class describes the collection and interactions of PV system components rather than an installed system on the ground. It is typically used in combination with
Location
andModelChain
objects.See the
LocalizedPVSystem
class for an object model that describes an installed PV system.The class supports basic system topologies consisting of:
- N total modules arranged in series (modules_per_string=N, strings_per_inverter=1).
- M total modules arranged in parallel (modules_per_string=1, strings_per_inverter=M).
- NxM total modules arranged in M strings of N modules each (modules_per_string=N, strings_per_inverter=M).
The class is complementary to the module-level functions.
The attributes should generally be things that don’t change about the system, such the type of module and the inverter. The instance methods accept arguments for things that do change, such as irradiance and temperature.
Parameters: surface_tilt: float or array-like
Tilt angle of the module surface. Up=0, horizon=90.
surface_azimuth: float or array-like
Azimuth angle of the module surface. North=0, East=90, South=180, West=270.
albedo : None, float
The ground albedo. If
None
, will attempt to usesurface_type
andirradiance.SURFACE_ALBEDOS
to lookup albedo.surface_type : None, string
The ground surface type. See
irradiance.SURFACE_ALBEDOS
for valid values.module : None, string
The model name of the modules. May be used to look up the module_parameters dictionary via some other method.
module_parameters : None, dict or Series
Module parameters as defined by the SAPM, CEC, or other.
modules_per_string: int or float
See system topology discussion above.
strings_per_inverter: int or float
See system topology discussion above.
inverter : None, string
The model name of the inverters. May be used to look up the inverter_parameters dictionary via some other method.
inverter_parameters : None, dict or Series
Inverter parameters as defined by the SAPM, CEC, or other.
racking_model : None or string
Used for cell and module temperature calculations.
**kwargs
Arbitrary keyword arguments. Included for compatibility, but not used.
See also
pvlib.location.Location
,pvlib.tracking.SingleAxisTracker
,pvlib.pvsystem.LocalizedPVSystem
-
ashraeiam
(aoi)[source] Determine the incidence angle modifier using
self.module_parameters['b']
,aoi
, and theashraeiam()
function.Uses default arguments if keys not in module_parameters.
Parameters: aoi : numeric
The angle of incidence in degrees.
Returns: modifier : numeric
The AOI modifier.
-
calcparams_desoto
(poa_global, temp_cell, **kwargs)[source] Use the
calcparams_desoto()
function, the input parameters andself.module_parameters
to calculate the module currents and resistances.Parameters: poa_global : float or Series
The irradiance (in W/m^2) absorbed by the module.
temp_cell : float or Series
The average cell temperature of cells within a module in C.
**kwargs
See pvsystem.calcparams_desoto for details
Returns: See pvsystem.calcparams_desoto for details
-
get_aoi
(solar_zenith, solar_azimuth)[source] Get the angle of incidence on the system.
Parameters: solar_zenith : float or Series.
Solar zenith angle.
solar_azimuth : float or Series.
Solar azimuth angle.
Returns: aoi : Series
The angle of incidence
-
get_irradiance
(solar_zenith, solar_azimuth, dni, ghi, dhi, dni_extra=None, airmass=None, model='haydavies', **kwargs)[source] Uses the
irradiance.total_irrad()
function to calculate the plane of array irradiance components on a tilted surface defined byself.surface_tilt
,self.surface_azimuth
, andself.albedo
.Parameters: solar_zenith : float or Series.
Solar zenith angle.
solar_azimuth : float or Series.
Solar azimuth angle.
dni : float or Series
Direct Normal Irradiance
ghi : float or Series
Global horizontal irradiance
dhi : float or Series
Diffuse horizontal irradiance
dni_extra : float or Series
Extraterrestrial direct normal irradiance
airmass : float or Series
Airmass
model : String
Irradiance model.
**kwargs
Passed to
irradiance.total_irrad()
.Returns: poa_irradiance : DataFrame
Column names are:
total, beam, sky, ground
.
-
i_from_v
(resistance_shunt, resistance_series, nNsVth, voltage, saturation_current, photocurrent)[source] Wrapper around the
i_from_v()
function.Parameters: See pvsystem.i_from_v for details Returns: See pvsystem.i_from_v for details
-
localize
(location=None, latitude=None, longitude=None, **kwargs)[source] Creates a LocalizedPVSystem object using this object and location data. Must supply either location object or latitude, longitude, and any location kwargs
Parameters: location : None or Location
latitude : None or float
longitude : None or float
**kwargs : see Location
Returns: localized_system : LocalizedPVSystem
-
physicaliam
(aoi)[source] Determine the incidence angle modifier using
aoi
,self.module_parameters['K']
,self.module_parameters['L']
,self.module_parameters['n']
, and thephysicaliam()
function.Uses default arguments if keys not in module_parameters.
Parameters: aoi : numeric
The angle of incidence in degrees.
Returns: modifier : numeric
The AOI modifier.
-
pvwatts_ac
(pdc)[source] Calculates AC power according to the PVWatts model using
pvwatts_ac()
, self.module_parameters[‘pdc0’], and eta_inv_nom=self.inverter_parameters[‘eta_inv_nom’].See
pvwatts_ac()
for details.
-
pvwatts_dc
(g_poa_effective, temp_cell)[source] Calcuates DC power according to the PVWatts model using
pvwatts_dc()
, self.module_parameters[‘pdc0’], and self.module_parameters[‘gamma_pdc’].See
pvwatts_dc()
for details.
-
pvwatts_losses
(**kwargs)[source] Calculates DC power losses according the PVwatts model using
pvwatts_losses()
. No attributes are used in this calculation, but all keyword arguments will be passed to the function.See
pvwatts_losses()
for details.
-
sapm
(effective_irradiance, temp_cell, **kwargs)[source] Use the
sapm()
function, the input parameters, andself.module_parameters
to calculate Voc, Isc, Ix, Ixx, Vmp/Imp.Parameters: poa_direct : Series
The direct irradiance incident upon the module (W/m^2).
poa_diffuse : Series
The diffuse irradiance incident on module.
temp_cell : Series
The cell temperature (degrees C).
airmass_absolute : Series
Absolute airmass.
aoi : Series
Angle of incidence (degrees).
**kwargs
See pvsystem.sapm for details
Returns: See pvsystem.sapm for details
-
sapm_aoi_loss
(aoi)[source] Use the
sapm_aoi_loss()
function, the input parameters, andself.module_parameters
to calculate F2.Parameters: aoi : numeric
Angle of incidence in degrees.
Returns: F2 : numeric
The SAPM angle of incidence loss coefficient.
-
sapm_celltemp
(irrad, wind, temp)[source] Uses
sapm_celltemp()
to calculate module and cell temperatures based onself.racking_model
and the input parameters.Parameters: See pvsystem.sapm_celltemp for details Returns: See pvsystem.sapm_celltemp for details
-
sapm_effective_irradiance
(poa_direct, poa_diffuse, airmass_absolute, aoi, reference_irradiance=1000)[source] Use the
sapm_effective_irradiance()
function, the input parameters, andself.module_parameters
to calculate effective irradiance.Parameters: poa_direct : numeric
The direct irradiance incident upon the module.
poa_diffuse : numeric
The diffuse irradiance incident on module.
airmass_absolute : numeric
Absolute airmass.
aoi : numeric
Angle of incidence in degrees.
reference_irradiance : numeric
Reference irradiance by which to divide the input irradiance.
Returns: effective_irradiance : numeric
The SAPM effective irradiance.
-
sapm_spectral_loss
(airmass_absolute)[source] Use the
sapm_spectral_loss()
function, the input parameters, andself.module_parameters
to calculate F1.Parameters: airmass_absolute : numeric
Absolute airmass.
Returns: F1 : numeric
The SAPM spectral loss coefficient.
-
scale_voltage_current_power
(data)[source] Scales the voltage, current, and power of the DataFrames returned by
singlediode()
andsapm()
by self.modules_per_string and self.strings_per_inverter.Parameters: data: DataFrame
Must contain columns ‘v_mp’, ‘v_oc’, ‘i_mp’ ,’i_x’, ‘i_xx’, ‘i_sc’, ‘p_mp’.
Returns: scaled_data: DataFrame
A scaled copy of the input data.
-
singlediode
(photocurrent, saturation_current, resistance_series, resistance_shunt, nNsVth, ivcurve_pnts=None)[source] Wrapper around the
singlediode()
function.Parameters: See pvsystem.singlediode for details Returns: See pvsystem.singlediode for details
-
snlinverter
(v_dc, p_dc)[source] Uses
snlinverter()
to calculate AC power based onself.inverter_parameters
and the input parameters.Parameters: See pvsystem.snlinverter for details Returns: See pvsystem.snlinverter for details
ModelChain¶
-
class
pvlib.modelchain.
ModelChain
(system, location, orientation_strategy='south_at_latitude_tilt', 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, temp_model='sapm', losses_model='no_loss', **kwargs)[source] Bases:
object
An experimental class that represents all of the modeling steps necessary for calculating power or energy for a PV system at a given location using the SAPM.
CEC module specifications and the single diode model are not yet supported.
Parameters: system : PVSystem
A
PVSystem
object that represents the connected set of modules, inverters, etc.location : Location
A
Location
object that represents the physical location at which to evaluate the model.orientation_strategy : None or str
The strategy for aligning the modules. If not None, sets the
surface_azimuth
andsurface_tilt
properties of thesystem
. Allowed strategies include ‘flat’, ‘south_at_latitude_tilt’. Ignored for SingleAxisTracker systems.clearsky_model : str
Passed to location.get_clearsky.
transposition_model : str
Passed to system.get_irradiance.
solar_position_method : str
Passed to location.get_solarposition.
airmass_model : str
Passed to location.get_airmass.
dc_model: None, str, or function
If None, the model will be inferred from the contents of system.module_parameters. Valid strings are ‘sapm’, ‘singlediode’, ‘pvwatts’. The ModelChain instance will be passed as the first argument to a user-defined function.
ac_model: None, str, or function
If None, the model will be inferred from the contents of system.inverter_parameters and system.module_parameters. Valid strings are ‘snlinverter’, ‘adrinverter’ (not implemented), ‘pvwatts’. The ModelChain instance will be passed as the first argument to a user-defined function.
aoi_model: None, str, or function
If None, the model will be inferred from the contents of system.module_parameters. Valid strings are ‘physical’, ‘ashrae’, ‘sapm’, ‘no_loss’. The ModelChain instance will be passed as the first argument to a user-defined function.
spectral_model: None, str, or function
If None, the model will be inferred from the contents of system.module_parameters. Valid strings are ‘sapm’, ‘first_solar’ (not implemented), ‘no_loss’. The ModelChain instance will be passed as the first argument to a user-defined function.
temp_model: str or function
Valid strings are ‘sapm’. The ModelChain instance will be passed as the first argument to a user-defined function.
losses_model: str or function
Valid strings are ‘pvwatts’, ‘no_loss’. The ModelChain instance will be passed as the first argument to a user-defined function.
**kwargs
Arbitrary keyword arguments. Included for compatibility, but not used.
-
ac_model
-
adrinverter
()[source]
-
aoi_model
-
ashrae_aoi_loss
()[source]
-
complete_irradiance
(times=None, weather=None)[source] 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: times : DatetimeIndex
Times at which to evaluate the model. Can be None if attribute times is already set.
weather : pandas.DataFrame
Table with at least two columns containing one of the following data sets: dni, dhi, ghi. Can be None if attribute weather is already set.
Returns: self
Assigns attributes: times, weather
Examples
This example does not work until the parameters my_system, my_location, my_datetime and my_weather are not defined properly 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) >>> mc.complete_irradiance(my_datetime, my_weather) >>> mc.run_model()
>>> # my_weather containing 'dhi', 'ghi' and 'dni'. >>> mc = ModelChain(my_system, my_location) >>> mc.run_model(my_datetime, my_weather)
-
dc_model
-
effective_irradiance_model
()[source]
-
first_solar_spectral_loss
()[source]
-
infer_ac_model
()[source]
-
infer_aoi_model
()[source]
-
infer_dc_model
()[source]
-
infer_losses_model
()[source]
-
infer_spectral_model
()[source]
-
infer_temp_model
()[source]
-
losses_model
-
no_aoi_loss
()[source]
-
no_extra_losses
()[source]
-
no_spectral_loss
()[source]
-
orientation_strategy
-
physical_aoi_loss
()[source]
-
prepare_inputs
(times=None, irradiance=None, weather=None)[source] Prepare the solar position, irradiance, and weather inputs to the model.
Parameters: times : DatetimeIndex
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
If None, the weather attribute is used. If the weather attribute is also 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
complete_irradiance()
instead.Returns: self
Assigns attributes: times, solar_position, airmass, total_irrad, aoi
-
pvwatts_dc
()[source]
-
pvwatts_inverter
()[source]
-
pvwatts_losses
()[source]
-
run_model
(times=None, irradiance=None, weather=None)[source] Run the model.
Parameters: times : DatetimeIndex
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
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
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.
-
sapm
()[source]
-
sapm_aoi_loss
()[source]
-
sapm_spectral_loss
()[source]
-
sapm_temp
()[source]
-
singlediode
()[source]
-
snlinverter
()[source]
-
spectral_model
-
temp_model
-
LocalizedPVSystem¶
-
class
pvlib.pvsystem.
LocalizedPVSystem
(pvsystem=None, location=None, **kwargs)[source] Bases:
pvlib.pvsystem.PVSystem
,pvlib.location.Location
The LocalizedPVSystem class defines a standard set of installed PV system attributes and modeling functions. This class combines the attributes and methods of the PVSystem and Location classes.
See the
PVSystem
class for an object model that describes an unlocalized PV system.
SingleAxisTracker¶
-
class
pvlib.tracking.
SingleAxisTracker
(axis_tilt=0, axis_azimuth=0, max_angle=90, backtrack=True, gcr=0.2857142857142857, **kwargs)[source] Bases:
pvlib.pvsystem.PVSystem
Inherits all of the PV modeling methods from PVSystem.
-
get_irradiance
(dni, ghi, dhi, dni_extra=None, airmass=None, model='haydavies', **kwargs)[source] Uses the
irradiance.total_irrad()
function to calculate the plane of array irradiance components on a tilted surface defined byself.surface_tilt
,self.surface_azimuth
, andself.albedo
.Parameters: solar_zenith : float or Series.
Solar zenith angle.
solar_azimuth : float or Series.
Solar azimuth angle.
dni : float or Series
Direct Normal Irradiance
ghi : float or Series
Global horizontal irradiance
dhi : float or Series
Diffuse horizontal irradiance
dni_extra : float or Series
Extraterrestrial direct normal irradiance
airmass : float or Series
Airmass
model : String
Irradiance model.
**kwargs
Passed to
irradiance.total_irrad()
.Returns: poa_irradiance : DataFrame
Column names are:
total, beam, sky, ground
.
-
localize
(location=None, latitude=None, longitude=None, **kwargs)[source] Creates a
LocalizedSingleAxisTracker
object using this object and location data. Must supply either location object or latitude, longitude, and any location kwargsParameters: location : None or Location
latitude : None or float
longitude : None or float
**kwargs : see Location
Returns: localized_system : LocalizedSingleAxisTracker
-
singleaxis
(apparent_zenith, apparent_azimuth)[source]
-
LocalizedSingleAxisTracker¶
-
class
pvlib.tracking.
LocalizedSingleAxisTracker
(pvsystem=None, location=None, **kwargs)[source] Bases:
pvlib.tracking.SingleAxisTracker
,pvlib.location.Location
Highly experimental.