source: Sophya/trunk/DocHFI_L2/sdg.tex@ 845

\documentclass[twoside,12pt]{article}
%  Package standard : Utilisation de caracteres accentues, mode francais et graphique
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{graphicx}

%  Extension de symboles mathematiques
\usepackage{amssymb}

%  Definition de taille de page
\setlength{\textwidth}{16cm}
\setlength{\textheight}{21.5cm}
\setlength{\topmargin}{0.5cm}
\setlength{\oddsidemargin}{0.cm}
\setlength{\evensidemargin}{0.cm}
\setlength{\unitlength}{1mm}

\newcommand{\bul}{$\bullet \ $}

\begin{document}

\begin{titlepage}
\vspace{1cm}
\rule{110 mm}{0.5 mm}\makebox[50 mm]{\bf Planck HFI L2}
\vspace{2cm}
\begin{center}
\par \renewcommand{\baselinestretch}{2.0} \small 
{\LARGE \bf 
Planck HFI L2 \\ 
Software Development Guidelines
}
\par \renewcommand{\baselinestretch}{1.0} \normalsize
\vspace{5 cm}
\begin{tabular}{ll}
{R. Ansari} & {\tt ansari@lal.in2p3.fr} \\
{É. Aubourg} & {\tt aubourg@hep.saclay.cea.fr} \\
% {É. Lesquoy} & {\tt lesquoy@hep.saclay.cea.fr} \\
% {C. Magneville} & {\tt cmv@hep.saclay.cea.fr} \\
\end{tabular}

\end{center}
\vfill
\hfill 
% \includegraphics[width=4cm]{Fig/hfi_icon_vsmall.eps}
\framebox[\textwidth]{\hspace{0.5cm} \bf Planck HFI Level 2 
\hspace{1cm} \today }
\end{titlepage}

\tableofcontents

\newpage
% \tableofcontents

\section{Introduction}
We intend to gather gradually in this document the guidelines 
for the development of Planck HFI Level 2 data processing softwares.
We assume throughout this document that C++ is the baseline option
as the programming language for the development of Planck HFI 
Level 2 processing software.

\section{Integration of software modules in different languages}
We review here some of the problems which may arise when integrating software 
modules written in other languages into C++ programs.

\subsection{C and C++}
C++ extends the possibilities offered by the C language. 
All of the C language data types and function call syntax are thus 
supported by C++. Among other features, C++ offers the function 
overloading possibility. This means that functions with different 
argument list can have the same name.
\begin{verbatim} 
int fo(int a);
int fo(int a, int b);
int fo(double a, double b);
\end{verbatim}
Using {\bf C}, one would have written:
\begin{verbatim} 
int foi(int a);
int foii(int a, int b);
int fodd(double a, double b);
\end{verbatim}
C++ compilers use internally a name containing the encoding of the
argument list. In order to instruct the compiler to use simple 
names, {\bf C} functions should be declared as \\
{\tt extern "C" }. This is usually included in the header
file (.h). In the example above, the header file (.h) file
would be in the form:
\begin{verbatim} 
#ifdef __cplusplus
extern "C" {
#endif
int foi(int a);
int foii(int a, int b);
int fodd(double a, double b);
#ifdef __cplusplus
}
#endif
\end{verbatim}

\subsection{Fortran and C++}
Fortran is a simple language and uses only basic data types.
Although the exact mapping between Fortran and C/C++ basic data types 
may vary depending on the OS and hardware architecture, it is close
to the one shown in the table below: 
\begin{center}
\begin{tabular}{lll}
INTEGER     &  int    & usually 4 bytes \\
REAL*4      &  float  & usually 4 bytes \\
REAL*8      &  double & usually 8 bytes \\
COMPLEX     &  complex<float> & \\
COMPLEX*16  &  complex<double> & \\
\end{tabular}
\end{center}
In fortran, all arguments are passed by address and 
fortran compilers (on Unix systems) add an underscore "\_"
to all symbol names. It is thus rather easy to call 
Fortran subroutines or functions from C or C++. 
This is illustrated in the following example:
\begin{verbatim}
C   Fortran-Code
      SUBROUTINE FSUB(A,N,B,M)
      REAL A(*),B(*)
      INTEGER N,M
      RETURN
      END
\end{verbatim}
The corresponding C (or C++) declaration is: \\[3mm]
{\tt void fsub\_(float *a, int *n, float *b, int *m); } \\[3mm]
{\tt FSUB} can be called from C code, as is shown below : 
\begin{verbatim}
float aa[10];
int na=10;
float bb[10];    
int mb=10;
fsub_(aa, &na, bb, &mb);
\end{verbatim}

