Add a new output variable using XIOS

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.

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 xios_orchidee_init. This avoid that the variable will be initialized in the output file without being written if you keep the same .xml files. 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

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 and with one vertical axis:

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

choose axis_ref according to the vertical dimension

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

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"/>

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"/>