pvlib 0.9.5__py3-none-any.whl → 0.10.0__py3-none-any.whl

pvlib/iotools/tmy.py

@@ -3,9 +3,29 @@
 import datetime
 import re
 import pandas as pd
-
-
-def read_tmy3(filename, coerce_year=None, recolumn=True):
+import warnings
+from pvlib._deprecation import pvlibDeprecationWarning
+
+# Dictionary mapping TMY3 names to pvlib names
+VARIABLE_MAP = {
+    'GHI (W/m^2)': 'ghi',
+    'ETR (W/m^2)': 'ghi_extra',
+    'DNI (W/m^2)': 'dni',
+    'ETRN (W/m^2)': 'dni_extra',
+    'DHI (W/m^2)': 'dhi',
+    'Pressure (mbar)': 'pressure',
+    'Wdir (degrees)': 'wind_direction',
+    'Wspd (m/s)': 'wind_speed',
+    'Dry-bulb (C)': 'temp_air',
+    'Dew-point (C)': 'temp_dew',
+    'RHum (%)': 'relative_humidity',
+    'Alb (unitless)': 'albedo',
+    'Pwat (cm)': 'precipitable_water'
+}
+
+
+def read_tmy3(filename, coerce_year=None, map_variables=None, recolumn=None,
+              encoding=None):
     """Read a TMY3 file into a pandas dataframe.
 
     Note that values contained in the metadata dictionary are unchanged
@@ -24,9 +44,18 @@ def read_tmy3(filename, coerce_year=None, recolumn=True):
         If supplied, the year of the index will be set to `coerce_year`, except
         for the last index value which will be set to the *next* year so that
         the index increases monotonically.
-    recolumn : bool, default True
+    map_variables : bool, default None
+        When True, renames columns of the DataFrame to pvlib variable names
+        where applicable. See variable :const:`VARIABLE_MAP`.
+    recolumn : bool (deprecated, use map_variables instead)
         If ``True``, apply standard names to TMY3 columns. Typically this
         results in stripping the units from the column name.
+        Cannot be used in combination with ``map_variables``.
+    encoding : str, optional
+        Encoding of the file. For files that contain non-UTF8 characters it may
+        be necessary to specify an alternative encoding, e.g., for
+        SolarAnywhere TMY3 files the encoding should be 'iso-8859-1'. Users
+        may also consider using the 'utf-8-sig' encoding.
 
     Returns
     -------
@@ -35,7 +64,7 @@ def read_tmy3(filename, coerce_year=None, recolumn=True):
     data : DataFrame
         A pandas dataframe with the columns described in the table
         below. For more detailed descriptions of each component, please
-        consult the TMY3 User's Manual ([1]_), especially tables 1-1
+        consult the TMY3 User's Manual [1]_, especially tables 1-1
         through 1-6.
 
     metadata : dict
@@ -57,80 +86,83 @@ def read_tmy3(filename, coerce_year=None, recolumn=True):
     USAF              Int     USAF identifier
     ===============   ======  ===================
 
-    =====================       ======================================================================================================================================================
-    field                       description
-    =====================       ======================================================================================================================================================
-    Index                       A pandas datetime index. NOTE, the index is timezone aware, and times are set to local standard time (daylight savings is not included)
-    ETR                         Extraterrestrial horizontal radiation recv'd during 60 minutes prior to timestamp, Wh/m^2
-    ETRN                        Extraterrestrial normal radiation recv'd during 60 minutes prior to timestamp, Wh/m^2
-    GHI                         Direct and diffuse horizontal radiation recv'd during 60 minutes prior to timestamp, Wh/m^2
-    GHISource                   See [1]_, Table 1-4
-    GHIUncertainty              Uncertainty based on random and bias error estimates see [2]_
-    DNI                         Amount of direct normal radiation (modeled) recv'd during 60 mintues prior to timestamp, Wh/m^2
-    DNISource                   See [1]_, Table 1-4
-    DNIUncertainty              Uncertainty based on random and bias error estimates see [2]_
-    DHI                         Amount of diffuse horizontal radiation recv'd during 60 minutes prior to timestamp, Wh/m^2
-    DHISource                   See [1]_, Table 1-4
-    DHIUncertainty              Uncertainty based on random and bias error estimates see [2]_
-    GHillum                     Avg. total horizontal illuminance recv'd during the 60 minutes prior to timestamp, lx
-    GHillumSource               See [1]_, Table 1-4
-    GHillumUncertainty          Uncertainty based on random and bias error estimates see [2]_
-    DNillum                     Avg. direct normal illuminance recv'd during the 60 minutes prior to timestamp, lx
-    DNillumSource               See [1]_, Table 1-4
-    DNillumUncertainty          Uncertainty based on random and bias error estimates see [2]_
-    DHillum                     Avg. horizontal diffuse illuminance recv'd during the 60 minutes prior to timestamp, lx
-    DHillumSource               See [1]_, Table 1-4
-    DHillumUncertainty          Uncertainty based on random and bias error estimates see [2]_
-    Zenithlum                   Avg. luminance at the sky's zenith during the 60 minutes prior to timestamp, cd/m^2
-    ZenithlumSource             See [1]_, Table 1-4
-    ZenithlumUncertainty        Uncertainty based on random and bias error estimates see [1]_ section 2.10
-    TotCld                      Amount of sky dome covered by clouds or obscuring phenonema at time stamp, tenths of sky
-    TotCldSource                See [1]_, Table 1-5
-    TotCldUncertainty           See [1]_, Table 1-6
-    OpqCld                      Amount of sky dome covered by clouds or obscuring phenonema that prevent observing the sky at time stamp, tenths of sky
-    OpqCldSource                See [1]_, Table 1-5
-    OpqCldUncertainty           See [1]_, Table 1-6
-    DryBulb                     Dry bulb temperature at the time indicated, deg C
-    DryBulbSource               See [1]_, Table 1-5
-    DryBulbUncertainty          See [1]_, Table 1-6
-    DewPoint                    Dew-point temperature at the time indicated, deg C
-    DewPointSource              See [1]_, Table 1-5
-    DewPointUncertainty         See [1]_, Table 1-6
-    RHum                        Relatitudeive humidity at the time indicated, percent
-    RHumSource                  See [1]_, Table 1-5
-    RHumUncertainty             See [1]_, Table 1-6
-    Pressure                    Station pressure at the time indicated, 1 mbar
-    PressureSource              See [1]_, Table 1-5
-    PressureUncertainty         See [1]_, Table 1-6
-    Wdir                        Wind direction at time indicated, degrees from north (360 = north; 0 = undefined,calm)
-    WdirSource                  See [1]_, Table 1-5
-    WdirUncertainty             See [1]_, Table 1-6
-    Wspd                        Wind speed at the time indicated, meter/second
-    WspdSource                  See [1]_, Table 1-5
-    WspdUncertainty             See [1]_, Table 1-6
-    Hvis                        Distance to discernable remote objects at time indicated (7777=unlimited), meter
-    HvisSource                  See [1]_, Table 1-5
-    HvisUncertainty             See [1]_, Table 1-6
-    CeilHgt                     Height of cloud base above local terrain (7777=unlimited), meter
-    CeilHgtSource               See [1]_, Table 1-5
-    CeilHgtUncertainty          See [1]_, Table 1-6
-    Pwat                        Total precipitable water contained in a column of unit cross section from earth to top of atmosphere, cm
-    PwatSource                  See [1]_, Table 1-5
-    PwatUncertainty             See [1]_, Table 1-6
-    AOD                         The broadband aerosol optical depth per unit of air mass due to extinction by aerosol component of atmosphere, unitless
-    AODSource                   See [1]_, Table 1-5
-    AODUncertainty              See [1]_, Table 1-6
-    Alb                         The ratio of reflected solar irradiance to global horizontal irradiance, unitless
-    AlbSource                   See [1]_, Table 1-5
-    AlbUncertainty              See [1]_, Table 1-6
-    Lprecipdepth                The amount of liquid precipitation observed at indicated time for the period indicated in the liquid precipitation quantity field, millimeter
-    Lprecipquantity             The period of accumulatitudeion for the liquid precipitation depth field, hour
-    LprecipSource               See [1]_, Table 1-5
-    LprecipUncertainty          See [1]_, Table 1-6
-    PresWth                     Present weather code, see [2]_.
-    PresWthSource               Present weather code source, see [2]_.
-    PresWthUncertainty          Present weather code uncertainty, see [2]_.
-    =====================       ======================================================================================================================================================
+
+    ========================       ======================================================================================================================================================
+    field                          description
+    ========================       ======================================================================================================================================================
+    **† denotes variables that are mapped when `map_variables` is True**
+    -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    Index                          A pandas datetime index. NOTE, the index is timezone aware, and times are set to local standard time (daylight savings is not included)
+    ghi_extra†                     Extraterrestrial horizontal radiation recv'd during 60 minutes prior to timestamp, Wh/m^2
+    dni_extra†                     Extraterrestrial normal radiation recv'd during 60 minutes prior to timestamp, Wh/m^2
+    ghi†                           Direct and diffuse horizontal radiation recv'd during 60 minutes prior to timestamp, Wh/m^2
+    GHI source                     See [1]_, Table 1-4
+    GHI uncert (%)                 Uncertainty based on random and bias error estimates see [2]_
+    dni†                           Amount of direct normal radiation (modeled) recv'd during 60 mintues prior to timestamp, Wh/m^2
+    DNI source                     See [1]_, Table 1-4
+    DNI uncert (%)                 Uncertainty based on random and bias error estimates see [2]_
+    dhi†                           Amount of diffuse horizontal radiation recv'd during 60 minutes prior to timestamp, Wh/m^2
+    DHI source                     See [1]_, Table 1-4
+    DHI uncert (%)                 Uncertainty based on random and bias error estimates see [2]_
+    GH illum (lx)                  Avg. total horizontal illuminance recv'd during the 60 minutes prior to timestamp, lx
+    GH illum source                See [1]_, Table 1-4
+    GH illum uncert (%)            Uncertainty based on random and bias error estimates see [2]_
+    DN illum (lx)                  Avg. direct normal illuminance recv'd during the 60 minutes prior to timestamp, lx
+    DN illum source                See [1]_, Table 1-4
+    DN illum uncert (%)            Uncertainty based on random and bias error estimates see [2]_
+    DH illum (lx)                  Avg. horizontal diffuse illuminance recv'd during the 60 minutes prior to timestamp, lx
+    DH illum source                See [1]_, Table 1-4
+    DH illum uncert (%)            Uncertainty based on random and bias error estimates see [2]_
+    Zenith lum (cd/m^2)            Avg. luminance at the sky's zenith during the 60 minutes prior to timestamp, cd/m^2
+    Zenith lum source              See [1]_, Table 1-4
+    Zenith lum uncert (%)          Uncertainty based on random and bias error estimates see [1]_ section 2.10
+    TotCld (tenths)                Amount of sky dome covered by clouds or obscuring phenonema at time stamp, tenths of sky
+    TotCld source                  See [1]_, Table 1-5
+    TotCld uncert (code)           See [1]_, Table 1-6
+    OpqCld (tenths)                Amount of sky dome covered by clouds or obscuring phenonema that prevent observing the sky at time stamp, tenths of sky
+    OpqCld source                  See [1]_, Table 1-5
+    OpqCld uncert (code)           See [1]_, Table 1-6
+    temp_air†                      Dry bulb temperature at the time indicated, deg C
+    Dry-bulb source                See [1]_, Table 1-5
+    Dry-bulb uncert (code)         See [1]_, Table 1-6
+    temp_dew†                      Dew-point temperature at the time indicated, deg C
+    Dew-point source               See [1]_, Table 1-5
+    Dew-point uncert (code)        See [1]_, Table 1-6
+    relative_humidity†             Relatitudeive humidity at the time indicated, percent
+    RHum source                    See [1]_, Table 1-5
+    RHum uncert (code)             See [1]_, Table 1-6
+    pressure†                      Station pressure at the time indicated, 1 mbar
+    Pressure source                See [1]_, Table 1-5
+    Pressure uncert (code)         See [1]_, Table 1-6
+    wind_direction†                Wind direction at time indicated, degrees from north (360 = north; 0 = undefined,calm)
+    Wdir source                    See [1]_, Table 1-5
+    Wdir uncert (code)             See [1]_, Table 1-6
+    wind_speed†                    Wind speed at the time indicated, meter/second
+    Wspd source                    See [1]_, Table 1-5
+    Wspd uncert (code)             See [1]_, Table 1-6
+    Hvis (m)                       Distance to discernable remote objects at time indicated (7777=unlimited), meter
+    Hvis source                    See [1]_, Table 1-5
+    Hvis uncert (coe)              See [1]_, Table 1-6
+    CeilHgt (m)                    Height of cloud base above local terrain (7777=unlimited), meter
+    CeilHgt source                 See [1]_, Table 1-5
+    CeilHgt uncert (code)          See [1]_, Table 1-6
+    precipitable_water†            Total precipitable water contained in a column of unit cross section from earth to top of atmosphere, cm
+    Pwat source                    See [1]_, Table 1-5
+    Pwat uncert (code)             See [1]_, Table 1-6
+    AOD                            The broadband aerosol optical depth per unit of air mass due to extinction by aerosol component of atmosphere, unitless
+    AOD source                     See [1]_, Table 1-5
+    AOD uncert (code)              See [1]_, Table 1-6
+    albedo†                        The ratio of reflected solar irradiance to global horizontal irradiance, unitless
+    Alb source                     See [1]_, Table 1-5
+    Alb uncert (code)              See [1]_, Table 1-6
+    Lprecip depth (mm)             The amount of liquid precipitation observed at indicated time for the period indicated in the liquid precipitation quantity field, millimeter
+    Lprecip quantity (hr)          The period of accumulatitudeion for the liquid precipitation depth field, hour
+    Lprecip source                 See [1]_, Table 1-5
+    Lprecip uncert (code)          See [1]_, Table 1-6
+    PresWth (METAR code)           Present weather code, see [2]_.
+    PresWth source                 Present weather code source, see [2]_.
+    PresWth uncert (code)          Present weather code uncertainty, see [2]_.
+    ========================       ======================================================================================================================================================
 
     .. admonition:: Midnight representation
 
@@ -152,21 +184,21 @@ def read_tmy3(filename, coerce_year=None, recolumn=True):
     ----------
     .. [1] Wilcox, S and Marion, W. "Users Manual for TMY3 Data Sets".
        NREL/TP-581-43156, Revised May 2008.
+       :doi:`10.2172/928611`
     .. [2] Wilcox, S. (2007). National Solar Radiation Database 1991 2005
        Update: Users Manual. 472 pp.; NREL Report No. TP-581-41364.
+       :doi:`10.2172/901864`
     .. [3] `SolarAnywhere file formats
        <https://www.solaranywhere.com/support/historical-data/file-formats/>`_
     """  # noqa: E501
     head = ['USAF', 'Name', 'State', 'TZ', 'latitude', 'longitude', 'altitude']
 
