or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

atmosphere.mdbifacial.mdclearsky.mdiam.mdindex.mdinverter.mdiotools.mdirradiance.mdlosses.mdpvsystem.mdsolar-position.mdspectrum.mdtemperature.md
tile.json

tessl/pypi-pvlib

A comprehensive toolbox for modeling and simulating photovoltaic energy systems.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pvlib@0.13.x

To install, run

npx @tessl/cli install tessl/pypi-pvlib@0.13.0

index.mddocs/

pvlib Python

A comprehensive Python library for modeling and simulating photovoltaic energy systems. pvlib provides reliable, open-source implementations of industry-standard PV system models, offering extensive functionality for solar resource assessment, PV system performance modeling, and related calculations.

Package Information

  • Package Name: pvlib
  • Language: Python
  • Installation: pip install pvlib

Core Imports

import pvlib

Common import patterns for specific functionality:

from pvlib import solarposition, irradiance, atmosphere, temperature
from pvlib import pvsystem, modelchain, location
from pvlib.pvsystem import PVSystem
from pvlib.location import Location
from pvlib.modelchain import ModelChain

Basic Usage

import pvlib
from pvlib import solarposition, irradiance, atmosphere, temperature
from pvlib import pvsystem, modelchain, location
import pandas as pd

# Create a location object
site = location.Location(latitude=40.0583, longitude=-74.4057, 
                        tz='US/Eastern', altitude=10, name='Princeton')

# Get solar position data for a time period
times = pd.date_range('2023-01-01', '2023-01-02', freq='H', tz=site.tz)
solar_position = site.get_solarposition(times)

# Get clear sky data
clear_sky = site.get_clearsky(times)

# Calculate total irradiance on a tilted surface
surface_tilt = 30
surface_azimuth = 180
poa_irradiance = irradiance.get_total_irradiance(
    surface_tilt=surface_tilt,
    surface_azimuth=surface_azimuth,
    solar_zenith=solar_position['zenith'],
    solar_azimuth=solar_position['azimuth'],
    dni=clear_sky['dni'],
    ghi=clear_sky['ghi'],
    dhi=clear_sky['dhi']
)

print(poa_irradiance.head())

Architecture

pvlib follows a modular architecture organizing PV system modeling into distinct functional areas:

  • Solar Position: Algorithms for calculating sun position (SPA, PyEphem, analytical methods)
  • Irradiance Models: Solar irradiance calculations, decomposition, and transposition models
  • Atmosphere: Atmospheric modeling including airmass, precipitable water, and aerosol optical depth
  • Clear Sky Models: Multiple clear sky irradiance models (Ineichen, Bird, Haurwitz, SOLIS)
  • PV System Models: Complete PV system modeling from single diode models to system-level analysis
  • Temperature Models: Cell and module temperature calculations using various approaches
  • Data I/O: Comprehensive weather data reading from multiple sources and formats
  • Specialized Modules: Bifacial systems, spectral modeling, snow/soiling effects, tracking systems

This modular design enables both component-level analysis and complete system modeling workflows.

Capabilities

Solar Position Calculation

Calculate solar position using multiple high-precision algorithms including the Solar Position Algorithm (SPA), PyEphem, and analytical methods. Provides zenith, azimuth, sunrise, sunset, and solar transit times.

def get_solarposition(time, latitude, longitude, altitude=0, pressure=101325, 
                     temperature=12, method='nrel_numpy', **kwargs):
    """
    Calculate solar position using various algorithms.
    
    Parameters:
    - time: pandas.DatetimeIndex
    - latitude: float, decimal degrees
    - longitude: float, decimal degrees  
    - altitude: float, meters above sea level
    - pressure: float, pascals
    - temperature: float, degrees C
    - method: str, calculation method
    
    Returns:
    pandas.DataFrame with columns: apparent_zenith, zenith, 
    apparent_elevation, elevation, azimuth, equation_of_time
    """

Solar Position

Irradiance Modeling

Calculate solar irradiance components and perform decomposition/transposition modeling. Includes plane-of-array calculations, sky diffuse models (Perez, Hay-Davies, Reindl), and irradiance decomposition models.

