more edits

Author: wholmgren

docs/sphinx/source/clearsky.rst

@@ -3,12 +3,17 @@
 Clear sky
 =========
 
-Clear sky expectations are essential to many PV modeling tasks.
-Here, we briefly review the clear sky modeling capabilities of pvlib-python.
+Clear sky irradiance data is essential to many PV modeling tasks. Here, we
+review the clear sky modeling capabilities of pvlib-python. The
+:ref:`location` section demonstrates the easiest way to obtain a time
+series of clear sky data for a location. The :ref:`ineichen` and
+:ref:`simplified_solis` sections detail the clear sky algorithms and
+input data.
+
+We'll need these imports for the examples below.
 
 .. ipython:: python
 
-    import datetime
     import itertools
     import pandas as pd
     import matplotlib.pyplot as plt
@@ -23,23 +28,26 @@ Here, we briefly review the clear sky modeling capabilities of pvlib-python.
     from pvlib.location import Location
 
 
+.. _location:
+
 Location
 --------
 
-The easiest way to get clear sky data is to use a
+The easiest way to obtain a time series of clear sky irradiance is to use a
 :py:class:`~pvlib.location.Location` object's
 :py:meth:`~pvlib.location.Location.get_clearsky` method. The
 :py:meth:`~pvlib.location.Location.get_clearsky` method does the dirty
 work of calculating solar position, extraterrestrial irradiance,
 airmass, and atmospheric pressure, as appropriate, leaving the user to
-only specify the most important parameters. We encourage users to
-examine the source code.
+only specify the most important parameters: time and atmospheric
+attenuation.
 
 .. ipython:: python
 
     tus = Location(32.2, -111, 'US/Arizona', 700, 'Tucson')
-    times = pd.DatetimeIndex(start='2016-07-01', end='2016-07-04', freq='1min', tz=tus.tz)
-    cs = tus.get_clearsky(times)  # ineichen with lookup table by default
+    times = pd.DatetimeIndex(start='2016-07-01', end='2016-07-04',
+                             freq='1min', tz=tus.tz)
+    cs = tus.get_clearsky(times)  # ineichen with climatology table by default
     cs.plot();
     plt.ylabel('Irradiance $W/m^2$');
     @savefig location-basic.png width=6in
@@ -67,11 +75,16 @@ functions that do the computation.
     plt.ylabel('Irradiance $W/m^2$');
 
 
+See the sections below for more detail on the clear sky models.
+
+
+.. _ineichen:
+
 Ineichen
 --------
 
-The Ineichen and Perez (2002) clear sky model parameterizes irradiance
-in terms of the Linke turbidity.
+The Ineichen and Perez clear sky model parameterizes irradiance
+in terms of the Linke turbidity [Ine02]_.
 
 Turbidity data
 ^^^^^^^^^^^^^^
@@ -90,23 +103,25 @@ the year. You could run it in a loop to create plots for all months.
     filepath = os.path.join(pvlib_path, 'data', 'LinkeTurbidities.mat')
 
     mat = scipy.io.loadmat(filepath)
-    linke_turbidity_table = mat['LinkeTurbidity'] / 20
+    linke_turbidity_table = mat['LinkeTurbidity'] / 20.
 
     month = 1
-    plt.figure(figsize=(20,10));
     plt.imshow(linke_turbidity_table[:, :, month-1], vmin=1, vmax=5);
     plt.title(calendar.month_name[1+month]);
+    plt.colorbar(shrink=0.5);
+    plt.tight_layout();
     @savefig turbidity-1.png width=10in
-    plt.colorbar();
+    plt.show();
 
 .. ipython:: python
 
     month = 7
-    plt.figure(figsize=(20,10));
     plt.imshow(linke_turbidity_table[:, :, month-1], vmin=1, vmax=5);
     plt.title(calendar.month_name[month]);
+    plt.colorbar(shrink=0.5);
+    plt.tight_layout();
     @savefig turbidity-7.png width=10in
-    plt.colorbar();
+    plt.show();
 
 The :py:func:`~pvlib.clearsky.lookup_linke_turbidity` function takes a
 time, latitude, and longitude and gets the corresponding climatological
@@ -141,10 +156,18 @@ the variability of the data set.
     @savefig turbidity-yes-interp.png width=6in
     plt.ylabel('Linke Turbidity');
 
+Examples
+^^^^^^^^
+
+.. ipython:: python
+
+
 
 Validation
 ^^^^^^^^^^
 
+See [Ine02]_, [Ren12]_.
+
 Will Holmgren compared pvlib's Ineichen model and climatological
 turbidity to `SoDa's McClear service
 <http://www.soda-pro.com/web-services/radiation/cams-mcclear>`_ in
