ORCHIDEE Documentation Work

AIM, PINCIPLES, 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_111201_Part1.pdf​, 2-ScientificDocumentation_111201_Part2.pdf​ and * 2-ScientificDocumentation_111201_Part3.pdf​
3. Who does what? 4-Retreat_Workload_111201.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 poit (to avoid documenting old code). Protocol for documenting source code 3-Protocol_111201.doc​ Stomate_alloc.f90 stomate_alloc.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.6.2 of Doxygen has been compiled on obelix2 here :

/home/users/mmancip/PROG/doxygen-1.6.2

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_DOC_1_9_5_2/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 Martial version in modipsl/util directory with :

where_is_TOOLS/recup_my_ORCHIDEE my_svn_login perso/martial.mancip 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 -doc

to get your own version of the martial trunk documentation.

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.

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.)