def get_total_irradiance(surface_tilt, surface_azimuth, solar_zenith, 
                        solar_azimuth, dni, ghi, dhi, **kwargs):
    """
    Calculate total irradiance on a tilted surface.
    
    Parameters:
    - surface_tilt: float, degrees from horizontal
    - surface_azimuth: float, degrees from north
    - solar_zenith: numeric, degrees
    - solar_azimuth: numeric, degrees  
    - dni: numeric, direct normal irradiance
    - ghi: numeric, global horizontal irradiance
    - dhi: numeric, diffuse horizontal irradiance
    
    Returns:
    OrderedDict with keys: poa_global, poa_direct, poa_diffuse, poa_sky_diffuse, poa_ground_diffuse
    """

Irradiance

Atmospheric Modeling

Model atmospheric effects including airmass calculations, precipitable water, aerosol optical depth, and Linke turbidity. Essential for accurate irradiance and clear sky modeling.

def get_relative_airmass(zenith, model='kastenyoung1989'):
    """
    Calculate relative airmass.
    
    Parameters:
    - zenith: numeric, solar zenith angle in degrees
    - model: str, airmass model
    
    Returns:
    numeric, relative airmass
    """

def get_absolute_airmass(airmass_relative, pressure=101325.0):
    """
    Calculate absolute airmass.
    
    Parameters:
    - airmass_relative: numeric, relative airmass
    - pressure: numeric, atmospheric pressure in pascals
    
    Returns:
    numeric, absolute airmass
    """

Atmospheric Models

Clear Sky Irradiance

Calculate clear sky irradiance using multiple models including Ineichen, Bird, Haurwitz, and simplified SOLIS. Provides baseline irradiance for system modeling and clear sky detection.

def ineichen(apparent_zenith, airmass_absolute, linke_turbidity, 
            altitude=0, dni_extra=1366.1):
    """
    Ineichen clear sky model.
    
    Parameters:
    - apparent_zenith: numeric, degrees
    - airmass_absolute: numeric
    - linke_turbidity: numeric
    - altitude: numeric, meters
    - dni_extra: numeric, extraterrestrial irradiance
    
    Returns:
    OrderedDict with keys: ghi, dni, dhi
    """

Clear Sky Models

PV System Modeling

Complete PV system modeling including single diode models, SAPM, PVWatts, inverter models, and system-level analysis. Supports various module technologies and system configurations.

class PVSystem:
    """
    Complete PV system representation.
    
    Parameters:
    - arrays: Array or iterable of Array
    - name: str, system name
    - inverter: dict, inverter parameters
    - inverter_parameters: dict, inverter model parameters
    - temperature_model_parameters: dict
    """

def singlediode(photocurrent, saturation_current, resistance_series, 
               resistance_shunt, nNsVth, ivcurve_pnts=None):
    """
    Single diode model for PV cells/modules.
    
    Parameters:
    - photocurrent: numeric, light current (A)
    - saturation_current: numeric, dark saturation current (A)
    - resistance_series: numeric, series resistance (ohm)
    - resistance_shunt: numeric, shunt resistance (ohm)  
    - nNsVth: numeric, thermal voltage parameter
    - ivcurve_pnts: int, number of IV curve points
    
    Returns:
    OrderedDict with keys: i_sc, v_oc, i_mp, v_mp, p_mp, i_x, i_xx, v_x, i, v
    """

PV System Models

Temperature Modeling

Calculate PV cell and module temperatures using various models including SAPM, Faiman, Ross, Fuentes, and PVsyst approaches. Essential for accurate system performance modeling.

def sapm_cell(poa_global, temp_air, wind_speed, a, b, deltaT, 
             irrad_ref=1000, temp_ref=25):
    """
    SAPM cell temperature model.
    
    Parameters:
    - poa_global: numeric, plane-of-array irradiance (W/m^2)
    - temp_air: numeric, ambient air temperature (C)
    - wind_speed: numeric, wind speed (m/s)
    - a: numeric, SAPM module parameter
    - b: numeric, SAPM module parameter  
    - deltaT: numeric, SAPM module parameter
    - irrad_ref: numeric, reference irradiance
    - temp_ref: numeric, reference temperature
    
    Returns:
    numeric, cell temperature (C)
    """

Temperature Models

Weather Data I/O

Read and retrieve weather data from numerous sources including TMY files, NSRDB, PVGIS, SURFRAD, and many others. Provides standardized interfaces for various data formats.

def read_tmy3(filename, coerce_year=None, map_variables=True):
    """
    Read TMY3 files.
    
    Parameters:
    - filename: str, path to TMY3 file
    - coerce_year: int, year to assign to data
    - map_variables: bool, map to standard variable names
    
    Returns:
    tuple: (data, metadata) where data is DataFrame and metadata is dict
    """

