wiki:documentation

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) {
...
}
Last modified 5 years ago Last modified on 09/22/14 15:45:42