-    try:
-        with open(str(filename), 'r') as fbuf:
-            firstline, data = _parse_tmy3(fbuf)
-    # SolarAnywhere files contain non-UTF8 characters and may require
-    # encoding='iso-8859-1' in order to be parsed
-    except UnicodeDecodeError:
-        with open(str(filename), 'r', encoding='iso-8859-1') as fbuf:
-            firstline, data = _parse_tmy3(fbuf)
+    with open(str(filename), 'r', encoding=encoding) as fbuf:
+        # header information on the 1st line (0 indexing)
+        firstline = fbuf.readline()
+        # use pandas to read the csv file buffer
+        # header is actually the second line, but tell pandas to look for
+        data = pd.read_csv(fbuf, header=0)
 
     meta = dict(zip(head, firstline.rstrip('\n').split(",")))
     # convert metadata strings to numeric types
@@ -178,8 +210,10 @@ def read_tmy3(filename, coerce_year=None, recolumn=True):
 
     # get the date column as a pd.Series of numpy datetime64
     data_ymd = pd.to_datetime(data['Date (MM/DD/YYYY)'], format='%m/%d/%Y')
+    # extract minutes
+    minutes = data['Time (HH:MM)'].str.split(':').str[1].astype(int)
     # shift the time column so that midnite is 00:00 instead of 24:00
