pvlib Python: A Comprehensive Guide to Solar Energy Simulation

5/5 - (1 vote)

If you’re interested in simulating the performance of photovoltaic energy systems, pvlib Python is a tool that can provide you with a set of functions and classes to do just that 🌞. Developed as a community-supported project, it was originally ported from the PVLIB MATLAB toolbox created at Sandia National Laboratories, incorporating numerous models and methodologies from the Labs πŸ§ͺ.

As you dive into pvlib Python, you’ll discover its powerful capabilities in modeling photovoltaic systems. By leveraging the extensive package, you can accurately simulate system performance and plan the best possible setup for your solar projects ⚑.

Keep in mind that being an open-source project, it constantly evolves thanks to the combined efforts of developers from all around the world 🌍.

In your journey with pvlib Python, you’ll be able to optimize energy production from photovoltaic installations and contribute to the shared knowledge and improvement of solar power solutions 🌱.

Overview of PVLIB Python

History and Background

PVLIB Python 🐍 is a powerful tool that was originally ported from the PVLIB MATLAB toolbox. Developed at Sandia National Laboratories, it now provides you with functions and classes for simulating the performance of photovoltaic energy systems β˜€οΈ.

Key Components

With PVLIB Python, you can:

  • Retrieve irradiance and weather data 🌦️
  • Calculate solar position β˜€οΈ
  • Model photovoltaic (PV) system components πŸ”§

You will find it versatile, as it implements many models and methods from the PVPMC modeling diagram. To make your job even easier, PVLIB Python’s documentation has theory topics, an intro tutorial, an example gallery, and an API reference πŸ“š.

Community Supported Tool

PVLIB Python is a community-supported tool available on GitHub, which means you are encouraged to collaborate with fellow users, contribute to its growth, and stay up to date with the latest versions. By being a part of this community, you’ll be among those who benefit from new features, bug fixes, and performance improvements 🌐.

To sum it up, PVLIB Python equips you with the necessary tools to model and simulate photovoltaic energy systems, enriching your understanding of PV performance πŸ‘©β€πŸ’ΌπŸ‘¨β€πŸ’Ό.

Installing PVLIB Python πŸš€

Before diving headfirst into using PVLIB Python, you need to install it on your system. Don’t worry; it’s a breeze! Just follow these simple steps. Keep in mind that PVLIB Python requires the following packages: numpy and pandas.

To install PVLIB Python, use pip by running the command in your terminal:

pip install pvlib

πŸŽ‰ Congrats! You’ve successfully installed PVLIB Python.

If you want to experiment with the NREL SPA algorithm, follow these instructions:

  1. Obtain the source code by downloading the pvlib repository.
  2. Download the SPA files from NREL.
  3. Copy the SPA files into pvlib-python/pvlib/spa_c_files.
  4. From the pvlib-python directory, run:
pip uninstall pvlib
pip install .

That’s all it takes! You’re all set for exploring PVLIB Python and simulating photovoltaic energy systems performance. Happy coding! πŸ’»πŸŒž

PVLIB Python Models and Methods


PVLIB Python provides a variety of models for simulating the performance of photovoltaic energy systems 🌞. Originally ported from the PVLIB MATLAB toolbox developed at Sandia National Laboratories, it implements many of the models and methods used in PV performance modeling programs.

You’ll find models for irradiance and clear sky data, solar position, atmospheric and temperature data, as well as modules and inverter specifications. Utilizing these models, you can accurately predict the performance of your PV system based on various factors πŸ“Š.


Beyond the models, PVLIB Python also implements various methods to streamline the calculation and analytical processes associated with PV energy systems πŸ’‘.

These methods help determine system output by computing factors like irradiance components, spectral loss, and temperature coefficients. PVLIB provides methods for various tracking algorithms and translation functions that transform diffuse irradiance to the plane of array.

Additionally, PVLIB Python offers a collection of classes that cater to users with a preference for object-oriented programming πŸ–₯️.


In its documentation, PVLIB Python offers a comprehensive set of functions and classes for various tasks essential in simulating the performance of a PV energy system. Some essential functions include:

  • Functions for calculating solar position and extraterrestrial radiation πŸ’«
  • Functions for clear sky irradiance and atmospheric transmittance ☁️
  • Functions for processing irradiance data and PV module data ⚑
  • Functions for modeling PV system components like DC and AC power output πŸ”‹

