source: trunk/NEMOGCM/TOOLS/WEIGHTS/README @ 4832

nocsSCRIP v1.1 03/11/2010
-------------------------

Author: NOCS NEMO Team
Contacts: Steven Alderson (sga@noc.soton.ac.uk)
          Andrew Coward   (acc@noc.soton.ac.uk)

Disclaimer

This directory contains software for generating and manipulating interpolation
weights for use with the Interpolation On the Fly (IOF) option in NEMO
v3 onwards.  The utilities rely heavily on the Spherical Coordinate Remapping
and Interpolation Package (SCRIP) which is freely available from Los Alamos
(see copyright file). We make no claim to authorship of those parts of the
SCRIP package we have used and included with this distribution.

Unless otherwise indicated, all other software has been authored by an
employee or employees of the National Oceanography Centre, Southampton, UK
(NOCS).  NOCS operates as a collaboration between the Natural Environment
Research Council (NERC) and the University of Southampton.  The public may
copy and use this software without charge, provided that this Notice and any
statement of authorship are reproduced on all copies.  Neither NERC nor the
University makes any warranty, express or implied, or assumes any liability
or responsibility for the use of this software.

Introduction

The IOF option enables forced ocean runs without the need to provide surface
boundary data on the nemo grid. Atmospheric data are kept on their original
grid(s) which typically have a coarser resolution than the ocean grid. IOF
supports multiple source (atmospheric) grids and two interpolation methods
(bilinear and bicubic).  Different combinations of source grid and method can
be selected for each variable.  IOF is also compatible with AGRIF; allowing
AGRIF nests to be used without the need to provide separate forcing data
(only a separate set of weights fields).  Operational details are provided
in the SBC chapter of the NEMO reference manual.

Please note that the methods described here assume that the forcing datasets
are unmasked. Where the original sources are masked it is the users'
responsibility to ensure that an unmasked set is produced on the source
grid with appropriate oceanic values in previously masked locations. This
is particularly important for atmospheric variables which experience step
changes at the land-sea boundary. For these, care must be taken to avoid
contaminating oceanic values.

The software is divided into several sub-directories:

                         ./
                          |
     +-------------+--------------+--------------+
  SCRIP1.4      nocsutil         src            bin

