Manipulation of parameter files in libIGCM configurations

Author: J. Ghattas
Last revision: 2020/02/28, B. Guenet

This is the method used in ORCHIDEE_OL since rev [2524].

When doing simulation with the model, you can modify some aspect of your simulation:

• If you want to modify parameters values or activate/deactivate flags you have to do it in PARAM/run.def

• If you want to modify the boundaries conditions (climate forcing, PFT maps, soil maps, etc.) you have to modify the .card files located in the COMP directory.

• If you want to modify your more technical aspects of your setup (length of the simulation, number of processors used, restart files, etc) you can do it in config.card

Details are given below. This works with ORCHIDEE_OL offline configuration, LMDZOR_v6 and IPSLCM6 configurations:

• Highlight:
  • A value set in run.def can only be modified by the driver if it is set equal AUTO
  • A parameter can not be added by the driver. If you want to add new parameter in the model you must modified the source code. Be sure that the parameters are externalized.

Three types of parameters

• classical parameter those parameters are numerical or logicals and can be modified in the run.def. They will impact each time step of the simulation.

• nonblocker parameter can be modified or removed from run.def.

Example nonblocker parameter, extract from PARAM/run.def in ORCHIDEE_OL/OOL_SEC_STO_FG2:

# SECHIBA history output level (0..10)
SECHIBA_HISTLEVEL = _AUTO_

The variable SECHIBA_HISTLEVEL is set to AUTO because it is normally modified with a value from the default set up in sechiba.card. The value can be changed directly in run.def, for example SECHIBA_HISTLEVEL=3, and in that case, it will not be modified again by the driver. If you let it to AUTO the value can be modified in the .card files.

• blocker parameter can not be modified or removed from run.def otherwise the job will stop before executing the model.

Example, extract from PARAM/run.def in ORCHIDEE_OL/OOL_SEC_STO_FG2:

# Name of restart to read for initial conditions of STOMATE
STOMATE_RESTART_FILEIN = _AUTOBLOCKER_

The variable STOMATE_RESTART_FILEIN is set changed due to restart options set in config.card. It is an important parameter and is therefore a so called blocker parameter. If a blocker parameter is changed, the job will stop before launching the model. For example if it is set to STOMATE_RESTART_FILEIN=stomate_rest_in.nc, then the job will stop. This parameter must contain the key word AUTO. Except if you really know what you are doing we do not advice to modify the blocker parameters.

Implementation
If you added nonblocker or blocker parameters (i.e. those identified by AUTO or AUTOBLOCKER in the run.def) you must be sure that they are read and modified by the .driver files following the instructions below

The component's driver call the libIGCM function IGCM_comp_modifyDefFile (for run.def, orchidee.def,... ) or IGCM_comp_modifyXmlFile (for xml files) for each variable that needs to be manipulated.

Example from sechiba.driver:

IGCM_comp_modifyDefFile nonblocker run.def SECHIBA_HISTLEVEL ${sechiba_UserChoices_sechiba_LEVEL}

The first argument "nonblocker" gives the type of the parameter. In this case, nonblocker means that the parameter can be modified or removed from the parameter file. The other argmuments are file name, parameter name and final value.

Example from stomate.driver:

if ( [ ${CumulPeriod} -eq 1 ] && [ "${config_SBG_Restart}" = "n" ] ) ; then
     echo "STOMATE : without restart"
     IGCM_comp_modifyDefFile blocker run.def STOMATE_RESTART_FILEIN NONE
else
     IGCM_comp_modifyDefFile blocker run.def STOMATE_RESTART_FILEIN stomate_rest_in.nc
fi

The function is here called with different values(NONE or stomate_rest_in.nc) for the parameter(STOMATE_RESTART_FILEIN) depending on which CumulPeriod and if an option for restart is set in config.card. The first argument is blocker which means that it can not be change from the parameter file.

xml files
Since the inclustion of XIOS, there is a new file PARAM/file_def_orchidee.xml which needs to be adapted according to the level of output. The same method as for run.def using a similar function in libIGCM.

For example in PARAM/file_def_orchidee.xml:

  <file id="sechiba1" name="sechiba_history" output_level="11" output_freq="_AUTO_" enabled="_AUTO_">

The 2 parameters output_freq and enabled are modified by sechiba.driver according to the WriteFrequency set in config.card. But they are not blocker parameters so they can also be modified directly in the xml file if wanted. In sechiba.driver, the implementation looks like following :

IGCM_comp_modifyXmlFile nonblocker file_def_orchidee.xml sechiba1 enabled ${sechiba1_enabled}
IGCM_comp_modifyXmlFile nonblocker file_def_orchidee.xml sechiba1 output_freq ${sechiba1_freq}

Method in LMDZOR_v5 and all other _v5 configurations

In these configurations, in the .def files all variables modified by the driver are set =AUTO. Even if one these parameters is changed, in PARAM/orchidee.def for example, the driver will overwrite the value. A message is written in Script_Output text file.