models/lnd/clm/tools/mksurfdata/README		Mar/13/2008

The routines in this directory create a surface dataset.
The output grid is read in from the input namelist and
can correspond to either a global or regional grid (depending
on the setting of the namelist variables mksrf_gridtype).
The input grid file should have been generated by the 
mkgriddata tool.

The following steps provide a method to create the executable
and generate the surface dataset:

0) export your input data

1) cd to this directory 

2) run gmake

NOTE: In order to successfully build, some source files are required from
      other clm src directories. See the Filepath for the expected path of
      required files.

      By default code compiles 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  

3) create namelist file :
   (sample namelists are: mksurfdata.namelist, mksurfdata.regional, or mksurfdata.singlept)

    ! ======================================================================
    ! Read input namelist
    ! ======================================
    ! Must specify settings for the output grid:
    ! ======================================
    !    mksrf_fgrid -- Grid dataset
    ! ======================================
    ! Must specify settings for input high resolution datafiles
    ! ======================================
    !    mksrf_ffrac ---- land fraction and land mask dataset
    !    mksrf_fglacier - Glacier dataset
    !    mksrf_flai ----- Leaf Area Index dataset
    !    mksrf_flanwat -- Land water dataset
    !    mksrf_forganic - Organic soil carbon dataset
    !    mksrf_fmax ----- Max fractional saturated area dataset
    !    mksrf_fsoicol -- Soil color dataset
    !    mksrf_fsoitex -- Soil texture dataset
    !    mksrf_ftopo ---- Topography dataset (for glacier multiple elevation classes)
    !                     (and for limiting urban areas)
    !    mksrf_furban --- Urban dataset
    !    mksrf_fvegtyp -- PFT vegetation type dataset
    !    mksrf_fvocef  -- Volatile Organic Compund Emission Factor dataset
    ! ======================================
    ! Optionally specify setting for:
    ! ======================================
    !    all_urban --------- If entire area is urban
    !    mksrf_firrig ------ Irrigation dataset
    !    mksrf_fdynuse ----- ASCII text file that lists the
    !    mksrf_gridtype ---- Type of grid (default is 'global')
    !    mksrf_gridnm ------ Name of output grid resolution
    !    nglcec ------------ If you want to change the number of Glacier elevation classes
    !    outnc_double ------ If output should be in double precision
    !    outnc_large_files - If output should be in NetCDF large file format
    ! ==================
    ! ======================================================================

   make sure the datasets in the namelist correspond to the full path of where
   you downloaded your input datasets.

   Sample namelists (using /fs/cgd/csm as the root location where inputdata was exported) are:

   mksurfdata.namelist   ----- Standard global dataset
   mksurfdata.regional   ----- Regional dataset 
                               (assumes you ran the regional namelist for the mkgridata tool)
   mksurfdata.singlept   ----- Dataset for a single point
                               (assumes you ran the singlept namelist for the mkgridata tool)


4) run code (e.g.):
        mksurfdata < mksurfdata.namelist >&! mksurfdat.out

5) move (and rename if appropriate) generated surface dataset
   to /fis/cgd/csm/inputdata/lnd/clm/surfdata, etc.

6) Alturnative to steps 3-5: run the mksurfdata.pl script to get files for the 
   standard resolutions (already in the namelist_defaults_clm.xml file).

Important files:

  mksurfdata.pl ------------- Script to run mksurfdata for many resolutions and simulation years.
  Makefile ------------------ GNU makefile
  Srcfiles ------------------ List of source files needed (includes files outside this directory)
  Filepath ------------------ Filepath location to source files needed
  misc.h -------------------- CPP preprocess file required by outside source code
  preproc.h ----------------- CPP preprocess file required by outside source code
  mksurfdata.pftdyn --------- Sample namelist to create a dynamic PFT surface dataset (PFT changes in time)
  mksurfdata.namelist ------- Sample global grid namelist
  mksurfdata.regional ------- Sample regional grid namelist
  mksurfdata.singlept ------- Sample single-point namelist
  mksurfdata.globalirrig ---- Sample namelist also outputting global irrigation data

Lists of input files for range of dates historical or future scenarios:

  pftdyn_hist_simyr1850-2005.txt --- List of historical input PFT files from 1850 to 2005
  pftdyn_rcp2.6_simyr1850-2100.txt - List of rcp=2.6 input PFT files from 1850 to 2100
  pftdyn_rcp4.5_simyr1850-2100.txt - List of rcp=4.5 input PFT files from 1850 to 2100
  pftdyn_rcp6.0_simyr1850-2100.txt - List of rcp=6.0 input PFT files from 1850 to 2100
  pftdyn_rcp8.5_simyr1850-2100.txt - List of rcp=8.5 input PFT files from 1850 to 2100
  pftdyn_hist_simyr1850.txt -------- Input PFT file for year 1850
  pftdyn_hist_simyr2000.txt -------- Input PFT file for year 2000

(Historical period from 1850-2005 datafiles all point to the historical files, while
 the future scenarios 2006-2100 are the scenario datasets)

