How to tell libIGCM to copy a new input file for ORCHIDEE

Authors: D. Goll and J. Ghattas
Last revision: 2020/02/28, S. Luyssaert

Objective

This help you to: (1) understand why libIGCM is used pass input files and ORCHIDEE and (2) how new input files can be passed to ORCHIDEE by making use of libIGCM.

Why using libIGCM for passing files

The ORCHIDEE code makes use of hard coded file names. Somewhere in the code, for example, there is the instruction to open the file PFTmap.nc which contains a description of the vegetation classified in PFTs for which the ORCHIDEE model was parameterized. When the experiment was configured to simulate land cover change, each year the model will have to read a different file despite it has to be called PFTmap.nc for the ORCHIDEE code to work. This is one of the tasks of libIGCM; if the model is in the year 1901, it will link the path of a PFT map for the year 1901 to the name PFTmap.nc. So, in the year 1901 ORCHIDEE will link the name PFTmap.nc to the PFT map for that year. Depending on the experiment one has in the mind, some input files only need to be read once at the start of the experiment, other need to be read every year, etc. As explained below, libIGCM can take care of this complexity.

Passing input files to ORCHIDEE

Using libIGCM

When downloading the ORCHIDEE trunk from svn, you will also download the ORCIDEE_OL folder. This folder contains a set of default ​experiments. Check which of these experiments could be a good starting point for the experiment you have in mind. Copy that folder and start from there.

The experiment you copied conatins several folders. The offline driver forcing files are set in orchidee_ol.card. The input files for the stomate routines are typically set in COMP/stomate.card. For offline simulations, input files for sechiba are set in COMP/sechiba.card. For coupled simulations, input files for sechiba are set in the orchidee.card. For the experiment called ENSEMBLE the stomate.card and sechiba.card are hidden in config/ORCHIDEE_OL/SPINUP/SUBJOB/OOL_SEC_STO/COMP/. The ENSEMBLE experiment helps to compare ORCHIDEE simulations agains FLUXNET data but is a complicated and delicate set-up. It is best to first read its specific ​documentation
In these component.card, the input files are divided into different sections :

• [InitialStateFiles]/List : add the file here if it is only needed when no restart file is existing. For example soils_param.nc is set here.
• [BoundaryFiles]/List : add files that depend on the date of the simulation. For example the forcing file is set here. You can use ${year} and ${month} to describe the file.
• [BoundaryFiles]/ListNonDel : add the file here if it is needed during the whole simulation
• [ParametersFiles]/List : add the file here if it is a parameter file or xml file. Those files are typically found in the PARAM folder or the src_xml folder.

The component.card files are processed by the matching component.driver, hence, the syntax is really important and precise. See how it is done for other files. If you are adding a file to an existing list, remember to add in the end of the previous line ",\", be careful not to add empty spaces! Add a new line (source_file, destination_file) where source_file describes the complete file path and filename and destination_file is the filename read by the model (see above). For the destination_file you can use "." if the filename is the same. To define the path for the source_file you can use ${R_IN} which points to the shared repository IGCM or set directly the full path to the file ONLY if you are using a file that is not on the repository. Help us to save disk space and do NOT copy any files from the repository to your personal folders.

Example 1. Use a file with the reftemp.nc in ORCHIDEE. This file is known to ORCHIDEE as reftemp.nc so there is no need to change the name:

ListNonDel= (${R_IN}/SRF/reftemp.nc, .), \	 
            (path/to/new/file.nc, destinationfilename)

Example 2. Use for every year a different climate forcing file with the name ncc_for_XXX.nc where XXX is the year, e.g. 1902. These files are known to ORCHIDEE as forcing_file.nc:

[BoundaryFiles]
List=  (${R_IN}/SRF/METEO/NCC/ncc_for_${year}.nc, forcing_file.nc)

Alternatives

In specific cases (i.e., hard core debugging) it could be useful to bypass libIGCM. For most input files this is possible because the file name can also be read from the run.def or orchidee.def files. This is, however, not recommended for any simulations that passed the debug stage.