Ignore:
Timestamp:
2018-03-06T17:12:34+01:00 (2 years ago)
Author:
nicolasmartin
Message:

Global reorganisation of DOC directory: refactoring & cleaning of TeX source code for readability

File:
1 edited

Legend:

Unmodified
Added
Removed
  • branches/2017/dev_merge_2017/DOC/texfiles/chapters/chap_DIA.tex

    r9373 r9376  
    8282in a very easy way. All details of iomput functionalities are listed in the following subsections.  
    8383Examples of the XML files that control the outputs can be found in: 
    84 \begin{alltt} 
    85 \begin{verbatim} 
    86   NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef.xml 
    87   NEMOGCM/CONFIG/SHARED/field_def.xml 
    88   and 
    89   NEMOGCM/CONFIG/SHARED/domain_def.xml. 
    90 \end{verbatim} 
    91 \end{alltt} 
     84\path{NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef.xml}, \path{NEMOGCM/CONFIG/SHARED/field_def.xml} and 
     85\path{NEMOGCM/CONFIG/SHARED/domain_def.xml}. 
    9286 
    9387The second functionality targets output performance when running in parallel (\key{mpp\_mpi}).  
     
    201195See the installation guide on the \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS} wiki for help and guidance.  
    202196NEMO will need to link to the compiled XIOS library.  
    203 The \href{http://www.nemo-ocean.eu/Using-NEMO/User-Guides/Basics/XIOS-IO-server-installation-and-use}{XIOS with NEMO}  
     197The \href{https://forge.ipsl.jussieu.fr/nemo/wiki/Users/ModelInterfacing/InputsOutputs#Inputs-OutputsusingXIOS}{XIOS with NEMO}  
    204198guide provides an example illustration of how this can be achieved. 
    205199 
     
    223217For example: 
    224218\vspace{-20pt} 
    225 \begin{alltt}  {{\scriptsize 
    226 \begin{verbatim} 
     219\begin{xmlcode} 
    227220   <field_definition> 
    228221      <!-- T grid --> 
     
    233226      ... 
    234227   </field_definition>  
    235 \end{verbatim} 
    236 }}\end{alltt}  
     228\end{xmlcode} 
    237229Note your definition must be added to the field\_group whose reference grid is consistent  
    238230with the size of the array passed to iomput.  
     
    241233or defined in the domain\_def.xml file. $e.g.$: 
    242234\vspace{-20pt} 
    243 \begin{alltt}  {{\scriptsize 
    244 \begin{verbatim} 
     235\begin{xmlcode} 
    245236     <grid id="grid_T_3D" domain_ref="grid_T" axis_ref="deptht"/> 
    246 \end{verbatim} 
    247 }}\end{alltt}  
     237\end{xmlcode} 
    248238Note, if your array is computed within the surface module each nn\_fsbc time\_step,  
    249239add the field definition within the field\_group defined with the id ''SBC'': $<$field\_group id=''SBC''...$>$  
     
    252242\item[4.] add your field in one of the output files defined in iodef.xml (again see subsequent sections for syntax and rules)   \\ 
    253243\vspace{-20pt} 
    254 \begin{alltt}  {{\scriptsize 
    255 \begin{verbatim} 
     244\begin{xmlcode} 
    256245   <file id="file1" .../>    
    257246      ... 
     
    259248      ... 
    260249   </file>    
    261 \end{verbatim} 
    262 }}\end{alltt}  
     250\end{xmlcode} 
    263251 
    264252\end{description} 
     
    394382  
    395383\noindent In NEMO, by default, the field and domain definition is done in 2 separate files: 
    396 {\scriptsize \tt 
    397 \begin{verbatim} 
    398 NEMOGCM/CONFIG/SHARED/field_def.xml 
    399 and 
    400 NEMOGCM/CONFIG/SHARED/domain_def.xml  
    401 \end{verbatim} 
    402 } 
     384\path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml} 
     385 
    403386\noindent that are included in the main iodef.xml file through the following commands: \\ 
    404387{\scriptsize \verb? <field_definition src="./field_def.xml" /> ? \\ 
     
    415398example 1: Direct inheritance. 
    416399\vspace{-20pt} 
    417 \begin{alltt}  {{\scriptsize     
    418 \begin{verbatim} 
     400\begin{xmlcode} 
    419401   <field_definition operation="average" > 
    420402     <field id="sst"                    />   <!-- averaged      sst -->  
    421403     <field id="sss" operation="instant"/>   <!-- instantaneous sss -->  
    422404   </field_definition>  
    423 \end{verbatim} 
    424 }}\end{alltt}  
    425  
     405\end{xmlcode} 
    426406The field ''sst'' which is part (or a child) of the field\_definition will inherit the value ''average''  
    427407of the attribute ''operation'' from its parent. Note that a child can overwrite  
     
    431411example 2: Inheritance by reference. 
    432412\vspace{-20pt} 
    433 \begin{alltt}  {{\scriptsize 
    434 \begin{verbatim} 
     413\begin{xmlcode} 
    435414   <field_definition> 
    436415     <field id="sst" long_name="sea surface temperature" />    
     
    444423     </file>    
    445424   </file_definition>  
    446 \end{verbatim} 
    447 }}\end{alltt}  
     425\end{xmlcode} 
    448426Inherit (and overwrite, if needed) the attributes of a tag you are refering to. 
    449427 
     
    455433Note that for the field ''toce'', we overwrite the grid definition inherited from the group by ''grid\_T\_3D''. 
    456434\vspace{-20pt} 
    457 \begin{alltt}  {{\scriptsize 
    458 \begin{verbatim} 
     435\begin{xmlcode} 
    459436   <field_group id="grid_T" grid_ref="grid_T_2D"> 
    460437    <field id="toce" long_name="temperature"             unit="degC" grid_ref="grid_T_3D"/> 
     
    463440    <field id="ssh"  long_name="sea surface height"      unit="m"                        /> 
    464441         ... 
    465 \end{verbatim} 
    466 }}\end{alltt}  
     442\end{xmlcode} 
    467443 
    468444Secondly, the group can be used to replace a list of elements.  
     
    470446For example, a short list of the usual variables related to the U grid: 
    471447\vspace{-20pt} 
    472 \begin{alltt}  {{\scriptsize 
    473 \begin{verbatim} 
     448\begin{xmlcode} 
    474449   <field_group id="groupU" > 
    475450    <field field_ref="uoce"  /> 
     
    477452    <field field_ref="utau"  /> 
    478453   </field_group> 
    479 \end{verbatim} 
    480 }}\end{alltt}  
     454\end{xmlcode} 
    481455that can be directly included in a file through the following syntax: 
    482456\vspace{-20pt} 
    483 \begin{alltt}  {{\scriptsize 
    484 \begin{verbatim} 
     457\begin{xmlcode} 
    485458   <file id="myfile_U" output_freq="1d" />    
    486459    <field_group group_ref="groupU"/>   
    487460    <field field_ref="uocetr_eff"  />  <!-- add another field --> 
    488461   </file>    
    489 \end{verbatim} 
    490 }}\end{alltt}  
     462\end{xmlcode} 
    491463 
    492464\subsection{Detailed functionalities } 
     
    501473of a 5 by 5 box with the bottom left corner at point (10,10). 
    502474\vspace{-20pt} 
    503 \begin{alltt}  {{\scriptsize 
    504 \begin{verbatim} 
     475\begin{xmlcode} 
    505476   <domain_group id="grid_T"> 
    506477    <domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" /> 
    507 \end{verbatim} 
    508 }}\end{alltt}  
     478\end{xmlcode} 
    509479The use of this subdomain is done through the redefinition of the attribute domain\_ref of the tag family field. For example: 
    510480\vspace{-20pt} 
    511 \begin{alltt}  {{\scriptsize 
    512 \begin{verbatim} 
     481\begin{xmlcode} 
    513482   <file id="myfile_vzoom" output_freq="1d" > 
    514483      <field field_ref="toce" domain_ref="myzoom"/> 
    515484   </file> 
    516 \end{verbatim} 
    517 }}\end{alltt}  
     485\end{xmlcode} 
    518486Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain.  
    519487The Equatorial section, the TAO, RAMA and PIRATA moorings are alredy registered in the code  
     
    523491by ''T'' (for example: ''8s137eT'', ''1.5s80.5eT'' ...) 
    524492\vspace{-20pt} 
    525 \begin{alltt}  {{\scriptsize 
    526 \begin{verbatim} 
     493\begin{xmlcode} 
    527494   <file id="myfile_vzoom" output_freq="1d" > 
    528495      <field field_ref="toce" domain_ref="0n180wT"/> 
    529496   </file> 
    530 \end{verbatim} 
    531 }}\end{alltt}  
     497\end{xmlcode} 
    532498Note 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. 
    533499 
     
    535501Vertical 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: 
    536502\vspace{-20pt} 
    537 \begin{alltt}  {{\scriptsize 
    538 \begin{verbatim} 
     503\begin{xmlcode} 
    539504   <axis_group id="deptht" long_name="Vertical T levels" unit="m" positive="down" > 
    540505      <axis id="deptht" /> 
    541506      <axis id="deptht_myzoom" zoom_begin="1" zoom_end="10" /> 
    542 \end{verbatim} 
    543 }}\end{alltt}  
     507\end{xmlcode} 
    544508The use of this vertical zoom is done through the redefinition of the attribute axis\_ref of the tag family field. For example: 
    545509\vspace{-20pt} 
    546 \begin{alltt}  {{\scriptsize 
    547 \begin{verbatim} 
     510\begin{xmlcode} 
    548511   <file id="myfile_hzoom" output_freq="1d" > 
    549512      <field field_ref="toce" axis_ref="deptht_myzoom"/> 
    550513   </file> 
    551 \end{verbatim} 
    552 }}\end{alltt}  
     514\end{xmlcode} 
    553515 
    554516\subsubsection{Control of the output file names} 
     
    556518The output file names are defined by the attributs ''name'' and ''name\_suffix'' of the tag family file. for example: 
    557519\vspace{-20pt} 
    558 \begin{alltt}  {{\scriptsize 
    559 \begin{verbatim} 
     520\begin{xmlcode} 
    560521   <file_group id="1d" output_freq="1d" name="myfile_1d" >  
    561522      <file id="myfileA" name_suffix="_AAA" > <!-- will create file "myfile_1d_AAA"  --> 
     
    566527      </file> 
    567528   </file_group> 
    568 \end{verbatim} 
    569 }}\end{alltt}  
     529\end{xmlcode} 
    570530However it is often very convienent to define the file name with the name of the experiment, 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 999 on 1 to 3 digits) or one of the predefined sections or moorings (see next subsection), the following part of the name and the name\_suffix (that can be inherited) will be automatically replaced by:\\ 
    571531\\ 
     
    653613 
    654614\vspace{-20pt} 
    655 \begin{alltt}  {{\scriptsize     
    656 \begin{verbatim} 
     615\begin{xmlcode} 
    657616 <field field\_ref="sst"  name="tosK"  unit="degK" > sst + 273.15 </field> 
    658617 <field field\_ref="taum" name="taum2" unit="N2/m4" long\_name="square of wind stress module" > taum * taum </field> 
    659618 <field field\_ref="qt"   name="stupid\_check" > qt - qsr - qns </field> 
    660 \end{verbatim} 
    661 }}\end{alltt}  
     619\end{xmlcode} 
    662620 
    663621(2) Simple computation: define a new variable and use it in the file definition. 
     
    665623in field\_definition: 
    666624\vspace{-20pt} 
    667 \begin{alltt}  {{\scriptsize     
    668 \begin{verbatim} 
     625\begin{xmlcode} 
    669626 <field id="sst2" long\_name="square of sea surface temperature" unit="degC2" >  sst * sst </field > 
    670 \end{verbatim} 
    671 }}\end{alltt}  
     627\end{xmlcode} 
    672628in file\_definition: 
    673629\vspace{-20pt} 
    674 \begin{alltt}  {{\scriptsize     
    675 \begin{verbatim} 
     630\begin{xmlcode} 
    676631 <field field\_ref="sst2" > sst2 </field> 
    677 \end{verbatim} 
    678 }}\end{alltt}  
     632\end{xmlcode} 
    679633Note that in this case, the following syntaxe $<$field field\_ref="sst2" /$>$ is not working as sst2 won't be evaluated. 
    680634 
     
    682636 
    683637\vspace{-20pt} 
    684 \begin{alltt}  {{\scriptsize     
    685 \begin{verbatim} 
     638\begin{xmlcode} 
    686639     <!-- force to keep real 8 --> 
    687640 <field field\_ref="sst" name="tos\_r8" prec="8" /> 
    688641      <!-- integer 2  with add\_offset and scale\_factor attributes --> 
    689642 <field field\_ref="sss" name="sos\_i2" prec="2" add\_offset="20." scale\_factor="1.e-3" /> 
    690 \end{verbatim} 
    691 }}\end{alltt}  
     643\end{xmlcode} 
    692644Note that, then the code is crashing, writting real4 variables forces a numerical convection from real8 to real4 which will create an internal error in NetCDF and will avoid the creation of the output files. Forcing double precision outputs with prec="8" (for example in the field\_definition) will avoid this problem. 
    693645 
     
    695647 
    696648\vspace{-20pt} 
    697 \begin{alltt}  {{\scriptsize     
    698 \begin{verbatim} 
     649\begin{xmlcode} 
    699650      <file\_group id="1d" output\_freq="1d" output\_level="10" enabled=".TRUE."> <!-- 1d files -->  
    700651   <file id="file1" name\_suffix="\_grid\_T" description="ocean T grid variables" > 
     
    707658       </file> 
    708659     </file\_group>  
    709 \end{verbatim} 
    710 }}\end{alltt}  
     660\end{xmlcode} 
    711661 
    712662(5) use of the ``@'' function: example 1, weighted temporal average 
     
    714664 - define a new variable in field\_definition 
    715665\vspace{-20pt} 
    716 \begin{alltt}  {{\scriptsize     
    717 \begin{verbatim} 
     666\begin{xmlcode} 
    718667 <field id="toce\_e3t" long\_name="temperature * e3t" unit="degC*m" grid\_ref="grid\_T\_3D" > toce * e3t </field > 
    719 \end{verbatim} 
    720 }}\end{alltt} 
     668\end{xmlcode} 
    721669 - use it when defining your file.   
    722670\vspace{-20pt} 
    723 \begin{alltt}  {{\scriptsize     
    724 \begin{verbatim} 
     671\begin{xmlcode} 
    725672<file\_group id="5d" output\_freq="5d"  output\_level="10" enabled=".TRUE." >  <!-- 5d files -->   
    726673 <file id="file1" name\_suffix="\_grid\_T" description="ocean T grid variables" > 
     
    728675 </file> 
    729676</file\_group>  
    730 \end{verbatim} 
    731 }}\end{alltt} 
     677\end{xmlcode} 
    732678The freq\_op="5d" attribute is used to define the operation frequency of the ``@'' function: here 5 day. The temporal operation done by the ``@'' is the one defined in the field definition: here we use the default, average. So, in the above case, @toce\_e3t will do the 5-day mean of toce*e3t. Operation="instant" refers to the temporal operation to be performed on the field''@toce\_e3t / @e3t'': here the temporal average is alreday done by the ``@'' function so we just use instant to do the ratio of the 2 mean values. field\_ref="toce" means that attributes not explicitely defined, are inherited from toce field. Note that in this case, freq\_op must be equal to the file output\_freq. 
    733679 
     
    736682 - define a new variable in field\_definition 
    737683\vspace{-20pt} 
    738 \begin{alltt}  {{\scriptsize     
    739 \begin{verbatim} 
     684\begin{xmlcode} 
    740685 <field id="ssh2" long\_name="square of sea surface temperature" unit="degC2" >  ssh * ssh </field > 
    741 \end{verbatim} 
    742 }}\end{alltt}  
     686\end{xmlcode} 
    743687 - use it when defining your file.   
    744688\vspace{-20pt} 
    745 \begin{alltt}  {{\scriptsize     
    746 \begin{verbatim} 
     689\begin{xmlcode} 
    747690<file\_group id="1m" output\_freq="1m"  output\_level="10" enabled=".TRUE." >  <!-- 1m files -->   
    748691 <file id="file1" name\_suffix="\_grid\_T" description="ocean T grid variables" > 
     
    750693 </file> 
    751694</file\_group>  
    752 \end{verbatim} 
    753 }}\end{alltt} 
     695\end{xmlcode} 
    754696The freq\_op="1m" attribute is used to define the operation frequency of the ``@'' function: here 1 month. The temporal operation done by the ``@'' is the one defined in the field definition: here we use the default, average. So, in the above case, @ssh2 will do the monthly mean of ssh*ssh. Operation="instant" refers to the temporal operation to be performed on the field ''sqrt( @ssh2 - @ssh * @ssh )'': here the temporal average is alreday done by the ``@'' function so we just use instant. field\_ref="ssh" means that attributes not explicitely defined, are inherited from ssh field. Note that in this case, freq\_op must be equal to the file output\_freq. 
    755697 
     
    758700 - define 2 new variables in field\_definition 
    759701\vspace{-20pt} 
    760 \begin{alltt}  {{\scriptsize     
    761 \begin{verbatim} 
     702\begin{xmlcode} 
    762703 <field id="sstmax" field\_ref="sst" long\_name="max of sea surface temperature" operation="maximum" /> 
    763704 <field id="sstmin" field\_ref="sst" long\_name="min of sea surface temperature" operation="minimum" /> 
    764 \end{verbatim} 
    765 }}\end{alltt}  
     705\end{xmlcode} 
    766706 - use these 2 new variables when defining your file.   
    767707\vspace{-20pt} 
    768 \begin{alltt}  {{\scriptsize     
    769 \begin{verbatim} 
     708\begin{xmlcode} 
    770709<file\_group id="1m" output\_freq="1m"  output\_level="10" enabled=".TRUE." >  <!-- 1m files -->   
    771710 <file id="file1" name\_suffix="\_grid\_T" description="ocean T grid variables" > 
     
    773712 </file> 
    774713</file\_group>  
    775 \end{verbatim} 
    776 }}\end{alltt} 
     714\end{xmlcode} 
    777715The freq\_op="1d" attribute is used to define the operation frequency of the ``@'' function: here 1 day. The temporal operation done by the ``@'' is the one defined in the field definition: here maximum for sstmax and minimum for sstmin. So, in the above case, @sstmax will do the daily max and @sstmin the daily min. Operation="average" refers to the temporal operation to be performed on the field ``@sstmax - @sstmin'': here monthly mean (of daily max - daily min of the sst). field\_ref="sst" means that attributes not explicitely defined, are inherited from sst field. 
    778716 
     
    11141052 
    11151053%------------------------------------------namnc4---------------------------------------------------- 
    1116 \namdisplay{namnc4} 
     1054\fortranfile{namelists/namnc4} 
    11171055%------------------------------------------------------------------------------------------------------------- 
    11181056 
     
    11421080 
    11431081\vspace{-20pt} 
    1144 \begin{alltt}  {{\scriptsize  
    1145 \begin{verbatim} 
     1082\begin{fortrancode} 
    11461083     ichunksz(1) = MIN( idomain_size,MAX( (idomain_size-1)/nn_nchunks_i + 1 ,16 ) ) 
    11471084     ichunksz(2) = MIN( jdomain_size,MAX( (jdomain_size-1)/nn_nchunks_j + 1 ,16 ) ) 
    11481085     ichunksz(3) = MIN( kdomain_size,MAX( (kdomain_size-1)/nn_nchunks_k + 1 , 1 ) ) 
    11491086     ichunksz(4) = 1 
    1150 \end{verbatim} 
    1151 }}\end{alltt}  
     1087\end{fortrancode} 
    11521088 
    11531089\noindent As an example, setting: 
    11541090\vspace{-20pt} 
    1155 \begin{alltt}  {{\scriptsize 
    1156 \begin{verbatim} 
     1091\begin{fortrancode} 
    11571092     nn_nchunks_i=4, nn_nchunks_j=4 and nn_nchunks_k=31 
    1158 \end{verbatim} 
    1159 }}\end{alltt} \vspace{-10pt} 
     1093\end{fortrancode} 
    11601094 
    11611095\noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\tt 46x38x1} 
     
    12221156 
    12231157%------------------------------------------namtrd---------------------------------------------------- 
    1224 \namdisplay{namtrd}  
     1158\fortranfile{namelists/namtrd}  
    12251159%------------------------------------------------------------------------------------------------------------- 
    12261160 
     
    12611195\label{FLO} 
    12621196%--------------------------------------------namflo------------------------------------------------------- 
    1263 \namdisplay{namflo}  
     1197\fortranfile{namelists/namflo}  
    12641198%-------------------------------------------------------------------------------------------------------------- 
    12651199 
     
    13411275 
    13421276\vspace{-30pt} 
    1343 \begin{alltt}  {{\scriptsize 
    1344 \begin{verbatim} 
    1345  
     1277\begin{xmlcode} 
    13461278     <group id="1d\_grid\_T" name="auto" description="ocean T grid variables" >   } 
    13471279       <file id="floats"  description="floats variables"> }\\ 
     
    13551287       </file>} 
    13561288  </group>} 
    1357  
    1358 \end{verbatim} 
    1359 }}\end{alltt} 
     1289\end{xmlcode} 
    13601290 
    13611291 
     
    13751305 
    13761306%------------------------------------------namdia_harm---------------------------------------------------- 
    1377 \namdisplay{namdia_harm} 
     1307%\fortranfile{namelists/namdia_harm} 
    13781308%---------------------------------------------------------------------------------------------------------- 
    13791309 
     
    14171347 
    14181348%------------------------------------------namdct---------------------------------------------------- 
    1419 \namdisplay{namdct} 
     1349\fortranfile{namelists/namdct} 
    14201350%------------------------------------------------------------------------------------------------------------- 
    14211351 
     
    17461676 
    17471677%------------------------------------------namptr----------------------------------------- 
    1748 \namdisplay{namptr}  
     1678\fortranfile{namelists/namptr}  
    17491679%----------------------------------------------------------------------------------------- 
    17501680 
     
    17891719 
    17901720%------------------------------------------nam_dia25h------------------------------------- 
    1791 \namdisplay{nam_dia25h} 
     1721\fortranfile{namelists/nam_dia25h} 
    17921722%----------------------------------------------------------------------------------------- 
    17931723 
     
    18041734 
    18051735%------------------------------------------nam_diatmb----------------------------------------------------- 
    1806 \namdisplay{nam_diatmb} 
     1736\fortranfile{namelists/nam_diatmb} 
    18071737%---------------------------------------------------------------------------------------------------------- 
    18081738 
Note: See TracChangeset for help on using the changeset viewer.