ORCHIDEE Documentation Work

AIM, PRINCIPLES, EXAMPLES

Background (2010)

The current documentation of ORCHIDEE is incomplete, inconsistent in its level of detail, tri-lingual, fragmented and has been published in black, grey and white literature. Although considerable work has been done in the past, it is difficult for the current users to benefit from this work. The current organisation of the documentation is unlikely to attract new ORCHIDEE users and it is unlikely to meet traceability standards required by modern science.

Aim (2010)

To reorganise, complete and harmonize the scientific and technical documentation of ORCHIDEE in a state-of-the-art searchable archive. The quality of this archive should be such that it satisfies the needs of the current users, attracts new users, the results become traceable.

Guiding principles (2/2011, 02/12/2011)

1. The documentation serves multiple-purposes i.e. it is the basic information for beginners to get started but it should have additional functionality such that advanced ORCHIDEE users can use it as an analytical tool to understand model results.
2. The documentation will be dynamic in that it is integrated into the svn system. Documentation and executables are compiled at the same time. The documentation reflects the version of the code that has been compiled.
3. Ideally, users should be able to follow (by means of hyper-links) the computational chain from forcing to history file or the other way around.
4. Flags that determine the modelling sequence, should be documented and should become searchable.
5. Tier 1, tier 2 and tier 3 documentation are foreseen. Tier 1 consists of the documented source code, tier 2 uses basic dOxygen commands to extract basic information from the source code and regroups it in an html and pdf document. Tier 2 documentation foolows the sequential structure of the source code itself. Finally tier 3 uses advanced custom-made dOxygen commands that support compiling a process-based logic i.e. how is LAI calculated and updated throughout the code?

Examples and protocol (01/12/2011)

A preratory meeting clarifying the documentation effort was organized on December 1st 2011. The presentation given at the meeting, the agreed workplan and protocol can be downloaded below.

1. Aims, concept and planning of the documentation effort and retreat 1-Retreat_intro_111201.ppt​
2. Annotated example to help the responsibles in preparing documentation 2-ScientificDocumentation_111205_Part1.pdf​ and 2-ScientificDocumentation_111205_Part2.pdf​
3. Who does what? 4-Retreat_Workload_111202.doc​
4. A protocol and two examples were prepared to guide the documentation effort. All can be downloaded below. Alternatively, the examples or can be retrieved from the documentation branch which is readable for everybody (and writable to the administrators). Use the source code from this branch (1.9.5.2) as your starting point (to avoid documenting old code). Protocol for documenting source code 3-Protocol_111202.doc​ Stomate_alloc.f90 stomate_alloc.f90​ Diffuco_trans_co2.f90 diffuco_trans_co2.f90​

Updates to be expected between 01/12/2011 and 19-20/01/2012

• Technical: Template for a Module Header (F.M.).
• Technical: Create a LaTeX file that groups all variables names/symbols used in equations in order to harmonize. If available, add the corresponding CMIP5 name, see ​http://forge.ipsl.jussieu.fr/igcmg/wiki/IPSLCM5A/Sorties/EquivalenceIPSLCMIP5.
• Organization: Plan a second meeting early in January to ensure the preparation stays on track. (F.M.)

THE JANUARY 2012 RETREAT

When going to the retreat > 90% of the work should be done. This implies that at the start of the retreat the draft version of Tier 1 documentation is available. During the retreat we aim for:

• Consultancy with N. Viovy, N. de Noblet, A. Ducharne & Jan Polcher (by phone) to check and clarify hard bits (the remaining <10% that was not prepared before the retreat))
• Documenting overlooked subroutines (Tier 1)
• Reviewing each others documentation (Tier 1)
• Compiling Tier 2 documentation (Tier 2)
• Adding internal hyperlinks for in and output variables (Tier 3)

• Organization: Check if attendees need a 'Mission Order'.
• Organization: Constitute a Review Committee including possibly P. Ciais, G. Krinner, S. Piao, ... (S.L./M.M./P.P.)
• Communication: A report will be presented at the end of the retreat to some VIPs (IPSL, LSCE, LMD). (P.P.)

TECHNICAL ASPECTS

Software tool (5/2011)

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.

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.

Added functionality (9/2011)

Martial coded a script that extents the functionality of Doxygen. The script allows to tag 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.

You can find an example of this demonstration on obelix2 in

/home/users/mmancip/PROG/ORCHIDEE_branch_DOC/modeles/ORCHIDEE/docs

In latex subdirectory, you can find the refman.pdf file to be read with kpdf or acrobat. In html subdirectory, you will find the index.html to be oppened with your browser.

You can get modipsl, ORCHIDEE TOOLS as discribed in SubVersion? wiki page and get DOC branch version in modipsl/util directory with :

where_is_TOOLS/recup_my_ORCHIDEE my_svn_login branch/DOC my_mail@lsce.ipsl.fr

Here, you have to use ins_make script to get correct Makefile in ORCHIDEE.

And then go to

cd ../modeles/ORCHIDEE

and simply execute

./makeorchidee_fcm -rmdoc [-doc_tree] [-doc|-doc_para] 

to get your own version of the documentation branch.

Useful tool

An Open Office plugin (​writer2latex) is available to convert all type of Open Office files to Latex. Hence, existing documents can be easily transformed.

Headers 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
  !_ ================================================================================================================================
  

Questions

1. Can the information of each variable be extended with a list of routines where it is used and calculated?
   No. Only routines are traced by Doxygen.
2. Can the information of each variable be extended with a list of routines where the variable is used?
   No. Only routines are traced by Doxygen.
3. Can the information of each variable be extended with a link to how and where it is initialized?
   No. Only routines are traced by Doxygen. And only global variables (in head of modules) have hyperlink.
4. Doxygen has a graphical tool that shows the links between subroutines. Would something similar be possible to show the links between variables i.e. which functions make use of a certain variable? i.e. show everything that depends on lai (from lai to history files)
   No. Only routines are traced by Doxygen.

SIMPLIFIED TICKET SERVER

1. Organise documentation retreat (DONE)
2. Present documentation effort project at a reunion suivi (DONE)
3. Define standard header [attach:capsule.f90] (DONE).
4. Prepare examples and protocol (DONE)
5. Develop additional functionality if essential for tier 1 and tier 2 documentation (DONE)
6. Organize workload (DONE)
7. Follow-up of documentation effort (F.M./S.L. ONGOING)
8. Test tier 2 documentation. First step commited in perso/Martial.Mancip branch (M.M. ONGOING).
9. Compile tier 2 documentation (M.M.)
10. Prepare tier 3 documentation.(M.M., F.M. & S.L.)
11. Develop additional functionality for tier 3 documentation (M.M.)