-    shifted_hour = data['Time (HH:MM)'].str[:2].astype(int) % 24
+    shifted_hour = data['Time (HH:MM)'].str.split(':').str[0].astype(int) % 24
     # shift the dates at midnight (24:00) so they correspond to the next day.
     # If midnight is specified as 00:00 do not shift date.
     data_ymd[data['Time (HH:MM)'].str[:2] == '24'] += datetime.timedelta(days=1)  # noqa: E501
@@ -197,25 +231,34 @@ def read_tmy3(filename, coerce_year=None, recolumn=True):
         data_ymd.iloc[-1] = data_ymd.iloc[-1].replace(year=coerce_year+1)
     # NOTE: as of pvlib-0.6.3, min req is pandas-0.18.1, so pd.to_timedelta
     # unit must be in (D,h,m,s,ms,us,ns), but pandas>=0.24 allows unit='hour'
-    data.index = data_ymd + pd.to_timedelta(shifted_hour, unit='h')
-
-    if recolumn:
-        data = _recolumn(data)  # rename to standard column names
+    data.index = data_ymd + pd.to_timedelta(shifted_hour, unit='h') \
+        + pd.to_timedelta(minutes, unit='min')
+    # shouldnt' specify both recolumn and map_variables
+    if recolumn is not None and map_variables is not None:
+        msg = "`map_variables` and `recolumn` cannot both be specified"
+        raise ValueError(msg)
+    elif map_variables is None and recolumn is not None:
+        warnings.warn(
+            'The recolumn parameter is deprecated and will be removed in '
+            'pvlib 0.11.0. Use `map_variables` instead, although note that '
+            'its behavior is different from `recolumn`.',
+            pvlibDeprecationWarning)
+    elif map_variables is None and recolumn is None:
+        warnings.warn(
+            'TMY3 variable names will be renamed to pvlib conventions by '
+            'default starting in pvlib 0.11.0. Specify map_variables=True '
+            'to enable that behavior now, or specify map_variables=False '
+            'to hide this warning.', pvlibDeprecationWarning)
+    if map_variables:
+        data = data.rename(columns=VARIABLE_MAP)
+    elif recolumn or (recolumn is None and map_variables is None):
+        data = _recolumn(data)
 
     data = data.tz_localize(int(meta['TZ'] * 3600))
 
     return data, meta
 
 