By combining and implementing these functions, you can create a detailed and accurate simulation of your PV system under varying conditions and parameters 🌐.

PVLIB Example

The following code example calculates the annual energy yield of photovoltaic systems at different locations using the PVLIB library. It creates a function calculate_annual_energy() that takes in location coordinates, TMY3 weather data, module parameters, temperature model parameters, and inverter parameters.

The function uses PVLIB’s ModelChain to simulate the energy yield for each location and stores the results in a pandas Series. Finally, the code prints and plots the annual energy yield in a bar chart for visual comparison.

import pandas as pd
import matplotlib.pyplot as plt
from pvlib.pvsystem import PVSystem, Array, FixedMount
from pvlib.location import Location
from pvlib.modelchain import ModelChain

def calculate_annual_energy(coordinates, tmys, module, temperature_model_parameters, inverter):
    energies = {}
    for location, weather in zip(coordinates, tmys):
        latitude, longitude, name, altitude, timezone = location
        loc = Location(latitude, longitude, name=name, altitude=altitude, tz=timezone)
        mount = FixedMount(surface_tilt=latitude, surface_azimuth=180)
        array = Array(
        system = PVSystem(arrays=[array], inverter_parameters=inverter)
        mc = ModelChain(system, loc)
        annual_energy = mc.results.ac.sum()
        energies[name] = annual_energy

    return pd.Series(energies)

energies = calculate_annual_energy(coordinates, tmys, module, temperature_model_parameters, inverter)

energies.plot(kind='bar', rot=0)
plt.ylabel('Yearly energy yield (W hr)')

This code snippet defines a function calculate_annual_energy() that computes the annual energy yield for different locations using the PVLIB library. It then prints the energies and plots them in a bar chart.

Here’s a detailed explanation of the code:

  1. Import necessary libraries:
    • pandas for handling data manipulation and analysis
    • matplotlib.pyplot for creating plots and visualizations
    • PVSystem, Array, and FixedMount from pvlib.pvsystem for modeling photovoltaic systems
    • Location from pvlib.location for creating location objects
    • ModelChain from pvlib.modelchain for simulating the energy yield of a photovoltaic system
  2. Define the calculate_annual_energy() function:
    • The function takes five arguments:
      • coordinates: a list of tuples containing location information (latitude, longitude, name, altitude, and timezone)
      • tmys: a list of TMY3 weather data for each location in the coordinates list
      • module: a dictionary containing photovoltaic module parameters
      • temperature_model_parameters: a dictionary containing temperature model parameters
      • inverter: a dictionary containing inverter parameters
  3. Initialize an empty dictionary energies to store the annual energy yield for each location.
  4. Loop through the coordinates and tmys lists simultaneously using the zip() function:
    • Extract the latitude, longitude, name, altitude, and timezone from the location tuple
    • Create a Location object loc with the extracted information
    • Create a FixedMount object mount with the surface tilt equal to the latitude and surface azimuth equal to 180 (facing south)
    • Create an Array object array with the mount, module_parameters, and temperature_model_parameters
    • Create a PVSystem object system with the arrays and inverter_parameters
    • Create a ModelChain object mc with the system and loc
    • Run the model with the TMY3 weather data weather
    • Calculate the annual energy by summing the AC output (mc.results.ac.sum()) and store it in the energies dictionary with the location name as the key
  5. Return a pandas Series object created from the energies dictionary.
  6. Call the calculate_annual_energy() function with the required input variables (coordinates, tmys, module, temperature_model_parameters, and inverter), and store the result in the energies variable.
  7. Print the energies pandas Series.
  8. Create a bar plot of the energies pandas Series, rotating the x-axis labels to 0 degrees and setting the y-axis label to 'Yearly energy yield (W hr)'. Finally, display the plot using plt.show().

PVLIB Matlab Toolbox

As someone interested in simulating the performance of photovoltaic energy systems, you’ll appreciate the PVLIB Matlab Toolbox. This is a set of well-documented functions designed to model PV system performance 🌞, and it was developed at Sandia National Laboratories (SNL). The toolbox has evolved into the PVLIB Python version we know today, but the Matlab version is still available and useful for those who prefer it or are working within a Matlab environment.

Now, let’s dive into some of the features you’ll find in the PVLIB Matlab Toolbox! It consists of various functions tailored to achieve tasks such as solar position calculations, irradiance and temperature models, and direct current power modeling. As a user of this toolbox, you can compare various PV systems and assess their performance β˜€οΈ.

One thing you’ll love as a user of PVLIB Matlab Toolbox is the active community support πŸŽ‰. The development of the toolbox, as well as its Python counterpart, is rooted in the collaboration of the PV Performance Modeling Collaborative (PVPMC). So, if you encounter any challenges or require assistance, there is a community of experts ready to help and contribute to the ongoing development of the toolbox.

In terms of accessibility, the PVLIB Matlab Toolbox is also available in a Python version, called PVLIB Python. If you are more comfortable working in Python or your projects are in this programming language, PVLIB Python retains the models and methods that made the Matlab Toolbox valuable while also building upon its core capabilities with new features and enhancements πŸš€.

Projects, Tutorials, and Publications

In this section, you’ll learn about various projects and publications that utilize pvlib Python.

Journal Articles

One notable publication using pvlib Python is by William F. Holmgren, Clifford W. Hansen, and Mark A. Mikofski. They authored a paper titled pvlib python: a python package for modeling solar energy systems. This paper is published in the Journal of Open Source Software and focuses on solar energy system modeling using the pvlib python package.

When citing this paper, you can use the DOI provided or find the publication on zenodo.org. Make sure to check the installation page for using pvlib python in your research. πŸ§ͺ

Commercial Projects

In the commercial space, pvlib python has been adopted by various companies as a valuable tool for simulating the performance of photovoltaic energy systems. These organizations include scientific laboratories, private industries, and other sectors that require accurate solar energy system modeling. 🏭

Publicly-Available Applications

A number of publicly-available applications also take advantage of pvlib python. A GitHub wiki page lists various projects and publications using this comprehensive package for modeling solar energy systems, offering inspiration and a potential listing for your application.

As you work with pvlib python, remember to adhere to the variable naming convention to ensure consistency throughout the library. This will help you and others collaboratively build more robust solar energy system models. β˜€οΈ

Wiki and Documentation

Discover how to get started with pvlib Python through its official documentation. This comprehensive guide will help you explore pvlib Python’s functions and classes for simulating the performance of photovoltaic energy systems. Make the most of your pvlib Python experience by referring to the community-supported online wiki containing tutorials and sample projects for newcomers.

Check out this and more graphics at the official source: https://pvsc-python-tutorials.github.io/PVSC48-Python-Tutorial/Tutorial%200%20-%20Overview.html

Jupyter Notebook Tutorials

πŸ““ Enhance your learning with Jupyter Notebook tutorials designed to offer hands-on experience in simulating PV systems. Through interactive examples, you’ll go from understanding common PV systems data to modeling the energy output of a single-axis tracker system. Access these tutorials here.

Solar Power Forecasting Tool

You might be interested in the solar power forecasting tool provided by pvlib Python. This community-supported tool offers a set of functions and classes for simulating the performance of photovoltaic energy systems. Pvlib Python was initially a port of the PVLIB MATLAB toolbox developed at Sandia National Laboratories 🌞 (source)

J. S. Stein, R.W. Andrews, A.T. Lorenzo, J. Forbess, and D.G. Groenendyk are among the experts who contributed to the development of an open-source solar power forecasting tool using the pvlib Python library. This tool aims to efficiently model and analyze photovoltaic systems, offering features that enable users like you to better understand solar power forecasting πŸ“Š (source)

What makes pvlib Python a powerful resource for you is its well-documented functions for simulating photovoltaic system performance. It can help you forecast solar power production based on various parameters, enabling you to make informed decisions on your solar energy projects 🌐 (source)

When using pvlib Python, you’ll appreciate the flexibility of choosing from different models and methods for both weather forecast data and solar power prediction, addressing your specific needs or research interests β˜€οΈ (source)

So, if solar power forecasting is essential for you, give pvlib Python a try and explore the possibilities it offers. Remember, pvlib Python is part of the growing open-source community, and it’s continuously evolving, ensuring that it stays on top of the latest advancements in photovoltaic energy systems πŸ”‹(source)

Thanks for reading the whole tutorial! β™₯️ If you want to stay up-to-date with the latest developments in Python and check out our free Python cheat sheets, feel free to download all of them here: