1 | ****************** |
---|
2 | Diagnostics (XIOS) |
---|
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 | |
---|
14 | Use of XIOS for diagnostics is activated using the pre-compiler key ``key_iomput``. |
---|
15 | The default version of XIOS is the 2.0 release. |
---|
16 | |
---|
17 | Extracting and installing XIOS |
---|
18 | ============================== |
---|
19 | |
---|
20 | 1. 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. |
---|
22 | 2. 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 | |
---|
34 | Namelists |
---|
35 | ========= |
---|
36 | |
---|
37 | XIOS is controlled using xml input files that should be copied to your model run directory before |
---|
38 | running the model. |
---|
39 | The exact setup differs slightly between 1.0 and 2.0 releases. |
---|
40 | |
---|
41 | An ``iodef.xml`` file is still required in the run directory. |
---|
42 | For 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). |
---|
44 | Also the definition of the output files has been moved from the ``iodef.xml`` file into |
---|
45 | separate ``file_definition.xml`` files which are included in the ``iodef.xml`` file. |
---|
46 | Note that the ``domain_def.xml`` file is also different for XIOS 2.0. |
---|
47 | |
---|
48 | Modes |
---|
49 | ===== |
---|
50 | |
---|
51 | Detached Mode |
---|
52 | ------------- |
---|
53 | |
---|
54 | In detached mode the XIOS executable is executed on separate cores from the NEMO model. |
---|
55 | This is the recommended method for using XIOS for realistic model runs. |
---|
56 | To 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 | |
---|
62 | Make sure there is a copy (or link to) your XIOS executable in the working directory and |
---|
63 | in your job submission script allocate processors to XIOS. |
---|
64 | |
---|
65 | Attached Mode |
---|
66 | ------------- |
---|
67 | |
---|
68 | In attached mode XIOS runs on each of the cores used by NEMO. |
---|
69 | This method is less efficient than the detached mode but can be more convenient for testing or |
---|
70 | with small configurations. |
---|
71 | To 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 | |
---|
77 | and don't allocate any cores to XIOS. |
---|
78 | Note that due to the different domain decompositions between XIOS and NEMO if |
---|
79 | the total number of cores is larger than the number of grid points in the j direction then the model run will fail. |
---|
80 | |
---|
81 | Adding new diagnostics |
---|
82 | ====================== |
---|
83 | |
---|
84 | If you want to add a NEMO diagnostic to the NEMO code you will need to do the following: |
---|
85 | |
---|
86 | 1. Add any necessary code to calculate you new diagnostic in NEMO |
---|
87 | 2. 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. |
---|
91 | 3. 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 | |
---|
103 | 4. Add a variable definition to the ``field_def.xml`` (or ``field_def-???.xml``) file |
---|
104 | 5. Add the variable to the ``iodef.xml`` or ``file_definition.xml`` file. |
---|