WikiPrint - from Polar Technologies

The ORCHIDEE model

1. Introduction

Visit the ORCHIDEE's official website
Follow the actualities in developments of ORCHIDEE

The ORCHIDEE model includes 3 components: sechiba, stomate and LPJ (dynamic vegetation). Only the 2 components sechiba and stomate are activated by default. If you are using a coupled configuration with LMDZ, you will need the sechiba component to compute the water and energy balance. You will also need the stomate component to compute the carbon balance. It is possible to deactivate stomate. You will find additional information on how to use ORCHIDEE in libIGCM-supported configurations below.

2. Compile methods in ORCHIDEE

2 compile methods are used in ORCHIDEE depending on the version. Read more about compiling on the ORCHIDEE wiki: https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/UserGuide/CompileMethods

Compiling with makeorchidee_fcm

This method is available in the trunk ORCHIDEE, since revision 2149, in LMDZOR_v5.2 configuration and all _v6 configurations.
All platform dependent compile options are set in modeles/ORCHIDEE/arch/
Changing compile options or adding a new machine is done in modeles/ORCHIDEE/arch
3 different levels of optimization are available and can be changed using an argument to makeorchidee_fcm: -prod(default), -dev or -debug. These options can be changed or added in the main makefile in modipsl/config/YOUR_CONFIG/ directory.

Obsolete : Standard makefiles created based on AA_make and AA_make.gdef

This is the only method available in CMIP5 version of ORCHIDEE. All _v5 configurations with ORCHIDEE compile in this way.
All platform dependent compile options are set in modipsl/util/AA_make.gdef
=> Change compile options in AA_make.gdef, recreate makefiles with ./ins_make, clean previous compilation and recompile

3. Run options

Predefined run options are set in orchidee.card and stomate.card for coupled configurations and in orchidee_ol.card, sechiba.card and stomate.card for offline configurations. Other options not listed in the card can be set directly in the parameter file run.def (for offline run) or orchidee.def(for coupled run).

3.1. Choice of hydrology scheme

Since tag ORCHIDEE_2_1, only a multilayer hydrology scheme called CWRR is implemented. For older versions, the choice of the older 2 bucket scheme Choisnel or the newer multilayer scheme CWRR can be done.

Choose the hydrology scheme in the following way :

in _v6.2 and newer configurations and in offline ORCHIDEE_trunk configuration : no choice. CWRR scheme will be used.
in _v5 and _v6 configurations by setting DefSuffix=CWRR or DefSuffix=Choi in the section [UserChoices] in orchidee.card. The variable DefSuffix will be used to copy the corresponding orchidee.def file from PARAM directory, see the line :
```
[ParametersFiles]
List=   (${SUBMIT_DIR}/PARAM/orchidee.def_${DefSuffix}, orchidee.def)
```

3.2. Vegetation map

The vegetation map (PFTmap.nc) can be constant or updated annually. Use the option VEGET_UPDATE=0Y for constant vegetation map and VEGET_UPDATE=1Y to update annually the vegetation map. Note that in previous versions of ORCHIDEE up to revision 2718 on the trunk, including _v5 configurations, the vegetation map was updated in the end of the year with the map for the next coming year. In newer versions and all _v6 configurations, the vegetation map is updated on the first day of the year.

For constant vegetation map, set in orchidee.card (or sechiba.card) VEGET_UPDATE=0Y and set in [InitialStateFiles] the PFTmap.nc file you want to use for the simulation. Note that for constant vegetation map, the vegetation will be read from the restart file. Only if it is not found in the restart file, then the file PFTmap.nc will be read.

To update annually the vegetation map set in orchidee.card (or sechiba.card) VEGET_UPDATE=1Y and set :

for _v6 configurations and newer ORCHIDEE trunk from revision 2718:

[BoundaryFiles]
List=  (${R_BC}/SRF/${config_UserChoices_TagName}/PFTmap_1850to2005_AR5_LUHa.rc2/PFTmap_IPCC_${year}.nc, PFTmap.nc)

for _v5 configurations or offline with ORCHIDEE trunk or tag older than revision 2718:
- Note that here we use year_p1 to have the next coming year as the file is read in December for the next coming year
- You must also set LAND_COVER_CHANGE=y in section [UserChoices]
- With monthly period length:
```
[SmoothFiles]
List=(${R_BC}/SRF/${config_UserChoices_TagName}/PFTmap_1850to2005_AR5_LUHa.rc2/PFTmap_IPCC_${year_p1}.nc, PFTmap.nc, 12:12:)
```
- With yearly period length, note for this case you can not have PFTmap.nc also in the [InitialStateFiles] section:
```
[BoundaryFiles]
List=  (${R_BC}/SRF/${config_UserChoices_TagName}/PFTmap_1850to2005_AR5_LUHa.rc2/PFTmap_IPCC_${year_p1}.nc, PFTmap.nc)
```

