wiki:documentation

Version 2 (modified by mhnguyen, 10 years ago) (diff)

Adding some information how to document codes

    1. How to extract and compile XIOS
    2. How to run XIOS test
    3. Documentation policy

How to extract and compile XIOS

  • ./make_xios --help (or ./make_xios -h) 
    make_xios - installs XIOS on your architecture
make_xios [options]
options :
       [--prod] : compilation in production mode (default)
       [--dev] : compilation in development mode
       [--debug] : compilation in debug mode
       --arch arch : to choose target architecture
       [--avail] : to know available target architectures 
       [--full] : to generate dependencies and recompile from scratch
       [--use_oasis] : to use Oasis coupler
       [--doc] : to generate Doxygen documentation (not available yet)
       [--job ntasks] : to use parallel compilation with ntasks
       [--netcdf_lib 'netcdf4_par'/'netcdf4_seq' : default netcdf4_par] : choice of netcdf library
  • Known architectures : ./make_xios --avail 
    GCC_LINUX
GCC_MACOSX
IA64_PLATINE
PW6_VARGAS
X64_CURIE
X64_HORUS
X64_TITANE
X64_TITANE_GCC
X64_TITANE_VAMPIR
X86_LOCGNU_FEDORA
X86_LOCINTEL_FEDORA
XT6_LYNX
  • Compilation
    • On an known architecture. For example : ./make_xios --arch X64_CURIE
    • On an new architecture. You have to create your "arch_NEW_ARCH.fcm" and "arch_NEW_ARCH.path" files
  • Choice of compilation mode. As explained in the "help", there are three compilation modes :
    • [--prod] : compilation in production mode (default)
    • [--dev] : compilation in development mode
    • [--debug] : compilation in debug mode

For example : ./make_xios --dev --arch PW6_VARGAS

  • Use of "arch*.env" file. "arch*.env" file is an optionnal file (used only if it exists) which allows to define a compilation evironment in order to compile XIOS server.

For example : cat arch-X64_TITANE_GCC.env 

module unload bullxmpi
module load openmpi/1.4.2_gnu
module unload intel
module load gcc

export HDF5_INC_DIR=$WORKDIR/hdf5/include
export HDF5_LIB_DIR=$WORKDIR/hdf5_gnu/lib

export NETCDF_INC_DIR=$WORKDIR/netcdf4/include
export NETCDF_LIB_DIR=$WORKDIR/netcdf4_gnu/lib
  • Use of netcdf library. It is possible to use netcdf in parallel mode or sequential mode :
    • --netcdf_lib netcdf4_seq : only the multiple_file writing mode is available.
    • --netcdf_lib netcdf4_par : both one_file mode and mutliple_file mode are available.

How to run XIOS test

The compilation is ok. You have now two executables files in XIOS/bin directory :

  • test_client.exe : a test client executable
  • xios_server.exe : server executable

test_client allows to test XIOS server functionalities : ​http://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/trunk/src/test/test_client.f90

You can play with XIOS using test_client.exe (and xios_server.exe) to run on attached mode (or server mode i.e MPMD mode) using XIOS/inputs/iodef.xml configuration file.

  • Attached mode : 
<variable id="using_server" type="boolean">false</variable>

The xios library is linked to client test. The server executable is not used. The asynchroneous writing mode is not activated. The parallel writing mode (i.e one_file ) is available.

For example on curie machine : ccc_msub Job with Job : 

#!/usr/bin/ksh
#MSUB -r XIOS       # nom de la requete
#MSUB -o Script_Output_XIOS.000001    # nom du fichier de sortie
#MSUB -e Script_Output_XIOS.000001    # nom du fichier de sortie
#MSUB -eo
#MSUB -n 10 # reservation des processeurs pour le job
#MSUB -T 1800             # Limite temps (en secondes)
#MSUB -q standard
#MSUB -Q test
#MSUB -p gen2211

cd /ccc/scratch/cont003/dsm/p86caub/XIOS/bin
/usr/bin/time ccc_mprun ./test_client.exe
  • Server mode 
 <variable id="using_server" type="boolean">true</variable>

The server executable is used. The asynchroneous writing mode is activated. The parallel writing mode (i.e one_file ) is available.

For example on vargas machine : llsubmit Job

with Job : 

