/[escript]/trunk/doc/user/execute.tex
ViewVC logotype

Contents of /trunk/doc/user/execute.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3293 - (show annotations)
Thu Oct 21 23:18:32 2010 UTC (8 years, 9 months ago) by caltinay
File MIME type: application/x-tex
File size: 13743 byte(s)
user's guide builds again with new class file. The cleanup can commence...

1 \chapter{Execution of an {\it escript} Script}
2 \label{EXECUTION}
3
4 \section{Overview}
5 A typical way of starting your {\it escript} script \file{myscript.py} is with the \program{run-escript} command\index{run-escript}\footnote{The \program{run-escript} launcher is not supported under \WINDOWS yet.}.
6 This command was renamed from \program{escript} (used in previous releases) to
7 avoid clashing with an unrelated program installed by default on some systems.
8 Most 3.1 releases\footnote{i.e. not \WINDOWS or Ubuntu 9.10} of \escript allow
9 either \program{run-escript} or \program{escript} to be used but the latter
10 name will be removed in future releases. To run your script, issue\footnote{For
11 this discussion, it is assumed that \program{run-escript} is included in
12 your \env{PATH} environment. See the installation guide for details.}
13 \begin{verbatim}
14 run-escript myscript.py
15 \end{verbatim}
16 as already shown in \Sec{FirstSteps}.
17 In some cases it can be useful to work interactively, e.g. when debugging a
18 script, with the command
19 \begin{verbatim}
20 run-escript -i myscript.py
21 \end{verbatim}
22 This will execute \var{myscript.py} and when it completes (or an error occurs),
23 a \PYTHON prompt will be provided.
24 To leave the prompt press \kbd{Control-d} (\kbd{Control-z} on \WINDOWS).
25
26 To run the script using four threads (e.g. if you have a multi-core processor)
27 you can use
28 \begin{verbatim}
29 run-escript -t 4 myscript.py
30 \end{verbatim}
31 This requires {\it escript} to be compiled with \OPENMP\cite{OPENMP} support.
32 To run the script using \MPI\cite{MPI} with 8 processes use
33 \begin{verbatim}
34 run-escript -p 8 myscript.py
35 \end{verbatim}
36 If the processors which are used are multi-core processors or you are working
37 on a multi-processor shared memory architecture you can use threading in
38 addition to \MPI.
39 For instance to run 8 \MPI processes with 4 threads each, use the command
40 \begin{verbatim}
41 run-escript -p 8 -t 4 myscript.py
42 \end{verbatim}
43 In the case of a supercomputer or a cluster, you may wish to distribute the
44 workload over a number of nodes\footnote{For simplicity, we will use the term
45 \emph{node} to refer to either a node in a supercomputer or an individual
46 machine in a cluster}.
47 For example, to use 8 nodes with 4 \MPI processes per node, write
48 \begin{verbatim}
49 run-escript -n 8 -p 4 myscript.py
50 \end{verbatim}
51 Since threading has some performance advantages over processes, you may
52 specify a number of threads as well:
53 \begin{verbatim}
54 run-escript -n 8 -p 4 -t 2 myscript.py
55 \end{verbatim}
56 This runs the script on 8 nodes, with 4 processes per node and 2 threads per process.
57
58 \section{Options}
59 The general form of the \program{run-escript} launcher is as follows:
60
61 %%%%
62 % If you are thinking about changing this please remember to update the man page as well
63 %%%%
64
65 \program{run-escript}
66 \optional{\programopt{-n \var{nn}}}
67 \optional{\programopt{-p \var{np}}}
68 \optional{\programopt{-t \var{nt}}}
69 \optional{\programopt{-f \var{hostfile}}}
70 \optional{\programopt{-x}}
71 \optional{\programopt{-V}}
72 \optional{\programopt{-e}}
73 \optional{\programopt{-h}}
74 \optional{\programopt{-v}}
75 \optional{\programopt{-o}}
76 \optional{\programopt{-c}}
77 \optional{\programopt{-i}}
78 \optional{\programopt{-b}}
79 \optional{\var{file}}
80 \optional{\var{ARGS}}
81
82 where \var{file} is the name of a script and \var{ARGS} are the arguments to
83 be passed to the script.
84 The \program{run-escript} program will import your current environment variables.
85 If no \var{file} is given, then you will be presented with a regular \PYTHON
86 prompt (see \programopt{-i} for restrictions).
87
88 The options have the following meaning:
89 \begin{itemize}
90 \item[\programopt{-n} \var{nn}] the number of compute nodes \var{nn} to be used.
91 The total number of process being used is $\var{nn} \cdot \var{ns}$.
92 This option overwrites the value of the \env{ESCRIPT_NUM_NODES}
93 environment variable.
94 If a \var{hostfile} is given (see below), the number of nodes needs to
95 match the number of hosts given in that file.
96 If $\var{nn}>1$ but {\it escript} is not compiled for \MPI, a warning is
97 printed but execution is continued with $\var{nn}=1$.
98 If \programopt{-n} is not set the number of hosts in the host file is
99 used. The default value is 1.
100
101 \item[\programopt{-p} \var{np}] the number of \MPI processes per node.
102 The total number of processes to be used is $\var{nn} \cdot \var{np}$.
103 This option overwrites the value of the \env{ESCRIPT_NUM_PROCS}
104 environment variable.
105 If $\var{np}>1$ but {\it escript} is not compiled for \MPI, a warning is
106 printed but execution is continued with $\var{np}=1$.
107 The default value is 1.
108
109 \item[\programopt{-t} \var{nt}] the number of threads used per process.
110 The option overwrites the value of the \env{ESCRIPT_NUM_THREADS}
111 environment variable.
112 If $\var{nt}>1$ but {\it escript} is not compiled for \OPENMP, a warning
113 is printed but execution is continued with $\var{nt}=1$.
114 The default value is 1.
115
116 \item[\programopt{-f} \var{hostfile}] the name of a file with a list of host names.
117 Some systems require to specify the addresses or names of the compute
118 nodes where \MPI processes should be spawned.
119 These addresses or names of the compute nodes are listed in the file with
120 the name \var{hostfile}.
121 If \programopt{-n} is set, the number of different hosts defined in \var{hostfile}
122 must be equal to the number of requested compute nodes \var{nn}.
123 The option overwrites the value of the \env{ESCRIPT_HOSTFILE} environment
124 variable. By default no host file is used.
125
126 \item[\programopt{-c}] prints information about the settings used to compile {\it escript} and stops execution.
127
128 \item[\programopt{-V}] prints the version of {\it escript} and stops execution.
129
130 \item[\programopt{-h}] prints a help message and stops execution.
131
132 \item[\programopt{-i}] executes the script \var{file} and switches to
133 interactive mode after the execution is finished or an exception has occurred.
134 This option is useful for debugging a script.
135 The option cannot be used if more than one process ($\var{nn} \cdot \var{np}>1$) is used.
136
137 \item[\programopt{-b}] do not invoke python. This is used to run non-python
138 programs within an environment set for {\it escript}.
139
140 \item[\programopt{-e}] shows additional environment variables and commands
141 used to set up the {\it escript} environment.
142 This option is useful if users wish to execute scripts without using
143 the \program{run-escript} command.
144
145 \item[\programopt{-o}] enables the redirection of messages printed by
146 processors with \MPI rank greater than zero to the files
147 \file{stdout_\var{r}.out} and \file{stderr_\var{r}.out} where \var{r} is
148 the rank of the processor.
149 The option overwrites the value of the \env{ESCRIPT_STDFILES} environment
150 variable.
151
152 %\item[\programopt{-x}] interpret \var{file} as an {\it esysxml}\footnote{not released yet} task.
153 % This option is still experimental.
154
155 \item[\programopt{-v}] prints some diagnostic information.
156 \end{itemize}
157
158 \subsection{Notes}
159 \begin{itemize}
160 \item Make sure that \program{mpiexec} is in your \env{PATH} if applicable.
161 \item For MPICH and INTELMPI and for the case a hostfile is present
162 \program{run-escript} will start the \program{mpd} daemon before execution.
163 \end{itemize}
164
165 \section{Input and Output}
166 When \MPI is used on more than one process ($\var{nn} \cdot \var{np} >1$) no
167 input from the standard input is accepted.
168 Standard output on any process other than the master process (\var{rank}=0)
169 will also not be available.
170 Error output from any processor will be redirected to the node where \program{run-escript} has been invoked.
171 If the \programopt{-o} Option or \env{ESCRIPT_STDFILES} is set\footnote{That is, it has a non-empty value.},
172 then the standard and error output from any process other than the master
173 process will be written to files of the names \file{stdout_\var{r}.out}
174 and \file{stderr_\var{r}.out} (where \var{r} is the rank of the process).
175
176 If files are created or read by individual \MPI processes with information
177 local to the process (e.g. in the \function{dump} function) and more than one
178 process is used ($\var{nn} \cdot \var{np} >1$), the \MPI process rank is
179 appended to the file names.
180 This is to avoid problems if processes are using a shared file system.
181 Files which collect data that are global for all \MPI processors are created
182 by the process with \MPI rank 0 only.
183 Users should keep in mind that if the file system is not shared among the
184 processes, then a file containing global information which is read by all
185 processors needs to be copied to the local file system(s) before \program{run-escript} is invoked.
186
187 \section{Hints for MPI Programming}
188 In general a script based on the \escript module does not require
189 modifications to run under \MPI.
190 However, one needs to be careful if other modules are used.
191
192 When \MPI is used on more than one process ($\var{nn} \cdot \var{np} >1$) the
193 user needs to keep in mind that several copies of his script are executed at
194 the same time\footnote{In the case of \OPENMP only one copy is running
195 but {\it escript} temporarily spawns threads.} while data exchange is
196 performed through the \escript module.
197
198 This has three main implications:
199 \begin{enumerate}
200 \item most arguments (\var{Data} excluded) should have the same values on all
201 processors, e.g. \var{int}, \var{float}, \var{str} and \numpy parameters.
202 \item the same operations will be called on all processors.
203 \item different processors may store different amounts of information.
204 \end{enumerate}
205
206 With a few exceptions\footnote{\var{getTupleForDataPoint}}, values of
207 types \var{int}, \var{float}, \var{str} and \numpy returned by \escript will
208 have the same value on all processors.
209 If values produced by other modules are used as arguments, the user has to
210 make sure that the argument values are identical on all processors.
211 For instance, the usage of a random number generator to create argument values
212 bears the risk that the value may depend on the processor.
213
214 Some operations in \escript require communication with all processors
215 executing the job. It is not always obvious which operations these are.
216 For example, \var{Lsup} returns the largest value on all processors.
217 \var{getValue} on \var{Locator} may refer to a value stored on another processor.
218 For this reason it is better if scripts do not have conditional operations
219 (which manipulate data) based on which processor the script is on.
220 Crashing or hanging scripts can be an indication that this has happened.
221
222 It is not always possible to divide data evenly amongst processors.
223 In fact some processors might not have any data at all.
224 Try to avoid writing scripts which iterate over data points, instead try to
225 describe the operation you wish to perform as a whole.
226
227 Special attention is required when using files on more than one processor as
228 several processors access the file at the same time. Opening a file for
229 reading is safe, however the user has to make sure that the variables which
230 are set from reading data from files are identical on all processors.
231
232 When writing data to a file it is important that only one processor is writing
233 to the file at any time. As all values in \escript are global it is sufficient
234 to write values on the processor with \MPI rank $0$ only.
235 The \class{FileWriter} class provides a convenient way to write global data
236 to a simple file. The following script writes to the file \file{test.txt} on
237 the processor with rank 0 only:
238 \begin{python}
239 from esys.escript import FileWriter
240 f = FileWriter('test.txt')
241 f.write('test message')
242 f.close()
243 \end{python}
244 We strongly recommend using this class rather than \PYTHON's built-in \function{open}
245 function as it will guarantee a script which will run in single processor mode
246 as well as under \MPI.
247
248 If the situation occurs that one of the processors throws an exception, for
249 instance when opening a file for writing fails, the other processors are not
250 automatically made aware of this since \MPI does not handle exceptions.
251 However, \MPI will still terminate the other processes but may not inform the
252 user of the reason in an obvious way.
253 The user needs to inspect the error output files to identify the exception.
254
255 \section{Lazy Evaluation}
256 \label{sec:lazy}
257 Escript now supports lazy evaluation~\cite{lazyauspdc}.
258 Lazy evaluation is when expressions are not evaluated until they are actually
259 needed.
260 When applied to suitable problems, it can reduce both the memory and CPU time
261 required to perform a simulation.
262 This implementation is designed to be as transparent as possible; so
263 significant alterations to scripts are not required.
264
265 \subsection*{How to use it}
266 To have lazy evaluation applied automatically, put the following command in
267 your script after the imports.
268
269 \begin{python}
270 from esys.escript import setEscriptParamInt
271 setEscriptParamInt('AUTOLAZY', 1)
272 \end{python}
273
274 To get greater benefit, some fine tuning may be required.
275 If your simulation involves iterating for a number of time steps,
276 you will probably have some state variables which are updated in
277 each iteration based on their value in the previous iteration.
278 For example,
279
280 \begin{python}
281 x=f(x_previous)
282 y=g(x)
283 z=h(y, x, ...)
284 \end{python}
285
286 could be modified to:
287
288 \begin{python}
289 x=f(x_previous)
290 resolve(x)
291 y=g(x)
292 z=h(y, x, ...)
293 \end{python}
294
295 The \code{resolve} command forces x to be evaluated immediately.
296
297 \subsection*{When to use it}
298 We believe that problems involving large domains and complicated expressions
299 will benefit most from lazy evaluation.
300 In cases where lazy does provide a benefit, larger domains should give a
301 greater benefit.
302 If you are uncertain, try running a test on a smaller domain first.
303

  ViewVC Help
Powered by ViewVC 1.1.26