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