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