1

Introduction to the Open Source PV LIB for Python Photovoltaic SystemModelling Package

Robert W. Andrews 1, Joshua S. Stein 2, Clifford Hansen2, and Daniel Riley 21 Calama Consulting, Toronto, Ontario, M5T1B3, Canada

2Sandia National Laboratories, Albuquerque, NM, 87185, USA

Abstract—The proper modeling of Photovoltaic(PV) systemsis critical for their financing, design, and operation. PV LIBprovides a flexible toolbox to perform advanced data analysisand research into the performance modeling and operations ofPV assets, and this paper presents the extension of the PV LIBtoolbox into the python programming language. PV LIB providesa common repository for the release of published modelingalgorithms, and thus can also help to improve the quality andfrequency of model validation and inter comparison studies.Overall, the goal of PV LIB is to accelerate the pace of innovationin the PV sector.

Index Terms—PV modelling, software, data analysis, perfor-mance modelling

I. INTRODUCTION

THE proper modeling of a photovoltaic (PV) systemis critical to its technical and financial success. Many

commercial integrated software packages are available andaccepted in industry: for example PVsyst, Helioscope, SAM,PVWatts and others provide the ability for designers to assesthe potential output and revenue from a PV system. Thesepackages are particularly adept at answering the followingdesign questions:

• Overall system output given irradiance information.• Sizing and specification of major components (inverters,

panels, combiners).• Shading and loss factors analysis.And they are able to provide these results in a form

which is accepted in the technical and financial industries (i.ebankable). This is due to the traceability of their algorithmsand the familiarity of the industry with these outputs.

However, because of the integrated nature of these simu-lations packages, there is a lack in flexibility of simulationswhich the package can perform. This means that designers andresearchers cannot create customized and integrated tools forexploring advanced topics in PV performance analysis.Theseadvanced tools are often required to perform detailed analysesof system performance, and to allow innovation in the deploy-ment of PV technologies. Examples of questions which are noteasily answered with integrated modeling packages are:

• Comparisons of performance outputs using varying mod-els and assumptions

• Large scale parametric analyses of multiple datasets(though some newer models are allowing this)

• Ability to modify, customize, and update modeling algo-rithms

• Automated integration into external workflows, eg. auto-mated performance assessments

• Ability to view intermediary modeling results and per-form on-the-fly statistical analyses

Thus, those requiring the ability to perform more advanceddata analysis will generally create custom algorithms inprograms such as MATLAB, R, Python, or in spreadsheetprograms. These algorithms are generally based on publishedliterature or understood industry best practice, however theprocess of creating new algorithms based on these sources istime consuming and can lead to errors or mis-interpretations,and are generally difficult to individually validate.

In order to address these issues, Sandia National Laborato-ries has developed PV LIB [1], a collaboratively developedopen source PV modeling environment. This environmentconsists of modeling algorithms which can be used in isolationor in combination to analyze all portions of the PV systemmodeling work flow.

II. THE PV LIB CONCEPT

The vision for PV LIB is to become a standard repositoryfor high quality PV related analysis algorithms. Put simply, analgorithm can be published in a journal, conference, or whitepaper, and the code can be published through PV LIB.

This code is open-source, collaboratively developed andvalidated, and it is hoped that the release of this code willaccelerate the development of the PV industry for the follow-ing reasons:

• Create a linkage between researchers and implemen-tors Authors of new algorithms can present them in aformat which can be adopted into modeling work flowsquickly and and at a low cost

• Provide validated tools to groups which do not havethe ability to develop them Many industry and researchgroups do not have the ability to develop algorithms foradvanced data analysis, and are limited by the capabil-ities of spreadsheet software and commercial integratedanalysis packages

• Increase the efficiency of PV research Many researchprojects in PV performance require the development ofan initial testing and modeling suite before new researchcan begin. By providing a high quality and validated tool-set for the basis of research, the rate of innovation canbe accelerated

• Enable faster, reliable model inter-comparisons andvalidations Models integrated into the PV LIB Packagecan be easily compared and validated in a reproducibleway.

• Increase the quality of communication between de-velopers, Independent Engineers (IEs), and financiers

2

By providing a common modeling platform for advanceddata analysis, the communication of complex data anal-ysis can be simplified and shared in a reproducible way.

• Provide tools to efficiently handle large datasets Theanalysis of data on hourly or minutely timescales canprovide valuable insights into system performance, andspreadsheet programs are generally not able to handle thevolume of data associated with these datasets. Using ef-ficient code and the ability to parallelize some operationsmeans that high resolution data can be analyzed.

• Collaboration can increase the pace of technologyinnovation in the sector Because the future expansionof PV LIB will be based on the contributions of thePV community, new analysis methodologies and bestpractices can be quickly adopted by the sector.

