        INTRODUCTION

SBDART has a large number of input parameters, which provides an
experienced user a great deal of flexibility in specifying radiative
transfer problems. SBDART is a command line code.  It reads control
parameters from an input file (INPUT) and writes ASCII output to
stdout.  This mode of operation is useful for generating output for
graphics postprocessors or for generating databases for remote sensing
retrievals, but it is not very useful for students trying to
understand how radiative transfer works. The RunRT graphical user
interface is designed to fill this gap.  RunRT is a python 2.7
graphics code that makes it easy to run SBDART and display its output
graphically in ways that bring out the essential features of the
radiative transfer physics. The RunRT interface is quite simple, yet
flexible enough to perform many of the computational problems that
come up in climate science or remote sensing.

One of the main barriers to getting started with new modeling software
is the effort required to learn about which input parameters matter,
and the typical range overwhich these parameters vary. To help ease
this learning curve, the RunRT user interface provides a simple lookup
system to suggest reasonable values for the input parameters the user
decides to include in the SBDART run. There are four entry boxes at
the top of the RunRT user interface.  The first entry widget is used
to select an SBDART input parameter.  The remaining 4 boxes are used
to specify a resonable sampling of its typical range of variation.

    AN EXAMPLE WITH INTEGRATED FLUX OUTPUT (IOUT=10)

When RunRT starts up, the "RT parm" entry widget is initialized with
"TCLOUD", an SBDART input parameter that specifies cloud optical
depth.  This parameter was chosen as the default because it has large
effect on the radiation budget.  Next to the "RT parm" selection box
is a text field that gives a short description of the RT parameter.
Next, the "Start" and "End" boxes show a physically reasonable range
of values for cloud optical depth.  The "Num" entry box specifies the
number of samples between the "Start" and "End" values.  Finally, the
"Skew" parameter is used to bias the sample distribution toward
smaller values.  (Skew=0 corresponds to a logarithmic distribution,
while skew=1 yields a linearly spaced distribution). The values
displayed in the "Start", and "End" boxes may be changed either by
direct edits or by rolling the mouse wheel.  Immediately below the
entry widgets is a wide text box that shows a preview of a potential
RunRT sequence command.  On startup this widget contains the text

TCLOUD=0;10;20;30;40;50;60;70;80;90;100

Note that this sequence of optical depth values is consistent with the
values of start and ending values and the number samples.

Now we'll complete a simple input sequence to show how these widgets
are used to generate a sequence of SBDART runs.  First, place the
mouse cursor in the "End" entry widget.  Roll the mouse wheel up and
down, and notice how the preview command is changed to match the new
"End" value. Set the "End" value to 90. The "Start" value may be
changed in a similar way. Now move the mouse to the "Num" entry box
and increase the number of sample points to 10 using the same mouse
wheel technique.

Finally, by pressing the "Add" button, the preview command string is
copied to the end of command entry box, located under the graph. If a
parameter of the same name had already been present in the command
entry box, pressing the "Add" button would have replaced it with the
version shown in the preview command string.  If the "Add" button is
pressed with the middle mouse button, all contents of the command
entry box are erased before adding the preview command.  This is a
handy way to start over on a completely new calculation.

The command entry box can be thought of as a staging area to assemble
the RunRT command sequence. After a user becomes familiar with the
RunRT command sequence, it is sometimes convenient to directly edit
the commands in the command entry box.  But for now we'll focus on
commands generated on the preview line and added to the command entry
box using the "Add" button.

Next, move the mouse to the the "RT parm" entry box. With focus in the
widget, roll the mouse wheel up and down, and notice how the RT
parameter switches to different SBDART input variables.  Each time the
selection switches to a new RT parameter, the description, "Start",
and "End" values change accordingly.  The sequence of values of the RT
parameter is also previewed in a text box immediately below the entry
boxes.  Roll the mouse wheel up until parameter SZA is shown (The RT
parameters are listed in alphabetic order).  At this point the preview
box should show the 10 values of solar zenith angle from 0 to 80
degrees.  Put the mouse in the Num entry box and set the number of
samples to 9.  Press the "Add" button to copy the preview command to
the command box.  Press the "Run" button to execute this command
sequence.

At this point the command entry box should look like,


# Description: Example 1
#
TCLOUD=0;10;20;30;40;50;60;70;80;90
SZA=0;10;20;30;40;50;60;70;80
IOUT=10

