NREL bird clearsky (#276)

* add requirements.txt to install into virtualenv and ignore venv/

* add Bird clearsky model

* move clearsky.py into clearsky/core.py just for fun, let's try it out
* fix path to data in clearsky to LinkeTurbidities.mat
* add BIRD workbook to data for testing

Signed-off-by: Mark Mikofski <[email protected]>

* move test_bird to test_clearsky and move bird to clearsky core module

* revert api changes

* add spencer and pvcdron eot to solarposition, fix test and 2pi

* add equation of time test

* compare eot from spencer and pvcdrom to spa-python
* add note about coefficients in spencer 1971 and more references

* addressing comments in PR 276

* clean up docstrings for bird model, fix pub date to 1981, add references section, add attribution to daryl myers
* add spaces between colon and parameter to ineichen and simplified_solis models to correspond to numpydoc style
* revert changes in 457615d, change pvlib-path back to dirname of clearsky.py file, remove added clearsky_path
* start to change bird function signature to conform to existing clear sky algos, and strip out some of the complicated algos like the relative airmass, declination and solpos
 * change args aod_380nm to aod380 and aod_500nm to aod500.
 * clean up eot docstrings, add references, use external linking

* add declination formulas to solarposition.py

* added both cooper-69 and spencer-71
* replacing calls in bird to calls to new formulas for declination, eot, dayangle

* make bird function signature similar to other clearsky methods

* remove day_angle, relative airmass, eot, zenith, declination, extraterrestrial dni calcs, and pass values in as needed
* change o3_cm to ozone, h2o_cm to precipitable_water, b_a to asymmetry and alb to albedo
* replace pstar, patm and am_press with absolute airmass method from atmosphere
* testvalues no longer needed
* use irradiance.extraradiation() and remove etr()
* add analytical solar zenith angle and hour angle methods to solar position module

* add all parameters to docstring for bird clearsky

* also add returns
* remove defaults for aod, since should be supplied
TODO: change input to broadband when linke turbidity PR is complete
* remove times, not needed anymore
* remove commented relative airmass(method="kasten1966") since passed as arg
* remove extraradiation(method="spencer") since passed as arg
* change etr_ to etr since no more etr
TODO: change all variables to easier names
* add seinfeld and pandis to declination references
* finish hour angle calc

* add all parameters to docstring for bird clearsky

* also add returns
* remove defaults for aod, since should be supplied
TODO: change input to broadband when linke turbidity PR is complete
* remove times, not needed anymore
* remove commented relative airmass(method="kasten1966") since passed as arg
* remove extraradiation(method="spencer") since passed as arg
* change etr_ to etr since no more etr
TODO: change all variables to easier names
* add seinfeld and pandis to declination references
* finish hour angle calc

* set night values to zero

* save ze_cos once, instead of recalculating
* simplify/shorten some lines now that np.where(airmass > 0,<calc>,0.0) is gone

* calculate diffuse_horiz return value prior to return line

* update test_bird() with new function signature

* update docs

* add to what's new for v0.4.4
* add new solar position formulas and bird clear sky to api
* move links to references, and space references to make numpydoc happy
* add see also for eot, declination and solar_zenith_analytical

* add missing requirements

* add it to min build too

* remove dependence on xlrd

- use csv file instead of xls file - NOTE: I made this file by
changing all cells' format to General, fitting column size to content
width to show all significant figures, then saving as csv, new file
is less than 370kb vs 1.2mb
- use pandas read_csv instead of xlrd, way easier :)
- remove requirements.txt, can't be bothered

* move low precision solar position correlations to new api section

