# Changeset 3940

Ignore:
Timestamp:
2013-06-26T10:10:12+02:00 (9 years ago)
Message:

trunk: upgrade XIOS inteface, see #1122

Location:
trunk
Files:
10 edited

Unmodified
Removed
• ## trunk/DOC/TexFiles/Chapters/Chap_DIA.tex

 r3764 "\textit{grep -i numout}" in the source code directory. In the standard configuration, the user will find the model results in NetCDF files containing mean values (or instantaneous values if \key{diainstant} is defined) for every time-step where output is demanded. These outputs are defined in the \mdl{diawri} module. When defining \key{dimgout}, the output are written in DIMG format, an IEEE output format. Since version 3.2, an I/O server has been added which provides more flexibility in the choice of the fields to be output as well as how the writing work is distributed over the processors in massively parallel computing. It is presented in next section. 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). %\gmcomment{                    % start of gmcomment Since version 3.2, iom\_put is the NEMO output interface. It was designed to be simple to use, flexible and efficient. Two main functionalities are covered by iom\_put: (1) the control of the output files through an external xml file defined by the user ; (2) the distribution (or not) of all task related to output files on dedicated processors. The first functionality allows the user to specify, without touching anything into the code, the way he want to output data: \\ 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: \\ (1) the complete and flexible control of the output files through an external xml file defined by the user \\ (2) to achieve high performance outputs through the distribution (or not) of all tasks related to output files on dedicated processes. \\ The first functionality allows the user to specify, without touching anything into the code, the way he want to output data: \\ - choice of output frequencies that can be different for each file (including real months and years) \\ - choice of file contents: decide which data will be written in which file (the same data can be outputted in different files) \\ - possibility to extract a subdomain (for example all TAO-PIRATA-RAMA moorings are already defined)  \\ - choice of the temporal operation to perform: mean, instantaneous, min, max  \\ - choice of file contents: decide which data will be written in which file (the same data can be outputted in different files)  \\ - possibility to split output files at a choosen frequency \\ - possibility to extract a vertical or an horizontal subdomain  \\ - choice of the temporal operation to perform: average, accumulate, instantaneous, min, max and once  \\ - extremely large choice of data available   \\ - redefine variables name and long\_name  \\ In addition, iom\_put allows the user to output any variable (scalar, 2D or 3D) in the code in a very easy way. All details of iom\_put functionalities are listed in the following subsections. An example of the iodef.xml file that control the outputs can be found here: NEMOGCM/CONFIG/ORCA2\_LIM/EXP00/iodef.xml The second functionality targets outputs performances when running on a very large number of processes. The idea is to dedicate N specific processes to write the outputs, where N is defined by the user. In the current version, this functionality is technically working however, its performance are usually poor (for known reasons). Users can therefore test this functionality but they must be aware that expected performance improvement will not be achieved before the release 3.4. An example of xmlio\_server.def NEMOGCM/CONFIG/ORCA2\_LIM/EXP00/xmlio\_server.def 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 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. \subsection{Basic knowledge} \subsubsection{Structure of the xml file used in NEMO} The xml file is split into 3 parts: 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): \begin{description} \item[field definition]: define all variables that can be output \\ all lines in between the following two tags\\ \verb?    ?  \\ \verb?    ? \item[root]: declaration of the root element that can contain element groups or elements, for example : $<$file\_definition ...$/>$ \\ \item[group]: declaration of a group element that can contain element groups or elements, for example : $<$file\_group ...$/>$ \\ \item[element]: declaration of an element that can contain elements, for example : $<$file ...$/>$  \\ \end{description} 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. 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): \begin{description} \item[contex xios]: context containing informations for XIOS \\ \verb?    ?  \\ \verb?    ? \item[axis and grid definitions]: define the horizontal and vertical grids \\ all lines in between the following two set of two tags\\ \verb?    ?  \\ \verb?    ? and \\ \verb?    ?  \\ \verb?    ? \verb?    ? In NEMO, by default, the field and domain définition is done in 2 séparate files: \\ NEMOGCM/CONFIG/SHARED/field\_def.xml and \\ NEMOGCM/CONFIG/SHARED/domain\_def.xml that are included in the main iodef.xml file through the following commands: \\ \verb?    ? \\ \verb?    ? \subsubsection{Use of inheritance} XML extensively uses the concept of inheritance. XML has a based tree 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.  \\ \\ example 1: \\ \vspace{-30pt} example 1: Direct inheritance. \\ \begin{alltt}  {{\scriptsize \begin{verbatim}             \end{verbatim} }}\end{alltt} The field ''sst'' which is part (or a child) of the field\_definition will inherit the value ''ave(X)'' of the attribute ''operation'' from its parent ''field definition''. Note that a child can overwrite The field ''sst'' which is part (or a child) of the field\_definition will inherit the value ''average'' of the attribute ''operation'' from its parent. Note that a child can overwrite the attribute definition inherited from its parents. In the example above, the field ''sss'' will therefore output instantaneous values instead of average values. example 2: Use (or overwrite) attributes value of a field when listing the variables included in a file \vspace{-20pt} for example output instantaneous values instead of average values. \\ \\ example 2: Inheritance by reference. \\ \begin{alltt}  {{\scriptsize \begin{verbatim}         \end{verbatim} }}\end{alltt} With the help of the inheritance, the concept of group allow to define a set of attributes for several fields or files. example 3, group of fields: define a group ''T\_grid\_variables'' identified with the name ''grid\_T''. By default variables of this group have no vertical axis but, following inheritance rules, ''axis\_ref'' can be redefined for the field ''toce'' that is a 3D variable. \vspace{-30pt} \begin{alltt}  {{\scriptsize \begin{verbatim}   \end{verbatim} }}\end{alltt} example 4, group of files: define a group of file with the attribute output\_freq equal to 432000 (5 days) \vspace{-30pt} \begin{alltt}  {{\scriptsize \begin{verbatim}         Inherite (and overwrite, if needed) the attributes of a tag you are refering to. \subsubsection{Use of Group} Groups can be used fort 2 purposes. \\ 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''. \begin{alltt}  {{\scriptsize \begin{verbatim} ...     \end{verbatim} }}\end{alltt} 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 \\ NEMOGCM/CONFIG/SHARED/field\_def.xml. For example, a short list of usual variables related to the U grid: \begin{alltt}  {{\scriptsize \begin{verbatim} \end{verbatim} }}\end{alltt} that can be directly include in a file through the following syntaxe: \begin{alltt}  {{\scriptsize \begin{verbatim}   \end{verbatim} }}\end{alltt} \subsection{Detailed functionalities } The file NEMOGCM/CONFIG/ORCA2\_LIM/iodef\_demo.xml provides several examples of the use of the new functionalities offered by the XML interface of XIOS. \subsubsection{Define horizontal subdomains} 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). \begin{alltt}  {{\scriptsize \begin{verbatim} \end{verbatim} }}\end{alltt} The use of this subdomain is done through the redefinition of the attribute domain\_ref of the tag family field. For example: \begin{alltt}  {{\scriptsize \begin{verbatim} \end{verbatim} }}\end{alltt} 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'' ...) \begin{alltt}  {{\scriptsize \begin{verbatim} \end{verbatim} }}\end{alltt} Note that if the domain decomposition used in XIOS cuts the subdomain in several parts and if you use the ''multiple\_file'' type for your output files, you will endup with several files you will need to rebuild using unprovided tools (like ncpdq and ncrcat, \href{http://nco.sourceforge.net/nco.html#Concatenation}{see nco manual}). We are therefore advising to use the ''one\_file'' type in this case. \subsubsection{Define vertical zooms} 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: \begin{alltt}  {{\scriptsize \begin{verbatim} \end{verbatim} }}\end{alltt} The use of this vertical zoom is done through the redefinition of the attribute axis\_ref of the tag family field. For example: \begin{alltt}  {{\scriptsize \begin{verbatim} \end{verbatim} }}\end{alltt} \subsubsection{Control of the output file names} The output file names are defined by the attributs ''name'' and ''name\_suffix'' of the tag family file. for example: \begin{alltt}  {{\scriptsize \begin{verbatim} ... \end{verbatim} }}\end{alltt} \subsubsection{Control of the xml attributes from NEMO} 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). ... \end{verbatim} }}\end{alltt} 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: \\ \\ \begin{tabular}{|p{4cm}|p{8cm}|} \hline \centering part of the name automatically to be replaced & by \\ \hline \hline \centering @expname@ & the experience name (from cn\_exp in the namelist) \\ \hline \centering @freq@ & output frequency (from attribute output\_freq) \\ \hline \centering @startdate@  & starting date of the simulation (from nn\_date0 in the restart or the namelist). \verb?yyyymmdd? format \\ \hline \centering @startdatefull@  & starting date of the simulation (from nn\_date0 in the restart or the namelist). \verb?yyyymmdd_hh:mm:ss? format \\ \hline \centering @enddate@  & ending date of the simulation (from nn\_date0 and nn\_itend in the namelist). \verb?yyyymmdd? format \\ \hline \centering @enddatefull@  & ending date of the simulation (from nn\_date0 and nn\_itend in the namelist). \verb?yyyymmdd_hh:mm:ss? format \\ \hline \end{tabular} \\ For example, \begin{alltt}  {{\scriptsize \begin{verbatim} \end{verbatim} }}\end{alltt} With, in the namelist: \begin{alltt}  {{\scriptsize \begin{verbatim} cn_exp      =  "ORCA2" nn_date0    =  19891231 ln_rstart   = .false. \end{verbatim} }}\end{alltt} will give the following file name radical: \begin{alltt}  {{\scriptsize \begin{verbatim} myfile_ORCA2_19891231_freq1d \end{verbatim} }}\end{alltt} \subsubsection{Other controls of the xml attributes from NEMO} 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). Here is the list of these attributes: \\ \multicolumn{2}{|c|}{field\_definition} & freq\_op & \np{rn\_rdt} \\ \hline \multicolumn{2}{|c|}{SBC}                  & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_fsbc} \\ \hline 1h, 2h, 3h, 4h, 6h, 12h & \_grid\_T, \_grid\_U,  &  name & filename defined by   \\ 1d, 3d, 5d                     & \_grid\_V, \_grid\_W, &            & a call to rou{dia\_nam}  \\ 1m, 2m, 3m, 4m, 6m    & \_icemod, \_ptrc\_T,  &            & following NEMO \\ 1y, 2y, 5y, 10y               &  \_diad\_T, \_scalar   &            & nomenclature \\ \multicolumn{2}{|c|}{SBC}               & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_fsbc}  \\ \hline \multicolumn{2}{|c|}{ptrc\_T}           & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ \hline \multicolumn{2}{|c|}{diad\_T}           & freq\_op & \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ \hline \multicolumn{2}{|c|}{EqT, EqU, EqW} & jbegin, ni,      & according to the grid    \\ \multicolumn{2}{|c|}{                         } & name\_suffix &                                      \\ \hline \multicolumn{2}{|c|}{TAO, RAMA and PIRATA moorings} & ibegin, jbegin,      & according to the grid    \\ \multicolumn{2}{|c|}{TAO, RAMA and PIRATA moorings} & zoom\_ibegin, zoom\_jbegin, & according to the grid    \\ \multicolumn{2}{|c|}{                                                       } & name\_suffix &                                      \\ \hline \subsection{ Detailed functionalities } \subsubsection{Tag list} \begin{description} \item[context]: define the model using the xml file. Id is the only attribute accepted. Its value must be ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom. Child of simulation tag. \item[field]: define the field to be output. Accepted attributes are axis\_ref, description, enable, freq\_op, grid\_ref, id (if child of field\_definition), level, operation, name, ref (if child of file), unit, zoom\_ref. Child of field\_definition, file or group of fields tag. \item[field\_definition]: definition of the part of the xml file corresponding to the field definition. Accept the same attributes as field tag. Child of context tag. \item[group]: define a group of file or field. Accept the same attributes as file or field. \item[file]: define the output file's characteristics. Accepted attributes are description, enable, output\_freq, output\_level, id, name, name\_suffix. Child of file\_definition or group of files tag. \item[file\_definition]: definition of the part of the xml file corresponding to the file definition. Accept the same attributes as file tag. Child of context tag. \item[axis]: definition of the vertical axis. Accepted attributes are description, id, positive, size, unit. Child of axis\_definition tag. \item[axis\_definition]: definition of the part of the xml file corresponding to the vertical axis definition. Accept the same attributes as axis tag. Child of context tag \item[grid]: definition of the horizontal grid. Accepted attributes are description and id. Child of axis\_definition tag. \item[grid\_definition]: definition of the part of the xml file corresponding to the horizontal grid definition. Accept the same attributes as grid tag. Child of context tag \item[zoom]: definition of a subdomain of an horizontal grid. Accepted attributes are description, id, i/jbegin, ni/j. Child of grid tag. \end{description} \begin{tabular}{|p{2cm}|p{2.5cm}|p{3.5cm}|p{2cm}|p{2cm}|} \hline tag name & description & accepted attribute & child of & parent of \\ \hline \hline simulation & this tag is the root tag which encapsulates all the content of the xml file & none & none & context \\ \hline context & encapsulates parts of the xml file dédicated to different codes or different parts of a code & id (''xios'', ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom), src, time\_origin & simulation & all root tags: ...\_definition \\ \hline \hline field\_definition & encapsulates the definition of all the fields that can potentially be outputted & axis\_ref, default\_value, domain\_ref, enabled, grid\_ref, level, operation, prec, src & context & field or field\_group \\ \hline field\_group & encapsulates a group of fields & axis\_ref, default\_value, domain\_ref, enabled, group\_ref, grid\_ref, id, level, operation, prec, src & field\_definition, field\_group, file & field or field\_group \\ \hline field & define a specific field & axis\_ref, default\_value, domain\_ref, enabled, field\_ref, grid\_ref, id, level, long\_name, name, operation, prec, standard\_name, unit & field\_definition, field\_group, file & none \\ \hline \hline file\_definition & encapsulates the definition of all the files that will be outputted & enabled, min\_digits, name, name\_suffix, output\_level, split\_format, split\_freq, sync\_freq, type, src & context & file or file\_group \\ \hline file\_group & encapsulates a group of files that will be outputted & enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, split\_format, split\_freq, sync\_freq, type, src & file\_definition, file\_group & file or file\_group \\ \hline file & defile the contentof a file to be outputted & enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level, split\_format, split\_freq, sync\_freq, type, src & file\_definition, file\_group & field \\ \hline \end{tabular} \begin{tabular}{|p{2cm}|p{2.5cm}|p{3.5cm}|p{2cm}|p{2cm}|} \hline tag name & description & accepted attribute & child of & parent of \\ \hline \hline axis\_definition & define all the vertical axis potentially used by the variables & src & context & axis\_group, axis \\ \hline axis\_group & encapsulates a group of vertical axis & id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size & axis\_definition, axis\_group & axis\_group, axis \\ \hline axis & define a vertical axis & id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size & axis\_definition, axis\_group  & none \\ \hline \hline domain\_definition & define all the horizontal domains potentially used by the variables & src & context & domain\_group, domain \\ \hline domain\_group & encapsulates a group of horizontal domains & id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj & domain\_definition, domain\_group & domain\_group, domain \\ \hline domain & define an horizontal domain & id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj & domain\_definition, domain\_group & none \\ \hline \hline grid\_definition & define all the grid (association of a domain and/or an axis) potentially used by the variables & src & context & grid\_group, grid \\ \hline grid\_group & encapsulates a group of grids & id, domain\_ref, axis\_ref & grid\_definition, grid\_group & grid\_group, grid \\ \hline grid & define a grid & id, domain\_ref, axis\_ref & grid\_definition, grid\_group & none \\ \hline \end{tabular} \subsubsection{Attributes list} Applied to a tag or a group of tags. % table to be added ? Another table, perhaps? %%%% Attribute Applied to? Definition Comment axis\_ref field String defining the vertical axis of the variable. It refers to the id of the vertical axis defined in the axis tag. Use ''non'' if the variable has no vertical axis %%%%%% \begin{description} \item[axis\_ref]: field attribute. String defining the vertical axis of the variable. It refers to the id of the vertical axis defined in the axis tag. Use ''none'' if the variable has no vertical axis \item[description]: this attribute can be applied to all tags but it is used only with the field tag. In this case, the value of description will be used to define, in the output netcdf file, the attributes long\_name and standard\_name of the variable. \item[enabled]: field and file attribute. Logical to switch on/off the output of a field or a file. \item[freq\_op]: field attribute (automatically defined, see part 1.4 (''control of the xml attributes'')). An integer defining the frequency in seconds at which NEMO is calling iom\_put for this variable. It corresponds to the model time step (rn\_rdt in the namelist) except for the variables computed at the frequency of the surface boundary condition (rn\_rdt ? nn\_fsbc in the namelist). \item[grid\_ref]: field attribute. String defining the horizontal grid of the variable. It refers to the id of the grid tag. \item[ibegin]: zoom attribute. Integer defining the zoom starting point along x direction. Automatically defined for TAO/RAMA/PIRATA moorings (see part 1.4). \item[id]: exists for all tag. This is a string defining the name to a specific tag that will be used later to refer to this tag. Tags of the same category must have different ids. \item[jbegin]: zoom attribute. Integer defining the zoom starting point along y direction. Automatically defined for TAO/RAMA/PIRATA moorings and equatorial section (see part 1.4). \item[level]: field attribute. Integer from 0 to 10 defining the output priority of a field. See output\_level attribute definition \item[operation]: field attribute. String defining the type of temporal operation to perform on a variable. Possible choices are ''ave(X)'' for temporal mean, ''inst(X)'' for instantaneous, ''t\_min(X)'' for temporal min and ''t\_max(X)'' for temporal max. \item[output\_freq]: file attribute. Integer defining the operation frequency in seconds. For example 86400 for daily mean. \item[output\_level]: file attribute. Integer from 0 to 10 defining the output priority of variables in a file: 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. \item[positive]: axis attribute (always .FALSE.). Logical defining the vertical axis convention used in \NEMO (positive downward). Define the attribute positive of the variable in the netcdf output file. \item[prec]: field attribute. Integer defining the output precision. Not implemented, we always output real4 arrays. \item[name]: field or file attribute. String defining the name of a variable or a file. If the name of a file is undefined, its id is used as a name. 2 files must have different names. Files with specific ids will have their name automatically defined (see part 1.4). Note that is name will be automatically completed by the cpu number (if needed) and ''.nc'' \item[name\_suffix]: file attribute. String defining a suffix to be inserted after the name and before the cpu number and the ''.nc'' termination. Files with specific ids have an automatic definition of their suffix (see part 1.4). \item[ni]: zoom attribute. Integer defining the zoom extent along x direction. Automatically defined for equatorial sections (see part 1.4). \item[nj]: zoom attribute. Integer defining the zoom extent along x direction. \item[ref]: field attribute. String referring to the id of the field we want to add in a file. \item[size]: axis attribute. use unknown... \item[unit]: field attribute. String defining the unit of a variable and the associated attribute in the netcdf output file. \item[zoom\_ref]: field attribute. String defining the subdomain of data on which the file should be written (to ouput data only in a limited area). It refers to the id of a zoom defined in the zoom tag. \end{description} \subsection{IO\_SERVER} \begin{tabular}{|p{2cm}|p{4cm}|p{4cm}|p{2cm}|} \hline attribute name & description & example & accepted by \\ \hline \hline axis\_ref & refers to the id of a vertical axis & axis\_ref="deptht" & field, grid families \\ \hline enabled & switch on/off the output of a field or a file & enabled=".TRUE." & field, file families \\ \hline default\_value & missing\_value definition & default\_value="1.e20" & field family \\ \hline description & just for information, not used & description="ocean T grid variables" & all tags \\ \hline domain\_ref & refers to the id of a domain & domain\_ref="grid\_T" & field or grid families \\ \hline field\_ref= & id of the field we want to add in a file & field\_ref="toce" & field \\ \hline grid\_ref & refers to the id of a grid & grid\_ref="grid\_T\_2D" & field family \\ \hline group\_ref & refer to a group of variables & group\_ref="mooring" & field\_group \\ \hline id & allow to identify a tag & id="nemo" & accepted by all tags except simulation \\ \hline level & output priority of a field: 0 (high) to 10 (low)& level="1" & field family \\ \hline long\_name & define the long\_name attribute in the NetCDF file & long\_name="Vertical T levels" & field \\ \hline min\_digits & specify the minimum of digits used in the core number in the name of the NetCDF file & min\_digits="4" & file family \\ \hline name & name of a variable or a file. If the name of a file is undefined, its id is used as a name & name="tos" & field or file families \\ \hline name\_suffix & suffix to be inserted after the name and before the cpu number and the ''.nc'' termination of a file & name\_suffix="\_myzoom" & file family \\ \hline \end{tabular} \begin{tabular}{|p{2cm}|p{4cm}|p{4cm}|p{2cm}|} \hline attribute name & description & example & accepted by \\ \hline \hline operation & type of temporal operation: average, accumulate, instantaneous, min, max and once & operation="average" & field family \\ \hline output\_freq & operation frequency. units can be ts (timestep), y, mo, d, h, mi, s. & output\_freq="1d12h" & field family \\ \hline output\_level & 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. & output\_level="10"& file family \\ \hline positive & convention used for the orientation of vertival axis (positive downward in \NEMO). & positive="down" & axis family \\ \hline prec & output precision: real 4 or real 8 & prec="4" & field family \\ \hline split\_format & 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 & split\_format="\%yy\%mom\%dd" & file family \\ \hline split\_freq & split output files frequency. units can be ts (timestep), y, mo, d, h, mi, s. & split\_freq="1mo" & file family \\ \hline src & allow to include a file & src="./field\_def.xml" & accepted by all tags except simulation \\ \hline standard\_name & define the standard\_name attribute in the NetCDF file & standard\_name="Eastward\_Sea\_Ice\_Transport" & field \\ \hline sync\_freq & NetCDF file synchronization frequency (update of the time\_counter). units can be ts (timestep), y, mo, d, h, mi, s. & sync\_freq="10d" & file family \\ \hline \end{tabular} \begin{tabular}{|p{2cm}|p{4cm}|p{4cm}|p{2cm}|} \hline attribute name & description & example & accepted by \\ \hline \hline time\_origin & specify the origin of the time counter & time\_origin="1900-01-01 00:00:00"& context \\ \hline type (1)& specify if the output files must be splitted (multiple\_file) or not (one\_file) & type="multiple\_file" & file familly \\ \hline type (2)& define the type of a variable tag & type="boolean" & variable \\ \hline unit & unit of a variable or the vertical axis & unit="m" & field and axis families \\ \hline zoom\_ibegin & starting point along x direction of the zoom. Automatically defined for TAO/RAMA/PIRATA moorings & zoom\_ibegin="1" & domain family \\ \hline zoom\_jbegin & starting point along y direction of the zoom. Automatically defined for TAO/RAMA/PIRATA moorings & zoom\_jbegin="1" & domain family \\ \hline zoom\_ni & zoom extent along x direction & zoom\_ni="1" & domain family \\ \hline zoom\_nj & zoom extent along y direction & zoom\_nj="1" & domain family \\ \hline \end{tabular} \subsection{XIOS: the IO\_SERVER} \subsubsection{Attached or detached mode?} Iom\_put is based on the io\_server developed by Yann Meurdesoif from IPSL (see \href{http://forge.ipsl.jussieu.fr/ioserver/browser}{here} for the source code or see its copy in NEMOGCM/EXTERNAL directory). This server can be used in ''attached mode'' (as a library) or in ''detached mode'' (as an external executable on n cpus). In attached mode, each cpu of NEMO will output its own subdomain. In detached mode, the io\_server will gather data from NEMO and output them split over n files with n the number of cpu dedicated to the io\_server. \subsubsection{Control the io\_server: the namelist file xmlio\_server.def} % %Again, a small table might be more readable? %Name %Type %Description %Comment %Using_server %Logical %Switch to use the server in attached or detached mode %(.TRUE. corresponding to detached mode). The control of the use of the io\_server is done through the namelist file of the io\_server called xmlio\_server.def. \textbf{using\_server}: logical, switch to use the server in attached or detached mode (.TRUE. corresponding to detached mode). \textbf{using\_oasis}: logical, set to .TRUE. if NEMO is used in coupled mode. \textbf{client\_id} = ''oceanx'' : character, used only in coupled mode. Specify the id used in OASIS to refer to NEMO. The same id must be used to refer to NEMO in the \$NBMODEL part of OASIS namcouple in the call of prim\_init\_comp\_proto in cpl\_oasis3f90 \textbf{server\_id} = ''ionemo'' : character, used only in coupled mode. Specify the id used in OASIS to refer to the IO\_SERVER when used in detached mode. Use the same id to refer to the io\_server in the \$NBMODEL part of OASIS namcouple. \textbf{global\_mpi\_buffer\_size}: integer; define the size in Mb of the MPI buffer used by the io\_server. \subsubsection{Number of cpu used by the io\_server in detached mode} The number of cpu used by the io\_server is specified only when launching the model. Here is an example of 2 cpus for the io\_server and 6 cpu for opa using mpirun: \texttt{ -p 2 -e ./ioserver} \texttt{ -p 6 -e ./opa } 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''. \subsubsection{Control of xios: the xios context in iodef.xml} The control of the use of xios is done through the xios context in iodef.xml. \begin{tabular}{|p{3cm}|p{6.5cm}|p{2.5cm}|} \hline variable name & description & example \\ \hline \hline buffer\_size & 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 & 25000000 \\ \hline buffer\_server\_factor\_size & ratio between NEMO and XIOS buffer size. Should be 2. & 2 \\ \hline info\_level & verbosity level (0 to 100) & 0 \\ \hline using\_server & activate attached(false) or detached(true) mode & true \\ \hline using\_oasis & xios is used with OASIS(true) or not (false) & false \\ \hline oasis\_codes\_id & when using oasis, define the identifier of NEMO in the namcouple. Not that the identifier of XIOS is xios.x & oceanx \\ \hline \end{tabular} \subsubsection{Number of cpu used by XIOS in detached mode} 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: \texttt{ mpirun -np 2 ./nemo.exe : -np 62 ./xios\_server.exe } \subsection{Practical issues} \subsubsection{Add your own outputs} It is very easy to add you own outputs with iom\_put. 4 points must be followed. It is very easy to add you own outputs with iomput. 4 points must be followed. \begin{description} \item[1-] in NEMO code, add a \\ ... ... \end{verbatim} }}\end{alltt} attributes axis\_ref and grid\_ref must be consistent with the size of the array to pass to iom\_put. attributes axis\_ref and grid\_ref must be consistent with the size of the array to pass to iomput. if your array is computed within the surface module each nn\_fsbc time\_step, add the field definition within the group defined with the id ''SBC'': $<$group id=''SBC''...$>$ \begin{alltt}  {{\scriptsize \begin{verbatim} ... \end{description} \subsubsection{Several time axes in the output file} If your output file contains variables with different operations (see operation definition), IOIPSL will create one specific time axis for each operation. Note that inst(X) will have a time axis corresponding to the end each output period whereas all other operators will have a time axis centred in the middle of the output periods. \subsubsection{Error/bug messages from IOIPSL} If you get the following error in the standard output file: \vspace{-20pt} \begin{alltt}  {{\scriptsize \begin{verbatim} FATAL ERROR FROM ROUTINE flio_dom_set --> too many domains simultaneously defined --> please unset useless domains --> by calling flio_dom_unset \end{verbatim} }}\end{alltt} You must increase the value of dom\_max\_nb in fliocom.f90 (multiply it by 10 for example). If you mix, in the same file, variables with different freq\_op (see definition above), like for example variables from the surface module with other variables, IOIPSL will print in the standard output file warning messages saying there may be a bug. \vspace{-20pt} \begin{alltt}  {{\scriptsize \begin{verbatim} WARNING FROM ROUTINE histvar_seq --> There were 10 errors in the learned sequence of variables --> for file   4 --> This looks like a bug, please report it. \end{verbatim} }}\end{alltt} Don't worry, there is no bug, everything is properly working! %    }      %end  \gmcomment
• ## trunk/NEMOGCM/CONFIG/AMM12/EXP00/iodef.xml

 r3771 -->
• ## trunk/NEMOGCM/CONFIG/GYRE/EXP00/iodef.xml

 r3866 -->
• ## trunk/NEMOGCM/CONFIG/GYRE_BFM/EXP00/iodef.xml

 r3771 -->
• ## trunk/NEMOGCM/CONFIG/GYRE_PISCES/EXP00/iodef.xml

 r3771 -->
• ## trunk/NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef_ar5.xml

 r3771 -->                                                                                                   -->                                                         -->                                                         -->                                                         -->           -->                     -->
• ## trunk/NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef_default.xml

 r3771 -->
• ## trunk/NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef_demo.xml

 r3771 -->
• ## trunk/NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef_oldstyle.xml

 r3771 -->