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