ORCHIDEE Documentation Work

AIM, PRINCIPLES, EXAMPLES

Background

The documentation of ORCHIDEE 1.9.5.1 and older versions was found to be incomplete, inconsistent in its level of detail, tri-lingual, fragmented and published in black, grey and white literature. Although considerable work had been done, it was difficult for ORCHIDEE users to benefit from the documentation. Given the complexity of ORCHIDEE, incomplete and inconsistent documentation detered new ORCHIDEE users and did not meet traceability standards required by modern science.

Following a preparatory phase, a group effort was launched by late 2011 to reorganise, complete and harmonize the scientific and technical documentation of ORCHIDEE v. 1.9.5.2 in a state-of-the-art searchable archive (pdf and html). This new documentation serves multiple-purposes :

• The basic information for beginners to get started
• Analytical tool to understand model results for advanced ORCHIDEE users.
• Guarantee traceability. The documentation reflects the version of the code that has been compiled and is integrated into the svn system.

This effort was organized in three stages i.e. tier 1, tier 2 and tier 3. Tier 1 documentation consists of the documented source code. Tier 2 uses basic dOxygen commands to extract information from the source code and regroups it in an html and pdf document. Tier 2 documentation still follows the sequential structure of the source code itself. Finally, tier 3 follows a process-based logic. Ideally, users should be able to follow the computational chain from forcing to history file or the other way around i.e. how is LAI calculated and updated throughout the code?

Status of this effort

• Tier 1: All scientific modules of v.1.9.5.2 are consistently documented, the source code of these modules has been stored in a separate documentation branch on the svn system.
  
• Tier 2: All scientific modules of v.1.9.5.2 have been compiled in a pdf and html document. This document is currently being reviewed and completed with an overall model description. The documentation branch is being tested against v1.9.5.2 for numerical consistency. Tier 2 is expected to be released in spring 2012.
  
• Tier 3: This effort will start in autumn 2012
  

PROTOCOL

Guidelines

Tier 2 and 3 extract the comment text of tier 1. Comment extraction makes use of dOxygen. To accommodate our specific needs advanced custom-made dOxygen scripts were developed. Therefore it is essential to follow the instructions and respect the syntax.

• Each module starts with a module header (see example below) - notice the use of !, !!, !>\, !!\n and !_
  
• Each subroutine starts with a subroutine header (see example below) - notice the use of !!, !>\, !!\n and !_
  
• Each function starts with a function header (see example below) - notice the use of !!, !>\, !!\n and !_
  
• A line should contain no more than 132 characters
  
• Variable are commented AFTER variable declaration
  
• A variable without units is labelled as (unitless)
  
• If the range of the variable is know, this range is given i.e. (0-1, unitless)
  
• Units are written in latex and no fractions should be used i.e. (m s^{-1}) instead of (m/s)
  
• Units are contained within the following tags @tex ($m s^{-1}$) @endtex
  
• Flowcharts are made with dia and stored as *.dot
  
• Each equation is saved as a separate file. The equation is written in latex contained between \begin{equation} and \end{equation}. This file is named of the subroutine/function it belongs to.
  
• Tier 2 extracts comments preceded by a number i.e. !! 1. Initialize variable and organizes these comments as a 'table of content'. Take this in mind when numbering sections of code and use short headers. More information can be given below the header.
• For the declaration part, please use:

!! 0. Variables and parameter declaration
!! 0.1 Input variables
!! 0.2 Output variables
!! 0.3 Modified variables
!! 0.4 Local variables

• Tier 1 and tier 2 do not extract the comments below the section declaring the variables. Tier 3 should do so. In preparation of Tier 3, please duplicate the equations in the header description and the source code. Use !! for comments that should be extracted by tier 3, use ! for comments that help to understand the flow of the code but should be printed in the pdf and html.
  
• Tier 3 will make use of scripts extending the functionality of Doxygen. One such script tags blocks of code (@codeinc). These blocks will end up in the documentation. This functionality was thought to be essential as it is the only way to make sure that the most recent changes to the code end-up in the documentation.
  

Useful tools

• An Open Office plugin (​writer2latex) is available to convert all type of Open Office files to Latex. Hence, existing documents can be easily transformed.
  
• A script is available to truncate lines at 132 characters and to neatly organize the lay-out of the variable declaration.
  

Examples

• MODULE

  ! =================================================================================================================================
  ! MODULE       : forestry
  !
  ! CONTACT      : orchidee-help _at_ ipsl.jussieu.fr
  !
  ! LICENCE      : IPSL (2006)
  ! This software is governed by the CeCILL licence see ORCHIDEE/ORCHIDEE_CeCILL.LIC
  !
  !>\BRIEF       Gathers the main elements for forest management: the "forestry"
  !! subroutine, which itself calls a set of subroutines
  !! forestry_clear, clearcut, thinning, harvest, force_load, QsortC, and
  !! Partition, and a set of functions used in these subroutines.
  !!
  !!\n DESCRIPTION: None
  !!
  !! RECENT CHANGE(S): None
  !!
  !! REFERENCE(S)	:
  !! - Asael, S., 1999. Typologie des peuplements forestiers du massif vosgiens. 
  !! C.R.P.F. Lorraine-Alsace, Nancy, 54 p.
  !! - Bellassen, V., Le Maire, G., Dhote, J.F., Viovy, N., Ciais, P., 2010. 
  !! Modeling forest management within a global vegetation model  Part 1: 
  !! model structure and general behaviour. Ecological Modelling 221, 24582474.
  !! - Bellassen, V., Le Maire, G., Guin, O., Dhote, J.F., Viovy, N., Ciais, P., 
  !! 2011a. Modeling forest management within a global vegetation model  Part 2: 
  !! model validation from tree to continental scale. Ecological Modelling 222, 
  !! 5775.
  !!
  !! SVN          :
  !! $HeadURL: $
  !! $Date: $
  !! $Revision: $
  !! \n
  !_ ================================================================================================================================
  