The case of character string arguments in fortran subroutines
needs a bit more attention, and the string length needs to be passed 
as an additional integer type argument.
As with {\bf C} functions, fortran functions or subroutines 
have to be delared {\tt extern "C"} to be used within {\bf C++}
programs. {\bf C/C++} driver routines can easily be written for
extensively used fortran modules, simplifying calling sequences.

It should also be noted that the fortran support libraries have to be 
included for the link with the C++ driver.
It is also possible to translate the whole fortran source code 
into {\bf C} code using {\bf f2c} program. The call syntax 
will be exactly the same as with a Fortran compiler, and 
{\tt libf2c.a} should be used when linking the program.

It is very difficult to use C++ classes directly from fortran.
However, high level functionalities based on a C++ libray can 
be wrapped in a fortran style function which can be 
called from fortran. One looses of course many of the 
possibilities offered by underlying C++ library.

We illustrate below the wrapping of a simple C++ class:
\begin{verbatim}
// An example class performing some computation
class Example {
  Example();
  ~Example();
  void compute(int sz, float *x);
  int getSize();
  float getResult(int k);
};
\end{verbatim}

The wrapper would then look like:
\begin{verbatim}
extern "C" {
  void foradapt_(float *a, int *n, float *b, int *m);
}

foradapt_(float *a, int *m, float *b, int *n)
{
// a is the input array, m it's size
// b is the output array, n the returned size
// b has to dimensioned big enough in the calling program

Example ex;
ex.compute(*n, a);
*m = ex.getSize();
for(int i=0; i<ex.getSize(); i++) 
  b[i] = ex.getResult(i);
}
\end{verbatim}

One can then call {\tt FORADPAT} from fortran :
\begin{verbatim}
REAL  A(1000)
REAL  B(1000)
INTEGER N,M
M = 1000
N = 1000
CALL FORADPAT(A, M, B, N)
\end{verbatim}


\subsection{Fortran-90 and C++}
Fortran-90 (F90) is a much more complex language than Fortran 77
(F77). Compared to F77, it introduces many new constructions, including:
\begin{itemize}
\item[-] pointers 
\item[-] local and global variables
\item[-] in, out, in-out argument type for function and subroutines
\item[-] compound data types, similar to structures in C 
\item[-] multidimensional arrays
\item[-] function and operator overloading.
\end{itemize}
It is thus more difficult to use full featured F90 modules from 
{\bf C} or {\bf C++}. One would have to map all these different 
data structures with their attributes between the two languages,
in a OS/compiler independent way.
It should however be possible to encapsulate F90 modules into simple F77 
like subroutines that could be called from C/C++. 


\newpage
\appendix

\section{The C++ language}
\vspace{5 mm}
{\bf C++} is a very powerful Object Oriented language. 
It has been developped by extending the {\bf C} language, 
keeping in mind the efficiency and performance, 
as well as easy integration with existing softwares.
It incorporates new possibilities such as:

\begin{itemize}
\item Introduction of object and classes
\item function overloading
\item Operator overloading
\item function and operator inlining (optimisation)
\item virtual functions (polymorphism)
\item public, protected and private members
\item dynamic memory management operators
\item Exception handling
\item generic (template) function and classes
\end{itemize}

{\bf C++} can be considered now as a mature language. 
C++ class library covering various areas, including
numerical data processing are available as freeware 
or commercial products. Many software tools feature
a standard C++ API. 
\par \vspace{3mm}
The current standard for C++ and C are defined by
\footnote{Available from {\bf http://www.ansi.org/ } }: 
\begin{itemize}
\item[] {\bf ISO/IEC 14882-1998(E)} Programming languages -- C++ 
\item[] {\bf ANSI/ISO 9899-1990} for Programming Languages C  
\end{itemize}


\newpage
\section{C++ compilers}


Powerful compilers are available on most platforms, 
including:

\begin{itemize}
\item[-] the GNU multiplatform g++ \footnote{http://gcc.gnu.org/},
\item[-] KAI KCC \footnote{http://www.kai.com/C\_plus\_plus/} which is a 
nice multiplatform optimising C++ compiler.
\item[-] Digital (Compaq) cxx \footnote{http://www.unix.digital.com/cplus/}
\item[-] IBM VisualAge C++ \footnote{http://www-4.ibm.com/software/ad/vacpp/}
\item[-] HP aCC \footnote{http://www.hp.com/esy/lang/cpp/}
\item[-] Silicon Graphics SGI-CC on IRIX \footnote{http://www.sgi.com/developers/devtools/languages/c++.html} 
\item[-] Cray C++ compiler on Unicos \footnote{http://www.sgi.com/software/unicos/cplusoverview.html}
\end{itemize} 


\end{document}