def get_psm3(latitude, longitude, api_key, email, names='tmy', **kwargs):
    """
    Get NSRDB PSM3 data.
    
    Parameters:
    - latitude: float, decimal degrees
    - longitude: float, decimal degrees
    - api_key: str, NREL API key
    - email: str, email address
    - names: str or list, data to retrieve
    
    Returns:
    tuple: (data, metadata)
    """

Weather Data I/O

Spectral Modeling

Model spectral irradiance and calculate spectral mismatch factors for different module technologies. Includes SPECTRL2 model and various spectral correction approaches.

def spectral_factor_firstsolar(precipitable_water, airmass_absolute, 
                              module_type=None, coefficients=None):
    """
    First Solar spectral correction factor.
    
    Parameters:
    - precipitable_water: numeric, cm
    - airmass_absolute: numeric
    - module_type: str, module technology
    - coefficients: array-like, custom coefficients
    
    Returns:
    numeric, spectral correction factor
    """

Spectral Models

Bifacial PV Systems

Model bifacial PV systems including view factor calculations, irradiance on both module surfaces, and specialized bifacial performance analysis.

def pvfactors_timeseries(solar_zenith, solar_azimuth, surface_azimuth, 
                        surface_tilt, axis_azimuth, timestamps, dni, dhi, 
                        gcr, pvrow_height, pvrow_width, albedo, **kwargs):
    """
    Run pvfactors timeseries simulation for bifacial systems.
    
    Parameters:
    - solar_zenith: array-like, degrees
    - solar_azimuth: array-like, degrees
    - surface_azimuth: numeric, degrees
    - surface_tilt: numeric, degrees
    - axis_azimuth: numeric, degrees  
    - timestamps: DatetimeIndex
    - dni: array-like, W/m^2
    - dhi: array-like, W/m^2
    - gcr: numeric, ground coverage ratio
    - pvrow_height: numeric, meters
    - pvrow_width: numeric, meters
    - albedo: numeric, ground reflectance
    
    Returns:
    tuple: (front_irradiance, back_irradiance, df_inputs)
    """

Bifacial Systems

Loss Modeling

Model various PV system losses including soiling, snow coverage, shading effects, and DC losses. Essential for realistic system performance predictions.

def kimber(rainfall, cleaning_threshold=6, soiling_loss_rate=0.0015, 
          grace_period=14, max_loss_factor=0.3):
    """
    Kimber soiling model.
    
    Parameters:
    - rainfall: numeric, daily rainfall (mm)
    - cleaning_threshold: numeric, rainfall threshold for cleaning (mm)
    - soiling_loss_rate: numeric, daily soiling loss rate
    - grace_period: numeric, days without loss after cleaning
    - max_loss_factor: numeric, maximum loss factor
    
    Returns:
    numeric, soiling loss factor
    """

Loss Models

Types

class Location:
    """
    Location object for solar calculations.
    
    Parameters:
    - latitude: float, decimal degrees
    - longitude: float, decimal degrees
    - tz: str, timezone
    - altitude: float, meters above sea level
    - name: str, location name
    """
    
    def get_solarposition(self, times, method='nrel_numpy', **kwargs):
        """Get solar position for this location."""
    
    def get_clearsky(self, times, model='ineichen', **kwargs):
        """Get clear sky irradiance for this location."""

class Array:
    """
    PV array representation.
    
    Parameters:
    - mount: AbstractMount, mounting configuration
    - albedo: numeric, ground reflectance
    - module: str or dict, module parameters
    - module_type: str, module technology type
    - module_parameters: dict, module model parameters
    - temperature_model_parameters: dict
    - name: str, array name
    """

class ModelChain:
    """
    High-level PV system modeling chain.
    
    Parameters:
    - system: PVSystem, system configuration
    - location: Location, geographic location
    - orientation_strategy: str, orientation determination method
    - clearsky_model: str, clear sky irradiance model
    - transposition_model: str, irradiance transposition model
    - solar_position_method: str, solar position algorithm
    - airmass_model: str, airmass calculation method
    - dc_model: str, DC power model
    - ac_model: str, AC power model
    - aoi_model: str, angle of incidence model
    - spectral_model: str, spectral correction model
    - temperature_model: str, temperature model
    - losses_model: str, system losses model
    - name: str, model chain name
    """
    
    def run_model(self, weather):
        """Run complete modeling chain with weather data."""