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