models/lnd/clm/tools/README					May/25/2011

CLM tools for analysis of CLM history files -- or for creation or
modification of CLM input files.
	
I.  General directory structure:

	interpinic ------- Interpolate initial datasets to a different resolution. (has optimized and OMP option)
        mkdatadomain ----- Create data model domain datasets from clm datasets.
	mkgriddata ------- Create grid datasets.
	mksurfdata ------- Create surface datasets.
	cprnc ------------ Compare output history files. (stand-alone tool)
        ncl_scripts ------ NCL post or pre processing scripts.

II. Notes on the build system for each of the above tools:

    Each tool (except cprnc as it's stand-alone) has the following files:

	README ------- Specific help for using the specific tool and help on specific files in that directory.
	Filepath ----- List of directories needed to build the tool (some files in ../src directories are required).
	Makefile ----- GNU Makefile to build the tool (these are almost identical between tools.
        Mkdepends ---- Tool for Makefile to figure out code dependencies
	Srcfiles ----- List of source files that are needed.

    cprnc is a tool shared by other CESM components as it's a general tool for comparing
    NetCDF files with a time coordinate. As such it has it's own standalone Makefile 
    and is a little different than the other tools.

    The tools have copies of files from other directories -- see the README.filecopies
    file for more information on this.

    Tools also have files with the directory name followed by: namelist, runoptions, regional, or singlept
    these are sample namelists:

	<directory>.namelist ------ Namelist to create a global file.
	<directory>.regional ------ Namelist to create a regional file.
	<directory>.singlept ------ Namelist to create a single-point file.
	<directory>.runoptions ---- Command line options to use the given tool.

    These files are also used by the test scripts to test the tools (see the
    README.testing) file.

    NOTE: Be sure to change the path of the datasets references by these namelists to point to where you
    have untarred your datasets.

    To build:

	cd <directory>
        setenv INC_NETCDF <path-to-NetCDF-include-files>
        setenv LIB_NETCDF <path-to-NetCDF-library-files>
	gmake

    The process will create a file called "Depends" which has the dependencies
    for the build of each file on other files.

      By default some codes (mkdatadomain and mkgridata) are compiled non-optimized 
      so that you can use the debugger, and with bounds-checking, and float trapping on. 
      To speed up do the following...

   gmake OPT=TRUE  (by default already on for interpinic and mksurfdata)

      Also some of the tools allow for OpenMP shared memory parallelism 
      (such as interpinic and mksurfdata) with

   gmake SMP=TRUE


    To run a program with a namelist:

        ./program < namelist

    To get help on running a program with command line options (cprnc and interpinic):

        ./program

    To run a program built with SMP=TRUE:

        setenv OMP_NUM_THREADS=<number_of_threads_to_use>

        run normally as above
