Documentation

Main Version

Other Versions

Scripts

Forcings

Evaluation

Tools

Meetings

Seminars

Contact

Documentation

Here below are some links towards presentations of ORCHIDEE model and related papers of reference. In a near future, a dynamic documentation will be written based on Doxygen software.

• OrchideeDocumentation? using Doxygen to prepare the scientific and technical documentation

• CMIP5 METAFOR MetaforOrc? questions.

• OrchideeParameters? : list of the parameters used by the model (to complete)

Main Presentations

• Technical notes from G. Krinner that give the main equations of STOMATE and LPJ components. ​note.technique_krinner99.ps
  
• A presentation that gives the structure in which ORCHIDEE was coded. ​orchidee.pdf
• A presentation that gives a brief overview of the processes, structure and inputs/outputs structure of ORCHIDEE ​cours_orchidee_sept2011.pdf
• Installation and off-line usage of ORCHIDEE with modipsl framework and libIGCM running environnement ​Cours-ORCHIDEE-oct2011
• Orchidee code is versionned with Subversion software. See SubVersion? page for all commands.And Didier Solyga course ​here

Papers of reference

• Ducoudré, Nathalie I., Laval, Katia, et Perrier, Alain (1993). SECHIBA, a New Set of Parameterizations of the Hydrologic Exchanges at the Land-Atmosphere Interface within the LMD Atmospheric General Circulation Model. Journal of Climate, 6(2), 248--273.​link
• Polcher, J., Laval, K., Dümenil, L., Lean, J., et Rowntree, P. R. (1996). Comparing three land surface schemes used in general circulation models. Journal of Hydrology, 180(1-4), 373--394. ​link
• Ducharne, A., Laval, K., et Polcher, J. (1998). Sensitivity of the hydrological cycle to the parametrization of soil hydrology in a GCM. Climate Dynamics, 14, 307--327. ​link
• Rosnay, P. de et Polcher, J. (1999). Modelling root water uptake in a complex land surface scheme coupled to a GCM. Hydrol. Earth Syst. Sci., 2(2/3), 239--255. ​link
• Krinner, G., Viovy, N., Noblet-Ducoudre, N. de, Ogee, J., Polcher, J., Friedlingstein, P., Ciais, P., Sitch, S., and Prentice, I. C (2005). A dynamic global vegetation model for studies of the coupled atmosphere-biosphere system. Global Biogeochem. Cycles, 19, GB1015. ​link
• d'Orgeval, T. et Polcher, J. (2008). Impacts of precipitation events and land-use changes on West African river discharges during the years 1951--2000. Climate Dynamics, 31(2), 249--262. ​link
• Guimberteau M., Laval K., Perrier A. and Polcher J.: Global effect of irrigation and its impact on the onset of the Indian summer monsoon, Climate Dynamics, in press (Available online 5 Dec. 2011), doi:10.1007/s00382-011-1252-5 ​link
• Guimberteau, M., Drapeau, G., Ronchail, J., Sultan, B., Polcher, J., Martinez, J.-M., Prigent, C., Guyot, J.-L., Cochonneau, G., Espinoza, J. C., Filizola, N., Fraizy, P., Lavado, W., De Oliveira, E., Pombosa, R., Noriega, L., and Vauchel, P. (2012): Discharge simulation in the sub-basins of the Amazon using ORCHIDEE forced by new datasets, Hydrol. Earth Syst. Sci., 16, 911-935, doi:10.5194/hess-16-911-2012, 2012 ​link

Documentation for ORCHIDEE_OL scripts

When you have installed ORCHIDEE and ORCHIDEE_OL source code for trunk version as described in the ​course, you will find in "modipsl"/config/ORCHIDEE_OL tree some directories for scripts used to run ORCHIDEE in an off-line mode.

We strongly invite you to read other wiki and pdf documentation in addition of this one :

1. ​ModipslBeginner
2. ​Documentation for IPSLCM5 current release of IPSL coupled model gives a lot of links on other documentations. You can find the course on the Global IPSL coupled model ​here
3. ​libIGCM users and developpers documentation.

