Package: pvfactors
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 systems 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]andlinkto paper).Table of contentsDocumentationQuick StartInstallationRequirementsCiting pvfactorsContributingReleasingReferencesDocumentationThe documentation can be foundhere.
It includes a lot oftutorialsthat describe the different ways of using pvfactors.Quick StartGiven some timeseries inputs:# Import external librariesfromdatetimeimportdatetimeimportpandasaspd# Create input datadf_inputs=pd.DataFrame({'solar_zenith':[20.,50.],'solar_azimuth':[110.,250.],'surface_tilt':[10.,20.],'surface_azimuth':[90.,270.],'dni':[1000.,900.],'dhi':[50.,100.],'albedo':[0.2,0.2]},index=[datetime(2017,8,31,11),datetime(2017,8,31,15)])df_inputssolar_zenithsolar_azimuthsurface_tiltsurface_azimuthdnidhialbedo2017-08-31 11:00:0020.0110.010.090.01000.050.00.22017-08-31 15:00:0050.0250.020.0270.0900.0100.00.2And some PV array parameterspvarray_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}The user can quickly create a PV array withpvfactors, and manipulate it with the enginefrompvfactors.geometryimportOrderedPVArray# Create PV arraypvarray=OrderedPVArray.init_from_dict(pvarray_parameters)frompvfactors.engineimportPVEngine# Create engineengine=PVEngine(pvarray)# Fit engine to dataengine.fit(df_inputs.index,df_inputs.dni,df_inputs.dhi,df_inputs.solar_zenith,df_inputs.solar_azimuth,df_inputs.surface_tilt,df_inputs.surface_azimuth,df_inputs.albedo)The user can then plot the PV array geometry at any given time of the simulation:# Plot pvarray shapely geometriesf,ax=plt.subplots(figsize=(10,5))pvarray.plot_at_idx(1,ax)plt.show()It is then very easy to run simulations using the defined engine:pvarray=engine.run_full_mode(fn_build_report=lambdapvarray:pvarray)And inspect the results thanks to the simple geometry APIprint("Incident irradiance on front surface of middle pv row:{}W/m2".format(pvarray.ts_pvrows[1].front.get_param_weighted('qinc')))print("Reflected irradiance on back surface of left pv row:{}W/m2".format(pvarray.ts_pvrows[0].back.get_param_weighted('reflection')))print("Isotropic irradiance on back surface of right pv row:{}W/m2".format(pvarray.ts_pvrows[2].back.get_param_weighted('isotropic')))Incident irradiance on front surface of middle pv row: [1034.968  886.377] W/m2
Reflected irradiance on back surface of left pv row: [112.139  86.404] W/m2
Isotropic irradiance on back surface of right pv row: [0.116 1.849] W/m2The users can also create a “report” while running the simulations that will rely on the simple API shown above, and which will look like whatever the users want.# Create a function that will build a reportdeffn_report(pvarray):return{'total_incident_back':pvarray.ts_pvrows[1].back.get_param_weighted('qinc'),'total_absorbed_back':pvarray.ts_pvrows[1].back.get_param_weighted('qabs')}# Run full mode simulationreport=engine.run_full_mode(fn_build_report=fn_report)# Print results (report is defined by report function passed by user)df_report=pd.DataFrame(report,index=df_inputs.index)df_reporttotal_incident_backtotal_absorbed_back2017-08-31 11:00:00106.627832103.4289972017-08-31 15:00:0079.66887877.278812Installationpvfactors is currently compatible and tested with 3.6+, and is available inPyPI. The easiest way to install pvfactors is to usepipas follows:$pipinstallpvfactorsThe package wheel files are also available in therelease sectionof the Github repository.RequirementsRequirements are included in therequirements.txtfile of the package. Here is a list of important dependencies:numpypvlib-pythonshapelyCiting pvfactorsWe 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.ContributingContributions 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 usingpipin the root folder of the package:$pipinstall.To install the package in editable mode, you can use:$pipinstall-e.ReleasingWhen releasing pvfactors, you will need to run a couple of build commands. First make sure to activate your virtual environment if any, then:create a tag on the latest master branch commit usinggit tag -a vX.X.X, and write a tag message. You can then push that tag to Github so that it will appear there.build the documentation by runningmake build-docs. When done running, you should be able to openbuild/sphinx/html/index.html, and confirm that the version displayed is the same as the one from the git tag. You can deploy by copying the content of of thebuild/sphinx/html/folder into thegh-pagesbranch of the repo (make sure to keep the.nojekyllfile that’s already present).build the release files by runningmake build-package. When done running, you should be able to opendist/and see both a whl file and and tar file. Make sure that their names include the correct git tag you created. Please confirm that the whl file was built correctly by installing it locally and testing the newly released updates. You can deploy by 1) making a Github release from the tag you created and pushed, and including the files indist/in the release. 2) The last step is to publish a release in PyPI, for which you can use twine and the commandtwine upload dist/*References[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.