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