source: NEMO/trunk/cfgs/SHARED/README.rst @ 10460

Last change on this file since 10460 was 10460, checked in by nicolasmartin, 20 months ago

Small modifications regarding README(s) and ReST files

File size: 4.1 KB
Line 
1***********
2Diagnostics
3***********
4
5.. contents::
6   :local:
7
8| Output of diagnostics in NEMO is usually done using XIOS.
9  This is an efficient way of writing diagnostics because the time averaging, file writing and even
10  some simple arithmetic or regridding is carried out in parallel to the NEMO model run.
11| This page gives a basic introduction to using XIOS with NEMO.
12  Much more information is available from the XIOS homepage above and from the `NEMO manual`_.
13
14Use of XIOS for diagnostics is activated using the pre-compiler key ``key_iomput``.
15The default version of XIOS is the 2.0 release.
16
17Extracting and installing XIOS
18==============================
19
201. Install the NetCDF4 library.
21   If you want to use single file output you will need to compile the HDF & NetCDF libraries to allow parallel IO.
222. Download the version of XIOS that you wish to use.
23   The recommended version is now XIOS 2.0:
24   
25   .. code-block:: console
26
27      $ svn co ​http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.0 xios-2.0
28
29   and follow the instructions in :xios:`XIOS documentation <wiki/documentation>` to compile it.
30   If you find problems at this stage, support can be found by subscribing to the `XIOS mailing list
31   <http://forge.ipsl.jussieu.fr/mailman/listinfo.cgi/xios-users>`_
32   and sending a mail message to it.
33
34Namelists
35=========
36
37XIOS is controlled using xml input files that should be copied to your model run directory before
38running the model.
39The exact setup differs slightly between 1.0 and 2.0 releases.
40
41An ``iodef.xml`` file is still required in the run directory.
42For XIOS 2.0 the ``field_def.xml`` file has been further split into ``field_def-oce.xml`` (for physics),
43``field_def-ice.xml`` (for ice) and ``field_def-bgc.xml`` (for biogeochemistry).
44Also the definition of the output files has been moved from the ``iodef.xml`` file into
45separate ``file_definition.xml`` files which are included in the ``iodef.xml`` file.
46Note that the ``domain_def.xml`` file is also different for XIOS 2.0.
47
48Modes
49=====
50
51Detached Mode
52-------------
53
54In detached mode the XIOS executable is executed on separate cores from the NEMO model.
55This is the recommended method for using XIOS for realistic model runs.
56To use this mode set ``using_server`` to ``true`` at the bottom of the ``iodef.xml`` file:
57
58.. code-block:: xml
59
60   <variable id="using_server" type="boolean">true</variable>
61
62Make sure there is a copy (or link to) your XIOS executable in the working directory and
63in your job submission script allocate processors to XIOS.
64
65Attached Mode
66-------------
67
68In attached mode XIOS runs on each of the cores used by NEMO.
69This method is less efficient than the detached mode but can be more convenient for testing or
70with small configurations.
71To activate this mode simply set ``using_server`` to false in the ``iodef.xml`` file
72
73.. code-block:: xml
74
75   <variable id="using_server" type="boolean">false</variable>
76
77and don't allocate any cores to XIOS.
78Note that due to the different domain decompositions between XIOS and NEMO if
79the total number of cores is larger than the number of grid points in the j direction then the model run will fail.
80
81Adding new diagnostics
82======================
83
84If you want to add a NEMO diagnostic to the NEMO code you will need to do the following:
85
861. Add any necessary code to calculate you new diagnostic in NEMO
872. Send the field to XIOS using ``CALL iom_put( 'field_id', variable )`` where ``field_id`` is a unique id for
88   your new diagnostics and variable is the fortran variable containing the data.
89   This should be called at every model timestep regardless of how often you want to output the field.
90   No time averaging should be done in the model code.
913. If it is computationally expensive to calculate your new diagnostic you should also use "iom_use" to
92   determine if it is requested in the current model run. For example,
93   
94   .. code-block:: fortran
95
96      IF iom_use('field_id') THEN
97         !Some expensive computation
98         !...
99         !...
100         iom_put('field_id', variable)
101      ENDIF
102
1034. Add a variable definition to the ``field_def.xml`` (or ``field_def-???.xml``) file
1045. Add the variable to the ``iodef.xml`` or ``file_definition.xml`` file.
Note: See TracBrowser for help on using the repository browser.