III. THE PV LIB PACKAGE

The PV LIB software package currently exists as a set ofPython and MATLAB scripts which perform system perfor-mance calculations, and represent a large portion of currentlypublished system performance and atmospheric functions.

These algorithms can be used in isolation to investigatea certain portion of PV performance evaluation, or can beused in combination to fully simulate a PV array, and aresummarized in Table I.

A. Python PV LIB

The Python programming language is a free and opensource programming environment which has been shown tobe very well suited to scientific computations [2], [3], [4]. Akey feature of Python is it’s flexibility to handle computationfrom small scale to large highly parallelized high performancecomputing operations [5] and because of this is able to scaleeasily, with no costs, to a users demands and requirements.

In addition, the Python language is supported by a vi-brant community of developers, and new features are activelyadded and maintained. Because of this, integration with web,database and graphically intensive processes are relativelysimple and intuitive in the system, allowing for a greaterflexibility when developing models and algorithms. [6]

Python is also designed to be easily written and interpreted,and because of the high-level nature of the code is easilylearned and understood by those with a basic understandingof programming syntax.

As PV LIB develops into the Python programming lan-guage, it will feature three main principles:

• Take advantage of the Python programming language, toensure free access to academic and commercial users

• Designed for collaborative development, and backed bya rigorous method to include the contributions of authorsand researchers into the package

• Backed by a full testing and validation suite- to ensurestability of the package and to allow for validation ofmodel results against real-world performance data.

IV. COLLABORATIVE SOFTWARE DEVELOPMENT

The Python version of PV LIB will be designed and main-tained to allow for collaborative development of the softwareusing the open source model. [7], [8]

The full set of code is maintained on the Git Hub collab-orative revision control system and it is possible for thoseinterested in using or modifying the code base to create a’fork’ of the code onto their local systems. The users can thenuse or modify the code on their local machines. If a bug isfixed or a new function is developed, a request can be madethrough the GitHub system to integrate it into the main codebase.

Requests to merge a change into the code base are thenreviewed by the maintainers of the code, and if accepted canbe integrated and merged into the code of those utilizing thecode. At specified milestones, official version updates will bereleased which will integrate the latest updates into a downloadable package.

A. User demographicsThere is a distinction made between two categories of

expected users of the PV LIB package: Users and Developers

Users Users are concerned with using high level modulesto develop analysis workflows. They would take advantage ofpre-defined modules, but wouldn’t generally dive into theirback end function or development. It is assumed that theywill generally interact with PV LIB through the ’Ipythonnotebook’ environment, shown in Figure 1

Developers Though developers would be interested in theend result of developing new analysis workflows, they wouldalso be concerned with the back end development of analysismodules. This would include the development of algorithmsand the creation of algorithmic and physical testing suites.

B. Testing requirementsAlgorithms integrated into the PV LIB Python package

will require algorithmic and physical testing packages. Thespecific requirements for these are published on the PV LIBwebsite.

Algorithmic testing packages ensure that the module willoperate properly under all reasonable conditions imposed onit by users , including logical error handling.

Physical physical testing should include a validationdataset which demonstrates the implied function of thealgorithm. This provides users with an accessible methodof ensuring the accuracy of results and ensuring thephysical validity of their models. Validation datasets must beincluded directly in the testing file, and should not rely onexternal datasets to ensure stability of the validation over time.

In order to ensure repeatable results, a version trackingsystem is also included in PV LIB which will provide astandard method to document the algorithms and versionswhich were used in a particular simulation.

3

TABLE IFUNCTIONS INCLUDED IN VERSION 1.1 OF PV LIB . ALL REFERENCES ARE INCLUDED IN THE ON LINE PV LIB DOCUMENTATION

Irradiance and atmospheric functionspvlib.pvl_alt2pres(altitude) Determine site pressure from altitudepvlib.pvl_pres2alt(pressure) Determine altitude from site pressurepvlib.pvl_getaoi(SurfTilt, SurfAz, SunZen, SunAz) Determine angle of incidence from surface tilt/azimuth and apparent sun zenith/azimuthpvlib.pvl_disc(GHI, SunZen, Time[, pressure]) Estimate Direct Normal Irradiance from Global Horizontal Irradiance using the DISC

modelpvlib.pvl_ephemeris(Time, Location[, ...]) Calculates the position of the sun given time, location, and optionally pressure and

temperaturepvlib.pvl_spa(Time, Location) Calculate the solar position using the PySolar packagepvlib.pvl_extraradiation(doy) Determine extraterrestrial radiation from day of yearpvlib.pvl_globalinplane(SurfTilt, SurfAz, ...) Determine the three components on in-plane irradiancepvlib.pvl_grounddiffuse(SurfTilt, GHI, Albedo) Estimate diffuse irradiance from ground reflections given irradiance, albedo, and surface

