source: CPL/oasis3/trunk/src/mod/oasis3/doc/UG4_Transformations.tex @ 1677

Last change on this file since 1677 was 1677, checked in by aclsce, 12 years ago

Imported oasis3 (tag ipslcm5a) from cvs server to svn server (igcmg project).

File size: 39.6 KB
2\chapter{The transformations and interpolations in OASIS3}
5Different transformations and 2D interpolations are available in
6OASIS3 to adapt the coupling fields from a source model grid to a target
7model grid. They are divided into five general classes that have
8precedence one over the other in the following order: time
9transformation (with {\tt CLIM/MPI1-MPI2} and PSMILe only), pre-processing,
10interpolation, ``cooking'', and post-processing. This order of
11precedence is conceptually logical, but is also constrained by the
12OASIS3 software internal structure.
14In the following paragraphs, it is first described how to use OASIS3
15in an interpolator-only mode. Then a description of each
16transformation with its corresponding configuring lines is given.
18\section{Using OASIS3 in the interpolator-only mode}
21OASIS3 can be used in an interpolator-only mode, in which case it
22 transforms fields without running any model.  It is
23 recommended to use first OASIS3 in this mode
24 to test different transformations and interpolations without
25 having to run the whole coupled system. In the interpolator-only mode,
26 all transformations, except the time transformations, are available.
28To run OASIS3 in an interpolator-only mode, the user has to prepare
29the {\it namcouple} as indicated in sections
30\ref{subsec_namcouplefirst} and \ref{subsec_namcouplesecond}. In
31particular, {\tt NONE} has to be chosen below the keyword {\tt
32\$CHANNEL}; ``0'' (without any model name and Fortran unit number)
33must be given below the keyword {\tt \$NBMODEL}; {\tt \$RUNTIME} has
34to be the number of time occurrences of the field to interpolate from
35the NetCDF input file\footnote{For binary input file, only one time
36occurence may be interpolated}; finally, the ``coupling'' period of
37the field (4th entry on the field first line) must be always ``1''.
38Note that if {\tt \$RUNTIME} is smaller than the total number of time
39ocurrences in the input file, the first {\tt \$RUNTIME} occurrences
40will be interpolated.
42The name of the input file which contains the fields to interpolate is
43given by the 6th entry on the field first line (see
44\ref{subsec_namcouplesecond}). A positive LAG has to be defined for the
45field so that the input file is opened at the beginning of the
46run. After their transformation, OASIS3 writes them to their output
47file which name is the 7th entry on the first line. Note that all
48fields have to be present in the same restart file.
50The time variable in the input file, if any, is recognized by the its
51attribute "units".  The acceptable units for time are listed in the
52udunits.dat file \cite{udunits}.  This follows the CF convention.
53A practical example on how to use OASIS3 in a interpolator-only mode
54is given in {\tt prism/util/running/toymodel/testinterp} (from CERFACS
55CVS only).
57The configuring parameters that have to be defined in the {\it
58namcouple} for each transformation in the interpolator-only mode or in
59the coupling mode are described here after.
61%{Running OASIS3 in the interpolator-only mode}
63\section{The time transformations}
66{\tt LOCTRANS} can be chosen as first transformation if
67CLIM/MPI1-MPI2 communication and the PSMILe interface are used. {\tt
68LOCTRANS} requires one configuring line on which a time
69transformation, automatically performed below the call to PSMILe {\tt
70prism\_put\_proto}, should be indicated:
73\item {\tt INSTANT}: no time transformation, the instantaneous field is
75\item {\tt ACCUMUL}: the field accumulated over the previous coupling
76period is transferred;
77\item {\tt AVERAGE}: the field averaged over the previous
78coupling period is transferred; 
79\item {\tt T\_MIN}: the minimum value of the field
80for each source grid point over the previous coupling period is
82\item {\tt T\_MAX}: the maximum value of the field for each source grid
83point over the previous coupling period is transferred;
84\item ONCE: only one {\tt prism\_put\_proto} or {\tt
85prism\_get\_proto} will be performed; this is equivalent to giving the
86length of the run as coupling or I/O period.
89\section{The pre-processing transformations}
92The following transformations are available in the pre-processing part of
93OASIS3, controlled by {\tt preproc.f}.
97\item {\bf REDGLO} (not recommended anymore as
98 interpolations now exist directly for Reduced grids):
100 {\tt REDGLO} (routine {\tt redglo.f}) performs the interpolation from a
101 Reduced grid to a Gaussian one. The interpolation is linear and
102 performed latitude circle per
103 latitude circle. When present, REDGLO must be the first pre-processing
104 transformation performed.
105 The configuring line is as follows:
106 \begin{verbatim}
107 # REDGLO operation
108     $NNBRLAT  $CDMSK \end{verbatim}where {\tt \$NNBRLAT} is NOxxx
109 where xxx is half the number of latitude circles of the Gaussian
110 grid. For example, for a T42 with 64 latitude circles, {\tt
111 \$NNBRLAT} is ``NO32''. In the current version, it can be either
112 NO16, NO24, NO32, NO48, NO80, NO160.{\tt \$CDMSK} is a flag
113 indicating if non-masked values have to be extended to masked areas
114 before interpolation ({\tt \$CDMSK = SEALAND}) using the Reduced grid
115 mask (see section \ref{subsec_griddata}) or if the opposite has to be
116 performed ({\tt \$CDMSK = LANDSEA}).  If {\tt \$CDMSK = NOEXTRAP},
117 then no extrapolation is performed.
119\item {\bf INVERT}:
121 {\tt INVERT} (routine {\tt invert.f}) reorders a field so that it
122 goes from south to north and from west to east (the first point will
123 be the southern and western most one; then it goes parallel by parallel
124 going from south to north). {\tt INVERT} should be used only for
125 fields associated to A, B, G, L, Z, or Y grids (see annexe
126 \ref{subsec_gridtypes}) but produced by the source model from North to
127 South and/or from East to West. {\tt INVERT} does not work for
128 Reduced ('D') or unstructured ('U') grids (see annexe
129 \ref{subsec_gridtypes}).
131 The generic input line is as follows:
132 \begin{verbatim}
133 # INVERT operation
134     $CORLAT  $CORLON \end{verbatim} where
135 {\tt \$CORLAT = NORSUD} or {\tt SUDNOR} and {\tt \$CORLON = ESTWST}
136 or {\tt WSTEST} describes the orientation of the source field in
137 longitude and latitude, respectively.
139\item {\bf MASK}:
141 {\tt MASK} (routine {\tt masq.f}) is used before the analysis {\tt
142 EXTRAP}.  A given {\tt REAL} value {\tt VALMASK} is assigned to all masked
143 points following the source grid mask (see section
144 \ref{subsec_griddata}), so they can be detected by {\tt EXTRAP}.
146 The generic input line is as follows:
147 \begin{verbatim}
148 # MASK operation
149     $VALMASK \end{verbatim}Problems may arise if the value chosen
150 approaches the maximum value that your computing platform can
151 represent; choose a value well outside the range of
152 your field values but not too large.
154\item {\bf EXTRAP}:
156 {\tt EXTRAP} (routine {\tt extrap.f}) performs the extrapolation of a
157 field over its masked points.  The analysis {\tt MASK} must be used
158 just before, so that {\tt EXTRAP} can identify masked points. Note
159 that {\tt EXTRAP} does not work for Reduced ('D') or unstructured
160 ('U') grids (see section \ref{subsec_gridtypes}).
162 Two methods of extrapolation are available. With {\tt NINENN}, a
163 N-nearest-neighbour method is used. The procedure is iterative and the
164 set of remaining masked points evolves at each iteration.  The
165 configuring line is:
166 \begin{verbatim}
167 # EXTRAP operation for $CMETH = NINENN
168     $CMETH  $NV  $NIO  $NID\end{verbatim} where
169 {\tt \$CMETH = NINENN}; {\tt \$NV} is the minimum number
170 of neighbours required to perform the extrapolation (with a maximum
171 of 4)\footnote{For some grids, the extrapolation may not converge if
172 {\tt \$NV} is too large.}; {\tt \$NIO} is the flag that
173 indicates if the weight-address-and-iteration-number dataset will be
174 calculated and written by OASIS3 ({\tt \$NIO}= 1), or only read ({\tt
175 \$NIO}= 0) in file {\em nweights} (see section
176 \ref{subsec_transformationdata}); {\tt \$NID} is the identificator for
177 the weight-address-iteration-number dataset in all the different
178 {\tt EXTRAP/NINENN} datasets in the present coupling.\footnote{An
179 {\tt EXTRAP/NINENN} analysis is automatically performed within {\tt GLORED}
180 analysis but the corresponding datasets have to be distinct; this is
181 automatically checked by OASIS3 at the beginning of the run.}
183 With {\tt \$CMETH = WEIGHT}, an N-weighted-neighbour extrapolation
184 is performed. In that case, the user has to build the grid-mapping
185 file, giving for each target grid point the weights and addresses
186 of the source grid points used in the extrapolation; the structure of this
187 file has to follow the OASIS3 generic structure for transformation
188 auxiliary data files (see section \ref{subsec_transformationdata}).
190 The configuring line is:
191 \begin{verbatim}
192 # EXTRAP operation for $CMETH = WEIGHT
193     $CMETH  $NV  $CFILE  $NUMLU  $NID\end{verbatim} where
194 {\tt \$CMETH = WEIGHT}; {\tt \$NV} is the maximum number of
195 neighbours required by the extrapolation operation; {\tt \$CFILE} and
196 {\tt \$NUMLU} are the grid-mapping file name and associated logical
197 unit; {\tt \$NID} is the identificator for the relevant grid-mapping
198 dataset in all different {\tt EXTRAP/WEIGHT} transformations in the present
199 coupling.
203\item {\bf CHECKIN}:
205 {\tt CHECKIN} (routine {\tt chkfld.f}) calculates the mean and extremum
206 values of the source field and prints them to the coupler log file
207 {\em cplout}.
209 The generic input line is as follows:
210 \begin{verbatim}
211 # CHECKIN operation
212     $NINT   \end{verbatim} where
213 {\tt \$NINT} = 1 or 0, depending on whether or not the source
214 field integral is also calculated and printed.
216\item {\bf CORRECT}:
218 {\tt CORRECT} (routine {\tt correct.f}) reads external fields from binary
219 files and uses them to modify the coupling field. This transformation
220 can be used, for example, to perform flux correction on the field.
222 This transformation requires at least one configuration line with two
223 parameters:
224 \begin{verbatim}
225 # CORRECT operation
226     $XMULT  $NBFIELDS \end{verbatim} where
227 {\tt \$XMULT} is the multiplicative coefficient of the current
228 field, and {\tt \$NBFIELDS} the number of additional fields to be
229 combined with the current field.  For each additional field, an
230 additional configuring line is required:
231 \begin{verbatim}
232 # nbfields lines
233     $CLOC  $AMULT  $CFILE  $NUMLU \end{verbatim} where
234 {\tt \$CLOC} and {\tt \$AMULT}, {\tt \$CFILE} and {\tt \$NUMLU}
235 are respectively the symbolic name, the multiplicative coefficient,
236 the file name and the associated logical unit on which the additional
237 field is going to be read. The structure of the file has to follow
238 the structure of OASIS3 binary coupling restart files (see section
239 \ref{subsec_restartdata}).
243%subsection{The pre-processing transformations}
245\section{The interpolation}
248The following interpolations, controlled by {\tt interp.f}, are
249available in OASIS3.
253\item {\bf BLASOLD}:
255{\tt BLASOLD} (routine {\tt blasold.f}) performs a linear combination of the
256current coupling field with other coupling fields or with a constant
257before the interpolation {\it per se}.
259This transformation requires at least one configuring line with two
262 # BLASOLD operation
263     $XMULT     $NBFIELDS\end{verbatim}where
264{\tt \$XMULT} is the multiplicative coefficient of the current
265field, and {\tt \$NBFIELDS} the number of additional fields to be
266combined with the current field.  For each additional field, an
267additional input line is required:
269# nbfields lines
270     $CNAME  $AMULT
272where {\tt \$CNAME} and {\tt \$AMULT} are the symbolic name and the
273multiplicative coefficient for the additional field. To add a
274constant value to the original field, put {\tt \$XMULT} = 1, {\tt
275\$NBFIELDS} = 1, {\tt \$CNAME = CONSTANT}, {\tt \$AMULT} = value to
278\item {\bf SCRIPR}:
280  {\tt SCRIPR} is new in OASIS3 and gathers the interpolation
281  techniques offered by Los Alamos National Laboratory SCRIP 1.4
282  library\footnote{See the copyright statement in annexe
283  \ref{sec_SCRIP}.}\cite{SCRIPR}. {\tt SCRIPR} routines are in {\tt
284  prism/src/lib/scrip}. See also the SCRIP 1.4
285  documentation in  {\tt prism/src/mod/oasis3/doc/SCRIPusers.pdf}.
286  Linking with NetCDF library is mandatory when using
287  {\tt SCRIPR} interpolations.
289  The following types of interpolations are available:
291  \begin{itemize}
293  \item {\tt DISTWGT} performs N nearest-neighbour interpolation (N
294  neighbours). All grid types are supported. If the N nearest
295  neighbours of a target grid point are masked, no value is calculated
296  for that point; transformations {\tt MASK} and {\tt EXTRAP} should
297  be used to avoid problems for those points. No values are calculated
298  for masked target grid points.
300  The configuring line is:
302  \begin{verbatim}
304  $CMETH $CGRS $CFTYP $REST $NBIN $NV $ASSCMP $PROJCART\end{verbatim} where:
305  \begin{itemize}
306  \item {\tt \$CMETH = DISTWGT}.
307  \item {\tt \$CGRS} is the source grid
308  type ({\tt LR}, {\tt D} or {\tt U})- see annexe
309  \ref{subsec_gridtypes}.
311  \item {\tt \$CFTYP} is the field type: {\tt SCALAR} if the field is
312  a scalar one, or {\tt VECTOR\_I} or {\tt VECTOR\_J} whether the
313  field represents respectively the first or the second component of a
314  vector field (see paragraph {\bf Support of vector fields}
315  below). Note that {\tt VECTOR}, which is fact leads to a scalar treatment
316  of the field (as in the previous versions), is still supported.
318  \item {\tt \$REST} is the search restriction type: {\tt LATLON}
319  or {\tt LATITUDE} (see SCRIP 1.4 documentation). Note that for {\tt
320  D} or {\tt U} grid, the restriction may influence sligthly the
321  result near the borders of the restriction bins.
322  \item {\tt \$NBIN} the number of restriction bins (see SCRIP 1.4
323  documentation).
324  \item {\tt \$NV} is the number of neighbours used.
325  \item {\tt \$ASSCMP}: optional, for {\tt VECTOR\_I} or {\tt VECTOR\_J} vector fields only; the source symbolic name of the associated vector component.
326  \item {\tt \$PROJCART}: optional, for vector fields only; should be {\tt PROJCART} if the user wants the vector components to be projected in a Cartesian coordinate system before interpolation (see paragraph {\bf Support of vector fields} below).
327  \end{itemize}
329  \item {\tt GAUSWGT} performs N nearest-neighbour interpolation
330  weighted by a gaussian function. All grid types are
331  supported. Behaviour for source and target masked points is the same
332  than for {\tt DISTWGT}. The configuring line is:
333  \begin{verbatim}
335$CMETH  $CGRS  $CFTYP  $REST  $NBIN  $NV $VAR $ASSCMP $PROJCART\end{verbatim} where all entries are as for  {\tt DISTWGT}, except that:
336  \begin{itemize} 
337   \item {\tt \$CMETH = GAUSWGT}
338   \item {\tt \$VAR}, which must be given as a
339    REAL value (e.g 2.0 and not 2), defines the weight given to a
340    neighbour source grid point as inversely
341    proportional to $exp(-1/2 \cdot d^2/\sigma^2)$ where $d$ is the
342    distance between the source and target grid points, and $\sigma^2 =
343    \$VAR \cdot \overline{d}^2$ where $\overline{d}^2$ is the average
344    distance between two source grid points (calculated automatically
345    by OASIS3).
346  \end{itemize}
348  \item {\tt BILINEAR} performs bilinear interpolation.
350  \item {\tt BICUBIC} performs a bicubic interpolation.
352  For {\tt BILINEAR} and {\tt BICUBIC}, Logically-Rectangular (LR) and
353  Reduced (D) source grid types are supported. If the some of the
354  source grid points NORMlly used in the bilinear or bicubic
355  interpolation are masked, another algorithm is applied; at least,
356  the nearest non-masked source neighbour is used.  No values are
357  calculated for masked target grid points.
359  The configuring line is:
361  \begin{verbatim}
363     $CMETH  $CGRS  $CFTYP  $REST  $NBIN $ASSCMP $PROJCART\end{verbatim}where:
364  \begin{itemize}
365  \item {\tt \$CMETH = BILINEAR} or {\tt BICUBIC}
366  \item {\tt \$CGRS} is the source grid type (LR or D)
367  \item {\tt \$CFTYP}, {\tt \$NBIN}, {\tt \$ASSCMP} {\tt \$PROJCART} are
368  as for {\tt DISTWGT}.
369  \item {\tt \$REST} is as for {\tt DISTWGT}, except that only
370  {\tt LATITUDE} is possible for a Reduced (D) source grid.
371  \end{itemize}
373  \item {\tt CONSERV} performs 1st or 2nd order conservative remapping,
374  which means that the weight of a source cell is proportional to area
375  intersected by target cell. Values are possibly calculated for all
376  target grid points whether they are masked or not. The source grid
377  mask is taken into account in the NORMlisation (see below).
379  The configuring line is:
380  \begin{verbatim}
382$CMETH  $CGRS  $CFTYP  $REST  $NBIN  $NORM  $ORDER $ASSCMP $PROJCART\end{verbatim}where:
383  \begin{itemize}
384  \item {\tt \$CMETH = CONSERV} 
385  \item {\tt \$CGRS} is the source grid type: LR, D and U are
386  supported for 1st-order remapping if the grid corners are given by
387  the user in the grid data file which is, in this case, necessarily a
388  netCDF file (, see section \ref{subsec_griddata}); only LR
389  is supported if the grid corners are not available in the grid data
390  file and therefore have to be calculated automatically by
391  OASIS3. For second-order remapping, only LR is supported because the
392  gradient of the coupling field used in the transformation has to be
393  calculated automatically by OASIS3.
394  \item {\tt \$CFTYP, \$REST}, {\tt \$NBIN}, {\tt \$ASSCMP},and {\tt \$PROJCART} are as for {\tt
395  DISTWGT}. Note that for {\tt CONSERV} the restriction does not
396  influence the result.
397  \item {\tt \$NORM} is the NORMlization option:
398  \begin{itemize}
399   \item {\tt FRACAREA}: The sum of the source cell intersected areas
400    is used to NORMlise each target cell field value: the flux is not
401    locally conserved, but the flux value itself is reasonable.
402   \item  {\tt DESTAREA}: The total target cell area is used to NORMlise each
403    target cell field value even if it only partly intersects the source
404    grid cells: local flux conservation is ensured, but
405    unreasonable flux values may result.
406   \item  {\tt FRACNNEI}: as {\tt FRACAREA}, except that the source nearest
407    neighbour is used for target cells that do not intersect any
408    unmasked source cells.
409  \end{itemize} 
410\item {\tt \$ORDER}: {\tt FIRST} or {\tt SECOND}\footnote{{\tt
411  CONSERV/SECOND} has not been tested in detail.} for first or second
412  order remapping respectively (see SCRIP 1.4 documentation).
416{\bf Support of vector fields}
418{\tt SCRIPR} supports 2D vector interpolation. The two vector
419components have to be identified by replacing {\tt \$CFTYP} by {\tt
420VECTOR\_I} or {\tt VECTOR\_J} and have to be associated by replacing
421{\tt \$ASSCMP}, for each component field, by the source symbolic name
422of the associated vector component in (see above). A proper example of
423vector interpolation is given in the interpolator-only mode example
424(see details in {\tt
425prism/util/running/testinterp/README\_testinterp}). The details of the
426vector treatment, performed by the routines {\tt scriprmp\_vector.F90}
427and {\tt rotations.F90} in {\tt prism/src/lib/scrip/src} are the
431\item If the angles of the source grid local coordinate system are defined in the {\it} data file (see section \ref{subsec_griddata}), an automatic rotation from the local to the geographic spherical coordinate system is performed.
432\item If the two source vector components are not defined on the same source grid, one component is automatically interpolated on the grid of the other component.
433\item If the user put the {\tt PROJCART} keyword at the end of the
434{\tt SCRIPR} configuring line (see above), projection of the two
435vector components in a Cartesian coordinate system, interpolation of
436the resulting 3 Cartesian components, and projection back in the
437spherical coordinate system are performed. In debug mode (compilation
438with {\tt DEBUG} pre-compiling key), the resulting vertical component
439in the spherical coordinate system after interpolation is written to a
440file {\tt}; as the source vector is horizontal, this component should be very close to 0. 
441\item If the user did not put the {\tt PROJCART} keyword at the end of the {\tt SCRIPR} configuring line, the two spherical coordinate system components are interpolated.
442\item If the angles of the target grid local coordinate system are defined in the {\it} data file (see section \ref{subsec_griddata}), an automatic rotation from the geographic spherical to the local coordinate system is performed.
443\item The first and second components of the interpolated vector field are then present in the target fields associated respectively to the first and second source vector component. The target grids for the two vector components can be different.
447\item {\bf INTERP}:
449%-Note sur le traitement des points masqu‰s dans OASIS:
450%Note: Le champ interpol‰ fldnew est initialis‰ € z‰ro. La valeur du
451%masque de la grille source n'est pas chang‰e ni par masq.f ni par
455% -les points source masqu‰s ne sont pas utilis‰s.
456% -le calcul des poids est fait pour tous les points cible mais les poids et
457%  adresses des points masqu‰s sont remis € 0 et 1.
458% -le calcul du champ interpol‰ n'est fait que pour les points cible
459%  non-masqu‰s.
461% -tous les points source, mŠme masqu‰s, sont utilis‰s (c'est pour ‡a
462%  qu'il faut faire MASK et EXTRAP avant).
463% -le calcul des poids est fait pour tous les points cibles
464%  masqu‰s ou pas.
465% -le calcul du champ interpol‰ est fait pour tous les points cibles
466%  masqu‰s ou pas.
468% -les points source masqu‰s ne sont pas utilis‰s.
469% -le calcul des poids n'est fait que pour les points cible
470% non-masqu‰s.
471% -le calcul du champ interpol‰ n'est fait que pour les points cible
472% non-masqu‰s.
474  {\tt INTERP} gathers different techniques of interpolation controlled by
475  routine {\tt fiasco.f}. The following interpolations are available:
477  \begin{itemize}
479   \item {\tt BILINEAR} performs a bilinear interpolation using 4
480    neighbours.
482   \item {\tt BICUBIC} performs a bicubic interpolation.
484   \item {\tt NNEIBOR} performs a nearest-neighbour interpolation.
486  These three interpolations are performed by routines in {\tt
487  /prism/src/lib/fscint} and support only A, B,
488  G, L, Y, or Z grids (see annexe
489  \ref{subsec_gridtypes}). All sources grid points, masked or not, are
490  used in the calculation. To avoid the `contamination' by masked
491  source grid points, transformations {\tt MASK} and {\tt EXTRAP}
492  should be used. Values are calculated for all target grid points,
493  masked or not.
495  The configuring line is as follows:
496    \begin{verbatim}
497 # BILINEAR or BICUBIC or NNEIBOR interpolation
498    $CMETH $CGRS $CFTYP \end{verbatim} where
499     \begin{itemize}
500     \item {\tt \$CMETH = BILINEAR}, {\tt BICUBIC} or {\tt NNEIBOR}
501     \item {\tt \$CGRS} is the source grid type (A, B, G, L, Y, or
502     Z, see annexe \ref{subsec_gridtypes})
503     \item {\tt \$CFTYP} the field type ({\tt SCALAR} or {\tt
504  VECTOR}). {\tt VECTOR} has an effect for target grid points located
505  near the pole: the sign of a source value located on
506  the other side of the pole will be reversed.
507     \end{itemize}
509   \item {\tt SURFMESH} (routines in {\tt /prism/src/lib/anaism}) is a
510    first-order conservative remapping from a fine to a coarse grid
511    (the source grid must be finer over the whole domain) and supports
512    only Lat-Lon grids. For a target grid cell, all the underlying not
513    masked source grid cells are found and the target grid field value
514    is the sum of the source grid field values weighted by the
515    overlapped surfaces. No value is assigned to masked cells. Note
516    that it is not recommended to use this interpolation anymore, as
517    the more general {\tt SCRIPR/CONSERV} remapping is now available.
518    The configuring line is as follows:
520    \begin{verbatim}
521 # SURFMESH remapping
522     $CMETH $CGRS $CFTYP $NID $NV $NIO\end{verbatim} where
523     \begin{itemize}
524     \item {\tt \$CMETH = SURFMESH}
525     \item {\tt \$CGRS} and {\tt \$CFTYP} are as for {\tt BILINEAR}
526     \item {\tt \$NID} is the identificator for the weight-address
527    dataset in all the different {\tt INTERP/SURFMESH} datasets in the
528    present coupling.  This dataset will be calculated by OASIS3 if
529    {\tt \$NIO}= 1, or only read if {\tt \$NIO}= 0.
530    \item {\tt \$NV} is the maximum number of source grid meshes
531    used in the remapping.
532    \end{itemize}
534    \item {\tt GAUSSIAN} (routines in {\tt /prism/src/lib/anaisg}) is a
535     gaussian weighted nearest-neighbour interpolation technique.
536    The user can choose the variance of the function and the number of
537    neighbours considered. The masked source grid points are not used
538    and no value are calculated for masked target grid points.
540    The configuring line is:
541    \begin{verbatim}
542    # GAUSSIAN interpolation
543    $CMETH $CGRS $CFTYP $NID $NV $VAR  $NIO\end{verbatim}where
544    \begin{itemize}
545    \item {\tt \$CMETH = GAUSSIAN}
546    \item {\tt \$CGRS} is the source grid type ({\tt LR, D} or {\tt U}) and {\tt \$CFTYP} is as for the {\tt DISTWGT}
547    % (in the {\tt U} case the surface calculation is wrong XXXXX).
548    \item {\tt \$NID} is the identificator for the
549    weight-address dataset in all the different {\tt INTERP/GAUSSIAN}
550    datasets in the present coupling. This weight-address dataset will
551    be calculated by OASIS3 if {\tt \$NIO}= 1, or only read if {\tt
552    \$NIO}= 0.
553    \item {\tt \$NV} is the number of neighbours used in the
554    interpolation.
555    \item {\tt \$VAR} is as for {\tt SCRIPR/GAUSWGT} (see above).
556    \end{itemize}
559\item {\bf MOZAIC}:
561{\tt MOZAIC} performs the mapping of a field from a source to a target
562grid. The grid-mapping dataset, i.e. the weights and addresses of the
563source grid points used to calculate the value of each target grid
564point are defined by the user in a file (see section
565\ref{subsec_transformationdata}).  The configuring line is:
567# MOZAIC operation
568     $CFILE  $NUMLU  $NID  $NV
571\item{\tt \$CFILE} and {\tt \$NUMLU} are the grid-mapping file name
572and associated logical unit on which the grid-mapping dataset is going
573to be read),
574\item {\tt \$NID} the identificator for this grid-mapping dataset in
575all {\tt MOZAIC} grid-mapping datasets in the present coupling
576\item {\tt \$NV} is the maximum number of target grid points use
577in the mapping.
580\item {\bf NOINTERP}:
582{\tt NOINTERP} is the analysis that has to be chosen when no other
583transformation from the interpolation class is chosen.
584There is no configuring line.
586\item {\bf FILLING}:
588{\tt FILLING} (routine {\tt /prism/src/mod/oasis3/src/filling.f})
589performs the blending of a regional data set with a climatological
590global one for a Sea Surface Temperature (SST) or a Sea Ice Extent
591field. This occurs when coupling a non-global ocean model with a
592global atmospheric model. {\tt FILLING} can only handle
593fields on Logically Rectangular grid (LR, but also A, B,
594G, L, Y, and Z grids, see section \ref{subsec_gridtypes}.
596The global data set has to be a set of SST
597given in Celsius degrees (for the filling of a Sea Ice Extent field,
598the presence or absence of ice is deduced from the value of the
599SST). The frequency of the global set can be interannual monthly,
600climatological monthly or yearly.
602The blending can be smooth or abrupt. If the blending is abrupt, only
603model values are used within the model domain, and only the global
604data set values are used outside. If the blending is smooth, a linear
605interpolation is performed between the two fields within the model
606domain over narrow bands along the boundaries. The linear
607interpolation can also be performed giving a different weight to the
608regional or and global fields.
610 The smoothing is defined by parameters in {\tt
611/prism/src/mod/oasis3/src/} \-\-\- {\tt mod\_smooth.F90}. The lower smoothing band
612in the global model second dimension is defined by {\em nsltb}
613(outermost point) and {\em nslte} (innermost point); the upper
614smoothing band in the global model second dimension is defined by {\em
615nnltb} (outermost point) and {\em nnlte} (innermost point). The
616parameter {\em qalfa} controls the weights given to the regional and
617to the global fields in the linear interpolation. {\em qalfa} has to
618be $1/(nslte-nsltb)$ or $1/(nnltb-nnlte)$. For the outermost points
619({\em nsltb} or {\em nnltb}) in the smoothing band, the weight given
620to the regional and global fields will respectively be 0 and 1; for
621the innermost points ({\em nslte} or {\em nnlte}) in the smoothing
622band, the weight given to the regional and global fields will
623respectively be 1 and 0; within the smoothing band, the weights will
624be a linear interpolation of the outermost and innermost weights.
626The smoothing band in the global model first dimension will be a band
627of {\em nliss} points following the coastline. To calculate this band,
628OASIS3 needs {\em nwlgmx}, the greater first dimension index of the
629lower coastline and {\em nelgmx}, the smaller first dimension index on
630the upper coastline. The parameter {\em qbeta} controls the weights
631given to the regional and to the global fields in the linear
632interpolation. {\em qbeta} has to be $1/(nliss-1)$. The weights given
633to the regional and global fields in the global model first dimension
634smoothing bands will be calculated as for the second dimension.
636The user must provide the climatological data file with
637a specific format described in \ref{subsec_transformationdata}.
638When one uses {\tt FILLING} for SST with smooth blending, thermodynamics
639consistency requires to modify the heat fluxes over the blending
640regions. The correction term is proportional to the difference between
641the blended SST and the original SST interpolated on the atmospheric
642grid and can be written out on a file to be read later, for analysis
643{\tt CORRECT} for example. In that case, the symbolic name of the flux
644correction term read through the input file {\em namcouple} must
645correspond in {\tt FILLING} and {\tt CORRECT} analyses.
647In case the regional ocean model includes a coastal part or islands, a
648sea-land mask mismatch may occur and a coastal point correction can be
649performed if the field has been previously interpolated with {\tt
650INTER/SURFMESH}. In fact, the
651mismatch could result in the atmosphere undesirably ``seeing''
652climatological SST's directly adjacent to ocean model SST's.  Where
653this situation arises, the coastal correction consists in identifying
654the suitable ocean model grid points that can be used to extrapolate
655the field, excluding climatological grid points.
657This analysis requires one configuring line with 3, 4 or 6 arguments.
660\item If FILLING performs the blending of a regional data set with a
661global one for the Sea Ice Extent, the 3-argument input line is:
663# Sea Ice Extent FILLING operation
664     $CFILE  $NUMLU  $CMETH\end{verbatim} where {\tt \$CFILE} is
665the file name for the global data set, {\tt \$NUMLU} the associated
666logical unit. {\tt \$CMETH}, the {\tt FILLING} technique, is a {\tt
667CHARACTER*8} variable: the first 3 characters are either {\tt SMO},
668smooth filling, or {\tt RAW}, no smoothing ; the next three characters
669must be {\tt SIE} for a Sea Ice Extent filling operation; the last two
670define the time characteristics of the global data file, respectively
671{\tt MO}, {\tt SE} and {\tt AN} for interannual monthly,
672climatological monthly and yearly. Note that in all cases, the global
673data file has to be a Sea Surface Temperature field in Celsius
676\item If FILLING performs the blending of a regional data set with a
677global one for the Sea Surface Temperature without any smoothing, the
6784-argument input line is:
680#Sea Surface Temperature FILLING operation without smoothing
681     $CFILE  $NUMLU  $CMETH  $NFCOAST\end{verbatim} where
682{\tt \$CFILE}, {\tt \$NUMLU} are as for the SIE filling. In this
683case however, {\tt \$CMETH(1:3) = RAW}, {\tt \$CMETH(4:6) = SST},
684and the last two characters define the time characteristics of the
685global data file, as for the SIE filling. {\tt \$NFCOAST} is 
686the flag for the calculation of the coastal correction ( 0 no, 1 yes).
688\item If FILLING performs the blending of a regional data set with a
689global one for the Sea Surface Temperature with smoothing, the
6906-argument input line is:
692#Sea Surface Temperature FILLING operation with smoothing
693     $CFILE  $NUMLU  $CMETH  $NFCOAST  $CNAME  $NUNIT\end{verbatim}
694     where {\tt \$CFILE}, {\tt \$NUMLU} and {\tt \$NFCOAST} are as for the SST
695filling without smoothing. In this case, {\tt \$CMETH(1:3) = SMO},
696{\tt \$CMETH(4:6) = SST}, and the last two characters define the
697time characteristics of the global data file, as for the SIE
698filling. {\tt \$CNAME} is the symbolic name for the correction
699term that is calculated by OASIS3 and {\tt \$NUNIT} the logical
700unit on which it is going to be written.
706%subsection{The interpolation}
708\section{The ``cooking'' stage}
711The following analyses are available in the ``cooking'' part of
712OASIS3, controlled by {\tt cookart.f}.
716\item {\bf CONSERV}:
718{\tt CONSERV} (routine {\tt /prism/src/mod/oasis3/src/conserv.f})
719performs global flux conservation. The flux is integrated on both
720source and target grids, without considering values of masked points,
721and the residual (target - source) is calculated. Then all flux values
722on the target grid are uniformly modified, according to their
723corresponding surface.  This analysis requires one input line with one
726# CONSERV operation
727     $CMETH\end{verbatim}where {\tt \$CMETH} is the conservation method required. In this
728version, only global flux conservation can be performed. Therefore
729{\tt \$CMETH} must be {\tt GLOBAL}.
731\item {\bf SUBGRID}:
733{\tt SUBGRID} can be used to interpolate a field from a coarse grid to a
734finer target grid (the target grid must be finer over the whole
735domain). Two types of subgrid interpolation can be performed,
736depending on the type of the field.
738For solar type of flux field ({\tt \$SUBTYPE = SOLAR}), the operation
739performed is:
740$$\Phi_{i} = \frac{1-\alpha_i}{1-\alpha} F$$ where $\Phi_{i}$ ($F$) is
741the flux on the fine (coarse) grid, $\alpha_i$ ($\alpha$) an auxiliary
742field on the fine (coarse) grid (e.g. the albedo).  The whole
743operation is interpolated from the coarse grid with a grid-mapping type
744of interpolation; the dataset of weights and addresses has to be given
745by the user.
747For non-solar type of field ({\tt \$SUBTYPE = NONSOLAR}), a
748first-order Taylor expansion of the field on the fine grid relatively
749to a state variable is performed (for instance, an expansion of the
750total heat flux relatively to the SST):
751$$\Phi_{i} = F + \frac{\partial F}{\partial T} ( T_i - T ) $$ where
752$\Phi_{i}$ ($F$) is the heat flux on the fine (coarse) grid, $T_i$
753($T$) an auxiliary field on the fine (coarse) grid (e.g. the SST) and
754$\frac{\partial F}{\partial T}$ the derivative of the flux versus the
755auxiliary field on the coarse grid. This operation is interpolated
756from the coarse grid with a grid-mapping type of interpolation; the
757dataset of weights and addresses has to be given by the user.
759This analysis requires one input line with 7 or 8
760arguments depending on the type of subgrid interpolation.
763\item If the the {\tt SUBGRID} operation is performed on a solar flux,
764the 7-argument input line is:
766# SUBGRID operation with $SUBTYPE=SOLAR
767  $CFILE  $NUMLU  $NID  $NV  $SUBTYPE  $CCOARSE $CFINE\end{verbatim}where
768{\tt \$CFILE} and {\tt \$NUMLU} are the subgrid-mapping file name and
769associated logical unit (see section \ref{subsec_transformationdata} for the
770structure of this file); {\tt \$NID} the identificator for this
771subgrid-mapping dataset within the file build by OASIS based on all
772the different {\tt SUBGRID} analyses in the present coupling; {\tt
773\$NV} is the maximum number of target grid points use in the
774subgrid-mapping; {\tt \$SUBTYPE = SOLAR} is the type of subgrid
775  interpolation; {\tt \$CCOARSE} is the
776auxiliary field name on the coarse grid (corresponding to $\alpha$)
777and {\tt \$CFINE} is the auxiliary field name on fine grid
778(corresponding to $\alpha_i$).
779These two fields needs to be exchanged between their original model
780and OASIS3 main process, at least as {\tt AUXILARY} fields.
781This analysis is performed from the coarse grid with a grid-mapping type
782of interpolation based on the {\tt \$CFILE} file.
784\item If the the SUBGRID operation is performed on a nonsolar flux,
785the 8-argument input line is:
787# SUBGRID operation with $SUBTYPE=NONSOLAR
789\end{verbatim} where {\tt \$CFILE},  {\tt \$NUMLU},  {\tt \$NID}, 
790{\tt \$NV} are as for a solar subgrid interpolation; {\tt
791\$SUBTYPE = NONSOLAR}; {\tt \$CCOARSE} is the auxiliary
792field name on the coarse grid (corresponding to $T$) and {\tt \$CFINE}
793is the auxiliary field name on fine grid (corresponding to $T_i$); the
794additional argument {\tt \$CDQDT} is the coupling ratio on the coarse
795grid (corresponding to $\frac{\partial F}{\partial T}$) These three
796fields need to be exchanged between their original model and OASIS3
797main process as {\tt AUXILARY} fields. This operation is performed from the
798coarse grid with a grid-mapping type of interpolation based on the {\tt
799\$CFILE} file.
805\item {\bf BLASNEW}:
807{\tt BLASNEW} (routine {\tt /prism/src/mod/oasis3/src/blasnew.f}) performs a linear combination of the
808current coupling field with any other fields after the
809interpolation. These can be other coupling fields or constant fields.
811This analysis requires the same input line as {\tt BLASOLD}.
813\item {\bf MASKP}:
815A new analysis {\tt MASKP} can be used to mask the fields after
816interpolation. {\tt MASKP} has the same generic input line as {\tt MASK}.
820%subsection{The ``cooking'' stage}
822\section{The post-processing}
825The following analyses are available in the post-processing part of
826OASIS3, controlled by {\tt /prism/src/mod/oasis3/src/postpro.f}.
830\item {\bf REVERSE}:
832{\tt REVERSE} (routine {\tt /prism/src/mod/oasis3/src/reverse.f})
833reorders a field.
835This analysis requires the same input line as {\tt INVERT}, with {\tt
836\$CORLON} and {\tt \$CORLAT} being now the resulting orientation.
837{\tt REVERSE} does not work for U and D grids
838(see annexe \ref{subsec_gridtypes}).
840\item {\bf CHECKOUT}:
842{\tt CHECKOUT} (routine {\tt /prism/src/mod/oasis3/src/chkfld.f}) calculates
843the mean and extremum values of an output field and prints them to the
844coupler output {\em cplout}.
846The generic input line is as for {\tt CHECKIN}.
848\item {\bf GLORED} (not recommended as coupling fields can be directly
849 interpolated to a target Reduced grid, if needed):
852{\tt GLORED} performs a linear interpolation of field from a full
853Gaussian grid to a Reduced grid. When present, {\tt GLORED} must be the last
854analysis performed.
856Before doing the interpolation, non-masked values are automatically
857extrapolated to masked points with {\tt EXTRAP/NINENN} method (see
858above); to do so, the masked grid points are first replaced with a
859predefined value.  The required global grid mask must be
860present in data file {\tt masks} or {\tt} (see section
863The generic input line is as follows:
865# GLORED operation
866     $NNBRLAT  $NV   $NIO   $NID\end{verbatim} where {\tt \$NNBRLAT}
867is as for {\tt REDGLO} (see {\tt REDGLO} description above).
868The next 3 parameters refer to the {\tt EXTRAP/NINENN} extrapolation
869(see {\tt EXTRAP/NINENN} description above).  The value assigned to
870all land points before interpolation is given by {\tt amskred} in {\tt
871/prism/src/mod/oasis3/src/blkdata.f}; as for the {\tt \$VALMASK} in
872{\tt MASK} analysis, it has to be chosen well outside the range of
873your field values but not too large to avoid any representation problem.
877%subsection{The post-processing}
879%subsection{Input line(s) for each transformation}
Note: See TracBrowser for help on using the repository browser.