README:  Version 2012-09-17

Suggestions, comments, and corrections are welcome (mail to
kmanning@ucar.edu).

I've tried to do some careful documentation in the code of
simple_driver.F, in order to be as clear as possible about what I
think is going on.  I've tried describe particularly the input to and
output from SFLX.  Please let me know of any necessary corrections.

Let me know, as well, if what I think is going on is not what should
be happening.

Source code:

    The main driver code is "simple_driver.F".  I've tried to be very
    clear in documenting the code and program flow in the main
    routine.  The Noah LSM code is in file "module_sf_noahlsm.F"; the
    main interface to this code is the call to subroutine SFLX in the
    driver.  Other source-code files handle utility codes and details
    of the I/O procedures, and are not really intended for public
    consumption.  But feel free to hack away at those codes if you've
    got some ideas.

Note on NetCDF libraries:

    This code requires that the NetCDF libraries are installed on
    your machine.  In general, the code provided here should be
    compiled with the same compiler used to create the NetCDF
    libraries.  

Note on the graphics code:

    This distribution includes a plotting program, written with the
    NCAR-Graphics low-level utilities, for creating simple plots of the
    1d driver output.  This is located in subdirectory "graphics".
    This graphics code requires that the NCAR-Graphics libraries are
    installed on your machine.  Other libraries associated with
    NCAR-Graphics tend to be pretty specific to your installation.

    The graphics code is set up to compare two NetCDF output files to
    the observations found in the file "bondville.val".  It is
    pretty bare-bones stuff, and probably does not do what you want it
    to.  Don't expect much of it.  Right now, you are basically on
    your own for any more sophisticated graphical display of model
    output.

To compile:

    Edit the user_build_options to choose compiler, compiler options,
    libraries, etc.  Adjust compiler options and library paths as 
    necessary from the default settings provided in user_build_options.

    Set an environment variable NCARG_ROOT to the top-level path
    for NCAR-Graphics libraries and include files.

    Invoke "make" to compile.  This should create executable file
    "driver.exe".  Note that the Makefile included here is set up
    for the GNU make utility.  If "make" does not work on your
    system, try "gmake".  To compile the graphics code, change to 
    the "graphihcs" directory and invoke "make".

To run:

    execute:
      "driver.exe bondville.dat"

Input file:

    The forcing data and initial data are combined in a single file,
    in this case called "bondville.dat".  A namelist section in 
    that file describes site parameters and initial conditions. The
    namelist is followed by records of forcing fields.

Output file:

    The program is set up to create both ASCII and NetCDF
    output. Output will go to files "OUTPUT.txt" and "OUTPUT.nc".  At
    the driver level, the code to add or remove variables in the
    output files is easily adaptable.  See (in the driver code) the
    calls to subroutines output_levels and output_var.

    If iteration over the same year of data is activated, output files
    will be called OUPUT.<xxxx>.txt and OUTPUT.<xxxx>.nc, where <xxxx>
    is the four-digit iteration number (starting from zero).

To create some simple graphical output:

    To try the graphics code, change to the "graphics" directory, and
    execute:
       "graphics.exe -namelist graphics.namelist ../OUTPUT.nc ../OUTPUT.nc".
    The program creates an NCAR-Graphics gmeta file called "compare.cgm"
    Some tuning of the graphics is possible via options in the 
    "graphics.namelist" file.

    The program is set up to compare two files; if one file is named
    twice, lines are overwritten so you effectively get the results of
    that one file.

    To see a few simple options to the graphics program, execute
    "graphics.exe -help"