0
# pvlib Python
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: pvlib
7
- **Language**: Python
8
- **Installation**: `pip install pvlib`
9

10
## Core Imports
11

12
```python
13
import pvlib
14
```
15

16
Common import patterns for specific functionality:
17

18
```python
19
from pvlib import solarposition, irradiance, atmosphere, temperature
20
from pvlib import pvsystem, modelchain, location
21
from pvlib.pvsystem import PVSystem
22
from pvlib.location import Location
23
from pvlib.modelchain import ModelChain
24
```
25

26
## Basic Usage
27

28
```python
29
import pvlib
30
from pvlib import solarposition, irradiance, atmosphere, temperature
31
from pvlib import pvsystem, modelchain, location
32
import pandas as pd
33

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

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

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

45
# Calculate total irradiance on a tilted surface
46
surface_tilt = 30
47
surface_azimuth = 180
48
poa_irradiance = irradiance.get_total_irradiance(
49
    surface_tilt=surface_tilt,
50
    surface_azimuth=surface_azimuth,
51
    solar_zenith=solar_position['zenith'],
52
    solar_azimuth=solar_position['azimuth'],
53
    dni=clear_sky['dni'],
54
    ghi=clear_sky['ghi'],
55
    dhi=clear_sky['dhi']
56
)
57

58
print(poa_irradiance.head())
59
```
60

61
## Architecture
62

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

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

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

76
## Capabilities
77

78
### Solar Position Calculation
79

80
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.
81

82
```python { .api }
83
def get_solarposition(time, latitude, longitude, altitude=0, pressure=101325, 
84
                     temperature=12, method='nrel_numpy', **kwargs):
85
    """
86
    Calculate solar position using various algorithms.
87
    
88
    Parameters:
89
    - time: pandas.DatetimeIndex
90
    - latitude: float, decimal degrees
91
    - longitude: float, decimal degrees  
92
    - altitude: float, meters above sea level
93
    - pressure: float, pascals
94
    - temperature: float, degrees C
95
    - method: str, calculation method
96
    
97
    Returns:
98
    pandas.DataFrame with columns: apparent_zenith, zenith, 
99
    apparent_elevation, elevation, azimuth, equation_of_time
100
    """
101
```
102

103
[Solar Position](./solar-position.md)
104

105
### Irradiance Modeling
106

107
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.
108

109
```python { .api }
110
def get_total_irradiance(surface_tilt, surface_azimuth, solar_zenith, 
111
                        solar_azimuth, dni, ghi, dhi, **kwargs):
112
    """
113
    Calculate total irradiance on a tilted surface.
114
    
115
    Parameters:
116
    - surface_tilt: float, degrees from horizontal
117
    - surface_azimuth: float, degrees from north
118
    - solar_zenith: numeric, degrees
119
    - solar_azimuth: numeric, degrees  
120
    - dni: numeric, direct normal irradiance
121
    - ghi: numeric, global horizontal irradiance
122
    - dhi: numeric, diffuse horizontal irradiance
123
    
124
    Returns:
125
    OrderedDict with keys: poa_global, poa_direct, poa_diffuse, poa_sky_diffuse, poa_ground_diffuse
126
    """
127
```
128

129
[Irradiance](./irradiance.md)
130

131
### Atmospheric Modeling
132

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

135
```python { .api }
136
def get_relative_airmass(zenith, model='kastenyoung1989'):
137
    """
138
    Calculate relative airmass.
139
    
140
    Parameters:
141
    - zenith: numeric, solar zenith angle in degrees
142
    - model: str, airmass model
143
    
144
    Returns:
145
    numeric, relative airmass
146
    """
147

148
def get_absolute_airmass(airmass_relative, pressure=101325.0):
149
    """
150
    Calculate absolute airmass.
151
    
152
    Parameters:
153
    - airmass_relative: numeric, relative airmass
154
    - pressure: numeric, atmospheric pressure in pascals
155
    
156
    Returns:
157
    numeric, absolute airmass
158
    """
159
```
160

161
[Atmospheric Models](./atmosphere.md)
162

163
### Clear Sky Irradiance
164

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