-def _parse_tmy3(fbuf):
-    # header information on the 1st line (0 indexing)
-    firstline = fbuf.readline()
-    # use pandas to read the csv file buffer
-    # header is actually the second line, but tell pandas to look for
-    data = pd.read_csv(fbuf, header=0)
-    return firstline, data
-
-
 def _recolumn(tmy3_dataframe):
     """
     Rename the columns of the TMY3 DataFrame.
@@ -283,7 +326,7 @@ def read_tmy2(filename):
     data : DataFrame
         A dataframe with the columns described in the table below. For a
         more detailed descriptions of each component, please consult the
-        TMY2 User's Manual ([1]_), especially tables 3-1 through 3-6, and
+        TMY2 User's Manual [1]_, especially tables 3-1 through 3-6, and
         Appendix B.
 
     metadata : dict
@@ -385,6 +428,7 @@ def read_tmy2(filename):
     ----------
     .. [1] Marion, W and Urban, K. "Wilcox, S and Marion, W. "User's Manual
        for TMY2s". NREL 1995.
+       :doi:`10.2172/87130`
     """  # noqa: E501
     # paste in the column info as one long line
     string = '%2d%2d%2d%2d%4d%4d%4d%1s%1d%4d%1s%1d%4d%1s%1d%4d%1s%1d%4d%1s%1d%4d%1s%1d%4d%1s%1d%2d%1s%1d%2d%1s%1d%4d%1s%1d%4d%1s%1d%3d%1s%1d%4d%1s%1d%3d%1s%1d%3d%1s%1d%4d%1s%1d%5d%1s%1d%10d%3d%1s%1d%3d%1s%1d%3d%1s%1d%2d%1s%1d'  # noqa: E501

