temperature.py

"""
The ``temperature`` module contains functions for modeling temperature of
PV modules and cells.
"""

import numpy as np
import pandas as pd
from pvlib.tools import sind
from pvlib._deprecation import warn_deprecated
from pvlib.tools import _get_sample_intervals
import scipy
import scipy.constants
import warnings


TEMPERATURE_MODEL_PARAMETERS = {
    'sapm': {
        'open_rack_glass_glass': {'a': -3.47, 'b': -.0594, 'deltaT': 3},
        'close_mount_glass_glass': {'a': -2.98, 'b': -.0471, 'deltaT': 1},
        'open_rack_glass_polymer': {'a': -3.56, 'b': -.0750, 'deltaT': 3},
        'insulated_back_glass_polymer': {'a': -2.81, 'b': -.0455, 'deltaT': 0},
    },
    'pvsyst': {'freestanding': {'u_c': 29.0, 'u_v': 0},
               'insulated': {'u_c': 15.0, 'u_v': 0},
               'semi_integrated': {'u_c': 20.0, 'u_v': 0}}
}
"""Dictionary of temperature parameters organized by model.

There are keys for each model at the top level. Currently there are two models,
``'sapm'`` for the Sandia Array Performance Model, and ``'pvsyst'``. Each model
has a dictionary of configurations; a value is itself a dictionary containing
model parameters. Retrieve parameters by indexing the model and configuration
by name. Note: the keys are lower-cased and case sensitive.

Example
-------
Retrieve the open rack glass-polymer configuration for SAPM::

    from pvlib.temperature import TEMPERATURE_MODEL_PARAMETERS
    temperature_model_parameters = (
        TEMPERATURE_MODEL_PARAMETERS['sapm']['open_rack_glass_polymer'])
    # {'a': -3.56, 'b': -0.075, 'deltaT': 3}
"""


def _temperature_model_params(model, parameter_set):
    try:
        params = TEMPERATURE_MODEL_PARAMETERS[model]
        return params[parameter_set]
    except KeyError:
        msg = ('{} is not a named set of parameters for the {} cell'
               ' temperature model.'
               ' See pvlib.temperature.TEMPERATURE_MODEL_PARAMETERS'
               ' for names'.format(parameter_set, model))
        raise KeyError(msg)


