source: NEMO/branches/2019/dev_ASINTER-01-05_merged/cfgs/SHARED/README.rst @ 12165

Last change on this file since 12165 was 12165, checked in by davestorkey, 10 months ago

2019/dev_ASINTER-01-05_merged: Update to r12072 of trunk.

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