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 ============ 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..801588c691 --- /dev/null +++ b/docs/sphinx/source/user_guide/faq.rst @@ -0,0 +1,140 @@ +.. _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, 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). + + +Usage Questions +*************** + +All I have is GHI, how do I get to POA? +--------------------------------------- + +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`. + +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. + + +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? +-------------------------------------------- + +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 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 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``). +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 +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. + + +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 the differences between versions. + + +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 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`. 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 diff --git a/docs/sphinx/source/whatsnew/v0.9.4.rst b/docs/sphinx/source/whatsnew/v0.9.4.rst index 72c2a1eaf9..c042f6aaa2 100644 --- a/docs/sphinx/source/whatsnew/v0.9.4.rst +++ b/docs/sphinx/source/whatsnew/v0.9.4.rst @@ -33,6 +33,7 @@ Testing Documentation ~~~~~~~~~~~~~ +* Added an FAQ page to the docs: :ref:`faq`. (:issue:`1546`, :pull:`1549`) * Fixed equation in :py:func:`pvlib.iam.martin_ruiz` docstring (:issue:`1561`, :pull:`1599`) Benchmarking