==========================================================================
$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.
 --batch (or -b)
   Toggles batch mode usage. If you want to run in batch mode
   you need to have a separate batch script for a supported machine
   that calls this script interactively - you cannot submit this
   script directly to the batch system
 --clm_name
   Use the CLM naming convention
 --serial
   For yellowstone batch jobs only! 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 yellowstone,
   geyser, caldera, and jaguar. Note that this script will determines 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 yellowstone and caldera and the tool
                 will be loaded from modules)
  MPIEXEC ------ Name of mpirun executable
                 (default is mpirun.lsf on yellowstone and caldera; if
                 you run interactively on yellowstone, mpi is not used)
  REGRID_PROC -- Number of MPI processors to use (jaguar only!)
                 (default is 8)

=================
USAGE: BATCH MODE
=================

Currently, batch mode is only set up for yellowstone. This uses the file
regridbatch.yellowstone.sh as a wrapper to create_ESMF_map.sh. Before submitting,
make sure you do the following:

(1) Modify the #BSUB lines at the top of regridbatch.yellowstone.sh. You need to
at least specify a project number; you may want to change some of the other
settings, too.

(2) Modify the variables in the section labeled "Set user-defined parameters
here". See the documentation for create_ESMF_map.sh above for more details on
the parameters that can be set here.

(3) Submit with:

bsub < regridbatch.yellowstone.sh

(4) Run the check_maps tool on the generated mapping file:

    out_file=*.nc
    ../../check_maps/check_map.sh ${out_file}