doc: minor fixes
[charm.git] / doc / charm++ / run.tex
1 \section{Launching Programs with \kw{charmrun}}
2 \label{charmrun}
3
4 When compiling \charmpp{} programs, the charmc linker produces 
5 both an executable file and an utility called {\tt charmrun},
6 which is used to load the executable onto the parallel machine.
7
8 To run a \charmpp{} program named ``pgm'' on four processors, type:
9 \begin{alltt}
10 charmrun pgm +p4
11 \end{alltt}
12
13
14 Programs built using the network version of \charmpp{} can be run
15 alone, without charmrun.  This restricts you to using the processors
16 on the local machine, but it is convenient and often useful for
17 debugging.  For example, a \charmpp{} program can be run on one
18 processor in the debugger using:
19
20 \begin{alltt}
21 gdb pgm
22 \end{alltt}
23
24 If the program needs some environment variables
25 to be set for its execution on compute nodes
26 (such as library paths), they can be set in
27 .charmrunrc under home directory. charmrun
28 will run that shell script before running the executable.
29
30 \section[Command Line Options]{Command Line Options}
31 \label{command line options}
32 \index{command line options}
33
34 A \charmpp{} program accepts the following command line options:
35 \begin{description}
36
37 \item[{\tt +pN}] Run the program with N processors. The default is 1.
38
39 \item[{\tt +ss}] Print summary statistics about chare creation.  This option
40 prints the total number of chare creation requests, and the total number of
41 chare creation requests processed across all processors.
42
43 \item[{\tt +cs}] Print statistics about the number of create chare messages
44 requested and processed, the number of messages for chares requested and 
45 processed, and the number of messages for branch office chares requested and
46 processed, on a per processor basis.  Note that the number of messages 
47 created and processed for a particular type of message on a given node 
48 may not be the same, since a message may be processed by a different
49 processor from the one originating the request.
50
51 \item[{\tt user\_options}] Options that are be interpreted by the user
52 program may be included mixed with the system options. 
53 However, {\tt user\_options} cannot start with +.
54 The {\tt user\_options} will be passed as arguments to the user program 
55 via the usual {\tt argc/argv} construct to the {\tt main}
56 entry point of the main chare. 
57 \charmpp{} system options will not appear in {\tt argc/argv}.
58
59 \end{description}
60
61
62
63 \subsection{Additional Network Options}
64 \label{network command line options}
65
66 The following {\tt ++} command line options are available in
67 the network version:
68 \begin{description}
69
70 \item[{\tt ++local}] Run charm program only on local machines. No 
71  remote shell invocation is needed in this case. It starts node programs 
72  right on your local machine. This could be useful if you just want to 
73  run small program on only one machine, for example, your laptop.
74
75
76 \item[{\tt ++mpiexec}]
77
78 Use the cluster's {\tt mpiexec} job launcher instead of the built in rsh/ssh
79 method.
80
81 This will pass {\tt -n \$P} to indicate how many processes to
82 launch. An executable named something other than {\tt mpiexec} can be
83 used with the additional argument {\tt ++remote-shell} {\it runmpi},
84 with `runmpi' replaced by the necessary name.
85
86 Use of this option can potentially provide a few benefits:
87
88 \begin{itemize}
89 \item Faster startup compared to the SSH/RSH approach charmrun would
90   otherwise use
91 \item No need to generate a nodelist file
92 \item Multi-node job startup on clusters that do not allow connections
93   from the head/login nodes to the compute nodes
94 \end{itemize}
95
96 At present, this option depends on the environment variables for some
97 common MPI implementations. It supports OpenMPI ({\tt OMPI\_COMM\_WORLD\_RANK} and
98 {\tt OMPI\_COMM\_WORLD\_SIZE}) and M(VA)PICH ({\tt MPIRUN\_RANK} and {\tt
99   MPIRUN\_NPROCS} or {\tt PMI\_RANK} and {\tt PMI\_SIZE}).
100
101 \item[{\tt ++debug}] Run each node under gdb in an xterm window, prompting
102 the user to begin execution.
103
104 \item[{\tt ++debug-no-pause}] Run each node under gdb in an xterm window
105 immediately (i.e. without prompting the user to begin execution).
106
107 If using one of the {\tt ++debug} or {\tt ++debug-no-pause} options,
108 the user must ensure the following:
109 \begin{enumerate}
110
111 \item The {\tt DISPLAY} environment variable points to your terminal.
112 SSH's X11 forwarding does not work properly with \charmpp{}.
113
114 \item The nodes must be authorized to create windows on the host machine (see
115 man pages for {\tt xhost} and {\tt xauth}).
116
117 \item {\tt xterm}, {\tt xdpyinfo},  and {\tt gdb} must be in
118 the user's path.
119
120 \item The path must be set in the {\tt .cshrc} file, not the {\tt .login}
121 file, because {\tt rsh} does not run the {\tt .login} file. 
122
123 \end{enumerate}
124
125 \item[{\tt ++maxrsh}] Maximum number of {\tt rsh}'s to run at a
126 time.
127
128 \item[{\tt ++nodelist}] File containing list of nodes.
129
130
131 \item[{\tt ++ppn}]              number of pes per node
132
133 \item[{\tt ++help}]             print help messages
134
135 \item[{\tt ++runscript}]        script to run node-program with
136
137 \item[{\tt ++xterm}]            which xterm to use
138
139 \item[{\tt ++in-xterm}]         Run each node in an xterm window
140
141 \item[{\tt ++display}]          X Display for xterm
142
143 \item[{\tt ++debugger}]         which debugger to use
144
145 \item[{\tt ++remote-shell}]     which remote shell to use
146
147 \item[{\tt ++useip}]            Use IP address provided for charmrun IP
148
149 \item[{\tt ++usehostname}]      Send nodes our symbolic hostname instead of IP address
150
151 \item[{\tt ++server-auth}]      CCS Authentication file
152
153 \item[{\tt ++server-port}]      Port to listen for CCS requests
154
155 \item[{\tt ++server}]           Enable client-server (CCS) mode
156
157 \item[{\tt ++nodegroup}]        which group of nodes to use
158
159 \item[{\tt ++verbose}]          Print diagnostic messages
160
161 \item[{\tt ++timeout}]          seconds to wait per host connection
162
163 \item[{\tt ++p}]                number of processes to create
164
165 \end{description}
166
167 \subsection{Multicore Options}
168
169 On multicore platforms, operating systems (by default) are free to move
170 processes and threads among cores to balance load. This however sometimes can
171 degrade the performance of Charm++ applications due to the extra overhead of
172 moving processes and threads, especailly when Charm++ applications has already
173 implemented its own dynamic load balancing.
174
175 Charm++ provides the following runtime options to set the processor affinity
176 automatically so that processes or threads no longer move. When cpu affinity
177 is supported by an operating system (tested at Charm++ configuration time),
178 same runtime options can be used for all flavors of Charm++ versions including
179 network and MPI versions, smp and non-smp versions.
180
181 \begin{description}
182
183 \item[{\tt +setcpuaffinity}]             set cpu affinity automatically for processes (when Charm++ is based on non-smp versions) or threads (when smp)
184
185 \item[{\tt +excludecore <core \#>}]       does not set cpu affinity for the given core number. One can use this option multiple times to provide a list of core numbers to avoid.
186
187 \item[{\tt +pemap L[-U[:S[.R]]][,...]}] Bind the execution threads to
188   the sequence of cores described by the arguments using the operating
189   system's CPU affinity functions.
190
191 A single number identifies a particular core. Two numbers separated by
192 a dash identify an inclusive range (\emph{lower bound} and \emph{upper
193   bound}). If they are followed by a colon and another number (a
194 \emph{stride}), that range will be stepped through in increments of
195 the additional number. Within each stride, a dot followed by a
196 \emph{run} will indicate how many cores to use from that starting
197 point.
198
199 For example, the sequence {\tt 0-8:2,16,20-24} includes cores 0, 2, 4,
200 6, 8, 16, 20, 21, 22, 23, 24. On a 4-way quad-core system, if one
201 wanted to use 3 cores from each socket, one could write this as {\tt
202   0-15:4.3}.
203
204 \item[{\tt +commap p[,q,...]}] Bind communication threads to the
205   listed cores, one per process.
206
207 \end{description}
208
209 \subsection{IO buffering options}
210 \label{io buffer options}
211 There may be circumstances where a \charmpp{} application may want to take
212 or relinquish control of stdout buffer flushing. Most systems default to
213 giving the \charmpp{} runtime control over stdout but a few default to
214 giving the application that control. The user can override these system
215 defaults with the following runtime options:
216
217 \begin{description}
218 \item[{\tt +io\_flush\_user}]     User (application) controls stdout flushing
219 \item[{\tt +io\_flush\_system}]   The \charmpp{} runtime controls flushing
220 \end{description}
221
222
223 \section{Nodelist file}
224
225 For network of workstations,
226 the list of machines to run the program can be specified in a file.  
227 Without a nodelist file, \charmpp{} runs the program only on the 
228 local machine.
229
230 The format of this file
231 allows you to define groups of machines, giving each group a name.
232 Each line of the nodes file is a command.  The most important command
233 is:
234
235 \begin{alltt}
236 host <hostname> <qualifiers>
237 \end{alltt}
238
239 which specifies a host.  The other commands are qualifiers: they modify
240 the properties of all hosts that follow them.  The qualifiers are:
241
242
243 \begin{tabbing}
244 {\tt group <groupname>}~~~\= - subsequent hosts are members of specified group\\
245 {\tt login <login>  }     \> - subsequent hosts use the specified login\\
246 {\tt shell <shell>  }     \> - subsequent hosts use the specified remote 
247 shell\\
248 %{\tt passwd <passwd>}     \> - subsequent hosts use the specified password\\
249 {\tt setup <cmd>  }       \> - subsequent hosts should execute cmd\\
250 {\tt pathfix <dir1> <dir2>}         \> - subsequent hosts should replace dir1 with dir2 in the program path\\
251 {\tt cpus <n>}            \> - subsequent hosts should use N light-weight processes\\
252 {\tt speed <s>}           \> - subsequent hosts have relative speed rating\\
253 {\tt ext <extn>}          \> - subsequent hosts should append extn to the pgm name\\
254 \end{tabbing}
255
256 {\bf Note:}
257 By default, charmrun uses a remote shell ``rsh'' to spawn node processes
258 on the remote hosts. The {\tt shell} qualifier can be used to override
259 it with say, ``ssh''. One can set the {\tt CONV\_RSH} environment variable
260 or use charmrun option {\tt ++remote-shell} to override the default remote 
261 shell for all hosts with unspecified {\tt shell} qualifier.
262
263 All qualifiers accept ``*'' as an argument, this resets the modifier to
264 its default value.  Note that currently, the passwd, cpus, and speed
265 factors are ignored.  Inline qualifiers are also allowed:
266
267 \begin{alltt}
268 host beauty ++cpus 2 ++shell ssh
269 \end{alltt}
270
271 Except for ``group'', every other qualifier can be inlined, with the
272 restriction that if the ``setup'' qualifier is inlined, it should be
273 the last qualifier on the ``host'' or ``group'' statement line.
274
275 Here is a simple nodes file:
276
277 \begin{alltt}
278         group kale-sun ++cpus 1
279           host charm.cs.uiuc.edu ++shell ssh
280           host dp.cs.uiuc.edu
281           host grace.cs.uiuc.edu
282           host dagger.cs.uiuc.edu
283         group kale-sol
284           host beauty.cs.uiuc.edu ++cpus 2
285         group main
286           host localhost
287 \end{alltt}
288
289 This defines three groups of machines: group kale-sun, group kale-sol,
290 and group main.  The ++nodegroup option is used to specify which group
291 of machines to use.  Note that there is wraparound: if you specify
292 more nodes than there are hosts in the group, it will reuse
293 hosts. Thus,
294
295 \begin{alltt}
296         charmrun pgm ++nodegroup kale-sun +p6
297 \end{alltt}
298
299 uses hosts (charm, dp, grace, dagger, charm, dp) respectively as
300 nodes (0, 1, 2, 3, 4, 5).
301
302 If you don't specify a ++nodegroup, the default is ++nodegroup main.
303 Thus, if one specifies
304
305 \begin{alltt}
306         charmrun pgm +p4
307 \end{alltt}
308
309 it will use ``localhost'' four times.  ``localhost'' is a Unix
310 trick; it always find a name for whatever machine you're on.
311
312 The user is required to set up remote login permissions on all nodes
313 using the ``.rhosts'' file in the home directory if ``rsh'' is used for remote
314 login into the hosts. If ``ssh'' is used, the user will have to setup
315 password-less login to remote hosts using
316 RSA authentication based on a key-pair and adding public keys to 
317 ``.ssh/authorized\_keys'' file. See ``ssh'' documentation for more information.
318
319 In a network environment, {\tt charmrun} must
320 be able to locate the directory of the executable.  If all workstations
321 share a common file name space this is trivial.  If they don't, {\tt charmrun}
322 will attempt to find the executable in a directory with the same path
323 from the {\bf \$HOME} directory.  Pathname resolution is performed as 
324 follows:
325 \begin{enumerate}
326         \item The system computes the absolute path of {\tt pgm}.
327         \item If the absolute path starts with the equivalent of {\bf \$HOME} 
328         or the current working directory, the beginning part of the 
329         path 
330         is replaced with the environment variable {\bf \$HOME} or the 
331         current working directory. However, if {\tt ++pathfix dir1 dir2} is 
332         specified in the nodes file (see above), the part of
333         the path matching {\tt dir1} is replaced with {\tt dir2}.
334         \item The system tries to locate this program (with modified 
335         pathname and appended extension if specified) on all nodes.
336 \end{enumerate}
337