From b37211777804401c1ccfdc326ea755aea0a9caad Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Mon, 3 Nov 2025 18:03:50 -0500 Subject: [PATCH 1/2] create temperature user guide page --- docs/sphinx/source/user_guide/index.rst | 1 + .../modeling_topics/temperature.rst | 93 +++++++++++++++++++ docs/sphinx/source/whatsnew/v0.13.2.rst | 1 + 3 files changed, 95 insertions(+) create mode 100644 docs/sphinx/source/user_guide/modeling_topics/temperature.rst diff --git a/docs/sphinx/source/user_guide/index.rst b/docs/sphinx/source/user_guide/index.rst index 07102a5630..f8da3b6b44 100644 --- a/docs/sphinx/source/user_guide/index.rst +++ b/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 diff --git a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst new file mode 100644 index 0000000000..e3dc6afc28 --- /dev/null +++ b/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. diff --git a/docs/sphinx/source/whatsnew/v0.13.2.rst b/docs/sphinx/source/whatsnew/v0.13.2.rst index d4cd10b5e7..b282d2a93a 100644 --- a/docs/sphinx/source/whatsnew/v0.13.2.rst +++ b/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 From d5699d1059817ff0c7ac99c59290e38066b2d481 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Tue, 4 Nov 2025 08:30:28 -0500 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Cliff Hansen --- .../modeling_topics/temperature.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst index e3dc6afc28..67d27872f0 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst @@ -5,7 +5,7 @@ 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 +simple empirical equations requiring just a few multiplications to more complex thermal balance models with numerical integration. Types of models @@ -14,8 +14,8 @@ 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. + of a PV module. Easy to measure, but usually a few degrees 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. @@ -24,8 +24,8 @@ 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. +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: @@ -36,7 +36,7 @@ the thermal inertia of a PV module. Temperature models are either: - *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 +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 @@ -71,7 +71,8 @@ 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. +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. @@ -85,8 +86,8 @@ 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.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,