pvlib 0.9.4a1__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

@@ -1481,24 +1481,24 @@ def _disc_kn(clearness_index, airmass, max_airmass=12):
 
     am = np.minimum(am, max_airmass)  # GH 450
 
-    # powers of kt will be used repeatedly, so compute only once
-    kt2 = kt * kt  # about the same as kt ** 2
-    kt3 = kt2 * kt  # 5-10x faster than kt ** 3
-
-    bools = (kt <= 0.6)
-    a = np.where(bools,
-                 0.512 - 1.56*kt + 2.286*kt2 - 2.222*kt3,
-                 -5.743 + 21.77*kt - 27.49*kt2 + 11.56*kt3)
-    b = np.where(bools,
-                 0.37 + 0.962*kt,
-                 41.4 - 118.5*kt + 66.05*kt2 + 31.9*kt3)
-    c = np.where(bools,
-                 -0.28 + 0.932*kt - 2.048*kt2,
-                 -47.01 + 184.2*kt - 222.0*kt2 + 73.81*kt3)
+    is_cloudy = (kt <= 0.6)
+    # Use Horner's method to compute polynomials efficiently
+    a = np.where(
+        is_cloudy,
+        0.512 + kt*(-1.56 + kt*(2.286 - 2.222*kt)),
+        -5.743 + kt*(21.77 + kt*(-27.49 + 11.56*kt)))
+    b = np.where(
+        is_cloudy,
+        0.37 + 0.962*kt,
+        41.4 + kt*(-118.5 + kt*(66.05 + 31.9*kt)))
+    c = np.where(
+        is_cloudy,
+        -0.28 + kt*(0.932 - 2.048*kt),
+        -47.01 + kt*(184.2 + kt*(-222.0 + 73.81*kt)))
 
     delta_kn = a + b * np.exp(c*am)
 
-    Knc = 0.866 - 0.122*am + 0.0121*am**2 - 0.000653*am**3 + 1.4e-05*am**4
+    Knc = 0.866 + am*(-0.122 + am*(0.0121 + am*(-0.000653 + 1.4e-05*am)))
     Kn = Knc - delta_kn
     return Kn, am
 
@@ -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,198 @@ 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"""
+    Estimate DNI and DHI from GHI using the Boland clearness index model.
+
+    The Boland model [1]_, [2]_ estimates the diffuse fraction, DF, from global
+    horizontal irradiance, GHI, through an empirical relationship between DF
+    and the clearness index, :math:`k_t`, the ratio of GHI to horizontal
+    extraterrestrial irradiance.
+
+    .. math::
+
+        \mathit{DF} = \frac{1}{1 + \exp\left(a \left(k_t - b\right)\right)}
+
+
+    Parameters
+    ----------
+    ghi: numeric
+        Global horizontal irradiance. [W/m^2]
+    solar_zenith: numeric
+        True (not refraction-corrected) zenith angles in decimal degrees.
+    datetime_or_doy : numeric, pandas.DatetimeIndex
+        Day of year or array of days of year e.g.
+        pd.DatetimeIndex.dayofyear, or pd.DatetimeIndex.
+    a_coeff : float, default 8.645
+        Logistic curve fit coefficient.
+    b_coeff : float, default 0.613
+        Logistic curve fit coefficient.
+    min_cos_zenith : numeric, default 0.065
+        Minimum value of cos(zenith) to allow when calculating global
+        clearness index :math:`k_t`. 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] J. Boland, B. Ridley (2008) Models of Diffuse Solar Fraction. In:
+       Badescu V. (eds) Modeling Solar Radiation at the Earth’s Surface.
+       Springer, Berlin, Heidelberg. :doi:`10.1007/978-3-540-77455-6_8`
+    .. [2] John Boland, Lynne Scott, and Mark Luther, Modelling the diffuse
+       fraction of global solar radiation on a horizontal surface,
+       Environmetrics 12(2), pp 103-116, 2001,
+       :doi:`10.1002/1099-095X(200103)12:2%3C103::AID-ENV447%3E3.0.CO;2-2`
+
+    See also
+    --------
+    dirint
+    disc
+    erbs
+    orgill_hollands
+
+    Notes
+    -----
+    Boland diffuse fraction differs from other decomposition algorithms by use
+    of a logistic function to fit the entire range of clearness index,
+    :math:`k_t`. Parameters ``a_coeff`` and ``b_coeff`` are reported in [2]_
+    for different time intervals:
+
+    * 15-minute: ``a = 8.645`` and ``b = 0.613``
+    * 1-hour:  ``a = 7.997`` and ``b = 0.586``
+    """
+
+    dni_extra = get_extra_radiation(datetime_or_doy)
+
+    kt = clearness_index(
+        ghi, solar_zenith, dni_extra, min_cos_zenith=min_cos_zenith,
+        max_clearness_index=1)
+
+    # Boland equation
+    df = 1.0 / (1.0 + np.exp(a_coeff * (kt - b_coeff)))
+    # NOTE: [2] has different coefficients, for different time intervals
+    # 15-min: df = 1 / (1 + exp(8.645 * (kt - 0.613)))
+    # 1-hour: df = 1 / (1 + exp(7.997 * (kt - 0.586)))
+
+    dhi = df * ghi
+
+    dni = (ghi - dhi) / 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
+
+
 def campbell_norman(zenith, transmittance, pressure=101325.0,
                     dni_extra=1367.0):
     '''
@@ -3013,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