From a37dc0864155d688c0a0a2fccbe33519a2e2f4b7 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Mon, 12 Sep 2022 21:51:30 -0400 Subject: [PATCH 01/10] partial faq page --- docs/examples/README.rst | 2 + docs/sphinx/source/user_guide/faq.rst | 121 ++++++++++++++++++++++++ docs/sphinx/source/user_guide/index.rst | 1 + 3 files changed, 124 insertions(+) create mode 100644 docs/sphinx/source/user_guide/faq.rst diff --git a/docs/examples/README.rst b/docs/examples/README.rst index 4f0e8ab71c..332e49d65e 100644 --- a/docs/examples/README.rst +++ b/docs/examples/README.rst @@ -1,3 +1,5 @@ +.. _example_gallery: + Example Gallery =============== diff --git a/docs/sphinx/source/user_guide/faq.rst b/docs/sphinx/source/user_guide/faq.rst new file mode 100644 index 0000000000..3ab5ae45a6 --- /dev/null +++ b/docs/sphinx/source/user_guide/faq.rst @@ -0,0 +1,121 @@ +.. _faq: + +Frequently Asked Questions +========================== + +General Questions +***************** + +What is pvlib? +-------------- + +pvlib is a free and open-source python software library for modeling +the electrical performance of solar photovoltaic (PV) systems. It provides +implementations of scientific models for many topics relevant for PV modeling. + +For additional details about the project, see :ref:`package_overview`. +For examples of using pvlib, see :ref:`example_gallery`. + + +How does pvlib compare to other PV modeling tools like PVsyst or SAM? +--------------------------------------------------------------------- + +pvlib is similar to tools like PVsyst and SAM in that it can be used +for "weather-to-power" modeling to model system energy production +based on system configuration and a weather dataset. However, pvlib +is also very different in that you use pvlib via python code instead +of via a GUI. pvlib is also more of a toolbox or a framework to use +to build your own modeling process (although some pre-built workflows +are available as well). + + +Usage Questions +*************** + +All I have is GHI, how do I get to POA? +--------------------------------------- + +Going from GHI to POA irradiance is a two-step process. The first step is to +use a decomposition model (also called a separation model) to estimate the +DNI and DHI corresponding to your GHI. For a list of decomposition +models available in pvlib, see :ref:`dniestmodels`. + +The second step is to transpose those estimated DNI and DHI components into +POA components. This is most easily done with the +:py:func:`pvlib.irradiance.get_total_irradiance` function. + + +Can I use PVsyst (PAN/OND) files with pvlib? +-------------------------------------------- + +Currently, pvlib does not have the ability to import any PVsyst file formats. +Certain formats of particular interest (e.g. PAN files) may be added in a future +version. Until then, these Google Group threads +(`one `_ +and `two `_) +may be useful for some users. + + +Why don't my simulation results make sense? +------------------------------------------- + +pvlib does not prevent you from using models improperly and generating +invalid results. It is on you as the user to understand the models you +are using. However, here are a few modeling errors that beginners sometimes +run into: + +- *Improper time zone localization*: calculating solar positions is often the + first step of a modeling process and relies on timestamps being localized to + the correct time zone. A telltale sign of improper time zones is a time + shift between solar position and the irradiance data. + For more information on handling timezone correctly, see :ref:`timetimezones`. +- TODO other beginner issues + +Matplotlib and pandas have very powerful plotting capabilities that are great +for tracking down where things went wrong in a modeling process. Try plotting +multiple a few days of intermediate time series in a single plot, looking for +inconsistencies like nonzero irradiance when the sun is below the horizon. +This will give you a clue of where to look for errors in your code. + + +I got a warning like ``RuntimeWarning: invalid value encountered in arccos``, what does it mean? +------------------------------------------------------------------------------------------------ + +It is fairly common to use pvlib models in conditions where they are not +applicable, for example attempting to calculate an IV curve at night. +In such cases the model failure doesn't really matter (nighttime values are +irrelevant), but the numerical packages that pvlib is built on +(e.g. `numpy `_) emit warnings complaining about +`invalid value`, `divide by zero`, etc. In these cases the warnings can +often be ignored without issue. + +However, that's not always the case: sometimes these warnings are caused +by an error in your code, for example by giving a function inappropriate inputs. +So, these warnings don't necessarily indicate a problem, but you shouldn't +get in the habit of immediately discounting them either. + + +I got an error like ``X has no attribute Y``, what does it mean? +---------------------------------------------------------------- + +If you see a function in the pvlib documentation that doesn't seem to exist +in your pvlib installation, the documentation is likely for a different version +of pvlib. You can check your installed pvlib version by running +``print(pvlib.__version__)`` in python. To switch documentation versions, use +the `v:` version switcher widget in the bottom right corner of this page. + +You can also upgrade your installed pvlib to the latest compatible version +with ``pip install -U pvlib``, but be sure to check the :ref:`whatsnew` +page to see what the differences between versions are. + + +The CEC table doesn't include my module or inverter, what should I do? +---------------------------------------------------------------------- + +The CEC tables for module and inverter parameters included in pvlib are periodically +copied from `SAM `_, +so you can check the tables there for more up-to-date tables. + +For modules, if even files don't include the module you're looking for either, +you can calculate CEC module model parameters from +datasheet information using :py:func:`pvlib.ivtools.sdm.fit_cec_sam`. diff --git a/docs/sphinx/source/user_guide/index.rst b/docs/sphinx/source/user_guide/index.rst index 3a0c204ffa..0db1bfd000 100644 --- a/docs/sphinx/source/user_guide/index.rst +++ b/docs/sphinx/source/user_guide/index.rst @@ -18,3 +18,4 @@ User Guide comparison_pvlib_matlab variables_style_rules singlediode + faq From d3443c8ba7ab9acd355924d875d87c79af37ea74 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Mon, 12 Sep 2022 21:57:53 -0400 Subject: [PATCH 02/10] typo --- docs/sphinx/source/user_guide/faq.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/user_guide/faq.rst b/docs/sphinx/source/user_guide/faq.rst index 3ab5ae45a6..8292e25212 100644 --- a/docs/sphinx/source/user_guide/faq.rst +++ b/docs/sphinx/source/user_guide/faq.rst @@ -116,6 +116,6 @@ The CEC tables for module and inverter parameters included in pvlib are periodic copied from `SAM `_, so you can check the tables there for more up-to-date tables. -For modules, if even files don't include the module you're looking for either, -you can calculate CEC module model parameters from +For modules, if even the SAM files don't include the module you're looking for +either, you can calculate CEC module model parameters from datasheet information using :py:func:`pvlib.ivtools.sdm.fit_cec_sam`. From 3fe89f87f23b7f323772edd1b89e6140098eb80d Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Mon, 12 Sep 2022 22:00:53 -0400 Subject: [PATCH 03/10] whatsnew --- docs/sphinx/source/whatsnew/v0.9.3.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/sphinx/source/whatsnew/v0.9.3.rst b/docs/sphinx/source/whatsnew/v0.9.3.rst index 2f3c643d05..0c65a08ff7 100644 --- a/docs/sphinx/source/whatsnew/v0.9.3.rst +++ b/docs/sphinx/source/whatsnew/v0.9.3.rst @@ -23,6 +23,7 @@ Testing Documentation ~~~~~~~~~~~~~ +* Added an FAQ page to the docs: :ref:`faq`. (:issue:`1546`, :pull:`1549`) Benchmarking From ccc35cb52664d298d0edcb02d3b4435827365246 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Tue, 13 Sep 2022 09:35:53 -0400 Subject: [PATCH 04/10] add "where can I get irradiance data" Co-Authored-By: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com> --- docs/sphinx/source/user_guide/faq.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/sphinx/source/user_guide/faq.rst b/docs/sphinx/source/user_guide/faq.rst index 8292e25212..7815397971 100644 --- a/docs/sphinx/source/user_guide/faq.rst +++ b/docs/sphinx/source/user_guide/faq.rst @@ -45,6 +45,22 @@ POA components. This is most easily done with the :py:func:`pvlib.irradiance.get_total_irradiance` function. +Where can I get irradiance data for my simulation? +-------------------------------------------------- + +pvlib has a module called iotools which has several functions for +retrieving irradiance data as well as reading standard file formats +such as EPW, TMY2, and TMY3. For free irradiance data, you may +consider NREL's NSRDB which can be accessed using the +:py:func:`pvlib.iotools.get_psm3` function and is available for +North America. For Europe and Africa, you may consider looking into +CAMS (:py:func:`pvlib.iotools.get_cams`). +PVGIS (:py:func:`pvlib.iotools.get_pvgis_hourly`) is another option, which +provides irradiance from several different databases with near global coverage. +pvlib also has functions for accessing a plethora of ground-measured +irradiance datasets, including the BSRN, SURFRAD, SRML, and NREL's MIDC. + + Can I use PVsyst (PAN/OND) files with pvlib? -------------------------------------------- From a41a47c58c59ded0c22f1dce05d8902d106d67ad Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Tue, 13 Sep 2022 09:40:39 -0400 Subject: [PATCH 05/10] Apply suggestions from code review Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com> --- docs/sphinx/source/user_guide/faq.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/user_guide/faq.rst b/docs/sphinx/source/user_guide/faq.rst index 8292e25212..ee2a5bf051 100644 --- a/docs/sphinx/source/user_guide/faq.rst +++ b/docs/sphinx/source/user_guide/faq.rst @@ -24,7 +24,8 @@ pvlib is similar to tools like PVsyst and SAM in that it can be used for "weather-to-power" modeling to model system energy production based on system configuration and a weather dataset. However, pvlib is also very different in that you use pvlib via python code instead -of via a GUI. pvlib is also more of a toolbox or a framework to use +of via a GUI, which makes pvlib ideal for automating tasks. pvlib +is also more of a toolbox or a framework to use to build your own modeling process (although some pre-built workflows are available as well). @@ -35,7 +36,8 @@ Usage Questions All I have is GHI, how do I get to POA? --------------------------------------- -Going from GHI to POA irradiance is a two-step process. The first step is to +Going from GHI to plane of array (POA) irradiance is a two-step process. +The first step is to use a decomposition model (also called a separation model) to estimate the DNI and DHI corresponding to your GHI. For a list of decomposition models available in pvlib, see :ref:`dniestmodels`. From b1e0264bb88c297d23ff1194f5a3ae46bbd45ba8 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Fri, 16 Sep 2022 12:51:17 -0400 Subject: [PATCH 06/10] Revert "whatsnew" This reverts commit 3fe89f87f23b7f323772edd1b89e6140098eb80d. --- docs/sphinx/source/whatsnew/v0.9.3.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/sphinx/source/whatsnew/v0.9.3.rst b/docs/sphinx/source/whatsnew/v0.9.3.rst index 0c65a08ff7..2f3c643d05 100644 --- a/docs/sphinx/source/whatsnew/v0.9.3.rst +++ b/docs/sphinx/source/whatsnew/v0.9.3.rst @@ -23,7 +23,6 @@ Testing Documentation ~~~~~~~~~~~~~ -* Added an FAQ page to the docs: :ref:`faq`. (:issue:`1546`, :pull:`1549`) Benchmarking From ab7ece93917f119b114dee9986bc6becc6349f2d Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Fri, 16 Sep 2022 12:52:09 -0400 Subject: [PATCH 07/10] move whatsnew note to 0.9.4 --- docs/sphinx/source/whatsnew/v0.9.4.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/sphinx/source/whatsnew/v0.9.4.rst b/docs/sphinx/source/whatsnew/v0.9.4.rst index ea89248743..0347852fec 100644 --- a/docs/sphinx/source/whatsnew/v0.9.4.rst +++ b/docs/sphinx/source/whatsnew/v0.9.4.rst @@ -21,6 +21,7 @@ Testing Documentation ~~~~~~~~~~~~~ +* Added an FAQ page to the docs: :ref:`faq`. (:issue:`1546`, :pull:`1549`) Benchmarking From 360abac6d3763ea2563bb1ee313a190cb1494a9a Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Tue, 27 Sep 2022 13:05:42 -0400 Subject: [PATCH 08/10] faq edits --- docs/sphinx/source/user_guide/faq.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/sphinx/source/user_guide/faq.rst b/docs/sphinx/source/user_guide/faq.rst index 6cb991a398..4b3cd3bdfd 100644 --- a/docs/sphinx/source/user_guide/faq.rst +++ b/docs/sphinx/source/user_guide/faq.rst @@ -79,19 +79,20 @@ Why don't my simulation results make sense? pvlib does not prevent you from using models improperly and generating invalid results. It is on you as the user to understand the models you -are using. However, here are a few modeling errors that beginners sometimes -run into: - -- *Improper time zone localization*: calculating solar positions is often the - first step of a modeling process and relies on timestamps being localized to - the correct time zone. A telltale sign of improper time zones is a time - shift between solar position and the irradiance data. - For more information on handling timezone correctly, see :ref:`timetimezones`. -- TODO other beginner issues - +are using. However, one modeling error that beginners sometimes +run into is improper time zone localization: calculating solar +positions is often the first step of a modeling process +and relies on timestamps being localized to the correct time zone. +A telltale sign of improper time zones is a time shift between solar +position and the irradiance data (for example, ``solar_elevation`` +peaks at a different time from clear-sky ``ghi``). +For more information on handling timezone correctly, see :ref:`timetimezones`. + +More generally, inspecting the simulation results visually is a good first +step when investigating strange results. Matplotlib and pandas have very powerful plotting capabilities that are great for tracking down where things went wrong in a modeling process. Try plotting -multiple a few days of intermediate time series in a single plot, looking for +a few days of intermediate time series in a single plot, looking for inconsistencies like nonzero irradiance when the sun is below the horizon. This will give you a clue of where to look for errors in your code. @@ -124,7 +125,7 @@ the `v:` version switcher widget in the bottom right corner of this page. You can also upgrade your installed pvlib to the latest compatible version with ``pip install -U pvlib``, but be sure to check the :ref:`whatsnew` -page to see what the differences between versions are. +page to see the differences between versions. The CEC table doesn't include my module or inverter, what should I do? From 272e5102b36f46dfa0918442b6971c122dee4ee7 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Fri, 2 Dec 2022 14:48:21 -0500 Subject: [PATCH 09/10] link FAQ in readme --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 88c132673a..0186295f84 100644 --- a/README.md +++ b/README.md @@ -93,8 +93,8 @@ but operate independently of it. Documentation ============= -Full documentation can be found at [readthedocs](http://pvlib-python.readthedocs.io/en/stable/). - +Full documentation can be found at [readthedocs](http://pvlib-python.readthedocs.io/en/stable/), +including an [FAQ](http://pvlib-python.readthedocs.io/en/stable/user_guide/faq.html) page. Installation ============ From ee93dbe04e3dc0aa87b0a1c7cefd334c54892d57 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Fri, 2 Dec 2022 15:11:13 -0500 Subject: [PATCH 10/10] Apply suggestions from code review Co-authored-by: Cliff Hansen --- docs/sphinx/source/user_guide/faq.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sphinx/source/user_guide/faq.rst b/docs/sphinx/source/user_guide/faq.rst index 4b3cd3bdfd..801588c691 100644 --- a/docs/sphinx/source/user_guide/faq.rst +++ b/docs/sphinx/source/user_guide/faq.rst @@ -79,10 +79,10 @@ Why don't my simulation results make sense? pvlib does not prevent you from using models improperly and generating invalid results. It is on you as the user to understand the models you -are using. However, one modeling error that beginners sometimes -run into is improper time zone localization: calculating solar +are using and to supply appropriate, correctly-formatted data. One modeling error that beginners sometimes +make is improper time zone localization. Calculating solar positions is often the first step of a modeling process -and relies on timestamps being localized to the correct time zone. +and this step relies on timestamps being localized to the correct time zone. A telltale sign of improper time zones is a time shift between solar position and the irradiance data (for example, ``solar_elevation`` peaks at a different time from clear-sky ``ghi``). @@ -92,7 +92,7 @@ More generally, inspecting the simulation results visually is a good first step when investigating strange results. Matplotlib and pandas have very powerful plotting capabilities that are great for tracking down where things went wrong in a modeling process. Try plotting -a few days of intermediate time series in a single plot, looking for +a few days of intermediate time series results in a single plot, looking for inconsistencies like nonzero irradiance when the sun is below the horizon. This will give you a clue of where to look for errors in your code.