Index: /trunk/DocHFI_L2/sdg.tex
===================================================================
--- /trunk/DocHFI_L2/sdg.tex	(revision 794)
+++ /trunk/DocHFI_L2/sdg.tex	(revision 794)
@@ -0,0 +1,278 @@
+\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}
