$CTSMROOT/tools/mkmapdata/README		Jun/08/2018

The routines in this directory create a mapping dataset from
SCRIP grid files to map from one grid to another. These mapping files
are used by either CLM or mksurfdata_map to regrid from one resolution
to another.

The script uses ESMF and requires that ESMF be built and the path
for ESMF binary files (using the program ESMF_RegridWeightGen) 
be given as input to the script. You need to build at least
two versions, one with mpiuni and one with mpi. Both versions
also need to be built with NetCDF rather than the default
IO version.

Currently uses: ESMF7.1.0r

Do the following for help with the different options to the script...

   ./mkmapdata.sh -help

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

0) Background tasks you only have to do once

 a.)  Export the input SCRIP grid files for the resolutions you'll need

  Most of these files are on the Subversion inputdata server at...

  https://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/lnd/clm2/mappingdata/grids/

  Supported machines also have a copy on the CESM DIN_LOC_ROOT location
  for that machine.

 b.) Obtain and build the versions of ESMF required for this script

The version needs to support ESMF_RegridWeightGen and support the
options passed to it in the mkmapdata.sh script. As such it needs
to be built with NetCDF. You also need to build at least one
version with mpiuni and one with an mpi library. You also need
a version that supports the options: --netcdf4, --64bit_offset
and --src_type UGRID.

   http://www.earthsystemmodeling.org/

You may need more than one version to do everything above. On cheyenne
we use ESMF7.1.0r.

The version of NetCDF used with ESMF needs to be version 4.1 or higher
and compiled with the NetCDF4 file format enabled (with HDF5 compression).
That will enable the --netcdf4 and --64bit_offset options to be used.

1) cd to this directory 

2) Create map dataset(s)
   Option A.)  Use mkmapdata.sh directly
   run script(e.g.): (see header of mkmapdata.sh for other environment that can be set)

   Example for standard resolutions
        ./mkmapdata.sh -r 10x15
   Example for non-standard resolutions where you provide an input SCRIP grid file.
        ./mkmapdata.sh -f <SCRIP_gridfile>

   Option B.) Alternatively, run regridbatch.sh to run mkmapdata.sh for a bunch of 
        different resolutions.

   Option C.) Alternatively, run mknoocnmap.pl to create a single-point/regional
   map for an area without ocean.

   ./mknoocnmap.pl -help      # for help on this script

3) move (and rename if appropriate) generated map datasets
   to $DIN_LOC_ROOT/lnd/clm/mappingdata/maps, etc.


Important files:

  regridbatch.sh ------- Script to run mkmapdata.sh for many resolutions on cheyenne
  regridgeyser.sh ------ Script to run mkmapdata.sh for many resolutions on geyser
  mvNimport.sh --------- Script to copy and import mapping files in for many resolutions
  mkmapdata.sh --------- Script to create mapping datasets for a given resolution

  mknoocnmap.pl -------- Script to create unity mapping dataset for single-point
                         or regional studies over land-only (no ocean).
  mkunitymap.ncl ------- NCL script to create a unity map -- ran by above script
  rmdups.ncl ----------- NCL script to remove duplicate mapping points