Add a new output variable using XIOS

Author: J. Ghattas
Last revision: 2020/02/03, A. Ducharne

In order to add a new variable in the output files you need to add a line in the fortran source code to send the variable to xios during run time. You also need to adapt the xml files to recognise this variable and to write it to one or several output files.

Detailed information regarding the XIOS syntax can be found on ​http://forge.ipsl.jussieu.fr/ioserver, which includes a user guide and reference guide.

1. Modifications in the fortran source code

From any module in ORCHIDEE you can send the variable to xios. Add the following:

CALL xios_orchidee_send_field(“new_var_id”,new_var)

xios_orchidee_send_field is an interface in module xios_orchidee for subroutines where the variable new_var can be DIMENSION(kjpindex) or DIMENSION(kjpindex,z), where z can be any vertical axis. If it is not already the case, you also need to add "USE xios_orchidee" in the beginning of the module.

Note: If the variable is only calculated for a specific option, it is good to add an exception in the subroutine xios_orchidee_init written in src_parallel/xios_orchidee.f90. This avoids that the variable will be initialized in the output file without being written. For example if the variable new_var is only calculated for the case ok_newvar, then deactivated it for the other case as follow:

IF (.NOT. ok_newvar ) CALL xios_set_field_attr("new_var_id",enabled=.FALSE.)

2. Modifications in the xml files

All the xml files are stored in the model directory ORCHIDEE/src_xml. When running the model using the libIGCM configurations, file_def_orchidee.xml is copied from ORCHIDEE/src_xml into PARAM/ directory during the simulation and it is this file that will be considered.

field_def_orchidee.xml

Add the declaration of the new variable in field_def_orchidee.xml. By default the variables are supposed to be horizontal fields. If they have a vertical axis it needs to be specified here. Add the following in field_def_orchidee.xml for horizontal field:

<field id="new_var_id" name="varname" long_name="..." unit="..." />

or for horizontal fields having one vertical axis:

<field id="new_var_id" name="varname" long_name="..." unit="..." axis_ref=".."/>

choose axis_ref according to the vertical dimension (note for nvm there are 2 axes: different for the use in sechiba and stomate history files):

axis_ref       dimension
------------------------
"veget"        nvm
"PFT"          nvm
"laiax"        nlai+1 
"solth"        ngrnd
"soiltyp"      nstm
"nobio"        nnbio
"solay"        nslm
"soildiag"     nbdl
"snowlev"      nsnow
"albtyp"       2
"P10"          10
"P100"         100
"P11"          11
"P101"         101

For the moment, using XIOS1 it is not possible to have more than one vertical axis (e.g. solay and soildiag at the same time).

Note 1: The default operation is average. You can change to another operation(once, accumulate, max, min) on the declaration line for the variable :

<field id="new_var_id" name="varname" long_name="..." unit="..." axis_ref=".." operation="max"/>

Note 2: You can create new variables using the reference from the first one without changing the source code:

<field id="new_var_id" name="varname" long_name="..." unit="..." axis_ref=".."/>
<field id="new_var_id_max" field_ref="new_var_id" name="varmax" long_name="..." unit="..." axis_ref=".." operation="max"/>

Note 3: The axis or grid you need may not yet be defined. Define your the dimensions of the new axis in src_parallel/xios_orchidee.def. For example,

CALL xios_set_axis_attr("ncut", n_glo=ncut_times,VALUE=(/(REAL(i,r_std),i=1,ncut_times)/))

complete the definition in src_xml/context_orchidee.xml. For example,

<axis id="ncut" standard_name="model_level_number" long_name="types of cuttings" unit="1"/>

file_def_orchidee.xml

Specify in which files the variable should be written in file_def_orchidee.xml. Set in one or several sections (one section corresponding to one file):

<field field_ref="new_var_id" level="1"/>

The key word level is related to output_level set in the beginning of the file section in the same file. To write the file, level must be smaller or equal to output_level. In the following example the new_var will be written :

<file id="sechiba1" name="sechiba_history" output_level="11" output_freq="1d" enabled=".TRUE.">
   <field field_ref="new_var_id" level="1"/>