pvlib/irradiance.py

@@ -2227,6 +2227,8 @@ def erbs(ghi, zenith, datetime_or_doy, min_cos_zenith=0.065, max_zenith=87):
     --------
     dirint
     disc
+    orgill_hollands
+    boland
     """
 
     dni_extra = get_extra_radiation(datetime_or_doy)
@@ -2265,6 +2267,93 @@ def erbs(ghi, zenith, datetime_or_doy, min_cos_zenith=0.065, max_zenith=87):
     return data
 
 
+def orgill_hollands(ghi, zenith, datetime_or_doy, dni_extra=None,
+                    min_cos_zenith=0.065, max_zenith=87):
+    """Estimate DNI and DHI from GHI using the Orgill and Hollands model.
+
+    The Orgill and Hollands model [1]_ estimates the diffuse fraction DF from
+    global horizontal irradiance through an empirical relationship between
+    hourly DF observations (in Toronto, Canada) and the ratio of GHI to
+    extraterrestrial irradiance, Kt.
+
+    Parameters
+    ----------
+    ghi: numeric
+        Global horizontal irradiance in W/m^2.
+    zenith: numeric
+        True (not refraction-corrected) zenith angles in decimal degrees.
+    datetime_or_doy : int, float, array, pd.DatetimeIndex
+        Day of year or array of days of year e.g.
+        pd.DatetimeIndex.dayofyear, or pd.DatetimeIndex.
+    dni_extra : None or numeric, default None
+        Extraterrestrial direct normal irradiance. [W/m2]
+    min_cos_zenith : numeric, default 0.065
+        Minimum value of cos(zenith) to allow when calculating global
+        clearness index `kt`. Equivalent to zenith = 86.273 degrees.
+    max_zenith : numeric, default 87
+        Maximum value of zenith to allow in DNI calculation. DNI will be
+        set to 0 for times with zenith values greater than `max_zenith`.
+
+    Returns
+    -------
+    data : OrderedDict or DataFrame
+        Contains the following keys/columns:
+
+            * ``dni``: the modeled direct normal irradiance in W/m^2.
+            * ``dhi``: the modeled diffuse horizontal irradiance in
+              W/m^2.
+            * ``kt``: Ratio of global to extraterrestrial irradiance
+              on a horizontal plane.
+
+    References
+    ----------
+    .. [1] Orgill, J.F., Hollands, K.G.T., Correlation equation for hourly
+      diffuse radiation on a horizontal surface, Solar Energy 19(4), pp 357–359,
+      1977. Eqs. 3(a), 3(b) and 3(c)
+      :doi:`10.1016/0038-092X(77)90006-8`
+
+    See Also
+    --------
+    dirint
+    disc
+    erbs
+    boland
+    """
+    if dni_extra is None:
+        dni_extra = get_extra_radiation(datetime_or_doy)
+
+    kt = clearness_index(ghi, zenith, dni_extra, min_cos_zenith=min_cos_zenith,
+                         max_clearness_index=1)
+
+    # For Kt < 0.35, set the diffuse fraction
+    df = 1 - 0.249*kt
+
+    # For Kt >= 0.35 and Kt <= 0.75, set the diffuse fraction
+    df = np.where((kt >= 0.35) & (kt <= 0.75),
+                  1.557 - 1.84*kt, df)
+
+    # For Kt > 0.75, set the diffuse fraction
+    df = np.where(kt > 0.75, 0.177, df)
+
+    dhi = df * ghi
+
+    dni = (ghi - dhi) / tools.cosd(zenith)
+    bad_values = (zenith > max_zenith) | (ghi < 0) | (dni < 0)
+    dni = np.where(bad_values, 0, dni)
+    # ensure that closure relationship remains valid
+    dhi = np.where(bad_values, ghi, dhi)
+
+    data = OrderedDict()
+    data['dni'] = dni
+    data['dhi'] = dhi
+    data['kt'] = kt
+
+    if isinstance(datetime_or_doy, pd.DatetimeIndex):
+        data = pd.DataFrame(data, index=datetime_or_doy)
+
+    return data
+
+
 def boland(ghi, solar_zenith, datetime_or_doy, a_coeff=8.645, b_coeff=0.613,
            min_cos_zenith=0.065, max_zenith=87):
     r"""
