Document "racking model" for temperature models

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

@@ -47,6 +47,9 @@ Documentation
   page, using the sphinx glossary directive. (:issue:`1421`, :pull:`2234`)
 * Explained how to write docstrings for new functions in :ref:`example-docstring`
   (:discussion:`2081`, :pull:`2254`)
+* Clarify mounting cases for parameters for :py:func:`~pvlib.temperature.sapm_module`
+  :py:func:`~pvlib.temperature.sapm_cell` and :py:func:`~pvlib.temperature.pvsyst_cell`.
+   (:issue:`1323`, :pull:`2293`)
 * Added the following variables to the :ref:`nomenclature` page:
 
   - `spectra` and `spectra_components` (:issue:`2150`, :pull:`2264`)

pvlib/pvsystem.py

@@ -168,9 +168,11 @@ class PVSystem:
         Inverter parameters as defined by the SAPM, CEC, or other.
 
     racking_model : string, optional
-        Valid strings are 'open_rack', 'close_mount', 'freestanding',
-        'insulated', or 'insulated_back'.
-        Used to identify a parameter set for the cell temperature model.
+        Valid strings are ``'open_rack'``, ``'close_mount'``,
+        ``'freestanding'``, and ``'insulated_back'`. Used to identify a
+        parameter set for the SAPM cell temperature model.
+        See :py:func:`~pvlib.temperature.sapm_module` and
+        :py:func:`~pvlib.temperature.pvsyst_cell` for definitions.
 
     losses_parameters : dict or Series, optional
         Losses parameters as defined by PVWatts or other.
@@ -1393,9 +1395,11 @@ class FixedMount(AbstractMount):
         West=270. [degrees]
 
     racking_model : str, optional
-        Valid strings are 'open_rack', 'close_mount', 'freestanding',
-        'insulated', or 'insulated_back'.
-        Used to identify a parameter set for the cell temperature model.
+        Valid strings are ``'open_rack'``, ``'close_mount'``,
+        ``'freestanding'``, and ``'insulated_back'`. Used to identify a
+        parameter set for the SAPM cell temperature model.
+        See :py:func:`~pvlib.temperature.sapm_module`  and
+        :py:func:`~pvlib.temperature.pvsyst_cell` for definitions.
 
     module_height : float, optional
        The height above ground of the center of the module [m]. Used for
@@ -1471,9 +1475,12 @@ class SingleAxisTrackerMount(AbstractMount):
         `cross_axis_tilt`. [degrees]
 
     racking_model : str, optional
-        Valid strings are 'open_rack', 'close_mount', 'freestanding',
-        'insulated', or 'insulated_back'.
-        Used to identify a parameter set for the cell temperature model.
+        Valid strings are ``'open_rack'``, ``'close_mount'``,
+        ``'freestanding'``, and ``'insulated_back'`. Used to identify a
+        parameter set for the SAPM cell temperature model.
+        ``'open_rack'`` should be used for systems with single-axis trackers.
+        See :py:func:`~pvlib.temperature.sapm_module` and
+        :py:func:`~pvlib.temperature.pvsyst_cell` for definitions.
 
     module_height : float, optional
        The height above ground of the center of the module [m]. Used for

pvlib/temperature.py

@@ -125,6 +125,18 @@ def sapm_cell(poa_global, temp_air, wind_speed, a, b, deltaT,
     | glass/polymer | insulated back | -2.81 | -0.0455 | 0                   |
     +---------------+----------------+-------+---------+---------------------+
 
+    Mounting cases can be described in terms of air flow across and around the
+    rear-facing surface of the module:
+
+    * "open rack" refers to mounting that allows relatively free air flow.
+      This case is typical of ground-mounted systems on fixed racking or
+      single axis trackers.
+    * "close roof" refers to limited or restricted air flow. This case is
+      typical of roof-mounted systems with some gap behind the module.
+    * "insulated back" refers to systems with no air flow contacting the rear
+      surface of the module. This case is typical of building-integrated PV
+      systems, or systems laid flat on a ground surface.
+
     References
     ----------
     .. [1] King, D. et al, 2004, "Sandia Photovoltaic Array Performance
@@ -206,6 +218,18 @@ def sapm_module(poa_global, temp_air, wind_speed, a, b):
     | glass/polymer | insulated back | -2.81 | -0.0455 | 0                   |
     +---------------+----------------+-------+---------+---------------------+
 
+    Mounting cases can be described in terms of air flow across and around the
+    rear-facing surface of the module:
+
+    * "open rack" refers to mounting that allows relatively free air flow.
+      This case is typical of ground-mounted systems on fixed racking or
+      single axis trackers.
+    * "close roof" refers to limited or restricted air flow. This case is
+      typical of roof-mounted systems with some gap behind the module.
+    * "insulated back" refers to systems with no air flow contacting the rear
+      surface of the module. This case is typical of building-integrated PV
+      systems, or systems laid flat on a ground surface.
+
     References
     ----------
     .. [1] King, D. et al, 2004, "Sandia Photovoltaic Array Performance
@@ -276,6 +300,18 @@ def sapm_cell_from_module(module_temperature, poa_global, deltaT,
     | glass/polymer | insulated back | -2.81 | -0.0455 | 0                   |
     +---------------+----------------+-------+---------+---------------------+
 
+    Mounting cases can be described in terms of air flow across and around the
+    rear-facing surface of the module:
+
+    * "open rack" refers to mounting that allows relatively free air flow.
+      This case is typical of ground-mounted systems on fixed racking or
+      single axis trackers.
+    * "close roof" refers to limited or restricted air flow. This case is
+      typical of roof-mounted systems with some gap behind the module.
+    * "insulated back" refers to systems with no air flow contacting the rear
+      surface of the module. This case is typical of building-integrated PV
+      systems, or systems laid flat on a ground surface.
+
     References
     ----------
     .. [1] King, D. et al, 2004, "Sandia Photovoltaic Array Performance
@@ -360,6 +396,16 @@ def pvsyst_cell(poa_global, temp_air, wind_speed=1.0, u_c=29.0, u_v=0.0,
     | insulated    | 15.0          | 0.0           |
     +--------------+---------------+---------------+
 
+    Mounting cases can be described in terms of air flow across and around the
+    rear-facing surface of the module:
+
+    * "freestanding" refers to mounting that allows relatively free air
+      circulation around the modules. This case is typical of ground-mounted
+      systems on tilted, fixed racking or single axis trackers.
+    * "insluated" refers to mounting with air flow across only the front
+      surface. This case is typical of roof-mounted systems with no gap
+      behind the module.
+
     References
     ----------
     .. [1] "PVsyst 7 Help", [Online]. Available: