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 optimized so it's reasonably fast. If you want
      to use the debugger, with bounds-checking, and float trapping on do the 
      following:

   gmake OPT=FALSE

See Also: See the models/lnd/clm/tools/README file for notes about setting
          the path for NetCDF and running with shared-memory parallelism.

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