The first two lines are comment fields that can be changed as desired
to provide descriptive information about the run.  The lines that
don't start with the "#" are the active commands that cause SBDART to
compute integrated radiative quantities at the surface and top of the
atmosphere for a range of cloud optical depth and solar zenith angle,
with the first parameter (TCLOUD) varying in the inner most loop.  The
type of output generated in this example is specific to the IOUT=10,
the default output format.  All the IOUT output formats that may be
used with RunRT are listed here:

    IOUT=1          Spectral profile irradiance plots
    IOUT=2          Spectral profile transmission plots
    IOUT=10         Spectrally integrated fluxes at top and bottom of atmosphere
    IOUT=11         Vertical profiles spectrally integrated flux
    IOUT=20 or 21   Radiance contour plots

Examples of the other plot types will be shown below. But for now we
will continue with the integrated flux (IOUT=10) example.

Taking a look at the plot generated by our first trial run, note that
all values of SZA are shown in the plot. If this seems too cluttered,
some of the SZA plot lines can be removed by unselecting them in the
"Plot lines" menu. With IOUT=10, SBDART computes upward and downward
integrated flux, at the surface and the top of the atmosphere.
Initially, the BOTDN flux is selected for plotting.  Other plot
quantities may be overlayed by selecting them in the "RT Quants" menu.

Before leaving this example lets see if we can improve the plot. Note
that our initial run shows abrupt changes in flux at the lower end of
the optical depth scale.  Evidently, a jump from TCLOUD=0 to TCLOUD=10
is too large to produce a smooth plot.  Lets fix this by visiting the
"Skew" input box and setting the skew value to 0.3 using the mouse
wheel.  This value of skew puts more samples of cloud optical depth in
the range where there is greatest sensitivity to its variation.  Press
the "Add" button, and note that the previous TCLOUD parameter sequence
has been replaced in the command entry box.  Finally, press "Run",
wait a moment, and notice that the plots are better resolved near
TCLOUD=0.

At this point we can save this calculation to a named file by visiting
the "File" menu and selecting "Save." The file will be saved with a
file suffix, '.pkl' in the RUNS folder (the RUNS folder is located
RunRT working directory).  Archived runs may be read back into RunRT
by selecting File -> Open.

We could also extend this calculation by adding another RT parameter
variant.  For example, visit "RT parm" and select "ALBCON." Set the
number of samples to 11, press "Add", and then "Run."  Again, RunRT
shows plot output for all values of SZA, but now the effect of
changing surface albedo can be assessed by visiting the newly created
spinbox, which shows different values of ALBCON.  Rolling the mouse
wheel up and down shows computed results with different values of
surface albedo.

This sequence of commands made cloud optical depth the inner most
do-loop variable.  The next most rapid variation was in SZA.  Surface
albedo was the outer-most loop variable.  With the IOUT=10 output
format the variable that varies in the inner loop is always treated as
the dependent variable in the plot (x-axis).  All values of the next
most rapidly changing parameter is overlayed on the plot.  Parameters
that vary in the 3rd and higher nested loops are selected through
spinboxes.

It is, however, possible to overlay all values of any looped variable
on the same plot.  For example, in our previous example, we may want
to compare radiative output for all values of surface albedo at a
fixed value of solar zenith angle. This can be accomplished by
clicking in the spinbox with the right mouse button.  This action puts
ALBCON variation in the "Plot lines" menu and SZA variation in the
spinbox.  Now rolling in the spinbox changes values of SZA, and shows
all values of ALBCON in the plot.  Another right mouse button click in
the spinbox switches back to the original configuration. This
capablilty is extended to any number of nested RT parameters.  For
IOUT=10, N nested RT parameter variants results in N-2 spinboxes.

        AN EXAMPLE SHOWING SPECTRAL OUTPUT (IOUT=1)

To execute a new scenario two options are available: either edit the
displayed command sequence as desired, or erase the contents of the
command box by adding the first new command using a middle mouse
button click on the "Add" button.  Lets proceed using this later
approach.

For the next example, we'll compute the spectral radiant flux leaving
the top of the atmosphere in the infrared, with goal of determining
how variations in water vapor and surface temperature affect the
radiative energy budget. Use the techniques described above to put the
following commands in the command box:

# Description: Example 2
#
BTEMP=260;270;280;290;300;310;320;330
UW=0.5261;1.1;1.725;2.406;3.15;3.96;4.843;5.806;6.856;8
WLINF=6
WLSUP=14
WLINC=20
IOUT=1

