==========================================================================
$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|patc] (required)
  [ --typesrc|tsrc ] [regional|global]
  [ --typedst|tdst ] [regional|global]
  [ --batch|-b ]
  [ --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
 --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
 -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 
                 (default is /contrib/esmf-5.2.0r-64-O/bin)
  MPIEXEC ------ Name of mpirun executable
                 (default is mpirun.lsf)
  REGRID_PROC -- Number of MPI processors to use
                 (default is 8)

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

Currently, batch mode is only set up for bluefire. This uses the file
regridbatch.bluefire.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.bluefire.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.bluefire.sh

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

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