tiltpvlib.pvl_makelocationstruct(latitude, ...) Create a structure to define a site locationpvlib.pvl_relativeairmass(z[, model]) Gives the relative (not pressure-corrected) airmasspvlib.pvl_absoluteairmass(AMrelative, Pressure) Determine absolute (pressure corrected) airmass from relative airmass and pressurepvlib.pvl_clearsky_ineichen(Time, Location) Determine clear sky GHI, DNI, and DHI from Ineichen/Perez modelpvlib.pvl_clearsky_haurwitz(ApparentZenith) Determine clear sky GHI from Haurwitz model

Irradiance Translation Functionspvlib.pvl_perez(SurfTilt, SurfAz, DHI, DNI, ...) Determine diffuse irradiance from the sky on a tilted surface using one of the Perez

modelspvlib.pvl_haydavies1980(SurfTilt, SurfAz, ...) Determine diffuse irradiance from the sky on a tilted surface using Hay & Davies’ 1980

modelpvlib.pvl_isotropicsky(SurfTilt, DHI) Determine diffuse irradiance from the sky on a tilted surface using isotropic sky modelpvlib.pvl_kingdiffuse(SurfTilt, DHI, GHI, SunZen) Determine diffuse irradiance from the sky on a tilted surface using the King modelpvlib.pvl_klucher1979(SurfTilt, SurfAz, DHI, ...) Determine diffuse irradiance from the sky on a tilted surface using Klucher’s 1979

modelpvlib.pvl_reindl1990(SurfTilt, SurfAz, DHI, ...) Determine diffuse irradiance from the sky on a tilted surface using Reindl’s 1990 model

Data Handlingpvlib.pvl_readtmy2(FileName) Read a TMY2 file in to a DataFramepvlib.pvl_readtmy3(FileName) Read a TMY3 file in to a DataFrame

System Modeling functionspvlib.pvl_physicaliam(K, L, n, theta) Determine the incidence angle modifier using refractive modelspvlib.pvl_ashraeiam(b, theta) Determine the incidence angle modifier using the ASHRAE transmission modelpvlib.pvl_calcparams_desoto(S, Tcell, ...[, ...]) Applies the temperature and irradiance corrections to inputs for pvl singlediodepvlib.pvl_retreiveSAM(name[, FileLoc]) Retrieve latest module and inverter info from SAM websitepvlib.pvl_sapm(Module, Eb, Ediff, Tcell, AM, AOI) Performs Sandia PV Array Performance Model to get 5 points on IV curve given SAPM

module parameters, Ee, andcell temperaturepvlib.pvl_sapmcelltemp(E, Wspd, Tamb[, modelt]) Estimate cell temperature from irradiance, wind speed, ambient temperature, and module

parameters (SAPM)pvlib.pvl_singlediode(Module, IL, I0, Rs, ...) Solve the single-diode model to obtain a photovoltaic IV curvepvlib.pvl_snlinverter(Inverter, Vmp, Pmp) Converts DC power and voltage to AC power using Sandia’s Grid-Connected PV Inverter

modelpvlib.pvl_systemdef(TMYmeta, SurfTilt, ...) Generates a dictionary of system parameters used throughout a simulation

C. Code examples

Developers wising to contribute to the PV LIB packagewill be require to adhere to PV LIB coding standards fordocumentation and function creation. Docstrings (functiondescriptive headers) should be included for all functions andformatted according to the current google python docstringstandard, and functions should adhere to the google pythonstyle guide where possible. An example of the basic layoutof a function and it’s test function is shown below. Note thatthe data included in a physical function test must be includedin the same file as the test script to ensure stability of thetesting package over time.

Function Code

’’’Attribution blockDeveloped by: name, organizationDate:

Revision 1: name, organizationDate:’’’import modulesdef pvl Fcn ( I n p u t s ,∗∗ kwargs ) :

’’’Function DescriptionParameters----------Input name: format

Input DescriptionReturns-------Output name: format

