New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
README in trunk/NEMOGCM/TOOLS/WEIGHTS – NEMO

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

Last change on this file since 2528 was 2448, checked in by smasson, 13 years ago

nemo_v3_3_beta: minor bugfix in WEIGHTS tools

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