add temperature.sapm_cell_from_module (#938)

* add temperature.sapm_cell_to_module

* add See also to docstring

* Update pvlib/temperature.py

Co-Authored-By: Will Holmgren <[email protected]>

* remove hyphen

* remove ~ from function paths

Co-authored-by: Will Holmgren <[email protected]>

Author: cwhanse

docs/sphinx/source/api.rst

@@ -232,6 +232,7 @@ PV temperature models
 
    temperature.sapm_cell
    temperature.sapm_module
+   temperature.sapm_cell_from_module
    temperature.pvsyst_cell
    temperature.faiman
 

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

@@ -21,13 +21,17 @@ Enhancements
 * TMY3 dataframe returned by :py:func:`~pvlib.iotools.read_tmy3` now contains
   the original ``Date (MM/DD/YYYY)`` and ``Time (HH:MM)`` columns that the
   indices were parsed from. (:pull:`866`)
-* Add :py:func:`~pvlib.pvsystem.PVSystem.faiman` and added
+* Add :py:func:`pvlib.pvsystem.PVSystem.faiman` and added
   ``temperature_model='faiman'`` option to :py:class:`~pvlib.modelchain.ModelChain`
   (:pull:`897`) (:issue:`836`).
+* Add Kimber soiling model :py:func:`pvlib.losses.soiling_kimber`. (:pull:`860`)
+* Add :py:func:`pvlib.iotools.read_pvgis_tmy` for files downloaded using the
 * Add Kimber soiling model :py:func:`pvlib.soiling.kimber`. (:pull:`860`,
    :issue`935`)
 * Add :func:`~pvlib.iotools.read_pvgis_tmy` for files downloaded using the
   PVGIS tool. (:issue:`880`)
+* Add :py:func:`pvlib.temperature.sapm_cell_from_module` to convert back of
+  module temperature to cell temperature (:issue:`927`)
 * Add new module :py:mod:`pvlib.snow` to contain models related to snow coverage and effects on a PV system. (:pull:`764`)
 * Add snow coverage model :py:func:`pvlib.snow.coverage_nrel` and function to identify when modules are fully covered by snow :py:func:`pvlib.snow.fully_covered_nrel`. (:issue:`577`)
 * Add function :py:func:`pvlib.snow.dc_loss_nrel` for effect of snow coverage on DC output. (:pull:`764`)

pvlib/temperature.py

@@ -33,7 +33,7 @@ def _temperature_model_params(model, parameter_set):
 def sapm_cell(poa_global, temp_air, wind_speed, a, b, deltaT,
               irrad_ref=1000):
     r'''
-    Calculate cell temperature per the Sandia PV Array Performance Model.
+    Calculate cell temperature per the Sandia Array Performance Model.
 
     See [1]_ for details on the Sandia Array Performance Model.
 
@@ -107,6 +107,11 @@ def sapm_cell(poa_global, temp_air, wind_speed, a, b, deltaT,
        Model", SAND Report 3535, Sandia National Laboratories, Albuquerque,
        NM.
 
+    See also
+    --------
+    sapm_cell_from_module
+    sapm_module
+
     Examples
     --------
     >>> from pvlib.temperature import sapm_cell, TEMPERATURE_MODEL_PARAMETERS
@@ -116,12 +121,13 @@ def sapm_cell(poa_global, temp_air, wind_speed, a, b, deltaT,
     '''
     module_temperature = sapm_module(poa_global, temp_air, wind_speed,
                                      a, b)
-    return module_temperature + (poa_global / irrad_ref) * deltaT
+    return sapm_cell_from_module(module_temperature, poa_global, deltaT,
+                                 irrad_ref)
 
 
 def sapm_module(poa_global, temp_air, wind_speed, a, b):
     r'''
-    Calculate module back surface temperature per the Sandia PV Array
+    Calculate module back surface temperature per the Sandia Array
     Performance Model.
 
     See [1]_ for details on the Sandia Array Performance Model.
@@ -182,10 +188,84 @@ def sapm_module(poa_global, temp_air, wind_speed, a, b):
        Model", SAND Report 3535, Sandia National Laboratories, Albuquerque,
        NM.
 
+    See also
+    --------
+    sapm_cell
+    sapm_cell_from_module
     '''
     return poa_global * np.exp(a + b * wind_speed) + temp_air
 
 
+def sapm_cell_from_module(module_temperature, poa_global, deltaT,
+                          irrad_ref=1000):
+    r'''
+    Calculate cell temperature from module temperature using the Sandia Array
+    Performance Model.
+
+    See [1]_ for details on the Sandia Array Performance Model.
+
+    Parameters
+    ----------
+    module_temperature : numeric
+        Temperature of back of module surface [C].
+
+    poa_global : numeric
+        Total incident irradiance [W/m^2].
+
+    deltaT : float
+        Parameter :math:`\Delta T` in :eq:`sapm2` [C].
+
+    irrad_ref : float, default 1000
+        Reference irradiance, parameter :math:`E_{0}` in
+        :eq:`sapm2` [W/m^2].
+
+    Returns
+    -------
+    numeric, values in degrees C.
+
+    Notes
+    -----
+    The model for cell temperature :math:`T_{C}` is given by Eq. 12 in [1]_.
+
+    .. math::
+       :label: sapm2
+
+       T_{C} = T_{m} + \frac{E}{E_{0}} \Delta T
+
+    The module back surface temperature :math:`T_{m}` is implemented in
+    :py:func:`~pvlib.temperature.sapm_module`.
+
+    Model parameters depend both on the module construction and its mounting.
+    Parameter sets are provided in [1]_ for representative modules and
+    mounting, and are coded for convenience in
+    ``pvlib.temperature.TEMPERATURE_MODEL_PARAMETERS``.
+
+    +---------------+----------------+-------+---------+---------------------+
+    | Module        | Mounting       | a     | b       | :math:`\Delta T [C]`|
+    +===============+================+=======+=========+=====================+
+    | glass/glass   | open rack      | -3.47 | -0.0594 | 3                   |
+    +---------------+----------------+-------+---------+---------------------+
+    | glass/glass   | close roof     | -2.98 | -0.0471 | 1                   |
+    +---------------+----------------+-------+---------+---------------------+
+    | glass/polymer | open rack      | -3.56 | -0.075  | 3                   |
+    +---------------+----------------+-------+---------+---------------------+
+    | glass/polymer | insulated back | -2.81 | -0.0455 | 0                   |
+    +---------------+----------------+-------+---------+---------------------+
+
+    References
+    ----------
+    .. [1] King, D. et al, 2004, "Sandia Photovoltaic Array Performance
+       Model", SAND Report 3535, Sandia National Laboratories, Albuquerque,
+       NM.
+
+    See also
+    --------
+    sapm_cell
+    sapm_module
+    '''
+    return module_temperature + (poa_global / irrad_ref) * deltaT
+
+
 def pvsyst_cell(poa_global, temp_air, wind_speed=1.0, u_c=29.0, u_v=0.0,
                 eta_m=0.1, alpha_absorption=0.9):
     r"""

pvlib/tests/test_temperature.py

@@ -26,6 +26,12 @@ def test_sapm_module(sapm_default):
     assert_allclose(default, 40.809, 3)
 
 
+def test_sapm_cell_from_module(sapm_default):
+    default = temperature.sapm_cell_from_module(50, 900,
+                                                sapm_default['deltaT'])
+    assert_allclose(default, 50 + 900 / 1000 * sapm_default['deltaT'])
+
+
 def test_sapm_ndarray(sapm_default):
     temps = np.array([0, 10, 5])
     irrads = np.array([0, 500, 0])