3.3. Manage output in _v6 configurations and ORCHIDEE_trunk using XIOS

XIOS is used by default in v6 configurations. In ORCHIDEE_trunk it is possible to activate XIOS output. To do so you need first to compile with XIOS. This is done using gmake with_xios in modipsl/config/ORCHIDEE_OL directory. Before running activate XIOS in orchidee_ol.card by setting XIOS=y. This is the default and only behaviour in coupled _v6 configurations.

The output levels in ORCHIDEE are controlled by the xml files that have to be present during run time. Following files are needed : iodef.xml, context_orchidee.xml, field_def_orchidee.xml and file_def_orchidee.xml. They are stored in the model directory ORCHIDEE/src_xml and in the configuration directory PARAM/. You can see the copy of these files and where they are stored in the orchidee.card or orchidee_ol.card. file_def_orchidee.xml contains a description of predefined files and their variable content. All variables modified by the configuration are marked with _AUTO_. These variables can be changed directly in the file if you want. Otherwise the values set in config.card and/or comp.card will be used. In config.card the choice of output file and frequency is done using the WriteFrequency option in section [SRF] and [SBG] :

[SRF] : The first frequency corresponds to the output frequency for the sechiba_history.nc file. The available frequencies are: xY, xM, 5D, 1D and xs, where x is an integer and s means seconds. This file is required. If you add HF, a second sechiba_out_2.nc file will be written with the 3H frequency.
[SBG] : Only one frequency (xY, xM, 5D, 1D or xs) can be specified. The same frequency is applied to both the stomate_history.nc and stomate_ipcc_history.nc files.

Read more in chapter Setup about WriteFrequency.
Read more on the ORCHIDEE wiki about how XIOS is implemented and used in ORCHIDEE : https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/UserGuide#Historyoutputfiles

The easiest way to personalise the output is to modify directly in PARAM/file_def_orchidee.xml. You can change the variables marked equal _AUTO_ as you wish. In that case you do not need to change in config.card. You can remove or modify the variables as you need which according to the rules for XIOS.

3.4. Manage output in _v5 configurations using IOIPSL

The model output frequency is configured in

config.card
- The WriteFrequency variable in the [SRF] section induces a change of the WRITE_STEP variable in orchidee.def. WRITE_STEP determines the output frequency for the sechiba_history.nc file. The available frequencies are: xY (x years), xM (x months), 5D(5 days), 1D (1 day), xs (x seconds). This file is mandatory. If you add HF a second sechiba_out_2.nc file will be written with a 3 hour frequency.
- The WriteFrequency variable in the [SBG] section induces a change of the STOMATE_HIST_DT variable in orchidee.def. STOMATE_HIST_DT determines the output frequency for the stomate_history.nc file. The stomate_history_ipcc.nc file has always daily output frequency.
orchidee.card (or sechiba.card in offline configuration)
- sechiba_LEVEL : mandatory variable, no default value, it varies between 0 and 11. This value is used in orchidee.def/run.def to set SECHIBA_HISTLEVEL variable. This variable determines the number of variables written in sechiba_history.nc.
stomate.card
- stomate_LEVEL : mandatory variable, no default value, it varies between 0 and 10. This value is used in orchidee.def/run.def to set STOMATE_HISTLEVEL variable. This variable determines the number of variables written in stomate_history.nc.

Note that in the _v5 configuration you can not change directly a variable set =_AUTO_ in orchidee.def/run.def. You need to understand how it works through the config.card and comp.card as described above.

4. Deactivate stomate in ORCHIDEE

You can deactivate STOMATE component included by default in all experiments with ORCHIDEE and only run the SECHIBA component. To do so:

in config.card: delete the line for SBG in the ListeOfComponents section
in COMP/orchidee.card (for _v5 or _v6 configurations) or in COMP/sechiba.card (for ORCHIDEE_OL configuration): add the lai2D.nc file in BoundaryFiles, ListNonDel section as follow:
```
ListNonDel= (${R_BC}/SRF/${config_UserChoices_TagName}/lai2D_03.nc, lai2D.nc)
```
in PARAM/orchidee.def (for _v5 or _v6) or PARAM/run.def (for ORCHIDEE_OL): add parameter LAI_MAP to request the reading of LAI_MAP:
```
# Read a LAI map (12 monthly values)
LAI_MAP = y
# default = n
```