=================
ABOUT THESE TOOLS
=================

The CIME coupler can map two different types of runoff to the ocean: liquid
(river) and ice; these tools are provided to help generate both maps. The src/
directory contains F90 files and a Makefile to produce the runoff_map executable
(see the INSTALL file for more details), and run_merge_mapping_files.sh is a
bash script that provides a clean interface to an NCL script.

======================
HOW TO USE THESE TOOLS
======================

1) Build (see the INSTALL file in this directory for details)
2) Setup a namelist file (see the "NAMELIST FILE FORMAT" section below or any
   runoff_map_*.nml for an example)
3) Run with the following command:

$ ./runoff_map < [namelist file]

4) For some ocean models, it is useful to use combine two liquid runoff maps
   so that river runoff sent to the open ocean is treated differently than
   runoff sent to a marginal sea. This step is generally not needed for ice
   runoff, but two maps can be merged with the following command:
   
$ ./run_merge_mapping_files.sh

See the "MERGE MAPPING FILES" section below for more details.

====================
NAMELIST FILE FORMAT
====================

The namelist looks like this

&input_nml
   gridtype     = 'rtm'
   file_roff    = '/glade/p/cesm/cseg/inputdata/lnd/clm2/rtmdata/rdirc.05.061026'
   file_ocn     = '/glade/p/cesm/cseg/mapping/grids/gx1v7_151008.nc'
   file_ocn_coastal_mask = '/glade/p/cesm/cseg/mapping/grids/gx1v7_coast_170322.nc'
   file_nn      = 'map_r05_to_gx1v7_coast_nearestdtos_170324.nc'
   file_smooth  = 'map_gx1v7_coast_to_gx1v7_sm_e1000r300_170324.nc'
   file_new     = 'map_r05_to_gx1v7_nnsm_e1000r300_170324.nc'
   title        = 'runoff map: r05 -> gx1v7, nearest neighbor and smoothed'
   eFold        = 1000000.0
   rMax         =  300000.0
   restrict_smooth_src_to_nn_dest = .true.
   step1 = .true.
   step2 = .true.
   step3 = .true.
/

Where the variables can be divided into four categories:

1. Input grid files
  gridtype =  type of file_roff file, "rtm" or "obs" or "scrip"
              * rtm is a 720 x 360 grid ascii file
              * obs is a netcdf file with xc, yc, xv, yv, mask and area variable names
              * scrip is a scrip type grid file (must contain grid_area along with
                typical scrip grid variables)
  file_roff  =  an ascii rdirc file OR an obs rtm file OR a scrip grid file
  file_ocn   =  a scrip ocean grid file where the mask is 1 for all ocean grid
                cells (see note 3 below)
  file_ocn_coastal_mask  =  a scrip ocean grid file where the mask is only 1
                            for coastal grid cells (see note 3 below)

NOTES:
1) gridtype, file_roff, and file_ocn MUST be specified in the namelist
2) if file_ocn_coastal_mask is not specified, file_ocn will be used
3) The file_ocn and file_ocn_coast_mask must be standard scrip grid files that
   include the cell area

2. Input parameters
  eFold = smoothing eFold distance in meters (default: 1000000)
  rMax  = maximum radius of effect in meters (default: 300000)

3. Settings
  title                 = ascii string to add to mapping files (default: 'unset')
  restrict_smooth_src_to_nn_dest = option to limit the source points for step2 to
                                   just the points that get mapped to in step1; if
                                   false, use all ocean points in
                                   file_ocn_coastal_mask instead (default: .true.)
  step1                 = computes nearest neighbor map (default: .true.)
  step2                 = computes smooth map (default: .true.)
  step3                 = multiply two maps together (default: .true.)

4. Output fields
  file_nn     = nearest neighbor mapping file (default: 'nn.nc')
  file_smooth = smoother mapping file (default: 'smooth.nc')
  file_new    = combined file (default: 'nnsm.nc')

========================
WHAT THESE TOOLS PROVIDE
========================

The runoff_map executable generates three maps:

1) A nearest neighbor mapping from the rof grid to the ocean grid.
   * For river runoff, it may be desireble to limit the destination grid so that
     runoff only enters at coastal points. The optional file_ocn_coast_mask
     variable in the namelist allows you to specify two ocean grid files; one for
     the full ocean and one for just the coast. Typically this should not be
     specified for ice runoff.
2) A smoothing map from the ocean grid to the ocean grid.
   * If file_ocn_coast_mask was specified, this maps from the coastal ocean to
     the open ocean; otherwise it maps from the ocean grid onto itself.
   * By default, the source domain of this map is only cells that appear as
     destination cells of the nearest neighbor map. Optionally, one can
     set restrict_smooth_src_to_nn_dest = .false. and generate a map that maps
     from all ocean cells, even if they are not destination cells of the nearest
     neighbor map. Enabling this map will not change the resulting map, but will
     allow the resulting map to be reused if you are generating multiple maps
     from different runoff grids onto the same ocean grid.
   * If file_ocn_coast_mask is not specified, be aware that setting
     restrict_smooth_src_to_nn_dest = .false. will take significantly longer
     (and generate a much larger file) than leaving it .true.
3) The product of the previous two maps.

The ncl/ directory contains an NCL script to compute a fourth map (which is
actually a combination of two existing maps):

4) Map (1) from above for rof grid cells that map into the open ocean, or map
   (3) for the rof grid cells that map into a marginal sea.
   * This is only necessary if runoff should be treated differently in the open
     ocean than in marginal seas, otherwise map (3) from above should be used
     and this step is not needed.

===================
MERGE MAPPING FILES
===================

The run_merge_mapping_files.sh script requires four arguments:

$ ./run_merge_mapping_files --map_in_oo MAP_IN_OO_FNAME     \
                            --map_in_ms MAP_IN_MS_FNAME     \
                            --region_mask REGION_MASK_FNAME \
                            --map_out MAP_OUT_FNAME         \
                            [-h -v]

  -h,--help     show this message
  -v,--verbose  echo file names back to screen before running NCL script
  --map_in_oo MAP_IN_OO_FNAME
                mapping file containing map to open ocean points
  --map_in_ms MAP_IN_MS_FNAME
                mapping file containing map to marginal sea points
  --region_mask REGION_MASK_FNAME
                POP region mask file (to specify open ocean vs marginal sea)
  --map_out MAP_OUT_FNAME
                output file

A couple of useful notes:
* MAP_IN_OO_FNAME and MAP_IN_MS_FNAME are typically maps (1) and (3),
  respectively, from the "WHAT THESE TOOLS PROVIDE" section.
* REGION_MASK_FNAME is a binary file (written with big endian convention)
  containing one integer per grid cell -- a positive number represents a region
  in open ocean, a negative number represents a region in a marginal sea, and a
  zero is land.

