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)

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)

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')

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', **kwargs)

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’.

kwargs passed to the relevant functions. Climatological values

are assumed in many cases. See code for details.

Returns:

clearsky : DataFrame

Column names are: ghi, dni, dhi.

get_solarposition(times, pressure=None, temperature=12, **kwargs)

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() and self.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 include zenith and azimuth.

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)

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 and ModelChain 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 use surface_type and irradiance.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)

Determine the incidence angle modifier using self.module_parameters['b'], aoi, and the ashraeiam() function.

Parameters:

aoi : numeric

The angle of incidence in degrees.

Returns:

modifier : numeric

The AOI modifier.

calcparams_desoto(poa_global, temp_cell, **kwargs)

Use the calcparams_desoto() function, the input parameters and self.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)

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)

Uses the irradiance.total_irrad() function to calculate the plane of array irradiance components on a tilted surface defined by self.surface_tilt, self.surface_azimuth, and self.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)

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)

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)

Determine the incidence angle modifier using self.module_parameters['K'], self.module_parameters['L'], self.module_parameters['n'], aoi, and the physicaliam() function.

Parameters:See pvsystem.physicaliam for details Returns:See pvsystem.physicaliam for details

sapm(poa_direct, poa_diffuse, temp_cell, airmass_absolute, aoi, **kwargs)

Use the sapm() function, the input parameters, and self.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_celltemp(irrad, wind, temp)

Uses sapm_celltemp() to calculate module and cell temperatures based on self.racking_model and the input parameters.

Parameters:See pvsystem.sapm_celltemp for details Returns:See pvsystem.sapm_celltemp for details

scale_voltage_current_power(data)

Scales the voltage, current, and power of the DataFrames returned by singlediode() and sapm() 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)

Wrapper around the singlediode() function.

Parameters:See pvsystem.singlediode for details Returns:See pvsystem.singlediode for details

snlinverter(v_dc, p_dc)

Uses snlinverter() to calculate AC power based on self.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', **kwargs)

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 and surface_tilt properties of the system. Allowed strategies include ‘flat’, ‘south_at_latitude_tilt’.

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.

**kwargs

Arbitrary keyword arguments. Included for compatibility, but not used.

orientation_strategy

run_model(times, irradiance=None, weather=None)

Run the model.

Parameters:

times : DatetimeIndex

Times at which to evaluate the model.

irradiance : None or DataFrame

If None, calculates clear sky data. Columns must be ‘dni’, ‘ghi’, ‘dhi’.

weather : None or DataFrame

If None, assumes air temperature is 20 C and wind speed is 0 m/s. Columns must be ‘wind_speed’, ‘temp_air’.

Returns:

self

Assigns attributes: times, solar_position, airmass, irradiance,

total_irrad, weather, temps, aoi, dc, ac

LocalizedPVSystem

class pvlib.pvsystem.LocalizedPVSystem(pvsystem=None, location=None, **kwargs)

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)

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)

Uses the irradiance.total_irrad() function to calculate the plane of array irradiance components on a tilted surface defined by self.surface_tilt, self.surface_azimuth, and self.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)

Creates a LocalizedSingleAxisTracker 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 : LocalizedSingleAxisTracker

singleaxis(apparent_zenith, apparent_azimuth)

LocalizedSingleAxisTracker

class pvlib.tracking.LocalizedSingleAxisTracker(pvsystem=None, location=None, **kwargs)

Bases: pvlib.tracking.SingleAxisTracker, pvlib.location.Location

Highly experimental.