================================================================================
SVN $Id: README 2891 2007-01-12 23:24:31Z kauff $
SVN $URL: https://svn-ccsm-models.cgd.ucar.edu/tools/mapping/gen_runoffmap/trunk/README $
===============================================================================

           How to create a runoff map for CCSM3

----------------------------------------------------------------------
 Step 0: generate initial scrip map
----------------------------------------------------------------------

   use scrip to generated a conservative (area avg) map: runoff -> ocn

   notes: 
   - runoff can be masked, ocn must not be masked (or have mask=1 everywhere).
     This will result in some runoff being assigned to lnd points on the ocn grid.
     This will be corrected in step 2.
   - scrip ignores the mask of the 2nd grid specified in it's namelist (grid2_file).
     Put ocn domain file as the 2nd grid specified in script namelist (grid2_file)
     then it's mask will be ignored and ocn will be unmasked
   - it is strongly encouraged that the runoff and ocn domain files used 
     as input to scrip be located in the standard ccsm grids directory:
     ncar-scd:/fis/cgd/cseg/csm/mapping/grids
     and that the global attributes of any resulting netCDF mapping files
     document the names and locations of these grids
   - it is strongly encouraged that the user name & file create date
     be put into the global attributes of any resulting netCDF mapping files
   - The code is one single program, but by modifying the main.F90 code, 
     one can break the code into several steps: (1),(2),(3a),(3b)
     This involves changing "true" to "false" in one or more of...
	logical,parameter :: step1  = .true.
	logical,parameter :: step2  = .true.
	logical,parameter :: step3a = .true.
	logical,parameter :: step3b = .true.
     Why do this?  The code takes 4.25 hours to run on a bluesky 32-way node and 
     could possibly exceed a 6hr wall-clock limit when using fewer processors.

----------------------------------------------------------------------
 Step 1: correct initial scrip map
----------------------------------------------------------------------

   1a) correct original scrip map (relocate runoff over lnd to ocn)
   1b) sort this corrected map

   input : file_orig = 'map_r05_to_gx1v4.nc '
   output: file_corr = 'map_a.nc '

   timings (bluesky 2007) 
   1a) 15s
   1b) 2sec

----------------------------------------------------------------------
 Step 2: create spatial smoothing map
----------------------------------------------------------------------

   2a) create smoothing map
   2b) sort this smoothing map
    
   input : eFold       = 1000000.0  <- default nml value
   input : rMax        =  500000.0  <- default nml value
   input : file_corr   = 'map_a.nc '
   output: file_smooth = 'map_smoother.nc '

   timings (bluesky 2007):
   2a) 45min
   2b) 10sec

----------------------------------------------------------------------
 Step 3: apply spatial smoothing to corrected map (final step)
----------------------------------------------------------------------

   3a) do matrix-matrix multiply
   3b) sort this smoothed/correct map

   3a input : file_corr     = 'map_a.nc '
   3a input : file_smooth   = 'map_smoother.nc '
   3a output: file_unsorted = 'map_b.nc '

   3b input:  file_unsorted = 'map_b.nc '
   3b output: file_new      = 'map_r05_to_gx1v4_e1000r500_yymmdd.nc 

   timings (bluesky 2007):
   3a) 3.5hrs (using 32 OMP threads -- scales well)
   3b) 1.5min (using 32 OMP threads)