SCRIP1.4 contains the unmodified copy (apart from compression of two sample netcdf
files) of SCRIP version 1.4 from Los Alamos. 
(http://climate.lanl.gov/Software/SCRIP).

The bin directory contains python script freeform.py.
This is run to reformat the code for use within the NEMO 3.3 fcm framework.
It creates and populates a directory called 'src' with copied and modified versions
of the SCRIP library routines (and derived programs from the nocsutil directory).  
Changes are described in the src/CHANGES file.
This script has already been run and only needs to be re-executed if SCRIP is updated.

The src directory also contains the three programs used to generate a weights file.
The three programs are:

scripgrid.exe (scripgrid.F90) which creates two grid description files suitable for
input to the scrip package. 

scrip.exe (scrip.F90) which takes these descriptions and generates the required
weights in the standard SCRIP format. This program is a version of the SCRIP
program: scrip.f which has been modified to accept the name of its namelist
file on the command line.

scripshape.exe (scripshape.F90) which takes the output from scrip and rearranges
the fields into a series of 2D fields more suited for input into NEMO using
the iom_get routine.

All three FORTRAN90 programs read domain information from their respective
netCDF input files and dynamically allocate internal storage. They are
thus independent of the target configuration and have been successfully
tested with both ORCA2 and ORCA025 grids. Their suitably for use with larger
grids has not been tested but should only be subject to limitations of
the operating system and the memory available to the processing element.

A separate tar file is available containing test data.
This comprises an ORCA2 coordinates file and sample DFS4.1 input field that
can be used for testing. Reference weights files generated using the two
example namelists provided are located in its refout subdirectory.

Installation is by use of the maketools script.
E.g. change to the NEMOGCM/TOOLS directory and type:

./maketools -help

and, for example:

./maketools -m gfortran_linux -n WEIGHTS


Example Use
-----------

  cd data
  ../scripgrid.exe  namelist_reshape_bilin    (creates remap_data_grid.nc 
                                                and remap_nemo_grid.nc)
  ../scrip.exe      namelist_reshape_bilin    (creates data_nemo_bilin.nc)

  ../scripshape.exe namelist_reshape_bilin    (creates reshape_orca2_bilinear.nc)
  
[Note that because the gfortran compiler does not understand the iargc function 
and getarg subroutine calls, command line namelist names can only be supplied if
symbol ARGC is defined during compilation (eg add '#define ARGC' to the top of 
the relevant program).  If not, the program asks for the name instead during execution.]

Only the final output file is required for use with NEMO but the intermediate
files can be checked against the examples in the test data (available separately).

For bicubic mapping only scrip and scripshape need to be rerun (because the grid_inputs namelist
entries are identical in the two namelist files, see Controls section below):
 
  ../scrip.exe namelist_reshape_bicubic       (creates data_nemo_bicubic.nc)

  ../scripshape.exe namelist_reshape_bicubic  (creates reshape_orca2_bicubic.nc)

Controls
--------

The SCRIP derived utilities use SCRIP-style namelists to control their
operation.  In the example above the same named file is used for both but within that
file are two separate namelists:

&grid_inputs
    input_file = './snow_1m_TRP_1958.nc'
    nemo_file = 'coordinates.nc'
    datagrid_file = 'remap_data_grid.nc'
    nemogrid_file = 'remap_nemo_grid.nc'
    method = 'regular'
    input_lon = 'lon'
    input_lat = 'lat'
    nemo_lon = 'glamt'
    nemo_lat = 'gphit'
    nemo_mask = 'none'
    nemo_mask_value = 10
    input_mask = 'none'
    input_mask_value = 10
/

which is used by scripgrid, and:

&remap_inputs
    num_maps = 1
    grid1_file = 'remap_data_grid.nc'
    grid2_file = 'remap_nemo_grid.nc'
    interp_file1 = 'data_nemo_bilin.nc'
    interp_file2 = 'nemo_data_bilin.nc'
    map1_name = 'data to nemo bilin Mapping'
    map2_name = 'nemo to data bilin Mapping'
    map_method = 'bilinear'
    normalize_opt = 'frac'
    output_opt = 'scrip'
    restrict_type = 'latitude'
    num_srch_bins = 90
    luse_grid1_area = .false.
    luse_grid2_area = .false.
/

which is used by scrip.

scripshape also reads information from a namelist:

&shape_inputs
    interp_file = 'data_nemo_bilin.nc'
    output_file = 'weights_bilin.nc'
    ew_wrap     = 0
/

scripgrid.exe
-------------

scripgrid accesses the named files and coordinate data in order to produce
the grid centre and corner locations required by scrip. In the example given,
a file called 'coordinates.nc' must exist in the current directory. This is
used by scripgrid as a nemo coordinates file and the correct corner
locations appropriate to the named grid centres are obtained (i.e. since
glamt is named, glamf and gphif will be used to provide corner coordinates).
The nemo file need not be called 'coordinates.nc' (e.g. '1_coordinates.nc' instead),
but must have longitude and latitude variables which start with the four 
characters 'gphi' and 'glam' respectively.
"input_file" file must contain at least one variable on a grid whose axes are
described by the netcdf coordinate variables named in input_lon and input_lat.
The program produces two grid description files, one corresponding to each
input file, for use by the scrip program to calculate weights required to
go from one to the other and back again.

This step is independent of the mapping method (e.g. bilinear or bicubic)
and so only one set of remap_data_grid.nc and remap_nemo_grid.nc files needs
to be produced for each pair of source and destination grids.

scrip.exe
---------

scrip takes the output files from scripgrid and creates a file of weights
to use to interpolate between the two grids described. The example given
only requests 1 map (from data to nemo); setting num_maps=2 will provide
the reverse weights if required.
 
 - num_maps is either 1 or 2 depending on whether the reverse 
    transformation is required 

 - grid1_file, grid2_file: two remap grid files are required 
    as output by scripgrid

 - interp_file1, interp_file2: one or two interp_file names are 
    then supplied; these hold the weights to convert one grid to another

 - map1_name, map2_name: the map_name variables are just descriptive

 - map_method: can be 'bilinear' or 'bicubic'

 - normalize_opt: should usually be 'frac' or else the user needs to do  
    this scaling manually (this seems to the case for fractional ice cover)

 - output_opt may be supplied and set to either 'scrip' or 'ncar-csm'

 - restrict_type: should be 'latitude' or 'latlon' in which case 
    num_srch_bins only are used in one or two directions

 - use_grid_area fields override the scrip calculation of area in 
    case the model gets slightly different answers, but the area needs 
    to be supplied in the input files

A conservative mapping scheme exists but is not yet working with NEMO grids.
See the scrip package documentation for more details of these parameters.
(http://climate.lanl.gov/Software/SCRIP/SCRIPusers.pdf)

scripshape.exe
--------------

scripshape takes the output from scrip (e.g. data_nemo_bilin.nc ) and
rearranges the source and destination indices and associated weights into
sets of 2D fields each spanning the nemo grid. Each set is associated with
each node involved in the interpolation scheme.  Thus for a bilinear mapping
the weights file required by the IOF option includes the following fields:

  double src01(lat, lon) ;   double dst01(lat, lon) ;   double wgt01(lat, lon) ;
  double src02(lat, lon) ;   double dst02(lat, lon) ;   double wgt02(lat, lon) ;
  double src03(lat, lon) ;   double dst03(lat, lon) ;   double wgt03(lat, lon) ;
  double src04(lat, lon) ;   double dst04(lat, lon) ;   double wgt04(lat, lon) ;

For a bicubic mapping the required fields are:

  double src01(lat, lon) ;   double dst01(lat, lon) ;   double wgt01(lat, lon) ;
  double src02(lat, lon) ;   double dst02(lat, lon) ;   double wgt02(lat, lon) ;
  double src03(lat, lon) ;   double dst03(lat, lon) ;   double wgt03(lat, lon) ;
  double src04(lat, lon) ;   double dst04(lat, lon) ;   double wgt04(lat, lon) ;
  double src05(lat, lon) ;   double dst05(lat, lon) ;   double wgt05(lat, lon) ;
  double src06(lat, lon) ;   double dst06(lat, lon) ;   double wgt06(lat, lon) ;
  double src07(lat, lon) ;   double dst07(lat, lon) ;   double wgt07(lat, lon) ;
  double src08(lat, lon) ;   double dst08(lat, lon) ;   double wgt08(lat, lon) ;
  double src09(lat, lon) ;   double dst09(lat, lon) ;   double wgt09(lat, lon) ;
  double src10(lat, lon) ;   double dst10(lat, lon) ;   double wgt10(lat, lon) ;
  double src11(lat, lon) ;   double dst11(lat, lon) ;   double wgt11(lat, lon) ;
  double src12(lat, lon) ;   double dst12(lat, lon) ;   double wgt12(lat, lon) ;
  double src13(lat, lon) ;   double dst13(lat, lon) ;   double wgt13(lat, lon) ;
  double src14(lat, lon) ;   double dst14(lat, lon) ;   double wgt14(lat, lon) ;
  double src15(lat, lon) ;   double dst15(lat, lon) ;   double wgt15(lat, lon) ;
  double src16(lat, lon) ;   double dst16(lat, lon) ;   double wgt16(lat, lon) ;

This program also adds an attribute to the weights file for use by the fld_interp
routine in fldread.F90.  This tells the model about the east-west cyclicity of the source grid.
The value needs to be supplied in the scripshape namelist via the variable ew_wrap.
It should have one of the values -1, 0, 1 or 2.  -1 means that the input grid is not
cyclic; 0 means that it is cyclic but with no overlapping columns; and a value greater
than zero represents the number of columns that overlap.  In fact it only has an effect 
when using bicubic interpolation in which the model needs to know which additional columns
have to be read in to correctly calculate gradient values.
The weights file produced by scripshape is ready for use in NEMO. This file
needs to by placed in the nemo working directory and needs to be named in the
appropriate SBC namelist entry (e.g. namsbc_clio, namsbc_flux or namsbc_core).

scripinterp.exe
---------------

Take data on an input grid and interpolate to the nemo grid using the weights
calculated by the scrip program.
Method
Two namelists are used for configuration, eg

&interp_inputs
    input_file = "../data/wsx_av.nc"
    interp_file = "data_nemo_bilin.nc"
    input_name = "wsx"
    input_start = 1,1,1,1
    input_stride = 1,1,1,1
    input_stop = 0,0,0,1
    input_vars = 'time'
/

&interp_outputs
    output_file = "taux_1m.nc"
    output_mode = "create"
    output_dims = 'x', 'y', 'time_counter'
    output_scaling = "sozotaux|1.0", "time_counter|86400.0"
    output_name = 'sozotaux'
    output_lon = 'x'
    output_lat = 'y'
    output_vars = 'time_counter'
    output_attributes = 'time_counter|units|seconds since 1995-00-00 00:00:00',
                        'time_counter|calendar|noleap',
                        'sozotaux|units|N/m2'
/

This program just multiplies by weights and sums over each contributing point,
and then formats the output correctly for the model.