==========================================================================
$Id: README 45821 2013-04-10 22:21:06Z [email protected] $
$URL: https://svn-ccsm-models.cgd.ucar.edu/tools/mapping/trunk_tags/mapping_141106/gen_mapping_files/README $
==========================================================================


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

This directory contains a shell script that uses ESMF's ESMF_RegridWeightGen
utility to generate a suite of mapping files to map between specified grid
files. It does not call the ESMF tool directly, rather the script

gen_ESMF_mapping_file/create_ESMF_map.sh

is used as a wrapper. If you only want to generate a single mapping file, you
should use that script (see the README file in the gen_ESMF_mapping_file/
directory for details).

To use this tool, specify some (or all) of the following: atmosphere grid (atm),
ocean grid (ocn), land grid (lnd), and runoff grid (rtm). Depending on what
grids are used as input, the following maps will be generated:

 * atm -> ocn: conservative, bilinear, patch
 * ocn -> atm: conservative, bilinear
 * atm -> lnd: conservative, bilinear
 * lnd -> atm: conservative
 * ocn -> lnd: conservative
 * lnd -> rtm: conservative
 * rtm -> lnd: conservative

If you specify a runoff grid but not a land grid, the utility will use the
atmosphere grid instead. If you want to make a rtm -> ocn mapping file, you
should use the tool found in

runoff_to_ocn/

The conservative ocn to atm mapping file should be used as input to gen_domain,
which is located in

../gen_domain_files/ (and must be built in gen_domain_files/src/)

If the ocean and atm grids are identical then the mapping file will simply be
unity and the atm fraction will be one minus the ocean fraction.

All maps generated will be checked for global consistency by 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. Note that this tool must be
built prior to running gen_cesm_maps.sh, unless you use the --nogridcheck or
--recompile option. Skipping the grid check is not recommended.

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

gen_cesm_maps.sh
  --fileatm|-fatm  input atm_grid_filename
  --fileocn|-focn  input ocn_grid_filename
  --filelnd|-flnd  input lnd_grid_filename
  --filertm|-frtm  input rtm_grid_filename
  --fileglc|-fglc  input glc_grid_filename
  --nameocn|-nocn  output ocn_name in mapping file
  --nameatm|-natm  output atm_name in mapping file
  --namelnd|-nlnd  output lnd_name in mapping file
  --namertm|-nrtm  output rtm_name in mapping file
  --nameglc|-nglc  output glc_name in mapping file
  [ --typeocn|tocn ] [regional|global]
  [ --typeatm|tatm ] [regional|global]
  [ --nogridcheck ]
  [ --batch|-b ]
  [ --help|-h ]
  [ -v ]

where
 --fileatm (or -fatm)
   SCRIP grid format atmosphere filename (full pathname)
 --fileocn (or -focn)
   SCRIP grid format ocean filename (full pathname)
 --filelnd (or -flnd)
   SCRIP grid format land filename (full pathname), must be global
 --filertm (or -frtm)
   SCRIP grid format runoff filename (full pathname)
 --fileglc (or -fglc)
   SCRIP grid format glc filename (full pathname), assumed to be regional
 --nameatm (or -natm)
   Shortname to use for atm in mapping filename
 --nameocn (or -nocn)
   Shortname to use for ocn in mapping filename
 --namelnd (or -nlnd)
   Shortname to use for lnd in mapping filename
 --namertm (or -nrtm)
   Shortname to use for rtm in mapping filename
 --nameglc (or -nglc)
   Shortname to use for glc in mapping filename
 --typeocn (or -tocn)
   ocean grid type,  valid values are regional or global
   default is global
 --typeatm (or -tatm)
   atm grid type, valid values are regional or global
   default is global
   value must be global if -frtm and -nrtm are specified
 --nogridcheck
   By default, script will run consistency check on new
   maps; this flag disables these checks
 --serial
   Run the ESMF tools in serial rather than parallel
 -rc
   Pass the "--recompile" flag to the ESMF tool
   (Only necessary if nothing has been built in ../check_maps/)
 --help or -h
   displays this help message

Note: if rtm or glc are specified and lnd is not, then this tool will
      assume lnd and atm are on the same grid.

You can also set the following env variables:
  ESMFBIN_PATH - Path to ESMF binaries
                 (Known machines will load tools from modules)
  MPIEXEC ------ Name of mpirun executable
                 (currently tools only run in serial due to module issues)