@@ -155,11 +178,13 @@ and its `html rendering
 <https://forecasting.energy.arizona.edu/media/ineichen_vs_mcclear.html>`_.
 
 
+.. _simplified_solis:
+
 Simplified Solis
 ----------------
 
 The Simplified Solis model parameterizes irradiance in terms of
-precipitable water and aerosol optical depth.
+precipitable water and aerosol optical depth [Ine08ss]_.
 
 Aerosol and precipitable water data
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -170,80 +195,88 @@ Ground based aerosol data can be obtained from
 `Aeronet <http://aeronet.gsfc.nasa.gov>`_. Precipitable water can be obtained
 from `radiosondes <http://weather.uwyo.edu/upperair/sounding.html>`_,
 `ESRL GPS-MET <http://gpsmet.noaa.gov/cgi-bin/gnuplots/rti.cgi>`_, or
-derived from surface relative humidity using the
-:py:func:`pvlib.atmosphere.gueymard94_pw` function.
+derived from surface relative humidity using functions such as
+:py:func:`pvlib.atmosphere.gueymard94_pw`.
 Numerous gridded products from satellites, weather models, and climate models
 contain one or both of aerosols and precipitable water.
 
-Note that aerosol optical depth is a function of wavelength, so be sure
-that you understand the aerosol data that you're looking at. The
-Simplified Solis model requires AOD at 700 nm. Models exist to convert
-AOD between different wavelengths, as well as convert Linke turbidity to
-AOD.
+Aerosol optical depth is a function of wavelength, and the Simplified
+Solis model requires AOD at 700 nm. Models exist to convert AOD between
+different wavelengths, as well as convert Linke turbidity to AOD and PW
+[Ine08con]_, [Ine16]_.
+
 
+Examples
+^^^^^^^^
 
+A clear sky time series using basic pvlib functions.
 
 .. ipython:: python
 
+    latitude, longitude, tz, altitude, name = 32.2, -111, 'US/Arizona', 700, 'Tucson'
+    times = pd.date_range(start='2014-01-01', end='2014-01-02', freq='1Min', tz=tz)
+    solpos = pvlib.solarposition.get_solarposition(times, latitude, longitude)
+
+    apparent_elevation = solpos['apparent_elevation']
     aod700 = 0.1
     precipitable_water = 1
-    apparent_elevation = pd.Series(np.linspace(-10, 90, 101))
-    pressure = 101325
-    dni_extra = 1364
+    pressure = pvlib.atmosphere.alt2pres(altitude)
+    dni_extra = pvlib.irradiance.extraradiation(apparent_elevation.index.dayofyear)
 
-    solis = clearsky.simplified_solis(apparent_elevation, aod700,
-                                      precipitable_water, pressure, dni_extra)
-    ax = solis.plot()
-    ax.set_xlabel('apparent elevation (deg)');
-    ax.set_ylabel('irradiance (W/m**2)');
-    @savefig solis-vs-elevation.png width=6in
+    solis = clearsky.simplified_solis(apparent_elevation, aod700, precipitable_water,
+                                      pressure, dni_extra)
+    ax = solis.plot();
+    ax.set_ylabel('Irradiance $W/m^2$');
     ax.legend(loc=2);
+    @savefig solis-vs-time-0.1-1.png width=6in
+    plt.show();
 
 
-.. ipython:: python
-
-    from pvlib.location import Location
+Irradiance as a function of solar elevation.
 
-    tus = Location(32.2, -111, 'US/Arizona', 700, 'Tucson')
-    times = pd.date_range(start=datetime.datetime(2014,1,1), end=datetime.datetime(2014,1,2), freq='1Min').tz_localize(tus.tz)
-    solpos = pvlib.solarposition.get_solarposition(times, tus.latitude, tus.longitude)
-    ephem_data = solpos
+.. ipython:: python
 
+    apparent_elevation = pd.Series(np.linspace(-10, 90, 101))
     aod700 = 0.1
     precipitable_water = 1
-    apparent_elevation = solpos['apparent_elevation']
-    pressure = pvlib.atmosphere.alt2pres(tus.altitude)
-    dni_extra = pvlib.irradiance.extraradiation(apparent_elevation.index.dayofyear)
+    pressure = 101325
+    dni_extra = 1364
 
