ORCHIDEE Documentation Work

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 any traceability or reproducibility 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 and the simulation reproducible.

Guiding principles (2/2011)

1. The user should be able to follow (by means of hyper-links) the computational chain from forcing to history file or the other way around.
2. The documentation should 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. The documentation needs to serve 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.
4. Special attention should be paid to flags that determine the modelling sequence, such flags should be documented and become searchable.
5. The functionality of the documentation should work even when the documentation is incomplete. This gives time to improve and complete the content over time.

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.

Implementation (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.

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

Demonstration (9/2011)

Fabienne will use existing and new functionalities of Doxygen to merge existing documentation with the phenology module. This will be a first example where attention will be paid to the content and appearance of the documentation. An initial set of rules has been defined but this set will most likely change following the experiences of Fabienne.

1. Document the smallest possible units i.e. a line of code or a couple of lines. This approach ensures that following an initial effort it is a lot easier to keep the documentation up to date as there is a clear relationship between the documentation and the code.
2. Have a scientific description at the start of the code. Avoid lengthy blocks of text because this is hard to maintain and will most likely get outdated pretty fast. It can also hamper readability of the code.
3. Give full references of the scientific literature used in support of the code.
4. Add flow charts to explain the structure of the (nested) if-then-else.
5. Each variable/parameter has a standardized description containing the following fields: Variable name, Local/Global, Dimensions, units.

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.

Open 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.
5. Could we think of a set of rules to decide when we copy code to the documentation? Should we define a common vocabulary of verbs i.e. convert, transfer, transform, ...
6. Could we set up a searchable database for variables (ecology based)? A searchable database of code-based variables is a basic functionality of Doxygen.

Future activities

1. Present demonstration project at a reunion suivi (Fabienne & Martial)
2. Refine documentation protocol (Sebastiaan, Fabienne & Martial)
3. Develop additional functionality if essential for tier 1 documentation (Martial)
4. Organise documentation retreat (12/2011?)
5. We have to define standard header for all documented module. Martial has listed some header [attach:capsule.f90].
6. Release and test tier 1 documentation.
   First step commited in perso/Martial.Mancip branch (opened).
7. Plan for tier 2 documentation.

Preparation of the Retreat (01/12/2011)

Presentations

• 1-Retreat_intro_111201.ppt​
• 2-ScientificDocumentation_111201_Part1.pdf​
• 2-ScientificDocumentation_111201_Part2.pdf​
• 2-ScientificDocumentation_111201_Part3.pdf​
• 3-Protocol_111201.doc​
• 4-Retreat_Workload_111201.doc​

Actions

• Technical: Propose a Module Header (F.M.).
• Technical: Create a LaTeX file grouping 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: 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.)
• Organization: Plan a second meeting early in January to ensure the preparation of the retreat is efficient. (F.M.)
• Communication: A report could be presented at the end of the retreat to some VIPs (IPSL, LSCE, LMD). (P.P.)

What P. Peylin would like all of contributors to remember:

• Better more than less.
• Equations are very useful.
• A flowchart is mandatory for all large subroutines.
• DO NOT MODIFY THE CODE (only comments), but do not hesitate to do suggestions maybe in a separate file if you think about changing some variables names, modifying the structure to be more efficient (do/enddo, if/endif, ...), remove some obsolete code, ...