source: branches/nemo_v3_3_beta/NEMOGCM/TOOLS/WEIGHTS/README @ 2352

Last change on this file since 2352 was 2352, checked in by sga, 10 years ago

NEMO branch nemo_v3_3_beta
Add NOCS tools based on SCRIP package for creating weights for interpolation on the fly
These now should build with the maketools script in the TOOLS directory using the same
architecture configuration file as the model (hopefully)

File size: 13.3 KB
Line 
1nocsSCRIP v1.1 03/11/2010
2-------------------------
3
4Author: NOCS NEMO Team
5Contacts: Steven Alderson (sga@noc.soton.ac.uk)
6          Andrew Coward   (acc@noc.soton.ac.uk)
7
8Disclaimer
9
10This directory contains software for generating and manipulating interpolation
11weights for use with the Interpolation On the Fly (IOF) option in NEMO
12v3 onwards.  The utilities rely heavily on the Spherical Coordinate Remapping
13and Interpolation Package (SCRIP) which is freely available from Los Alamos
14(see copyright file). We make no claim to authorship of those parts of the
15SCRIP package we have used and included with this distribution.
16
17Unless otherwise indicated, all other software has been authored by an
18employee or employees of the National Oceanography Centre, Southampton, UK
19(NOCS).  NOCS operates as a collaboration between the Natural Environment
20Research Council (NERC) and the University of Southampton.  The public may
21copy and use this software without charge, provided that this Notice and any
22statement of authorship are reproduced on all copies.  Neither NERC nor the
23University makes any warranty, express or implied, or assumes any liability
24or responsibility for the use of this software.
25
26Introduction
27
28The IOF option enables forced ocean runs without the need to provide surface
29boundary data on the nemo grid. Atmospheric data are kept on their original
30grid(s) which typically have a coarser resolution than the ocean grid. IOF
31supports multiple source (atmospheric) grids and two interpolation methods
32(bilinear and bicubic).  Different combinations of source grid and method can
33be selected for each variable.  IOF is also compatible with AGRIF; allowing
34AGRIF nests to be used without the need to provide separate forcing data
35(only a separate set of weights fields).  Operational details are provided
36in the SBC chapter of the NEMO reference manual.
37
38Please note that the methods described here assume that the forcing datasets
39are unmasked. Where the original sources are masked it is the users'
40responsibility to ensure that an unmasked set is produced on the source
41grid with appropriate oceanic values in previously masked locations. This
42is particularly important for atmospheric variables which experience step
43changes at the land-sea boundary. For these, care must be taken to avoid
44contaminating oceanic values.
45
46The software is divided into several sub-directories:
47
48                         ./
49                          |
50     +-------------+--------------+
51  SCRIP1.4      nocsutil         bin
52
53SCRIP1.4 contains the unmodified copy (apart from compression of two sample netcdf
54files) of SCRIP version 1.4 from Los Alamos.
55(http://climate.lanl.gov/Software/SCRIP).
56
57The bin directory contains python script freeform.py.
58This is run to reformat the code for use within the NEMO 3.3 FCm framework.
59It creates and populates a directory called 'src' with copied and modified versions
60of the SCRIP library routines.  Changes are described in the src/CHANGES file.
61This script has already been run and only needs to be re-executed if SCRIP is updated.
62
63The nocscrip directory contains the code for the three programs used to
64generate a weights file. These are:
65
66scripgrid.exe (scripgrid.F90) which creates two grid description files suitable for
67input to the scrip package.
68
69scrip.exe (scrip.F90) which takes these descriptions and generates the required
70weights in the standard SCRIP format. This program is a version of the SCRIP
71program: scrip.f which has been modified to accept the name of its namelist
72file on the command line.
73
74scripshape.exe (scripshape.F90) which takes the output from scrip and rearranges
75the fields into a series of 2D fields more suited for input into NEMO using
76the iom_get routine.
77
78All three FORTRAN90 programs read domain information from their respective
79netCDF input files and dynamically allocate internal storage. They are
80thus independent of the target configuration and have been successfully
81tested with both ORCA2 and ORCA025 grids. Their suitably for use with larger
82grids has not been tested but should only be subject to limitations of
83the operating system and the memory available to the processing element.
84
85A separate tar file is available containing test data.
86This comprises an ORCA2 coordinates file and sample DFS4.1 input field that
87can be used for testing. Reference weights files generated using the two
88example namelists provided are located in its refout subdirectory.
89
90Installation is by use of the makenemo script.
91
92Example Use
93-----------
94
95  cd data
96  scripgrid.exe namelist_reshape_bilin    (creates remap_data_grid.nc
97                                              and remap_nemo_grid.nc)
98  scrip.exe     namelist_reshape_bilin        (creates data_nemo_bilin.nc)
99
100  scripshape.exe data_nemo_bilin.nc reshape_orca2_bilinear.nc 
101                                             (creates reshape_orca2_bilinear.nc)
102 
103[Note that because the gfortran compiler does not understand the iargc function
104and getarg subroutine calls, command line namelist names can only be supplied if
105symbol ARGC is defined during compilation (eg add '#define ARGC' to the top of
106the relevant program).  If not, the program asks for the name instead during execution.]
107
108Only the final output file is required for use with NEMO but the intermediate
109files can be checked against the examples in the test data (available separately).
110
111For bicubic mapping only scrip and scripshape need to be rerun (because the grid_inputs namelist
112entries are identical in the two namelist files, see Controls section below):
113 
114  ../bin/scrip namelist_reshape_bicubic      (creates data_nemo_bicubic.nc)
115
116  ../bin/scripshape data_nemo_bicubic.nc reshape_orca2_bicubic.nc 
117                                             (creates reshape_orca2_bicubic.nc)
118
119Controls
120--------
121
122The SCRIP derived utilities use SCRIP-style namelists to control their
123operation.  In the example above the same named file is used for both but within that
124file are two separate namelists:
125
126&grid_inputs
127    input_file = './snow_1m_TRP_1958.nc'
128    nemo_file = 'coordinates.nc'
129    datagrid_file = 'remap_data_grid.nc'
130    nemogrid_file = 'remap_nemo_grid.nc'
131    method = 'regular'
132    input_lon = 'lon'
133    input_lat = 'lat'
134    nemo_lon = 'glamt'
135    nemo_lat = 'gphit'
136    nemo_mask = 'none'
137    nemo_mask_value = 10
138    input_mask = 'none'
139    input_mask_value = 10
140/
141
142which is used by scripgrid, and:
143
144&remap_inputs
145    num_maps = 1
146    grid1_file = 'remap_data_grid.nc'
147    grid2_file = 'remap_nemo_grid.nc'
148    interp_file1 = 'data_nemo_bilin.nc'
149    interp_file2 = 'nemo_data_bilin.nc'
150    map1_name = 'data to nemo bilin Mapping'
151    map2_name = 'nemo to data bilin Mapping'
152    map_method = 'bilinear'
153    normalize_opt = 'frac'
154    output_opt = 'scrip'
155    restrict_type = 'latitude'
156    num_srch_bins = 90
157    luse_grid1_area = .false.
158    luse_grid2_area = .false.
159/
160
161which is used by scrip.
162
163scripshape also reads information from a namelist:
164
165&shape_inputs
166    interp_file = 'data_nemo_bilin.nc'
167    output_file = 'weights_bilin.nc'
168    ew_wrap     = 0
169/
170
171scripgrid.exe
172-------------
173
174scripgrid accesses the named files and coordinate data in order to produce
175the grid centre and corner locations required by scrip. In the example given,
176a file called 'coordinates.nc' must exist in the current directory. This is
177recognised by scripgrid as a nemo coordinates file and the correct corner
178locations appropriate to the named grid centres are obtained (i.e. since
179glamt is named, glamf and gphif will be used to provide corner coordinates).
180"input_file" file must contain at least one variable on a grid whose axes are
181described by the netcdf coordinate variables named in input_lon and input_lat.
182The program produces two grid description files, one corresponding to each
183input file, for use by the scrip program to calculate weights required to
184go from one to the other and back again.
185
186This step is independent of the mapping method (e.g. bilinear or bicubic)
187and so only one set of remap_data_grid.nc and remap_nemo_grid.nc files needs
188to be produced for each pair of source and destination grids.
189
190scrip.exe
191---------
192
193scrip takes the output files from scripgrid and creates a file of weights
194to use to interpolate between the two grids described. The example given
195only requests 1 map (from data to nemo); setting num_maps=2 will provide
196the reverse weights if required.
197 
198 - num_maps is either 1 or 2 depending on whether the reverse
199    transformation is required
200
201 - grid1_file, grid2_file: two remap grid files are required
202    as output by scripgrid
203
204 - interp_file1, interp_file2: one or two interp_file names are
205    then supplied; these hold the weights to convert one grid to another
206
207 - map1_name, map2_name: the map_name variables are just descriptive
208
209 - map_method: can be 'bilinear' or 'bicubic'
210
211 - normalize_opt: should usually be 'frac' or else the user needs to do 
212    this scaling manually (this seems to the case for fractional ice cover)
213
214 - output_opt may be supplied and set to either 'scrip' or 'ncar-csm'
215
216 - restrict_type: should be 'latitude' or 'latlon' in which case
217    num_srch_bins only are used in one or two directions
218
219 - use_grid_area fields override the scrip calculation of area in
220    case the model gets slightly different answers, but the area needs
221    to be supplied in the input files
222
223A conservative mapping scheme exists but is not yet working with NEMO grids.
224See the scrip package documentation for more details of these parameters.
225(http://climate.lanl.gov/Software/SCRIP/SCRIPusers.pdf)
226
227scripshape.exe
228--------------
229
230scripshape takes the output from scrip (e.g. data_nemo_bilin.nc ) and
231rearranges the source and destination indices and associated weights into
232sets of 2D fields each spanning the nemo grid. Each set is associated with
233each node involved in the interpolation scheme.  Thus for a bilinear mapping
234the weights file required by the IOF option includes the following fields:
235
236  double src01(lat, lon) ;   double dst01(lat, lon) ;   double wgt01(lat, lon) ;
237  double src02(lat, lon) ;   double dst02(lat, lon) ;   double wgt02(lat, lon) ;
238  double src03(lat, lon) ;   double dst03(lat, lon) ;   double wgt03(lat, lon) ;
239  double src04(lat, lon) ;   double dst04(lat, lon) ;   double wgt04(lat, lon) ;
240
241For a bicubic mapping the required fields are:
242
243  double src01(lat, lon) ;   double dst01(lat, lon) ;   double wgt01(lat, lon) ;
244  double src02(lat, lon) ;   double dst02(lat, lon) ;   double wgt02(lat, lon) ;
245  double src03(lat, lon) ;   double dst03(lat, lon) ;   double wgt03(lat, lon) ;
246  double src04(lat, lon) ;   double dst04(lat, lon) ;   double wgt04(lat, lon) ;
247  double src05(lat, lon) ;   double dst05(lat, lon) ;   double wgt05(lat, lon) ;
248  double src06(lat, lon) ;   double dst06(lat, lon) ;   double wgt06(lat, lon) ;
249  double src07(lat, lon) ;   double dst07(lat, lon) ;   double wgt07(lat, lon) ;
250  double src08(lat, lon) ;   double dst08(lat, lon) ;   double wgt08(lat, lon) ;
251  double src09(lat, lon) ;   double dst09(lat, lon) ;   double wgt09(lat, lon) ;
252  double src10(lat, lon) ;   double dst10(lat, lon) ;   double wgt10(lat, lon) ;
253  double src11(lat, lon) ;   double dst11(lat, lon) ;   double wgt11(lat, lon) ;
254  double src12(lat, lon) ;   double dst12(lat, lon) ;   double wgt12(lat, lon) ;
255  double src13(lat, lon) ;   double dst13(lat, lon) ;   double wgt13(lat, lon) ;
256  double src14(lat, lon) ;   double dst14(lat, lon) ;   double wgt14(lat, lon) ;
257  double src15(lat, lon) ;   double dst15(lat, lon) ;   double wgt15(lat, lon) ;
258  double src16(lat, lon) ;   double dst16(lat, lon) ;   double wgt16(lat, lon) ;
259
260This program also adds an attribute to the weights file for use by the fld_interp
261routine in fldread.F90.  This tells the model about the east-west cyclicity of the source grid.
262The value needs to be supplied in the scripshape namelist via the variable ew_wrap.
263It should have one of the values -1, 0, 1 or 2.  -1 means that the input grid is not
264cyclic; 0 means that it is cyclic but with no overlapping columns; and a value greater
265than zero represents the number of columns that overlap.  In fact it only has an effect
266when using bicubic interpolation in which the model needs to know which additional columns
267have to be read in to correctly calculate gradient values.
268The weights file produced by scripshape is ready for use in NEMO. This file
269needs to by placed in the nemo working directory and needs to be named in the
270appropriate SBC namelist entry (e.g. namsbc_clio, namsbc_flux or namsbc_core).
271
272scripinterp.exe
273---------------
274
275Take data on an input grid and interpolate to the nemo grid using the weights
276calculated by the scrip program.
277Method
278Two namelists are used for configuration, eg
279
280&interp_inputs
281    input_file = "../data/wsx_av.nc"
282    interp_file = "data_nemo_bilin.nc"
283    input_name = "wsx"
284    input_start = 1,1,1,1
285    input_stride = 1,1,1,1
286    input_stop = 0,0,0,1
287    input_vars = 'time'
288/
289
290&interp_outputs
291    output_file = "taux_1m.nc"
292    output_mode = "create"
293    output_dims = 'x', 'y', 'time_counter'
294    output_scaling = "sozotaux|1.0", "time_counter|86400.0"
295    output_name = 'sozotaux'
296    output_lon = 'x'
297    output_lat = 'y'
298    output_vars = 'time_counter'
299    output_attributes = 'time_counter|units|seconds since 1995-00-00 00:00:00',
300                        'time_counter|calendar|noleap',
301                        'sozotaux|units|N/m2'
302/
303
304This program just multiplies by weights and sums over each contributing point,
305and then formats the output correctly for the model.
306
Note: See TracBrowser for help on using the repository browser.