From b37211777804401c1ccfdc326ea755aea0a9caad Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Mon, 3 Nov 2025 18:03:50 -0500 Subject: [PATCH 1/7] 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/7] 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, From 94d2a71d2d11cad0728f5200bbb4c92e3f0dd172 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Thu, 20 Nov 2025 09:31:22 -0500 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: RDaxini <143435106+RDaxini@users.noreply.github.com> --- docs/sphinx/source/user_guide/modeling_topics/temperature.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst index 67d27872f0..567560d33a 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst @@ -14,13 +14,11 @@ 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 a few degrees less + 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. -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 From 13d4138d16e0b5ecb124c14d7b3fc096aa99a09f Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Thu, 20 Nov 2025 09:41:23 -0500 Subject: [PATCH 4/7] add mention of parameter conversion with GenericLinearModel --- docs/sphinx/source/user_guide/modeling_topics/temperature.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst index 67d27872f0..28281d397c 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst @@ -77,6 +77,10 @@ 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.GeneralLinearModel`. + Currently, pvlib provides no functionality for fitting parameter values using measured temperature. From 0a25860cad16f9179755cca55387fdbfdc28e0dc Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Thu, 20 Nov 2025 09:50:55 -0500 Subject: [PATCH 5/7] add note about IR --- .../modeling_topics/temperature.rst | 44 ++++++++++--------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst index 63bfccb04d..33e2686521 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst @@ -40,27 +40,29 @@ 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 | 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. Model parameters From 34ef1591baa1cfd0b093a350fe721e88a553a536 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Thu, 20 Nov 2025 09:55:21 -0500 Subject: [PATCH 6/7] move "other functions" up to below the table --- .../modeling_topics/temperature.rst | 24 +++++++++---------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst index 33e2686521..a0cbe251e0 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst @@ -65,6 +65,17 @@ following table: .. [#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 ---------------- @@ -83,16 +94,3 @@ using :py:class:`~pvlib.temperature.GeneralLinearModel`. 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 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. From b2ecc30096220135c3f6587483f688e4c09ff5d9 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Thu, 20 Nov 2025 10:09:40 -0500 Subject: [PATCH 7/7] fix spelling --- docs/sphinx/source/user_guide/modeling_topics/temperature.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst index a0cbe251e0..b8471c780c 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/temperature.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/temperature.rst @@ -90,7 +90,7 @@ 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.GeneralLinearModel`. +using :py:class:`~pvlib.temperature.GenericLinearModel`. Currently, pvlib provides no functionality for fitting parameter values using measured temperature.