# Nom de la requete
# @ job_name = Jobname
# @ job_type = parallel
# Fichier de sortie standard
# @ output = Script_Output_000001
# Fichier de sortie erreur (le meme)
# @ error = Script_Output_000001
# Nombre de processus demandes
# @ total_tasks = 10
# Temps CPU max. par processus MPI hh:mm:ss
# @ wall_clock_limit = 0:10:00
# Memoire max. utilisee par processus
# @ data_limit = 3.2gb
# Memoire stack a etendre si besoin
## @ stack_limit = 0.5gb,0.5gb
# Pas d OpenMP
# @ resources = ConsumableCpus(1)
# Fin de l entete
# @ queue
# @ class = debug
 
cd /workgpfs/rech/ces/rces061/XIOS/bin
poe -pgmmodel MPMD -cmdfile ./run_file

with run_file ( this configuration will launch test_client on 8 processes and xios server on 2 processes ): 

./test_client.exe
./test_client.exe
./test_client.exe
./test_client.exe
./test_client.exe
./test_client.exe
./test_client.exe
./test_client.exe
./xios_server.exe
./xios_server.exe
  • Multiple_file mode 
 <file_definition type="multiple_file">

Each client process (or server process) in attached mode (or server mode) writes its output file. Mode available with both "netcdf4_par" and "netcdf4_seq" as compilation options.

  • One_file mode 
<file_definition type="one_file">

Parallel writing from each client process (or server process) in attached mode (or server mode) to one file. Mode available only with "netcdf4_par" as complation option.

Documentation policy

The documentation is compliant with DOXYGEN syntax and all html documentations are automatically generated in directory doc There are some general points which we should follow:

  • The language of documentation is English
  • Function declarations are documented with brief (one-line, one-sentence) comments and only brief comments.
  • Function definitions (inline or not) are documented with detailed comments.

Below are instructions to document codes in details

  1. File

Here is the structure of the comment one developer should write to document a file (header or source). This part of comment must be at the beginning of a file, before anything else. 

/*!
   \file context.hpp
   \author Yann Meurdesoif 
   \date 25 jan 2011
   \since 3 mar 2007

   \brief comment.

   next part of detailed comment
 */
  • The macro \date indicates file creation date
  • The macro \since specifies the latest modification
  • The macro \brief provides overview information of file

In case of multiple authors, the macro \authors should be used 

/*!
   \file context.hpp
   \authors Yann Meurdesoif, Arnaud Caubel 
   \date 25 jan 2011
   \since 3 mar 2007

   \brief comment.

   next part of detailed comment
 */
  1. Class, typedef, enum and struct

A class documentation is written just before the class declaration/definition in the

header file with the following structure: 

/*!
    \class A
    \brief comment associated to A

    next part of detailed comment associated to A
 */
class A {
...
};

For typedef, enum and struct, instead of the macro \class, the corresponding macros \typedef, \enum and \struct should be used.

  1. Attributes

Simply, attributes should be commented with one of these syntaxes 

class A {
  public :
    //! comment associated to i
    int i;
    double j; //!< comment associated to j
    /*!
      comment associated to k
     */
    B k;
    ...

  1. Functions and constructors

Function declaration is documented with a brief comment, and only a brief comment. All of the following syntaxes, shown here for in-class function but also valid for external ones, can be used 

class A {
  public :
    ...
   //! brief comment associated to declaration of f
   void f();

   /*! 
       brief comment associated to declaration of g
    */
   void g();
   
   void h(); //!< comment associated to declaration of h
};

Functions definitions (inline or not) are documented with detailed comments. If the declaration has not been commented first, the first line of the comment will be the brief comment. The below syntaxes are for inline operations but valid for the other types 

class A {
  public :
    B b;
    ...
   //! comment associated to definition of f
   void f() {
   ...
   }
   void g() //! comment associated to definition of g
   {
   ...
   }
   A() //! comment associated to definition of composite constructor
   : B() 
   {
   ...
   }

   /*!
      comment associated to definition of h
    */
   void h() {
   ...
   }
};
  1. Arguments

Only in the case of a function definition, arguments and return value might be documented with following convention 

/*!
    comment of function f
 */
int f (double d, //!< comment of d
       int i //!< comment of i
      ) {
...
}
/*!
    comment of function g
    \param [in] d comment of d
    \param [in/out] i comment of i
    \return comment of return value
 */
int g (double d, int i) {
...
}