Philippe 23/02/2016: lfi2cdf: modif for JPHEXT/=1
[MNH-git_open_source-lfs.git] / LIBTOOLS / readme / LATEX / extract.tex
1 \section{Dealing with diachronic files}
2 The Meso-NH program of post-processing ({\sc diag}) treats synchronous 
3 files from initialization or simulation. 
4 For a given need, one wants to work on fields stored in
5 a diachronic file before exploration with {\tt diaprog} or with another
6 graphical tool to possibly compare with observations.
7
8 \begin{itemize}
9 \item The \texttt{extractdia} tool allows to extract fields from a diachronic 
10 file, on the whole domain or on a part of it, to interpole them (horizontal
11 grid and/or vertical grid) and to write 
12 them in some other given formats (section \ref{extractdia}). 
13 This program is based on a routine of reading and a routine of writing of 
14 diachronic variables: 
15 they are the essential source lines to deal with a diachronic file.
16 These 2 routines can be used in the user own program to match his personal
17 needs. An example of such a program \texttt{exrwdia.f90} and how to compile it
18 is given in section \ref{exrwdia}.
19 \end{itemize}
20
21 Some other tools based on the 2 routines of reading and writing
22 are also available to allow easier comparisons with observation 
23 data (sections \ref{mnh2obs} and \ref{obs2mnh}):
24 \begin{itemize}
25 \item \texttt{mesonh2obs} to get MesoNH field values at given 
26 observation points (the format of output file is ASCII),
27 \item \texttt{obs2mesonh} to put observation values on a
28 given MesoNH grid (the output file has diachronic FM format),
29 observations can then be plotted with \texttt{diaprog} tool.
30 \item \texttt{compute\_r00\_pc} to catenate evolution of Lagrangian tracers 
31 back to the model start (as done in {\sc diag} program, see documentation 
32 ``Lagrangian trajectory and air-mass tracking analyses with
33 MesoNH by means of Eulerian passive tracers'', Gheusi and Stein, 2005).
34 \end{itemize}
35
36 The figure \ref{outils_dia} resumes the input and output of these tools.
37 \begin{figure}[htb] 
38 \centerline{\psfig{file=outils_dia.eps,width=10cm,angle=270} } 
39 \caption{\label{outils_dia}}
40 \end{figure}
41 \\
42
43 \underline{Remark}:
44  for all the following tools, the input diachronic files can be located
45 in another directory than the one in which the tool is invoked (as
46 for \texttt{diaprog}). In this case, initialise the following shell variable
47 \begin{verbatim}
48 export DIRLFI=directory_files_diachro
49 \end{verbatim}
50
51 Shell links will be automatically performed during the execution and
52 will be removed by the mesonh-shell-tool \texttt{rmlink} at the execution end.
53
54
55 \subsection{Extracte fields, domain, change format with
56 {\tt extractdia} tool}\label{extractdia}
57
58 The input file is a FM diachronic file, either a `true' diachronic one 
59 (its name is ended by {\bf .000} and it contains time series of informations 
60 obtained during the run of the model),
61 or a `pseudo'-diachronic one (it is the result of the conversion of a 
62 synchronous file, see section \ref{diachro_file}), compressed (with {\tt lfiz})
63 or not.
64
65 The format of the output file is chosen by the user among one of the following:
66 \begin{itemize}
67 \item a FM {\sc diac}hronic file, 
68 \item an ASCII file with 
69 {\sc l}atitude-{\sc l}ongitude-{\sc h}eight-{\sc v}alue or
70 latitude-longitude-height-value,
71 \item ASCII files with {\sc free} format defined by the user (one file per field),
72 \item a {\sc cdl} file (converted to NetCDF format at the end of the program,
73 with \texttt{ncgen} utility of NetCDF package inside the mesonh-shell-tool \texttt{tonetcdf}),
74 \item a {\sc grib} file (in the future),
75 \item a {\sc Vis5D} file (in the future).
76 \end{itemize}
77 The main program is an interactive one: 
78 the name of input diachronic file, the output format, 
79 the coordinates of the part of the domain,
80 the name of fields to be read and written are required.
81 All that is typed on keyboard is saved in {\tt dirextr.}fmt
82 file, it can be appended and used as input (after renaming it) for the next call
83 of the tool \\
84 (e.g. {\tt mv dirextr.DIAC dirDIAC1 ; extractdia < dirDIAC1}).
85 \\
86 \\
87 The advantages for each output format are the following:
88
89 \begin{itemize}
90 \item the wind direction (dd) and wind intensity (ff) could be asked.
91 \item fields are eventually interpolated according output format,
92 first vertically and then horizontally.
93 For vertical interpolation, the user specifies the type of levels (Z or P), 
94 the number of levels and their values (in m or in hPa). No vertical interpolation if the type of levels is K (model levels).
95
96 For horizontal interpolation on regular grid in longitude and latitude, the program chooses the optimum values computed for the model grid. 
97
98 If interpolations are required, the wind components are transformed in zonal and meridian components.
99
100 These interpolations do not allow interpolation in a required cross-section, the {\sc ficval} file obtained during a {\tt diaprog} session gives this interpolation.
101 \item for the {\sc diac}hronic format, the output file will be reduced in size
102 since it contains only some fields on a part of the domain without any interpolations .
103 It can still be plotted with {\tt diaprog}.
104 \item for the {\sc ll*v}/ll*v format, the fields can be interpolated onto a 
105 regular grid in longitude and latitude ({\sc lalo} option) or can remained on 
106 the conformal model grid.
107 ({\sc llzv}/llzv option for interpolation on constant altitude levels,
108 {\sc llpv}/llpv option for interpolation on constant pression levels
109 {\sc llhv}/lhzv option to stay on MesoNH vertical levels).
110 Three header lines give zoom, unit, variable name and temporal informations and
111 are followed by four values on each line.
112 \item for the {\sc cdl} format, the fields can be horizontally interpolated
113 onto a regular grid in longitude and latitude ({\sc lalo} option),
114 and eventually vertically on some prescribed levels 
115 ({\sc zcdl} option for interpolation on constant altitude levels,
116 {\sc pcdl} option for interpolation on constant pression levels,
117 {\sc kcdl} option to stay on MesoNH vertical levels).
118 The CDL format is transformed to binary Netdcf format at the end of the program run by the mesonh-shell-tool \texttt{tonetcdf}.
119 \item the {\sc free} format allows to get the interpolated values (vertical or horizontal interpolations) without any geographical locations: just values list are available after one header line.
120 \ignore{
121 \item for the {\sc grib} format, the fields can be horizontally interpolated
122 onto a regular grid in longitude and latitude and are vertically interpolated
123 on constant Z-levels or P-levels.
124 }%ignore
125 \end{itemize}
126
127
128 \subsection{Personal modifications: \texttt{exrwdia} program}\label{exrwdia}
129 The \texttt{extractdia} program uses 2 routines of reading
130 (\texttt{readvar.f90}) and writing (\texttt{writevar.f90}) of MesoNH variables
131 as they are stored in diachronic files (that is in 6-dimensional arrays).
132 These 2 routines can be used in your own program:
133 an example of such a program is \texttt{exrwdia.f90}.
134 The source code contains extended comments,
135 and there are some examples of computation with the extracted fields 
136 (module and direction of components of wind, interpolation on some Z levels, 
137 maximum of a 3D field along the vertical direction, vertical average between two
138 Z levels). 
139
140 The use of this method need to be familiar with the Mesonh specificities:
141  seven grids (Gal-Chen) for the storage of the variables, the U,V wind components are
142  referenced in the Mesonh grid and are different from the Uzonal and Vmeridian
143  components.
144
145 \subsubsection{Routines of reading and writing}
146 A diachronic file contain time series of informations that are
147 self-documented (section \ref{diachro_file}). 
148 The self-documentation is provided by the header of the file, which contains
149 a list of pre-defined records, and each field (or information)
150 is stored by several records, the number of them varies
151 from 8 to 11, according to the type of the information
152 ({\sc cart, mask, spxy, ssol, drst, rspl} or {\sc rapl}).
153
154 The subroutine \texttt{readvar.f90} reads the required field. At the first call,
155 the file is opened, its header is read 
156 (the dimensions of the total domain ({\sc imax, jmax, kmax}), 
157 the orography...)
158 and some characteristics are computed
159 (the conformal coordinates, the map factor...).
160 The required field is then read and available in a 6-dimensional array: 
161 {\sc xvar}(i,j,k,t,n,p)\footnote{For a whole description of the diachronic file
162 type, reader must refer to the original documentation on the Meso-NH web site:
163 ``{\sc cr\'eation et exploitation de fichiers diachroniques}, J. Duron''.}.
164
165 The subroutine \texttt{writevar.f90} writes the field if the wanted output
166 format is {\sc dia}chronic one.
167 If it is the first call the header is written, then
168 the field is stored by the same number of records than when it was read.
169
170
171 The personal code can be inserted in the main program between the call of the
172 two previous subroutines. For the {\sc free} format, the writing code lines
173 are to be written in the main program.
174
175 \subsubsection{Compilation}
176 You have to 
177 \begin{itemize}
178 \item create a sub-directory {\tt src} to put your own source files
179 \item copy {\tt\$MESONH/MAKE/tools/diachro/src/EXTRACTDIA/exrwdia.f90} to {\tt src/my\_prog.f90} and modify it
180 \item initialize the shell variable {\tt ARCH} which refers to your system and the compiler used (see 
181 examples as the suffix of files in {\tt \$MESONH/MAKE/conf} directory).
182 \item compile with \\
183 {\tt gmaketools PROG=my\_prog OBJS="my\_routine1.o my\_routine2.o" } \\ 
184 (the \$MESONH/MAKE/tools/diachro/{\tt Makefile.exrwdia} version will be used).
185 \end{itemize}
186
187 \noindent To update the routines dependances directly inside the  Makefile:
188 \begin{itemize}
189 \item initialize the following shell variables:
190 \begin{itemize}
191 \item {\tt MNH\_LIBTOOLS} which is the directory where the reference sources
192 for the libraries and tools are,
193 \item {\tt ARCH} which refers to your system and the compiler used (see 
194 examples as the suffix of files in {\tt \$MNH\_LIBTOOLS/conf} directory). 
195 \end{itemize}
196 \item copy the {\tt \$MNH\_LIBTOOLS/tools/diachro/Makefile.exrwdia} file in your working directory, 
197 rename it to \texttt{Makefile},
198 \item compile with {\tt gmake}
199 \end{itemize}
200
201
202 \subsection{Compare to observations with 
203 {\tt mesonh2obs} tool \label{mnh2obs}}
204 \subsubsection{Input and output}
205 The \texttt{mesonh2obs} tool allows to interpolate MesoNH fields 
206 at given points (such as points where observation data are available). 
207
208 The input files are an ASCII file indicated the position of the points by their
209 latitude and longitude coordinates as well as vertical dimension if a vertical profile is required, and one or several diachronic FM file(s) with fields to interpolate
210 at previous points.
211
212 Each output file, one for each input FM file, is an ASCII one with six possible
213 options for lines format
214 (\textsc{llhv}, llhv, \textsc{llzv}, llzv, \textsc{llpv}, llpv).
215
216 In the input ASCII file, each line indicates the location of one point,
217 all lines have the same format, one of the following :\\
218 \begin{tabular}{l|ll}
219  lon lat & and altitudes will be asked by the {\tt mesonh2obs} program\\
220  lat lon & and altitudes will be asked by the {\tt mesonh2obs} program\\
221  lon lat altitude(m) & \\
222  lat lon altitude(m) & \\   
223 \end{tabular} \\
224
225 The output ASCII file contains lines with the same format, one of the 
226 following according to the option: \\
227 \begin{tabular}{l|ll}
228  lon lat model\_level\_altitude(m)& option \textsc{llhv} \\
229  lat lon model\_level\_altitude(m)& option llhv \\
230  lon lat altitude(m) & option \textsc{llzv}&
231  --interpolation routine \texttt{zinter.f90} for 3D fields\\
232  lat lon altitude(m) & option llzv& \hspace*{1cm} " \\
233  lon lat pression(hPa) & option \textsc{llpv} &
234  --interpolation routine \texttt{pinter.f90} for 3D fields\\
235  lat lon pression(hPa) & option llpv& \hspace*{1cm} "   (pressure variable is read in input FM file) \\
236 \end{tabular} \\
237
238
239 \subsubsection{Usage}
240 The tool is an interactive one: the option for the lines format of the output
241 file, the name of the ASCII file with the location of
242 the observation points are first asked. 
243 Then the name of the input diachronic files is asked in a loop, and the 
244 name of the fields to interpolate in a second loop:
245 \begin{verbatim}
246     mesonh2obs << eof
247 format_output_file # line format of output file (LLHV/llhv/LLZV/llzv/LLPV/llpv)
248 format_input_file  # LL (lon,lat)ou ll (lat,lon)
249 altitude_in_input_file # O (altitude_in_m on the third colon)/N 
250 if N, number_vertical_levels # number of vertical levels above 
251                              # each lat,lon points
252       list_of_these_levels   # exemple: (in metres or hPa): 500 1500
253 obs_file                   # name of the Obs file 
254 0                          # control prints (0/1/2/3)
255 diachronic_file1           # file with fields to be interpolated (without .lfi)
256 field1_of_diachronic_file1 # field to be interpolated
257 field2_of_diachronic_file1
258 END                        # end of extraction in diachronic_file1
259 diachronic_file2           # file with fields to be interpolated (without .lfi)
260 fieldi_of_diachronic_file2 # field to be interpolated
261 fieldj_of_diachronic_file2
262 END                        # end of extraction in diachronic_file2
263 END                        # end of diachronic files list
264 eof
265 \end{verbatim}
266  
267  If \texttt{field\_of\_diachronic\_file} contains 'AC' string 
268 (for ACcumulated precipitation), you can substract values of the same field
269 from a previous diachronic file. Then after line 
270 \texttt{field('AC')\_of\_diachronic\_file}, answer the question: 
271 \begin{verbatim}
272 "- ACcumulated rain, do you want to make difference with a previous instant
273 (o\/O\/y\/Y\/n\/N) ?"
274 \end{verbatim}
275 if \texttt{Y$/$O}, indicate the name of \texttt{diachronic\_file\_previous}
276 (without .lfi) in a second supplementary line. 
277
278 \subsubsection{Method}
279 The main program retrieves first the $X$ and $Y$ conformal coordinates of each 
280 observation point, then for each read field interpolates it vertically 
281 if required (vertical profile field with option \textsc{llzv}, llzv, \textsc{llpv} or llpv, \textsc{llhv}, llhv),
282 and finally interpolates horizontally the field and the array of the vertical
283 profile.
284
285
286
287
288 \subsection{Compare to observations with 
289 \texttt{obs2mesonh} tool \label{obs2mnh}}
290 \subsubsection{Input and output}
291 The \texttt{obs2mesonh} tool allows to replace observations on a MesoNH grid.
292 The output file has diachronic FM format: it can be used as input for 
293 \texttt{diaprog} to plot observations in the same background as MesoNH fields.
294
295 The input files are one or several ASCII file(s), each of it contains the
296 values of one type of observation (one value per line, all lines have the same
297 format: (date-)lon-lat-(alt\_in\_meters-)value or 
298 (date-)lat-lon-(alt\_in\_meters-)value),
299 and a diachronic FM file which spatial grid will be
300 used to replace previous observation values.
301
302 The output file is a diachronic file with the orography and the grids of the
303 input diachronic one, each field corresponds to each input observation file.
304 One or two fields are added for each observation field treated: N\_field\_name 
305 for the number of observation averaged in each grid points and if 2D type, ALT\_field\_name for the altitudes of the observation.
306
307 \subsubsection{Usage}
308 The tool is an interactive one:
309 \begin{verbatim}
310     obs2mesonh << eof
311 file_diachronic_with_zs    # initialize MesoNH spatial and temporal grids
312 0/1/2/3                 # verbosity level
313 LL                      # format of obs file (LL=lon lat alt value, 
314                         #                     ll=lat lon alt value)
315 file1_obs               # name of obs file (undefined value=999.0)
316 name_new_field1         # name of the obs field  in output file
317 unit_new_field1         # free characters string for unit
318 1D/2D/3D                # profil of the  obs field 
319                         # for the 2D case, only K=1 will be initialised
320 LL                      # format of obs file (LL=lon lat alt value, 
321                         #                     ll=lat lon alt value)
322 file2_obs
323 name_new_field2
324 unit_new_field2
325 1D/2D/3D
326 END                     # closing of output diachronic file
327 eof
328 \end{verbatim}
329
330 \subsubsection{Method}
331 For each observation read in an input file: \\
332 - the MesoNH grid point I,J containing this observation is searching, \\
333 - then for observation with 3D profil, the vertical level K is searched
334 (the MesoNH vertical grid (Gal-Chen) at I,J is taken into account); 
335 for observation with 2D or 1D profil, the first level K=1 is attributed,\\
336 - the value of the observation is stored on grid point (I,J,K). \\
337 If several values are stored at the same grid point, arithmetic average of 
338 values is done (when unit is $dBz$, the average is computed in $Ze$).
339 If there is no values at a grid point, undefined value is put. 
340 The observations whose altitude is below the altitude of the first MesoNH level are stored at level K=1, a warning message is printed in this case.
341
342 The wind components are considered zonal and meridian in the observation and
343 are transformed to wind components in the Mesonh grid.
344
345 \subsubsection{Plotting with \texttt{diaprog}}
346 For plotting observation values with \texttt{diaprog}, you have to use the
347 pixel mode
348 \texttt{LSPOT=T}: this option is recommended for sparse data since there is
349 no interpolation of values for graphic plotting.
350 For superpose with simulated field, do not forget to fix the extrema
351 and interval of plotting for the 2 fields in order to compare them.
352 Here is an example of directives for \texttt{diaprog} to plot observed values
353 and superpose them with simulated fields:
354 \begin{verbatim}
355 LINVWB=T
356 !
357 LCOLAREA=T LISO=F 
358 LSPOT=T    ! no interpolation 
359 _file1_'file_obs'
360 T2M
361 y          ! yes to draw a black line around obs pixel
362 0 0
363 !
364 _file2_'file_sim'
365 NIMNMX=1 XDIAINT_T2M=2. XISOMIN_T2M=-8. XISOMAX_T2M=24.
366 T2M_ON_    ! for superpose
367 n          ! no black border
368 T2M_file1_
369 y          ! yes to draw a black line around obs pixel
370 0 0
371 quit
372 \end{verbatim}
373
374
375 \subsection{Catenation of Lagrangian trajectory with
376 \texttt{compute\_r00\_pc} tool}
377 \subsubsection{Input and output}
378 The \texttt{compute\_r00\_pc} tool allows to compute advanced 
379 diagnostics. 
380 related to Lagrangian tracers activated during the model simulation
381 (\texttt{LLG=.TRUE.} in namelist \texttt{NAM\_CONF}): it is based on the subroutine \texttt{compute\_r00} used in the DIAG program.
382 See section 2.2 of documentation
383 ``Lagrangian trajectory and air-mass tracking analyses with
384 MesoNH by means of Eulerian passive tracers'' (Gheusi and Stein, 2005).
385
386 The input files are one or several diachronic FM file(s) containing Lagrangian
387 tracers (\texttt{LGXM,LGYM,LGZM}) simply converted by \texttt{conv2dia} after
388 simulation, or after {\sc diag} (in the latter case, only Lagrangian
389 basic diagnostics were asked: \texttt{LTRAJ=.TRUE.} 
390 in namelist \texttt{NAM\_DIAG} with the namelist
391 \texttt{NAM\_STO\_FILE} empty, and additional diagnostic fields can be asked:
392 \texttt{CISO='EV'} and \texttt{LMOIST\_E=.T.} 
393 for the example of \ref{sss:compute.nam}), 
394 and an ASCII file named \texttt{compute\_r00.nam} with namelist format.
395
396 The output file is a diachronic file containing advanced diagnostics: initial
397  coordinates resulting from catenation process, initial values of basic 
398 diagnostic fields (present in the input diachronic files) that the Lagrangian
399 parcels had at initial time(s). 
400
401
402 \subsubsection{Usage} \label{sss:compute.nam}
403 The ASCII file \texttt{compute\_r00.nam} looks as the following:
404 \begin{verbatim}
405 &NAM_STO_FILE CFILES(1)='AR40_mc2_19990921.00d.Z',
406               CFILES(2)='AR40_mc2_19990920.12d.Z',
407               CFILES(3)='AR40_mc2_19990920.00d.Z',
408               CFILES(4)='AR40_mc2_19990919.12d.Z', 
409               CFILES(5)='AR40_mc2_19990919.00d.Z',
410               NSTART_SUPP(1)=3                   /
411 &NAM_FIELD  CFIELD_LAG(1)='THETAE',
412             CFIELD_LAG(2)='POVOM' /
413 \end{verbatim}
414 The namelist \texttt{NAM\_STO\_FILE} is the same as in the file
415  \texttt{DIAG1.nam}. The namelist \texttt{NAM\_FIELD} indicates the other
416 quantities for which initial values have to be computed.
417 \\
418
419 Then to run the tool,
420 \begin{verbatim}
421 #  initialise the following shell variable (optional if input file 
422 #  is in the current directory):
423 export DIRLFI=directory_files_diachro
424 #  initialise the variable ARCH (LXNAGf95 for PC, HPf90 for HP)
425 export ARCH=LXNAGf95
426 #  execute 
427 $MESONH/MAKE/tools/diachro/$ARCH/compute_r00_pc
428 \end{verbatim}
429
430
431
432 \subsubsection{Method}
433 The structure of the program and the interpolation subroutine
434  (\texttt{interpxyz}) are the same as in the {\sc diag} program,
435  the subroutines of reading and writing are those for handling diachronic files
436  (\texttt{readvar} and \texttt{writevar}).