Skip to main content

2D View Factor Model to calculate the irradiance incident on various surfaces of PV arrays

Project description

pvfactors: irradiance modeling made simple

CircleCI license

pvfactors is a tool used by PV professionals to calculate the irradiance incident on surfaces of a photovoltaic array. It relies on the use of 2D geometries and view factors integrated mathematically into a linear system of equations to account for reflections between all of the surfaces.

pvfactors was originally ported from the SunPower developed 'vf_model' package, which was introduced at the IEEE PV Specialist Conference 44 2017 (see [1] and link to paper).


The documentation can be found here. It includes a lot of tutorials that describe many ways of using pvfactors.

Quick Start

Given some timeseries inputs:

# Import external libraries
from datetime import datetime
import pandas as pd

# Create input data
df_inputs = pd.DataFrame(
    {'solar_zenith': [20., 50.],
     'solar_azimuth': [110., 250.],
     'surface_tilt': [10., 20.],
     'surface_azimuth': [90., 270.],
     'dni': [1000., 300.],
     'dhi': [50., 500.],
     'albedo': [0.2, 0.2]},
    index=[datetime(2017, 8, 31, 11), datetime(2017, 8, 31, 15)]
albedo dhi dni solar_azimuth solar_zenith surface_azimuth surface_tilt
2017-08-31 11:00:00 0.2 50.0 1000.0 110.0 20.0 90.0 10.0
2017-08-31 15:00:00 0.2 500.0 300.0 250.0 50.0 270.0 20.0

And some PV array parameters

pvarray_parameters = {
    'n_pvrows': 3,            # number of pv rows
    'pvrow_height': 1,        # height of pvrows (measured at center / torque tube)
    'pvrow_width': 1,         # width of pvrows
    'axis_azimuth': 0.,       # azimuth angle of rotation axis
    'gcr': 0.4,               # ground coverage ratio
    'rho_front_pvrow': 0.01,  # pv row front surface reflectivity
    'rho_back_pvrow': 0.03    # pv row back surface reflectivity

The users can run a timeseries simulation using the PVEngine

from pvfactors.engine import PVEngine

# Create engine
engine = PVEngine(pvarray_parameters)
# Fit engine to data, df_inputs.dni, df_inputs.dhi,
           df_inputs.solar_zenith, df_inputs.solar_azimuth,
           df_inputs.surface_tilt, df_inputs.surface_azimuth,

For a single timestamp

# Import external libraries
import matplotlib.pyplot as plt

# Get pvarray at given timestamp
pvarray = engine.run_timestep(idx=1)

# Plot pvarray shapely geometries
f, ax = plt.subplots(figsize=(10, 3))

The user can inspect the results very easily thanks to the simple geometry API

print("Incident irradiance on front surface of middle pv row: {} W/m2"
print("Reflected irradiance on back surface of left pv row: {} W/m2"
print("Isotropic irradiance on back surface of right pv row: {} W/m2"
Incident irradiance on front surface of middle pv row: 811.7 W/m2
Reflected irradiance on back surface of left pv row: 90.2 W/m2
Isotropic irradiance on back surface of right pv row: 9.3 W/m2

The users can also run simulations for all timestamps, and obtain a "report" that will look like whatever the users want, and which will rely on the simple geometry API shown above. Here is an example:

# Create a function that will build a report
from import example_fn_build_report

# Run full simulation
report = engine.run_all_timesteps(fn_build_report=example_fn_build_report)

# Print results (report is defined by report function passed by user)
df_report = pd.DataFrame(report, index=df_inputs.index)
100%|██████████| 2/2 [00:00<00:00, 26.58it/s]
qinc_back iso_back qinc_front iso_front
2017-08-31 11:00:00 106.627832 0.115792 1034.967753 20.848345
2017-08-31 15:00:00 85.535537 6.304878 811.659036 276.181750


pvfactors is currently compatible and tested with Python versions 2.7 and 3.6, and is available in PyPI.

The easiest way to install pvfactors is to use pip as follows:

$ pip install pvfactors

The package wheel files are also available in the release section of the Github repository.


Requirements are included in the requirements.txt file of the package. Here is a list of important dependencies:

Citing pvfactors

We appreciate your use of pvfactors. If you use pvfactors in a published work, we kindly ask that you cite:

Anoma, M., Jacob, D., Bourne, B.C., Scholl, J.A., Riley, D.M. and Hansen, C.W., 2017. View Factor Model and Validation for Bifacial PV and Diffuse Shade on Single-Axis Trackers. In 44th IEEE Photovoltaic Specialist Conference.


Contributions are needed in order to improve pvfactors. If you wish to contribute, you can start by forking and cloning the repository, and then installing pvfactors using pip in the root folder of the package:

$ pip install .

To install the package in editable mode, you can use:

$ pip install -e .


[1] Anoma, M., Jacob, D., Bourne, B. C., Scholl, J. A., Riley, D. M., & Hansen, C. W. (2017). View Factor Model and Validation for Bifacial PV and Diffuse Shade on Single-Axis Trackers. In 44th IEEE Photovoltaic Specialist Conference.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pvfactors, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size pvfactors-1.0.0-py2.py3-none-any.whl (12.7 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size pvfactors-1.0.0.tar.gz (28.9 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page