* add Daryl R. Myers, "Solar Radiation" CRC Press (2013) reference
* fix some sphinx-build errors in solar-position, explicit emphasis
start with no end for "*Note" (missing closing "*" for emphasis in
`nrel_earthsun_distance` and `spa_python`
* use numpydoc linked references for spencer71 equation of time

* test keywords in bird clear sky model

* add BIRD_08_16_2012_patm.csv for 2nd bird test data
* fix docs by moving text before parameters so not indented

* test scalars in bird model

* add test data file

* lower case Spencer71 in docs and solarposition

* fix lower case 's' in spencer71

* output OrderedDict or DataFrame

* fix link

* update docstring returns to OrderedDict/DataFrame

* provide note on solar vs apparent zenith and testing

* quotes for 'direct_horizontal' in docstring returns

* add tests for solarposition low-accuracy formulas

* move whats new note from 0.4.4 to 0.4.5
* test declination and solar-zenith
* correct spelling of Rayleigh

Author: mikofski

docs/sphinx/source/api.rst

@@ -46,6 +46,7 @@ unless you know that you need a different function.
    solarposition.pyephem
    solarposition.spa_c
 
+
 Additional functions for quantities closely related to solar position.
 
 .. autosummary::
@@ -65,6 +66,19 @@ algorithm.
    spa
 
 
+Correlations and analytical expressions for low precision solar position
+calculations.
+
+.. autosummary::
+   :toctree: generated/
+
+   solarposition.solar_zenith_analytical
+   solarposition.declination_spencer71
+   solarposition.declination_cooper69
+   solarposition.equation_of_time_spencer71
+   solarposition.equation_of_time_pvcdrom
+   solarposition.hour_angle
+
 Clear sky
 =========
 
@@ -77,6 +91,7 @@ Clear sky
    clearsky.simplified_solis
    clearsky.haurwitz
    clearsky.detect_clearsky
+   clearsky.bird
 
 
 Airmass and atmospheric models

docs/sphinx/source/whatsnew/v0.4.5.txt

@@ -9,9 +9,13 @@ Bug fixes
 
 * Fix pandas 0.20 incompatibilities in Location.get_clearsky,
   solarposition.ephemeris (:issue:`325`)
+* Added NREL Bird clear sky model. (:issue:`276`)
+* Added lower accuracy formulas for equation of time, declination, hour angle
+  and solar zenith.
 
 
 Contributors
 ~~~~~~~~~~~~
 
 * Will Holmgren
+* Mark Mikofski

pvlib/clearsky.py

@@ -12,7 +12,7 @@
 import numpy as np
 import pandas as pd
 
-from pvlib import tools
+from pvlib import tools, atmosphere, solarposition, irradiance
 
 
 def ineichen(apparent_zenith, airmass_absolute, linke_turbidity,
@@ -31,19 +31,19 @@ def ineichen(apparent_zenith, airmass_absolute, linke_turbidity,
 
     Parameters
     -----------
-    apparent_zenith: numeric
+    apparent_zenith : numeric
         Refraction corrected solar zenith angle in degrees.
 
-    airmass_absolute: numeric
+    airmass_absolute : numeric
         Pressure corrected airmass.
 
-    linke_turbidity: numeric
+    linke_turbidity : numeric
         Linke Turbidity.
 
-    altitude: numeric
+    altitude : numeric
         Altitude above sea level in meters.
 
-    dni_extra: numeric
+    dni_extra : numeric
         Extraterrestrial irradiance. The units of ``dni_extra``
         determine the units of the output.
 
@@ -349,24 +349,24 @@ def simplified_solis(apparent_elevation, aod700=0.1, precipitable_water=1.,
 
     Parameters
     ----------
-    apparent_elevation: numeric
+    apparent_elevation : numeric
         The apparent elevation of the sun above the horizon (deg).
 
-    aod700: numeric
+    aod700 : numeric
         The aerosol optical depth at 700 nm (unitless).
         Algorithm derived for values between 0 and 0.45.
 
-    precipitable_water: numeric
+    precipitable_water : numeric
         The precipitable water of the atmosphere (cm).
         Algorithm derived for values between 0.2 and 10 cm.
         Values less than 0.2 will be assumed to be equal to 0.2.
 
-    pressure: numeric
+    pressure : numeric
         The atmospheric pressure (Pascals).
         Algorithm derived for altitudes between sea level and 7000 m,
         or 101325 and 41000 Pascals.
 
-    dni_extra: numeric
+    dni_extra : numeric
         Extraterrestrial irradiance. The units of ``dni_extra``
         determine the units of the output.
 
@@ -720,3 +720,124 @@ def rmse(alpha):
         return clear_samples, components, alpha
     else:
         return clear_samples
+
+
+def bird(zenith, airmass_relative, aod380, aod500, precipitable_water,
+         ozone=0.3, pressure=101325., dni_extra=1364., asymmetry=0.85,
+         albedo=0.2):
+    """
+    Bird Simple Clear Sky Broadband Solar Radiation Model
+
+    Based on NREL Excel implementation by Daryl R. Myers [1, 2].
+
+    Bird and Hulstrom define the zenith as the "angle between a line to the sun
+    and the local zenith". There is no distinction in the paper between solar
+    zenith and apparent (or refracted) zenith, but the relative airmass is
+    defined using the Kasten 1966 expression, which requires apparent zenith.
+    Although the formulation for calculated zenith is never explicitly defined
+    in the report, since the purpose was to compare existing clear sky models
+    with "rigorous radiative transfer models" (RTM) it is possible that apparent
+    zenith was obtained as output from the RTM. However, the implentation
+    presented in PVLIB is tested against the NREL Excel implementation by Daryl
+    Myers which uses an analytical expression for solar zenith instead of
+    apparent zenith.
+
+    Parameters
+    ----------
+    zenith : numeric
+        Solar or apparent zenith angle in degrees - see note above
+    airmass_relative : numeric
+        Relative airmass
+    aod380 : numeric
+        Aerosol optical depth [cm] measured at 380[nm]
+    aod500 : numeric
+        Aerosol optical depth [cm] measured at 500[nm]
+    precipitable_water : numeric
+        Precipitable water [cm]
+    ozone : numeric
+        Atmospheric ozone [cm], defaults to 0.3[cm]
+    pressure : numeric
+        Ambient pressure [Pa], defaults to 101325[Pa]
+    dni_extra : numeric
+        Extraterrestrial radiation [W/m^2], defaults to 1364[W/m^2]
+    asymmetry : numeric
+        Asymmetry factor, defaults to 0.85
+    albedo : numeric
+        Albedo, defaults to 0.2
+
+    Returns
+    -------
+    clearsky : DataFrame (if Series input) or OrderedDict of arrays
+        DataFrame/OrderedDict contains the columns/keys
+        ``'dhi', 'dni', 'ghi', 'direct_horizontal'`` in  [W/m^2].
+
+    See also
+    --------
+    pvlib.atmosphere.bird_hulstrom80_aod_bb
+    pvlib.atmosphere.relativeairmass
+
+    References
+    ----------
+    [1] R. E. Bird and R. L Hulstrom, "A Simplified Clear Sky model for Direct
+    and Diffuse Insolation on Horizontal Surfaces" SERI Technical Report
+    SERI/TR-642-761, Feb 1981. Solar Energy Research Institute, Golden, CO.
+
+    [2] Daryl R. Myers, "Solar Radiation: Practical Modeling for Renewable
+    Energy Applications", pp. 46-51 CRC Press (2013)
+
+    `NREL Bird Clear Sky Model <http://rredc.nrel.gov/solar/models/clearsky/>`_
+
+    `SERI/TR-642-761 <http://rredc.nrel.gov/solar/pubs/pdfs/tr-642-761.pdf>`_
+
+    `Error Reports <http://rredc.nrel.gov/solar/models/clearsky/error_reports.html>`_
+    """
+    etr = dni_extra  # extraradiation
+    ze_rad = np.deg2rad(zenith)  # zenith in radians
+    airmass = airmass_relative
+    # Bird clear sky model
+    am_press = atmosphere.absoluteairmass(airmass, pressure)
+    t_rayleigh = (
+        np.exp(-0.0903 * am_press ** 0.84 * (
+            1.0 + am_press - am_press ** 1.01
+        ))
+    )
+    am_o3 = ozone*airmass
+    t_ozone = (
+        1.0 - 0.1611 * am_o3 * (1.0 + 139.48 * am_o3) ** -0.3034 -
+        0.002715 * am_o3 / (1.0 + 0.044 * am_o3 + 0.0003 * am_o3 ** 2.0)
+    )
+    t_gases = np.exp(-0.0127 * am_press ** 0.26)
+    am_h2o = airmass * precipitable_water
+    t_water = (
+        1.0 - 2.4959 * am_h2o / (
+            (1.0 + 79.034 * am_h2o) ** 0.6828 + 6.385 * am_h2o
+        )
+    )
+    bird_huldstrom = atmosphere.bird_hulstrom80_aod_bb(aod380, aod500)
+    t_aerosol = np.exp(
+        -(bird_huldstrom ** 0.873) *
+        (1.0 + bird_huldstrom - bird_huldstrom ** 0.7088) * airmass ** 0.9108
+    )
+    taa = 1.0 - 0.1 * (1.0 - airmass + airmass ** 1.06) * (1.0 - t_aerosol)
+    rs = 0.0685 + (1.0 - asymmetry) * (1.0 - t_aerosol / taa)
+    id_ = 0.9662 * etr * t_aerosol * t_water * t_gases * t_ozone * t_rayleigh
+    ze_cos = np.where(zenith < 90, np.cos(ze_rad), 0.0)
+    id_nh = id_ * ze_cos
+    ias = (
+        etr * ze_cos * 0.79 * t_ozone * t_gases * t_water * taa *
+        (0.5 * (1.0 - t_rayleigh) + asymmetry * (1.0 - (t_aerosol / taa))) / (
+            1.0 - airmass + airmass ** 1.02
+        )
+    )
+    gh = (id_nh + ias) / (1.0 - albedo * rs)
+    diffuse_horiz = gh - id_nh
+    # TODO: be DRY, use decorator to wrap methods that need to return either
+    # OrderedDict or DataFrame instead of repeating this boilerplate code
+    irrads = OrderedDict()
+    irrads['direct_horizontal'] = id_nh
+    irrads['ghi'] = gh
+    irrads['dni'] = id_
+    irrads['dhi'] = diffuse_horiz
+    if isinstance(irrads['dni'], pd.Series):
+        irrads = pd.DataFrame.from_dict(irrads)
+    return irrads