fortran-rules.tex

% Converted with LaTeX2HTML 99.1 release (March 30, 1999)
% original version by:  Nikos Drakos, CBLU, University of Leeds
% * revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
% * with significant contributions from:
%   Jens Lippmann, Marek Rouchal, Martin Wilck and others 
%%\title{fortran-rules}
%  Changed by: Hans Grote, 10-Jun-2002 


\subsection{ Rules for Fortran routines for MAD-X}
\label{subsec:fortran_rules}

\begin{itemize}
 
   \item \textbf{ Code}
     \begin{enumerate}
        \item lower case throughout
	\item all routines start with ``implicit none''
	\item the following types should be used exclusively:    
          \begin{itemize}
	     \item integer - use integer as well instead of logical, 0 = false, else true
	     \item double precision (not real*8)
	     \item complex*16 - only internally, and in cases where it really helps
	     \item character - if this routine can be called from
               outside (i.e. as well from C routines), always foresee a
               length input variable (see example). When calling a C
               routine with character strings, make sure they end with a
               blank (e.g. 'abc ').    
          \end{itemize}
	\item use only generic names for functions, i.e. sin, cos, abs,
          exp etc. and \textbf{ not} dsin, dcos, dabs, dexp etc.;
          nota bene: ANSI for arcus sinus and arcus cosinus is asin
          and acos (not arsin and arcos)   
	\item do not use statement functions, arithmetic IF (3-branch), or IMPLICIT GOTO.  
	\item in DO loops: use always do...enddo constructs.  
	\item IMPORTANT: when transferring  strings to C routines, always terminate the string with a blank, e.g. 
\begin{verbatim}
      call double_to_table('twiss ', 'betx ', betx)
\end{verbatim}
        \item When transferring  integer or double to C routines, always
          use     specific variables (no values or expressions), e.g. to
          receive the     current element name  
\begin{verbatim}
      integer i
      character * 16 name
      i = 16
      call element_name(name, i)
\end{verbatim}
     \end{enumerate}

   \item \textbf{ Style}
     \begin{enumerate}
        \item all modules and stand-alone routines perform all
          input/output through symbolic variables in the call (no
          ``common''); common blocks can be used inside modules,
          however. 
	\item functions return only one (the function-) value and do not
          modify any of the input variables 
	\item all input/output parameters are described, and the routine
          purpose stated 
	\item avoid ``goto'' as far as reasonable
	\item indent do ... enddo and if ... then ... else constructs 
	\item avoid using ``return''; only one exit of the routine, at
          the end (this makes debugging easier)   
	\item no I/O (read, write, print to files) in a Fortran routine,
          except for printing to output (error messages, summary data
          etc.); most of the data will be put into tables via C routine
          calls. 
	\item Error flags, or calls to special exception routines can be
          foreseen as need arises. 
     \end{enumerate}

   \item \textbf{ General}
     \begin{enumerate}
        \item for local buffers of moderate size use local arrays; for
          bulk storage use blank common; blank common may as
          well be used to pass data inside modules 
	\item for matrix manipulation use the existing m66 package
	\item do not use any external library (e.g. cernlib), rather
          extract and include the code needed   
     \end{enumerate}

   \item \textbf{ Checks are essential!!}
     \begin{enumerate}
        \item  Run your code through f2c to check that the Fortran is
          compatible with standard Fortran 77. Recent testing of the
          MAD-X Fortran77 code has  revealed some problematic
          programming techniques. Example: f2c twiss.F   
	\item  Use the NAG f95 compiler with very strict checking by
          using "make -f Makefile\_develop (madxp)" in brackets if you
          test the MAD-X PTC version. 
	\item  Then run your example with that executable. The "-nan"
          compile flags will demonstrate at run time if variables have
          not been properly initialized so as to allow for fixing this
          problem.   
	\item  At last the MAD-X custodian (presently FS) will check the
          compatibility with Fortran90. Thereby performing certain
          "beautification" procedures. Moreover, the NAG f95 compiler
          reveals more inconsistencies in the Fortran90 mode.   
     \end{enumerate} 

\end{itemize}


\textbf{ Example}
\begin{verbatim}
      integer function type(s_length, s_type)
*++ Purpose: returns an integer type code for certain elements
*-- input:
*   s_length   length of s_type
*   s_type     string containing type
*-- return values:
*   1   for s_type == 'drift'
*   2   for s_type == 'sbend'
*   3   for s_type == 'rbend'
*   5   for s-type == 'quadrupole'
*   0   else
*++
      implicit none
      integer s_length
      character *(*) s_type

      if (s_type(:s_length) .eq. 'drift')  then
        type = 1
      elseif (s_type(:s_length) .eq. 'sbend')  then
        type = 2
      elseif (s_type(:s_length) .eq. 'rbend')  then
        type = 3
      elseif (s_type(:s_length) .eq. 'quadrupole')  then
        type = 5
      else
        type = 0
      endif
      end
\end{verbatim}


% \textit{Hans Grote} \textit{2001-01-22}