source: NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/SHARED/README.rst @ 11777

Last change on this file since 11777 was 11777, checked in by acc, 22 months ago

Branch 2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps. Begin merge prepartions by merging changes on the trunk since this branch creation. Do this in staged commits in case of issues. First stage is to merge and commit changes to cfgs directory (cd cfgs; svn merge -r 10721:11740 svn+ssh://acc@forge.ipsl.jussieu.fr/ipsl/forge/projets/nemo/svn/NEMO/trunk/cfgs ./)

File size: 4.3 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 the time averaging, file writing and even some simple arithmetic or regridding is carried out in parallel to the NEMO model run.
14This page gives a basic introduction to using XIOS with NEMO.
15Much more information is available from the XIOS homepage above and from the NEMO manual.
16
17Use of XIOS for diagnostics is activated using the pre-compiler key ``key_iomput``.
18
19Extracting and installing XIOS
20------------------------------
21
221. Install the NetCDF4 library.
23   If you want to use single file output you will need to compile the HDF & NetCDF libraries to allow parallel IO.
242. Download the version of XIOS that you wish to use. The recommended version is now XIOS 2.5:
25
26.. code-block:: console
27
28   $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5 xios-2.5
29
30and follow the instructions in `XIOS documentation <http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation>`_ to compile it.
31   If you find problems at this stage, support can be found by subscribing to the `XIOS mailing list <http://forge.ipsl.jussieu.fr/mailman/listinfo.cgi/xios-users>`_ and sending a mail message to it.
32
33XIOS Configuration files
34------------------------
35
36XIOS is controlled using xml input files that should be copied to your model run directory before running the model.
37Examples of these files can be found in the reference configurations (``cfgs``). The XIOS executable expects to find a file called ``iodef.xml`` in the model run directory.
38In NEMO we have made the decision to use include statements in the ``iodef.xml`` file to include ``field_def_nemo-oce.xml`` (for physics), ``field_def_nemo-ice.xml`` (for ice), ``field_def_nemo-pisces.xml`` (for biogeochemistry) and ``domain_def.xml`` from the /cfgs/SHARED directory.
39Most users will not need to modify ``domain_def.xml`` or ``field_def_nemo-???.xml`` unless they want to add new diagnostics to the NEMO code.
40The definition of the output files is organized into separate ``file_definition.xml`` files which are included in the ``iodef.xml`` file.
41
42Modes
43-----
44
45Detached Mode
46-------------
47
48In detached mode the XIOS executable is executed on separate cores from the NEMO model.
49This is the recommended method for using XIOS for realistic model runs.
50To use this mode set ``using_server`` to ``true`` at the bottom of the ``iodef.xml`` file:
51
52.. code-block:: xml
53
54   <variable id="using_server" type="boolean">true</variable>
55
56Make 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.
57
58Attached Mode
59-------------
60
61In attached mode XIOS runs on each of the cores used by NEMO.
62This method is less efficient than the detached mode but can be more convenient for testing or with small configurations.
63To activate this mode simply set ``using_server`` to false in the ``iodef.xml`` file
64
65.. code-block:: xml
66
67   <variable id="using_server" type="boolean">false</variable>
68
69and don't allocate any cores to XIOS.
70Note 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.
71
72Adding new diagnostics
73----------------------
74
75If you want to add a NEMO diagnostic to the NEMO code you will need to do the following:
76
771. Add any necessary code to calculate you new diagnostic in NEMO
782. 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.
79   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.
803. 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,
81
82.. code-block:: fortran
83
84      IF iom_use('field_id') THEN
85         !Some expensive computation
86         !...
87         !...
88         iom_put('field_id', variable)
89      ENDIF
90
914. Add a variable definition to the ``field_def_nemo-???.xml`` file.
925. Add the variable to the ``iodef.xml`` or ``file_definition.xml`` file.
Note: See TracBrowser for help on using the repository browser.