Document "racking model" for temperature models (#2293)

* describe racking model choices for SAPM temperature models

* whatsnew

* doc edits

* add freestanding back in

* definitions for pvsyst racking

* add link to pvsyst_cell

* update whatsnew

* review comments

* pvsyst for trackers

* Apply suggestions from code review

Co-authored-by: Kevin Anderson <[email protected]>

---------

Co-authored-by: Kevin Anderson <[email protected]>

Author: cwhanse

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,12 @@ 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'``,
+        ``'insulated_back'``, ``'freestanding'`` and ``'insulated'``.
+        Used to identify a parameter set for the SAPM or PVsyst 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 +1396,12 @@ 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'``,
+        ``'insulated_back'``, ``'freestanding'`` and ``'insulated'``.
+        Used to identify a parameter set for the SAPM or PVsyst 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 +1477,13 @@ 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'``,
+        ``'insulated_back'``, ``'freestanding'`` and ``'insulated'``.
+        Used to identify a parameter set for the SAPM or PVsyst cell
+        temperature model. ``'open_rack'`` or ``'freestanding'`` 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

@@ -118,13 +118,25 @@ def sapm_cell(poa_global, temp_air, wind_speed, a, b, deltaT,
     +===============+================+=======+=========+=====================+
     | glass/glass   | open rack      | -3.47 | -0.0594 | 3                   |
     +---------------+----------------+-------+---------+---------------------+
-    | glass/glass   | close roof     | -2.98 | -0.0471 | 1                   |
+    | glass/glass   | close mount    | -2.98 | -0.0471 | 1                   |
     +---------------+----------------+-------+---------+---------------------+
     | glass/polymer | open rack      | -3.56 | -0.075  | 3                   |
     +---------------+----------------+-------+---------+---------------------+
     | 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 mount" 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
@@ -199,13 +211,25 @@ def sapm_module(poa_global, temp_air, wind_speed, a, b):
     +===============+================+=======+=========+=====================+
     | glass/glass   | open rack      | -3.47 | -0.0594 | 3                   |
     +---------------+----------------+-------+---------+---------------------+
-    | glass/glass   | close roof     | -2.98 | -0.0471 | 1                   |
+    | glass/glass   | close mount    | -2.98 | -0.0471 | 1                   |
     +---------------+----------------+-------+---------+---------------------+
     | glass/polymer | open rack      | -3.56 | -0.075  | 3                   |
     +---------------+----------------+-------+---------+---------------------+
     | 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 mount" 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
@@ -269,13 +293,25 @@ def sapm_cell_from_module(module_temperature, poa_global, deltaT,
     +===============+================+=======+=========+=====================+
     | glass/glass   | open rack      | -3.47 | -0.0594 | 3                   |
     +---------------+----------------+-------+---------+---------------------+
-    | glass/glass   | close roof     | -2.98 | -0.0471 | 1                   |
+    | glass/glass   | close mount    | -2.98 | -0.0471 | 1                   |
     +---------------+----------------+-------+---------+---------------------+
     | glass/polymer | open rack      | -3.56 | -0.075  | 3                   |
     +---------------+----------------+-------+---------+---------------------+
     | 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 mount" 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.
+    * "insulated" 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: