Changeset 3976
- Timestamp:
- 2013-07-16T11:28:29+02:00 (12 years ago)
- Location:
- trunk/DOC
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/DOC/NEMO_book.tex
r3294 r3976 23 23 \usepackage[margin=10pt,font={small},labelsep=colon,labelfont={bf}]{caption} % Gives small font for captions 24 24 \usepackage{enumitem} % allows non-bold description items 25 \usepackage{longtable} % allows multipage tables 25 26 %\usepackage{colortbl} % gives coloured panels behind table columns 26 27 -
trunk/DOC/TexFiles/Chapters/Chap_DIA.tex
r3940 r3976 1 1 % ================================================================ 2 % Chapter ÑI/O & Diagnostics2 % Chapter I/O & Diagnostics 3 3 % ================================================================ 4 4 \chapter{Ouput and Diagnostics (IOM, DIA, TRD, FLO)} … … 16 16 17 17 The model outputs are of three types: the restart file, the output listing, 18 and the output file(s). The restart file is used internally by the code when18 and the diagnostic output file(s). The restart file is used internally by the code when 19 19 the user wants to start the model with initial conditions defined by a 20 20 previous simulation. It contains all the information that is necessary in … … 25 25 that it is saved in the same binary format as the one used by the computer 26 26 that is to read it (in particular, 32 bits binary IEEE format must not be used for 27 this file). The output listing and file(s) are predefined but should be checked 27 this file). 28 29 The output listing and file(s) are predefined but should be checked 28 30 and eventually adapted to the user's needs. The output listing is stored in 29 31 the $ocean.output$ file. The information is printed from within the code on the … … 31 33 "\textit{grep -i numout}" in the source code directory. 32 34 33 By default, outpout files are written in NetCDF format but an IEEE output format, called DIMG, can be choosen when defining \key{dimgout}. Since version 3.2, when defining \key{iomput}, an I/O server has been added which provides more flexibility in the choice of the fields to be outputted as well as how the writing work is distributed over the processors in massively parallel computing. The complete description of the use of this I/O server is presented in next section. If neither \key{iomput} nor \key{dimgout} are defined, NEMO is producing NetCDF with the old IOIPSL library which has been kept for compatibility and its easy installation, but it is quite inefficient on parrallel machines. If \key{iomput} is not defined, output files are defined in the \mdl{diawri} module and containing mean (or instantaneous if \key{diainstant} is defined) values over a period of nn\_write time-step (namelist parameter). 35 By default, diagnostic output files are written in NetCDF format but an IEEE binary output format, called DIMG, can be choosen by defining \key{dimgout}. 36 37 Since version 3.2, when defining \key{iomput}, an I/O server has been added which provides more flexibility in the choice of the fields to be written as well as how the writing work is distributed over the processors in massively parallel computing. The complete description of the use of this I/O server is presented in the next section. 38 39 By default, if neither \key{iomput} nor \key{dimgout} are defined, NEMO produces NetCDF with the old IOIPSL library which has been kept for compatibility and its easy installation. However, the IOIPSL library is quite inefficient on parallel machines and, since version 3.2, many diagnostic options have been added presuming the use of \key{iomput}. The usefulness of the default IOIPSL-based option is expected to reduce with each new release. If \key{iomput} is not defined, output files and content are defined in the \mdl{diawri} module and contain mean (or instantaneous if \key{diainstant} is defined) values over a regular period of nn\_write time-steps (namelist parameter). 34 40 35 41 %\gmcomment{ % start of gmcomment … … 42 48 43 49 44 Since version 3.2, iomput is the NEMO output interface. It was designed to be simple to use, flexible and efficient. The two main purposes of iomput are: \\ 45 (1) the complete and flexible control of the output files through an external xml file defined by the user \\ 46 (2) to achieve high performance outputs through the distribution (or not) of all tasks related to output files on dedicated processes. \\ 47 The first functionality allows the user to specify, without touching anything into the code, the way he want to output data: \\ 48 - choice of output frequencies that can be different for each file (including real months and years) \\ 49 - choice of file contents: decide which data will be written in which file (the same data can be outputted in different files) \\ 50 - possibility to split output files at a choosen frequency \\ 51 - possibility to extract a vertical or an horizontal subdomain \\ 52 - choice of the temporal operation to perform: average, accumulate, instantaneous, min, max and once \\ 53 - extremely large choice of data available \\ 54 - redefine variables name and long\_name \\ 55 In addition, iomput allows the user to output any variable (scalar, 2D or 3D) in the code in a very easy way. All details of iomput functionalities are listed in the following subsections. Example of the iodef.xml files that control the outputs can be found here: NEMOGCM/CONFIG/ORCA2\_LIM/EXP00/iodef*.xml 56 57 The second functionality targets outputs performances when running on a very large number of processes. First, iomput provides the possibility to dedicate N specific processes (in addition to NEMO processes) to write the outputs, where N is big enough (and defined by the user) to suppress the bottle neck associated with the the writing of the output files. Since version 3.5, this interface depends on an external code called \href{http://forge.ipsl.jussieu.fr/ioserver}{XIOS}. This new IO server takes advantage of the new functionalitiy of NetCDF4 that allows the user to write files in parallel and therefore to bypass the rebuilding phase. Note that writting in parallel into the same NetCDF files requires that your NetCDF4 library is linked to an HDF5 library that has been correctly compiled (i.e. with the configure option $--$enable-parallel). Note that the files created by iomput trough xios are incompatible with NetCDF3. All post-processsing and visualization tools must therefore be compatible with NetCDF4 and not only NetCDF3. 58 59 \subsection{Basic knowledge} 60 50 Since version 3.2, iomput is the NEMO output interface of choice. It has been designed to be simple to use, flexible and efficient. The two main purposes of iomput are: 51 \begin{enumerate} 52 \item The complete and flexible control of the output files through external XML files adapted by the user from standard templates. 53 \item To achieve high performance and scalable output through the optional distribution of all diagnostic output related tasks to dedicated processes. 54 \end{enumerate} 55 The first functionality allows the user to specify, without code changes or recompilation, aspects of the diagnostic output stream, such as: 56 \begin{itemize} 57 \item The choice of output frequencies that can be different for each file (including real months and years). 58 \item The choice of file contents; includes complete flexibility over which data are written in which files (the same data can be written in different files). 59 \item The possibility to split output files at a choosen frequency. 60 \item The possibility to extract a vertical or an horizontal subdomain. 61 \item The choice of the temporal operation to perform, e.g.: average, accumulate, instantaneous, min, max and once. 62 \item Control over metadata via a large XML "database" of possible output fields. 63 \end{itemize} 64 In addition, iomput allows the user to add the output of any new variable (scalar, 2D or 3D) in the code in a very easy way. All details of iomput functionalities are listed in the following subsections. Examples of the XML files that control the outputs can be found in: 65 \begin{alltt} 66 \begin{verbatim} 67 NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef.xml 68 NEMOGCM/CONFIG/SHARED/field_def.xml 69 and 70 NEMOGCM/CONFIG/SHARED/domain_def.xml. 71 \end{verbatim} 72 \end{alltt} 73 74 The second functionality targets output performance when running in parallel (\key{mpp\_mpi}). Iomput provides the possibility to specify N dedicated I/O processes (in addition to the NEMO processes) to collect and write the outputs. With an appropriate choice of N by the user, the bottleneck associated with the writing of the output files can be greatly reduced. 75 76 Since version 3.5, the iom\_put interface depends on an external code called \href{http://forge.ipsl.jussieu.fr/ioserver}{XIOS}. This new IO server can take advantage of the parallel I/O functionality of NetCDF4 to create a single output file and therefore to bypass the rebuilding phase. Note that writing in parallel into the same NetCDF files requires that your NetCDF4 library is linked to an HDF5 library that has been correctly compiled (i.e. with the configure option $--$enable-parallel). Note that the files created by iomput through XIOS are incompatible with NetCDF3. All post-processsing and visualization tools must therefore be compatible with NetCDF4 and not only NetCDF3. 77 78 Even if not using the parallel I/O functionality of NetCDF4, using N dedicated I/O servers, where N is typically much less than the number of NEMO processors, will reduce the number of output files created. This can greatly reduce the post-processing burden usually associated with using large numbers of NEMO processors. Note that for smaller configurations, the rebuilding phase can be avoided, even without a parallel-enabled NetCDF4 library, simply by employing only one dedicated I/O server. 79 80 \subsection{XIOS: the IO\_SERVER} 81 82 \subsubsection{Attached or detached mode?} 83 84 Iomput is based on \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS}, the io\_server developed by Yann Meurdesoif from IPSL. The behaviour of the io subsystem is controlled by settings in the external XML files listed above. Key settings in the iodef.xml file are {\tt using\_server} and the {\tt type} tag associated with each defined file. The {\tt using\_server} setting determines whether or not the server will be used in ''attached mode'' (as a library) [{\tt false}] or in ''detached mode'' (as an external executable on N additional, dedicated cpus) [{\tt true}]. The ''attached mode'' is simpler to use but much less efficient for massively parallel applications. The type of each file can be either ''multiple\_file'' or ''one\_file''. 85 86 In attached mode and if the type of file is ''multiple\_file'', then each NEMO process will also act as an IO server and produce its own set of output files. Superficially, this emulates the standard behaviour in previous versions, However, the subdomain written out by each process does not correspond to the {\tt jpi x jpj x jpk} domain actually computed by the process (although it may if {\tt jpni=1}). Instead each process will have collected and written out a number of complete longitudinal strips. If the ''one\_file'' option is chosen then all processes will collect their longitudinal strips and write (in parallel) to a single output file. 87 88 In detached mode and if the type of file is ''multiple\_file'', then each stand-alone XIOS process will collect data for a range of complete longitudinal strips and write to its own set of output files. If the ''one\_file'' option is chosen then all XIOS processes will collect their longitudinal strips and write (in parallel) to a single output file. Note running in detached mode requires launching a Multiple Process Multiple Data (MPMD) parallel job. The following subsection provides a typical example but the syntax will vary in different MPP environments. 89 90 \subsubsection{Number of cpu used by XIOS in detached mode} 91 92 The number of cores used by the XIOS is specified when launching the model. The number of cores dedicated to XIOS should be from ~1/10 to ~1/50 of the number or cores dedicated to NEMO. Some manufacturers suggest using O($\sqrt{N}$) dedicated IO processors for N processors but this is a general recommendation and not specific to NEMO. It is difficult to provide precise recommendations because the optimal choice will depend on the particular hardware properties of the target system (parallel filesystem performance, available memory, memory bandwidth etc.) and the volume and frequency of data to be created. Here is an example of 2 cpus for the io\_server and 62 cpu for nemo using mpirun: 93 94 \texttt{ mpirun -np 62 ./nemo.exe : -np 2 ./xios\_server.exe } 95 96 \subsubsection{Control of XIOS: the XIOS context in iodef.xml} 97 98 As well as the {\tt using\_server} flag, other controls on the use of XIOS are set in the XIOS context in iodef.xml. See the XML basics section below for more details on XML syntax and rules. 99 100 \begin{tabular}{|p{4cm}|p{6.0cm}|p{2.0cm}|} 101 \hline 102 variable name & 103 description & 104 example \\ 105 \hline 106 \hline 107 buffer\_size & 108 buffer size used by XIOS to send data from NEMO to XIOS. Larger is more efficient. Note that needed/used buffer sizes are summarized at the end of the job & 109 25000000 \\ 110 \hline 111 buffer\_server\_factor\_size & 112 ratio between NEMO and XIOS buffer size. Should be 2. & 113 2 \\ 114 \hline 115 info\_level & 116 verbosity level (0 to 100) & 117 0 \\ 118 \hline 119 using\_server & 120 activate attached(false) or detached(true) mode & 121 true \\ 122 \hline 123 using\_oasis & 124 XIOS is used with OASIS(true) or not (false) & 125 false \\ 126 \hline 127 oasis\_codes\_id & 128 when using oasis, define the identifier of NEMO in the namcouple. Note that the identifier of XIOS is xios.x & 129 oceanx \\ 130 \hline 131 \end{tabular} 132 133 134 \subsection{Practical issues} 135 136 \subsubsection{Installation} 137 138 As mentioned, XIOS is supported separately and must be downloaded and compiled before it can be used with NEMO. See the installation guide on the \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS} wiki for help and guidance. NEMO will need to link to the compiled XIOS library. The 139 \href{http://www.nemo-ocean.eu/Using-NEMO/User-Guides/Basics/XIOS-IO-server-installation-and-use}{XIOS with NEMO} guide provides an example illustration of how this can be achieved. 140 141 \subsubsection{Add your own outputs} 142 143 It is very easy to add your own outputs with iomput. Many standard fields and diagnostics are already prepared (i.e., steps 1 to 3 below have been done) and simply need to be activated by including the required output in a file definition in iodef.xml (step 4). To add new output variables, all 4 of the following steps must be taken. 144 \begin{description} 145 \item[1.] in NEMO code, add a \\ 146 \texttt{ CALL iom\_put( 'identifier', array ) } \\ 147 where you want to output a 2D or 3D array. 148 149 \item[2.] If necessary, add \\ 150 \texttt{ USE iom\ \ \ \ \ \ \ \ \ \ \ \ ! I/O manager library } \\ 151 to the list of used modules in the upper part of your module. 152 153 \item[3.] in the field\_def.xml file, add the definition of your variable using the same identifier you used in the f90 code (see subsequent sections for a details of the XML syntax and rules). For example: 154 \vspace{-20pt} 155 \begin{alltt} {{\scriptsize 156 \begin{verbatim} 157 <field_definition> 158 <!-- T grid --> 159 160 <field_group id="grid_T" grid_ref="grid_T_3D"> 161 ... 162 <field id="identifier" long_name="blabla" ... /> 163 ... 164 </field_definition> 165 \end{verbatim} 166 }}\end{alltt} 167 Note your definition must be added to the field\_group whose reference grid is consistent with the size of the array passed to iomput. The grid\_ref attribute refers to definitions set in iodef.xml which, in turn, reference grids and axes either defined in the code (iom\_set\_domain\_attr and iom\_set\_axis\_attr in iom.F90) or defined in the domain\_def.xml file. E.g.: 168 \vspace{-20pt} 169 \begin{alltt} {{\scriptsize 170 \begin{verbatim} 171 <grid id="grid_T_3D" domain_ref="grid_T" axis_ref="deptht"/> 172 \end{verbatim} 173 }}\end{alltt} 174 Note, if your array is computed within the surface module each nn\_fsbc time\_step, 175 add the field definition within the field\_group defined with the id ''SBC'': $<$field\_group id=''SBC''...$>$ which has been defined with the correct frequency of operations (iom\_set\_field\_attr in iom.F90) 176 177 \item[4.] add your field in one of the output files defined in iodef.xml (again see subsequent sections for syntax and rules) \\ 178 \vspace{-20pt} 179 \begin{alltt} {{\scriptsize 180 \begin{verbatim} 181 <file id="file1" .../> 182 ... 183 <field field_ref="identifier" /> 184 ... 185 </file> 186 \end{verbatim} 187 }}\end{alltt} 188 189 \end{description} 190 \subsection{XML fundamentals} 61 191 62 192 \subsubsection{ XML basic rules} … … 72 202 73 203 The XML file used in XIOS is structured by 7 families of tags: context, axis, domain, grid, field, file and variable. Each tag family has hierarchy of three flavors (except for context): 74 \begin{description} 75 \item[root]: declaration of the root element that can contain element groups or elements, for example : $<$file\_definition ...$/>$ \\ 76 \item[group]: declaration of a group element that can contain element groups or elements, for example : $<$file\_group ...$/>$ \\ 77 \item[element]: declaration of an element that can contain elements, for example : $<$file ...$/>$ \\ 78 \end{description} 204 \\ 205 \begin{tabular}{|p{3.0cm}|p{4.5cm}|p{4.5cm}|} 206 \hline 207 flavor & 208 description & 209 example \\ 210 \hline 211 \hline 212 root & 213 declaration of the root element that can contain element groups or elements & 214 {\scriptsize \verb? < file_definition ... >?} \\ 215 \hline 216 group & 217 declaration of a group element that can contain element groups or elements & 218 {\scriptsize \verb? < file_group ... >?} \\ 219 \hline 220 element & 221 declaration of an element that can contain elements & 222 {\scriptsize \verb? < file ... >?} \\ 223 \hline 224 \end{tabular} 225 \\ 79 226 80 227 Each element may have several attributes. Some attributes are mandatory, other are optional but have a default value and other are are completely optional. Id is a special attribute used to identify an element or a group of elements. It must be unique for a kind of element. It is optional, but no reference to the corresponding element can be done if it is not defined. 81 228 82 The XML file is split into context tags that are used to isolate IO definition from different codes or different parts of a code. No interference is possible between 2 different contexts. Each context has its own calendar and an associated timestep. In NEMO, we used the following contexts (that can be defined in any order): 83 \begin{description} 84 \item[contex xios]: context containing informations for XIOS \\ 85 \verb? <context id="xios" ... ? 86 \item[context nemo]: contex containing IO informations for NEMO (mother grid when using AGRIF) \\ 87 \verb? <context id="nemo" ... ? 88 \item[context 1\_nemo]: contex containing IO informations for NEMO child grid 1 (when using AGRIF) \\ 89 \verb? <context id="1_nemo" ... ? 90 \item[context n\_nemo]: contex containing IO informations for NEMO child grid n (when using AGRIF) \\ 91 \verb? <context id="n_nemo" ... ? 92 \end{description} 93 94 Each context tag related to NEMO (mother or child grids) is divided into 5 parts (that can be defined in any order): 95 \begin{description} 96 \item[field definition]: define all variables that can potentially be outputted \\ 97 \verb? <field_definition ... ? 98 \item[file definition]: define the netcdf files to be created and the variables they will contain \\ 99 \verb? <file_definition ... ? 100 \item[axis definitions]: define vertical axis \\ 101 \verb? <axis_definition ... ? 102 \item[domain definitions]: define the horizontal grids \\ 103 \verb? <domain_definition ... ? 104 \item[grid definitions]: define the 2D and 3D grids (association of an axis and a domain) \\ 105 \verb? <grid_definition ... ? 106 \end{description} 107 108 the xios context contains only 1 tag: 109 \begin{description} 110 \item[variable definition]: define variables needed by xios. This can be seen as a kind of namelist for xios. \\ 111 \verb? <variable_definition ... ? 112 \end{description} 113 114 The XML file can be split in different parts to improve its readability and facilitate its use. The inclusing of XML files into the main XML file can be done through the attribute src: \\ 115 \verb? <context src="./nemo_def.xml" /> ? 116 In NEMO, by default, the field and domain définition is done in 2 séparate files: \\ 117 NEMOGCM/CONFIG/SHARED/field\_def.xml and \\ 118 NEMOGCM/CONFIG/SHARED/domain\_def.xml that are included in the main iodef.xml file through the following commands: \\ 119 \verb? <field_definition src="./field_def.xml" /> ? \\ 120 \verb? <domain_definition src="./domain_def.xml" /> ? 229 The XML file is split into context tags that are used to isolate IO definition from different codes or different parts of a code. No interference is possible between 2 different contexts. Each context has its own calendar and an associated timestep. In NEMO, we used the following contexts (that can be defined in any order):\\ 230 \\ 231 \begin{tabular}{|p{3.0cm}|p{4.5cm}|p{4.5cm}|} 232 \hline 233 context & 234 description & 235 example \\ 236 \hline 237 \hline 238 context xios & 239 context containing information for XIOS & 240 {\scriptsize \verb? <context id="xios" ... ?} \\ 241 \hline 242 context nemo & 243 context containing IO information for NEMO (mother grid when using AGRIF) & 244 {\scriptsize \verb? <context id="nemo" ... ?} \\ 245 \hline 246 context 1\_nemo & 247 context containing IO information for NEMO child grid 1 (when using AGRIF) & 248 {\scriptsize \verb? <context id="1_nemo" ... ?} \\ 249 \hline 250 context n\_nemo & 251 context containing IO information for NEMO child grid n (when using AGRIF) & 252 {\scriptsize \verb? <context id="n_nemo" ... ?} \\ 253 \hline 254 \end{tabular} 255 \\ 256 257 \noindent The xios context contains only 1 tag: 258 \\ 259 \begin{tabular}{|p{3.0cm}|p{4.5cm}|p{4.5cm}|} 260 \hline 261 context tag & 262 description & 263 example \\ 264 \hline 265 \hline 266 variable\_definition & 267 define variables needed by XIOS. This can be seen as a kind of namelist for XIOS. & 268 {\scriptsize \verb? <variable_definition ... ?} \\ 269 \hline 270 \end{tabular} 271 \\ 272 273 \noindent Each context tag related to NEMO (mother or child grids) is divided into 5 parts (that can be defined in any order):\\ 274 \\ 275 \begin{tabular}{|p{3.0cm}|p{4.5cm}|p{4.5cm}|} 276 \hline 277 context tag & 278 description & 279 example \\ 280 \hline 281 \hline 282 field\_definition & 283 define all variables that can potentially be outputted & 284 {\scriptsize \verb? <field_definition ... ?} \\ 285 \hline 286 file\_definition & 287 define the netcdf files to be created and the variables they will contain & 288 {\scriptsize \verb? <file_definition ... ?} \\ 289 \hline 290 axis\_definition & 291 define vertical axis & 292 {\scriptsize \verb? <axis_definition ... ?} \\ 293 \hline 294 domain\_definition & 295 define the horizontal grids & 296 {\scriptsize \verb? <domain_definition ... ?} \\ 297 \hline 298 grid\_definition & 299 define the 2D and 3D grids (association of an axis and a domain) & 300 {\scriptsize \verb? <grid_definition ... ?} \\ 301 \hline 302 \end{tabular} 303 \\ 304 305 \subsubsection{Nesting XML files} 306 307 The XML file can be split in different parts to improve its readability and facilitate its use. The inclusion of XML files into the main XML file can be done through the attribute src: \\ 308 {\scriptsize \verb? <context src="./nemo_def.xml" /> ?}\\ 309 310 \noindent In NEMO, by default, the field and domain definition is done in 2 separate files: 311 {\scriptsize \tt 312 \begin{verbatim} 313 NEMOGCM/CONFIG/SHARED/field_def.xml 314 and 315 NEMOGCM/CONFIG/SHARED/domain_def.xml 316 \end{verbatim} 317 } 318 \noindent that are included in the main iodef.xml file through the following commands: \\ 319 {\scriptsize \verb? <field_definition src="./field_def.xml" /> ? \\ 320 \verb? <domain_definition src="./domain_def.xml" /> ? } 121 321 122 322 123 323 \subsubsection{Use of inheritance} 124 324 125 XML extensively uses the concept of inheritance. XML has a based treestructure with a parent-child oriented relation: all children inherit attributes from parent, but an attribute defined in a child replace the inherited attribute value. Note that the special attribute ''id'' is never inherited. \\325 XML extensively uses the concept of inheritance. XML has a tree based structure with a parent-child oriented relation: all children inherit attributes from parent, but an attribute defined in a child replace the inherited attribute value. Note that the special attribute ''id'' is never inherited. \\ 126 326 \\ 127 example 1: Direct inheritance. \\ 327 example 1: Direct inheritance. 328 \vspace{-20pt} 128 329 \begin{alltt} {{\scriptsize 129 330 \begin{verbatim} 130 331 <field_definition operation="average" > 131 132 332 <field id="sst" /> <!-- averaged sst --> 333 <field id="sss" operation="instant"/> <!-- instantaneous sss --> 133 334 </field_definition> 134 335 \end{verbatim} … … 140 341 for example output instantaneous values instead of average values. \\ 141 342 \\ 142 example 2: Inheritance by reference. \\ 343 example 2: Inheritance by reference. 344 \vspace{-20pt} 143 345 \begin{alltt} {{\scriptsize 144 346 \begin{verbatim} 145 347 <field_definition> 146 147 348 <field id="sst" long_name="sea surface temperature" /> 349 <field id="sss" long_name="sea surface salinity" /> 148 350 </field_definition> 149 351 150 352 <file_definition> 151 152 153 154 353 <file id="myfile" output_freq="1d" /> 354 <field field_ref="sst" /> <!-- default def --> 355 <field field_ref="sss" long_name="my description" /> <!-- overwrite --> 356 </file> 155 357 </file_definition> 156 358 \end{verbatim} 157 359 }}\end{alltt} 158 Inherite (and overwrite, if needed) the attributes of a tag you are refering to. 159 160 \subsubsection{Use of Group} 161 162 Groups can be used fort 2 purposes. \\ 163 164 First, the group can be used to define common attributes to be shared by the elements of the group through the inheritance. In the following example, we define a group of field that will share a common grid ''grid\_T\_2D''. Note that for the field ''toce'', we overwrite the grid definition inherited from the group by ''grid\_T\_3D''. 360 Inherit (and overwrite, if needed) the attributes of a tag you are refering to. 361 362 \subsubsection{Use of Groups} 363 364 Groups can be used for 2 purposes. Firstly, the group can be used to define common attributes to be shared by the elements of the group through the inheritance. In the following example, we define a group of field that will share a common grid ''grid\_T\_2D''. Note that for the field ''toce'', we overwrite the grid definition inherited from the group by ''grid\_T\_3D''. 365 \vspace{-20pt} 165 366 \begin{alltt} {{\scriptsize 166 367 \begin{verbatim} 167 368 <field_group id="grid_T" grid_ref="grid_T_2D"> 168 169 170 171 369 <field id="toce" long_name="temperature" unit="degC" grid_ref="grid_T_3D"/> 370 <field id="sst" long_name="sea surface temperature" unit="degC" /> 371 <field id="sss" long_name="sea surface salinity" unit="psu" /> 372 <field id="ssh" long_name="sea surface height" unit="m" /> 172 373 ... 173 374 \end{verbatim} 174 375 }}\end{alltt} 175 376 176 Second , the group can be used to replace a list of elements. Several examples of groups of fields are proposed at the end of the file \\177 NEMOGCM/CONFIG/SHARED/field\_def.xml. For example, a short list of usual variables related to the U grid: 377 Secondly, the group can be used to replace a list of elements. Several examples of groups of fields are proposed at the end of the file {\tt CONFIG/SHARED/field\_def.xml}. For example, a short list of the usual variables related to the U grid: 378 \vspace{-20pt} 178 379 \begin{alltt} {{\scriptsize 179 380 \begin{verbatim} 180 381 <field_group id="groupU" > 181 182 183 382 <field field_ref="uoce" /> 383 <field field_ref="suoce" /> 384 <field field_ref="utau" /> 184 385 </field_group> 185 386 \end{verbatim} 186 387 }}\end{alltt} 187 that can be directly include in a file through the following syntaxe: 388 that can be directly include in a file through the following syntax: 389 \vspace{-20pt} 188 390 \begin{alltt} {{\scriptsize 189 391 \begin{verbatim} 190 392 <file id="myfile_U" output_freq="1d" /> 191 192 393 <field_group group_ref="groupU"/> 394 <field field_ref="uocetr_eff" /> <!-- add another field --> 193 395 </file> 194 396 \end{verbatim} … … 197 399 \subsection{Detailed functionalities } 198 400 199 The file NEMOGCM/CONFIG/ORCA2\_LIM/iodef\_demo.xmlprovides several examples of the use of the new functionalities offered by the XML interface of XIOS.401 The file {\tt NEMOGCM/CONFIG/ORCA2\_LIM/iodef\_demo.xml} provides several examples of the use of the new functionalities offered by the XML interface of XIOS. 200 402 201 403 \subsubsection{Define horizontal subdomains} 202 Horizontal subdomains are defined through the attributs zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj of the tag family domain. It must therefore be done in the domain part of the XML file. For example, in NEMOGCM/CONFIG/SHARED/domain\_def.xml, we provide the following example of a definition of a 5 by 5 box with the bottom left corner at point (10,10). 404 Horizontal subdomains are defined through the attributs zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj of the tag family domain. It must therefore be done in the domain part of the XML file. For example, in {\tt CONFIG/SHARED/domain\_def.xml}, we provide the following example of a definition of a 5 by 5 box with the bottom left corner at point (10,10). 405 \vspace{-20pt} 203 406 \begin{alltt} {{\scriptsize 204 407 \begin{verbatim} 205 408 <domain_group id="grid_T"> 206 409 <domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" /> 207 410 \end{verbatim} 208 411 }}\end{alltt} 209 412 The use of this subdomain is done through the redefinition of the attribute domain\_ref of the tag family field. For example: 413 \vspace{-20pt} 210 414 \begin{alltt} {{\scriptsize 211 415 \begin{verbatim} … … 216 420 }}\end{alltt} 217 421 Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain. The Equatorial section, the TAO, RAMA and PIRATA moorings are alredy registered in the code and can therefore be outputted without taking care of their (i,j) position in the grid. These predefined domains can be activated by the use of specific domain\_ref: ''EqT'', ''EqU'' or ''EqW'' for the equatorial sections and the mooring position for TAO, RAMA and PIRATA followed by ''T'' (for example: ''8s137eT'', ''1.5s80.5eT'' ...) 422 \vspace{-20pt} 218 423 \begin{alltt} {{\scriptsize 219 424 \begin{verbatim} … … 227 432 \subsubsection{Define vertical zooms} 228 433 Vertical zooms are defined through the attributs zoom\_begin and zoom\_end of the tag family axis. It must therefore be done in the axis part of the XML file. For example, in NEMOGCM/CONFIG/ORCA2\_LIM/iodef\_demo.xml, we provide the following example: 434 \vspace{-20pt} 229 435 \begin{alltt} {{\scriptsize 230 436 \begin{verbatim} … … 235 441 }}\end{alltt} 236 442 The use of this vertical zoom is done through the redefinition of the attribute axis\_ref of the tag family field. For example: 443 \vspace{-20pt} 237 444 \begin{alltt} {{\scriptsize 238 445 \begin{verbatim} … … 246 453 247 454 The output file names are defined by the attributs ''name'' and ''name\_suffix'' of the tag family file. for example: 455 \vspace{-20pt} 248 456 \begin{alltt} {{\scriptsize 249 457 \begin{verbatim} … … 258 466 \end{verbatim} 259 467 }}\end{alltt} 260 However it is also often very convienent to define the file name with the name of the experience, the output file frequency and the date of the beginning and the end of the simulation (which are informations stored either in the namelist or in the XML file). To do so, we added the following rule: if the id of the tag file is ''fileN''(where N = 1 to 99) or one of the predefined section or mooring (see next subsection), the following part of the name and the name\_suffix (that can be inherited) will be automatically replaced by:\\468 However it is often very convienent to define the file name with the name of the experience, the output file frequency and the date of the beginning and the end of the simulation (which are informations stored either in the namelist or in the XML file). To do so, we added the following rule: if the id of the tag file is ''fileN''(where N = 1 to 99) or one of the predefined section or mooring (see next subsection), the following part of the name and the name\_suffix (that can be inherited) will be automatically replaced by:\\ 261 469 \\ 262 470 \begin{tabular}{|p{4cm}|p{8cm}|} 263 471 \hline 264 \centering part of the name automatically to be replaced & 265 by \\ 472 \centering placeholder string & automatically replaced by \\ 266 473 \hline 267 474 \hline … … 284 491 ending date of the simulation (from nn\_date0 and nn\_itend in the namelist). \verb?yyyymmdd_hh:mm:ss? format \\ 285 492 \hline 286 \end{tabular} 493 \end{tabular}\\ 287 494 \\ 288 495 289 For example, 290 291 \begin{alltt} {{\scriptsize 496 \noindent For example, 497 {{\scriptsize 292 498 \begin{verbatim} 293 499 <file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" > 294 500 \end{verbatim} 295 }}\end{alltt} 296 297 With, in the namelist: 298 299 \begin{alltt} {{\scriptsize 501 }} 502 \noindent with the namelist: 503 {{\scriptsize 300 504 \begin{verbatim} 301 505 cn_exp = "ORCA2" … … 303 507 ln_rstart = .false. 304 508 \end{verbatim} 305 }}\end{alltt} 306 307 will give the following file name radical: 308 309 \begin{alltt} {{\scriptsize 509 }} 510 \noindent will give the following file name radical: 511 {{\scriptsize 310 512 \begin{verbatim} 311 513 myfile_ORCA2_19891231_freq1d 312 514 \end{verbatim} 313 }}\end{alltt} 314 515 }} 315 516 316 517 \subsubsection{Other controls of the xml attributes from NEMO} 317 518 318 The values of some attributes are automatically defined by NEMO (and any definition given in the xml file is overwritten). By convention, these attributes are defined to ''auto'' (for string) or ''0000'' (for integer) in the xml file (but this is not necessary).319 320 Here is the list of these attributes: 519 The values of some attributes are defined by subroutine calls within NEMO (calls to iom\_set\_domain\_attr, iom\_set\_axis\_attr and iom\_set\_field\_attr in iom.F90). Any definition given in the xml file will be overwritten. By convention, these attributes are defined to ''auto'' (for string) or ''0000'' (for integer) in the xml file (but this is not necessary). 520 521 Here is the list of these attributes:\\ 321 522 \\ 322 523 \begin{tabular}{|l|c|c|c|} … … 343 544 344 545 546 \subsection{XML reference tables} 547 345 548 \subsubsection{Tag list} 346 549 347 348 \begin{tabular}{|p{2cm}|p{2.5cm}|p{3.5cm}|p{2cm}|p{2cm}|} 550 \begin{longtable}{|p{2.2cm}|p{2.5cm}|p{3.5cm}|p{2.2cm}|p{1.6cm}|} 349 551 \hline 350 552 tag name & … … 352 554 accepted attribute & 353 555 child of & 354 parent of \\ 355 \hline 556 parent of \endhead 356 557 \hline 357 558 simulation & … … 362 563 \hline 363 564 context & 364 encapsulates parts of the xml file d édicated to different codes or different parts of a code &565 encapsulates parts of the xml file dedicated to different codes or different parts of a code & 365 566 id (''xios'', ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom), src, time\_origin & 366 567 simulation & 367 all root tags: ... \_definition \\568 all root tags: ... \_definition \\ 368 569 \hline 369 570 \hline … … 400 601 \hline 401 602 file & 402 defi le the contentof a file to be outputted &603 define the contents of a file to be outputted & 403 604 enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, split\_format, split\_freq, sync\_freq, type, src & 404 605 file\_definition, file\_group & 405 606 field \\ 406 \hline407 \end{tabular}408 \begin{tabular}{|p{2cm}|p{2.5cm}|p{3.5cm}|p{2cm}|p{2cm}|}409 \hline410 tag name &411 description &412 accepted attribute &413 child of &414 parent of \\415 \hline416 607 \hline 417 608 axis\_definition & … … 434 625 \hline 435 626 \hline 436 domain\_ definition &627 domain\_\-definition & 437 628 define all the horizontal domains potentially used by the variables & 438 629 src & 439 630 context & 440 domain\_ group, domain \\631 domain\_\-group, domain \\ 441 632 \hline 442 633 domain\_group & 443 634 encapsulates a group of horizontal domains & 444 635 id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj & 445 domain\_ definition, domain\_group &446 domain\_ group, domain \\636 domain\_\-definition, domain\_group & 637 domain\_\-group, domain \\ 447 638 \hline 448 639 domain & 449 640 define an horizontal domain & 450 641 id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj & 451 domain\_ definition, domain\_group &642 domain\_\-definition, domain\_group & 452 643 none \\ 453 644 \hline … … 471 662 none \\ 472 663 \hline 473 \end{ tabular}664 \end{longtable} 474 665 475 666 476 667 \subsubsection{Attributes list} 477 668 478 \begin{tabular}{|p{2cm}|p{4cm}|p{4cm}|p{2cm}|} 479 \hline 669 \begin{longtable}{|p{2.2cm}|p{4cm}|p{3.8cm}|p{2cm}|} 670 \hline 671 attribute name & 672 description & 673 example & 674 accepted by \endhead 675 \hline 676 axis\_ref & 677 refers to the id of a vertical axis & 678 axis\_ref="deptht" & 679 field, grid families \\ 680 \hline 681 enabled & 682 switch on/off the output of a field or a file & 683 enabled=".TRUE." & 684 field, file families \\ 685 \hline 686 default\_value & 687 missing\_value definition & 688 default\_value="1.e20" & 689 field family \\ 690 \hline 691 description & 692 just for information, not used & 693 description="ocean T grid variables" & 694 all tags \\ 695 \hline 696 domain\_ref & 697 refers to the id of a domain & 698 domain\_ref="grid\_T" & 699 field or grid families \\ 700 \hline 701 field\_ref & 702 id of the field we want to add in a file & 703 field\_ref="toce" & 704 field \\ 705 \hline 706 grid\_ref & 707 refers to the id of a grid & 708 grid\_ref="grid\_T\_2D" & 709 field family \\ 710 \hline 711 group\_ref & 712 refer to a group of variables & 713 group\_ref="mooring" & 714 field\_group \\ 715 \hline 716 id & 717 allow to identify a tag & 718 id="nemo" & 719 accepted by all tags except simulation \\ 720 \hline 721 level & 722 output priority of a field: 0 (high) to 10 (low)& 723 level="1" & 724 field family \\ 725 \hline 726 long\_name & 727 define the long\_name attribute in the NetCDF file & 728 long\_name="Vertical T levels" & 729 field \\ 730 \hline 731 min\_digits & 732 specify the minimum of digits used in the core number in the name of the NetCDF file & 733 min\_digits="4" & 734 file family \\ 735 \hline 736 name & 737 name of a variable or a file. If the name of a file is undefined, its id is used as a name & 738 name="tos" & 739 field or file families \\ 740 \hline 741 name\_suffix & 742 suffix to be inserted after the name and before the cpu number and the ''.nc'' termination of a file & 743 name\_suffix="\_myzoom" & 744 file family \\ 745 \hline 480 746 attribute name & 481 747 description & … … 484 750 \hline 485 751 \hline 486 axis\_ref & 487 refers to the id of a vertical axis & 488 axis\_ref="deptht" & 489 field, grid families \\ 490 \hline 491 enabled & 492 switch on/off the output of a field or a file & 493 enabled=".TRUE." & 494 field, file families \\ 495 \hline 496 default\_value & 497 missing\_value definition & 498 default\_value="1.e20" & 752 operation & 753 type of temporal operation: average, accumulate, instantaneous, min, max and once & 754 operation="average" & 499 755 field family \\ 500 756 \hline 501 description & 502 just for information, not used & 503 description="ocean T grid variables" & 504 all tags \\ 505 \hline 506 domain\_ref & 507 refers to the id of a domain & 508 domain\_ref="grid\_T" & 509 field or grid families \\ 510 \hline 511 field\_ref= & 512 id of the field we want to add in a file & 513 field\_ref="toce" & 757 output\_freq & 758 operation frequency. units can be ts (timestep), y, mo, d, h, mi, s. & 759 output\_freq="1d12h" & 760 field family \\ 761 \hline 762 output\_level & 763 output priority of variables in a file: 0 (high) to 10 (low). All variables listed in the file with a level smaller or equal to output\_level will be output. Other variables won't be output even if they are listed in the file. & 764 output\_level="10"& 765 file family \\ 766 \hline 767 positive & 768 convention used for the orientation of vertival axis (positive downward in \NEMO). & 769 positive="down" & 770 axis family \\ 771 \hline 772 prec & 773 output precision: real 4 or real 8 & 774 prec="4" & 775 field family \\ 776 \hline 777 split\_format & 778 date format used in the name of splitted output files. can be spécified using the following syntaxe: \%y, \%mo, \%d, \%h \%mi and \%s & 779 split\_format= "\%yy\%mom\%dd" & 780 file family \\ 781 \hline 782 split\_freq & 783 split output files frequency. units can be ts (timestep), y, mo, d, h, mi, s. & 784 split\_freq="1mo" & 785 file family \\ 786 \hline 787 src & 788 allow to include a file & 789 src="./field\_def.xml" & 790 accepted by all tags except simulation \\ 791 \hline 792 standard\_name & 793 define the standard\_name attribute in the NetCDF file & 794 standard\_name= "Eastward\_Sea\_Ice\_Transport" & 514 795 field \\ 515 796 \hline 516 grid\_ref & 517 refers to the id of a grid & 518 grid\_ref="grid\_T\_2D" & 519 field family \\ 520 \hline 521 group\_ref & 522 refer to a group of variables & 523 group\_ref="mooring" & 524 field\_group \\ 525 \hline 526 id & 527 allow to identify a tag & 528 id="nemo" & 529 accepted by all tags except simulation \\ 530 \hline 531 level & 532 output priority of a field: 0 (high) to 10 (low)& 533 level="1" & 534 field family \\ 535 \hline 536 long\_name & 537 define the long\_name attribute in the NetCDF file & 538 long\_name="Vertical T levels" & 539 field \\ 540 \hline 541 min\_digits & 542 specify the minimum of digits used in the core number in the name of the NetCDF file & 543 min\_digits="4" & 797 sync\_freq & 798 NetCDF file synchronization frequency (update of the time\_counter). units can be ts (timestep), y, mo, d, h, mi, s. & 799 sync\_freq="10d" & 544 800 file family \\ 545 801 \hline 546 name &547 name of a variable or a file. If the name of a file is undefined, its id is used as a name &548 name="tos" &549 field or file families \\550 \hline551 name\_suffix &552 suffix to be inserted after the name and before the cpu number and the ''.nc'' termination of a file &553 name\_suffix="\_myzoom" &554 file family \\555 \hline556 \end{tabular}557 \begin{tabular}{|p{2cm}|p{4cm}|p{4cm}|p{2cm}|}558 \hline559 802 attribute name & 560 803 description & … … 563 806 \hline 564 807 \hline 565 operation &566 type of temporal operation: average, accumulate, instantaneous, min, max and once &567 operation="average" &568 field family \\569 \hline570 output\_freq &571 operation frequency. units can be ts (timestep), y, mo, d, h, mi, s. &572 output\_freq="1d12h" &573 field family \\574 \hline575 output\_level &576 output priority of variables in a file: 0 (high) to 10 (low). All variables listed in the file with a level smaller or equal to output\_level will be output. Other variables won't be output even if they are listed in the file. &577 output\_level="10"&578 file family \\579 \hline580 positive &581 convention used for the orientation of vertival axis (positive downward in \NEMO). &582 positive="down" &583 axis family \\584 \hline585 prec &586 output precision: real 4 or real 8 &587 prec="4" &588 field family \\589 \hline590 split\_format &591 date format used in the name of splitted output files. can be spécified using the following syntaxe: \%y, \%mo, \%d, \%h \%mi and \%s &592 split\_format="\%yy\%mom\%dd" &593 file family \\594 \hline595 split\_freq &596 split output files frequency. units can be ts (timestep), y, mo, d, h, mi, s. &597 split\_freq="1mo" &598 file family \\599 \hline600 src &601 allow to include a file &602 src="./field\_def.xml" &603 accepted by all tags except simulation \\604 \hline605 standard\_name &606 define the standard\_name attribute in the NetCDF file &607 standard\_name="Eastward\_Sea\_Ice\_Transport" &608 field \\609 \hline610 sync\_freq &611 NetCDF file synchronization frequency (update of the time\_counter). units can be ts (timestep), y, mo, d, h, mi, s. &612 sync\_freq="10d" &613 file family \\614 \hline615 \end{tabular}616 \begin{tabular}{|p{2cm}|p{4cm}|p{4cm}|p{2cm}|}617 \hline618 attribute name &619 description &620 example &621 accepted by \\622 \hline623 \hline624 808 time\_origin & 625 809 specify the origin of the time counter & … … 628 812 \hline 629 813 type (1)& 630 specify if the output files must be split ted(multiple\_file) or not (one\_file) &814 specify if the output files must be split (multiple\_file) or not (one\_file) & 631 815 type="multiple\_file" & 632 816 file familly \\ … … 662 846 domain family \\ 663 847 \hline 664 \end{tabular} 665 666 \subsection{XIOS: the IO\_SERVER} 667 668 \subsubsection{Attached or detached mode?} 669 670 Iomput is based on \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS}, the io\_server developed by Yann Meurdesoif from IPSL. This server can be used in ''attached mode'' (as a library) or in ''detached mode'' (as an external executable on n cpus). The ''attached mode'' is simpler to use but much less efficient. If the type of file is ''multiple\_file'', then in attached(detached) mode, each NEMO(XIOS) process will output its own subdomain: if NEMO(XIOS) is runnning on N cores, the ouput files will be splitted into N files. If the type of file is ''one\_file'', the output files will be directly recombined into one unique file either in ''detached mode'' or ''attached mode''. 671 672 \subsubsection{Control of xios: the xios context in iodef.xml} 673 674 The control of the use of xios is done through the xios context in iodef.xml. 675 676 \begin{tabular}{|p{3cm}|p{6.5cm}|p{2.5cm}|} 677 \hline 678 variable name & 679 description & 680 example \\ 681 \hline 682 \hline 683 buffer\_size & 684 buffer size used by XIOS to send data from NEMO to XIOS. Larger is more efficient. Note that needed/used buffer sizes are summarized at the end of the job & 685 25000000 \\ 686 \hline 687 buffer\_server\_factor\_size & 688 ratio between NEMO and XIOS buffer size. Should be 2. & 689 2 \\ 690 \hline 691 info\_level & 692 verbosity level (0 to 100) & 693 0 \\ 694 \hline 695 using\_server & 696 activate attached(false) or detached(true) mode & 697 true \\ 698 \hline 699 using\_oasis & 700 xios is used with OASIS(true) or not (false) & 701 false \\ 702 \hline 703 oasis\_codes\_id & 704 when using oasis, define the identifier of NEMO in the namcouple. Not that the identifier of XIOS is xios.x & 705 oceanx \\ 706 \hline 707 \end{tabular} 708 709 \subsubsection{Number of cpu used by XIOS in detached mode} 710 711 The number of cores used by the xios is specified only when launching the model. The number or cores dedicated to XIOS should be from ~1/10 to ~1/50 of the number or cores dedicated to NEMO (according of the amount of data to be created). Here is an example of 2 cpus for the io\_server and 62 cpu for opa using mpirun: 712 713 \texttt{ mpirun -np 2 ./nemo.exe : -np 62 ./xios\_server.exe } 714 715 \subsection{Practical issues} 716 717 \subsubsection{Add your own outputs} 718 719 It is very easy to add you own outputs with iomput. 4 points must be followed. 720 \begin{description} 721 \item[1-] in NEMO code, add a \\ 722 \texttt{ CALL iom\_put( 'identifier', array ) } \\ 723 where you want to output a 2D or 3D array. 724 725 \item[2-] don't forget to add \\ 726 \texttt{ USE iom ! I/O manager library } \\ 727 in the list of used modules in the upper part of your module. 728 729 \item[3-] in the file\_definition part of the xml file, add the definition of your variable using the same identifier you used in the f90 code. 730 \vspace{-20pt} 731 \begin{alltt} {{\scriptsize 732 \begin{verbatim} 733 <field_definition> 734 ... 735 <field id="identifier" long_name="blabla" ... /> 736 ... 737 </field_definition> 738 \end{verbatim} 739 }}\end{alltt} 740 attributes axis\_ref and grid\_ref must be consistent with the size of the array to pass to iomput. 741 if your array is computed within the surface module each nn\_fsbc time\_step, 742 add the field definition within the group defined with the id ''SBC'': $<$group id=''SBC''...$>$ 743 744 \item[4-] add your field in one of the output files \\ 745 \vspace{-20pt} 746 \begin{alltt} {{\scriptsize 747 \begin{verbatim} 748 <file id="file1" .../> 749 ... 750 <field ref="identifier" /> 751 ... 752 </file> 753 \end{verbatim} 754 }}\end{alltt} 755 756 \end{description} 848 \end{longtable} 849 757 850 758 851 … … 809 902 domain size in any dimension. The algorithm used is: 810 903 904 \vspace{-20pt} 811 905 \begin{alltt} {{\scriptsize 812 906 \begin{verbatim}
Note: See TracChangeset
for help on using the changeset viewer.