Mapping/update runoff to ocn

tools/mapping/gen_mapping_files/runoff_to_ocn/INSTALL

@@ -2,17 +2,16 @@
 HOW TO BUILD
 ============
 
-Prior to building, you must make sure $CIMEROOT is set.
-
 (1) $ cd src
-(2) $ $CIMEROOT/tools/configure -mach [machine name]
-(3) Bash users:
-    $ . .env_mach_specific.sh
-    csh users:
-    $ source .env_mach_specific.csh
-(4) $ gmake
+(2) $ ../../../../configure --macros-format Makefile --mpilib mpi-serial
+Bash users:
+(3) $ (. .env_mach_specific.sh ; gmake)
+csh users:
+(3) $ (source .env_mach_specific.csh ; gmake)
 
-Note: in the second step, replace [machine name] with the machine you are
-building on. Also, some machines have dedicated build nodes, so you might need
-to SSH to another node before the 'gmake' step.
+Note: in the second step, you may need to include "--machine [machine name]",
+where [machine name] is the name of the machine you are building on. In most
+cases configure can figure that out on its own, but if you get an error that is
+the first fix to try. Also, some machines have dedicated build nodes, so you
+might need to SSH to another node before the 'gmake' step.
 

tools/mapping/gen_mapping_files/runoff_to_ocn/README

@@ -1,86 +1,162 @@
-===============
-ABOUT THIS TOOL
-===============
+=================
+ABOUT THESE TOOLS
+=================
 
-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:
+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.
 
-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 THESE TOOLS
+======================
 
-====================
-HOW TO USE THIS TOOL
-====================
+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:
 
-1) Build (in the src/ directory)
-2) Setup a namelist file (runoff_map.nml)
-3) Run ./runoff_map
+$ ./runoff_map < [namelist file]
 
-============
-HOW TO BUILD
-============
+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 INSTALL file in this directory
+See the "MERGE MAPPING FILES" section below for more details.
 
 ====================
 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 '
+&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 = .false.
-   step3 = .false.
-  /
-
-where
-
-Input grid files:
-  file_roff =   an ascii rdirc file OR an obs rtm file OR a scrip 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 (must contain grid_area along with typical
-       scrip grid variables)
-  file_ocn  =  a scrip ocean grid file (must contain grid_area along with
-    typical scrip grid variables)
-
-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 above section for tips on creating the file)
+   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 srouce 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 desireable 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
+     variable can be used to point to an ocean grid 
+   * The optional file_ocn_coast_mask file allows mapping to a subset of ocean
+     cells, presumably the coastal cells); 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.
 

tools/mapping/gen_mapping_files/runoff_to_ocn/map_r05_to_gx1v7_nnsm_e1000r300.nml

@@ -0,0 +1,16 @@
+&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.
+/

tools/mapping/gen_mapping_files/runoff_to_ocn/map_r05_to_gx3v7_nnsm_e1000r500.nml

@@ -0,0 +1,16 @@
+&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/gx3v7_120309.nc'
+   file_ocn_coastal_mask = '/glade/p/cesm/cseg/mapping/grids/gx3v7_coast_161214.nc'
+   file_nn      = 'map_r05_to_gx3v7_coast_nearestdtos_170324.nc'
+   file_smooth  = 'map_gx3v7_coast_to_gx3v7_sm_e1000r500_170324.nc'
+   file_new     = 'map_r05_to_gx3v7_nnsm_e1000r500_170324.nc'
+   title        = 'runoff map: r05 -> gx3v7, nearest neighbor and smoothed'
+   eFold        = 1000000.0
+   rMax         =  500000.0
+   restrict_smooth_src_to_nn_dest = .true.
+   step1 = .true.
+   step2 = .true.
+   step3 = .true.
+/

tools/mapping/gen_mapping_files/runoff_to_ocn/map_rx1_to_gx1v7_nnsm_e1000r300.nml

