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