• SUBROUTINE

  !! ================================================================================================================================
  !! SUBROUTINE   : pheno_moigdd
  !!
  !>\BRIEF          The 'moigdd' onset model initiates leaf onset based on mixed temperature
  !!                and moisture availability criteria.
  !!                Currently PFTs 10 - 13 (C3 and C4 grass, and C3 and C4 agriculture)
  !!                are assigned to this model.
  !!
  !! DESCRIPTION  : This onset model combines the GDD model (Chuine, 2000), as described for
  !!                the 'humgdd' onset model (::pheno_humgdd), and the 'moi' model, in order
  !!                to account for dependence on both temperature and moisture conditions in
  !!                warmer climates. \n
  !!                Leaf onset begins when the a PFT-dependent GDD threshold is reached.
  !!                In addition there are temperature and moisture conditions.
  !!                The temperature condition specifies that the monthly temperature has to be
  !!                higher than a constant threshold (::t_always) OR
  !!                the weekly temperature is higher than the monthly temperature.
  !!                There has to be at least some moisture. The moisture condition
  !!                is exactly the same as the 'moi' onset model (::pheno_moi), which has
  !!                already been described. \n
  !!                GDD is set to undef if beginning of the growing season detected.
  !!                As in the ::pheno_humgdd model, the parameter ::t_always is defined as
  !!                10 degrees C in this subroutine, as are the parameters ::moisture_avail_tree
  !!                and ::moisture_avail_grass (set to 1 and 0.6 respectively), which are used
  !!                in the moisture condition (see ::pheno_moi onset model description). \n
  !!                The PFT-dependent GDD threshold (::gdd_crit) is calculated as in the onset
  !!                model ::pheno_humgdd, using the equation:
  !!                \latexonly
  !!                \input{phenol_hummoigdd_gddcrit_eqn.tex}
  !!                \endlatexonly
  !!                \n
  !!                where i and j are the grid cell and PFT respectively.
  !!                The three GDDcrit parameters (::pheno_crit%gdd(j,*)) are set for each PFT in
  !!                ::stomate_data, and three tables defining each of the three critical GDD
  !!                parameters for each PFT is given in ::gdd_crit1_tab, ::gdd_crit2_tab and
  !!                ::gdd_crit3_tab in ::stomate_constants. \n
  !!                The ::pheno_moigdd subroutine is called in the subroutine ::phenology.
  !!
  !! RECENT CHANGE(S): None
  !!
  !! MAIN OUTPUT VARIABLE(S): ::begin_leaves - specifies whether leaf growth can start
  !!
  !! REFERENCE(S) :
  !! - Botta, A., N. Viovy, P. Ciais, P. Friedlingstein and P. Monfray (2000),
  !! A global prognostic scheme of leaf onset using satellite data,
  !! Global Change Biology, 207, 337-347.
  !! - Chuine, I (2000), A unified model for the budburst of trees, Journal of
  !! Theoretical Biology, 207, 337-347.
  !! - Krinner, G., N. Viovy, N. de Noblet-Ducoudre, J. Ogee, J. Polcher, P.
  !! Friedlingstein, P. Ciais, S. Sitch and I.C. Prentice (2005), A dynamic global
  !! vegetation model for studies of the coupled atmosphere-biosphere system, Global
  !! Biogeochemical Cycles, 19, doi:10.1029/2003GB002199.
  !!
  !! FLOWCHART    :
  !! \latexonly
  !! \includegraphics[scale = 1]{pheno_moigdd.png}
  !! \endlatexonly
  !! \n
  !_ ================================================================================================================================
  

• FUNCTION

  !! ================================================================================================================================
  !! FUNCTION     : bm_vol
  !!
  !>\BRIEF        ! This allometric function computes biomass as a function of
  !! volume at stand scale. biomass \f$gC m^{-2}) = f(volume (m^3 ha^{-1}))\f$
  !!
  !! DESCRIPTION : None
  !!
  !! RECENT CHANGE(S): None
  !!
  !! RETURN VALUE : bm_vol
  !!
  !! REFERENCE(S) : See above, module description.
  !!
  !! FLOWCHART    : None
  !! \n
  !_ ================================================================================================================================
  

TECHNICAL ASPECTS

Documentation branch

To download the documented version from the svn system, please, consult this document ​here

Why dOxygen?

Fabienne checked the functionality of the following software tools:

1. Robodoc ​http://www.xs4all.nl/%7Erfsber/Robo/robodoc.html
2. Fordocu ​http://www.vortech.nl/en/software/fortran-documentation-generator/
3. Doxygen ​http://www.stack.nl/~dimitri/doxygen/

It was decided to continue using dOxygen as the user community seems the largest (of the three tools) and the most active. In addition, new releases of Doxygen are made available regularly and the software currently has an extensive functionality.

dOxygen

Version 1.7.3 of Doxygen have been patched and compiled on obelix2 here :

/home/users/mmancip/PROG/Release_1_7_3_20110217

and installed in this directory :

/home/users/mmancip/PROG/bin

You can add this tool to your own environment (here in .login file for tcsh shell) :

setenv PATH /home/users/mmancip/PROG/bin:$PATH
if ! ($?LD_LIBRARY_PATH) then
     setenv LD_LIBRARY_PATH /home/users/mmancip/PROG/lib
else
     setenv LD_LIBRARY_PATH /home/users/mmancip/PROG/lib:${LD_LIBRARY_PATH}
endif

A version 2.28.0 of graphviz set of tools has been installed in the same path. It contains last version of dot scheme builder.