Documentation: add ++quiet to runtime options
[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 ssh
83 method.
84
85 This will pass {\tt -n \$P} to indicate how many processes to
86 launch.
87 If {\tt -n \$P} is not required because the number of processes
88 to launch is determined via queueing system environment varibles
89 then use {\tt ++mpiexec-no-n} rather than {\tt ++mpiexec}.
90 An executable named something other than {\tt mpiexec} can be
91 used with the additional argument {\tt ++remote-shell} {\it runmpi},
92 with `runmpi' replaced by the necessary name.
93
94 Use of this option can potentially provide a few benefits:
95
96 \begin{itemize}
97 \item Faster startup compared to the SSH approach charmrun would
98   otherwise use
99 \item No need to generate a nodelist file
100 \item Multi-node job startup on clusters that do not allow connections
101   from the head/login nodes to the compute nodes
102 \end{itemize}
103
104 At present, this option depends on the environment variables for some
105 common MPI implementations. It supports OpenMPI ({\tt OMPI\_COMM\_WORLD\_RANK} and
106 {\tt OMPI\_COMM\_WORLD\_SIZE}), M(VA)PICH ({\tt MPIRUN\_RANK} and {\tt
107   MPIRUN\_NPROCS} or {\tt PMI\_RANK} and {\tt PMI\_SIZE}),
108 and IBM POE ({\tt MP\_CHILD} and {\tt MP\_PROCS}).
109
110 \item[{\tt ++debug}] Run each node under gdb in an xterm window, prompting
111 the user to begin execution.
112
113 \item[{\tt ++debug-no-pause}] Run each node under gdb in an xterm window
114 immediately (i.e. without prompting the user to begin execution).
115
116 If using one of the {\tt ++debug} or {\tt ++debug-no-pause} options,
117 the user must ensure the following:
118 \begin{enumerate}
119
120 \item The {\tt DISPLAY} environment variable points to your terminal.
121 SSH's X11 forwarding does not work properly with \charmpp{}.
122
123 \item The nodes must be authorized to create windows on the host machine (see
124 man pages for {\tt xhost} and {\tt xauth}).
125
126 \item {\tt xterm}, {\tt xdpyinfo},  and {\tt gdb} must be in
127 the user's path.
128
129 \item The path must be set in the {\tt .cshrc} file, not the {\tt .login}
130 file, because {\tt ssh} does not run the {\tt .login} file.
131
132 \end{enumerate}
133
134 \item[{\tt ++scalable-start}]   Scalable start, or SMP-aware startup. It is useful for scalable process launch on multi-core systems since it creates only one ssh session per node and spawns all clients from that ssh session. This is the default startup strategy and the option is retained for backward compatibility.
135
136 \item[{\tt ++batch}]            Ssh a set of node programs at a time, avoiding overloading Charmrun pe.  In this strategy, the nodes assigned to a charmrun are divided into sets of fixed size. Charmrun performs ssh to the nodes in the current set, waits for the clients to connect back and then performs ssh on the next set. We call the number of nodes in one ssh set as batch size.
137
138 \item[{\tt ++maxssh}] Maximum number of {\tt ssh}'s to run at a
139 time. For backwards compatibility, this option is also available as {\tt ++maxrsh}.
140
141 \item[{\tt ++nodelist}] File containing list of nodes.
142
143
144 \item[{\tt ++ppn}]              Number of pes per node
145
146 \item[{\tt ++help}]             Print help messages
147
148 \item[{\tt ++runscript}]        Script to run node-program with. The specified run script is invoked with the node program and parameter. For example:
149
150 \begin{alltt}
151 ./charmrun +p4 ./pgm 100 2 3 ++runscript ./set\_env\_script
152 \end{alltt}
153
154 In this case, the {\tt set\_env\_script} is invoked on each node before launching {\tt pgm}.
155
156 \item[{\tt ++xterm}]            Which xterm to use
157
158 \item[{\tt ++in-xterm}]         Run each node in an xterm window
159
160 \item[{\tt ++display}]          X Display for xterm
161
162 \item[{\tt ++debugger}]         Which debugger to use
163
164 \item[{\tt ++remote-shell}]     Which remote shell to use
165
166 \item[{\tt ++useip}]            Use IP address provided for charmrun IP
167
168 \item[{\tt ++usehostname}]      Send nodes our symbolic hostname instead of IP address
169
170
171
172 \item[{\tt ++server-auth}]      CCS Authentication file
173
174 \item[{\tt ++server-port}]      Port to listen for CCS requests
175
176 \item[{\tt ++server}]           Enable client-server (CCS) mode
177
178 \item[{\tt ++nodegroup}]        Which group of nodes to use
179
180 \item[{\tt ++verbose}]          Print diagnostic messages
181
182 \item[{\tt ++quiet}]            Suppress runtime output during startup and shutdown
183
184 \item[{\tt ++timeout}]          Seconds to wait per host connection
185
186 \item[{\tt ++p}]                Number of processes to create
187
188 \end{description}
189
190 \subsection{SMP and Multicore Options}
191
192 On multicore platforms, operating systems (by default) are free to move
193 processes and threads among cores to balance load. This however sometimes can
194 degrade the performance of Charm++ applications due to the extra overhead of
195 moving processes and threads, especially for Charm++ applications that already
196 implement their own dynamic load balancing.
197
198 Charm++ provides the following runtime options to set the processor affinity
199 automatically so that processes or threads no longer move. When cpu affinity
200 is supported by an operating system (tested at Charm++ configuration time),
201 the same runtime options can be used for all flavors of Charm++ versions
202 including network and MPI versions, smp and non-smp versions.
203
204 \begin{description}
205
206 \item[{\tt +setcpuaffinity}]             Set cpu affinity automatically for processes (when Charm++ is based on non-smp versions) or threads (when smp). This option is the default on platforms that support it.
207
208 \item[{\tt +excludecore <core \#>}]       Do 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.
209
210 \item[{\tt +pemap L[-U[:S[.R]+O]][,...]}] Bind the execution threads to
211   the sequence of cores described by the arguments using the operating
212   system's CPU affinity functions.
213
214 A single number identifies a particular core. Two numbers separated by
215 a dash identify an inclusive range (\emph{lower bound} and \emph{upper
216   bound}). If they are followed by a colon and another number (a
217 \emph{stride}), that range will be stepped through in increments of
218 the additional number. Within each stride, a dot followed by a
219 \emph{run} will indicate how many cores to use from that starting
220 point. A plus represents the offset to the previous core number. 
221 Multiple {\tt +offset} flags are supported, e.g., 0-7+8+16 equals 0,8,16,1,9,17.
222
223 For example, the sequence {\tt 0-8:2,16,20-24} includes cores 0, 2, 4,
224 6, 8, 16, 20, 21, 22, 23, 24. On a 4-way quad-core system, if one
225 wanted to use 3 cores from each socket, one could write this as {\tt
226 0-15:4.3}. {\tt +ppn 10 +pemap 0-11:6.5+12} equals {\tt +ppn 10 +pemap 
227 0,12,1,13,2,14,3,15,4,16,6,18,7,19,8,20,9,21,10,22}
228
229 \item[{\tt +commap p[,q,...]}] Bind communication threads to the
230   listed cores, one per process.
231
232 \end{description}
233
234 \subsection{IO buffering options}
235 \label{io buffer options}
236 There may be circumstances where a \charmpp{} application may want to take
237 or relinquish control of stdout buffer flushing. Most systems default to
238 giving the \charmpp{} runtime control over stdout but a few default to
239 giving the application that control. The user can override these system
240 defaults with the following runtime options:
241
242 \begin{description}
243 \item[{\tt +io\_flush\_user}]     User (application) controls stdout flushing
244 \item[{\tt +io\_flush\_system}]   The \charmpp{} runtime controls flushing
245 \end{description}
246
247
248 \section{Nodelist file}
249
250 For network of workstations,
251 the list of machines to run the program can be specified in a file.
252 Without a nodelist file, \charmpp{} runs the program only on the
253 local machine.
254
255 The format of this file
256 allows you to define groups of machines, giving each group a name.
257 Each line of the nodes file is a command.  The most important command
258 is:
259
260 \begin{alltt}
261 host <hostname> <qualifiers>
262 \end{alltt}
263
264 which specifies a host.  The other commands are qualifiers: they modify
265 the properties of all hosts that follow them.  The qualifiers are:
266
267
268 \begin{tabbing}
269 {\tt group <groupname>}~~~\= - subsequent hosts are members of specified group\\
270 {\tt login <login>  }     \> - subsequent hosts use the specified login\\
271 {\tt shell <shell>  }     \> - subsequent hosts use the specified remote
272 shell\\
273 %{\tt passwd <passwd>}     \> - subsequent hosts use the specified password\\
274 {\tt setup <cmd>  }       \> - subsequent hosts should execute cmd\\
275 {\tt pathfix <dir1> <dir2>}         \> - subsequent hosts should replace dir1 with dir2 in the program path\\
276 {\tt cpus <n>}            \> - subsequent hosts should use N light-weight processes\\
277 {\tt speed <s>}           \> - subsequent hosts have relative speed rating\\
278 {\tt ext <extn>}          \> - subsequent hosts should append extn to the pgm name\\
279 \end{tabbing}
280
281 {\bf Note:}
282 By default, charmrun uses a remote shell ``ssh'' to spawn node processes
283 on the remote hosts. The {\tt shell} qualifier can be used to override
284 it with say, ``rsh''. One can set the {\tt CONV\_RSH} environment variable
285 or use charmrun option {\tt ++remote-shell} to override the default remote
286 shell for all hosts with unspecified {\tt shell} qualifier.
287
288 All qualifiers accept ``*'' as an argument, this resets the modifier to
289 its default value.  Note that currently, the passwd, cpus, and speed
290 factors are ignored.  Inline qualifiers are also allowed:
291
292 \begin{alltt}
293 host beauty ++cpus 2 ++shell ssh
294 \end{alltt}
295
296 Except for ``group'', every other qualifier can be inlined, with the
297 restriction that if the ``setup'' qualifier is inlined, it should be
298 the last qualifier on the ``host'' or ``group'' statement line.
299
300 Here is a simple nodes file:
301
302 \begin{alltt}
303         group kale-sun ++cpus 1
304           host charm.cs.illinois.edu ++shell ssh
305           host dp.cs.illinois.edu
306           host grace.cs.illinois.edu
307           host dagger.cs.illinois.edu
308         group kale-sol
309           host beauty.cs.illinois.edu ++cpus 2
310         group main
311           host localhost
312 \end{alltt}
313
314 This defines three groups of machines: group kale-sun, group kale-sol,
315 and group main.  The ++nodegroup option is used to specify which group
316 of machines to use.  Note that there is wraparound: if you specify
317 more nodes than there are hosts in the group, it will reuse
318 hosts. Thus,
319
320 \begin{alltt}
321         charmrun pgm ++nodegroup kale-sun +p6
322 \end{alltt}
323
324 uses hosts (charm, dp, grace, dagger, charm, dp) respectively as
325 nodes (0, 1, 2, 3, 4, 5).
326
327 If you don't specify a ++nodegroup, the default is ++nodegroup main.
328 Thus, if one specifies
329
330 \begin{alltt}
331         charmrun pgm +p4
332 \end{alltt}
333
334 it will use ``localhost'' four times.  ``localhost'' is a Unix
335 trick; it always find a name for whatever machine you're on.
336
337 Using ``ssh'', the user will have to setup
338 password-less login to remote hosts using
339 public key authentication based on a key-pair and adding public keys to
340 ``.ssh/authorized\_keys'' file. See ``ssh'' documentation for more information.
341 If ``rsh'' is used for remote
342 login to the compute nodes, the user is required to set up remote login permissions on all nodes
343 using the ``.rhosts'' file in their home directory.
344
345 In a network environment, {\tt charmrun} must
346 be able to locate the directory of the executable.  If all workstations
347 share a common file name space this is trivial.  If they don't, {\tt charmrun}
348 will attempt to find the executable in a directory with the same path
349 from the {\bf \$HOME} directory.  Pathname resolution is performed as
350 follows:
351 \begin{enumerate}
352         \item The system computes the absolute path of {\tt pgm}.
353         \item If the absolute path starts with the equivalent of {\bf \$HOME}
354         or the current working directory, the beginning part of the
355         path
356         is replaced with the environment variable {\bf \$HOME} or the
357         current working directory. However, if {\tt ++pathfix dir1 dir2} is
358         specified in the nodes file (see above), the part of
359         the path matching {\tt dir1} is replaced with {\tt dir2}.
360         \item The system tries to locate this program (with modified
361         pathname and appended extension if specified) on all nodes.
362 \end{enumerate}
363