| Version 2 (modified by nvuilsce, 13 years ago) (diff) |
|---|
How to use this version of ORCHIDEE
This page is a copy of the file you could find in the folder Doc_externalised_version/ when
you download ORCHIDEE_EXT.
Global specifications
The file « orchidee.def » contains the options and parameters that you can modify for any job. You will find it in the folder :
config/ORCHIDEE_OL/Job_Name/PARAM
where Job_Name designs your own job.
Each parameter externalized in ORCHIDEE is defined by a key word. This key word is written in capital letters in the « orchidee.def ». You will find some comments (lines beginning by #) for the parameters externalized in the AR5 version. For a scalar parameter, you should indicate the key word in capital letters and the new value. For example, open « orchidee.def » in the folder :
.../modipsl/config/ORCHIDEE_OL/Job_Name/PARAM/
and set exactly :
HCRIT_LITTER = 0.075
(the standard value for this parameter is 0.08).
Generally, the names of the parameters and the key words match exactly. There exists some exceptions (you could find the list in the documentation folder ORCHIDEE_OL/Doc_externalised_version).
Specifc requirements for PFTs parameters
Unlike the other versions of ORCHIDEE, the number of PFTs is not fixed to 13 in the ORCHIDEE externalised version. You have the possibility to change the parameter representing the number of PFTs 'nvm'. You can easily modify the values of the parameters associated to each PFT (88 in this version). You know that the PFTs are described by a set of common parameters of which values were fixed in the previous versions of ORCHIDEE.
In this ORCHIDEE externalised version, you can choose and change the values of parameters for each PFT. It is possible by using an object called metaclass (= MTC). Each PFT is associated to a MTC. Here we give the list of the MTCs :
- bare ground
- tropical broad-leaved evergreen
- tropical broad-leaved raingreen
- temperate needleleaf evergreen
- temperate broad-leaved evergreen
- temperate broad-leaved summergreen
- boreal needleleaf evergreen
- boreal broad-leaved summergreen
- boreal needleleaf summergreen
- C3 grass
- C4 grass
- C3 agriculture
- C4 agriculture
As you notice, the list of the MTCs matches exactly the list of PFTs in the ORCHIDEE AR5 version. Each PFT is associated to one MTC, corresponding to the usual PFTs in the previous versions. Each MTC is described by the same parameters than the PFTs. The values of the MTC-parameters are fixed and are the default values of the system. By consequence, we implemented 13 MTCs in the code of the externalised version.
All you have to do is to associate a PFT to a MTC. When you link a PFT to a MTC, the PFT parameters will take automatically the default values given for the corresponding MTC. With this technique, you can modify the values and the parameters of interest for you. In practice, go the folder :
modipsl/config/ORCHIDEE_OL/Job_Name/PARAM/
and open « orchidee.def ». In the first step, specify your number of PFTs (called 'nvm') like this :
NVM = 13
In the second step, you will declare the array PFT_TO_MTC. You have two ways for declaring an array in "orchidee.def":
1 .Either you can declare directly like this :
PFT_TO_MTC = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 , 11, 12 , 13
- Or component by component :
PFT_TO_MTC__01 = 1 PFT_TO_MTC__02 = 2 PFT_TO_MTC__03 = 3 PFT_TO_MTC__04 = 4 PFT_TO_MTC__05 = 5 PFT_TO_MTC__06 = 6 PFT_TO_MTC__07 = 7 PFT_TO_MTC__08 = 8 PFT_TO_MTC__09 = 9 PFT_TO_MTC__10 = 10 PFT_TO_MTC__11 = 11 PFT_TO_MTC__12 = 12 PFT_TO_MTC__13 = 13
In both cases, you have to declare ALL the NVM values taken by PFT_TO_MTC you intend to use for your job.
In this example, we associate each PFT to one MTC corresponding to the PFTs of the AR5 configuration of ORCHIDEE.
Actually, if you only want to use ORCHIDEE to its configuration standard and ONLY in this case, you don't need to fill PFT_TO_MTC because we implemented an default array for the case NVM = 13.
Syntax advice : for the second method, there is a double underscore symbol between the name and the component of the vector
PFT_TO_MTC__01
« orchidee.def » don't recognize the type of the parameter.
If you want to distinguish put a point after the number if you want to consider it like a real.
(for example 1 become 1.). For the logical, you can simply set y for TRUE or n for FALSE.
Except PFT_TO_MTC, the other parameters are optional.
If you want ORCHIDEE not to read some values, put a comment by using the character # at the beginning of the line.
Examples
1)Change the value for an already-existing PFT-parameter :
LAI_MAX__10 = 3.5
2)Create a new pft that differs only by one parameter value. For that, follow these two steps : a) Associate your new PFT to one MTC using the array called PFT_TO_MTC. If you want your 14th PFT to possess the carateristics of the C3 grass , set exactly in « orchidee.def » :
NVM =14 PFT_TO_MTC__14 = 10
(the 10th MTC is C3 grass according to the previous array)
At this point, your new pft will share automatically all the standard values taken by the parameters of the C3 grass.
b) Now, your new PFT is not exactly the C3 grass. It differs from the C3 grass by one value. For example, let's suppose that the LAI_MAX parameter for your PFT is different from the standard value. All you have to do is to set in the « orchidee.def »:
LAI_MAX__14 = 3.5
These two examples are not similar : in the first case, you change the LAI_MAX value from the default one for the PFT 10 (C3 grass). In the second case, you introduce a new specie of C3 grass as the 14 th PFT.
You have just seen an example with one parameter. You are not limited to one : you can change the values for any given set of parameters.You can also change NVM in the other way ; you could set NVM less than 13 and considering only a given number of MTCs (4 or 5 for example)
Let's suppose you only want temperate vegetation and natural grass for your job. All you have to do is to set :
NVM = 6 PFT_TO_MTC__01 = 1 PFT_TO_MTC__02 = 4 PFT_TO_MTC__03 = 5 PFT_TO_MTC__04 = 6 PFT_TO_MTC__05 = 10 PFT_TO_MTC__06 = 11
NB: Concerning the other arrays parameters
For the other arrays parameters, you have to set directly the new values.
For example, let's consider the parameter called albsoil_vis. His key word is ALBSOIL_VIS and it is of dimension 9, corresponding to the dimensioning parameter for the soil color numbers and their albedo. Its standard values are :
albsoil_vis = (/0.18, 0.16, 0.16, 0.15, 0.12, 0.105, 0.09, 0.075, 0.25/)
If you want to change the third value, set in « orchidee.def » :
ALBSOIL_VIS__03 = 0.25
(for example). You could change the values of the third, sixth and ninth components. Just set :
ALBSOIL_VIS__03 = 0.25 ALBSOIL_VIS__06 = 0.120 ALBSOIL_VIS__09 = 0.27
This last example is available for all parameters-arrays (PFT or others), except PFT_TO_MTC.
Warning : all parameters depend on the differents flags of ORCHIDEE like river_routing, ok_co2, ok_stomate, etc.... For example, the parameters used by stomate will be read only if the option STOMATE_OK_STOMATE is set to TRUE in « orchidee.def ». You will find the list of the flags and the corresponding parameters in « sechiba_parameters_default_values.txt » and « stomate_parameters_default_values.txt ».
How can you control your values after your job
If you want to see if ORCHIDEE takes into account your modifications, you must go in a first step to the following folder :
...../IGCM_OUT/OL2/JOB_JobName/OOL/Debug/
You will find three types of files (this is a my own example, replace SECHSTOM by the name of your job) :
SECHSTOM_19820101_19820131_out_orchidee_ol SECHSTOM_19820101_19820131_run.def SECHSTOM_19820101_19820131_used_run.def .....
The file « SECHSTOM_19820101_19820131_run.def » is a copy of your initial « orchidee.def ».
In this one, you could find of course the values you imposed.
The file « SECHSTOM_19820101_19820131_used_run.def » contains the list of all the parameters read by the driver in « orchidee.def ». For the scalar parameters read by ORCHIDEE, you will find this comment for example in « SECHSTOM_19820101_19820131_used_run.def » :
# Values of LIMIT_NORTH comes from run.def
Thanks to that coment, you know that the LIMIT_NORTH parameter has been imposed by the user. Unfortunately, in the case of the arrays, it will give you only the values which were default or imposed. For example, you could find :
# Values of LAI_MAX are all defaults.
or :
# Values of ALBSOIL_VIS are a mix of run.def and defaults
but it won't tell you which value is default or not. Normally, it would be sufficient to know if ORCHIDEE has correctly read your « orchidee.def ».
The file « SECHSTOM_19820101_19820131_out_orchidee_ol » will list only the default values :
USING DEFAULTS : ALBSOIL_VIS__00001 = 0.180000000000000 USING DEFAULTS : ALBSOIL_VIS__00002 = 0.160000000000000 USING DEFAULTS : ALBSOIL_VIS__00004 = 0.150000000000000 USING DEFAULTS : ALBSOIL_VIS__00005 = 0.120000000000000
You notice that
ALBSOIL_VIS__03
is missing. Comparing the files « SECHSTOM_19820101_19820131_used_run.def » and « SECHSTOM_19820101_19820131_run.def » to be absolutely sure to know whether ORCHIDEE has taken into account your new values.
Some rules to respect for this version
There are few rules you have to respect for the moment (discussions are needed with the people involved to solve these restrictions) :
-First rule: Except if you use the standard configuration of ORCHIDEE, you always have to fill the array PFT_TO_MTC in « orchidee.def ».
It is very important because without it, the code won't be able to make the link between PFT and MTC. The dimension of PFT_TO_MTC is NVM. Even the parameter NVM is optional : if you don't set it, NVM will take the default value 13.
So if you have more PFTs, ORCHIDEE will only read the first 13 values of your correspondence table. This rule is also applied to the two following parameters when you activate IMPOSE_VEG :
SECHIBA_VEG SECHIBA_VEGMAX
The sum of the elements of SECHIBA_VEG and SECHIBA_VEGMAX must be equal to 1.
-Second rule : You have to generate yourself or to provide your veget map with the good number of PFTs for using the "externalized" version. Soon a python script will be provided for generating a veget map. This veget map is based on the Olson classification. With the script, you will be able to choose the number of PFTs of your map. A page on the wiki will be created.
If you don't want to use a new map, you can set the flag IMPOSE_VEG to TRUE. In this case, you will work without a veget map. Be sure to have filled PFT_TO_MTC.
-Third rule :the first PFT has to be associated to the first MTC :
ie PFT_TO_MTC__01 = 1
Moreover, you can't have two PFTs corresponding to the bare soil . To sum up, the only PFT associated to the bare soil (the first MTC) has to be the first PFT.
Other aspects
-In order not to have a « big » file filled with 300 parameters and all their default values, the new « orchidee.def » file contains no default values. It lists only the description of the parameters anf their key words. You find an example here :
# Vegetation distribution within the mesh (0-dim mode) # If IMPOSE_VEG # The fraction of vegetation is read from the restart file. # If it is not found there we will use the values provided here. # SECHIBA_VEG
The goal is that « orchidee.def » will be filled only by the values the user imposed. You could easily see the new values of the parameters. (see « How can you control your values after your job »).You will find all the default values and their types by two different ways : there are files called « orchidee_run_parameters.txt », « sechiba_parameters_default_values.txt » and « stomate_parameters_default_values.txt »which list all the default values used in the code. This is the « user's » way. The second is the « developper's » way : look at the files called « constantes.f90 » and « constantes_mtc.f90 » in the src_parameter folder.
PS :The next objective will be to divide « orchidee.def » in three parts : « orchidee_run.def » which will contain all the global options for a job, « sechiba_parameters.def » and « stomate_parameters.def » «containing respectively the specific parameters for sechiba and for stomate.
-Only for the PFT parameters, you can use an option called IMPOS_PARAM. If you set it to FALSE, all the new values you put to the PFT parameters won't be read. If you make many changes for one job and you want to compare with the default values, you don't need to comment the values you impose. We think about the same mechanism for the other parameters (you could find all them in constantes.f90).
-Except for PFT_TO_MTC and a few exceptions, the values of the parameters you will set are not controled. (We can't put 300 barriers) Read the different « .txt » files before making some changes. For debugging the version, you could find the specific error messages on the following wiki page : ErrorsMessages?
MARCH 2011
PS : In the most recent version of ORCHIDEE, you will find three files instead of "orchidee.def". These files are called "driver.def","sechiba.def" and "stomate.def". You can choose to define your parameters in any of these files because ORCHIDEE can make the merge.
JULY 2011
When you work with this version, I advice you to document you run.def file specially when you don't use the standard configuration.
This is important if you want to use the same MTC.
In this case, you should give names to your PFTs. You got two ways to do it : comment your *.def file or using
the variable PFT_name.
Let's suppose you want to work on forests with 3 differents species.
You could have the following run.def file :
# Nb of PFTs : NVM = 4 # Correspondance table # sol_nu/bare_ground PFT_TO_MTC__01 = 1 # hetre/beech PFT_TO_MTC__02 = 6 # chene/oak PFT_TO_MTC__03 = 6 # bouleau/birch PFT_TO_MTC__04 = 6
or you can use the variable called PFT_NAME :
# Nb of PFTs NVM = 4 # Correspondance table PFT_TO_MTC__01 = 1 PFT_TO_MTC__02 = 6 PFT_TO_MTC__03 = 6 PFT_TO_MTC__04 = 6 # Names of the pfts PFT_NAME__01 = bare_ground PFT_NAME__02 = beech PFT_NAME__03 = oak PFT_NAME__04 = birch
By default, PFT_NAME contains the names of the MTCs.
If you choose the second manner, you will find in the output files *_out_orchidee_ol :
the PFT 1 called sol_nu corresponds to the MTC : bared ground the PFT 2 called hetre corresponds to the MTC : temperate broad-leaved summergreen the PFT 3 called chene corresponds to the MTC : temperate broad-leaved summergreen the PFT 4 called bouleau corresponds to the MTC : temperate broad-leaved summergreen
It is only a data variable for the moment, so do as you please.
Advice for developpers only ==
Our strategy was to centralize all the parameters in src_parameters. We think that this is better for the maintenance.
If some people for their developpements want to add a new permanent metaclass or a new pft parameter (like Q10), they only have to modify the file constantes_mtc.f90 and add all the new values (don't forget to change the parameter 'nvmc' representing the number of MTCs).