def sapm_cell(poa_global, temp_air, wind_speed, a, b, deltaT,
              irrad_ref=1000.):
    r'''
    Calculate cell temperature per the Sandia Array Performance Model.

    See [1]_ for details on the Sandia Array Performance Model.

    Parameters
    ----------
    poa_global : numeric
        Total incident irradiance [W/m^2].

    temp_air : numeric
        Ambient dry bulb temperature [C].

    wind_speed : numeric
        Wind speed at a height of 10 meters [m/s].

    a : float
        Parameter :math:`a` in :eq:`sapm1`.

    b : float
        Parameter :math:`b` in :eq:`sapm1`.

    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 a pair of
    equations (Eq. 11 and 12 in [1]_).

    .. math::
       :label: sapm1

       T_{m} = E \times \exp (a + b \times WS) + T_{a}

    .. 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`.

    Inputs to the model are plane-of-array irradiance :math:`E` (W/m2) and
    ambient air temperature :math:`T_{a}` (C). 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 :data:`~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 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
       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
    >>> params = TEMPERATURE_MODEL_PARAMETERS['sapm']['open_rack_glass_glass']
    >>> sapm_cell(1000, 10, 0, **params)
    44.11703066106086
    '''
    module_temperature = sapm_module(poa_global, temp_air, wind_speed,
                                     a, b)
    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 Array
    Performance Model.

    See [1]_ for details on the Sandia Array Performance Model.

    Parameters
    ----------
    poa_global : numeric
        Total incident irradiance [W/m^2].

    temp_air : numeric
        Ambient dry bulb temperature [C].

    wind_speed : numeric
        Wind speed at a height of 10 meters [m/s].

    a : float
        Parameter :math:`a` in :eq:`sapm1mod`.

    b : float
        Parameter :math:`b` in :eq:`sapm1mod`.

    Returns
    -------
    numeric, values in degrees C.

    Notes
    -----
    The model for module temperature :math:`T_{m}` is given by Eq. 11 in [1]_.

    .. math::
       :label: sapm1mod

       T_{m} = E \times \exp (a + b \times WS) + T_{a}

    Inputs to the model are plane-of-array irradiance :math:`E` (W/m2) and
    ambient air temperature :math:`T_{a}` (C). Model outputs are surface
    temperature at the back of the module :math:`T_{m}` and cell temperature
    :math:`T_{C}`. 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
    :data:`~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 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
       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_cell_from_mod` [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_cell_from_mod

       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
    :data:`~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 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
       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,
                module_efficiency=0.1, alpha_absorption=0.9):
    r"""
    Calculate cell temperature using an empirical heat loss factor model
    as implemented in PVsyst.

    Parameters
    ----------
    poa_global : numeric
        Total incident irradiance [W/m^2].

    temp_air : numeric
        Ambient dry bulb temperature [C].

    wind_speed : numeric, default 1.0
        Wind speed in m/s measured at the same height for which the wind loss
        factor was determined.  The default value 1.0 m/s is the wind
        speed at module height used to determine NOCT. [m/s]

    u_c : float, default 29.0
        Combined heat loss factor coefficient. The default value is
        representative of freestanding modules with the rear surfaces exposed
        to open air (e.g., rack mounted). Parameter :math:`U_{c}` in
        :eq:`pvsyst`.
        :math:`\left[\frac{\text{W}/{\text{m}^2}}{\text{C}}\right]`

    u_v : float, default 0.0
        Combined heat loss factor influenced by wind. Parameter :math:`U_{v}`
        in :eq:`pvsyst`.
        :math:`\left[ \frac{\text{W}/\text{m}^2}{\text{C}\ \left( \text{m/s} \right)} \right]`

    module_efficiency : numeric, default 0.1
        Module external efficiency as a fraction. Parameter :math:`\eta_{m}`
        in :eq:`pvsyst`. Calculate as
        :math:`\eta_{m} = DC\ power / (POA\ irradiance \times module\ area)`.

    alpha_absorption : numeric, default 0.9
        Absorption coefficient. Parameter :math:`\alpha` in :eq:`pvsyst`.

    Returns
    -------
    numeric, values in degrees Celsius

    Notes
    -----
    The Pvsyst model for cell temperature :math:`T_{C}` is given by

    .. math::
       :label: pvsyst

        T_{C} = T_{a} + \frac{\alpha E (1 - \eta_{m})}{U_{c} + U_{v} \times WS}

    Inputs to the model are plane-of-array irradiance :math:`E` (W/m2), ambient
    air temperature :math:`T_{a}` (C) and wind speed :math:`WS` (m/s). Model
    output is cell temperature :math:`T_{C}`. Model parameters depend both on
    the module construction and its mounting. Parameters are provided in
    [1]_ for open (freestanding), close (insulated), and intermediate
    (semi_integrated) mounting configurations, and are coded for convenience in
    :data:`~pvlib.temperature.TEMPERATURE_MODEL_PARAMETERS`. The heat loss
    factors provided represent the combined effect of convection, radiation and
    conduction, and their values are experimentally determined.

    +-----------------+---------------+---------------+
    | Mounting        | :math:`U_{c}` | :math:`U_{v}` |
    +=================+===============+===============+
    | freestanding    | 29.0          | 0.0           |
    +-----------------+---------------+---------------+
    | insulated       | 15.0          | 0.0           |
    +-----------------+---------------+---------------+
    | semi_integrated | 20.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:
       https://www.pvsyst.com/help/index.html?thermal_loss.htm.
       [Accessed: 30-Jan-2024].

    .. [2] Faiman, D. (2008). "Assessing the outdoor operating temperature of
       photovoltaic modules." Progress in Photovoltaics 16(4): 307-315.

    Examples
    --------
    >>> from pvlib.temperature import pvsyst_cell, TEMPERATURE_MODEL_PARAMETERS
    >>> params = TEMPERATURE_MODEL_PARAMETERS['pvsyst']['freestanding']
    >>> pvsyst_cell(1000, 10, **params)
    37.93103448275862
    """  # noQA: E501

    total_loss_factor = u_c + u_v * wind_speed
    heat_input = poa_global * alpha_absorption * (1 - module_efficiency)
    temp_difference = heat_input / total_loss_factor
    return temp_air + temp_difference


def faiman(poa_global, temp_air, wind_speed=1.0, u0=25.0, u1=6.84):
    r'''
    Calculate cell or module temperature using the Faiman model.

    The Faiman model uses an empirical heat loss factor model [1]_ and is
    adopted in the IEC 61853 standards [2]_ and [3]_.

    Usage of this model in the IEC 61853 standard does not distinguish
    between cell and module temperature.

    Parameters
    ----------
    poa_global : numeric
        Total incident irradiance [W/m^2].

    temp_air : numeric
        Ambient dry bulb temperature [C].

    wind_speed : numeric, default 1.0
        Wind speed in m/s measured at the same height for which the wind loss
        factor was determined.  The default value 1.0 m/s is the wind
        speed at module height used to determine NOCT. [m/s]

    u0 : numeric, default 25.0
        Combined heat loss factor coefficient. The default value is one
        determined by Faiman for 7 silicon modules
        in the Negev desert on an open rack at 30.9° tilt.
        :math:`\left[\frac{\text{W}/{\text{m}^2}}{\text{C}}\right]`

    u1 : numeric, default 6.84
        Combined heat loss factor influenced by wind. The default value is one
        determined by Faiman for 7 silicon modules
        in the Negev desert on an open rack at 30.9° tilt.
        :math:`\left[ \frac{\text{W}/\text{m}^2}{\text{C}\ \left( \text{m/s} \right)} \right]`

    Returns
    -------
    numeric, values in degrees Celsius

    Notes
    -----
    All arguments may be scalars or vectors. If multiple arguments
    are vectors they must be the same length.

    References
    ----------
    .. [1] Faiman, D. (2008). "Assessing the outdoor operating temperature of
       photovoltaic modules." Progress in Photovoltaics 16(4): 307-315.
       :doi:`10.1002/pip.813`

    .. [2] "IEC 61853-2 Photovoltaic (PV) module performance testing and energy
       rating - Part 2: Spectral responsivity, incidence angle and module
       operating temperature measurements". IEC, Geneva, 2018.

    .. [3] "IEC 61853-3 Photovoltaic (PV) module performance testing and energy
       rating - Part 3: Energy rating of PV modules". IEC, Geneva, 2018.

    See also
    --------
    pvlib.temperature.faiman_rad

    '''  # noQA: E501

    # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Dec., 2019

    # The following lines may seem odd since u0 & u1 are probably scalar,
    # but it serves an indirect and easy way of allowing lists and
    # tuples for the other function arguments.
    u0 = np.asanyarray(u0)
    u1 = np.asanyarray(u1)

    total_loss_factor = u0 + u1 * wind_speed
    heat_input = poa_global
    temp_difference = heat_input / total_loss_factor
    return temp_air + temp_difference


def faiman_rad(poa_global, temp_air, wind_speed=1.0, ir_down=None,
               u0=25.0, u1=6.84, sky_view=1.0, emissivity=0.88):
    r'''
    Calculate cell or module temperature using the Faiman model augmented
    with a radiative loss term.

    The Faiman model uses an empirical heat loss factor model [1]_ and is
    adopted in the IEC 61853 standards [2]_ and [3]_.  The radiative loss
    term was proposed and developed by Driesse [4]_.

    The model can be used to represent cell or module temperature.

    Parameters
    ----------
    poa_global : numeric
        Total incident irradiance [W/m^2].

    temp_air : numeric
        Ambient dry bulb temperature [C].

    wind_speed : numeric, default 1.0
        Wind speed measured at the same height for which the wind loss
        factor was determined.  The default value 1.0 m/s is the wind
        speed at module height used to determine NOCT. [m/s]

    ir_down : numeric, default 0.0
        Downwelling infrared radiation from the sky, measured on a horizontal
        surface. [W/m^2]

    u0 : numeric, default 25.0
        Combined heat loss factor coefficient. The default value is one
        determined by Faiman for 7 silicon modules
        in the Negev desert on an open rack at 30.9° tilt.
        :math:`\left[\frac{\text{W}/{\text{m}^2}}{\text{C}}\right]`

    u1 : numeric, default 6.84
        Combined heat loss factor influenced by wind. The default value is one
        determined by Faiman for 7 silicon modules
        in the Negev desert on an open rack at 30.9° tilt.
        :math:`\left[ \frac{\text{W}/\text{m}^2}{\text{C}\ \left( \text{m/s} \right)} \right]`

    sky_view : numeric, default 1.0
        Effective view factor limiting the radiative exchange between the
        module and the sky. For a tilted array the expressions
        (1 + 3*cos(tilt)) / 4 can be used as a first estimate for sky_view
        as discussed in [4]_. The default value is for a horizontal module.
        [unitless]

    emissivity : numeric, default 0.88
        Infrared emissivity of the module surface facing the sky. The default
        value represents the middle of a range of values found in the
        literature. [unitless]

    Returns
    -------
    numeric, values in degrees Celsius

    Notes
    -----
    All arguments may be scalars or vectors. If multiple arguments
    are vectors they must be the same length.

    When only irradiance, air temperature and wind speed inputs are provided
    (`ir_down` is `None`) this function calculates the same device temperature
    as the original faiman model. When down-welling long-wave radiation data
    are provided as well (`ir_down` is not None) the default u0 and u1 values
    from the original model should not be used because a portion of the
    radiative losses would be double-counted.

    References
    ----------
    .. [1] Faiman, D. (2008). "Assessing the outdoor operating temperature of
       photovoltaic modules." Progress in Photovoltaics 16(4): 307-315.
       :doi:`10.1002/pip.813`

    .. [2] "IEC 61853-2 Photovoltaic (PV) module performance testing and energy
       rating - Part 2: Spectral responsivity, incidence angle and module
       operating temperature measurements". IEC, Geneva, 2018.

    .. [3] "IEC 61853-3 Photovoltaic (PV) module performance testing and energy
       rating - Part 3: Energy rating of PV modules". IEC, Geneva, 2018.

    .. [4] Driesse, A. et al (2022) "Improving Common PV Module Temperature
       Models by Incorporating Radiative Losses to the Sky". SAND2022-11604.
       :doi:`10.2172/1884890`

    See also
    --------
    pvlib.temperature.faiman

    '''  # noQA: E501

    # Contributed by Anton Driesse (@adriesse), PV Performance Labs. Nov., 2022

    abs_zero = -273.15
    sigma = scipy.constants.Stefan_Boltzmann

    if ir_down is None:
        qrad_sky = 0.0
    else:
        ir_up = sigma * ((temp_air - abs_zero)**4)
        qrad_sky = emissivity * sky_view * (ir_up - ir_down)

    heat_input = poa_global - qrad_sky
    total_loss_factor = u0 + u1 * wind_speed
    temp_difference = heat_input / total_loss_factor
    return temp_air + temp_difference


def ross(poa_global, temp_air, noct=None, k=None):
    r'''
    Calculate cell temperature using the Ross model.

    The Ross model [1]_ assumes the difference between cell temperature
    and ambient temperature is proportional to the plane of array irradiance,
    and assumes wind speed of 1 m/s. The model implicitly assumes steady or
    slowly changing irradiance conditions.

    Parameters
    ----------
    poa_global : numeric
        Total incident irradiance. [W/m⁻²]

    temp_air : numeric
        Ambient dry bulb temperature. [C]

    noct : numeric, optional
        Nominal operating cell temperature [C], determined at conditions of
        800 W/m⁻² irradiance, 20 C ambient air temperature and 1 m/s wind.
        If ``noct`` is not provided, ``k`` is required.
    k: numeric, optional
        Ross coefficient [Km²W⁻¹], which is an alternative to employing
        NOCT in Ross's equation. If ``k`` is not provided, ``noct`` is
        required.

    Returns
    -------
    cell_temperature : numeric
        Cell temperature. [C]

    Notes
    -----
    The Ross model for cell temperature :math:`T_{C}` is given in [1]_ as

    .. math::

        T_{C} = T_{a} + \frac{NOCT - 20}{80} S = T_{a} + k × S

    where :math:`S` is the plane of array irradiance in mWcm⁻².
    This function expects irradiance in Wm⁻².

    Representative values for k are provided in [2]_, covering different types
    of mounting and degrees of back ventialtion. The naming designations,
    however, are adapted from [3]_ to enhance clarity and usability.

    +--------------------------------------+-----------+
    | Mounting                             | :math:`k` |
    +======================================+===========+
    | Sloped roof, well ventilated         | 0.02      |
    +--------------------------------------+-----------+
    | Free-standing system                 | 0.0208    |
    +--------------------------------------+-----------+
    | Flat roof, well ventilated           | 0.026     |
    +--------------------------------------+-----------+
    | Sloped roof, poorly ventilated       | 0.0342    |
    +--------------------------------------+-----------+
    | Facade integrated, semi-ventilated   | 0.0455    |
    +--------------------------------------+-----------+
    | Facade integrated, poorly ventilated | 0.0538    |
    +--------------------------------------+-----------+
    | Sloped roof, non-ventilated          | 0.0563    |
    +--------------------------------------+-----------+

    It is also worth noting that the semi-ventilated facade case refers to
    partly transparent compound glass insulation modules, while the non-
    ventilated case corresponds to opaque, insulated PV-cladding elements.
    However, the emphasis in [3]_ appears to be on ventilation conditions
    rather than module construction.

    References
    ----------
    .. [1] Ross, R. G. Jr., (1981). "Design Techniques for Flat-Plate
       Photovoltaic Arrays". 15th IEEE Photovoltaic Specialist Conference,
       Orlando, FL.
    .. [2] E. Skoplaki and J. A. Palyvos, "Operating temperature of
       photovoltaic modules: A survey of pertinent correlations," Renewable
       Energy, vol. 34, no. 1, pp. 23–29, Jan. 2009,
       :doi:`10.1016/j.renene.2008.04.009`
    .. [3] T. Nordmann and L. Clavadetscher, "Understanding temperature
       effects on PV system performance," Proceedings of 3rd World Conference
       on Photovoltaic Energy Conversion, May 2003.
    '''
    if (noct is None) & (k is None):
        raise ValueError("Either noct or k is required.")
    elif (noct is not None) & (k is not None):
        raise ValueError("Provide only one of noct or k, not both.")
    elif k is None:
        # factor of 0.1 converts irradiance from W/m2 to mW/cm2
        return temp_air + (noct - 20.) / 80. * poa_global * 0.1
    elif noct is None:
        # k assumes irradiance in W.m-2, dismissing 0.1 factor
        return temp_air + k * poa_global


def _fuentes_hconv(tave, windmod, temp_delta, xlen, tilt, check_reynold):
    # Calculate the convective coefficient as in Fuentes 1987 -- a mixture of
    # free, laminar, and turbulent convection.
    densair = 0.003484 * 101325.0 / tave  # density
    visair = 0.24237e-6 * tave**0.76 / densair  # kinematic viscosity
    condair = 2.1695e-4 * tave**0.84  # thermal conductivity
    reynold = windmod * xlen / visair
    # the boundary between laminar and turbulent is modeled as an abrupt
    # change at Re = 1.2e5:
    if check_reynold and reynold > 1.2e5:
        # turbulent convection
        hforce = 0.0282 / reynold**0.2 * densair * windmod * 1007 / 0.71**0.4
    else:
        # laminar convection
        hforce = 0.8600 / reynold**0.5 * densair * windmod * 1007 / 0.71**0.67
    # free convection via Grashof number
    # NB: Fuentes hardwires sind(tilt) as 0.5 for tilt=30
    grashof = 9.8 / tave * temp_delta * xlen**3 / visair**2 * sind(tilt)
    # product of Nusselt number and (k/l)
    hfree = 0.21 * (grashof * 0.71)**0.32 * condair / xlen
    # combine free and forced components
    hconv = (hfree**3 + hforce**3)**(1/3)
    return hconv


def _hydraulic_diameter(width, height):
    # calculate the hydraulic diameter of a rectangle
    return 2 * (width * height) / (width + height)


def fuentes(poa_global, temp_air, wind_speed, noct_installed, module_height=5,
            wind_height=9.144, emissivity=0.84, absorption=0.83,
            surface_tilt=30, module_width=0.31579, module_length=1.2):
    """
    Calculate cell or module temperature using the Fuentes model.

    The Fuentes model is a first-principles heat transfer energy balance
    model [1]_ that is used in PVWatts for cell temperature modeling [2]_.

    Parameters
    ----------
    poa_global : pandas Series
        Total incident irradiance [W/m^2]

    temp_air : pandas Series
        Ambient dry bulb temperature [C]

    wind_speed : pandas Series
        Wind speed [m/s]

    noct_installed : float
        The "installed" nominal operating cell temperature as defined in [1]_.
        PVWatts assumes this value to be 45 C for rack-mounted arrays and
        49 C for roof mount systems with restricted air flow around the
        module.  [C]

    module_height : float, default 5.0
        The height above ground of the center of the module. The PVWatts
        default is 5.0 [m]

    wind_height : float, default 9.144
        The height above ground at which ``wind_speed`` is measured. The
        PVWatts default is 9.144 [m]

    emissivity : float, default 0.84
        The effectiveness of the module at radiating thermal energy. [unitless]

    absorption : float, default 0.83
        The fraction of incident irradiance that is converted to thermal
        energy in the module. [unitless]

    surface_tilt : float, default 30
        Module tilt from horizontal. If not provided, the default value
        of 30 degrees from [1]_ and [2]_ is used. [degrees]

    module_width : float, default 0.31579
        Module width. The default value of 0.31579 meters in combination with
        the default `module_length` gives a hydraulic diameter of 0.5 as
        assumed in [1]_ and [2]_. [m]

    module_length : float, default 1.2
        Module length. The default value of 1.2 meters in combination with
        the default `module_width` gives a hydraulic diameter of 0.5 as
        assumed in [1]_ and [2]_. [m]

    Returns
    -------
    temperature_cell : pandas Series
        The modeled cell temperature [C]

    Notes
    -----
    This function returns slightly different values from PVWatts at night
    and just after dawn. This is because the SAM SSC assumes that module
    temperature equals ambient temperature when irradiance is zero so it can
    skip the heat balance calculation at night.

    References
    ----------
    .. [1] Fuentes, M. K., 1987, "A Simplifed Thermal Model for Flat-Plate
           Photovoltaic Arrays", SAND85-0330, Sandia National Laboratories,
           Albuquerque NM.
           http://prod.sandia.gov/techlib/access-control.cgi/1985/850330.pdf
    .. [2] Dobos, A. P., 2014, "PVWatts Version 5 Manual", NREL/TP-6A20-62641,
           National Renewable Energy Laboratory, Golden CO.
           :doi:`10.2172/1158421`.
    """
    # ported from the FORTRAN77 code provided in Appendix A of Fuentes 1987;
    # nearly all variable names are kept the same for ease of comparison.

    boltz = 5.669e-8
    emiss = emissivity
    absorp = absorption
    xlen = _hydraulic_diameter(module_width, module_length)
    # cap0 has units of [J / (m^2 K)], equal to mass per unit area times
    # specific heat of the module.
    cap0 = 11000
    tinoct = noct_installed + 273.15

    # convective coefficient of top surface of module at NOCT
    windmod = 1.0
    tave = (tinoct + 293.15) / 2
    hconv = _fuentes_hconv(tave, windmod, tinoct - 293.15, xlen,
                           surface_tilt, False)

    # determine the ground temperature ratio and the ratio of the total
    # convection to the top side convection
    hground = emiss * boltz * (tinoct**2 + 293.15**2) * (tinoct + 293.15)
    backrat = (
        absorp * 800.0
        - emiss * boltz * (tinoct**4 - 282.21**4)
        - hconv * (tinoct - 293.15)
    ) / ((hground + hconv) * (tinoct - 293.15))
    tground = (tinoct**4 - backrat * (tinoct**4 - 293.15**4))**0.25
    tground = np.clip(tground, 293.15, tinoct)

    tgrat = (tground - 293.15) / (tinoct - 293.15)
    convrat = (absorp * 800 - emiss * boltz * (
        2 * tinoct**4 - 282.21**4 - tground**4)) / (hconv * (tinoct - 293.15))

    # adjust the capacitance (thermal mass) of the module based on the INOCT.
    # It is a function of INOCT because high INOCT implies thermal coupling
    # with the racking (e.g. roofmount), so the thermal mass is increased.
    # `cap` has units J/(m^2 C) -- see Table 3, Equations 26 & 27
    cap = cap0
    if tinoct > 321.15:
        cap = cap * (1 + (tinoct - 321.15) / 12)

    # iterate through timeseries inputs
    sun0 = 0

    # n.b. the way Fuentes calculates the first timedelta makes it seem like
    # the value doesn't matter -- rather than recreate it here, just assume
    # it's the same as the second timedelta:
    timedelta_seconds = poa_global.index.to_series().diff().dt.total_seconds()
    timedelta_hours = timedelta_seconds / 3600
    timedelta_hours.iloc[0] = timedelta_hours.iloc[1]

    tamb_array = temp_air + 273.15
    sun_array = poa_global * absorp

    # Two of the calculations are easily vectorized, so precalculate them:
    # sky temperature -- Equation 24
    tsky_array = 0.68 * (0.0552 * tamb_array**1.5) + 0.32 * tamb_array
    # wind speed at module height -- Equation 22
    # not sure why the 1e-4 factor is included -- maybe the equations don't
    # behave well if wind == 0?
    windmod_array = wind_speed * (module_height/wind_height)**0.2 + 1e-4

    tmod0 = 293.15
    tmod_array = np.zeros_like(poa_global)

    iterator = zip(tamb_array, sun_array, windmod_array, tsky_array,
                   timedelta_hours)
    for i, (tamb, sun, windmod, tsky, dtime) in enumerate(iterator):
        # solve the heat transfer equation, iterating because the heat loss
        # terms depend on tmod. NB Fuentes doesn't show that 10 iterations is
        # sufficient for convergence.
        tmod = tmod0
        for j in range(10):
            # overall convective coefficient
            tave = (tmod + tamb) / 2
            hconv = convrat * _fuentes_hconv(tave, windmod,
                                             abs(tmod-tamb), xlen,
                                             surface_tilt, True)
            # sky radiation coefficient (Equation 3)
            hsky = emiss * boltz * (tmod**2 + tsky**2) * (tmod + tsky)
            # ground radiation coeffieicient (Equation 4)
            tground = tamb + tgrat * (tmod - tamb)
            hground = emiss * boltz * (tmod**2 + tground**2) * (tmod + tground)
            # thermal lag -- Equation 8
            eigen = - (hconv + hsky + hground) / cap * dtime * 3600
            # not sure why this check is done, maybe as a speed optimization?
            if eigen > -10:
                ex = np.exp(eigen)
            else:
                ex = 0
            # Equation 7 -- note that `sun` and `sun0` already account for
            # absorption (alpha)
            tmod = tmod0 * ex + (
                (1 - ex) * (
                    hconv * tamb
                    + hsky * tsky
                    + hground * tground
                    + sun0
                    + (sun - sun0) / eigen
                ) + sun - sun0
            ) / (hconv + hsky + hground)
        tmod_array[i] = tmod
        tmod0 = tmod
        sun0 = sun

    return pd.Series(tmod_array - 273.15, index=poa_global.index, name='tmod')


def _adj_for_mounting_standoff(x):
    # supports noct cell temperature function. Except for x > 3.5, the SAM code
    # and documentation aren't clear on the precise intervals. The choice of
    # < or <= here is pvlib's.
    return np.piecewise(x, [x <= 0, (x > 0) & (x < 0.5),
                            (x >= 0.5) & (x < 1.5), (x >= 1.5) & (x < 2.5),
                            (x >= 2.5) & (x <= 3.5), x > 3.5],
                        [0., 18., 11., 6., 2., 0.])


def noct_sam(poa_global, temp_air, wind_speed, noct, module_efficiency,
             effective_irradiance=None, transmittance_absorptance=0.9,
             array_height=1, mount_standoff=4):
    r'''
    Cell temperature model from the System Advisor Model (SAM).

    The model is described in [1]_, Section 10.6.

    Parameters
    ----------
    poa_global : numeric
        Total incident irradiance. [W/m^2]

    temp_air : numeric
        Ambient dry bulb temperature. [C]

    wind_speed : numeric
        Wind speed in m/s measured at the same height for which the wind loss
        factor was determined.  The default value 1.0 m/s is the wind
        speed at module height used to determine NOCT. [m/s]

    noct : float
        Nominal operating cell temperature [C], determined at conditions of
        800 W/m^2 irradiance, 20 C ambient air temperature and 1 m/s wind.

    module_efficiency : float
        Module external efficiency [unitless] at reference conditions of
        1000 W/m^2 and 20C. Denoted as :math:`eta_{m}` in [1]_. Calculate as
        :math:`\eta_{m} = \frac{V_{mp} I_{mp}}{A \times 1000 W/m^2}`
        where A is module area [m^2].

    effective_irradiance : numeric, optional
        The irradiance that is converted to photocurrent. If not specified,
        assumed equal to poa_global. [W/m^2]

    transmittance_absorptance : numeric, default 0.9
        Coefficient for combined transmittance and absorptance effects.
        [unitless]

    array_height : int, default 1
        Height of array above ground in stories (one story is about 3m). Must
        be either 1 or 2. For systems elevated less than one story, use 1.
        If system is elevated more than two stories, use 2.

    mount_standoff : numeric, default 4
        Distance between array mounting and mounting surface. Use default
        if system is ground-mounted. [inches]

    Returns
    -------
    cell_temperature : numeric
        Cell temperature. [C]

    Raises
    ------
    ValueError
        If array_height is an invalid value (must be 1 or 2).

    References
    ----------
    .. [1] Gilman, P., Dobos, A., DiOrio, N., Freeman, J., Janzou, S.,
           Ryberg, D., 2018, "SAM Photovoltaic Model Technical Reference
           Update", National Renewable Energy Laboratory Report
           NREL/TP-6A20-67399.
    '''
    # in [1] the denominator for irr_ratio isn't precisely clear. From
    # reproducing output of the SAM function noct_celltemp_t, we determined
    # that:
    #  - G_total (SAM) is broadband plane-of-array irradiance before
    #    reflections. Equivalent to pvlib variable poa_global
    #  - Geff_total (SAM) is POA irradiance after reflections and
    #    adjustment for spectrum. Equivalent to effective_irradiance
    if effective_irradiance is None:
        irr_ratio = 1.
    else:
        irr_ratio = effective_irradiance / poa_global

    if array_height == 1:
        wind_adj = 0.51 * wind_speed
    elif array_height == 2:
        wind_adj = 0.61 * wind_speed
    else:
        raise ValueError(
            f'array_height must be 1 or 2, {array_height} was given')

    noct_adj = noct + _adj_for_mounting_standoff(mount_standoff)
    tau_alpha = transmittance_absorptance * irr_ratio

    # [1] Eq. 10.37 isn't clear on exactly what "G" is. SAM SSC code uses
    # poa_global where G appears
    cell_temp_init = poa_global / 800. * (noct_adj - 20.)
    heat_loss = 1 - module_efficiency / tau_alpha
    wind_loss = 9.5 / (5.7 + 3.8 * wind_adj)
    return temp_air + cell_temp_init * heat_loss * wind_loss


def prilliman(temp_cell, wind_speed, unit_mass=11.1, coefficients=None):
    """
    Smooth short-term cell temperature transients using the Prilliman model.

    The Prilliman et al. model [1]_ applies a weighted moving average to
    the output of a steady-state cell temperature model to account for
    a module's thermal inertia by smoothing the cell temperature's
    response to changing weather conditions.

    .. warning::
        This implementation requires the time series inputs to be regularly
        sampled in time with frequency less than 20 minutes.  Data with
        irregular time steps (including from data gaps, missing leap days,
        etc) should be resampled prior to using this function.

    Parameters
    ----------
    temp_cell : pandas.Series with DatetimeIndex
        Cell temperature modeled with steady-state assumptions. [C]

    wind_speed : pandas.Series
        Wind speed, adjusted to correspond to array height [m/s]

    unit_mass : float, default 11.1
        Total mass of module divided by its one-sided surface area [kg/m^2]
        One-sided surface area is equal to module height times width

    coefficients : 4-element list-like, optional
        Values for coefficients a_0 through a_3, see Eq. 9 of [1]_

    Returns
    -------
    temp_cell : pandas.Series
        Smoothed version of the input cell temperature. Input temperature
        with sampling interval >= 20 minutes is returned unchanged. [C]

    Notes
    -----
    This smoothing model was developed and validated using the SAPM
    cell temperature model for the steady-state input.

    Smoothing is done using the 20 minute window behind each temperature
    value. At the beginning of the series where a full 20 minute window is not
    possible, partial windows are used instead.

    Output ``temp_cell[k]`` is NaN when input ``wind_speed[k]`` is NaN, or
    when no non-NaN data are in the input temperature for the 20 minute window
    preceding index ``k``.

    References
    ----------
    .. [1] M. Prilliman, J. S. Stein, D. Riley and G. Tamizhmani,
       "Transient Weighted Moving-Average Model of Photovoltaic Module
       Back-Surface Temperature," IEEE Journal of Photovoltaics, 2020.
       :doi:`10.1109/JPHOTOV.2020.2992351`
    """

    # `sample_interval` in minutes:
    sample_interval, samples_per_window = \
        _get_sample_intervals(times=temp_cell.index, win_length=20)

    if sample_interval >= 20:
        warnings.warn("temperature.prilliman only applies smoothing when "
                      "the sampling interval is shorter than 20 minutes "
                      f"(input sampling interval: {sample_interval} minutes);"
                      " returning input temperature series unchanged")
        # too coarsely sampled for smoothing to be relevant
        return temp_cell

    # handle cases where the time series is shorter than 20 minutes total
    samples_per_window = min(samples_per_window, len(temp_cell))

    # prefix with NaNs so that the rolling window is "full",
    # even for the first actual value:
    prefix = np.full(samples_per_window, np.nan)
    temp_cell_prefixed = np.append(prefix, temp_cell.values)

    # generate matrix of integers for creating windows with indexing
    H = scipy.linalg.hankel(np.arange(samples_per_window),
                            np.arange(samples_per_window - 1,
                                      len(temp_cell_prefixed) - 1))
    # each row of `subsets` is the values in one window
    subsets = temp_cell_prefixed[H].T

    # `subsets` now looks like this (for 5-minute data, so 4 samples/window)
    # where "1." is a stand-in for the actual temperature values
    # [[nan, nan, nan, nan],
    #  [nan, nan, nan,  1.],
    #  [nan, nan,  1.,  1.],
    #  [nan,  1.,  1.,  1.],
    #  [ 1.,  1.,  1.,  1.],
    #  [ 1.,  1.,  1.,  1.],
    #  [ 1.,  1.,  1.,  1.],
    #  ...

    # calculate weights for the values in each window
    if coefficients is not None:
        a = coefficients
    else:
        # values from [1], Table II
        a = [0.0046, 0.00046, -0.00023, -1.6e-5]

    wind_speed = wind_speed.values
    p = a[0] + a[1]*wind_speed + a[2]*unit_mass + a[3]*wind_speed*unit_mass
    # calculate the time lag for each sample in the window, paying attention
    # to units (seconds for `timedeltas`, minutes for `sample_interval`)
    timedeltas = np.arange(samples_per_window, 0, -1) * sample_interval * 60
    weights = np.exp(-p[:, np.newaxis] * timedeltas)

    # Set weights corresponding to the prefix values to zero; otherwise the
    # denominator of the weighted average below would be wrong.
    # Weights corresponding to (non-prefix) NaN values must be zero too
    # for the same reason.

    # Right now `weights` is something like this
    # (using 5-minute inputs, so 4 samples per window -> 4 values per row):
    # [[0.0611, 0.1229, 0.2472, 0.4972],
    #  [0.0611, 0.1229, 0.2472, 0.4972],
    #  [0.0611, 0.1229, 0.2472, 0.4972],
    #  [0.0611, 0.1229, 0.2472, 0.4972],
    #  [0.0611, 0.1229, 0.2472, 0.4972],
    #  [0.0611, 0.1229, 0.2472, 0.4972],
    #  [0.0611, 0.1229, 0.2472, 0.4972],
    #  ...

    # After the next line, the NaNs in `subsets` will be zeros in `weights`,
    # like this (with more zeros for any NaNs in the input temperature):

    # [[0.    , 0.    , 0.    , 0.    ],
    #  [0.    , 0.    , 0.    , 0.4972],
    #  [0.    , 0.    , 0.2472, 0.4972],
    #  [0.    , 0.1229, 0.2472, 0.4972],
    #  [0.0611, 0.1229, 0.2472, 0.4972],
    #  [0.0611, 0.1229, 0.2472, 0.4972],
    #  [0.0611, 0.1229, 0.2472, 0.4972],
    #  ...

    weights[np.isnan(subsets)] = 0

    # change the first row of weights from zero to nan -- this is a
    # trick to prevent div by zero warning when dividing by summed weights
    weights[0, :] = np.nan

    # finally, take the weighted average of each window:
    # use np.nansum for numerator to ignore nans in input temperature, but
    # np.sum for denominator to propagate nans in input wind speed.
    numerator = np.nansum(subsets * weights, axis=1)
    denominator = np.sum(weights, axis=1)
    smoothed = numerator / denominator
    smoothed[0] = temp_cell.values[0]
    smoothed = pd.Series(smoothed, index=temp_cell.index)
    return smoothed


def generic_linear(poa_global, temp_air, wind_speed, u_const, du_wind,
                   module_efficiency, absorptance):
    """
    Calculate cell temperature using a generic linear heat loss factor model.

    The parameters for this model can be obtained from other model
    parameters using :py:class:`GenericLinearModel`.  A description of this
    model and its relationship to other temperature models is found in [1]_.

    Parameters
    ----------
    poa_global : numeric
        Total incident irradiance [W/m^2].

    temp_air : numeric
        Ambient dry bulb temperature [C].

    wind_speed : numeric
        Wind speed at a height of 10 meters [m/s].

    u_const : float
        Combined heat transfer coefficient at zero wind speed [(W/m^2)/C]

    du_wind : float
        Influence of wind speed on combined heat transfer coefficient
        [(W/m^2)/C/(m/s)]

    module_efficiency : float
        The electrical efficiency of the module. [-]

    absorptance : float
        The light absorptance of the module. [-]

    Returns
    -------
    numeric, values in degrees C.

    References
    ----------
    .. [1] A. Driesse et al, "PV Module Operating Temperature
       Model Equivalence and Parameter Translation". 2022 IEEE
       Photovoltaic Specialists Conference (PVSC), 2022.

    See also
    --------
    pvlib.temperature.GenericLinearModel
    """
    # Contributed by Anton Driesse (@adriesse), PV Performance Labs, Sept. 2022

    heat_input = poa_global * (absorptance - module_efficiency)
    total_loss_factor = u_const + du_wind * wind_speed
    temp_difference = heat_input / total_loss_factor

    return temp_air + temp_difference


class GenericLinearModel():
    '''
    A class that can both use and convert parameters of linear module
    temperature models: faiman, pvsyst, noct_sam, sapm_module
    and generic_linear.

    Parameters are converted between models by first converting
    to the generic linear heat transfer model [1]_ by the ``use_``
    methods. The equivalent parameters for the target temperature
    model are then obtained by the ``to_`` method.
    Parameters are returned as a dictionary that is compatible with the
    target model function to use in simulations.

    An instance of the class represents a specific module type and
    the parameters ``module_efficiency`` and ``absorptance`` are required.
    Although some temperature models do not use these properties, they
    nevertheless exist and affect operating temperature. Values
    should be representative of the conditions at which the input
    model parameters were determined (usually high irradiance).

    Parameters
    ----------
    module_efficiency : float
        The electrical efficiency of the module. [-]

    absorptance : float
        The light absorptance of the module. [-]

    Notes
    -----
    After creating a GenericLinearModel object using the module properties,
    one of the ``use_`` methods must be called to provide thermal model
    parameters.  If this is not done, the ``to_`` methods will return ``nan``
    values.

    References
    ----------
    .. [1] A. Driesse et al, "PV Module Operating Temperature
       Model Equivalence and Parameter Translation". 2022 IEEE
       Photovoltaic Specialists Conference (PVSC), 2022.

    Examples
    --------
    >>> glm = GenericLinearModel(module_efficiency=0.19, absorptance=0.88)

    >>> glm.use_faiman(16, 8)
    GenericLinearModel: {'u_const': 11.04, 'du_wind': 5.52,
                         'eta': 0.19, 'alpha': 0.88}

    >>> glm.to_pvsyst()
    {'u_c': 11.404800000000002, 'u_v': 5.702400000000001,
     'module_efficiency': 0.19, 'alpha_absorption': 0.88}

    >>> parmdict = glm.to_pvsyst()
    >>> pvsyst_cell(800, 20, 1, **parmdict)
    53.33333333333333

    See also
    --------
    pvlib.temperature.generic_linear
    '''
    # Contributed by Anton Driesse (@adriesse), PV Performance Labs, Sept. 2022

    def __init__(self, module_efficiency, absorptance):

        self.u_const = np.nan
        self.du_wind = np.nan
        self.eta = module_efficiency
        self.alpha = absorptance

        return None

    def __repr__(self):

        return self.__class__.__name__ + ': ' + vars(self).__repr__()

    def __call__(self, poa_global, temp_air, wind_speed,
                 module_efficiency=None):
        '''
        Calculate module temperature using the generic_linear model and
        previously initialized parameters.

        Parameters
        ----------
        poa_global : numeric
            Total incident irradiance [W/m^2].

        temp_air : numeric
            Ambient dry bulb temperature [C].

        wind_speed : numeric
            Wind speed in m/s measured at the same height for which the wind
            loss factor was determined.  [m/s]

        module_efficiency : numeric, optional
            Module electrical efficiency.  The default value is the one
            that was specified initially. [-]

        Returns
        -------
        numeric, values in degrees Celsius

        See also
        --------
        get_generic
        pvlib.temperature.generic_linear
        '''
        if module_efficiency is None:
            module_efficiency = self.eta

        return generic_linear(poa_global, temp_air, wind_speed,
                              self.u_const, self.du_wind,
                              module_efficiency, self.alpha)

    def get_generic_linear(self):
        '''
        Get the generic linear model parameters to use with the separate
        generic linear module temperature calculation function.

        Returns
        -------
        model_parameters : dict

        See also
        --------
        pvlib.temperature.generic_linear
        '''
        return dict(u_const=self.u_const,
                    du_wind=self.du_wind,
                    module_efficiency=self.eta,
                    absorptance=self.alpha)

    def use_faiman(self, u0, u1):
        '''
        Use the Faiman model parameters to set the generic_model equivalents.

        Parameters
        ----------
        u0, u1 : float
            See :py:func:`pvlib.temperature.faiman` for details.
        '''
        net_absorptance = self.alpha - self.eta
        self.u_const = u0 * net_absorptance
        self.du_wind = u1 * net_absorptance

        return self

    def to_faiman(self):
        '''
        Convert the generic model parameters to Faiman equivalents.

        Returns
        ----------
        model_parameters : dict
            See :py:func:`pvlib.temperature.faiman` for
            model parameter details.
        '''
        net_absorptance = self.alpha - self.eta
        u0 = self.u_const / net_absorptance
        u1 = self.du_wind / net_absorptance

        return dict(u0=u0, u1=u1)

    def use_pvsyst(self, u_c, u_v, module_efficiency=None,
                   alpha_absorption=None):
        '''
        Use the PVsyst model parameters to set the generic_model equivalents.

        Parameters
        ----------
        u_c, u_v : float
            See :py:func:`pvlib.temperature.pvsyst_cell` for details.

        module_efficiency, alpha_absorption : float, optional
            See :py:func:`pvlib.temperature.pvsyst_cell` for details.

        Notes
        -----
        The optional parameters are primarily for convenient compatibility
        with existing function signatures.
        '''
        if module_efficiency is not None:
            self.eta = module_efficiency

        if alpha_absorption is not None:
            self.alpha = alpha_absorption

        net_absorptance_glm = self.alpha - self.eta
        net_absorptance_pvsyst = self.alpha * (1.0 - self.eta)
        absorptance_ratio = net_absorptance_glm / net_absorptance_pvsyst

        self.u_const = u_c * absorptance_ratio
        self.du_wind = u_v * absorptance_ratio

        return self

    def to_pvsyst(self):
        '''
        Convert the generic model parameters to PVsyst model equivalents.

        Returns
        ----------
        model_parameters : dict
            See :py:func:`pvlib.temperature.pvsyst_cell` for
            model parameter details.
        '''
        net_absorptance_glm = self.alpha - self.eta
        net_absorptance_pvsyst = self.alpha * (1.0 - self.eta)
        absorptance_ratio = net_absorptance_glm / net_absorptance_pvsyst

        u_c = self.u_const / absorptance_ratio
        u_v = self.du_wind / absorptance_ratio

        return dict(u_c=u_c,
                    u_v=u_v,
                    module_efficiency=self.eta,
                    alpha_absorption=self.alpha)

    def use_noct_sam(self, noct, module_efficiency=None,
                     transmittance_absorptance=None):
        '''
        Use the NOCT SAM model parameters to set the generic_model equivalents.

        Parameters
        ----------
        noct : float
            See :py:func:`pvlib.temperature.noct_sam` for details.

        module_efficiency, transmittance_absorptance : float, optional
            See :py:func:`pvlib.temperature.noct_sam` for details.

        Notes
        -----
        The optional parameters are primarily for convenient compatibility
        with existing function signatures.
        '''
        if module_efficiency is not None:
            self.eta = module_efficiency

        if transmittance_absorptance is not None:
            self.alpha = transmittance_absorptance

        # NOCT is determined with wind speed near module height
        # the adjustment reduces the wind coefficient for use with 10m wind
        wind_adj = 0.51
        u_noct = 800.0 * self.alpha / (noct - 20.0)
        self.u_const = u_noct * 0.6
        self.du_wind = u_noct * 0.4 * wind_adj

        return self

    def to_noct_sam(self):
        '''
        Convert the generic model parameters to NOCT SAM model equivalents.

        Returns
        ----------
        model_parameters : dict
            See :py:func:`pvlib.temperature.noct_sam` for
            model parameter details.
        '''
        # NOCT is determined with wind speed near module height
        # the adjustment reduces the wind coefficient for use with 10m wind
        wind_adj = 0.51
        u_noct = self.u_const + self.du_wind / wind_adj
        noct = 20.0 + (800.0 * self.alpha) / u_noct

        return dict(noct=noct,
                    module_efficiency=self.eta,
                    transmittance_absorptance=self.alpha)

    def use_sapm(self, a, b, wind_fit_low=1.4, wind_fit_high=5.4):
        '''
        Use the SAPM model parameters to set the generic_model equivalents.

        In the SAPM the heat transfer coefficient increases exponentially
        with windspeed, whereas in the other models the increase is linear.
        This function equates the generic linear model to SAPM at two
        specified winds speeds, thereby defining a linear approximation
        for the exponential behavior.

        Parameters
        ----------
        a, b : float
            See :py:func:`pvlib.temperature.sapm_module` for details.

        wind_fit_low : float, optional
            First wind speed value at which the generic linear model
            must be equal to the SAPM model. [m/s]

        wind_fit_high : float, optional
            Second wind speed value at which the generic linear model
            must be equal to the SAPM model. [m/s]

        Notes
        -----
        The two default wind speed values are based on measurements
        at 10 m height.  Both the SAPM model and the conversion
        functions can work with wind speed data at different heights as
        long as the same height is used consistently throughout.
        '''
        u_low = 1.0 / np.exp(a + b * wind_fit_low)
        u_high = 1.0 / np.exp(a + b * wind_fit_high)

        du_wind = (u_high - u_low) / (wind_fit_high - wind_fit_low)
        u_const = u_low - du_wind * wind_fit_low

        net_absorptance = self.alpha - self.eta
        self.u_const = u_const * net_absorptance
        self.du_wind = du_wind * net_absorptance

        return self

    def to_sapm(self, wind_fit_low=1.4, wind_fit_high=5.4):
        '''
        Convert the generic model parameters to SAPM model equivalents.

        In the SAPM the heat transfer coefficient increases exponentially
        with windspeed, whereas in the other models the increase is linear.
        This function equates SAPM to the generic linear model at two
        specified winds speeds, thereby defining an exponential approximation
        for the linear behavior.

        Parameters
        ----------
        wind_fit_low : float, optional
            First wind speed value at which the generic linear model
            must be equal to the SAPM model. [m/s]

        wind_fit_high : float, optional
            Second wind speed value at which the generic linear model
            must be equal to the SAPM model. [m/s]

        Returns
        ----------
        model_parameters : dict
            See :py:func:`pvlib.temperature.sapm_module` for
            model parameter details.

        Notes
        -----
        The two default wind speed values are based on measurements
        at 10 m height.  Both the SAPM model and the conversion
        functions can work with wind speed data at different heights as
        long as the same height is used consistently throughout.
        '''
        net_absorptance = self.alpha - self.eta
        u_const = self.u_const / net_absorptance
        du_wind = self.du_wind / net_absorptance

        u_low = u_const + du_wind * wind_fit_low
        u_high = u_const + du_wind * wind_fit_high

        b = - ((np.log(u_high) - np.log(u_low)) /
               (wind_fit_high - wind_fit_low))
        a = - (np.log(u_low) + b * wind_fit_low)

        return dict(a=a, b=b)