FAQ: Refer to charm mailing list instead of ppl
[charm.git] / doc / faq / install.tex
1 \section{Installation and Usage}
2
3 \subsubsection{How do I get Charm++?}
4
5 See our \htmladdnormallink{download}{http://charm.cs.uiuc.edu/download/} page.
6
7 \subsubsection{Should I use the CVS version of Charm++?}
8
9 The developers of Charm++ routinely use the latest CVS versions, and most of the
10 time this is the best case. Occasionally something breaks, but the CVS version
11 will likely contain bug fixes not found in the releases.
12
13 \subsubsection{How do I compile Charm++?}
14
15 Run the interactive build script {\tt ./build} with no extra arguments If this fails,
16 email \htmladdnormallink{charm AT cs.uiuc.edu}{mailto:charm AT cs.uiuc.edu} with the
17 problem. Include the build line used (this is saved automatically in
18 {\tt smart-build.log})
19
20 If you have a very unusual machine configuration, you will have to run
21 {\tt ./build\ --help} to list all possible build options. You will then choose the closest
22 architecture, and then you may have to modify the associated conf-mach.sh and
23 conv-mach.h files in src/arch to point to your desired compilers and options. If
24 you develop a significantly different platform, send the modified files to
25 \htmladdnormallink{charm AT cs.uiuc.edu}{mailto:charm AT cs.uiuc.edu} so we can include it
26 in the distribution.
27
28 \subsubsection{How do I compile AMPI?}
29
30 Run the interactive build script {\tt ./build} and choose the option for building
31 ``Charm++, AMPI, ParFUM, FEM and other libraries''.
32
33 \subsubsection{Can I remove part of charm tree after compilation to free disk space?}
34
35
36 \subsubsection{If the interactive script fails, how do I compile Charm++?}
37
38 %<p>First, on a typical Linux machine, unpack the tarball, cd into "charm",
39 %and type <tt>./build AMPI net-linux -g</tt>.
40
41 %<p>Next, if your machine is similar to one of the machines below, 
42 %use the listed "build" command:
43 %<table border="1">
44 %<tr><th>Computer</th><th>Type</th><th>Charm Build</th>
45
46 %<tr>
47 %       <td>UIUC CSE <a href="http://www.cse.uiuc.edu/turing/">Turing</a> Cluster</td>
48 %       <td>Myrinet Linux Cluster. <br>
49 %               640 2GHz G5 processors as 2-way nodes.</td>
50 %       <td>
51 %               Debug: ./build AMPI net-ppc-darwin -g<br>
52 %               Production: ./build AMPI net-ppc-darwin gm -O3<br>
53 %               To run a job, use "rjc" to find nodes, then "charmrun".
54 %       </td>
55 %</tr>
56 %<tr>
57 %       <td>PSC <a href="http://www.psc.edu/machines/tcs/lemieux.html">Lemieux</a></td>
58 %       <td>HP/Compaq AlphaServer. <br> 
59 %               3,000 64-bit Alpha processors as 750 4-way SMP nodes. 3TB total RAM.
60 %       </td>
61 %       <td>
62 %               Use: ./build AMPI elan-axp cxx -O<br>
63 %               To run a short job, use "charmrun".
64 %               To run a long job, prepare a batch script and use "qsub".
65 %       </td>
66 %</tr>
67 %<tr>
68 %       <td>NCSA <a href="http://www.ncsa.uiuc.edu/UserInfo/Resources/Hardware/IBMp690/">Copper</a></td>
69 %       <td>IBM SP (pSeries 690). <br> 
70 %               Use up to 32 1.3GHz 64-bit IBM Power4 processors as a single SMP node.
71 %       </td>
72 %       <td>
73 %               32-bit Mode: ./build AMPI mpi-sp -O<br>
74 %               64-bit Mode: ./build AMPI mpi-sp mpcc64 -O<br>
75 %               To run an interactive job, use "charmrun".
76 %               To run a long job, write a batch script and use "llsubmit".
77 %       </td>
78 %</tr>
79 %<tr>
80 %       <td>NCSA <a href="http://www.ncsa.uiuc.edu/UserInfo/Resources/Hardware/XeonCluster/">Tungsten</a></td>
81 %       <td>Myrinet Linux Cluster. <br>
82 %               2,560 3.2 GHz Intel Xeon processors as 2-way nodes with Myrinet, 3 GB RAM per node.
83 %       </td>
84 %       <td>
85 %               Use: ./build AMPI net-linux gm -O , or<br>
86 %                    ./build AMPI net-linux gm icc ifort -O (Intel compilers) , or<br>
87 %                    ./build AMPI mpi-linux cmpi -O (Champion MPI)<br>
88 %       </td>
89 %</tr>
90 %<tr>
91 %       <td>NCSA <a href="http://www.ncsa.uiuc.edu/UserInfo/Resources/Hardware/TGIA64LinuxCluster/">Mercury</a></td>
92 %       <td>Myrinet Linux Cluster. <br>
93 %               1,744 1.3/1.5 GHz Intel Itanium-2 processors as 2-way nodes with Myrinet, 4 GB RAM per node.
94 %       </td>
95 %       <td>
96 %               Use: ./build AMPI net-linux-ia64 gm -O , or<br>
97 %                    ./build AMPI mpi-linux-ia64 gm -nobs -O (MPICH over GM)<br>
98 %       </td>
99 %</tr>
100 %<tr>
101 %       <td>NCSA <a href="http://www.ncsa.uiuc.edu/UserInfo/Resources/Hardware/SGIAltix/">Cobalt</a></td>
102 %       <td>SGI Altix 3700 <br>
103 %               1,024 1.6 GHz Intel Itanium-2 processors as two 512-processor shared memory systems, 1,024 GB RAM in one system and 2,048 GB RAM in the other
104 %       </td>
105 %       <td>
106 %               Use: ./build AMPI mpi-linux-ia64 ifort mpt icc -O <br>
107 %       </td>
108 %</tr>
109 %<tr>
110 %       <td>NCSA <a href="http://www.ncsa.uiuc.edu/UserInfo/Resources/Hardware/IA32LinuxCluster/">Platinum</a></td>
111 %       <td>Myrinet Linux Cluster with VMI. <br>
112 %               968 1 GHz 32-bit Intel Pentium III processors as 2-way nodes with Myrinet.
113 %       </td>
114 %       <td>
115 %               Debug: ./build AMPI net-linux gm icc -O<br>
116 %               Production: ./build AMPI mpi-linux vmi icc -O<br>
117 %               To run an interactive job with net version, use "charmrun". To run with mpi version, use vmirun. Checkout NCSA's webpage for how to write a job script.<br>
118 %       </td>
119 %</tr>
120 %<tr>
121 %       <td>NCSA <a href="http://www.ncsa.uiuc.edu/UserInfo/Resources/Hardware/IA32LinuxCluster/">Titanium</a></td>
122 %       <td>Myrinet Itanium Linux Cluster. <br>
123 %               256 800 MHz 64-bit Intel Itanium processors as 2-way nodes with Myrinet.
124 %       </td>
125 %       <td>
126 %               Use: ./build AMPI net-linux-ia64 gm ecc -O , or<br>
127 %                    ./build AMPI mpi-linux-ia64 vmi ecc -O<br>
128 %               To run an interactive job with net version, use "charmrun". To run with mpi version, use vmirun.<br>
129 %       </td>
130 %</tr>
131 %<tr>
132 %       <td><a href=http://www.hpcx.ac.uk/">HPCx</td>
133 %       <td>IBM eServer 575 LPARs with HPC Federation interconnect. <br>
134 %               96 1.5 GHz 64-bit Power5</td>
135 %       <td>Use: ./build AMPI lapi -O3 -qstrict
136 %               "charmrun" will allocate jobs to the load leveler. A prototype file is needed for the accounting</td>
137 %</tr>
138 %<tr>
139 %       <td>Architecture Cluster</a></td>
140 %       <td>Fast Ethernet Linux Cluster. <br>
141 %               140 1.7 GHz 32-bit Athlon MP 2000 processors as 2-way nodes.
142 %       </td>
143 %       <td>
144 %               Debug: ./build AMPI net-linux -g<br>
145 %               Production: ./build AMPI net-linux -O<br>
146 %               To run interactive use "frun", "fsub" for batch submission.<br> 
147 %       </td>
148 %</tr>
149
150 %</table>
151
152 %<br>
153 %For a computer not in the list above, you can decide which build options to use based
154 %on the following rules of thumb.
155 %<ul>
156 %<li>The compiler defaults to gcc or mpicc on most platforms.  
157 %If you'd like to use another compiler, you can usually add an 
158 %option like "icc", "pgcc", "xlc", "xlc64", or many others--
159 %see the README file or charm/src/arch/common for a complete list.
160 %For platform specific options, one can run build command with "help" option, for example: <br>
161 %./build charm++ net-linux help
162
163 %<li>Under Linux, if you or your communication layer uses pthreads,
164 %and you use Charm threads (such as AMPI), and your Glibc is less than
165 %version 3.2, you'll get a horrible crash unless you add the "smp" option.
166 %This version links in a special version of pthreads that works with
167 %our user-level threads.
168
169 %<li>On the net- version, if you're having trouble with rsh/ssh or just
170 %want to spawn processes on your own machine, add the "local" option, 
171 %like <tt>./build AMPI net-linux local -g</tt>
172
173 %<li>Run "./build --help" to display detailed help page for supported build options
174
175 %</ul>
176
177 %See the README file for extensive details.
178 %<br>
179 %<br>
180
181 %<li>
182 %<b>How do I set up my linux box for parallel runs?</b>
183 %or <b>What does "rsh> protocol failure in circuit setup" mean?</b>
184 %</li>
185
186 %<br>Charmrun normally uses rsh to start the individual programs in a parallel
187 %run. If you can't execute "rsh localhost echo Hello", you need to set up rsh.
188
189 %<p>Rsh is normally started by the inetd service.  For pre-RedHat 7 Linux systems,
190 %you ask inetd to start rsh by adding, as root, this line to /etc/inetd.conf:
191 %<pre>
192 %shell  stream  tcp     nowait.1000     root    /usr/sbin/tcpd  in.rshd
193 %</pre>
194 %You'll then need to restart inetd using "/etc/rc.d/init.d/inetd restart".
195
196 %<p>On a modern Linux system you probably don't have an /etc/inetd.conf file,
197 %because your system uses xinetd.  With xinetd, you enable rsh by adding,
198 %as root, a file called "rsh" to the directory /etc/xinetd.d/ containing:
199 %<pre>
200 %# default: on
201 %# description: The rshd server is the server for the rcmd(3) routine and, \
202 %#      consequently, for the rsh(1) program.  The server provides \
203 %#      remote execution facilities with authentication based on \
204 %#      privileged port numbers from trusted hosts.
205 %service shell
206 %{
207 %       socket_type             = stream
208 %       wait                    = no
209 %       user                    = root
210 %       only_from               = 127.0.0.1 ...your subnet address here.../24
211 %       cps                     = 1000 30
212 %       log_on_success          += USERID
213 %       log_on_failure          += USERID
214 %       server                  = /usr/sbin/in.rshd
215 %}
216 %</pre>
217
218 %Afer adding this file, you'll need to restart xinetd using "/etc/rc.d/init.d/xinetd restart".
219
220 %<p>Finally, no matter what kind of inetd you have, you probably also want a
221 %/etc/hosts.equiv file.  This file contains a list of hosts you want to be able to
222 %rsh from without using a password.  Since Charm never uses passwords with rsh,
223 %you want to add all the machines you'll be starting Charm jobs from.
224 %For example, if I start jobs on this machine from localhost and foo.bar.edu,
225 %my /etc/hosts.equiv file would contain:
226 %<pre>
227 %localhost
228 %foo.bar.edu
229 %</pre>
230
231 \subsubsection{How do I specify the processors I want to use?}
232
233 For the net versions, you need to write a nodelist file which lists
234 all the machine hostnames available for parallel runs.
235 \begin{alltt}
236 group main
237   host foo1
238   host foo2 ++cpus 4
239   host foo3.bar.edu
240 \end{alltt}
241
242 %<p>For the net SCYLD version, you don't need nodelist file,
243 %<tt>charmrun
244 %+p n</tt> will automatically find the first n available nodes.
245
246 For the MPI version, you need to set up an MPI configuration for available
247 machines as for normal MPI applications.
248
249 \subsubsection{How do I use {\em ssh} instead of the deprecated {\em rsh}?}
250
251 You need to set up your {\tt .ssh/authorized\_keys} file
252 correctly. Setup no-password logins using ssh by putting the correct host
253 key (ssh-keygen) in the file {\tt .ssh/authorized\_keys}.
254
255 Finally, in the {\tt .nodelist} file,
256 you specify the shell to use for remote execution of a program using
257 the keyword {\em ++shell}.
258 \begin{alltt}
259 group main ++shell ssh
260   host foo1
261   host foo2
262   host foo3
263 \end{alltt}
264
265 \subsubsection{Can I use the serial library X from a Charm program?}
266
267 Yes.  Some of the known working serial libraries include:
268 \begin{itemize}
269 \item The Tcl/Tk interpreter (in NAMD)
270 \item The Python interpreter (in Cosmo prototype)
271 \item OpenGL graphics (in graphics demos)
272 \item Metis mesh partitioning (included with charm)
273 \end{itemize}
274
275 \subsubsection{How do I get the command-line switches available for a specific
276 program?}
277
278 Try \begin{alltt}./charmrun ./pgm --help\end{alltt} to see a list of parameters
279 at the command line. The charmrun arguments are documented in the
280 \htmladdnormallink{Installation and Usage Manual}{http://charm.cs.uiuc.edu/manuals/html/install/manual.html}
281 the arguments for the installed libraries are listed in the library manuals.
282
283 %<b>Could you tell me how to run speedshop?</b></li>
284
285 %<br><b>speedshop</b> is the performance analysis tool on Origin2000. In
286 %order to use it, one need not specify any special compilation or linking
287 %options. It can also be used for parallel programs. Here is what to do
288 %to use speedshop.
289 %<p>Suppose the name of the executable is <tt>pgm</tt>, and it is an MPI
290 %program (or a Charm++ program on mpi-origin version). You run:
291 %<pre>mpirun -np 4 ssrun -ideal pgm &lt;pgm-options></pre>
292 %<tt>ssrun</tt> is the command that instruments the executable (original
293 %executable is not modified), and runs it. The
294 %<tt>-ideal</tt> option specifies
295 %what data needs to be collected. It is called <b>experiment</b> in speedshop
296 %terminology.
297 %<p>This will produce a few files called
298 %<tt>pgm.ideal.*</tt>. To be precise,
299 %when <tt>-np</tt> is 4, it will produce 5 files: one of them is
300 %<tt>pgm.ideal.m*</tt>,
301 %and the rest are
302 %<tt>pgm.ideal.f*</tt>. * is the PID of each process. the
303 %m* file corresponds to the master program of MPI (and also the lazy thread),
304 %so it does not contain any user data. The user processes generate <tt>pgm.ideal.f*</tt>
305 %files.
306 %<p>Now run prof on it: <tt>prof [-gprof] pgm.ideal.f*</tt>
307 %<p>This will print the profiling statistics to stdout. The
308 %<tt>-gprof</tt>
309 %option asks prof to generate gprof style output.
310 %<p>There are various interesting experiements one can run with speedshop.
311 %See speedshop(1) for more details.
312 %<br>&nbsp;</ol>