Docs: move caveats of ++debug to just below its description
[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. At present, this depends
79 on the environment variables {\tt OMPI\_COMM\_WORLD\_RANK} and {\tt
80   OMPI\_COMM\_WORLD\_SIZE} being set in each launched process.
81
82 Use of this option can potentially provide a few benefits:
83
84 \begin{itemize}
85 \item Faster startup compared to the SSH/RSH approach charmrun would
86   otherwise use
87 \item No need to generate a nodelist file
88 \item Multi-node job startup on clusters that do no allow connections
89   from the head/login nodes to the compute nodes
90 \end{itemize}
91
92 \item[{\tt ++debug}] Run each node under gdb in an xterm window, prompting
93 the user to begin execution.
94
95 \item[{\tt ++debug-no-pause}] Run each node under gdb in an xterm window
96 immediately (i.e. without prompting the user to begin execution).
97
98 If using one of the {\tt ++debug} or {\tt ++debug-no-pause} options,
99 the user must ensure the following:
100 \begin{enumerate}
101
102 \item The {\tt DISPLAY} environment variable points to your terminal.
103 SSH's X11 forwarding does not work properly with \charmpp{}.
104
105 \item The nodes must be authorized to create windows on the host machine (see
106 man pages for {\tt xhost} and {\tt xauth}).
107
108 \item {\tt xterm}, {\tt xdpyinfo},  and {\tt gdb} must be in
109 the user's path.
110
111 \item The path must be set in the {\tt .cshrc} file, not the {\tt .login}
112 file, because {\tt rsh} does not run the {\tt .login} file. 
113
114 \end{enumerate}
115
116 \item[{\tt ++maxrsh}] Maximum number of {\tt rsh}'s to run at a
117 time.
118
119 \item[{\tt ++nodelist}] File containing list of nodes.
120
121
122 \item[{\tt ++ppn}]              number of pes per node
123
124 \item[{\tt ++help}]             print help messages
125
126 \item[{\tt ++runscript}]        script to run node-program with
127
128 \item[{\tt ++xterm}]            which xterm to use
129
130 \item[{\tt ++in-xterm}]         Run each node in an xterm window
131
132 \item[{\tt ++display}]          X Display for xterm
133
134 \item[{\tt ++debugger}]         which debugger to use
135
136 \item[{\tt ++remote-shell}]     which remote shell to use
137
138 \item[{\tt ++useip}]            Use IP address provided for charmrun IP
139
140 \item[{\tt ++usehostname}]      Send nodes our symbolic hostname instead of IP address
141
142 \item[{\tt ++server-auth}]      CCS Authentication file
143
144 \item[{\tt ++server-port}]      Port to listen for CCS requests
145
146 \item[{\tt ++server}]           Enable client-server (CCS) mode
147
148 \item[{\tt ++nodegroup}]        which group of nodes to use
149
150 \item[{\tt ++verbose}]          Print diagnostic messages
151
152 \item[{\tt ++timeout}]          seconds to wait per host connection
153
154 \item[{\tt ++p}]                number of processes to create
155
156 \end{description}
157
158 \subsubsection{Multicore Options}
159
160 On multicore platforms, operating systems (by default) are free to move
161 processes and threads among cores to balance load. This however sometimes can
162 degrade the performance of Charm++ applications due to the extra overhead of
163 moving processes and threads, especailly when Charm++ applications has already
164 implemented its own dynamic load balancing.
165
166 Charm++ provides the following runtime options to set the processor affinity
167 automatically so that processes or threads no longer move. When cpu affinity
168 is supported by an operating system (tested at Charm++ configuration time),
169 same runtime options can be used for all flavors of Charm++ versions including
170 network and MPI versions, smp and non-smp versions.
171
172 \begin{description}
173
174 \item[{\tt +setcpuaffinity}]             set cpu affinity automatically for processes (when Charm++ is based on non-smp versions) or threads (when smp)
175
176 \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.
177
178 \end{description}
179
180 \subsection{Nodelist file}
181
182 For network of workstations,
183 the list of machines to run the program can be specified in a file.  
184 Without a nodelist file, \charmpp{} runs the program only on the 
185 local machine.
186
187 The format of this file
188 allows you to define groups of machines, giving each group a name.
189 Each line of the nodes file is a command.  The most important command
190 is:
191
192 \begin{alltt}
193 host <hostname> <qualifiers>
194 \end{alltt}
195
196 which specifies a host.  The other commands are qualifiers: they modify
197 the properties of all hosts that follow them.  The qualifiers are:
198
199
200 \begin{tabbing}
201 {\tt group <groupname>}~~~\= - subsequent hosts are members of specified group\\
202 {\tt login <login>  }     \> - subsequent hosts use the specified login\\
203 {\tt shell <shell>  }     \> - subsequent hosts use the specified remote 
204 shell\\
205 %{\tt passwd <passwd>}     \> - subsequent hosts use the specified password\\
206 {\tt setup <cmd>  }       \> - subsequent hosts should execute cmd\\
207 {\tt pathfix <dir1> <dir2>}         \> - subsequent hosts should replace dir1 with dir2 in the program path\\
208 {\tt cpus <n>}            \> - subsequent hosts should use N light-weight processes\\
209 {\tt speed <s>}           \> - subsequent hosts have relative speed rating\\
210 {\tt ext <extn>}          \> - subsequent hosts should append extn to the pgm name\\
211 \end{tabbing}
212
213 {\bf Note:}
214 By default, charmrun uses a remote shell ``rsh'' to spawn node processes
215 on the remote hosts. The {\tt shell} qualifier can be used to override
216 it with say, ``ssh''. One can set the {\tt CONV\_RSH} environment variable
217 or use charmrun option {\tt ++remote-shell} to override the default remote 
218 shell for all hosts with unspecified {\tt shell} qualifier.
219
220 All qualifiers accept ``*'' as an argument, this resets the modifier to
221 its default value.  Note that currently, the passwd, cpus, and speed
222 factors are ignored.  Inline qualifiers are also allowed:
223
224 \begin{alltt}
225 host beauty ++cpus 2 ++shell ssh
226 \end{alltt}
227
228 Except for ``group'', every other qualifier can be inlined, with the
229 restriction that if the ``setup'' qualifier is inlined, it should be
230 the last qualifier on the ``host'' or ``group'' statement line.
231
232 Here is a simple nodes file:
233
234 \begin{alltt}
235         group kale-sun ++cpus 1
236           host charm.cs.uiuc.edu ++shell ssh
237           host dp.cs.uiuc.edu
238           host grace.cs.uiuc.edu
239           host dagger.cs.uiuc.edu
240         group kale-sol
241           host beauty.cs.uiuc.edu ++cpus 2
242         group main
243           host localhost
244 \end{alltt}
245
246 This defines three groups of machines: group kale-sun, group kale-sol,
247 and group main.  The ++nodegroup option is used to specify which group
248 of machines to use.  Note that there is wraparound: if you specify
249 more nodes than there are hosts in the group, it will reuse
250 hosts. Thus,
251
252 \begin{alltt}
253         charmrun pgm ++nodegroup kale-sun +p6
254 \end{alltt}
255
256 uses hosts (charm, dp, grace, dagger, charm, dp) respectively as
257 nodes (0, 1, 2, 3, 4, 5).
258
259 If you don't specify a ++nodegroup, the default is ++nodegroup main.
260 Thus, if one specifies
261
262 \begin{alltt}
263         charmrun pgm +p4
264 \end{alltt}
265
266 it will use ``localhost'' four times.  ``localhost'' is a Unix
267 trick; it always find a name for whatever machine you're on.
268
269 The user is required to set up remote login permissions on all nodes
270 using the ``.rhosts'' file in the home directory if ``rsh'' is used for remote
271 login into the hosts. If ``ssh'' is used, the user will have to setup
272 password-less login to remote hosts using
273 RSA authentication based on a key-pair and adding public keys to 
274 ``.ssh/authorized\_keys'' file. See ``ssh'' documentation for more information.
275
276 In a network environment, {\tt charmrun} must
277 be able to locate the directory of the executable.  If all workstations
278 share a common file name space this is trivial.  If they don't, {\tt charmrun}
279 will attempt to find the executable in a directory with the same path
280 from the {\bf \$HOME} directory.  Pathname resolution is performed as 
281 follows:
282 \begin{enumerate}
283         \item The system computes the absolute path of {\tt pgm}.
284         \item If the absolute path starts with the equivalent of {\bf \$HOME} 
285         or the current working directory, the beginning part of the 
286         path 
287         is replaced with the environment variable {\bf \$HOME} or the 
288         current working directory. However, if {\tt ++pathfix dir1 dir2} is 
289         specified in the nodes file (see above), the part of
290         the path matching {\tt dir1} is replaced with {\tt dir2}.
291         \item The system tries to locate this program (with modified 
292         pathname and appended extension if specified) on all nodes.
293 \end{enumerate}
294
295 \subsubsection{IO buffering options}
296 \label{io buffer options}
297 There may be circumstances where a \charmpp{} application may want to take
298 or relinquish control of stdout buffer flushing. Most systems default to
299 giving the \charmpp{} runtime control over stdout but a few default to
300 giving the application that control. The user can override these system
301 defaults with the following runtime options:
302
303 \begin{description}
304 \item[{\tt +io\_flush\_user}]     User (application) controls stdout flushing
305 \item[{\tt +io\_flush\_system}]   The \charmpp{} runtime controls flushing
306 \end{description}