XIOS Guidelines

For the moment, calls to XIOS (for writting outputs) in the code of ORCHIDEE completely mimic those that were done to IOIPSL (the old I/O library).
Because XIOS has advanced features (compared to IOIPSL), we propose to take advantages of these features in order to simplify the way that we output variables into ORCHIDEE. Here below, are described some of these features and how we can benefit of them :

See also how to run with XIOS and how to add new variables in the How to page.

Guideline 1 : Id name

With XIOS, we can easily rename any output variable by modifying the field_def file. This is possible without recompiling the code. What we only have to do in the code is to specify a Id name for each variable that is output. By default, we propose that the Id name should be the same as the name of the variable in the code. Here below is an example with the Ground heat flux variable that is output in the thermosoil_main routine (thermosoil.f90 file)

Example:

For the moment, we have line ​622

CALL xios_orchidee_send_field("Qg",soilflx)

where Qg is the field id
and soilflx, the local variable in the FORTRAN code

and in field_def:

<field id="Qg" name="Qg" long_name="Ground heat flux" unit="W/m^2"/>

where name is the name of variable in the output file: here "Qg" (because name="Qg")

---

Using the same name for the Id and the variable in the code, we should have now :
in the code:

CALL xios_orchidee_send_field("soilflx",soilflx)

and in the field_def file:

<field id="soilflx" name="Qg" long_name="Ground heat flux" unit="W/m^2"/>

For variables which are vectors, such as the variable 'carbon_passive' for instance in stomate_lpj.f90

CALL xios_orchidee_send_field("CARBON_PASSIVE",carbon(:,ipassive,:))

Guideline 2 : Units

Conversion of units can be performed and defined in the field_def file.

We propose to output variables with the same units as they are used. One exception is regarding the time unit. We don't want to ouput variables expressed per time step unit, like a flux per 30min. The unit "per second" should be the standard.

Example 1:
For instance, in intersurf.f90 line ​1701: The instruction

CALL xios_orchidee_send_field("evap",zvevapp*one_day/dt_sechiba)

should be modified as follows:

CALL xios_orchidee_send_field("zvevapp",zvevapp/dt_sechiba)

and in the field_def file, instead of having

<field id="evap" name="evap" long_name="Evaporation" unit="mm/d"/>

one proposes to have:

<field id="zvevapp" name="zvevapp" long_name="Evaporation" unit="mm/s"/>
<field id="evap" name="evap" field_ref="zvevapp" long_name="Evaporation" unit="mm/d"/> zvevapp*86400 </field>

Guideline 3 : Operation

Similarly to units conversion, some outputs are only the sum of elementary outputs.

Example:
For instance, in slowproc.f90 (​here), the following section can be deleted:

! 4.2.2 Compute the net primary production as the diff from
! Gross primary productin and the growth and maintenance
! respirations
npp(:,1)=zero
DO j = 2,nvm
   npp(:,j) = gpp(:,j) - resp_growth(:,j) - resp_maint(:,j)
ENDDO
	       
CALL xios_orchidee_send_field("npp",npp/dt_sechiba)

beacause, gpp, resp_growth and resp_maint are already ouptuts.

CALL xios_orchidee_send_field("maint_resp",resp_maint/dt_sechiba)
CALL xios_orchidee_send_field("hetero_resp",resp_hetero/dt_sechiba)
CALL xios_orchidee_send_field("growth_resp",resp_growth/dt_sechiba)

npp will be now only set in the field_def file as follows:

<field id="npp" name="npp" long_name="Net Primary Productivity" field_ref="gpp" /> gpp-hetero_resp-growth_resp </field>

Guideline 4

We do the "CALL xios_orchidee_send_field" in the module where the variable is calculated. If the variable is changed in several places, we do the call in the last XIOS module where it is changed or in sechiba_main, this has to be decided case by case.

Guideline 5

If the variable is only calculated for a specific run case, then we deactivate the output from xios_orchidee.f90 with xios_set_field_attr as for the case not calculated. This leaves us the possibility of having the same file_def_orchidee.xml for different setups. If we forgot, it will work but we will have declared variables in the .nc files without values, which is is troubling. As an exception, the stomate variables are not deactivated in this way, that would be too many exception cases. But since we traditionally separated variables between sechiba_history.nc and stomate_history.nc, we have no problem because we deactivate the whole stomate_history.nc file if stomate is not active.

For example, for the routing variables, we deactivate them if we have no routing. In this case, even if they are in file_def_orchidee.xml, they will not be written. In xios_orchidee:

IF (.NOT. River_routing) THEN
   CALL xios_set_field_attr ("basinmap" enabled = .FALSE.)
...