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,93 @@
+.. _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 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 not directly related to PV
+  efficiency.
+- *cell temperature*: the temperature of the PV cell itself.  The relevant
+  temperature for PV modeling, but almost never measured directly.
+
+Cell temperature is typically thought to be slightly higher than module
+temperature.
+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.  Different parameter values may be used for different PV
+module technologies and/or the mounting conditions of the module.
+
+Another way to classify 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 variation in
+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 |
++===========================================+========+============+================+=====================+============+================+
+| :py:func:`~pvlib.temperature.faiman`      | either |            | ✓              | ✓                   | ✓          |                |
++-------------------------------------------+--------+------------+----------------+---------------------+------------+----------------+
+| :py:func:`~pvlib.temperature.faiman_rad`  | either |            | ✓              | ✓                   | ✓          | ✓              |
++-------------------------------------------+--------+------------+----------------+---------------------+------------+----------------+
+| :py:func:`~pvlib.temperature.fuentes`     | cell   | ✓          | ✓              | ✓                   | ✓          |                |
++-------------------------------------------+--------+------------+----------------+---------------------+------------+----------------+
+| :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 |            | ✓              | ✓                   | ✓          |                |
++-------------------------------------------+--------+------------+----------------+---------------------+------------+----------------+
+
+
+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.
+
+Module-specific values can be obtained via testing, for example following
+the IEC 61853-2 standard.
+
+Currently, pvlib provides no functionality for fitting parameter values
+using measured temperature.
+
+
+Other functions
+---------------
+
+pvlib also provides a few other functions for temperature modeling:
+
+- :py:func:`~pvlib.temperature.prilliman`: an "add-on" model that introduces
+  transience to steady-state models.
+- :py:func:`~pvlib.temperature.sapm_cell_from_module`: a model for
+  estimating cell temperature from module temperature.
+- :py:func:`~pvlib.temperature.generic_linear`: a generic linear model form,
+  equivalent to several conventional temperature models.

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

@@ -46,6 +46,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`)
 
 
 Testing