# 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 PVSystem. modelchain.ModelChain(system, location[, …]) 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. pvsystem.LocalizedPVSystem([pvsystem, location]) The LocalizedPVSystem class defines a standard set of installed PV system attributes and modeling functions. tracking.LocalizedSingleAxisTracker([…]) The LocalizedSingleAxisTracker class defines a standard set of installed PV system attributes and modeling functions.

## 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. 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. spa.calculate_deltat(year, month) Calculate the difference between Terrestrial Dynamical Time (TD) and Universal Time (UT).

Functions for calculating sunrise, sunset and transit times.

 location.Location.get_sun_rise_set_transit(times) Calculate sunrise, sunset and transit times. solarposition.sun_rise_set_transit_ephem(…) Calculate the next sunrise and sunset times using the PyEphem package. solarposition.sun_rise_set_transit_spa(…) Calculate the sunrise, sunset, and sun transit times using the NREL SPA algorithm. solarposition.sun_rise_set_transit_geometric(…) Geometric calculation of solar sunrise, sunset, and transit.

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 and attributed to Spencer (1971) and Iqbal (1983). solarposition.declination_cooper69(dayofyear) Solar declination from Duffie & Beckman 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. solarposition.sun_rise_set_transit_geometric(…) Geometric calculation of solar sunrise, sunset, and transit.

## 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. clearsky.haurwitz(apparent_zenith) Determine clear sky GHI using the Haurwitz model. clearsky.detect_clearsky(measured, clearsky, …) Detects clear sky times according to the algorithm developed by Reno and Hansen for GHI measurements. 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.get_absolute_airmass(airmass_relative) Determine absolute (pressure corrected) airmass from relative airmass and pressure atmosphere.get_relative_airmass(zenith[, model]) Gives the relative (not pressure-corrected) airmass. atmosphere.pres2alt(pressure) Determine altitude from site pressure. atmosphere.alt2pres(altitude) Determine site pressure from altitude. atmosphere.gueymard94_pw(temp_air, …) Calculates precipitable water (cm) from ambient air temperature (C) and relatively humidity (%) using an empirical model. atmosphere.first_solar_spectral_correction(pw, …) Spectral mismatch modifier based on precipitable water and absolute (pressure corrected) airmass. 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, lambda0) 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.get_total_irradiance() 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.get_total_irradiance() 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(datetime_or_doy) Determine extraterrestrial radiation from day of year. 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 sun position unit vector and the surface normal unit vector; in other words, the cosine of the angle of incidence. 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(aoi, dni, …) Determine in-plane irradiance components. irradiance.get_ground_diffuse(surface_tilt, ghi) Estimate diffuse irradiance from ground reflections given irradiance, albedo, and surface tilt irradiance.dni(ghi, dhi, zenith[, …]) Determine DNI from GHI and DHI.

