==========================================================================
$Id: README 40654 2012-09-29 21:53:03Z mlevy@ucar.edu $
$URL: https://svn-ccsm-models.cgd.ucar.edu/tools/mapping/trunk/gen_mapping_files/README $
==========================================================================


===============
ABOUT THIS TOOL
===============

This directory contains a shell script that uses ESMF's ESMF_RegridWeightGen
utility to generate a single mapping file from a specified source grid to
a specified destination grid.

After you use this script, it is recommended that you check the resulting
mapping file using the tool found in

../../check_maps/

See the README file in that directory for more details, but basically the tool
is based on ESMF's ESMF_RegridWeightGenCheck untility. It maps 5 different
global patterns from source to destination and compares the errors; for any
conservative maps, it also checks for conservation.

=======================
USAGE: INTERACTIVE MODE
=======================

create_ESMF_map.sh
  --filesrc|-fsrc  input source grid_filename (required)
  --filedst|-fdst  input destination grid_filename (required)
  --namesrc|-nsrc  output source name in mapping file (required)
  --namedst|-ndst  output destination name in mapping file (required)
  --maptype|-map   type of mapping [aave|blin|bilin|patc|nearestdtos|neareststod] (required)
  [ --typesrc|tsrc ] [regional|global]
  [ --typedst|tdst ] [regional|global]
  [ --pass2esmf ]    ["options"]
  [ --batch|-b ]
  [ --clm_name ]
  [ --serial ]
  [ -mach|--machine ] [machine_name]
  [ --large_file|-big ]
  [ --help|-h ]
  [ -v ]

where
 --filesrc (or -fsrc)
   SCRIP grid format source filename (full pathname)
 --filedst (or -fdst)
   SCRIP grid format destination filename (full pathname)
 --namesrc (or -nsrc) and --namesrc (or -nsrc) will result in the
   following mapping files
     namesrc_TO_namedst_maptype.cdate.nc

 --typesrc (or -tsrc)
   source grid type,  valid values are regional or global
   default is global
 --typedst (or -tdst)
   destination grid type, valid values are regional or global
   default is global
 --pass2esmf
   pass options directly to the ESMF tool.
 --clm_name
   Use the CLM naming convention
 --serial
   Load the serial ESMF tools rather than the parallel tools
   (necessary for mapping grids with a single point).
 --machine (or -mach)
   Name of the machine you are running on. Currently supports cheyenne,
   geyser, caldera, and pronghorn. Note that this script will
   determine the machine name automatically from the hostfile command.
 -d
   toggle debug-only
 --help or -h
   displays this help message

You can also set the following env variables:
  ESMFBIN_PATH - Path to ESMF binaries
                 (Leave unset on cheyenne/caldera/geyser/pronghorn
                 and the tool will be loaded from modules)
  MPIEXEC ------ Name of mpirun executable
                 (ignored if --serial, which is default on cheyenne
                 login nodes

