# API reference¶

## 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.Location(latitude, longitude[, tz, …]) Location objects are convenient containers for latitude, longitude, timezone, and altitude data associated with a particular geographic location. pvsystem.PVSystem([surface_tilt, …]) The PVSystem class defines a standard set of PV system attributes and modeling functions. tracking.SingleAxisTracker([axis_tilt, …]) Inherits the PV modeling methods from :ref:PVSystem:. modelchain.ModelChain(system, location[, …]) 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. pvsystem.LocalizedPVSystem([pvsystem, location]) The LocalizedPVSystem class defines a standard set of installed PV system attributes and modeling functions. tracking.LocalizedSingleAxisTracker([…]) Highly experimental.

## Solar Position¶

Functions and methods for calculating solar position.

The location.Location.get_solarposition() method and the solarposition.get_solarposition() function with default parameters are fast and accurate. We recommend using these functions unless you know that you need a different function.

 location.Location.get_solarposition(times[, …]) Uses the solarposition.get_solarposition() function to calculate the solar zenith, azimuth, etc. solarposition.get_solarposition(time, …[, …]) A convenience wrapper for the solar position calculators. solarposition.spa_python(time, latitude, …) Calculate the solar position using a python implementation of the NREL SPA algorithm described in [1]. solarposition.ephemeris(time, latitude, …) Python-native solar position calculator. solarposition.pyephem(time, latitude, longitude) Calculate the solar position using the PyEphem package. solarposition.spa_c(time, latitude, longitude) Calculate the solar position using the C implementation of the NREL SPA code.

Additional functions for quantities closely related to solar position.

 solarposition.calc_time(lower_bound, …[, …]) Calculate the time between lower_bound and upper_bound where the attribute is equal to value. solarposition.pyephem_earthsun_distance(time) Calculates the distance from the earth to the sun using pyephem. solarposition.nrel_earthsun_distance(time[, …]) Calculates the distance from the earth to the sun using the NREL SPA algorithm described in [R696e8080435f-1]. spa.calculate_deltat(year, month) Calculate the difference between Terrestrial Dynamical Time (TD) and Universal Time (UT).

The spa module contains the implementation of the built-in NREL SPA algorithm.

 spa Calculate the solar position using the NREL SPA algorithm either using numpy arrays or compiling the code to machine language with numba.

Correlations and analytical expressions for low precision solar position calculations.

 solarposition.solar_zenith_analytical(…) Analytical expression of solar zenith angle based on spherical trigonometry. solarposition.solar_azimuth_analytical(…) Analytical expression of solar azimuth angle based on spherical trigonometry. solarposition.declination_spencer71(dayofyear) Solar declination from Duffie & Beckman [1] and attributed to Spencer (1971) and Iqbal (1983). solarposition.declination_cooper69(dayofyear) Solar declination from Duffie & Beckman [1] and attributed to Cooper (1969) solarposition.equation_of_time_spencer71(…) Equation of time from Duffie & Beckman and attributed to Spencer (1971) and Iqbal (1983). solarposition.equation_of_time_pvcdrom(dayofyear) Equation of time from PVCDROM. solarposition.hour_angle(times, longitude, …) Hour angle in local solar time.

## Clear sky¶

 location.Location.get_clearsky(times[, …]) Calculate the clear sky estimates of GHI, DNI, and/or DHI at this location. clearsky.ineichen(apparent_zenith, …[, …]) Determine clear sky GHI, DNI, and DHI from Ineichen/Perez model. clearsky.lookup_linke_turbidity(time, …[, …]) Look up the Linke Turibidity from the LinkeTurbidities.h5 data file supplied with pvlib. clearsky.simplified_solis(apparent_elevation) Calculate the clear sky GHI, DNI, and DHI according to the simplified Solis model [Ra31b6ebd1385-1]. clearsky.haurwitz(apparent_zenith) Determine clear sky GHI from Haurwitz model. clearsky.detect_clearsky(measured, clearsky, …) Detects clear sky times according to the algorithm developed by Reno and Hansen for GHI measurements [1]. clearsky.bird(zenith, airmass_relative, …) Bird Simple Clear Sky Broadband Solar Radiation Model