167
```python { .api }
168
def ineichen(apparent_zenith, airmass_absolute, linke_turbidity, 
169
            altitude=0, dni_extra=1366.1):
170
    """
171
    Ineichen clear sky model.
172
    
173
    Parameters:
174
    - apparent_zenith: numeric, degrees
175
    - airmass_absolute: numeric
176
    - linke_turbidity: numeric
177
    - altitude: numeric, meters
178
    - dni_extra: numeric, extraterrestrial irradiance
179
    
180
    Returns:
181
    OrderedDict with keys: ghi, dni, dhi
182
    """
183
```
184

185
[Clear Sky Models](./clearsky.md)
186

187
### PV System Modeling
188

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

191
```python { .api }
192
class PVSystem:
193
    """
194
    Complete PV system representation.
195
    
196
    Parameters:
197
    - arrays: Array or iterable of Array
198
    - name: str, system name
199
    - inverter: dict, inverter parameters
200
    - inverter_parameters: dict, inverter model parameters
201
    - temperature_model_parameters: dict
202
    """
203

204
def singlediode(photocurrent, saturation_current, resistance_series, 
205
               resistance_shunt, nNsVth, ivcurve_pnts=None):
206
    """
207
    Single diode model for PV cells/modules.
208
    
209
    Parameters:
210
    - photocurrent: numeric, light current (A)
211
    - saturation_current: numeric, dark saturation current (A)
212
    - resistance_series: numeric, series resistance (ohm)
213
    - resistance_shunt: numeric, shunt resistance (ohm)  
214
    - nNsVth: numeric, thermal voltage parameter
215
    - ivcurve_pnts: int, number of IV curve points
216
    
217
    Returns:
218
    OrderedDict with keys: i_sc, v_oc, i_mp, v_mp, p_mp, i_x, i_xx, v_x, i, v
219
    """
220
```
221

222
[PV System Models](./pvsystem.md)
223

224
### Temperature Modeling
225

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

228
```python { .api }
229
def sapm_cell(poa_global, temp_air, wind_speed, a, b, deltaT, 
230
             irrad_ref=1000, temp_ref=25):
231
    """
232
    SAPM cell temperature model.
233
    
234
    Parameters:
235
    - poa_global: numeric, plane-of-array irradiance (W/m^2)
236
    - temp_air: numeric, ambient air temperature (C)
237
    - wind_speed: numeric, wind speed (m/s)
238
    - a: numeric, SAPM module parameter
239
    - b: numeric, SAPM module parameter  
240
    - deltaT: numeric, SAPM module parameter
241
    - irrad_ref: numeric, reference irradiance
242
    - temp_ref: numeric, reference temperature
243
    
244
    Returns:
245
    numeric, cell temperature (C)
246
    """
247
```
248

249
[Temperature Models](./temperature.md)
250

251
### Weather Data I/O
252

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

255
```python { .api }
256
def read_tmy3(filename, coerce_year=None, map_variables=True):
257
    """
258
    Read TMY3 files.
259
    
260
    Parameters:
261
    - filename: str, path to TMY3 file
262
    - coerce_year: int, year to assign to data
263
    - map_variables: bool, map to standard variable names
264
    
265
    Returns:
266
    tuple: (data, metadata) where data is DataFrame and metadata is dict
267
    """
268

269
def get_psm3(latitude, longitude, api_key, email, names='tmy', **kwargs):
270
    """
271
    Get NSRDB PSM3 data.
272
    
273
    Parameters:
274
    - latitude: float, decimal degrees
275
    - longitude: float, decimal degrees
276
    - api_key: str, NREL API key
277
    - email: str, email address
278
    - names: str or list, data to retrieve
279
    
280
    Returns:
281
    tuple: (data, metadata)
282
    """
283
```
284

285
[Weather Data I/O](./iotools.md)
286

287
### Spectral Modeling  
288

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

291
```python { .api }
292
def spectral_factor_firstsolar(precipitable_water, airmass_absolute, 
293
                              module_type=None, coefficients=None):
294
    """
295
    First Solar spectral correction factor.
296
    
297
    Parameters:
298
    - precipitable_water: numeric, cm
299
    - airmass_absolute: numeric
300
    - module_type: str, module technology
301
    - coefficients: array-like, custom coefficients
302
    
303
    Returns:
304
    numeric, spectral correction factor
305
    """
306
```
307

