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