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

This directory contains a stand-alone utility to check previously-generated
mapping files. It requires the ESMF libary to build -- see below for details
on how to build.

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.)

=====
BUILD
=====

To compile this tool, you need to have the ESMFMKFILE environment variable set.
The easiest way to do that is to load the ESMF modules. On cheyenne, caldera,
geyser, or pronghorn you must already have the intel module loaded. Then load the
version of ESMF you want to use (as of May 2018, the most recent version on the
NCAR machines is 7.0.0):

Caldera, Geyser, Pronghorn:
$ module load esmf
$ module load esmf-7.0.0-ncdfio-uni-O

Cheyenne:
$ module load esmf_libs/7.0.0
$ module load esmf-7.0.0-ncdfio-uni-O

This will set ESMFMKFILE. With this variable set, enter the src/ directory and
run gmake

$ cd src
$ gmake [VERBOSE=TRUE]

VERBOSE=TRUE turns on some extra diagnostic output and is optional.

Back in this directory, you should now have an executable file named
ESMF_RegridWeightGenCheck.

Note that at this time, the tool only works in serial mode (building with the
mpi-enabled version of the ESMF makefile leads to a segmentation fault when
running with more than one MPI task).

=====
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 cheyenne, geyser, caldera, or pronghorn only!
  2) Need to set ESMFMKFILE (see comments in Makefile) or compilation will fail
  3) If -rc option is not enabled, -v flag is ignored and verbose / concise will depend on previous compilation