source: PSPA/madxPSPA/doc/usrguide/Introduction/module_doc.html @ 430

Last change on this file since 430 was 430, checked in by touze, 11 years ago

import madx-5.01.00
File size: 7.0 KB
Line 
1<head>
2<title>MAD-X Module Writer's Guide</title>
3<!-- Changed by: Chris ISELIN, 17-Jul-1997 -->
4<!-- Changed by: Hans Grote, 10-Jun-2002 -->
5</head>
6
7<body bgcolor = "#ffffff">
8<center>
9EUROPEAN ORGANIZATION FOR NUCLEAR RESEARCH
10<IMG SRC="http://cern.ch/madx/icons/mx7_25.gif" align=right>
11<h2>MAD-X Module Writer's Guide</h2> 
12</center>
13<br>
14Hans Grote and Frank Schmidt
15</center>
16<hr>
17<h2>Introduction</h2>
18MAD-X, in its actual form, consists of a main program in Fortran-77 that
19does nothing but call a C program which handles the overall control.
20This C program (CONTROL in the following)
21in turn calls modules written in Fortran-77, possibly
22Fortran-90 or Fortran-95, and C. The Fortran-77 modules come from MAD-8
23and are adapted to the new structure.
24<p>
25All I/O (except for debug or error messages) is performed by CONTROL. The
26modules receive their input data via calls (Fortran), or take them from
27structures (C); the module outputs are stored in tables or variables via
28calls (Fortran) or directly in structures (C).
29<p>
30For each new module to be added, FS will provide a complete
31development environment consisting of:
32<ul>
33<li>Makefile</li>
34<li>A separate mad-X version with a call to the new module</li>
35<li>Access to the input commands steering the module</li>
36</ul>
37Additional functionality will be added to CONTROL as it becomes necessary,
38i.e. to gain access to data not yet provided.
39<p>
40In the following, the different cases are handled separately.
41<ul>
42<h2>C part</h2>
43The C language is already pretty safe by nature. However, one can
44still produce bad code! Therefore, use the compile flags "-Wall
45-pedantic" (can be done via "make -f Makefile_develop" either for madx
46or madxp) and please fix all warnings that the compiler detects. The
47last checking campaign revealed hundreds of warnings!
48To allow for better code maintainability we have recently to introduce
49a general indentation by 2 characters per level
50level with all curly brackets on an extra line. The curly brackets are
51aligned with the operators. FS has semi-automatic tools to do this
52indentation.
53<li> Memory allocation: <font color=ff0000>Never use the plain
54malloc or calloc C functions!</font>. Instead use the wrappers <font
55color=ff0000> mymalloc and mycalloc </font>. The syntax of how to call
56these functions can be found in madxu.c.
57<h2>Fortran</h2>
58Fortran normally mixes well with C (at least under Unix) provided a few
59<a href="fortran-rules.html">basic rules</a> are respected.
60They concern mainly the transfer of arguments to and from C.
61<p>
62Normally the module will already exist in MAD-8.In this case, follow these
63steps:
64<ul>
65<li>Extract all routines belonging to the module from MAD-8 (possibly
66with the help of FS)
67<li>Find out which routines if any have already been transmitted to mad-X
68<li>Remove all common statements
69<li>Transfer variables that exist only inside the module either via calls
70(as arguments), or via a common block with a name reminding of the module.
71This common block has to be identical in all routines where it appears.
72<li>Make a list of all variables that the module needs from outside
73<li>Give the list to FS so he can provide them
74<li>Make a list of the output data provided by the module (reminder:
75the module should only print error messages,
76and transfer all result data to tables or variables);
77Discuss the details of the output storage with FS
78<li>Attach the modified module to mad-X and test it
79<li>Provide module documentation (based on MAD-8 documentation)
80<li>Provide test jobs that test the module abilities as far as reasonable
81</ul>
82If it is a new module, the above rules are modified accordingly. However,
83new modules should be written in C whenever possible.
84<p>
85<h2>Strict Checking</h2>
86Before committing to CVS (see next section) it is mandatory
87to perform a strict check of all your examples. To this end create an
88executable with Makefile_develop:
89<p>
90<ul>
91<li> For madx perform: "make -f Makefile_develop"
92<li> For madxp perform: "make -f Makefile_develop madxp"
93</ul>
94Check compiler output for warnings and get rid of them. Then run your
95examples with these executables until MAD-X finishes the job
96successfully. There will be a crash if variables have not been
97initialized before usage and in case of out-of-bound usage of arrays.
98<p>
99<h2>CVS</h2>
100MAD-X is kept under CVS (Concurrent Version System). The CVS version
101number should be >=1.11.2.
102<p>
103Here are the  CVS basics for MAD-X:
104<p>
105<ul>
106<li> For CERN users: First step is to include the following lines into
107your .tcshrc file in your HOME directory (users of other SHELLs adapt
108accordingly):
109<ul>
110<p>
111setenv CVSROOT :kserver:isscvs.cern.ch:/local/reps/madx
112<p>
113setenv CVSEDITOR emacs
114</ul>
115(second command for emacs users) use "source .tcshrc" to activate the
116MAD-X CVS repository.
117<li> Go to your directory of choice, probably the one where you develop
118your module.
119<li> type <font color=ff0000>cvs checkout madX</font> this will create
120a new directory named <font color=00ff00>madX</font> with the newest
121files from the CVS repository. Change directory to <font
122color=00ff00>madX</font>.
123<li> Make your changes.
124<li> <font color=ff0000>VERY IMPORTANT BEFORE PROCEEDING!!! </font>
125<ul>
126<li> Before you <font color=ff0000>commit</font> your changes check
127with <font color=ff0000>cvs log</font> <font
128color=0000ff>your_file</font> if anybody has worked on that file in
129the meantime.
130<li> Also, before a <font color=ff0000>commit</font> please check
131with <font color=ff0000>cvs -n update -A </font> <font
132color=0000ff>your_file</font> if this is truly what you want to commit
133or if there are conflicts. Explanation: <font color=ff0000>-n</font>
134is a global CVS option that give information without actually changing
135any files, the auxiliary <font color=ff0000>-A</font> flag removes
136<font color=ff0000>sticky tags</font> about which you do not really
137want to know about!
138<li> With <font color=ff0000>make</font> produce an executable <font
139color=0000ff>madx</font> and check that all your examples run
140properly!
141</ul>
142<li> type <font color=ff0000>cvs commit </font> <font
143color=0000ff>your_file</font> for each file you have changed.
144<li> In the rare case that there is a conflict with another module writer
145that has edited the same file, you have to contact him to sort out
146possible problems. It is one of the advantage of the CVS system to
147detect these conflicts.
148<li> Optional: Go back to directory above and type <font
149color=ff0000>cvs release madX </font> this insures that you really
150have committed all changed files before getting rid of the <font
151color=00ff00>madX</font> directory.
152<li> Optional: If you want to know about the history of a file type
153<font color=ff0000>cvs log -S</font> <font
154color=0000ff>your_file</font> (you have to be in the <font
155color=00ff00>madX</font> directory). Explanation: The <font
156color=ff0000>-S</font> flags avoids excessive printout. 
157</ul>
158
159If you want to learn more about CVS please consult the manual which is
160accessible at:
161/afs/cern.ch/eng/sl/MAD-X/dev/cvs_manual.ps
162
163<p>
164Comments from readers are most welcome.
165They may be sent to the following Internet addresses:
166<pre><tt>
167   Frank.Schmidt@cern.ch
168</tt></pre>
169<hr>
170
171<hr>
172</body>
Note: See TracBrowser for help on using the repository browser.