@@ -2326,6 +2415,7 @@ def boland(ghi, solar_zenith, datetime_or_doy, a_coeff=8.645, b_coeff=0.613,
     dirint
     disc
     erbs
+    orgill_hollands
 
     Notes
     -----
@@ -3117,3 +3207,64 @@ def complete_irradiance(solar_zenith,
                                      'dhi': dhi,
                                      'dni': dni})
     return component_sum_df
+
+
+def louche(ghi, solar_zenith, datetime_or_doy, max_zenith=90):
+    """
+    Determine DNI and DHI from GHI using the Louche model.
+
+    Parameters
+    ----------
+    ghi : numeric
+        Global horizontal irradiance. [W/m^2]
+
+    solar_zenith : numeric
+        True (not refraction-corrected) zenith angles in decimal
+        degrees. Angles must be >=0 and <=90.
+
+    datetime_or_doy : numeric, pandas.DatetimeIndex
+        Day of year or array of days of year e.g.
+        pd.DatetimeIndex.dayofyear, or pd.DatetimeIndex.
+
+    Returns
+    -------
+    data: OrderedDict or DataFrame
+        Contains the following keys/columns:
+
+            * ``dni``: the modeled direct normal irradiance in W/m^2.
+            * ``dhi``: the modeled diffuse horizontal irradiance in
+              W/m^2.
+            * ``kt``: Ratio of global to extraterrestrial irradiance
+              on a horizontal plane.
+
+    References
+    -------
+    .. [1] Louche A, Notton G, Poggi P, Simonnot G. Correlations for direct
+       normal and global horizontal irradiation on a French Mediterranean site.
+       Solar Energy 1991;46:261-6. :doi:`10.1016/0038-092X(91)90072-5`
+
+    """
+
+    I0 = get_extra_radiation(datetime_or_doy)
+
+    Kt = clearness_index(ghi, solar_zenith, I0)
+
+    kb = -10.627*Kt**5 + 15.307*Kt**4 - 5.205 * \
+        Kt**3 + 0.994*Kt**2 - 0.059*Kt + 0.002
+    dni = kb*I0
+    dhi = ghi - dni*tools.cosd(solar_zenith)
+
+    bad_values = (solar_zenith > max_zenith) | (ghi < 0) | (dni < 0)
+    dni = np.where(bad_values, 0, dni)
+    # ensure that closure relationship remains valid
+    dhi = np.where(bad_values, ghi, dhi)
+
+    data = OrderedDict()
+    data['dni'] = dni
+    data['dhi'] = dhi
+    data['kt'] = Kt
+
+    if isinstance(datetime_or_doy, pd.DatetimeIndex):
+        data = pd.DataFrame(data, index=datetime_or_doy)
+
+    return data

