1 | \newpage |
---|
2 | \chapter{The configuration file {\it namcouple}} |
---|
3 | \label{sec_namcouple} |
---|
4 | |
---|
5 | The OASIS3-MCT configuration file {\it namcouple} contains, below |
---|
6 | pre-defined keywords, all user's defined information necessary to |
---|
7 | configure a particular coupled run. |
---|
8 | |
---|
9 | The {\it namcouple} is a text file with the following characteristics: |
---|
10 | |
---|
11 | \begin{itemize} |
---|
12 | \item the keywords used to separate the information can appear in any |
---|
13 | order; |
---|
14 | \item the number of blanks between two character strings is |
---|
15 | non-significant; |
---|
16 | \item all lines beginning with \# are ignored and considered as |
---|
17 | comments. |
---|
18 | \item {\bf blank lines are not allowed.} |
---|
19 | \end{itemize} |
---|
20 | |
---|
21 | The first part of {\it namcouple } is devoted to configuration of |
---|
22 | general parameters such as the number of models involved in the |
---|
23 | simulation or the number of fields. The second part gathers specific |
---|
24 | information on each coupling (or I/O) field, e.g. their coupling |
---|
25 | period, the list of transformations or interpolations to be performed |
---|
26 | by OASIS3-MCT and associated configuring lines (described in more |
---|
27 | details in chapter \ref{sec_transformations}), etc. |
---|
28 | |
---|
29 | In OASIS3-MCT, several {\it namcouple} inputs have been deprecated |
---|
30 | but, for backwards compatibility, they are still allowed. These |
---|
31 | inputs will be noted in the following text using the notation |
---|
32 | ``UNUSED'' and not fully described. Information below these keywords |
---|
33 | is obsolete in OASIS3-MCT; it will not be read and will not be used. |
---|
34 | |
---|
35 | In the next sections, a simple {\it namcouple} example is given and |
---|
36 | all configuring parameters are described. The additional lines |
---|
37 | containing the different parameters required for each transformation |
---|
38 | are described in section \ref{sec_transformations}. A realistic {\it |
---|
39 | namcouple} can be found in {\tt |
---|
40 | oasis3-mct/examples/tutorial/data\_oasis3/} directory. |
---|
41 | |
---|
42 | \section{An example of a simple {\it namcouple}} |
---|
43 | \label{subsec_examplenamcouple} |
---|
44 | |
---|
45 | The following simple {\it namcouple} configures a run into which an |
---|
46 | ocean, an atmosphere and an atmospheric chemistry models are |
---|
47 | coupled. The ocean provides only the SOSSTSST field to the atmosphere, |
---|
48 | which in return provides the field CONSFTOT to the ocean. One field |
---|
49 | (COSENHFL) is exchanged from the atmosphere to the atmospheric |
---|
50 | chemistry, and one field (SOALBEDO) is read from a file by the ocean. |
---|
51 | |
---|
52 | \begin{verbatim} |
---|
53 | ###################################################################### |
---|
54 | # First section |
---|
55 | # |
---|
56 | $SEQMODE |
---|
57 | # |
---|
58 | $CHANNEL |
---|
59 | # |
---|
60 | $NFIELDS |
---|
61 | 4 |
---|
62 | # |
---|
63 | $JOBNAME |
---|
64 | # |
---|
65 | $NBMODEL |
---|
66 | 3 ocemod atmmod chemod 55 70 99 |
---|
67 | # |
---|
68 | $RUNTIME |
---|
69 | 432000 |
---|
70 | # |
---|
71 | $INIDATE |
---|
72 | # |
---|
73 | $MODINFO |
---|
74 | # |
---|
75 | $NLOGPRT |
---|
76 | 2 1 |
---|
77 | # |
---|
78 | $CALTYPE |
---|
79 | # |
---|
80 | ###################################################################### |
---|
81 | # Second section |
---|
82 | $STRINGS |
---|
83 | # |
---|
84 | # Field 1 |
---|
85 | SOSSTSST SISUTESU 1 86400 5 sstoc.nc EXPORTED |
---|
86 | 182 149 128 64 toce atmo LAG=+14400 SEQ=+1 |
---|
87 | P 2 P 0 |
---|
88 | LOCTRANS CHECKIN MAPPING BLASNEW CHECKOUT |
---|
89 | # |
---|
90 | AVERAGE |
---|
91 | INT=1 |
---|
92 | map_toce_atmo_120315.nc src opt |
---|
93 | 1.0 1 |
---|
94 | CONSTANT 273.15 |
---|
95 | INT=1 |
---|
96 | # |
---|
97 | # Field 2 |
---|
98 | CONSFTOT SOHEFLDO 6 86400 4 flxat.nc EXPORTED |
---|
99 | atmo toce LAG=+14400 SEQ=+2 |
---|
100 | P 0 P 2 |
---|
101 | LOCTRANS CHECKIN SCRIPR CHECKOUT |
---|
102 | # |
---|
103 | ACCUMUL |
---|
104 | INT=1 |
---|
105 | BILINEAR LR SCALAR LATLON 1 |
---|
106 | INT=1 |
---|
107 | # |
---|
108 | # Field 3 |
---|
109 | COSENHFL SOSENHFL 37 86400 1 flda3.nc IGNOUT |
---|
110 | atmo atmo LAG=+7200 |
---|
111 | LOCTRANS |
---|
112 | AVERAGE |
---|
113 | # |
---|
114 | # Field 4 |
---|
115 | SOALBEDO SOALBEDO 17 86400 0 SOALBEDO.nc INPUT |
---|
116 | ##################################################################### |
---|
117 | $END |
---|
118 | \end{verbatim} |
---|
119 | |
---|
120 | % section{An example of a simple {\it namcouple}} |
---|
121 | |
---|
122 | \section{ First section of {\it namcouple} file} |
---|
123 | \label{subsec_namcouplefirst} |
---|
124 | |
---|
125 | The first section of {\it namcouple } uses some predefined keywords |
---|
126 | prefixed by the \$ sign to locate the related information. The \$ sign |
---|
127 | must be in the second column. The first ten keywords are described |
---|
128 | hereafter: |
---|
129 | |
---|
130 | \begin{itemize} |
---|
131 | |
---|
132 | \item {\tt \$SEQMODE}: UNUSED |
---|
133 | |
---|
134 | \item {\tt \$CHANNEL}: UNUSED |
---|
135 | |
---|
136 | \item {\tt \$NFIELDS}: On the line below this keyword is the total |
---|
137 | number of field entries in the second part of the {\it |
---|
138 | namcouple}. If more than one field are described on the same line |
---|
139 | (new in OASIS3-MCT\_1.0, see appendix \ref{sec_changes_new}) this |
---|
140 | counts as only one entry. |
---|
141 | |
---|
142 | \item {\tt \$JOBNAME}: UNUSED |
---|
143 | |
---|
144 | \item {\tt \$NBMODEL}: On the line below this keyword is the number of |
---|
145 | models running in the given experiment followed by {\tt |
---|
146 | CHARACTER$\star$6} variables giving their names, which must |
---|
147 | correspond to the name announced by each model when calling {\tt |
---|
148 | oasis\_init\_comp} (second argument, see section |
---|
149 | \ref{subsubsec_Initialisation}). |
---|
150 | |
---|
151 | Then the user may indicate on the same line the maximum Fortran unit |
---|
152 | number used by the models. In the example, Fortran units above 55, |
---|
153 | 70, and 99 are free for respectively the ocean, atmosphere, and |
---|
154 | atmospheric chemistry models. {\bf In all cases, OASIS3-MCT library |
---|
155 | assumes, during the initialization phase, that units 1025 and 1026 |
---|
156 | are free and temporarily uses these units to read the {\it |
---|
157 | namcouple} and to write corresponding log messages to file {\tt |
---|
158 | nout.000000}.} After the initialization phase, OASIS3-MCT will |
---|
159 | still suppose that units above 1024 are free, unless maximum unit |
---|
160 | numbers are indicated here in the {\it namcouple}. |
---|
161 | % If {\tt \$CHANNEL} is {\tt NONE}, {\tt \$NBMODEL} has to be 0 and |
---|
162 | % there should be no model name and no unit number. |
---|
163 | |
---|
164 | \item {\tt \$RUNTIME}: On the line below this keyword is the total |
---|
165 | simulated time of the run, expressed in seconds (or any other time |
---|
166 | units as long as the same are used in all models and in the {\it |
---|
167 | namcouple}, see \ref{subsubsec_sendingreceiving}). |
---|
168 | % If {\tt \$CHANNEL} is {\tt NONE}, {\tt \$RUNTIME} has to be the |
---|
169 | % number of time occurrences of the field to interpolate from the |
---|
170 | % restart file. |
---|
171 | |
---|
172 | \item {\tt \$INIDATE}: UNUSED |
---|
173 | |
---|
174 | \item {\tt \$MODINFO}: UNUSED |
---|
175 | |
---|
176 | \item {\tt \$NLOGPRT}: The first and second numbers on the line below |
---|
177 | this keyword refer to the amount of debug and time statistic |
---|
178 | information written by OASIS3-MCT for each model and processor. |
---|
179 | |
---|
180 | The first number (that can be changed at runtime with the {\tt |
---|
181 | oasis\_set\_debug} routine, see section |
---|
182 | \ref{subsubsec_auxroutines}) may be: |
---|
183 | \begin{itemize} |
---|
184 | \item 0 : one file debug.root.xx is open by the master proces of |
---|
185 | each model and one file debug\_notroot.xx is open for all the |
---|
186 | other processes of each model to write only error information. |
---|
187 | \item 1 : one file debug.root.xx is open by the master proces of |
---|
188 | each model to write information equivalent to level 10 (see |
---|
189 | below); one file debug\_notroot.xx is open for all the other |
---|
190 | processes of each model to write error information. |
---|
191 | \item 2 : one file debug.xx.xxxxxx is open by each process of each |
---|
192 | model to write normal production diagnostics |
---|
193 | \item 5 : as for 2 with in addition some initial debug info |
---|
194 | \item 10: as for 5 with in addition the routine calling tree |
---|
195 | \item 12: as for 10 with in addition some routine calling notes |
---|
196 | \item 15: as for 12 with even more debug diagnostics |
---|
197 | \item 20: as for 15 with in addition some extra runtime analysis |
---|
198 | \item 30: full debug information |
---|
199 | \end{itemize} |
---|
200 | The second number defines how time statistics are written out to |
---|
201 | file {\tt *.timers\_xxxx}; it can be: |
---|
202 | \begin{itemize} |
---|
203 | \item 0 : nothing is calculated, nothing is written. |
---|
204 | \item 1 : some time statistics are calculated and written in a |
---|
205 | single file by the processor 0 as well as the min and the max |
---|
206 | times over all the processors. |
---|
207 | \item 2 : some time statistics are calculated and each processor |
---|
208 | writes its own file ; processor 0 also writes the min and the max |
---|
209 | times over all the processors in its file. |
---|
210 | \item 3 : some time statistics are calculated and each processor |
---|
211 | writes its own file ; processor 0 also writes in its file the min |
---|
212 | and the max times over all processors and also writes in its file |
---|
213 | all the results for each processor. |
---|
214 | \end{itemize} |
---|
215 | For more information on the time statistics written out, see section |
---|
216 | \ref{timestat}. |
---|
217 | |
---|
218 | \item {\tt \$CALTYPE}: UNUSED |
---|
219 | |
---|
220 | \end{itemize} |
---|
221 | |
---|
222 | % {Description of {\it namcouple} first section} |
---|
223 | |
---|
224 | \section{Second section of {\it namcouple} file } |
---|
225 | \label{subsec_namcouplesecond} |
---|
226 | |
---|
227 | The second part of the {\it namcouple}, starting after the keyword |
---|
228 | {\tt \$STRINGS}, contains coupling information for each coupling (or |
---|
229 | I/O) field. Its format depends on the field status given by the last |
---|
230 | entry on the field first line ({\tt EXPORTED}, {\tt IGNOUT} or {\tt |
---|
231 | INPUT} in the example above). The field may be : |
---|
232 | |
---|
233 | \begin{itemize} |
---|
234 | \item {\tt AUXILARY}: UNUSED |
---|
235 | \item {\tt EXPORTED}: exchanged between component models and |
---|
236 | transformed by OASIS3-MCT |
---|
237 | \item {\tt EXPOUT}: exchanged, transformed and also written to two |
---|
238 | debug NetCDF files, one before the sending action in the source |
---|
239 | model below the {\tt oasis\_put} call (after local transformations |
---|
240 | {\tt LOCTRANS} and {\tt BLASOLD} if present), and one after the |
---|
241 | receiving action in the target model below the {\tt oasis\_get} call |
---|
242 | (after all transformations). {\tt EXPOUT} should be used when |
---|
243 | debugging the coupled model only. The name of the debug NetCDF file |
---|
244 | (one per field) is automatically defined based on the field and |
---|
245 | component model names. |
---|
246 | \item {\tt IGNORED}: with OASIS3-MCT, this setting is equivalent to |
---|
247 | and converted to EXPORTED |
---|
248 | \item {\tt IGNOUT}: with OASIS3-MCT, this setting is equivalent to and |
---|
249 | converted to EXPOUT |
---|
250 | \item {\tt INPUT}: read in from the input file by the target model |
---|
251 | below the {\tt oasis\_get} call at |
---|
252 | appropriate times corresponding to the input period indicated by the |
---|
253 | user in the {\it namcouple}. See section \ref{subsec_inputdata} for |
---|
254 | the format of the input file. |
---|
255 | \item {\tt OUTPUT}: written out to an output debug NetCDF file by the |
---|
256 | source model below the {\tt oasis\_put} call, after local |
---|
257 | transformations {\tt LOCTRANS} and {\tt BLASOLD}, at appropriate |
---|
258 | times corresponding to the output period indicated by the user in |
---|
259 | the {\it namcouple}. |
---|
260 | |
---|
261 | \end{itemize} |
---|
262 | |
---|
263 | \subsection{Second section of {\it namcouple} for {\tt EXPORTED} and |
---|
264 | {\tt EXPOUT} fields} |
---|
265 | \label{subsubsec_secondEXPORTED} |
---|
266 | |
---|
267 | The first 3 lines for fields with status {\tt EXPORTED} and {\tt |
---|
268 | EXPOUT} are as follows: |
---|
269 | \begin{verbatim} |
---|
270 | SOSSTSST SISUTESU 1 86400 5 sstoc.nc EXPORTED |
---|
271 | 182 149 128 64 toce atmo LAG=+14400 SEQ=+1 |
---|
272 | P 2 P 0 |
---|
273 | \end{verbatim} |
---|
274 | %\vspace{-0.2cm} |
---|
275 | where the different entries are: |
---|
276 | \begin{itemize} |
---|
277 | \item Field first line: |
---|
278 | \begin{itemize} |
---|
279 | \item {\tt SOSSTSST} : symbolic name for the field in the source |
---|
280 | model ({\tt CHARACTER*128}). It has to match the argument {\tt name} |
---|
281 | of the corresponding field declaration in the source model; see |
---|
282 | {\tt oasis\_def\_var} in section \ref{subsubsec_Declaration} |
---|
283 | \item {\tt SISUTESU} : symbolic name for the field in the target |
---|
284 | model ({\tt CHARACTER*128}). It has to match the argument {\tt |
---|
285 | name} of the corresponding field declaration in the target |
---|
286 | model; see {\tt oasis\_def\_var} in section |
---|
287 | \ref{subsubsec_Declaration} |
---|
288 | \item 1 : UNUSED but still required for parsing |
---|
289 | \item 86400 : coupling and/or I/O period for the field, in seconds |
---|
290 | \item 5 : number of transformations to be performed by OASIS3 on |
---|
291 | this field |
---|
292 | \item sstoc.nc : name of the coupling restart file for the field |
---|
293 | ({\tt CHARACTER*8}); mandatory even if no coupling restart file is |
---|
294 | effectively used (for more detail, see section |
---|
295 | \ref{subsec_restartdata}) |
---|
296 | \item {\tt EXPORTED} : field status |
---|
297 | \end{itemize} |
---|
298 | \item Field second line: |
---|
299 | \begin{itemize} |
---|
300 | \item 182 : number of points for the source grid first dimension |
---|
301 | (optional) |
---|
302 | \item 149 : number of points for the source grid second dimension |
---|
303 | (optional)\footnote{For 1D field, put {\tt 1} as the second dimension} |
---|
304 | \item 128 : number of points for the target grid first dimension |
---|
305 | (optional) |
---|
306 | \item 64 : number of points for the target grid second dimension |
---|
307 | (optional)$^{1}$ |
---|
308 | |
---|
309 | {\bf These source and target grid dimensions are optional but note that |
---|
310 | in order to have 2D fields written as 2D arrays in the debug |
---|
311 | files, these dimensions must be provided in the {\it namcouple}; |
---|
312 | otherwise, the fields will be written out as 1D arrays.} |
---|
313 | |
---|
314 | \item toce : prefix of the source grid name in grid data files (see |
---|
315 | section \ref{subsec_griddata}) ({\tt CHARACTER*4}) |
---|
316 | \item atmo : prefix of the target grid name in grid data files ({\tt |
---|
317 | CHARACTER*4}) |
---|
318 | \item {\tt LAG=+14400}: optional lag index for the field (see section \ref{subsub_lag}) |
---|
319 | \item {\tt SEQ=+1}: optional sequence index for the field (see |
---|
320 | section \ref{subsec_sec}) |
---|
321 | \end{itemize} |
---|
322 | \item Field third line |
---|
323 | \begin{itemize} |
---|
324 | \item P : source grid first dimension characteristic (`P': |
---|
325 | periodical; `R': regional). |
---|
326 | \item 2 : source grid first dimension number of overlapping grid |
---|
327 | points. |
---|
328 | \item P : target grid first dimension characteristic (`P': |
---|
329 | periodical; `R': regional). |
---|
330 | \item 0 : target grid first dimension number of overlapping grid |
---|
331 | points. |
---|
332 | \end{itemize} |
---|
333 | |
---|
334 | \end{itemize} |
---|
335 | |
---|
336 | The fourth line gives the list of transformations to be performed for |
---|
337 | this field. In addition, there is one or more configuring lines |
---|
338 | describing some parameters for each transformation. These additional |
---|
339 | lines are described in more details in the chapter |
---|
340 | \ref{sec_transformations}. |
---|
341 | |
---|
342 | \subsection{Second section of {\it namcouple} for {\tt OUTPUT} fields} |
---|
343 | \label{subsubsec_secondOUTPUT} |
---|
344 | The first 2 lines for fields with status {\tt OUTPUT} are as follows: |
---|
345 | \begin{verbatim} |
---|
346 | COSHFTOT COSHFTOT 7 86400 0 fldhftot.nc OUTPUT |
---|
347 | atmo atmo |
---|
348 | \end{verbatim} |
---|
349 | % \vspace{-0.2cm} |
---|
350 | where the different entries are as for {\tt EXPOUT} fields, except |
---|
351 | that: |
---|
352 | \begin{itemize} |
---|
353 | \item the source symbolic name must be repeated twice on the field |
---|
354 | first line, |
---|
355 | \item the restart file name (here {\tt fldhftot.nc}) is needed only if |
---|
356 | a {\tt LOCTRANS} transformation is present, |
---|
357 | \item there is no output file name on the first line, |
---|
358 | \item there is no grid dimension\footnote{This means that all output |
---|
359 | fields will be written out in the output files as 1D arrays (this |
---|
360 | should be fixed in the next OASIS3-MCT version).} and no LAG or SEQ |
---|
361 | index on the second line; ; |
---|
362 | \end{itemize} |
---|
363 | The name of the output file is automatically defined based on the |
---|
364 | field and component model names. |
---|
365 | |
---|
366 | The third line is {\tt LOCTRANS} if this transformation is chosen for |
---|
367 | the field. Note that {\tt LOCTRANS} is the only transformation |
---|
368 | supported for {\tt OUTPUT} fields. |
---|
369 | |
---|
370 | \subsection{Second section of {\it namcouple} for {\tt INPUT} fields} |
---|
371 | \label{subsubsec_secondINPUT} |
---|
372 | |
---|
373 | The first and only line for fields with status {\tt INPUT} is: |
---|
374 | |
---|
375 | \begin{verbatim} |
---|
376 | SOALBEDO SOALBEDO 17 86400 0 SOALBEDO.nc INPUT |
---|
377 | \end{verbatim} |
---|
378 | \vspace{-0.5cm} |
---|
379 | where the different entries are: |
---|
380 | \begin{itemize} |
---|
381 | \item {\tt SOALBEDO}: symbolic name for the field in the target model |
---|
382 | ({\tt CHARACTER*128} repeated twice) |
---|
383 | \item 17: index in auxiliary file cf\_name\_table.txt (see above for |
---|
384 | EXPORTED fields) |
---|
385 | \item 86400: input period in seconds |
---|
386 | \item 0: number of transformations (always 0 for {\tt INPUT} fields) |
---|
387 | \item {\tt SOALBEDO.nc}: {\tt CHARACTER*32} giving the input file name |
---|
388 | (for more detail on its format, see section \ref{subsec_inputdata}) |
---|
389 | \item {\tt INPUT}: field status. |
---|
390 | \end{itemize} |
---|
391 | |
---|