An easier way to accomplish this would have been to copy the commands
listed above directly into the command box.  This could be done using
the copy and paste commands appropriate to your operating system
(e.g., COMMAND-C and COMMAND-V on OSX).  After the command box is
populated as indicated above, press "Run".  Note, in runs that use the
IOUT=1 output format, the x-variable is always wavelength (or wavenumber).
For this run, the spinbox shows different values of the percipitable
water vapor.

      AN EXAMPLE SHOWING VERTICAL RADIANT FLUX PROFILES (IOUT=11)

For this example, we'll compute the vertical profile of radiant flux
in the infrared. We'd like to see where water vapor and CO2 affects
the IR radiant flux over the same spectral range as the previous
example.  In this case the dependent variable is the height in the
atmosphere, which is shown along the vertical y-axis.

# Description: Example 3
#
UW=0.5;1.5;4
XCO2=200;400
BTEMP=300
WLINF=6
WLSUP=14
WLINC=20
IOUT=11


      A RADIANCE EXAMPLE (IOUT=21)

Our final example will show how to produce radiance contour plots with
SBDART. Set the command box as follows:

# Description: Example 4
#
TCLOUD=0;10
WLINF=0.4;0.8
WLSUP=0.4;0.8 &
SZA=60
IOUT=21

Here we have introduce another useful feature of the RunRT command
language -- the capability to specify variable RT parameters that
change in lock-step with each other.  The ampersand attatched to the
WLSUP parameter sequence indicates that WLSUP should vary with WLINF.
So in this case calculations are performed for TCLOUD=0 and TCLOUD=10,
and for (WLINF=WLSUP=0.4) and (WLINF=WLSUP=0.8).  It is important to
remember that RT parameters that are intended to vary together should
have exactly the same number of samples.  This calculation may be
varied slightly to compute the radiance integrated over a band of
wavelengths, say over 10 um bands centered at 0.45 and 0.85 um. The
input commads for that calculation would look like:

# Description: Example 5
#
TCLOUD=0;10
WLINF=0.4;0.8
WLSUP=0.5;0.9 &
SZA=60
IOUT=21

        OTHER INTERSTING FEATURES OF THE RunRT USER INTERFACE


1) With focus in the plot window the x and y plot range may be
   adjusted by rolling the mouse wheel.  Rolling the mouse wheel to
   the left of y-axis adjusts the y-axis scale. Mouse rolls below the
   x-axis adjusts the x-axis scale. If the roll event occurs near the
   plot origin it adjusts the lower limit of the plot.  If the roll
   event occurs near the max, it controls the max extent of the axis.
   The sense of the roll (either up or down) determines whether the
   limit is increased or decreased.  The effect of the axis scaling
   persists until the y-autorange checkbox is toggled.

2) If SBDART fails to complete the full RunRT command sequence, the
   last attempted RT command sequence is saved in a file
   RUNS/~runrt.sbd.  This file is copied back into the command entry
   box by selecting File -> Recover

3) In addition to the document you are now reading, the Help menu
   contains a help file, rtdoc.txt, which documents SBDART input
   parameters.  If rtdoc is visible in a pop-up window, it will move
   to the place in the documentation that covers the RT parameter
   selected in the RT parm widget.

4) With focus in the RT parm widget, you can quickly move to another
   RT parm by entering the first few letters of the parameter and
   pressing RETURN.  For example, typing 'al<return>' is quick way to
   switch to the ALBCON RT parameter.

5) Double clicking on one of the parameters listed in the command box
   will cause that parameter to be selected in the RT parm widget.

6) When assembling a command file that varies several RT parameters in
   lock-step it is sometimes necessary to define a loop variable which
   is not itself an RT variable interpretable by SBDART.  For example,
   suppose the goal is to compute the thermal spectral profile for
   four cases:

        1) No water vapor absorption, all other absorption nominal
        2) No CO2 absorption, all other absorption nominal
        3) No ozone absorption, all other absorption nominal
        4) All absorption nominal

   It would be tempting to write the command file as

   UW=   0;-1;-1;-1
   XCO2=-1; 0;-1;-1 &
   UO3= -1;-1; 0;-1 &
   WLINF=6
   WLSUP=14
   WLINC=5
   IOUT=1

   With this command sequence the SBDART runs would complete, but
   RunRT would choke while plotting the results. This is because the
   first variant, UW, which is used as a dictionary key for selecting
   lines to plot, is non-varying over the last three iterations
   (dictionary keys must be unique).  The solution is to define a new
   loop variable that is not used in the SBDART input, but is used by
   RunRT to disambiguate the loop sequence.  The new command sequence
   looks like this:

