Incorporate weight_gen program. (#677)

Add new "weight_gen" utility from the global-workflow.
Include new consistency test, and scripts to run
the utility on supported machines. Update doxygen and
'readthedocs' documentation.

Fixes #673.

README.md

@@ -27,6 +27,7 @@ grid_tools | R. J. Purser (regional_esg_grid), Tom Black/Ben Blake (shave.fd), G
 orog_mask_tools | Ning Wang, Jordan Alpert, Shan Sun and Ning Wang
 sfc_climo_gen | George Gayno
 vcoord_gen | Fanglin Yang, Mark Iredell
+weight_gen | George Gayno
 
 UFS_UTILS Code managers: George Gayno, Kyle Gerheiser, Jeff Beck, Larissa Reames
 
@@ -76,51 +77,36 @@ make install
 
 ## Contents
 
-The UFS_UTILS package contains the following utilities (under the sorc
-directory):
-- chgres_cube
-- cpld_gridgen
-- emcsfc_ice_blend
-- emcsfc_snow2mdl
-- fre-nctools
-- fvcom_tools
-- gblevents
-- global_cycle
-- grid_tools
-- orog_mask_tools
-- sfc_climo_gen
-- vcoord_gen
-
-The reg_tests directory contains the consistency test code.
-
-The fix directory is where we set links to directories containing
+The `sorc` directory contains the source code.
+
+The `reg_tests` directory contains the consistency test code.
+
+The `fix` directory contains links to directories containing
 large, static data files used by UFS_UTILS programs.
 
-The tests directory contains unit tests.
+The `tests` directory contains unit tests.
 
-The ush directory contains scripts to run UFS_UTILS programs.  Most
+The `ush` directory contains scripts to run UFS_UTILS programs.  Most
 are called from driver scripts.
 
-The util directory contains utility scripts to create coldstart
-initial conditions for GFS parallels, and to run the vertical
-coordinate generator.
+The `util` directory contains utility scripts.
 
-The parm directory contains variable mapping parameter tables used by
+The `parm` directory contains variable mapping parameter tables used by
 the chgres_cube program.
 
-The driver_scripts directory contains high-level driver scripts to
+The `driver_scripts` directory contains high-level driver scripts to
 create a model grid on officially supported HPC platforms.
 
-The modulefiles directory contains modules loaded when building
+The `modulefiles` directory contains modules loaded when building
 UFS_UTILS on supported HPC platforms.  They are also loaded at runtime
 by utility and consistency test scripts.
 
-The docs directory contains the control file for the doxygen
+The `docs` directory contains the control file for the doxygen
 documentation build, as well as some markdown files which are part of
 the documentation. It also contains (in the source subdirectory) the
 ReadTheDocs documentation files.
 
-The cmake directory contains CMake package find utilities, and utilities to
+The `cmake` directory contains CMake package find utilities, and utilities to
 run units tests on some supported HPC platforms.
 
 ## References

docs/source/ufs_utils.rst

@@ -600,3 +600,51 @@ Run script
 ----------
 
 To run, use script ./util/vcoord_gen/run.sh
+
+weight_gen   
+==========
+
+Introduction
+------------
+
+Creates ESMF 'scrip' files for gaussian grids. 
+
+Code structure
+--------------
+
+Location of the source code: ./sorc/weight_gen.fd.
+
+Program inputs
+--------------
+
+The global FV3 grid resolution from standard output. Valid choices are:
+
+     * C48
+     * C96
+     * C128
+     * C192
+     * C384
+     * C768
+     * C1152
+     * C3072
+
+Program outputs
+---------------
+
+Two gaussian grid 'scrip' files in NetCDF format. One includes two extra rows for the poles.
+
+     * C48  => 192x94 and 192x96 gaussian files
+     * C96  => 384x192 and 384x194 gaussian files
+     * C128 => 512x256 and 512x258 gaussian files
+     * C192 => 768x384 and 768x386 gaussian files
+     * C384 => 1536x768 and 1536x770 gaussian files
+     * C768 => 3072x1536 and 3072x1538 gaussian files
+     * C1152 => 4608x2304 and 4608x2406 gaussian files
+     * C3072 => 12288x6144 and 12288x6146 gaussian files
+
+Files contain center and corner point latitude and longitudes.
+
+Run script
+----------
+
+To run, use the machine-dependent script under ./util/weight_gen

docs/user_guide.md

@@ -76,3 +76,6 @@ https://github.com/ufs-community/UFS_UTILS.
 - <a href="cpld_gridgen/index.html">cpld_gridgen</a> - Utility to 
   create the Fix and IC files for the S2SW and S2S applications 
 
+- <a href="weight_gen/index.html">weight_gen</a> - Utility to 
+  create gaussian grid ESMF 'scrip' files for use in creating
+  ESMF interpolation weight files.

reg_tests/rt.sh

@@ -114,7 +114,7 @@ for dir in snow2mdl global_cycle chgres_cube grid_gen; do
     cd ..
 done
 
-for dir in ice_blend; do
+for dir in weight_gen ice_blend; do
     cd $dir
     if [[ $target == "hera" ]] || [[ $target == "jet" ]] || [[ $target == "orion" ]] || [[ $target == "s4" ]] ; then
         sbatch -A ${PROJECT_CODE} ./driver.$target.sh
@@ -140,7 +140,7 @@ echo "Commit hash: ${current_hash}" >> ${WORK_DIR}/reg_test_results.txt
 echo "" >> ${WORK_DIR}/reg_test_results.txt
 
 success=true
-for dir in cpld_gridgen chgres_cube grid_gen global_cycle ice_blend snow2mdl; do
+for dir in weight_gen cpld_gridgen chgres_cube grid_gen global_cycle ice_blend snow2mdl; do
     if grep -qi "FAILED" ${dir}/summary.log; then
         success=false
         echo "${dir} consistency tests FAILED" >> ${WORK_DIR}/reg_test_results.txt

reg_tests/weight_gen/driver.hera.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+#-----------------------------------------------------------------------------
+#
+# Run weight_gen consistency test on Hera.
+#
+# Set $DATA to your working directory.  Set the project code (SBATCH -A)
+# and queue (SBATCH -q) as appropriate.
+#
+# Invoke the script as follows:  sbatch $script
+#
+# Log output is placed in consistency.log.  A summary is
+# placed in summary.log
+#
+# The test fails when its output does not match the baseline files
+# as determined by the 'nccmp' command.  The baseline file is
+# stored in HOMEreg.
+#
+#-----------------------------------------------------------------------------
+
+#SBATCH -J weight_gen
+#SBATCH -A fv3-cpu
+#SBATCH --open-mode=truncate
+#SBATCH -o consistency.log
+#SBATCH -e consistency.log
+#SBATCH --ntasks=1
+#SBATCH -q debug
+#SBATCH -t 00:03:00
+
+set -x
+
+compiler=${compiler:-"intel"}
+
+source ../../sorc/machine-setup.sh > /dev/null 2>&1
+module use ../../modulefiles
+module load build.$target.$compiler
+module list
+
+export DATA="${WORK_DIR:-/scratch2/NCEPDEV/stmp1/$LOGNAME}"
+export DATA="${DATA}/reg-tests/weight_gen"
+
+#-----------------------------------------------------------------------------
+# Should not have to change anything below.
+#-----------------------------------------------------------------------------
+
+export UPDATE_BASELINE="FALSE"
+#export UPDATE_BASELINE="TRUE"
+
+if [ "$UPDATE_BASELINE" = "TRUE" ]; then
+  source ../get_hash.sh
+fi
+
+export HOMEreg=/scratch1/NCEPDEV/nems/role.ufsutils/ufs_utils/reg_tests/weight_gen
+export HOMEufs=$PWD/../..
+
+./weight_gen.sh
+
+exit 0

reg_tests/weight_gen/driver.jet.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+
+#-----------------------------------------------------------------------------
+#
+# Run weight_gen consistency test on Jet.
+#
+# Set $DATA to your working directory.  Set the project code 
+# (SBATCH --account) as appropriate.
+#
+# Invoke the script as follows:  sbatch $script
+#
+# Log output is placed in consistency.log.  A summary is
+# placed in summary.log
+#
+# The test fails when its output does not match the baseline files
+# as determined by the 'nccmp' command.  The baseline file is
+# stored in HOMEreg.
+#
+#-----------------------------------------------------------------------------
+
+#SBATCH --nodes=1
+#SBATCH --partition=sjet
+#SBATCH --time 0:01
+#SBATCH --account=emcda
+#SBATCH --job-name=weight_gen
+#SBATCH -o consistency.log
+#SBATCH -e consistency.log
+
+set -x
+
+compiler=${compiler:-"intel"}
+
+source ../../sorc/machine-setup.sh > /dev/null 2>&1
+module use ../../modulefiles
+module load build.$target.$compiler
+module list
+
+export DATA="${WORK_DIR:-/lfs4/HFIP/emcda/$LOGNAME/stmp}"
+export DATA="${DATA}/reg-tests/weight_gen"
+
+#-----------------------------------------------------------------------------
+# Should not have to change anything below.
+#-----------------------------------------------------------------------------
+
+export UPDATE_BASELINE="FALSE"
+#export UPDATE_BASELINE="TRUE"
+
+if [ "$UPDATE_BASELINE" = "TRUE" ]; then
+  source ../get_hash.sh
+fi
+
+export HOMEreg=/lfs4/HFIP/hfv3gfs/emc.nemspara/role.ufsutils/ufs_utils/reg_tests/weight_gen
+export HOMEufs=$PWD/../..
+
+./weight_gen.sh
+
+exit 0

reg_tests/weight_gen/driver.orion.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+#-----------------------------------------------------------------------------
+#
+# Run weight_gen consistency test on Orion.
+#
+# Set $DATA to your working directory.  Set the project code (SBATCH -A)
+# and queue (SBATCH -q) as appropriate.
+#
+# Invoke the script as follows:  sbatch $script
+#
+# Log output is placed in consistency.log.  A summary is
+# placed in summary.log
+#
+# The test fails when its output does not match the baseline files
+# as determined by the 'nccmp' command.  The baseline file is
+# stored in HOMEreg.
+#
+#-----------------------------------------------------------------------------
+
+#SBATCH -J weight_gen
+#SBATCH -A fv3-cpu
+#SBATCH --open-mode=truncate
+#SBATCH -o consistency.log
+#SBATCH -e consistency.log
+#SBATCH --ntasks=1
+#SBATCH -q debug
+#SBATCH -t 00:03:00
+
+set -x
+
+compiler=${compiler:-"intel"}
+
+source ../../sorc/machine-setup.sh > /dev/null 2>&1
+module use ../../modulefiles
+module load build.$target.$compiler
+module list
+
+export DATA="${WORK_DIR:-/work/noaa/stmp/$LOGNAME}"
+export DATA="${DATA}/reg-tests/weight_gen"
+
+#-----------------------------------------------------------------------------
+# Should not have to change anything below.
+#-----------------------------------------------------------------------------
+
+export UPDATE_BASELINE="FALSE"
+#export UPDATE_BASELINE="TRUE"
+
+if [ "$UPDATE_BASELINE" = "TRUE" ]; then
+  source ../get_hash.sh
+fi
+
+export HOMEreg=/work/noaa/nems/role-nems/ufs_utils/reg_tests/weight_gen
+export HOMEufs=$PWD/../..
+
+./weight_gen.sh
+
+exit 0

reg_tests/weight_gen/driver.wcoss2.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+
+#-----------------------------------------------------------------------------
+#
+# Run weight_gen consistency test on WCOSS2.
+#
+# Set $DATA to your working directory.  Set the project code (PBS -A)
+# and queue (PBS -q) as appropriate.
+#
+# Invoke the script as follows:  qsub $script
+#
+# Log output is placed in consistency.log.  A summary is
+# placed in summary.log
+#
+# The test fails when its output does not match the baseline files
+# as determined by the 'nccmp' command.  The baseline file is
+# stored in HOMEreg.
+#
+#-----------------------------------------------------------------------------
+
+#PBS -l walltime=00:02:00
+#PBS -o consistency.log
+#PBS -e consistency.log
+#PBS -N wgt_regt
+#PBS -q debug
+#PBS -A GFS-DEV
+#PBS -l select=1:ncpus=1:mem=250MB
+
+set -x
+
+cd $PBS_O_WORKDIR
+
+compiler=${compiler:-"intel"}
+
+source ../../sorc/machine-setup.sh > /dev/null 2>&1
+module use ../../modulefiles
+module load build.$target.$compiler
+module list
+
+export DATA="${WORK_DIR:-/lfs/h2/emc/stmp/$LOGNAME}"
+export DATA="${DATA}/reg-tests/weight_gen"
+
+#-----------------------------------------------------------------------------
+# Should not have to change anything below.
+#-----------------------------------------------------------------------------
+
+export UPDATE_BASELINE="FALSE"
+#export UPDATE_BASELINE="TRUE"
+
+if [ "$UPDATE_BASELINE" = "TRUE" ]; then
+  source ../get_hash.sh
+fi
+
+export HOMEreg=/lfs/h2/emc/global/noscrub/George.Gayno/ufs_utils.git/reg_tests/weight_gen
+export HOMEufs=$PBS_O_WORKDIR/../..
+
+export NCCMP=/lfs/h2/emc/global/noscrub/George.Gayno/util/nccmp/nccmp-1.8.5.0/src/nccmp
+
+./weight_gen.sh
+
+exit 0