pvlib/ivtools/sde.py

@@ -64,7 +64,8 @@ def fit_sandia_simple(voltage, current, v_oc=None, i_sc=None, v_mp_i_mp=None,
 
     Raises
     ------
-    RuntimeError if parameter extraction is not successful.
+    RuntimeError
+        if parameter extraction is not successful.
 
     Notes
     -----
@@ -106,7 +107,7 @@ def fit_sandia_simple(voltage, current, v_oc=None, i_sc=None, v_mp_i_mp=None,
     .. math::
 
         I &\approx \frac{I_{L}}{1 + G_{p} R_{s}}
-        - \frac{G_{p}}{1 + G_{p}R_{s}} V
+        - \frac{G_{p}}{1 + G_{p}R_{s}} V \\
         &= \beta_{0} + \beta_{1} V
 
     4. The exponential portion of the IV curve is defined by
@@ -124,8 +125,8 @@ def fit_sandia_simple(voltage, current, v_oc=None, i_sc=None, v_mp_i_mp=None,
     .. math::
 
         \log(\beta_{0} - \beta_{1} V - I)
-        &\approx \log(\frac{I_{0}}{1 + G_{p} R_{s}} + \frac{V}{nN_sV_{th}}
-        + \frac{I R_{s}}{nN_sV_{th}}) \\
+        &\approx \log(\frac{I_{0}}{1 + G_{p} R_{s}}) + \frac{V}{nN_sV_{th}}
+        + \frac{I R_{s}}{nN_sV_{th}} \\
         &= \beta_{2} + \beta_{3} V + \beta_{4} I
 
     6. Calculate values for ``IL, I0, Rs, Rsh,`` and ``nNsVth`` from the
@@ -139,7 +140,8 @@ def fit_sandia_simple(voltage, current, v_oc=None, i_sc=None, v_mp_i_mp=None,
        0 86758 909 4
     .. [2] C. B. Jones, C. W. Hansen, "Single Diode Parameter Extraction from
        In-Field Photovoltaic I-V Curves on a Single Board Computer", 46th IEEE
-       Photovoltaic Specialist Conference, Chicago, IL, 2019
+       Photovoltaic Specialist Conference, Chicago, IL, 2019.
+       :doi:`10.1109/PVSC40753.2019.8981330`
     """
 
     # If not provided, extract v_oc, i_sc, v_mp and i_mp from the IV curve data
@@ -289,8 +291,10 @@ def _fit_sandia_cocontent(voltage, current, nsvth):
 
     Raises
     ------
-    ValueError if ``voltage`` and ``current`` are different lengths.
-    ValueError if ``len(voltage)`` < 6
+    ValueError
+        if ``voltage`` and ``current`` are different lengths.
+    ValueError
+        if ``len(voltage)`` < 6
 
     Notes
     -----

pvlib/ivtools/sdm.py

@@ -76,9 +76,10 @@ def fit_cec_sam(celltype, v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc,
 
     Raises
     ------
-        ImportError if NREL-PySAM is not installed.
-
-        RuntimeError if parameter extraction is not successful.
+    ImportError
+        if NREL-PySAM is not installed.
+    RuntimeError
+        if parameter extraction is not successful.
 
     Notes
     -----
@@ -94,7 +95,7 @@ def fit_cec_sam(celltype, v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc,
     ----------
     .. [1] A. Dobos, "An Improved Coefficient Calculator for the California
        Energy Commission 6 Parameter Photovoltaic Module Model", Journal of
-       Solar Energy Engineering, vol 134, 2012.
+       Solar Energy Engineering, vol 134, 2012. :doi:`10.1115/1.4005759`
     """
 
     try:
@@ -204,7 +205,7 @@ def fit_desoto(v_mp, i_mp, v_oc, i_sc, alpha_sc, beta_voc, cells_in_series,
     ----------
     .. [1] W. De Soto et al., "Improvement and validation of a model for
        photovoltaic array performance", Solar Energy, vol 80, pp. 78-88,
-       2006.
+       2006. :doi:`10.1016/j.solener.2005.06.010`
     """
 
     # Constants
@@ -405,6 +406,7 @@ def fit_pvsyst_sandia(ivcurves, specs, const=None, maxiter=5, eps1=1.e-3):
     .. [1] K. Sauer, T. Roessler, C. W. Hansen, Modeling the Irradiance and
        Temperature Dependence of Photovoltaic Modules in PVsyst, IEEE Journal
        of Photovoltaics v5(1), January 2015.
+       :doi:`10.1109/JPHOTOV.2014.2364133`
     .. [2] A. Mermoud, PV Modules modeling, Presentation at the 2nd PV
        Performance Modeling Workshop, Santa Clara, CA, May 2013
     .. [3] A. Mermoud, T. Lejeuene, Performance Assessment of a Simulation
@@ -412,11 +414,13 @@ def fit_pvsyst_sandia(ivcurves, specs, const=None, maxiter=5, eps1=1.e-3):
        Photovoltaic Solar Energy Conference, Valencia, Spain, Sept. 2010
     .. [4] C. Hansen, Estimating Parameters for the PVsyst Version 6
        Photovoltaic Module Performance Model, Sandia National Laboratories
-       Report SAND2015-8598
+       Report SAND2015-8598. :doi:`10.2172/1223058`
     .. [5] C. Hansen, Parameter Estimation for Single Diode Models of
-       Photovoltaic Modules, Sandia National Laboratories Report SAND2015-2065
+       Photovoltaic Modules, Sandia National Laboratories Report SAND2015-2065.
+       :doi:`10.2172/1177157`
     .. [6] C. Hansen, Estimation of Parameters for Single Diode Models using
         Measured IV Curves, Proc. of the 39th IEEE PVSC, June 2013.
+        :doi:`10.1109/PVSC.2013.6744135`
     .. [7] PVLib MATLAB https://github.com/sandialabs/MATLAB_PV_LIB
     """
 
@@ -574,11 +578,13 @@ def fit_desoto_sandia(ivcurves, specs, const=None, maxiter=5, eps1=1.e-3):
     ----------
     .. [1] W. De Soto et al., "Improvement and validation of a model for
        photovoltaic array performance", Solar Energy, vol 80, pp. 78-88,
-       2006.
+       2006. :doi:`10.1016/j.solener.2005.06.010`
     .. [2] C. Hansen, Parameter Estimation for Single Diode Models of
-       Photovoltaic Modules, Sandia National Laboratories Report SAND2015-2065
+       Photovoltaic Modules, Sandia National Laboratories Report SAND2015-2065.
+       :doi:`10.2172/1177157`
     .. [3] C. Hansen, Estimation of Parameters for Single Diode Models using
         Measured IV Curves, Proc. of the 39th IEEE PVSC, June 2013.
+        :doi:`10.1109/PVSC.2013.6744135`
     .. [4] PVLib MATLAB https://github.com/sandialabs/MATLAB_PV_LIB
     """
 
@@ -942,7 +948,7 @@ def _update_io(voc, iph, io, rs, rsh, nnsvth):
 
     while maxerr > eps and k < niter:
         # Predict Voc
-        pvoc = v_from_i(rsh, rs, nnsvth, 0., tio, iph)
+        pvoc = v_from_i(0., iph, tio, rs, rsh, nnsvth)
 
         # Difference in Voc
         dvoc = pvoc - voc