-    solis = clearsky.simplified_solis(apparent_elevation, aod700, precipitable_water, pressure, dni_extra)
-    @savefig solis-vs-time.png width=6in
-    solis.plot();
+    solis = clearsky.simplified_solis(apparent_elevation, aod700,
+                                      precipitable_water, pressure, dni_extra)
+    ax = solis.plot()
+    ax.set_xlabel('Apparent elevation (deg)');
+    ax.set_ylabel('Irradiance $W/m^2$');
+    ax.set_title('Irradiance vs Solar Elevation')
+    @savefig solis-vs-elevation.png width=6in
+    ax.legend(loc=2);
 
 
+Grid with a clear sky irradiance for a few PW and AOD values.
 
 .. ipython:: python
 
-    times = pd.date_range(start=datetime.datetime(2014,9,1), end=datetime.datetime(2014,9,2), freq='1Min').tz_localize(tus.tz)
-    solpos = pvlib.solarposition.get_solarposition(times, tus.latitude, tus.longitude)
-    ephem_data = solpos
+    times = pd.date_range(start='2014-09-01', end='2014-09-02', freq='1Min', tz=tz)
+    solpos = pvlib.solarposition.get_solarposition(times, latitude, longitude)
 
     apparent_elevation = solpos['apparent_elevation']
-    pressure = pvlib.atmosphere.alt2pres(tus.altitude)
+    pressure = pvlib.atmosphere.alt2pres(altitude)
     dni_extra = pvlib.irradiance.extraradiation(apparent_elevation.index.dayofyear)
-
     aod700 = [0.01, 0.1]
     precipitable_water = [0.5, 5]
 
-    for aod, pw in itertools.product(aod700, precipitable_water):
+    fig, axes = plt.subplots(ncols=2, nrows=2, sharex=True, sharey=True, squeeze=True)
+    axes = axes.flatten()
+
+    for (aod, pw), ax in zip(itertools.chain(itertools.product(aod700, precipitable_water)), axes):
         solis = clearsky.simplified_solis(apparent_elevation, aod, pw,
                                           pressure, dni_extra)
-        fig, ax = plt.subplots()
         solis.plot(ax=ax, title='aod700={}, pw={}'.format(aod, pw))
-        ax.set_ylim(0, 1100)
-        file = 'aod{}_pw{}.png'.format(aod, pw)
-        @savefig file width=6in
-        plt.show()
 
+    @savefig solis-grid.png width=10in
+    plt.show();
+
+Contour plots of irradiance as a function of both PW and AOD.
 
 .. ipython:: python
 
@@ -265,7 +298,7 @@ AOD.
 
     def plot_solis(key):
         irrad = solis[key]
-        fig, ax = plt.subplots(figsize=(12,9))
+        fig, ax = plt.subplots()
         im = ax.contour(aod700, precipitable_water, irrad[:, :], n, cmap=cmap, vmin=vmin, vmax=vmax)
         imf = ax.contourf(aod700, precipitable_water, irrad[:, :], n, cmap=cmap, vmin=vmin, vmax=vmax)
         ax.set_xlabel('AOD')
@@ -277,20 +310,45 @@ AOD.
 .. ipython:: python
 
     plot_solis('ghi')
-    @savefig solis-ghi.png width=6in
+    @savefig solis-ghi.png width=10in
     plt.show()
 
     plot_solis('dni')
-    @savefig solis-dni.png width=6in
+    @savefig solis-dni.png width=10in
     plt.show()
 
     plot_solis('dhi')
-    @savefig solis-dhi.png width=6in
+    @savefig solis-dhi.png width=10in
     plt.show()
 
 
 Validation
 ^^^^^^^^^^
 
+See [Ine16]_.
+
 We encourage users to compare the pvlib implementation to Ineichen's
 `Excel tool <http://www.unige.ch/energie/fr/equipe/ineichen/solis-tool/>`_.
+
+
+References
+----------
+
+.. [Ine02] P. Ineichen and R. Perez, "A New airmass independent formulation for
+   the Linke turbidity coefficient", Solar Energy, 73, pp. 151-157,
+   2002.
+
+.. [Ine08ss] P. Ineichen, "A broadband simplified version of the
+   Solis clear sky model," Solar Energy, 82, 758-762 (2008).
+
+.. [Ine16] P. Ineichen, "Validation of models that estimate the clear
+   sky global and beam solar irradiance," Solar Energy, 132,
+   332-344 (2016).
+
+.. [Ine08con] P. Ineichen, "Conversion function between the Linke turbidity
+   and the atmospheric water vapor and aerosol content", Solar Energy,
+   82, 1095 (2008).
+
+.. [Ren12] M. Reno, C. Hansen, and J. Stein, "Global Horizontal Irradiance Clear
+   Sky Models: Implementation and Analysis", Sandia National
+   Laboratories, SAND2012-2389, 2012.