==========================================================================
$Id: README 35757 2012-03-26 21:39:10Z mlevy@ucar.edu $
$URL: https://svn-ccsm-models.cgd.ucar.edu/tools/mapping/trunk_tags/mapping_121113b/check_maps/README $
==========================================================================


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

This directory contains a stand-alone utility to check previously-generated
mapping files. It will only run on bluefire because it requires the ESMF
library.

The source and destination masks are checked for consistency, both should be
between 0 and 1. Due to round-off error, a small tolerance is allowed. Further,
the tool maps 5 different files from the source grid to the destination grid:

Test 1 -- 2 + cos^2(theta)*cos(2*lambda)
Test 2 -- 2
Test 3 -- 2 + cos^2(theta)*cos(8*lambda)
Test 4 -- 2 + cos^2(theta)*cos(16*lambda)
Test 5 -- 2 + cos^2(theta)*cos(32*lambda)

Each function is also calculated directly on the destination grid, and the
global L1 and L2 errors are calculated. Each of the ten errors (L1 and L2 for
each of the 5 tests) is compared to a bound that comes from a set of 234
pre-existing mapping functions, and a failure notice will print out if any
error exceeds the given bound.

Area-averaged maps have an additional check for each test function to ensure
conservation. The area of each function is computed on both the source and
destination grid, and the difference must again be within a tolerance derived
from an ensemble of 150 pre-existing area-averaged maps. Additionally, the
smallest weight in the map must be greater than a small negative number while
the largest weight must be smaller than 1 plus a small positive number. (The
weights should all be between 0 and 1, inclusive, but a tolerance has been
included in the checks due to round-off error.)

=====
USAGE
=====

./check_maps.sh [OPTION]... FILELIST
Runs a modified version of the ESMF RegridWeightGenCheck program over files
listed in FILELIST

  --recompile, -rc  Force recompile (necessary to change verbose)
  --verbose, -v     Compile with verbose output (use with -rc)
  --clean, -c       Remove log / aux files generated by this script
  --help, -h        Output this usage information

Notes:
  1) For use on bluefire only!
  2) Need to set ESMFMKFILE=/contrib/esmf-5.2.0r-64-O/lib/esmf.mk or compilation
     will fail
  3) If -rc option is not enabled, -v flag is ignored and verbose / concise will
     depend on previous compilation