## Airmass and atmospheric models¶

 location.Location.get_airmass([times, …]) Calculate the relative and absolute airmass. atmosphere.absolute_airmass atmosphere.get_relative_airmass atmosphere.pres2alt(pressure) Determine altitude from site pressure. atmosphere.alt2pres(altitude) Determine site pressure from altitude. atmosphere.pw_gueymard94 atmosphere.spectral_correction_first_solar atmosphere.spectral_corrrection_sapm atmosphere.aod_bb_bird_hulstrom80 atmosphere.bird_hulstrom80_aod_bb(aod380, aod500) Approximate broadband aerosol optical depth. atmosphere.kasten96_lt(airmass_absolute, …) Calculate Linke turbidity factor using Kasten pyrheliometric formula. atmosphere.angstrom_aod_at_lambda(aod0, …) Get AOD at specified wavelength using Angstrom turbidity model. atmosphere.angstrom_alpha(aod1, lambda1, …) Calculate Angstrom alpha exponent.

 pvsystem.PVSystem.get_irradiance(…[, …]) 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. pvsystem.PVSystem.get_aoi(solar_zenith, …) Get the angle of incidence on the system. tracking.SingleAxisTracker.get_irradiance(…) Uses the irradiance.total_irrad() function to calculate the plane of array irradiance components on a tilted surface defined by the input data and self.albedo.

 irradiance.get_extra_radiation irradiance.aoi(surface_tilt, …) Calculates the angle of incidence of the solar vector on a surface. irradiance.aoi_projection(surface_tilt, …) Calculates the dot product of the solar vector and the surface normal. irradiance.poa_horizontal_ratio(…) Calculates the ratio of the beam components of the plane of array irradiance and the horizontal irradiance. irradiance.beam_component(surface_tilt, …) Calculates the beam component of the plane of array irradiance. irradiance.poa_components irradiance.get_ground_diffuse

### Transposition models¶

 irradiance.get_total_irradiance irradiance.get_sky_diffuse irradiance.isotropic(surface_tilt, dhi) Determine diffuse irradiance from the sky on a tilted surface using the isotropic sky model. irradiance.perez(surface_tilt, …[, model, …]) Determine diffuse irradiance from the sky on a tilted surface using one of the Perez models. irradiance.haydavies(surface_tilt, …[, …]) Determine diffuse irradiance from the sky on a tilted surface using Hay & Davies’ 1980 model irradiance.klucher(surface_tilt, …) Determine diffuse irradiance from the sky on a tilted surface using Klucher’s 1979 model irradiance.reindl(surface_tilt, …) Determine diffuse irradiance from the sky on a tilted surface using Reindl’s 1990 model irradiance.king(surface_tilt, dhi, ghi, …) Determine diffuse irradiance from the sky on a tilted surface using the King model.

### DNI estimation models¶

 irradiance.disc(ghi, zenith, datetime_or_doy) Estimate Direct Normal Irradiance from Global Horizontal Irradiance using the DISC model. irradiance.dirint(ghi, zenith, times[, …]) Determine DNI from GHI using the DIRINT modification of the DISC model. irradiance.dirindex(ghi, ghi_clearsky, …) Determine DNI from GHI using the DIRINDEX model, which is a modification of the DIRINT model with information from a clear sky model. irradiance.erbs(ghi, zenith, doy) Estimate DNI and DHI from GHI using the Erbs model. irradiance.liujordan(zenith, transmittance, …) Determine DNI, DHI, GHI from extraterrestrial flux, transmittance, and optical air mass number.

## PV Modeling¶

### Classes¶

The PVSystem class provides many methods that wrap the functions listed below. See its documentation for details.

 pvsystem.PVSystem([surface_tilt, …]) The PVSystem class defines a standard set of PV system attributes and modeling functions. pvsystem.LocalizedPVSystem([pvsystem, location]) The LocalizedPVSystem class defines a standard set of installed PV system attributes and modeling functions.

### AOI modifiers¶

 pvsystem.iam_physical pvsystem.iam_ashrae pvsystem.iam_sapm

### Single diode model¶

Functions relevant for the single diode model.

 pvsystem.calcparams_desoto(poa_global, …) Applies the temperature and irradiance corrections to inputs for singlediode. pvsystem.i_from_v(resistance_shunt, …) Device current at the given device voltage for the single diode model. pvsystem.singlediode(photocurrent, …[, …]) Solve the single-diode model to obtain a photovoltaic IV curve. pvsystem.v_from_i(resistance_shunt, …) Device voltage at the given device current for the single diode model.

### SAPM model¶

Functions relevant for the SAPM model.

 pvsystem.sapm(effective_irradiance, …) The Sandia PV Array Performance Model (SAPM) generates 5 points on a PV module’s I-V curve (Voc, Isc, Ix, Ixx, Vmp/Imp) according to SAND2004-3535. pvsystem.effective_irradiance_sapm pvsystem.celltemp_sapm pvsystem.spectral_loss_sapm pvsystem.iam_sapm pvsystem.inverter_sapm

### PVWatts model¶

 pvsystem.pvwatts_dc(g_poa_effective, …[, …]) Implements NREL’s PVWatts DC power model [R549cc3f4d5f7-1]: pvsystem.pvwatts_ac(pdc, pdc0[, …]) Implements NREL’s PVWatts inverter model [R8eb68e324bb7-1]. pvsystem.pvwatts_losses([soiling, shading, …]) Implements NREL’s PVWatts system loss model [R7a6c04e4f7d1-1]:

### Other¶

 pvsystem.retrieve_sam([name, path]) Retrieve latest module and inverter info from a local file or the SAM website. pvsystem.systemdef(meta, surface_tilt, …) Generates a dict of system parameters used throughout a simulation. pvsystem.scale_voltage_current_power(data[, …]) Scales the voltage, current, and power of the DataFrames returned by singlediode() and sapm().