Some of those documentations are still in french and deal with the global couple model of IPSL (namly IPSLCM5 for CMIP5 exercise). But ORCHIDEE scripts use the same philosophy for executions, tree of directories, etc...

Remark : there is a copy of all ORCHIDEE script directories in model/ORCHIDEE_OL. This is for subversion management and it won't work correctly if you use those directories. You must use ones in config/ORCHIDEE_OL.

libIGCM scripts

libIGCM scripts are used as an SRE (Sytem Running Environment). They are used to manipulate input and output files for an executable (or a set of executables in the couple configuration).

• libIGCM : Set of scripts to launch simulations and posttreat. Modularity and

portability make you jobs work on a lot of machine (super-computer) in the same way.

• Include a master job and a lot of auxilary jobs for post-treatements.
• Documentation : ​http://forge.ipsl.jussieu.fr/libigcm

Technical Documentation

How to understand the operations performed on the variables when written in the history files

1. IOIPSL/src/histcom.f90

First read more about the IOIPSL module that manages the history files here: ​http://www.ipsl.jussieu.fr/~ioipsl/WWW2/index.html

The main information useful for ORCHIDEE is reproduced below:

histdef: The variables which will be written are declared and the following information is passed:

• name of variable
• title
• units
• size of the variable
• operation to be carried out on the variable before writing it
• frequency at which the operations need to be done (positive values are in units of seconds and negative values are in units of month)
• frequency at which the resulting data need to be written into the file(positive values are in units of seconds and negative values are in units of month)

Allowed operations

In histdef the user may specify for each field that is going to be archived a number of operations. 3 types may be distinguished: Vector operations, vector-scalar operations and index operations on the vector. In the description of the operations to be carried out the vector will be represented by x. For instance a gather operation will be written "gather(x)". It must be noted that the indexing operations will use as index vector the one passed to histwrite. On top of this a time operation has to be chosen. There only one is allowed and it should be outer most operator. For instance the time averaging of the gather operation will be written as "ave(gather(x))".

• Allowed time operations:

ave	time average of the field
inst	instantaneous values of the field is going to be written
t_min	the minimum value over the time period is going to be archived
t_max	the maximum value over the time period is going to be archived
t_sum	sums the variable over time
once	the field is written once on the file without any time axis
never	the field is never written

• Allowed vector operations:
  

Usage: cels(x)

cels	transforms the field into degrees Celsius

• Allowed vector-scalar operations:
  

Usage: scal*x

*	multiplication

• Allowed indexing operations:
  

Usage: gather(x)

gather	Gathers from the input data all the points listed in index and puts them onto the file. Other points in the resulting array are going to labeled as missing. This operation could be used to reduce the resolution of  the history file.
scatter	Scatters from the input data onto the points which are listed in the index. Other points are going to be labeled as missing. This is used for instance to put a variable only available over oceans onto a global grid.

Examples:

• ave(scatter(cels(X)): Will average the variables (temperature for instance) in celsius and scatter it onto the grid. This could be used in an ocean model where all grid points are in a vector and cover only ocean points. Thus in the history file you will have the field placed correctly on the map.
• ave(max(cels(x),0.)): Average over time only the temperature (if that is the variable in Kelvin) which are above 0.
• t_max(X): Computes the maximum over the time between two writes of the variable.

2. src_sechiba/intersurf.f90

The histdef calls are made in the intsurf_history subroutine for the sechiba history file and similarly in the stom_define_history subroutine for the stomate history file.

Characters strings are first declared to perform units conversion for fluxes:

!! Operations to be performed on fluxes
CHARACTER(LEN=30)   :: flux_op     
!! Operations which do not include a scatter               
CHARACTER(LEN=30)   :: flux_sc    
!! Operation in seconds                
CHARACTER(LEN=30)   :: flux_insec, flux_scinsec 

The history level will determine the number of output variables:

!! history output level (default is 10 => maximum output)
INTEGER(i_std)     :: hist_level 

The following strings arrays will contain the operation to perform from 1 to hist_level and contain ‘never’ from hist_level to 10, meaning there is nothing to do (the variable is not written in the history file).

!! The various operations to be performed
CHARACTER(LEN=40),DIMENSION(max_hist_level) :: &
         & ave, avecels, avescatter, fluxop, &
         & fluxop_scinsec, tmincels, tmaxcels, once, sumscatter  

For fluxes, the operation is written as a string with IOIPSL operators including a multiplication by the number required to obtain the desired output unit:

WRITE(flux_op,'("ave(scatter(X*",F8.1,"))")') one_day/dt
WRITE(flux_sc,'("ave(X*",F8.1,")")') one_day/dt
WRITE(flux_insec,'("ave(X*",F8.6,")")') un/dt
WRITE(flux_scinsec,'("ave(scatter(X*",F8.6,"))")') un/dt

Reading of the chosen history level from the run.def file:

!Config  Key  = SECHIBA_HISTLEVEL
!Config  Desc = SECHIBA history output level (0..10)
!Config  Def  = 5
!Config  Help = Chooses the list of variables in the history file. 
!Config         Values between 0: nothing is written; 10: everything is 
!Config         written are available More details can be found on the web under documentation.
!Config         web under documentation.
hist_level = 5
CALL getin_p('SECHIBA_HISTLEVEL', hist_level)

!- define operations as a function of history level.
!- Above hist_level, operation='never'
ave(1:max_hist_level) = 'ave(X)'
IF (hist_level < max_hist_level) THEN
       ave(hist_level+1:max_hist_level) = 'never'
ENDIF
sumscatter(1:max_hist_level) = 't_sum(scatter(X))'
IF (hist_level < max_hist_level) THEN
       sumscatter(hist_level+1:max_hist_level) = 'never'
ENDIF
avecels(1:max_hist_level) = 'ave(cels(X))'
IF (hist_level < max_hist_level) THEN
       avecels(hist_level+1:max_hist_level) = 'never'
ENDIF
avescatter(1:max_hist_level) = 'ave(scatter(X))'
IF (hist_level < max_hist_level) THEN
       avescatter(hist_level+1:max_hist_level) = 'never'
ENDIF
tmincels(1:max_hist_level) = 't_min(cels(X))'
IF (hist_level < max_hist_level) THEN
       tmincels(hist_level+1:max_hist_level) = 'never'
ENDIF
tmaxcels(1:max_hist_level) = 't_max(cels(X))'
IF (hist_level < max_hist_level) THEN
       tmaxcels(hist_level+1:max_hist_level) = 'never'
ENDIF
fluxop(1:max_hist_level) = flux_op
IF (hist_level < max_hist_level) THEN
       fluxop(hist_level+1:max_hist_level) = 'never'
ENDIF
fluxop_scinsec(1:max_hist_level) = flux_scinsec
IF (hist_level < max_hist_level) THEN
       fluxop_scinsec(hist_level+1:max_hist_level) = 'never'
ENDIF
once(1:max_hist_level) = 'once(scatter(X))'
IF (hist_level < max_hist_level) THEN
       once(hist_level+1:max_hist_level) = 'never'
ENDIF

If for example hist_lev=5, for a variable with a corresponding histdef call containing operator(6), operator(6) is ‘never’ and the variable won’t appear in the history file. For another variable with a corresponding histdef call containing operator(4), the variable will be processing according to the operator definition and written in the history file.

Example:

ALMA convention

Here we divide per dt to get per seconds:

CALL histdef(hist_id, 'Evap', 'Total Evapotranspiration', 'kg/m2/s', & 
           & iim,jjm, hori_id, 1,1,1, -99, 32, fluxop_scinsec(1), dt, dw) 

NOT ALMA

Here we multiply per one_day/dt to get per days:

CALL histdef(hist_id, 'evap', 'Evaporation', 'mm/d', & 
           & iim,jjm, hori_id, 1,1,1, -99, 32, fluxop(1), dt, dw)