diff --git a/.github/workflows/joss-pdf.yml b/.github/workflows/joss-pdf.yml new file mode 100644 index 0000000000..fc07838426 --- /dev/null +++ b/.github/workflows/joss-pdf.yml @@ -0,0 +1,26 @@ +# temporary job to rebuild the PDF while coauthors review the manuscript. +# TODO: delete before merging this PR + +on: [push] + +jobs: + paper: + runs-on: ubuntu-latest + name: Paper Draft + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Build draft PDF + uses: openjournals/openjournals-draft-action@master + with: + journal: joss + # This should be the path to the paper within your repo. + paper-path: paper/paper.md + - name: Upload + uses: actions/upload-artifact@v1 + with: + name: paper + # This is the output path where Pandoc will write the compiled + # PDF. Note, this should be the same directory as the input + # paper.md + path: paper/paper.pdf diff --git a/paper/codemeta.json b/paper/2018/codemeta.json similarity index 100% rename from paper/codemeta.json rename to paper/2018/codemeta.json diff --git a/paper/2018/paper.bib b/paper/2018/paper.bib new file mode 100644 index 0000000000..b79882d004 --- /dev/null +++ b/paper/2018/paper.bib @@ -0,0 +1,110 @@ +@inproceedings{Andrews2014, + Author = {R. W. Andrews and J. S. Stein and C. Hansen and D. Riley}, + Booktitle = {2014 IEEE 40th Photovoltaic Specialist Conference (PVSC)}, + doi = {10.1109/PVSC.2014.6925501}, + Title = {Introduction to the open source PV LIB for python Photovoltaic system modelling package}, + Year = {2014}} + +@online{DOESF2, + author = {Department of Energy}, + title = {Solar Forecasting 2}, + year = 2018, + url = {https://www.energy.gov/eere/solar/solar-forecasting-2}, + urldate = {2018-08-02}} + +@article{Gagne2017, + Author = {Gagne II, David John and McGovern, Amy and Haupt, Sue Ellen and Williams, John K.}, + Journal = {Solar Energy}, + Pages = {383- 393}, + doi = {10.1016/j.solener.2017.04.031}, + Title = {Evaluation of statistical learning configurations for gridded solar irradiance forecasting}, + Volume = {150}, + Year = {2017}} + +@inproceedings{Holmgren2015, + Author = {W. F. Holmgren and R. W. Andrews and A. T. Lorenzo and J. S. Stein}, + Booktitle = {2015 IEEE 42nd Photovoltaic Specialist Conference (PVSC)}, + Month = {June}, + Pages = {1-5}, + Title = {PVLIB Python 2015}, + Year = {2015}, + doi = {10.1109/PVSC.2015.7356005}} + +@inproceedings{Holmgren2016, + Author = {W. F. Holmgren and D. G. Groenendyk}, + Booktitle = {2016 IEEE 43rd Photovoltaic Specialists Conference (PVSC)}, + Month = {June}, + Pages = {0972-0975}, + Title = {An open source solar power forecasting tool using PVLIB-Python}, + Year = {2016}, + doi = {10.1109/PVSC.2016.7749755}} + +@inproceedings{Holmgren2017, + Author = {William F. Holmgren and Antonio T. Lorenzo and Clifford Hansen}, + Booktitle = {2017 IEEE 44th Photovoltaic Specialists Conference}, + Title = {A Comparison of PV Power Forecasts Using PVLib-Python}, + Year = {2017}, + doi = {10.5281/zenodo.1400857}} + +@inproceedings{Holmgren2018, + Author = {William F. Holmgren and Clifford W. Hansen and Joshua S. Stein and Mark A. Mikofski}, + Booktitle = {2018 IEEE 45th Photovoltaic Specialists Conference}, + Title = {Review of open source tools for PV modeling}, + Year = {2018}, + doi = {10.5281/zenodo.1401378}} + +@article{Louwen2017, + Author = {Atse Louwen and Ruud E.I. Schropp and Wilfried G.J.H.M. van Sark and Andr{\'e} P.C. Faaij}, + Journal = {Solar Energy}, + Pages = {1339 - 1353}, + Title = {Geospatial analysis of the energy yield and environmental footprint of different photovoltaic module technologies}, + Volume = {155}, + Year = {2017}, + doi = {10.1016/j.solener.2017.07.056}} + +@inproceedings{Mikofski2016, + Author = {M. Mikofski and A. Oumbe and C. Li and B. Bourne}, + Booktitle = {2016 IEEE 43rd Photovoltaic Specialists Conference (PVSC)}, + Month = {June}, + Pages = {1357-1362}, + Title = {Evaluation and correction of the impact of spectral variation of irradiance on PV performance}, + Year = {2016}, + doi = {10.1109/PVSC.2016.7749837}} + +@inproceedings{Mikofski2017, + Author = {Mark A. Mikofski and Clifford W. Hansen and William F. Holmgren and Gregory M. Kimball}, + Booktitle = {2017 IEEE 44th Photovoltaic Specialists Conference}, + Title = {Use of Measured Aerosol Optical Depth and Precipitable Water to Model Clear Sky Irradiance}, + Year = {2017}, + doi = {10.5281/zenodo.1403238}} + +@article{Polo2016, + Author = {J. Polo, S. Garcia-Bouhaben, M. C. Alonso-Garcia}, + Journal = {Journal of Renewable and Sustainable Energy}, + Title = {A comparative study of the impact of horizontal-to-tilted solar irradiance conversion in modelling small PV array performance}, + Year = {2016}, + doi = {10.1063/1.4964363}} + +@misc{pvlibZenodo, + author = {pvlib python Contributors}, + title = {pvlib python}, + doi = {10.5281/zenodo.1246152}, + howpublished = {\url{http://doi.org/10.5281/zenodo.1246152}}} + +@inproceedings{Stein2012, + Author = {J. S. Stein}, + Booktitle = {2012 38th IEEE Photovoltaic Specialists Conference}, + Month = {June}, + Pages = {003048-003052}, + Title = {The photovoltaic Performance Modeling Collaborative (PVPMC)}, + Year = {2012}, + doi = {10.1109/PVSC.2012.6318225}} + +@inproceedings{Stein2016, + Author = {J. S. Stein and W. F. Holmgren and J. Forbess and C. W. Hansen}, + Booktitle = {2016 IEEE 43rd Photovoltaic Specialists Conference (PVSC)}, + Month = {June}, + Pages = {3425-3430}, + Title = {PVLIB: Open source photovoltaic performance modeling functions for Matlab and Python}, + Year = {2016}, + doi = {10.1109/PVSC.2016.7750303}} diff --git a/paper/2018/paper.md b/paper/2018/paper.md new file mode 100644 index 0000000000..b144818943 --- /dev/null +++ b/paper/2018/paper.md @@ -0,0 +1,124 @@ +--- +title: 'pvlib python: a python package for modeling solar energy systems' +tags: + - Python + - solar energy + - photovoltaics + - renewable energy +authors: + - name: William F. Holmgren + orcid: 0000-0001-6218-9767 + affiliation: 1 + - name: Clifford W. Hansen + orcid: 0000-0002-8620-5378 + affiliation: 2 + - name: Mark A. Mikofski + orcid: 0000-0001-8001-8582 + affiliation: 3 +affiliations: + - name: Department of Hydrology and Atmospheric Sciences, University of Arizona + index: 1 + - name: Sandia National Laboratories + index: 2 + - name: DNV-GL + index: 3 +date: 2 August 2018 +bibliography: paper.bib +--- + +# Summary + +pvlib python is a community-supported open source tool that provides a +set of functions and classes for simulating the performance of +photovoltaic energy systems. pvlib python aims to provide reference +implementations of models relevant to solar energy, including for +example algorithms for solar position, clear sky irradiance, irradiance +transposition, DC power, and DC-to-AC power conversion. pvlib python is +an important component of a growing ecosystem of open source tools for +solar energy [@Holmgren2018]. + +pvlib python is developed on GitHub by contributors from academia, +national laboratories, and private industry. pvlib python is released +with a BSD 3-clause license allowing permissive use with attribution. +pvlib python is extensively tested for functional and algorithm +consistency. Continuous integration services check each pull request on +multiple platforms and Python versions. The pvlib python API is +thoroughly documented and detailed tutorials are provided for many +features. The documentation includes help for installation and +guidelines for contributions. The documentation is hosted at +readthedocs.org as of this writing. A Google group and StackOverflow tag +provide venues for user discussion and help. + +The pvlib python API was designed to serve the various needs of the many +subfields of solar power research and engineering. It is implemented in +three layers: core functions, the ``Location`` and ``PVSystem`` classes, +and the ``ModelChain`` class. The core API consists of a collection of +functions that implement algorithms. These algorithms are typically +implementations of models described in peer-reviewed publications. The +functions provide maximum user flexibility, however many of the function +arguments require an unwieldy number of parameters. The next API level +contains the ``Location`` and ``PVSystem`` classes. These abstractions +provide simple methods that wrap the core function API layer. The method +API simplification is achieved by separating the data that represents +the object (object attributes) from the data that the object methods +operate on (method arguments). For example, a ``Location`` is +represented by a latitude, longitude, elevation, timezone, and name, +which are ``Location`` object attributes. Then a ``Location`` object +method operates on a ``datetime`` to get the corresponding solar +position. The methods combine these data sources when calling the +function layer, then return the results to the user. The final level of +API is the ``ModelChain`` class, designed to simplify and standardize +the process of stitching together the many modeling steps necessary to +convert a time series of weather data to AC solar power generation, +given a PV system and a location. + +pvlib python was ported from the PVLib MATLAB toolbox in 2014 +[@Stein2012, @Andrews2014]. Efforts to make the project more pythonic +were undertaken in 2015 [@Holmgren2015]. Additional features continue to +be added, see, for example [@Stein2016, @Holmgren2016] and the +documentation's "What's New" section. + +pvlib python has been used in numerous studies, for example, of solar +power forecasting [@Gagne2017, @Holmgren2017], development of solar +irradiance models [@Polo2016], and estimation of photovoltaic energy +potential [@Louwen2017]. Mikofski et. al. used pvlib python to study +the accuracy of clear sky models with different aerosol optical depth +and precipitable water data sources [@Mikofski2017] and to determine the +effects of spectral mismatch on different PV devices [@Mikofski2016]. +pvlib python is a foundational piece of an award, "An Open Source +Evaluation Framework for Solar Forecasting," made under the Department +of Energy Solar Forecasting 2 program [@DOESF2]. + +Plans for pvlib python development includes the implementation of new +and existing models, addition of functionality to assist with +input/output, and improvements to API consistency. + +The source code for each pvlib python version is archived with Zenodo +[@pvlibZenodo]. + +# Acknowledgements + +The authors acknowledge and thank the code, documentation, and +discussion contributors to the project. + +WH acknowledges support from the Department of Energy's Energy +Efficiency and Renewable Energy Postdoctoral Fellowship Program +(2014-2016), Tucson Electric Power, Arizona Public Service, and Public +Service Company of New Mexico (2016-2018), and University of Arizona +Institute for Energy Solutions (2017-2018). + +CH acknowledges support from the U.S. Department of Energy's Solar +Energy Technology Office. + +WH and CH acknowledge support from the Department of Energy Solar +Forecasting 2 program. + +MM acknowledges support from SunPower Corporation (2016-2017). + +Sandia National Laboratories is a multi-mission laboratory managed and +operated by National Technology and Engineering Solutions of Sandia, +LLC., a wholly owned subsidiary of Honeywell International, Inc., for +the U.S. Department of Energy's National Nuclear Security Administration +under contract DE-NA-0003525. + +# References diff --git a/paper/community.pdf b/paper/community.pdf new file mode 100644 index 0000000000..e0fd0dc9d0 Binary files /dev/null and b/paper/community.pdf differ diff --git a/paper/functions_06_010.pdf b/paper/functions_06_010.pdf new file mode 100644 index 0000000000..aa485d7017 Binary files /dev/null and b/paper/functions_06_010.pdf differ diff --git a/paper/paper.bib b/paper/paper.bib index b79882d004..9389eff8c6 100644 --- a/paper/paper.bib +++ b/paper/paper.bib @@ -1,110 +1,216 @@ -@inproceedings{Andrews2014, - Author = {R. W. Andrews and J. S. Stein and C. Hansen and D. Riley}, - Booktitle = {2014 IEEE 40th Photovoltaic Specialist Conference (PVSC)}, - doi = {10.1109/PVSC.2014.6925501}, - Title = {Introduction to the open source PV LIB for python Photovoltaic system modelling package}, - Year = {2014}} - -@online{DOESF2, - author = {Department of Energy}, - title = {Solar Forecasting 2}, - year = 2018, - url = {https://www.energy.gov/eere/solar/solar-forecasting-2}, - urldate = {2018-08-02}} - -@article{Gagne2017, - Author = {Gagne II, David John and McGovern, Amy and Haupt, Sue Ellen and Williams, John K.}, - Journal = {Solar Energy}, - Pages = {383- 393}, - doi = {10.1016/j.solener.2017.04.031}, - Title = {Evaluation of statistical learning configurations for gridded solar irradiance forecasting}, - Volume = {150}, - Year = {2017}} - -@inproceedings{Holmgren2015, - Author = {W. F. Holmgren and R. W. Andrews and A. T. Lorenzo and J. S. Stein}, - Booktitle = {2015 IEEE 42nd Photovoltaic Specialist Conference (PVSC)}, - Month = {June}, - Pages = {1-5}, - Title = {PVLIB Python 2015}, - Year = {2015}, - doi = {10.1109/PVSC.2015.7356005}} - -@inproceedings{Holmgren2016, - Author = {W. F. Holmgren and D. G. Groenendyk}, - Booktitle = {2016 IEEE 43rd Photovoltaic Specialists Conference (PVSC)}, - Month = {June}, - Pages = {0972-0975}, - Title = {An open source solar power forecasting tool using PVLIB-Python}, - Year = {2016}, - doi = {10.1109/PVSC.2016.7749755}} - -@inproceedings{Holmgren2017, - Author = {William F. Holmgren and Antonio T. Lorenzo and Clifford Hansen}, - Booktitle = {2017 IEEE 44th Photovoltaic Specialists Conference}, - Title = {A Comparison of PV Power Forecasts Using PVLib-Python}, - Year = {2017}, - doi = {10.5281/zenodo.1400857}} + +@inproceedings{Stein2022, + title = {A Twelve-Year Retrospective On pvlib: Open-Source {PV} Performance Modeling Library}, + author = {Stein, Josh and Hansen, Clifford}, + url = {https://www.energy.gov/sites/default/files/2022-10/DOE%20OSS%20Workshop%2C%20Josh%20Stein%2C%20Sandia.pdf}, + booktitle = {{SETO}-funded Open-Source Software: Building Community Engagement for Lasting Impact}, + year = {2022}, +} + +@inproceedings{pvpmc_2023_update, + title = {{pvlib} 2023 update: {pvlib-python}, pvanalytics, twoaxistracking}, + author = {Hansen, Clifford and Anderson, Kevin and Vining, William, and Holmgren, William and Mikofski, Mark and Jensen, Adam R. and Driesse, Anton and Perry, Kirsten}, + url = {}, + booktitle = {PV Performance Modeling and Monitoring Workshop}, + year = {2023}, +} + +@inproceedings{pvpmc2022_pvlib_update, + title = {{pvlib} python 2022 update}, + author = {Anderson, Kevin and Holmgren, Will and Hansen, Clifford and Mikofski, Mark and Jensen, Adam R. and Driesse, Anton}, + url = {https://www.osti.gov/biblio/1886878}, + booktitle = {PV Performance Modeling and Monitoring Workshop}, + year = {2022}, +} + +@inproceedings{pvpmc2022_pvanalytics_update, + title = {{PVAnalytics}: A Python Package for Automated Processing of Solar Time Series Data}, + author = {Perry, Kirsten and Vining, William and Anderson, Kevin and Muller, Matthew and Hansen, Cliff}, + url = {https://www.osti.gov/biblio/1887283}, + booktitle = {PV Performance Modeling and Monitoring Workshop}, + year = {2022}, +} + +@techreport{seto2022, + title = "Modeling of Photovoltaic Systems: Basic Challenges and DOE-Funded Tools", + author = "{Solar Energy Technologies Office}", + institution = "{U.S. Department of Energy, Office of Energy Efficiency and Renewable Energy}", + address = "", + number = "", + year = 2022, +} + +@article{Jensen2022, + doi = {10.1016/j.mex.2022.101876}, + url = {https://doi.org/10.1016/j.mex.2022.101876}, + year = {2022}, + publisher = {Elsevier {BV}}, + volume = {9}, + pages = {101876}, + author = {Adam R. Jensen and Ioannis Sifnaios and Kevin Anderson}, + title = {{twoaxistracking} {\textendash} a python package for simulating self-shading of two-axis tracking solar collectors}, + journal = {{MethodsX}} +} + +@article{pvlibjoss2018, + doi = {10.21105/joss.00884}, + url = {https://doi.org/10.21105/joss.00884}, + year = {2018}, + volume = {3}, + number = {29}, + pages = {884}, + author = {William F. Holmgren and Clifford W. Hansen and Mark A. Mikofski}, + title = {{pvlib} python: a python package for modeling solar energy systems}, + journal = {Journal of Open Source Software} +} @inproceedings{Holmgren2018, Author = {William F. Holmgren and Clifford W. Hansen and Joshua S. Stein and Mark A. Mikofski}, - Booktitle = {2018 IEEE 45th Photovoltaic Specialists Conference}, + Booktitle = {IEEE 45th Photovoltaic Specialists Conference}, Title = {Review of open source tools for PV modeling}, Year = {2018}, - doi = {10.5281/zenodo.1401378}} - -@article{Louwen2017, - Author = {Atse Louwen and Ruud E.I. Schropp and Wilfried G.J.H.M. van Sark and Andr{\'e} P.C. Faaij}, - Journal = {Solar Energy}, - Pages = {1339 - 1353}, - Title = {Geospatial analysis of the energy yield and environmental footprint of different photovoltaic module technologies}, - Volume = {155}, - Year = {2017}, - doi = {10.1016/j.solener.2017.07.056}} - -@inproceedings{Mikofski2016, - Author = {M. Mikofski and A. Oumbe and C. Li and B. Bourne}, - Booktitle = {2016 IEEE 43rd Photovoltaic Specialists Conference (PVSC)}, - Month = {June}, - Pages = {1357-1362}, - Title = {Evaluation and correction of the impact of spectral variation of irradiance on PV performance}, - Year = {2016}, - doi = {10.1109/PVSC.2016.7749837}} - -@inproceedings{Mikofski2017, - Author = {Mark A. Mikofski and Clifford W. Hansen and William F. Holmgren and Gregory M. Kimball}, - Booktitle = {2017 IEEE 44th Photovoltaic Specialists Conference}, - Title = {Use of Measured Aerosol Optical Depth and Precipitable Water to Model Clear Sky Irradiance}, - Year = {2017}, - doi = {10.5281/zenodo.1403238}} - -@article{Polo2016, - Author = {J. Polo, S. Garcia-Bouhaben, M. C. Alonso-Garcia}, - Journal = {Journal of Renewable and Sustainable Energy}, - Title = {A comparative study of the impact of horizontal-to-tilted solar irradiance conversion in modelling small PV array performance}, - Year = {2016}, - doi = {10.1063/1.4964363}} - -@misc{pvlibZenodo, - author = {pvlib python Contributors}, - title = {pvlib python}, - doi = {10.5281/zenodo.1246152}, - howpublished = {\url{http://doi.org/10.5281/zenodo.1246152}}} - -@inproceedings{Stein2012, - Author = {J. S. Stein}, - Booktitle = {2012 38th IEEE Photovoltaic Specialists Conference}, - Month = {June}, - Pages = {003048-003052}, - Title = {The photovoltaic Performance Modeling Collaborative (PVPMC)}, - Year = {2012}, - doi = {10.1109/PVSC.2012.6318225}} - -@inproceedings{Stein2016, - Author = {J. S. Stein and W. F. Holmgren and J. Forbess and C. W. Hansen}, - Booktitle = {2016 IEEE 43rd Photovoltaic Specialists Conference (PVSC)}, - Month = {June}, - Pages = {3425-3430}, - Title = {PVLIB: Open source photovoltaic performance modeling functions for Matlab and Python}, - Year = {2016}, - doi = {10.1109/PVSC.2016.7750303}} + doi = {10.5281/zenodo.1401378} +} + +@techreport{Augspurger2023, + author = {Tobias Augspurger and Eirini Malliaraki and Josh Hopkins and Dan Brown}, + title = {The Open Source Sustainability Ecosystem}, + year = {2023}, + month = {August}, + institution = {The Linux Foundation} +} + +@article{pvlibiotools, + author = {Adam R. Jensen and Kevin S. Anderson and William F. Holmgren and Mark A. Mikofski and Clifford W. Hansen and Leland J. Boeman and Roel Loonen}, + title = {{pvlib} iotools - open-source Python functions for seamless access to solar irradiance data}, + year = {submitted}, + journal = {Solar Energy}, +} + +@Article{ numpy, + title = {Array programming with {NumPy}}, + author = {Charles R. Harris and K. Jarrod Millman and St{\'{e}}fan J. + van der Walt and Ralf Gommers and Pauli Virtanen and David + Cournapeau and Eric Wieser and Julian Taylor and Sebastian + Berg and Nathaniel J. Smith and Robert Kern and Matti Picus + and Stephan Hoyer and Marten H. van Kerkwijk and Matthew + Brett and Allan Haldane and Jaime Fern{\'{a}}ndez del + R{\'{i}}o and Mark Wiebe and Pearu Peterson and Pierre + G{\'{e}}rard-Marchant and Kevin Sheppard and Tyler Reddy and + Warren Weckesser and Hameer Abbasi and Christoph Gohlke and + Travis E. Oliphant}, + year = {2020}, + month = sep, + journal = {Nature}, + volume = {585}, + number = {7825}, + pages = {357--362}, + doi = {10.1038/s41586-020-2649-2}, + publisher = {Springer Science and Business Media {LLC}}, + url = {https://doi.org/10.1038/s41586-020-2649-2} +} + +@InProceedings{ pandas, + author = { {W}es {M}c{K}inney }, + title = { {D}ata {S}tructures for {S}tatistical {C}omputing in {P}ython }, + booktitle = { {P}roceedings of the 9th {P}ython in {S}cience {C}onference }, + pages = { 56 - 61 }, + year = { 2010 }, + editor = { {S}t\'efan van der {W}alt and {J}arrod {M}illman }, + doi = { 10.25080/Majora-92bf1922-00a } +} + +@ARTICLE{scipy, + author = {Virtanen, Pauli and Gommers, Ralf and Oliphant, Travis E. and + Haberland, Matt and Reddy, Tyler and Cournapeau, David and + Burovski, Evgeni and Peterson, Pearu and Weckesser, Warren and + Bright, Jonathan and {van der Walt}, St{\'e}fan J. and + Brett, Matthew and Wilson, Joshua and Millman, K. Jarrod and + Mayorov, Nikolay and Nelson, Andrew R. J. and Jones, Eric and + Kern, Robert and Larson, Eric and Carey, C J and + Polat, {\.I}lhan and Feng, Yu and Moore, Eric W. and + {VanderPlas}, Jake and Laxalde, Denis and Perktold, Josef and + Cimrman, Robert and Henriksen, Ian and Quintero, E. A. and + Harris, Charles R. and Archibald, Anne M. and + Ribeiro, Ant{\^o}nio H. and Pedregosa, Fabian and + {van Mulbregt}, Paul and {SciPy 1.0 Contributors}}, + title = {{{SciPy} 1.0: Fundamental Algorithms for Scientific + Computing in Python}}, + journal = {Nature Methods}, + year = {2020}, + volume = {17}, + pages = {261--272}, + adsurl = {https://rdcu.be/b08Wh}, + doi = {10.1038/s41592-019-0686-2}, +} + +@inproceedings{numba, + title={Numba: A {LLVM}-based python {JIT} compiler}, + author={Lam, Siu Kwan and Pitrou, Antoine and Seibert, Stanley}, + booktitle={Proceedings of the Second Workshop on the LLVM Compiler Infrastructure in HPC}, + pages={1--6}, + year={2015}, + doi={10.1145/2833157.2833162}, +} + +@Article{matplotlib, + Author = {Hunter, J. D.}, + Title = {Matplotlib: A 2D graphics environment}, + Journal = {Computing in Science \& Engineering}, + Volume = {9}, + Number = {3}, + Pages = {90--95}, + abstract = {Matplotlib is a 2D graphics package used for Python for + application development, interactive scripting, and publication-quality + image generation across user interfaces and operating systems.}, + publisher = {IEEE COMPUTER SOC}, + doi = {10.1109/MCSE.2007.55}, + year = 2007 +} + +@software{sphinx, + author = {Takeshi Komiya and + Georg Brandl and + Jean-François B. and + Takayuki SHIMIZUKAWA and + Jakob Lykke Andersen and + Adam Turner and + Stephen Finucane and + Robert Lehmann and + Timotheus Kampik and + Justus Magin and + jacobmason and + Jon Dufresne and + Jonathan Waltman and + Juan Luis Cano Rodríguez and + Armin Ronacher and + Matthias Geier and + Dmitry Shachnev and + Rob Ruana and + Pauli Virtanen and + danieleades and + François Freitag and + Louis Maddox and + Martin Liška and + Hong Xu and + Nils K and + Eric Wieser and + shirou and + Jeremy Maitin-Shepard and + Nozomu Kaneko and + cocoatomo}, + title = {sphinx-doc/sphinx: v7.0.1}, + month = may, + year = 2023, + publisher = {Zenodo}, + version = {v7.0.1}, + doi = {10.5281/zenodo.7931414}, + url = {https://doi.org/10.5281/zenodo.7931414} +} + +@misc{pytest, + title = {pytest}, + author = {Krekel, Holger and Oliveira, Bruno and Pfannschmidt, Ronny and Bruynooghe, Floris and Laugher, Brianna and Bruhin, Florian}, + year = {2004}, + url = {https://github.com/pytest-dev/pytest}, +} diff --git a/paper/paper.md b/paper/paper.md index b144818943..3936e3c1ce 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -1,124 +1,240 @@ --- -title: 'pvlib python: a python package for modeling solar energy systems' +title: 'pvlib python: 2023 project update' tags: - Python - solar energy - photovoltaics - renewable energy authors: - - name: William F. Holmgren - orcid: 0000-0001-6218-9767 + - name: Kevin S. Anderson + orcid: 0000-0002-1166-7957 affiliation: 1 - name: Clifford W. Hansen orcid: 0000-0002-8620-5378 + affiliation: 1 + - name: William F. Holmgren + orcid: 0000-0001-6218-9767 affiliation: 2 - name: Mark A. Mikofski orcid: 0000-0001-8001-8582 + affiliation: 2 + - name: Adam R. Jensen + orcid: 0000-0002-5554-9856 affiliation: 3 + - name: Anton Driesse + orcid: 0000-0003-3023-2155 + affiliation: 4 affiliations: - - name: Department of Hydrology and Atmospheric Sciences, University of Arizona - index: 1 - name: Sandia National Laboratories + index: 1 + - name: DNV index: 2 - - name: DNV-GL + - name: Technical University of Denmark index: 3 -date: 2 August 2018 + - name: PV Performance Labs + index: 4 + +date: 13 September 2023 bibliography: paper.bib --- -# Summary - -pvlib python is a community-supported open source tool that provides a -set of functions and classes for simulating the performance of -photovoltaic energy systems. pvlib python aims to provide reference -implementations of models relevant to solar energy, including for -example algorithms for solar position, clear sky irradiance, irradiance -transposition, DC power, and DC-to-AC power conversion. pvlib python is -an important component of a growing ecosystem of open source tools for -solar energy [@Holmgren2018]. - -pvlib python is developed on GitHub by contributors from academia, -national laboratories, and private industry. pvlib python is released -with a BSD 3-clause license allowing permissive use with attribution. -pvlib python is extensively tested for functional and algorithm -consistency. Continuous integration services check each pull request on -multiple platforms and Python versions. The pvlib python API is -thoroughly documented and detailed tutorials are provided for many -features. The documentation includes help for installation and -guidelines for contributions. The documentation is hosted at -readthedocs.org as of this writing. A Google group and StackOverflow tag -provide venues for user discussion and help. - -The pvlib python API was designed to serve the various needs of the many -subfields of solar power research and engineering. It is implemented in -three layers: core functions, the ``Location`` and ``PVSystem`` classes, -and the ``ModelChain`` class. The core API consists of a collection of -functions that implement algorithms. These algorithms are typically -implementations of models described in peer-reviewed publications. The -functions provide maximum user flexibility, however many of the function -arguments require an unwieldy number of parameters. The next API level -contains the ``Location`` and ``PVSystem`` classes. These abstractions -provide simple methods that wrap the core function API layer. The method -API simplification is achieved by separating the data that represents -the object (object attributes) from the data that the object methods -operate on (method arguments). For example, a ``Location`` is -represented by a latitude, longitude, elevation, timezone, and name, -which are ``Location`` object attributes. Then a ``Location`` object -method operates on a ``datetime`` to get the corresponding solar -position. The methods combine these data sources when calling the -function layer, then return the results to the user. The final level of -API is the ``ModelChain`` class, designed to simplify and standardize -the process of stitching together the many modeling steps necessary to -convert a time series of weather data to AC solar power generation, -given a PV system and a location. - -pvlib python was ported from the PVLib MATLAB toolbox in 2014 -[@Stein2012, @Andrews2014]. Efforts to make the project more pythonic -were undertaken in 2015 [@Holmgren2015]. Additional features continue to -be added, see, for example [@Stein2016, @Holmgren2016] and the -documentation's "What's New" section. - -pvlib python has been used in numerous studies, for example, of solar -power forecasting [@Gagne2017, @Holmgren2017], development of solar -irradiance models [@Polo2016], and estimation of photovoltaic energy -potential [@Louwen2017]. Mikofski et. al. used pvlib python to study -the accuracy of clear sky models with different aerosol optical depth -and precipitable water data sources [@Mikofski2017] and to determine the -effects of spectral mismatch on different PV devices [@Mikofski2016]. -pvlib python is a foundational piece of an award, "An Open Source -Evaluation Framework for Solar Forecasting," made under the Department -of Energy Solar Forecasting 2 program [@DOESF2]. - -Plans for pvlib python development includes the implementation of new -and existing models, addition of functionality to assist with -input/output, and improvements to API consistency. - -The source code for each pvlib python version is archived with Zenodo -[@pvlibZenodo]. -# Acknowledgements - -The authors acknowledge and thank the code, documentation, and -discussion contributors to the project. +# Summary -WH acknowledges support from the Department of Energy's Energy -Efficiency and Renewable Energy Postdoctoral Fellowship Program -(2014-2016), Tucson Electric Power, Arizona Public Service, and Public -Service Company of New Mexico (2016-2018), and University of Arizona -Institute for Energy Solutions (2017-2018). +pvlib python is a community-developed, open-source software toolbox +for simulating the performance of solar photovoltaic (PV) energy +components and systems. It provides reference implementations of +over 100 empirical and physics-based models from the peer-reviewed scientific literature, +including solar position algorithms, irradiance models, thermal models, +and PV electrical models. In addition to individual low-level +model implementations, pvlib python provides high-level workflows +that chain these models together like building blocks to form complete +"weather-to-power" photovoltaic system models. It also provides functions to +fetch and import a wide variety of weather datasets useful for PV modeling. + +pvlib python has been developed since 2013 and follows modern best +practices for open-source python software, with comprehensive automated +testing, standards-based packaging, and semantic versioning. +Its source code is developed openly on GitHub and releases are +distributed via the Python Package Index (PyPI) and the conda-forge +repository. pvlib python's source code is made freely available under +the permissive BSD-3 license. + +Here we (the project's core developers) present an update on pvlib python, +describing capability and community development since our 2018 publication +[@pvlibjoss2018]. + + +# Statement of need + +PV performance models are used throughout the field of photovoltaics. +The rapid increase in scale, technological diversity, and sophistication +of the global solar energy industry demands correspondingly more +capable models. Per the United States Department of Energy, +"the importance of accurate modeling is hard to overstate" [@seto2022]. + +Compared with other PV modeling tools, pvlib python stands out in several +key aspects. One is its toolbox design, providing the user a +level of flexibility and customization beyond that of other tools. Rather than organizing +the user interface around pre-built modeling workflows, pvlib python +makes the individual "building blocks" of PV performance models accessible to +the user. This allows the user to assemble their own model workflows, including +the ability of incorporating custom modeling steps. This flexibility +is essential for applications in both academia and industry. + +Another key aspect of pvlib python is that it is used via +a general-purpose programming language (Python), which +allows pvlib python functions to be combined with capabilities in other Python packages, +such as database query, data manipulation, numerical optimization, +plotting, and reporting packages. + +A final key aspect of pvlib python is its open peer review approach and +foundation on published scientific research, allowing it to be developed by +a decentralized and diverse community of PV researchers and practitioners +without compromising its focus on transparent and reliable model +implementations. + +These key aspects, along with sustained contributions from a passionate and +committed community, have led to pvlib python's widespread adoption across the PV +field [@Stein2022]. In support of the claim that pvlib python provides +meaningful value and addresses real needs, we offer these quantitative metrics: + +1. Its 2018 JOSS publication, at the time of this writing, +ranks 14th by citation count out of the 2000+ papers published by JOSS to date. +2. The Python Package Index (PyPI) classifies pvlib python as a "critical project" +due to being in the top 1% of the index's packages by download count. +3. The project's online documentation receives over 400,000 page views +per year. +4. pvlib python was found to be the third most-used python project +in the broader open-source sustainability software landscape, with the first +two being netCDF4 utilities applicable across many scientific fields [@Augspurger2023]. + + +# Functionality additions + +To meet new needs of the PV industry, substantial new functionality has been +added in the roughly five years since the 2018 JOSS publication. + +First, several dozen new models have been +implemented, expanding the package's capability in both existing and new +modeling areas and prompting the creation of several new modules within pvlib python. +In response to the recent rapid increase in deployment of bifacial PV, +a capability enhancement of particular note is the inclusion of models for simulating +irradiance on the rear side of PV modules. +Other notable additions include methods of fitting empirical PV performance models +to measurements and models for performance loss mechanisms like soiling and snow +coverage. +\autoref{fig:functions-comparison} summarizes the number of models (or functions) +per module for pvlib python versions 0.6.0 (released 2018-09-17) and 0.10.1 +(released 2023-07-03), showing a substantial capability expansion over the +last five years. + +![Comparison of public function counts for selected pvlib modules for v0.6.0 and v0.10.1. Some modules are smaller in v0.10.1 due to moving functions to new modules (e.g. from `pvsystem` to `iam`).\label{fig:functions-comparison}](functions_06_010.pdf) + +Second, in addition to the new function-level model implementations, +the package's high-level classes have also been expanded to support +the complexity of emerging system designs, including heterogeneous systems whose +subsystems differ in mounting or electrical configuration and systems that require +custom orientation/tracking models. + +Third, the creation of `pvlib.iotools`, a sub-package for fetching and importing +datasets relevant to PV modeling. These functions provide a standardized +interface for reading data files in various complex data formats, offering +conveniences like optionally standardizing the dataset variable names and units +to pvlib's conventions [@pvlibiotools]. As of version 0.10.1, `pvlib.iotools` contains +functions to download data from over ten online data providers, +plus file reading/parsing functions for a dozen solar resource file formats. + +These additions are discussed in more detail in [@pvpmc_2023_update] and [@pvpmc2022_pvlib_update]. +Complete descriptions of the changes in each release can be found in the +project's documentation. + + +# Community growth + +It is difficult to fully describe the community around +open-source projects like pvlib python, but some aspects can be +quantified. Here we examine the community from a few convenient +perspectives, emphasizing that these metrics provide a limited view of +the community as a whole. + +First, we examine contributors to pvlib python's code repository. The +project's use of version control software enables easy quantification of +repository additions (to code, documentation, tests, etc) over time. The +project's repository currently comprises contributions from over 100 people +spanning industry, academia, and government research institutions. +\autoref{fig:community} (left) shows the number of unique repository +contributors over time, demonstrating continued and generally accelerating +attraction of new contributors. + +![Total repository contributor count over time (left) and other community size statistics (right).\label{fig:community}](community.pdf) + +However, the project as a whole is the product of not only of those who contribute +code but also those who submit bug reports, propose ideas for new features, +participate in online forums, and support the project in other ways. +Along those lines, two easily tracked metrics are the number of people +registered in the pvlib python online discussion forum and the number of +GitHub "stars" (an indicator of an individual's interest, akin to a browser bookmark) +on the pvlib python code repository. \autoref{fig:community} (right) +shows these counts over time. Although these numbers +almost certainly underestimate the true size of the pvlib community, +their increase over time indicates continued and accelerating community growth. +Since the 2018 JOSS publication, pvlib python has doubled the number of +maintainers to bring in new perspectives and to better support the growing +community. + +In addition to continuous interaction online, community members sometimes +meet in person at user's group and tutorial sessions run by pvlib python +maintainers and community members alike. +To date, these meetings have been held at the IEEE Photovoltaics Specialists +Conference (PVSC), the PVPMC Workshops, and the PyData Global conference. +\autoref{fig:timeline} shows a timeline of these meetings, along with other +notable events in the project's history. + +![pvlib python major event timeline: releases (top), community events (middle), and other project milestones (bottom).\label{fig:timeline}](timeline2.pdf) + +Finally, it is worth pointing out that pvlib python contributors and users +are part of a broader community for the pvlib software "family", which includes pvanalytics, a +package for PV data quality assurance and feature recognition +algorithms [@pvpmc2022_pvanalytics_update], and twoaxistracking, a package +for simulating self-shading in arrays of two-axis solar trackers [@Jensen2022]. +Moreover, looking beyond pvlib and its affiliated packages, we see that Python +is proving to be the most common programming language in general for +open-source PV modeling and analysis software. The packages mentioned here +make up one portion of a growing landscape of Python-for-PV projects [@Holmgren2018]. -CH acknowledges support from the U.S. Department of Energy's Solar -Energy Technology Office. -WH and CH acknowledge support from the Department of Energy Solar -Forecasting 2 program. +# Acknowledgements -MM acknowledges support from SunPower Corporation (2016-2017). +Although much of the development and maintenance of pvlib python is on a +volunteer basis, the project has also been supported by projects with various +funding sources, including: + +- The U.S. Department of Energy’s Solar Energy Technology Office, through + the PV Performance Modeling Collaborative (PVPMC) and other projects +- The Danish Energy Agency through grant nos. 64020-1082 and 134232-510237 +- NumFOCUS's Small Development Grant program +- Google's Summer of Code program + +pvlib python benefits enormously from building on top of +various high-quality packages that have become de facto standards in the python +ecosystem: numpy [@numpy], pandas [@pandas], scipy [@scipy], and numba [@numba] +for numerics, matplotlib [@matplotlib] for plotting, +sphinx [@sphinx] for documentation, and pytest [@pytest] for automated testing. +The project also benefits from online infrastructure generously provided free +of charge, including GitHub (code development and automated testing) and +ReadTheDocs.org (documentation building and hosting). + +This work was supported by the U.S. Department of Energy’s Office of Energy +Efficiency and Renewable Energy (EERE) under the Solar Energy Technologies +Office Award Number 38267. Sandia National Laboratories is a multimission +laboratory managed and operated by National Technology & Engineering Solutions +of Sandia, LLC, a wholly owned subsidiary of Honeywell International Inc., for +the U.S. Department of Energy’s National Nuclear Security Administration under +contract DE-NA0003525. This paper describes objective technical results and +analysis. Any subjective views or opinions that might be expressed in the paper +do not necessarily represent the views of the U.S. Department of Energy or +the United States Government. -Sandia National Laboratories is a multi-mission laboratory managed and -operated by National Technology and Engineering Solutions of Sandia, -LLC., a wholly owned subsidiary of Honeywell International, Inc., for -the U.S. Department of Energy's National Nuclear Security Administration -under contract DE-NA-0003525. # References diff --git a/paper/timeline2.pdf b/paper/timeline2.pdf new file mode 100644 index 0000000000..05fcbf12a3 Binary files /dev/null and b/paper/timeline2.pdf differ