## Tracking¶

### SingleAxisTracker¶

The SingleAxisTracker inherits from PVSystem.

 tracking.SingleAxisTracker([axis_tilt, …]) Inherits the PV modeling methods from :ref:PVSystem:. tracking.SingleAxisTracker.singleaxis(…) tracking.SingleAxisTracker.get_irradiance(…) Uses the irradiance.total_irrad() function to calculate the plane of array irradiance components on a tilted surface defined by the input data and self.albedo. tracking.SingleAxisTracker.localize([…]) Creates a LocalizedSingleAxisTracker object using this object and location data. tracking.LocalizedSingleAxisTracker([…]) Highly experimental.

### Functions¶

 tracking.singleaxis(apparent_zenith, …[, …]) Determine the rotation angle of a single axis tracker using the equations in [1] when given a particular sun zenith and azimuth angle.

## TMY¶

Methods and functions for reading data from TMY files.

Move to IO subpackage

 location.Location.from_tmy(tmy_metadata[, …]) Create an object based on a metadata dictionary from tmy2 or tmy3 data readers. tmy.readtmy2(filename) Read a TMY2 file in to a DataFrame. tmy.readtmy3([filename, coerce_year, recolumn]) Read a TMY3 file in to a pandas dataframe.

## Forecasting¶

### Forecast models¶

 forecast.GFS([resolution, set_type]) Subclass of the ForecastModel class representing GFS forecast model. forecast.NAM([set_type]) Subclass of the ForecastModel class representing NAM forecast model. forecast.RAP([resolution, set_type]) Subclass of the ForecastModel class representing RAP forecast model. forecast.HRRR([set_type]) Subclass of the ForecastModel class representing HRRR forecast model. forecast.HRRR_ESRL([set_type]) Subclass of the ForecastModel class representing NOAA/GSD/ESRL’s HRRR forecast model. forecast.NDFD([set_type]) Subclass of the ForecastModel class representing NDFD forecast model.

### Getting data¶

 forecast.ForecastModel.get_data(latitude, …) Submits a query to the UNIDATA servers using Siphon NCSS and converts the netcdf data to a pandas DataFrame. forecast.ForecastModel.get_processed_data(…) Get and process forecast data.

### Processing data¶

 forecast.ForecastModel.process_data(data, …) Defines the steps needed to convert raw forecast data into processed forecast data. forecast.ForecastModel.rename(data[, variables]) Renames the columns according the variable mapping. forecast.ForecastModel.cloud_cover_to_ghi_linear(…) Convert cloud cover to GHI using a linear relationship. forecast.ForecastModel.cloud_cover_to_irradiance_clearsky_scaling(…) Estimates irradiance from cloud cover in the following steps: forecast.ForecastModel.cloud_cover_to_transmittance_linear(…) Convert cloud cover to atmospheric transmittance using a linear model. forecast.ForecastModel.cloud_cover_to_irradiance_liujordan(…) Estimates irradiance from cloud cover in the following steps: forecast.ForecastModel.cloud_cover_to_irradiance(…) Convert cloud cover to irradiance. forecast.ForecastModel.kelvin_to_celsius(…) Converts Kelvin to celsius. forecast.ForecastModel.isobaric_to_ambient_temperature(data) Calculates temperature from isobaric temperature. forecast.ForecastModel.uv_to_speed(data) Computes wind speed from wind components. forecast.ForecastModel.gust_to_speed(data[, …]) Computes standard wind speed from gust.

### IO support¶

These are public for now, but use at your own risk.

 forecast.ForecastModel.set_dataset() Retrieves the designated dataset, creates NCSS object, and creates a NCSS query object. forecast.ForecastModel.set_query_latlon() Sets the NCSS query location latitude and longitude. forecast.ForecastModel.set_location(time, …) Sets the location for the query. forecast.ForecastModel.set_time(time) Converts time data into a pandas date object.

## ModelChain¶

Creating a ModelChain object.

 modelchain.ModelChain(system, location[, …]) 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.

### Running¶

Running a ModelChain.

 modelchain.ModelChain.run_model([times, …]) Run the model. modelchain.ModelChain.complete_irradiance([…]) Determine the missing irradiation columns. modelchain.ModelChain.prepare_inputs([…]) Prepare the solar position, irradiance, and weather inputs to the model.

### Attributes¶

Simple ModelChain attributes:

system, location, clearsky_model, transposition_model, solar_position_method, airmass_model

### Properties¶

ModelChain properties that are aliases for your specific modeling functions.

### Inference methods¶

Methods that automatically determine which models should be used based on the information in the associated PVSystem object.

### Functions¶

Functions for power modeling.

 modelchain.basic_chain(times, latitude, …) An experimental function that computes all of the modeling steps necessary for calculating power or energy for a PV system at a given location. modelchain.get_orientation(strategy, **kwargs) Determine a PV system’s surface tilt and surface azimuth using a named strategy.