### Transposition models¶

 irradiance.get_total_irradiance(…[, …]) Determine total in-plane irradiance and its beam, sky diffuse and ground reflected components, using the specified sky diffuse irradiance model. irradiance.get_sky_diffuse(surface_tilt, …) Determine in-plane sky diffuse irradiance component using the specified sky diffuse irradiance model. 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, solar_zenith, …[, …]) Estimate Direct Normal Irradiance from Global Horizontal Irradiance using the DISC model. irradiance.dirint(ghi, solar_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. irradiance.erbs(ghi, zenith, datetime_or_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. irradiance.gti_dirint(poa_global, aoi, …) Determine GHI, DNI, DHI from POA global using the GTI DIRINT model.

### Clearness index models¶

 irradiance.clearness_index(ghi, …[, …]) Calculate the clearness index. irradiance.clearness_index_zenith_independent(…) Calculate the zenith angle independent clearness index. irradiance.clearsky_index(ghi, clearsky_ghi) Calculate the clearsky index.

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

### Incident angle modifiers¶

 iam.physical(aoi[, n, K, L]) Determine the incidence angle modifier using refractive index n, extinction coefficient K, and glazing thickness L. iam.ashrae(aoi[, b]) Determine the incidence angle modifier using the ASHRAE transmission model. iam.martin_ruiz(aoi[, a_r]) Determine the incidence angle modifier (IAM) using the Martin and Ruiz incident angle model. iam.martin_ruiz_diffuse(surface_tilt[, a_r, …]) Determine the incidence angle modifiers (iam) for diffuse sky and ground-reflected irradiance using the Martin and Ruiz incident angle model. iam.sapm(aoi, module[, upper]) Determine the incidence angle modifier (IAM) using the SAPM model. iam.interp(aoi, theta_ref, iam_ref[, …]) Determine the incidence angle modifier (IAM) by interpolating a set of reference values, which are usually measured values.

### PV temperature models¶

 temperature.sapm_cell(poa_global, temp_air, …) Calculate cell temperature per the Sandia Array Performance Model. temperature.sapm_module(poa_global, …) Calculate module back surface temperature per the Sandia Array Performance Model. temperature.sapm_cell_from_module(…[, …]) Calculate cell temperature from module temperature using the Sandia Array Performance Model. temperature.pvsyst_cell(poa_global, temp_air) Calculate cell temperature using an empirical heat loss factor model as implemented in PVsyst. temperature.faiman(poa_global, temp_air[, …]) Calculate cell or module temperature using the Faiman model.

### Single diode models¶

Functions relevant for single diode models.

 pvsystem.calcparams_cec(…[, EgRef, dEgdT, …]) Calculates five parameter values for the single diode equation at effective irradiance and cell temperature using the CEC model. pvsystem.calcparams_desoto(…[, EgRef, …]) Calculates five parameter values for the single diode equation at effective irradiance and cell temperature using the De Soto et al. pvsystem.calcparams_pvsyst(…[, R_sh_exp, …]) Calculates five parameter values for the single diode equation at effective irradiance and cell temperature using the PVsyst v6 model. 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. pvsystem.max_power_point(photocurrent, …) Given the single diode equation coefficients, calculates the maximum power point (MPP).

Low-level functions for solving the single diode equation.

 singlediode.estimate_voc(photocurrent, …) Rough estimate of open circuit voltage useful for bounding searches for i of v when using singlediode(). singlediode.bishop88(diode_voltage, …[, …]) Explicit calculation of points on the IV curve described by the single diode equation. singlediode.bishop88_i_from_v(voltage, …) Find current given any voltage. singlediode.bishop88_v_from_i(current, …) Find voltage given any current. singlediode.bishop88_mpp(photocurrent, …) Find max power point.

### 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.sapm_effective_irradiance(…) Calculates the SAPM effective irradiance using the SAPM spectral loss and SAPM angle of incidence loss functions. pvsystem.sapm_spectral_loss(…) Calculates the SAPM spectral loss coefficient, F1. pvsystem.sapm_aoi_loss(aoi, module[, upper]) Deprecated since version 0.7. pvsystem.snlinverter(v_dc, p_dc, inverter) Converts DC power and voltage to AC power using Sandia’s Grid-Connected PV Inverter model. pvsystem.adrinverter(v_dc, p_dc, inverter[, …]) Converts DC power and voltage to AC power using Anton Driesse’s Grid-Connected PV Inverter efficiency model temperature.sapm_cell(poa_global, temp_air, …) Calculate cell temperature per the Sandia Array Performance Model.

### Pvsyst model¶

Functions relevant for the Pvsyst model.

 temperature.pvsyst_cell(poa_global, temp_air) Calculate cell temperature using an empirical heat loss factor model as implemented in PVsyst.

### PVWatts model¶

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

### Functions for fitting diode models¶

 ivtools.fit_sde_sandia(voltage, current[, …]) Fits the single diode equation (SDE) to an IV curve. ivtools.fit_sdm_cec_sam(celltype, v_mp, …) Estimates parameters for the CEC single diode model (SDM) using the SAM SDK. ivtools.fit_sdm_desoto(v_mp, i_mp, v_oc, …) Calculates the parameters for the De Soto single diode model.

## Effects on PV System Output¶

 snow.coverage_nrel(snowfall, poa_irradiance, …) Calculates the fraction of the slant height of a row of modules covered by snow at every time step. snow.fully_covered_nrel(snowfall[, …]) Calculates the timesteps when the row’s slant height is fully covered by snow. snow.dc_loss_nrel(snow_coverage, num_strings) Calculates the fraction of DC capacity lost due to snow coverage.
 soiling.hsu(rainfall, cleaning_threshold, …) Calculates soiling ratio given particulate and rain data using the model from Humboldt State University (HSU). soiling.kimber(rainfall[, …]) Calculates fraction of energy lost due to soiling given rainfall data and daily loss rate using the Kimber model.

## Tracking¶

### SingleAxisTracker¶

The SingleAxisTracker inherits from PVSystem.

 tracking.SingleAxisTracker([axis_tilt, …]) Inherits the PV modeling methods from PVSystem. tracking.SingleAxisTracker.singleaxis(…) Get tracking data. tracking.SingleAxisTracker.get_irradiance(…) Uses the irradiance.get_total_irradiance() 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([…]) The LocalizedSingleAxisTracker class defines a standard set of installed PV system attributes and modeling functions.

### Functions¶

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

## IO Tools¶

Functions for reading and writing data from a variety of file formats relevant to solar energy modeling.

 iotools.read_tmy2(filename) Read a TMY2 file in to a DataFrame. iotools.read_tmy3([filename, coerce_year, …]) Read a TMY3 file in to a pandas dataframe. iotools.read_epw(filename[, coerce_year]) Read an EPW file in to a pandas dataframe. iotools.parse_epw(csvdata[, coerce_year]) Given a file-like buffer with data in Energy Plus Weather (EPW) format, parse the data into a dataframe. iotools.read_srml(filename) Read University of Oregon SRML 1min .tsv file into pandas dataframe. iotools.read_srml_month_from_solardat(…[, …]) Request a month of SRML data from solardat and read it into a Dataframe. iotools.read_surfrad(filename[, map_variables]) Read in a daily NOAA SURFRAD file. iotools.read_midc(filename[, variable_map, …]) Read in National Renewable Energy Laboratory Measurement and Instrumentation Data Center weather data. iotools.read_midc_raw_data_from_nrel(site, …) Request and read MIDC data directly from the raw data api. iotools.read_ecmwf_macc(filename, latitude, …) Read data from ECMWF MACC reanalysis netCDF4 file. iotools.get_ecmwf_macc(filename, params, …) Download data from ECMWF MACC Reanalysis API. iotools.read_crn(filename) Read a NOAA USCRN fixed-width file into pandas dataframe. iotools.read_solrad(filename) Read NOAA SOLRAD fixed-width file into pandas dataframe. iotools.get_psm3(latitude, longitude, …[, …]) Retrieve NSRDB PSM3 timeseries weather data from the PSM3 API. iotools.read_psm3(filename) Read an NSRDB PSM3 weather file (formatted as SAM CSV). iotools.parse_psm3(fbuf) Parse an NSRDB PSM3 weather file (formatted as SAM CSV). iotools.get_pvgis_tmy(lat, lon[, …]) Get TMY data from PVGIS. iotools.read_pvgis_tmy(filename[, pvgis_format]) Read a file downloaded from PVGIS.

A Location object may be created from metadata in some files.

 location.Location.from_tmy(tmy_metadata[, …]) Create an object based on a metadata dictionary from tmy2 or tmy3 data readers. location.Location.from_epw(metadata[, data]) Create a Location object based on a metadata dictionary from epw data readers.

## 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(tz, …) 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[, …]) 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.

### Running¶

Running a ModelChain.

 modelchain.ModelChain.run_model(weather[, times]) Run the model. modelchain.ModelChain.complete_irradiance(weather) Determine the missing irradiation columns. modelchain.ModelChain.prepare_inputs(weather) 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.

## Bifacial¶

Methods for calculating back surface irradiance

 bifacial.pvfactors_timeseries(solar_azimuth, …) Calculate front and back surface plane-of-array irradiance on a fixed tilt or single-axis tracker PV array configuration, and using the open-source “pvfactors” package.

## Scaling¶

Methods for manipulating irradiance for temporal or spatial considerations

 scaling.wvm(clearsky_index, positions, …) Compute spatial aggregation time series smoothing on clear sky index based on the Wavelet Variability model of Lave et al [1-2].