================================================================================
SVN $Id$
SVN $URL$
===============================================================================

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

The src/ directory here contains F90 files and a Makefile to produce the
runoff_map executable, which reads in a runoff file and an ocean grid file
and outputs a map from the former to the latter:

1) Computes an initial nearest neighbor mapping from the rof grid cells to 
   active ocean grid cells.
2) Computes a smoothing matrix on the ocean grid.
3) The two matrices are multipled together to generate the final mapping file.

====================
HOW TO USE THIS TOOL
====================

1) Build (in the src/ directory)
2) Setup a namelist file (runoff.nml)
3) Run ./runoff_map

============
HOW TO BUILD
============

Prior to building, you must make sure $CCSMROOT is set.

$ cd src
$ $CCSMROOT/scripts/ccsm_utils/Machines/configure -mach [machine name]
$ ./build.csh

Note: in the second step, replace [machine name] with the machine you are
building on. Also, some machines (such as janus) have dedicated build nodes,
so you might need to SSH to another node before the 'build.csh' step.

==================================
COMMON BUILD / RUN ISSUES ON JANUS
==================================

1) As hinted at in the "How to Build" section, you can not build on the login
  nodes on janus. If you see the error

  ld: cannot find -lrdmacm
  ld: cannot find -libverbs

  you are still on the headnode and need to SSH to node0001.

2) At present, the netCDF libraries available on janus have all been built
   with mpif90, which means that everything linking with netCDF must also
   be built in parallel. Unfortunately, this means you can not run map_fields
   from the head node -- you either need to push it through the queue or just
   run it from node0001. Running on node0001 is easier, but to run from the
   queue, edit map_field.janus.run (both the header info to set the requested
   walltime and the body of the script to point to the correct mapping file and
   name the domain files appropriately), and then run

   qsub map_field.janus.run

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

The namelist file must be called "runoff_map.nml".  That name is hardwired
into the executable.

The namelist looks like this

  &input_nml
   gridtype     = 'scrip'
   file_roff    = '/glade/p/cesm/cseg/mapping/grids/wr50a_090614.nc'
   file_ocn     = '/glade/p/cesm/cseg/mapping/grids/ar9v4_100920.nc'
   file_nn      = 'map_wr50a_ar9v4_nn.nc '
   file_smooth  = 'map_ar9v4_ar9v4_smoother.nc '
   file_new     = 'map_wr50a_to_ar9v4_e1000r300_130507.nc'
   title        = 'runoff map: wr50a -> ar9v4, smoothed '
   eFold        = 1000000.0
   rMax         =  300000.0
   step1 = .true.
   step2 = .false.
   step3 = .false.
  /

where

Input grid files:
  file_roff =   an ascii rdirc file OR an obs rtm file OR a script grid file
  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
  file_ocn  =  a scrip ocean grid file.

Input parameters:
  eFold  = smoothing eFold distance in meters
  rMax   = maximum radius of effect in meters

Settings:
  title = ascii string to add to mapping files
  step1 = computes nearest neighbor map
  step2 = computes smooth map
  step3 = multiple two maps together

Output fields:
  file_nn     = nearest neighbor mapping file
  file_smooth = smoother mapping file
  file_new    = combined file


==========
HOW TO RUN
==========

Execute the binary ./runoff_map (again, this will read the runoff_map.nml
namelist file - see bove section for tips on creating the file)