initial campbellnormal

Author: cwhanse

docs/sphinx/source/api.rst

@@ -181,6 +181,7 @@ DNI estimation models
    irradiance.dirint
    irradiance.dirindex
    irradiance.erbs
+   irradiance.campbellnorman
    irradiance.liujordan
    irradiance.gti_dirint
 

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

@@ -9,7 +9,7 @@ Breaking changes
 
 Deprecations
 ~~~~~~~~~~~~
-
+* :py:func:`pvlib.irradiance.liujordan` is deprecated.
 
 Enhancements
 ~~~~~~~~~~~~
@@ -21,6 +21,10 @@ Enhancements
   multiple MPPTs (:issue:`457`, :pull:`1085`)
 * Added optional ``attributes`` parameter to :py:func:`pvlib.iotools.get_psm3`
   and added the option of fetching 5- and 15-minute PSM3 data. (:pull:`1086`)
+* Added :py:func:`pvlib.irradiance.campbellnorman` for estimating DNI, DHI and GHI
+  from extraterrestrial irradiance. This function replaces :py:func:`pvlib.irradiance.liujordan`;
+  users of :py:func:`pvlib.irradiance.liujordan` should note that :py:func:`pvlib.irradiance.campbellnorman`
+  expects different parameters.
 
 Bug fixes
 ~~~~~~~~~

pvlib/irradiance.py

@@ -13,6 +13,9 @@
 
 from pvlib import atmosphere, solarposition, tools
 
+from pvlib._deprecation import deprecated
+
+
 # see References section of grounddiffuse function
 SURFACE_ALBEDOS = {'urban': 0.18,
                    'grass': 0.20,
@@ -2184,6 +2187,58 @@ def erbs(ghi, zenith, datetime_or_doy, min_cos_zenith=0.065, max_zenith=87):
     return data
 
 
+def campbellnorman(zenith, transmittance, pressure=101325.0, dni_extra=1367.0):
+    '''
+    Determine DNI, DHI, GHI from extraterrestrial flux, transmittance,
+    and atmospheric pressure.
+
+    Parameters
+    ----------
+    zenith: pd.Series
+        True (not refraction-corrected) zenith angles in decimal
+        degrees. If Z is a vector it must be of the same size as all
+        other vector inputs. Z must be >=0 and <=180.
+
+    transmittance: float
+        Atmospheric transmittance between 0 and 1.
+
+    pressure: float, default 101325.0
+        Air pressure
+
+    dni_extra: float, default 1367.0
+        Direct irradiance incident at the top of the atmosphere.
+
+    Returns
+    -------
+    irradiance: DataFrame
+        Modeled direct normal irradiance, direct horizontal irradiance,
+        and global horizontal irradiance in W/m^2
+
+    References
+    ----------
+    .. [1] Campbell, G. S., J. M. Norman (1998) An Introduction to
+       Environmental Biophysics. 2nd Ed. New York: Springer.
+    '''
+
+    tau = transmittance
+
+    airmass = atmosphere.get_relative_airmass(zenith, model='simple')
+    airmass = atmosphere.get_absolute_airmass(airmass, pressure=pressure)
+    dni = dni_extra*tau**airmass
+    dhi = 0.3 * (1.0 - tau**airmass) * dni_extra * np.cos(np.radians(zenith))
+    ghi = dhi + dni * np.cos(np.radians(zenith))
+
+    irrads = OrderedDict()
+    irrads['ghi'] = ghi
+    irrads['dni'] = dni
+    irrads['dhi'] = dhi
+
+    if isinstance(ghi, pd.Series):
+        irrads = pd.DataFrame(irrads)
+
+    return irrads
+
+
 def liujordan(zenith, transmittance, airmass, dni_extra=1367.0):
     '''
     Determine DNI, DHI, GHI from extraterrestrial flux, transmittance,
@@ -2242,6 +2297,10 @@ def liujordan(zenith, transmittance, airmass, dni_extra=1367.0):
     return irrads
 
 
+liujordan = deprecated('0.8', alternative='campbellnormam',
+                         name='liujordan', removal='0.9')(liujordan)
+
+
 def _get_perez_coefficients(perezmodel):
     '''
     Find coefficients for the Perez model

pvlib/tests/test_irradiance.py

@@ -295,6 +295,17 @@ def test_liujordan():
     assert_frame_equal(out, expected)
 
 
+def test_campbellnorman():
+    expected = pd.DataFrame(np.array(
+        [[863.859736967, 653.123094076, 220.65905025]]),
+        columns=['ghi', 'dni', 'dhi'],
+        index=[0])
+    out = irradiance.campbellnorman(
+        pd.Series([10]), pd.Series([0.5]), pd.Series([109764.21013135818]),
+        dni_extra=1400)
+    assert_frame_equal(out, expected)
+
+
 def test_get_total_irradiance(irrad_data, ephem_data, dni_et, relative_airmass):
     models = ['isotropic', 'klucher',
               'haydavies', 'reindl', 'king', 'perez']