Inputs-Outputs (using XIOS)

Last edition: 2017-09-04 15:59 CEST by clevy

Output of diagnostics in NEMO is usually done using XIOS. This is an efficient way of writing diagnostics because the time averaging, file writing and even some simple arithmetic or regridding is carried out in parallel to the NEMO model run.
This page gives a basic introduction to using XIOS with NEMO. Much more information is available from the XIOS homepage above and from the NEMO reference manual.

Use of XIOS for diagnostics is activated using the pre-compiler key key_iomput. In nemo_v3_6_STABLE the default version of XIOS is XIOS1.0 but XIOS2.0 can be used by activating key_xios2. At the head of the NEMO trunk only XIOS2.0 can be used (XIOS2.0 is the XIOS trunk) and key_xios2 is not required.

Extracting and installing XIOS

1) Install the NetCDF4 library. If you want to use single file output you will need to compile the HDF & NetCDF libraries to allow parallel IO.

2) Download the version of XIOS that you wish to use. The recommended version is now XIOS2.0, but by default, 3_6_STABLE runs with XIOS1:

svn co ​ xios-2.0

and follow the instructions in XIOS documentation to compile it. The latest revision tested by the NEMO systems team is 990 although later revisions should also work correctly.

For XIOS1 (by default with 3_6_STABLE reference):

Due to a change in the XIOS1.0 branch, NEMO v3.6 STABLE will only work up to revision 703 of the XIOS1.0 branch without modifying the code manually. Not recommended for NEMO beginners.

svn co ​-r 703 xios-1.0


XIOS is controlled using xml input files that should be copied to your model run directory before running the model. The exact setup differs slightly between XIOS1.0 and XIOS2.0.


Examples of these files can be found in the reference configurations (NEMOGCM/CONFIG) in the nemo_v3_6_STABLE branch. The XIOS executable expects to find a file called iodef.xml in the model run directory. In NEMO we have made the decision to use include statements in the iodef.xml file to include field_def.xml and domain_def.xml from the NEMOGCM/CONFIG/SHARED directory. Most users will not need to modify domain_def.xml or field_def.xml unless they want to add new diagnostics to the NEMO code (see below).


An iodef.xml file is still required in the run directory. For XIOS2.0 the field_def.xml file has been further split into field_def-opa.xml (for physics), field_def-lim.xml (for ice) and field_def-bgc.xml (for biogeochemistry). Also the definition of the output files has been moved from the iodef.xml file into separate file_definition.xml files which are included in the iodef.xml file. Note that the domain_def.xml file is also different for XIOS2.0. Examples of these files can be found in the trunk under NEMOGCM/CONFIG/GYRE_XIOS in the nemo_v3_6_STABLE branch or in the trunk under NEMOGCM/CONFIG.


Detached Mode

In detached mode the XIOS executable is executed on separate cores from the NEMO model. This is the recommended method for using XIOS for realistic model runs. To use this mode set using_server to true at the bottom of the iodef.xml file:

<variable id="using_server" type="boolean">true</variable>

Make sure there is a copy (or link to) your XIOS executable in the working directory and in your job submission script allocate processors to XIOS.

Attached Mode

In attached mode XIOS runs on each of the cores used by NEMO. This method is less efficient than the detached mode but can be more convenient for testing or with small configurations. To activate this mode simply set using_server to false in the iodef.xml file

<variable id="using_server" type="boolean">true</variable>

and don't allocate any cores to XIOS. Note that due to the different domain decompositions between XIOS and NEMO if the total number of cores is larger than the number of grid points in the j direction then the model run will fail.

Adding new diagnostics to NEMO

If you want to add a NEMO diagnostic to the NEMO code you will need to do the following:

1) Add any necessary code to calculate you new diagnostic in NEMO

2) Send the field to XIOS using CALL iom_put( 'field_id', variable ) where field_id is a unique id for your new diagnostics and variable is the fortran variable containing the data. This should be called at every model timestep regardless of how often you want to output the field. No time averaging should be done in the model code.

3) If it is computationally expensive to calculate your new diagnostic you should also use "iom_use" to determine if it is requested in the current model run. For example,

IF iom_use('field_id') THEN
   !Some expensive computation
   iom_put('field_id', variable)

4) Add a variable definition to the field_def.xml (or field_def-???.xml) file

5) Add the variable to the iodef.xml or file_definition.xml file.

Last modified 3 weeks ago Last modified on 2017-09-04T15:59:41+02:00