# Description: Example 5
#
#   Demonstrate use of pseudo variables to disambiguate parameter keys
#
_Abs=No H2O;No CO2;No O3;All
UW=    0; -1;-1;-1 &
XCO2= -1;  0;-1;-1 &
UO3=  -1; -1; 0;-1 &
WLINF=6
WLSUP=14
WLINC=5
IOUT=1

   The psuedo variant, in this case _Abs, is composed of any string
   that starts with a non-alphabetic character.  The values on the
   right of the equals sign are any set of strings that describe the
   loop sequence.  The RHS strings ('No H2O', 'No CO2', 'No O3',
   'ALL') will show up in the line labels, but the psuedo variant _Abs
   will not.

7) Moving the mouse cursor near a plot line hi-lights the line both on
   the plot and in the legend.  This is helpful when the color of
   plotted lines are hard to distinguish.

8) Click on a plot line with left mouse button to mark it as a baseline
   for difference plots.  Then by pressing Options -> 'Difference plots'
   or 'Ratio plots' in options menu,the baseline curve will either be
   subtracted or divided out of all other lines in the plot.  Pressing
   the Options -> 'No comparison plots' will restore the default plots.

9) Clicking on a plot line with middle mouse button causes the minimum
   maximum and integral of the curve to be written to preview widget. This
   action does not affect the baseline selection described above.

10) SBDART can be used to plot the diurnal variation of solar flux at a
   given latitutude and longitude as a function of time.  The first
   step is to compute a sequence of SBDART IOUT=10 calculations
   (irradiance at the top and bottom of the atmosphere) with SZA as the
   first variant parameter.  After the runs are complete, the diurnal
   plots are produced by pressing one of these choices in the options
   menu:

   * Nominal                   return to normal plotting
   * Hourly irradiance         irradiance as a function of time of day
   * Hourly irradiance (fine)  irradiance as a function of time of day.
                               Fine scale specification of latitude and
                               longitude.
   * Diurnal average vs lat    average irradiance over day vs latitude
   * Diurnal average vs day    average irradiance over day vs day of year

   For example, try running this sample file before selecting one of the
   diurnal variation plots in the options menu:

# Description: Example 6
#
#   Demonstrate diurnal plots based on a sequence of SZA calculations
#
SZA=0;5;10;15;20;25;30;35;40;45;50;55;60;65;70;75;80;85;90
TCLOUD=0;6.38;27.84;100
WLINF=0.3;0.8
WLSUP=0.3;0.8 &
NRE=8
WLINC=20
IOUT=10

11) The File menu provides several ways to review and save data displayed
    in the current plot.

     * Pressing File -> Open, will display a file dialog to choose files to
       view in RunRT.  More than one file may be selected through the dialog.
       The first file is diplayed immediately.  The other files in the list
       are opened by pressing the shift-up-arrow or shift-down-arrow.  When
       RunRT is first opened the saved file list contains all the .pkl files
       in the RUNS directory.

     * Pressing File -> View Plot Data, will display the current plot
       data to a popup window and save the data to the clipboard. The
       clipboard information may be further analyzed by pasteing it
       into a spreadsheet (e.g., Excel).

     * Pressing File -> Save Plot will cause the visible plot to be
       written to a PNG file in the same directory as the save files.
       The name of the plot will be derived from the run name
       associated with the scenario.  By the way, pressing File ->
       Save as..., performs the same function as the Save menu option
       (see below), but also changes the run name.

     * There are two ways save the results of a RunRT run.

       Pressing 'File -> Write' saves the run in an ascii format that
       is human readable, and may be easier to adapt for use in non-
       python post-processing solfware.  Unfortunately, the ascii format
       is slow to re-load, since it requires a fair bit of time to
       re-parse the file each time it's read from disk. The ascii files
       are written with a '.sbd' file suffix.

       Pressing 'File -> save' writes the run data to disk in Python's
       object serialization format, pickle (.pkl file suffix).  This
       binary format is much faster to re-load than the '.sbd' files.

       The pickle save files also provide an easy way to import the SBDART
       run data into an ipython session.  To simplify the process a short
       import utility, named RtRestore.py, is provided in the RunRT
       directory.  As an example of how to recover data in an interactive
       session, run and save Example2, above, as example2.pkl.  Then start
       an ipython session in another window, and issue the following
       commands,

$ ipython

In [1]: import RtRestore as rtr
In [2]: p=rtr.RtRestore()  # hit a return to get the last created
                           # pkl file listed in the menu
In [3]: x = p.data['WL']
In [4]: y = p.data['TOPUP BTEMP=330 UW=8']
In [5]: %pylab
In [6]: plot(x,y)