Output Description’’’Vars= l o c a l s ( )Expec t ={’Input1’ : ( ’num’ ,’x>0’ )

# Numer ica l l o g i c a l c o n t s r a i n t s’Input2’ : ( ’str’ , (’option1’ ,’option2’ )

# S t r i n g dependancy c o n s t r a i n t s’Inputopt’ : ( ’Optional’ )}

4

#Kwargs i n p u tv a r = p v l i b . p v l t o o l s . P a r s e ( Vars , Expec t )

f u n c t i o n b o d y p r o d u c i n g o u t p u t

re turn Outpu t

Testing Code

’’’Attribution blockDeveloped by: name, organization

Date:Revision 1: name, organization

Date:’’’from nose . t o o l s import ∗from . . import p v l f c nimport modulesdef t e s t p r o p e r a l g o r i t h m i c l ( ) :

#Run t h e f u n c t i o n w i t h m u l t i p e o f i n p u t s# t o e n s u r e i t h a n d l e s edge c a s e s p r o p e r l yp v l f c n ( I n p u t s )a s s e r t ( a l g o r i t h m i c t e s t p a s s e s )

def t e s t p r o p e r p h y s i c a l ( ) :# i n p u t s r e p r e s e n t i n g a p h y s i c a l t e s t case , can be#numpy a r r a y or DataFrameI n p u t s =np . a r r a y ( [ P h y s c i a l d a t a ] )# p h y s i c a l l y c o r r e c t o u t p u t s , can be numpy a r r a y or#DataFrameo u t p u t =np . a r r a y ( [ P h y s c i a l d a t a ] )# run t h e f u n c t i o no u t p u t a l g o r i t h m = p v l f c n ( I n p u t s )# check i t ’ s v a l i d i t ya s s e r t ( o u t p u t a l g o r i t h m == o u t p u t )

def main ( ) :u n i t t e s t . main ( )

i f name == ’__main__’ :main ( )

D. Licenses

PV LIB is licensed under the BSD 3 clause which is quotedin part below:

Redistribution and use in source and binaryforms, with or without modification, are permittedprovided that the following conditions are met:

1. Redistributions of source code must retain theabove copyright notice, this list of conditions andthe following disclaimer.

2. Redistributions in binary form must reproducethe above copyright notice, this list of conditionsand the following disclaimer in the documentationand/or other materials provided with the distribu-tion.

3. Neither the name of the copyright holdernor the names of its contributors may be usedto endorse or promote products derived from thissoftware without specific prior written permission.

The intention is to enable users to integrate the codeinto other projects or programs while ensuring that propertraceability and attribution of the code is maintained.

V. USING PV LIB FOR PYTHON

PV LIB is created in the Python programming language,and can used alongside a powerful suite of Python modulesto enable powerful options for data analysis including:

Numpy Numerical and statistical analysis tool-set

Scipy Scientific computing tool-sets including optimizationand advanced regression

Pandas Time series analysis tool-set, including timezoneand daylight savings handling, and time series statisticaloperations

The predominant method used by users to interact withPV LIB is through the IPython Notebook [3] which is shownin Figure 1, and allows users to create shareable workflows likethe one demonstrated below. These workflows can contain allprocessing steps from data input, to modeling, to statisticalanalysis. In addition, these workbooks can be shared asindividual program files, or can be converted to HTML andeasily shared as a static web-page.

Fig: 1. Example of PV LIB tools being used in IPython to perform analysis.This analysis shows a comparison of TMY GHI in Golden, Colorado to theclearsky GHI calculated from two models .

VI. CONCLUSION

This paper introduces the PV LIB for Python softwarepackage developed by Sandia National Laboratories. Theintention of this open source package is to accelerate thepace of innovation in the PV sector through providing apowerful, validated set of tools for the modeling of PV systemperformance. The intention of this package is to develop alongwith the industry and to serve as a common repository fornew and developing techniques prior to their inclusion incommercial integrated modeling software, and to enable usersto gain deeper insight into their data analysis.

5

ACKNOWLEDGEMENTS

Sandia is a multiprogram laboratory operated by SandiaCorporation, a Lockheed Martin Company, for the UnitedStates Department of Energy’s National Nuclear SecurityAdministration under contract DE-AC04-94AL85000.

REFERENCES

[1] J. S. Stein, “The Photovoltaic Performance Modeling Collaborative(PVPMC),” Photovoltaic Specialists Conference (PVSC), 2012.

[2] K. Hinsen, “High-Level Scientific Programming with Python,”Computational Science ICCS, pp. 691–700, 2002.

[3] F. Perez and B. E. Granger, “IPython: a system for interactive scientificcomputing,” Computing in Science & Engineering, 2007.

[4] F. Perez, B. E. Granger, and J. D. Hunter, “Python: An Ecosystem forScientific Computing,” Computing in Science & Engineering, vol. 13,no. 2, pp. 13–21, 2011.

[5] X. Cai, H. P. Langtangen, and H. Moe, “On the performance ofthe Python programming language for serial and parallel scientificcomputations,” Scientific Programming, 2005.

[6] K. J. Millman and M. Aivazis, “Python for Scientists and Engineers,”Computing in Science & Engineering, vol. 13, no. 2, pp. 9–12, 2011.

[7] B. Kogut and A. Metiu, “OpenSource Software Development andDistributed Innovation,” Oxford Review of Economic Policy, vol. 17,no. 2, pp. 248–264, Jun. 2001.

[8] K. R. Lakhani and E. Von Hippel, “How open source softwareworks:“free” user-to-user assistance,” Research policy, 2003.