Add guidance about temperature modeling to User Guide

docs/sphinx/source/user_guide/index.rst

@@ -26,6 +26,7 @@ This user guide is an overview and explains some of the key features of pvlib.
    modeling_topics/clearsky
    modeling_topics/weather_data
    modeling_topics/singlediode
+   modeling_topics/temperature
 
 .. toctree::
    :maxdepth: 2

docs/sphinx/source/user_guide/modeling_topics/temperature.rst

@@ -0,0 +1,105 @@
+.. _temperature:
+
+Temperature models
+==================
+
+pvlib provides a variety of models for predicting the operating temperature
+of a PV module from irradiance and weather inputs.  These models range from
+simple empirical equations requiring just a few multiplications to more complex
+thermal balance models with numerical integration.
+
+Types of models
+---------------
+
+Temperature models predict one of two quantities:
+
+- *module temperature*: the temperature as measured at the back surface
+  of a PV module.  Easy to measure, but usually marginally less
+  than the cell temperature which determines efficiency.
+- *cell temperature*: the temperature of the PV cell itself.  The relevant
+  temperature for PV modeling, but almost never measured directly.
+
+Temperature models estimate these quantities using inputs like incident
+irradiance, ambient temperature, and wind speed.  Each model also takes
+a set of parameter values that represent how a PV module responds to
+those inputs.  Parameter values generally depend on both the PV
+module technologies, the mounting configuration of the module,
+and on any weather parameters that are not included in the model.
+Note that, despite models conventionally being associated with either
+cell or module temperature, it is actually the parameter values that determine
+which of the two temperatures are predicted, as they will produce the same
+type of temperature from which they were originally derived.
+
+Another aspect of temperature models is whether they account for
+the thermal inertia of a PV module.  Temperature models are either:
+
+- *steady-state*: the module is assumed to have been at the specified operating
+  conditions for a sufficiently long time for its temperature to reach
+  equilibrium.
+- *transient*: the module's thermal inertia is included in the model,
+  causing a lag in modeled temperature change following changes in the inputs.
+
+Other effects that temperature models may consider include the
+photoconversion efficiency and radiative cooling.
+
+The temperature models currently available in pvlib are summarized in the
+following table:
+
++----------------------------------------------+--------+------------+---------------------------------------------------------------------------+
+| Model                                        | Type   | Transient? | Inputs                                                                    |
+|                                              |        |            +----------------+---------------------+------------+-----------------------+
+|                                              |        |            | POA irradiance | Ambient temperature | Wind speed | Downwelling IR [#f1]_ |
++==============================================+========+============+================+=====================+============+=======================+
+| :py:func:`~pvlib.temperature.faiman`         | either |            | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.faiman_rad`     | either |            | ✓              | ✓                   | ✓          | ✓                     |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.fuentes`        | either | ✓          | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.generic_linear` | either |            | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.noct_sam`       | cell   |            | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.pvsyst_cell`    | cell   |            | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.ross`           | cell   |            | ✓              | ✓                   |            |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.sapm_cell`      | cell   |            | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+| :py:func:`~pvlib.temperature.sapm_module`    | module |            | ✓              | ✓                   | ✓          |                       |
++----------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+
+.. [#f1] Downwelling infrared radiation.
+
+In addition to the core models above, pvlib provides several other functions
+for temperature modeling:
+
+- :py:func:`~pvlib.temperature.prilliman`: an "add-on" model that reprocesses
+  the output of a steady-state model to apply transient effects.
+- :py:func:`~pvlib.temperature.sapm_cell_from_module`: a model for
+  estimating cell temperature from module temperature.
+
+
+Model parameters
+----------------
+
+Some temperature model functions provide default values for their parameters,
+and several additional sets of temperature model parameter values are
+available in :py:data:`pvlib.temperature.TEMPERATURE_MODEL_PARAMETERS`.
+However, these generic values may not be suitable for all modules and mounting
+configurations. It should be noted that using the default parameter values for each 
+model generally leads to different modules temperature predictions. This alone
+does not mean one model is better than another; it's just evidence that the measurements
+used to derive the default parameter values were taken on different PV systems in different
+locations under different conditions.
+
+Parameter values for one model (e.g. ``u0``, ``u1`` for :py:func:`~pvlib.temperature.faiman`)
+can be converted to another model (e.g. ``u_c``, ``u_v`` for :py:func:`~pvlib.temperature.pvsyst_cell`)
+using :py:class:`~pvlib.temperature.GenericLinearModel`.
+
+Module-specific values can be obtained via testing, for example following
+the IEC 61853-2 standard for the Faiman model; however, such values still do not capture 
+the dependency of temperature on system design and other variables.
+
+Currently, pvlib provides no functionality for fitting parameter values
+using measured temperature.

docs/sphinx/source/whatsnew/v0.13.2.rst

@@ -47,6 +47,7 @@ Enhancements
 Documentation
 ~~~~~~~~~~~~~
 * Provide an overview of single-diode modeling functionality in :ref:`singlediode`. (:pull:`2565`)
+* Provide an overview of temperature modeling functionality in :ref:`temperature`. (:pull:`2591`)
 * Fix typo in parameter name ``atmos_refract`` in :py:func:`pvlib.solarposition.spa_python`
   and :py:func:`pvlib.spa.solar_position`. (:issue:`2532`, :pull:`2592`)