README:  Version 2008-04-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.  

    The top-level directory for the NetCDF installation
    should be specified in the environment variable "NETCDF".

Note on the graphics code:

    This distribution includes a plotting program, written with the
    NCAR-Graphics library utilities, for creating simple plots of the
    1d driver output.  This graphics code requires that the
    NCAR-Graphics libraries are installed on your machine.  If you do
    not have NCAR-Graphics, the graphics code will not compile, but
    the 1d drivers should still compile and work fine.  You will
    simply need to find some other way to display results.

    If NCAR-Graphics is installed on your machine, the top-level
    directory for the NCAR-Graphics installation should be specified
    in the environment variable "NCARG_ROOT".  This will
    probably be something like "/usr/local/ncarg", or even just
    "/usr/local"

    The graphics code is set up to make some comparisons to the
    observations, as found in the file "bondville.val"

    The graphics program "graphics_compare.F" is a very
    quick-and-dirty NCAR-Graphics program 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 Makefile to choose Fortran compiler.  Adjust compiler
    options as necessary from the default settings provided in the
    Makefile.

    Set an environment variable NETCDF to the path of the NetCDF
    installation directory consistent with your Fortran compiler.

    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 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.

To create some simple graphical output:

    execute "graphics.exe OUTPUT.nc"

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