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,96 @@
+.. _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 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 and 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 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`     | 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 |            | ✓              | ✓                   | ✓          |                       |
++-------------------------------------------+--------+------------+----------------+---------------------+------------+-----------------------+
+
+.. [#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.
+- :py:func:`~pvlib.temperature.generic_linear`: a generic linear model form,
+  equivalent to several conventional temperature models.
+
+
+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.
+
+Module-specific values can be obtained via testing, for example following
+the IEC 61853-2 standard.
+
+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`.
+
+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`)