module_doc.tex

%%\title{MAD-X Module Writer's Guide}
%  Changed by: Chris ISELIN, 17-Jul-1997 

%  Changed by: Hans Grote, 10-Jun-2002 

%%\usepackage{hyperref}
% commands generated by html2latex


%%\begin{document}
\begin{center}
 %%EUROPEAN ORGANIZATION FOR NUCLEAR RESEARCH 
%%\includegraphics{http://cern.ch/madx/icons/mx7_25.gif}

\subsection{MAD-X Module Writer's Guide}
Hans Grote and Frank Schmidt 
\end{center}


\line(1,0){300}


\subsection{Introduction} MAD-X, in its actual form, consists of a main
program in Fortran-77 that  does nothing but call a C program which
handles the overall control.  This C program (CONTROL in the following)
in turn calls modules written in Fortran-77, possibly  Fortran-90 or
Fortran-95, and C. The Fortran-77 modules come from MAD-8 and are
adapted to the new structure.  

All I/O (except for debug or error messages) is performed by
CONTROL. The modules receive their input data via calls (Fortran), or
take them from structures (C); the module outputs are stored in tables
or variables via calls (Fortran) or directly in structures (C).   

For each new module to be added, FS will provide a complete development
environment consisting of:  
\begin{itemize}
  \item Makefile
  \item A separate mad-X version with a call to the new module
  \item Access to the input commands steering the module
\end{itemize} 

Additional functionality will be added to CONTROL as it becomes
necessary, i.e. to gain access to data not yet provided.   

In the following, the different cases are handled separately. 

\subsection{C part} 
The C language is already pretty safe by nature. However, one can still
produce bad code! Therefore, use the compile flags "-Wall -pedantic"
(can be done via "make -f Makefile\_develop" either for madx or madxp)
and please fix all warnings that the compiler detects. The last checking
campaign revealed hundreds of warnings! To allow for better code
maintainability we have recently to introduce a general indentation by 2
characters per level level with all curly brackets on an extra line. The
curly brackets are aligned with the operators. FS has semi-automatic
tools to do this indentation.  

\begin{itemize}
  \item  Memory allocation: Never use the plain malloc or calloc C
    functions!. Instead use the wrappers  mymalloc and mycalloc . The
    syntax of how to call these functions can be found in madxu.c.  
\end{itemize}

\subsection{Fortran} 
Fortran normally mixes well with C (at least under Unix) provided a few
\href{fortran-rules.html}{basic rules} are respected. They concern
mainly the transfer of arguments to and from C.  

Normally the module will already exist in MAD-8.In this case, follow
these steps:  
\begin{itemize}
\item Extract all routines belonging to the module from MAD-8 (possibly
  with the help of FS)  
\item Find out which routines if any have already been transmitted to
  mad-X  
\item Remove all common statements
\item Transfer variables that exist only inside the module either via
  calls (as arguments), or via a common block with a name reminding of
  the module. This common block has to be identical in all routines
  where it appears.  
\item Make a list of all variables that the module needs from outside  
\item Give the list to FS so he can provide them 
\item Make a list of the output data provided by the module (reminder:
  the module should only print error messages,  and transfer all result
  data to tables or variables); Discuss the details of the output
  storage with FS  
\item Attach the modified module to mad-X and test it 
\item Provide module documentation (based on MAD-8 documentation) 
\item Provide test jobs that test the module abilities as far as
  reasonable  
\end{itemize} 
If it is a new module, the above rules are modified
accordingly. However, new modules should be written in C whenever
possible.  



\subsection{Strict Checking} 
Before committing to CVS (see next section) it is mandatory to perform a
strict check of all your examples. To this end create an executable with
Makefile\_develop:  


\begin{itemize}
 \item  For madx perform: "make -f Makefile\_develop" 
 \item  For madxp perform: "make -f Makefile\_develop madxp" 
\end{itemize} 

Check compiler output for warnings and get rid of them. Then run your
examples with these executables until MAD-X finishes the job
successfully. There will be a crash if variables have not been
initialized before usage and in case of out-of-bound usage of arrays.  



\subsection{CVS} 
MAD-X is kept under CVS (Concurrent Version System). The CVS version number should be \textgreater =1.11.2. 

Here are the  CVS basics for MAD-X: 


\begin{itemize}
\item  For CERN users: First step is to include the following lines into
  your .tcshrc file in your HOME directory (users of other SHELLs adapt
  accordingly):  
%\begin{itemize} 
\\
\\
 setenv CVSROOT :kserver:isscvs.cern.ch:/local/reps/madx  
 \\
 \\
 setenv CVSEDITOR emacs  
 \\
 \\
%\end{itemize}
 (second command for emacs users) use "source .tcshrc" to activate the
 MAD-X CVS repository.  
\item  Go to your directory of choice, probably the one where you
  develop your module.  
\item  type cvs checkout madX this will create a new directory named
  madX with the newest files from the CVS repository. Change directory
  to madX.  
\item  Make your changes. 
\item VERY IMPORTANT BEFORE PROCEEDING!!! 
  \begin{itemize}
  \item  Before you commit your changes check with cvs logyour\_file if
    anybody has worked on that file in the meantime.  
  \item  Also, before a commit please check with cvs -n update -A
    your\_file if this is truly what you want to commit or if there are
    conflicts. Explanation: -n is a global CVS option that give
    information without actually changing any files, the auxiliary -A
    flag removes sticky tags about which you do not really want to know
    about!  
  \item  With make produce an executable madx and check that all your
    examples run properly!  
  \end{itemize}
\item  type cvs commit your\_file for each file you have changed.  
\item  In the rare case that there is a conflict with another module
  writer that has edited the same file, you have to contact him to sort
  out possible problems. It is one of the advantage of the CVS system to
  detect these conflicts.  
\item  Optional: Go back to directory above and type cvs release madX
  this insures that you really have committed all changed files before
  getting rid of the madX directory.  
\item  Optional: If you want to know about the history of a file type
  cvs log -S your\_file (you have to be in the madX
  directory). Explanation: The -S flags avoids excessive printout.    
\end{itemize}  If you want to learn more about CVS please consult the
manual which is accessible at:
/afs/cern.ch/eng/sl/MAD-X/dev/cvs\_manual.ps   

Comments from readers are most welcome. They may be sent to the
following Internet addresses:  
\begin{verbatim}
   Frank.Schmidt@cern.ch
\end{verbatim}

\line(1,0){300}


\line(1,0){300}

\end{itemize}

%%\end{document}