New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Changeset 11747 for NEMO/trunk/cfgs/SHARED/README.rst – NEMO

Ignore:
Timestamp:
2019-10-21T15:21:48+02:00 (5 years ago)
Author:
nicolasmartin
Message:

Review README for diagnostics

File:
1 edited

Legend:

Unmodified
Added
Removed
  • NEMO/trunk/cfgs/SHARED/README.rst

    r11734 r11747  
    1111 
    1212Output of diagnostics in NEMO is usually done using XIOS. 
    13 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. 
     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. 
    1416This page gives a basic introduction to using XIOS with NEMO. 
    15 Much more information is available from the XIOS homepage above and from the NEMO manual. 
     17Much more information is available from the :xios:`XIOS homepage<>` above and from the NEMO manual. 
    1618 
    1719Use of XIOS for diagnostics is activated using the pre-compiler key ``key_iomput``. 
    1820 
    1921Extracting and installing XIOS 
    20 ------------------------------ 
     22============================== 
    2123 
    22241. 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. 
    24 2. Download the version of XIOS that you wish to use. The recommended version is now XIOS 2.5: 
     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: 
    2529 
    26 .. code-block:: console 
     30   .. code-block:: console 
    2731 
    28    $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5 xios-2.5 
     32      $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5 
    2933 
    30 and 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. 
     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. 
    3237 
    3338XIOS Configuration files 
    3439------------------------ 
    3540 
    36 XIOS is controlled using xml input files that should be copied to your model run directory before running the model. 
    37 Examples 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. 
    38 In 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. 
    39 Most 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. 
    40 The definition of the output files is organized into separate ``file_definition.xml`` files which are included in the ``iodef.xml`` file. 
     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. 
    4156 
    4257Modes 
    43 ----- 
     58===== 
    4459 
    4560Detached Mode 
     
    4863In detached mode the XIOS executable is executed on separate cores from the NEMO model. 
    4964This is the recommended method for using XIOS for realistic model runs. 
    50 To use this mode set ``using_server`` to ``true`` at the bottom of the ``iodef.xml`` file: 
     65To use this mode set ``using_server`` to ``true`` at the bottom of the :file:`iodef.xml` file: 
    5166 
    5267.. code-block:: xml 
    5368 
    54    <variable id="using_server" type="boolean">true</variable> 
     69   <variable id="using_server" type="boolean">true</variable> 
    5570 
    56 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. 
     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. 
    5773 
    5874Attached Mode 
     
    6076 
    6177In attached mode XIOS runs on each of the cores used by NEMO. 
    62 This method is less efficient than the detached mode but can be more convenient for testing or with small configurations. 
    63 To activate this mode simply set ``using_server`` to false in the ``iodef.xml`` file 
     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 
    6481 
    6582.. code-block:: xml 
    6683 
    67    <variable id="using_server" type="boolean">false</variable> 
     84   <variable id="using_server" type="boolean">false</variable> 
    6885 
    6986and don't allocate any cores to XIOS. 
    70 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. 
     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. 
    7193 
    7294Adding new diagnostics 
    73 ---------------------- 
     95====================== 
    7496 
    7597If you want to add a NEMO diagnostic to the NEMO code you will need to do the following: 
    7698 
    77991. Add any necessary code to calculate you new diagnostic in NEMO 
    78 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. 
    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. 
    80 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, 
     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, 
    81108 
    82 .. code-block:: fortran 
     109   .. code-block:: fortran 
    83110 
    84       IF iom_use('field_id') THEN 
    85          !Some expensive computation 
    86          !... 
    87          !... 
    88          iom_put('field_id', variable) 
    89       ENDIF 
     111      IF iom_use('field_id') THEN 
     112         !Some expensive computation 
     113         !... 
     114         !... 
     115    iom_put('field_id', variable) 
     116      ENDIF 
    90117 
    91 4. Add a variable definition to the ``field_def_nemo-???.xml`` file. 
    92 5. Add the variable to the ``iodef.xml`` or ``file_definition.xml`` file. 
     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 TracChangeset for help on using the changeset viewer.