What Is pvlib? How Physics-Based Solar Modeling Works
Last updated: 2026-04-08 · Solar Benchmark
What Is pvlib? How Physics-Based Solar Modeling Works
pvlib is an open-source Python library for simulating photovoltaic system performance. Developed with support from NREL (National Renewable Energy Laboratory), it implements peer-reviewed physical models that convert weather data and system specifications into hour-by-hour energy output estimates. Models built on pvlib with ERA5 weather data achieve approximately 5-7% monthly deviation from measured production.
Definition and How It Works
pvlib takes two categories of inputs and produces one output. The inputs are weather data (irradiance, air temperature, wind speed) and system parameters (panel specifications, tilt angle, azimuth, inverter efficiency curve, array layout). The output is expected energy production for each hour of the simulation period.
The library implements a chain of physical models, each handling one stage of the conversion from sunlight to grid power:
- Perez transposition model: Converts GHI, DNI, and DHI (measured on a horizontal surface) into GTI (global tilted irradiance), the actual radiation striking a panel at its installed angle and orientation.
- Faiman temperature model: Calculates panel operating temperature from air temperature, irradiance, and wind speed. Panels lose about 0.3-0.5% of output per degree Celsius above their rated temperature, so this step significantly affects accuracy.
- CEC module model: Uses parameters from the California Energy Commission module database to model each panel's current-voltage relationship at actual operating conditions.
- Single diode model: Solves the panel's electrical circuit equations to determine maximum power point output.
The result is a physically grounded estimate of what any specific system should have produced given the actual weather at that location. See the full methodology for how these models are combined in practice.
pvlib vs PVWatts: Key Differences
| Attribute | pvlib (physics-based) | PVWatts (NREL simplified) |
|---|---|---|
| Weather input | Actual hourly ERA5 data | TMY (30-year statistical average) |
| Performance ratio | Calculated from system physics | Fixed at 0.78 |
| Monthly accuracy | ~5-7% deviation from measured | ~38% deviation from measured |
| Panel model | CEC database parameters | Generic efficiency percentage |
| Primary use | Month-by-month performance benchmarking | Pre-install production estimates |
PVWatts uses a Typical Meteorological Year (TMY) dataset, which is a statistical composite of average weather. It is designed for pre-installation financial estimates, not for comparing actual production to an expected baseline in any specific month. In any given month, actual weather can differ substantially from the TMY average, making PVWatts unsuitable for diagnosing whether a system underperformed.
What pvlib Means for Homeowners
Most solar monitoring platforms answer: "What did my system produce?" pvlib answers the more useful question: "What should my system have produced this month, given the actual weather?"
When a homeowner notices lower-than-expected production in November, the critical question is whether November was simply a cloudy month (normal) or whether the system is underperforming relative to what the available sunlight warranted (a problem). Without a physics-based expected production model, there is no way to separate weather from equipment issues.
pvlib-based models that use actual ERA5 weather data for the simulation period provide that separation. The gap between expected (model) and actual (monitored) production is the performance signal that identifies real problems.
Frequently Asked Questions
Does pvlib require specialized software to use? pvlib is a Python library, so using it directly requires Python programming knowledge. However, services and tools can run pvlib calculations on the backend and present the results without requiring the homeowner to write any code. The underlying model is open-source and auditable regardless of how it is accessed.
Why does pvlib use the CEC module database instead of just panel spec sheets? The CEC database contains five electrical parameters per panel that are derived from measured testing, not just the headline watt rating on the spec sheet. These parameters allow the model to accurately simulate panel behavior across the range of temperatures and irradiance levels a panel experiences in the field, not just at standard test conditions (25°C, 1,000 W/m²).
Is a 5-7% monthly deviation good enough to detect real problems? Yes. Inverter failures, significant shading from new obstructions, or clipping issues produce deviations well above 10%. A physics-based model accurate to 5-7% can reliably flag systems that are underperforming by more than one standard deviation from expected output, which is the threshold for actionable investigation.
Data: pvlib physics modeling + Open-Meteo ERA5 weather data | Last updated: 2026-04-08 | Solar Benchmark