source: branches/UKMO/r6232_tracer_advection/NEMOGCM/TOOLS/WEIGHTS/README @ 9295

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

NEMO trunk: small corrections to the weights generation code in the TOOLS directory for nemo 3.3

  • typos in README file corrected
  • scripgrid.F90 now allows any input nemo grid filename (but lat/lon names have to begin with glam/gphi)
  • scripinterp.F90 now actually does something
File size: 13.5 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         src            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 (and derived programs from the nocsutil directory). 
61Changes are described in the src/CHANGES file.
62This script has already been run and only needs to be re-executed if SCRIP is updated.
63
64The src directory also contains the three programs used to generate a weights file.
65The three programs are:
66
67scripgrid.exe (scripgrid.F90) which creates two grid description files suitable for
68input to the scrip package.
69
70scrip.exe (scrip.F90) which takes these descriptions and generates the required
71weights in the standard SCRIP format. This program is a version of the SCRIP
72program: scrip.f which has been modified to accept the name of its namelist
73file on the command line.
74
75scripshape.exe (scripshape.F90) which takes the output from scrip and rearranges
76the fields into a series of 2D fields more suited for input into NEMO using
77the iom_get routine.
78
79All three FORTRAN90 programs read domain information from their respective
80netCDF input files and dynamically allocate internal storage. They are
81thus independent of the target configuration and have been successfully
82tested with both ORCA2 and ORCA025 grids. Their suitably for use with larger
83grids has not been tested but should only be subject to limitations of
84the operating system and the memory available to the processing element.
85
86A separate tar file is available containing test data.
87This comprises an ORCA2 coordinates file and sample DFS4.1 input field that
88can be used for testing. Reference weights files generated using the two
89example namelists provided are located in its refout subdirectory.
90
91Installation is by use of the maketools script.
92E.g. change to the NEMOGCM/TOOLS directory and type:
93
94./maketools -help
95
96and, for example:
97
98./maketools -m gfortran_linux -n WEIGHTS
99
100
101Example Use
102-----------
103
104  cd data
105  ../scripgrid.exe  namelist_reshape_bilin    (creates remap_data_grid.nc
106                                                and remap_nemo_grid.nc)
107  ../scrip.exe      namelist_reshape_bilin    (creates data_nemo_bilin.nc)
108
109  ../scripshape.exe namelist_reshape_bilin    (creates reshape_orca2_bilinear.nc)
110 
111[Note that because the gfortran compiler does not understand the iargc function
112and getarg subroutine calls, command line namelist names can only be supplied if
113symbol ARGC is defined during compilation (eg add '#define ARGC' to the top of
114the relevant program).  If not, the program asks for the name instead during execution.]
115
116Only the final output file is required for use with NEMO but the intermediate
117files can be checked against the examples in the test data (available separately).
118
119For bicubic mapping only scrip and scripshape need to be rerun (because the grid_inputs namelist
120entries are identical in the two namelist files, see Controls section below):
121 
122  ../scrip.exe namelist_reshape_bicubic       (creates data_nemo_bicubic.nc)
123
124  ../scripshape.exe namelist_reshape_bicubic  (creates reshape_orca2_bicubic.nc)
125
126Controls
127--------
128
129The SCRIP derived utilities use SCRIP-style namelists to control their
130operation.  In the example above the same named file is used for both but within that
131file are two separate namelists:
132
133&grid_inputs
134    input_file = './snow_1m_TRP_1958.nc'
135    nemo_file = 'coordinates.nc'
136    datagrid_file = 'remap_data_grid.nc'
137    nemogrid_file = 'remap_nemo_grid.nc'
138    method = 'regular'
139    input_lon = 'lon'
140    input_lat = 'lat'
141    nemo_lon = 'glamt'
142    nemo_lat = 'gphit'
143    nemo_mask = 'none'
144    nemo_mask_value = 10
145    input_mask = 'none'
146    input_mask_value = 10
147/
148
149which is used by scripgrid, and:
150
151&remap_inputs
152    num_maps = 1
153    grid1_file = 'remap_data_grid.nc'
154    grid2_file = 'remap_nemo_grid.nc'
155    interp_file1 = 'data_nemo_bilin.nc'
156    interp_file2 = 'nemo_data_bilin.nc'
157    map1_name = 'data to nemo bilin Mapping'
158    map2_name = 'nemo to data bilin Mapping'
159    map_method = 'bilinear'
160    normalize_opt = 'frac'
161    output_opt = 'scrip'
162    restrict_type = 'latitude'
163    num_srch_bins = 90
164    luse_grid1_area = .false.
165    luse_grid2_area = .false.
166/
167
168which is used by scrip.
169
170scripshape also reads information from a namelist:
171
172&shape_inputs
173    interp_file = 'data_nemo_bilin.nc'
174    output_file = 'weights_bilin.nc'
175    ew_wrap     = 0
176/
177
178scripgrid.exe
179-------------
180
181scripgrid accesses the named files and coordinate data in order to produce
182the grid centre and corner locations required by scrip. In the example given,
183a file called 'coordinates.nc' must exist in the current directory. This is
184used by scripgrid as a nemo coordinates file and the correct corner
185locations appropriate to the named grid centres are obtained (i.e. since
186glamt is named, glamf and gphif will be used to provide corner coordinates).
187The nemo file need not be called 'coordinates.nc' (e.g. '1_coordinates.nc' instead),
188but must have longitude and latitude variables which start with the four
189characters 'gphi' and 'glam' respectively.
190"input_file" file must contain at least one variable on a grid whose axes are
191described by the netcdf coordinate variables named in input_lon and input_lat.
192The program produces two grid description files, one corresponding to each
193input file, for use by the scrip program to calculate weights required to
194go from one to the other and back again.
195
196This step is independent of the mapping method (e.g. bilinear or bicubic)
197and so only one set of remap_data_grid.nc and remap_nemo_grid.nc files needs
198to be produced for each pair of source and destination grids.
199
200scrip.exe
201---------
202
203scrip takes the output files from scripgrid and creates a file of weights
204to use to interpolate between the two grids described. The example given
205only requests 1 map (from data to nemo); setting num_maps=2 will provide
206the reverse weights if required.
207 
208 - num_maps is either 1 or 2 depending on whether the reverse
209    transformation is required
210
211 - grid1_file, grid2_file: two remap grid files are required
212    as output by scripgrid
213
214 - interp_file1, interp_file2: one or two interp_file names are
215    then supplied; these hold the weights to convert one grid to another
216
217 - map1_name, map2_name: the map_name variables are just descriptive
218
219 - map_method: can be 'bilinear' or 'bicubic'
220
221 - normalize_opt: should usually be 'frac' or else the user needs to do 
222    this scaling manually (this seems to the case for fractional ice cover)
223
224 - output_opt may be supplied and set to either 'scrip' or 'ncar-csm'
225
226 - restrict_type: should be 'latitude' or 'latlon' in which case
227    num_srch_bins only are used in one or two directions
228
229 - use_grid_area fields override the scrip calculation of area in
230    case the model gets slightly different answers, but the area needs
231    to be supplied in the input files
232
233A conservative mapping scheme exists but is not yet working with NEMO grids.
234See the scrip package documentation for more details of these parameters.
235(http://climate.lanl.gov/Software/SCRIP/SCRIPusers.pdf)
236
237scripshape.exe
238--------------
239
240scripshape takes the output from scrip (e.g. data_nemo_bilin.nc ) and
241rearranges the source and destination indices and associated weights into
242sets of 2D fields each spanning the nemo grid. Each set is associated with
243each node involved in the interpolation scheme.  Thus for a bilinear mapping
244the weights file required by the IOF option includes the following fields:
245
246  double src01(lat, lon) ;   double dst01(lat, lon) ;   double wgt01(lat, lon) ;
247  double src02(lat, lon) ;   double dst02(lat, lon) ;   double wgt02(lat, lon) ;
248  double src03(lat, lon) ;   double dst03(lat, lon) ;   double wgt03(lat, lon) ;
249  double src04(lat, lon) ;   double dst04(lat, lon) ;   double wgt04(lat, lon) ;
250
251For a bicubic mapping the required fields are:
252
253  double src01(lat, lon) ;   double dst01(lat, lon) ;   double wgt01(lat, lon) ;
254  double src02(lat, lon) ;   double dst02(lat, lon) ;   double wgt02(lat, lon) ;
255  double src03(lat, lon) ;   double dst03(lat, lon) ;   double wgt03(lat, lon) ;
256  double src04(lat, lon) ;   double dst04(lat, lon) ;   double wgt04(lat, lon) ;
257  double src05(lat, lon) ;   double dst05(lat, lon) ;   double wgt05(lat, lon) ;
258  double src06(lat, lon) ;   double dst06(lat, lon) ;   double wgt06(lat, lon) ;
259  double src07(lat, lon) ;   double dst07(lat, lon) ;   double wgt07(lat, lon) ;
260  double src08(lat, lon) ;   double dst08(lat, lon) ;   double wgt08(lat, lon) ;
261  double src09(lat, lon) ;   double dst09(lat, lon) ;   double wgt09(lat, lon) ;
262  double src10(lat, lon) ;   double dst10(lat, lon) ;   double wgt10(lat, lon) ;
263  double src11(lat, lon) ;   double dst11(lat, lon) ;   double wgt11(lat, lon) ;
264  double src12(lat, lon) ;   double dst12(lat, lon) ;   double wgt12(lat, lon) ;
265  double src13(lat, lon) ;   double dst13(lat, lon) ;   double wgt13(lat, lon) ;
266  double src14(lat, lon) ;   double dst14(lat, lon) ;   double wgt14(lat, lon) ;
267  double src15(lat, lon) ;   double dst15(lat, lon) ;   double wgt15(lat, lon) ;
268  double src16(lat, lon) ;   double dst16(lat, lon) ;   double wgt16(lat, lon) ;
269
270This program also adds an attribute to the weights file for use by the fld_interp
271routine in fldread.F90.  This tells the model about the east-west cyclicity of the source grid.
272The value needs to be supplied in the scripshape namelist via the variable ew_wrap.
273It should have one of the values -1, 0, 1 or 2.  -1 means that the input grid is not
274cyclic; 0 means that it is cyclic but with no overlapping columns; and a value greater
275than zero represents the number of columns that overlap.  In fact it only has an effect
276when using bicubic interpolation in which the model needs to know which additional columns
277have to be read in to correctly calculate gradient values.
278The weights file produced by scripshape is ready for use in NEMO. This file
279needs to by placed in the nemo working directory and needs to be named in the
280appropriate SBC namelist entry (e.g. namsbc_clio, namsbc_flux or namsbc_core).
281
282scripinterp.exe
283---------------
284
285Take data on an input grid and interpolate to the nemo grid using the weights
286calculated by the scrip program.
287Method
288Two namelists are used for configuration, eg
289
290&interp_inputs
291    input_file = "../data/wsx_av.nc"
292    interp_file = "data_nemo_bilin.nc"
293    input_name = "wsx"
294    input_start = 1,1,1,1
295    input_stride = 1,1,1,1
296    input_stop = 0,0,0,1
297    input_vars = 'time'
298/
299
300&interp_outputs
301    output_file = "taux_1m.nc"
302    output_mode = "create"
303    output_dims = 'x', 'y', 'time_counter'
304    output_scaling = "sozotaux|1.0", "time_counter|86400.0"
305    output_name = 'sozotaux'
306    output_lon = 'x'
307    output_lat = 'y'
308    output_vars = 'time_counter'
309    output_attributes = 'time_counter|units|seconds since 1995-00-00 00:00:00',
310                        'time_counter|calendar|noleap',
311                        'sozotaux|units|N/m2'
312/
313
314This program just multiplies by weights and sums over each contributing point,
315and then formats the output correctly for the model.
316
Note: See TracBrowser for help on using the repository browser.