partial faq page

Author: kandersolar

docs/examples/README.rst

@@ -1,3 +1,5 @@
+.. _example_gallery:
+
 Example Gallery
 ===============
 

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 <https://groups.google.com/g/pvlib-python/c/PDDic0SS6ao/m/Z-WKj7C6BwAJ>`_
+and `two <https://groups.google.com/g/pvlib-python/c/b1mf4Y1qHBY/m/tK2FBCJyBgAJ>`_)
+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 <https://numpy.org>`_) 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 <https://github.com/NREL/SAM/tree/develop/deploy/libraries>`_,
+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`.

docs/sphinx/source/user_guide/index.rst

@@ -18,3 +18,4 @@ User Guide
    comparison_pvlib_matlab
    variables_style_rules
    singlediode
+   faq