@@ -0,0 +1,16 @@
+&input_nml
+   gridtype     = 'obs'
+   file_roff    = '/glade/p/cesm/cseg/inputdata/lnd/dlnd7/RX1/runoff.daitren.annual.090225.nc'
+   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_rx1_to_gx1v7_coast_nearestdtos_170324.nc'
+   file_smooth  = 'map_gx1v7_coast_to_gx1v7_sm_e1000r300_170324a.nc'
+   file_new     = 'map_rx1_to_gx1v7_nnsm_e1000r300_170324.nc'
+   title        = 'runoff map: rx1 -> gx1v7, nearest neighbor and smoothed'
+   eFold        = 1000000.0
+   rMax         =  300000.0
+   restrict_smooth_src_to_nn_dest = .true.
+   step1 = .true.
+   step2 = .true.
+   step3 = .true.
+/

tools/mapping/gen_mapping_files/runoff_to_ocn/map_rx1_to_gx3v7_nnsm_e1000r500.nml

@@ -0,0 +1,16 @@
+&input_nml
+   gridtype     = 'obs'
+   file_roff    = '/glade/p/cesm/cseg/inputdata/lnd/dlnd7/RX1/runoff.daitren.annual.090225.nc'
+   file_ocn     = '/glade/p/cesm/cseg/mapping/grids/gx3v7_120309.nc'
+   file_ocn_coastal_mask = '/glade/p/cesm/cseg/mapping/grids/gx3v7_coast_161214.nc'
+   file_nn      = 'map_rx1_to_gx3v7_coast_nearestdtos_170324.nc'
+   file_smooth  = 'map_gx3v7_coast_to_gx3v7_sm_e1000r500_170324a.nc'
+   file_new     = 'map_rx1_to_gx3v7_nnsm_e1000r500_170324.nc'
+   title        = 'runoff map: rx1 -> gx3v7, nearest neighbor and smoothed'
+   eFold        = 1000000.0
+   rMax         =  500000.0
+   restrict_smooth_src_to_nn_dest = .true.
+   step1 = .true.
+   step2 = .true.
+   step3 = .true.
+/

tools/mapping/gen_mapping_files/runoff_to_ocn/runoff_map_wr50a_ar9v4.nml → tools/mapping/gen_mapping_files/runoff_to_ocn/map_wr50a_to_ar9v4_nnsm_e1000r300.nml

@@ -1,15 +1,14 @@
-  &input_nml
+&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_to_ar9v4_nn_130508.nc '
-   file_smooth  = 'map_ar9v4_to_ar9v4_sm_e1000r300_130508.nc '
-   file_new     = 'map_wr50a_to_ar9v4_nnsm_e1000r300_130508.nc'
-   title        = 'runoff map: wr50a -> ar9v4, nearest neighbor and smoothed '
+   file_nn      = 'map_wr50a_to_ar9v4_nearestdtos_170324.nc'
+   file_smooth  = 'map_ar9v4_to_ar9v4_sm_e1000r300_170324.nc'
+   file_new     = 'map_wr50a_to_ar9v4_nnsm_e1000r300_170324.nc'
+   title        = 'runoff map: wr50a -> ar9v4, nearest neighbor and smoothed'
    eFold        = 1000000.0
    rMax         =  300000.0
    step1 = .true.
    step2 = .true.
    step3 = .true.
-
-  /
+/

tools/mapping/gen_mapping_files/runoff_to_ocn/map_wr50a_to_gx3v7_nnsm_e1000r300.nml

@@ -0,0 +1,14 @@
+&input_nml
+   gridtype     = 'scrip'
+   file_roff    = '/glade/p/cesm/cseg/mapping/grids/wr50a_090614.nc'
+   file_ocn     = '/glade/p/cesm/cseg/mapping/grids/gx3v7_120309.nc'
+   file_nn      = 'map_wr50a_to_gx3v7_nearestdtos_170324.nc'
+   file_smooth  = 'map_gx3v7_to_gx3v7_sm_e1000r300_170324.nc'
+   file_new     = 'map_wr50a_to_gx3v7_nnsm_e1000r300_170324.nc'
+   title        = 'runoff map: wr50a -> gx3v7, nearest neighbor and smoothed'
+   eFold        = 1000000.0
+   rMax         =  300000.0
+   step1 = .true.
+   step2 = .true.
+   step3 = .true.
+/

tools/mapping/gen_mapping_files/runoff_to_ocn/maps/.gitignore

@@ -0,0 +1 @@
+*.nc