308
[Spectral Models](./spectrum.md)
309

310
### Bifacial PV Systems
311

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

314
```python { .api }
315
def pvfactors_timeseries(solar_zenith, solar_azimuth, surface_azimuth, 
316
                        surface_tilt, axis_azimuth, timestamps, dni, dhi, 
317
                        gcr, pvrow_height, pvrow_width, albedo, **kwargs):
318
    """
319
    Run pvfactors timeseries simulation for bifacial systems.
320
    
321
    Parameters:
322
    - solar_zenith: array-like, degrees
323
    - solar_azimuth: array-like, degrees
324
    - surface_azimuth: numeric, degrees
325
    - surface_tilt: numeric, degrees
326
    - axis_azimuth: numeric, degrees  
327
    - timestamps: DatetimeIndex
328
    - dni: array-like, W/m^2
329
    - dhi: array-like, W/m^2
330
    - gcr: numeric, ground coverage ratio
331
    - pvrow_height: numeric, meters
332
    - pvrow_width: numeric, meters
333
    - albedo: numeric, ground reflectance
334
    
335
    Returns:
336
    tuple: (front_irradiance, back_irradiance, df_inputs)
337
    """
338
```
339

340
[Bifacial Systems](./bifacial.md)
341

342
### Loss Modeling
343

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

346
```python { .api }
347
def kimber(rainfall, cleaning_threshold=6, soiling_loss_rate=0.0015, 
348
          grace_period=14, max_loss_factor=0.3):
349
    """
350
    Kimber soiling model.
351
    
352
    Parameters:
353
    - rainfall: numeric, daily rainfall (mm)
354
    - cleaning_threshold: numeric, rainfall threshold for cleaning (mm)
355
    - soiling_loss_rate: numeric, daily soiling loss rate
356
    - grace_period: numeric, days without loss after cleaning
357
    - max_loss_factor: numeric, maximum loss factor
358
    
359
    Returns:
360
    numeric, soiling loss factor
361
    """
362
```
363

364
[Loss Models](./losses.md)
365

366
## Types
367

368
```python { .api }
369
class Location:
370
    """
371
    Location object for solar calculations.
372
    
373
    Parameters:
374
    - latitude: float, decimal degrees
375
    - longitude: float, decimal degrees
376
    - tz: str, timezone
377
    - altitude: float, meters above sea level
378
    - name: str, location name
379
    """
380
    
381
    def get_solarposition(self, times, method='nrel_numpy', **kwargs):
382
        """Get solar position for this location."""
383
    
384
    def get_clearsky(self, times, model='ineichen', **kwargs):
385
        """Get clear sky irradiance for this location."""
386

387
class Array:
388
    """
389
    PV array representation.
390
    
391
    Parameters:
392
    - mount: AbstractMount, mounting configuration
393
    - albedo: numeric, ground reflectance
394
    - module: str or dict, module parameters
395
    - module_type: str, module technology type
396
    - module_parameters: dict, module model parameters
397
    - temperature_model_parameters: dict
398
    - name: str, array name
399
    """
400

401
class ModelChain:
402
    """
403
    High-level PV system modeling chain.
404
    
405
    Parameters:
406
    - system: PVSystem, system configuration
407
    - location: Location, geographic location
408
    - orientation_strategy: str, orientation determination method
409
    - clearsky_model: str, clear sky irradiance model
410
    - transposition_model: str, irradiance transposition model
411
    - solar_position_method: str, solar position algorithm
412
    - airmass_model: str, airmass calculation method
413
    - dc_model: str, DC power model
414
    - ac_model: str, AC power model
415
    - aoi_model: str, angle of incidence model
416
    - spectral_model: str, spectral correction model
417
    - temperature_model: str, temperature model
418
    - losses_model: str, system losses model
419
    - name: str, model chain name
420
    """
421
    
422
    def run_model(self, weather):
423
        """Run complete modeling chain with weather data."""
424
```