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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3293 - (hide annotations)
Thu Oct 21 23:18:32 2010 UTC (8 years, 10 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 gross 2316 \chapter{Execution of an {\it escript} Script}
2     \label{EXECUTION}
3    
4     \section{Overview}
5 caltinay 3291 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 gross 2316 \begin{verbatim}
14 caltinay 3291 run-escript myscript.py
15 gross 2316 \end{verbatim}
16 caltinay 3291 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 gross 2316 \begin{verbatim}
20 jfenwick 2923 run-escript -i myscript.py
21 gross 2316 \end{verbatim}
22 caltinay 3291 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 gross 2316
26 caltinay 3291 To run the script using four threads (e.g. if you have a multi-core processor)
27     you can use
28 gross 2316 \begin{verbatim}
29 jfenwick 2923 run-escript -t 4 myscript.py
30 gross 2316 \end{verbatim}
31 caltinay 3291 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 gross 2316 \begin{verbatim}
34 jfenwick 2923 run-escript -p 8 myscript.py
35 gross 2316 \end{verbatim}
36 caltinay 3291 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 gross 2316 \begin{verbatim}
41 jfenwick 2923 run-escript -p 8 -t 4 myscript.py
42 gross 2316 \end{verbatim}
43 caltinay 3291 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 gross 2316 \begin{verbatim}
49 jfenwick 2923 run-escript -n 8 -p 4 myscript.py
50 gross 2316 \end{verbatim}
51 caltinay 3291 Since threading has some performance advantages over processes, you may
52     specify a number of threads as well:
53 jfenwick 2331 \begin{verbatim}
54 jfenwick 2923 run-escript -n 8 -p 4 -t 2 myscript.py
55 jfenwick 2331 \end{verbatim}
56 caltinay 3291 This runs the script on 8 nodes, with 4 processes per node and 2 threads per process.
57 gross 2316
58     \section{Options}
59 jfenwick 2923 The general form of the \program{run-escript} launcher is as follows:
60 gross 2316
61 jfenwick 2345 %%%%
62     % If you are thinking about changing this please remember to update the man page as well
63     %%%%
64    
65 jfenwick 2923 \program{run-escript}
66 gross 2316 \optional{\programopt{-n \var{nn}}}
67 jfenwick 2331 \optional{\programopt{-p \var{np}}}
68 gross 2316 \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 jfenwick 2343 \optional{\programopt{-b}}
79 gross 2316 \optional{\var{file}}
80     \optional{\var{ARGS}}
81    
82 caltinay 3291 where \var{file} is the name of a script and \var{ARGS} are the arguments to
83     be passed to the script.
84 jfenwick 2923 The \program{run-escript} program will import your current environment variables.
85 caltinay 3291 If no \var{file} is given, then you will be presented with a regular \PYTHON
86     prompt (see \programopt{-i} for restrictions).
87 jfenwick 2331
88 caltinay 3291 The options have the following meaning:
89 gross 2316 \begin{itemize}
90 caltinay 3291 \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 gross 2316
101 caltinay 3291 \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 gross 2316
109 caltinay 3291 \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 gross 2316
116 caltinay 3291 \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 gross 2316
126 caltinay 3291 \item[\programopt{-c}] prints information about the settings used to compile {\it escript} and stops execution.
127 gross 2316
128 caltinay 3291 \item[\programopt{-V}] prints the version of {\it escript} and stops execution.
129 gross 2316
130 caltinay 3291 \item[\programopt{-h}] prints a help message and stops execution.
131 gross 2316
132 caltinay 3291 \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 caltinay 3293 %\item[\programopt{-x}] interpret \var{file} as an {\it esysxml}\footnote{not released yet} task.
153 caltinay 3291 % This option is still experimental.
154    
155     \item[\programopt{-v}] prints some diagnostic information.
156 gross 2316 \end{itemize}
157 caltinay 3291
158 gross 2370 \subsection{Notes}
159     \begin{itemize}
160 caltinay 3291 \item Make sure that \program{mpiexec} is in your \env{PATH} if applicable.
161 gross 2370 \item For MPICH and INTELMPI and for the case a hostfile is present
162 caltinay 3291 \program{run-escript} will start the \program{mpd} daemon before execution.
163 gross 2370 \end{itemize}
164 gross 2316
165     \section{Input and Output}
166 caltinay 3291 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 jfenwick 2923 Error output from any processor will be redirected to the node where \program{run-escript} has been invoked.
171 caltinay 3291 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 gross 2316
176 caltinay 3291 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 gross 2316
187 gross 2375 \section{Hints for MPI Programming}
188 caltinay 3291 In general a script based on the \escript module does not require
189     modifications to run under \MPI.
190 jfenwick 2923 However, one needs to be careful if other modules are used.
191 gross 2375
192 caltinay 3291 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 gross 2375
198 jfenwick 2780 This has three main implications:
199     \begin{enumerate}
200 caltinay 3291 \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 jfenwick 2780 \end{enumerate}
205    
206 caltinay 3291 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 jfenwick 2780
214 caltinay 3291 Some operations in \escript require communication with all processors
215     executing the job. It is not always obvious which operations these are.
216 jfenwick 2780 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 caltinay 3291 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 jfenwick 2780 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 caltinay 3291 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 jfenwick 2780
227 caltinay 3291 Special attention is required when using files on more than one processor as
228 caltinay 2736 several processors access the file at the same time. Opening a file for
229 caltinay 3291 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 gross 2420
232 caltinay 3291 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 gross 2420 The \class{FileWriter} class provides a convenient way to write global data
236 caltinay 3291 to a simple file. The following script writes to the file \file{test.txt} on
237     the processor with rank 0 only:
238 gross 2375 \begin{python}
239 caltinay 3291 from esys.escript import FileWriter
240     f = FileWriter('test.txt')
241     f.write('test message')
242     f.close()
243 gross 2375 \end{python}
244 caltinay 3291 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 gross 2375
248 caltinay 3291 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 jfenwick 2923
255     \section{Lazy Evaluation}
256     \label{sec:lazy}
257     Escript now supports lazy evaluation~\cite{lazyauspdc}.
258 caltinay 3291 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 jfenwick 2923
265     \subsection*{How to use it}
266 caltinay 3291 To have lazy evaluation applied automatically, put the following command in
267     your script after the imports.
268 jfenwick 2923
269     \begin{python}
270 caltinay 3291 from esys.escript import setEscriptParamInt
271     setEscriptParamInt('AUTOLAZY', 1)
272 jfenwick 2923 \end{python}
273    
274     To get greater benefit, some fine tuning may be required.
275 caltinay 3291 If your simulation involves iterating for a number of time steps,
276 jfenwick 2923 you will probably have some state variables which are updated in
277     each iteration based on their value in the previous iteration.
278 caltinay 3291 For example,
279 jfenwick 2923
280     \begin{python}
281 caltinay 3291 x=f(x_previous)
282     y=g(x)
283     z=h(y, x, ...)
284 jfenwick 2923 \end{python}
285    
286 caltinay 3291 could be modified to:
287 jfenwick 2923
288     \begin{python}
289 caltinay 3291 x=f(x_previous)
290     resolve(x)
291     y=g(x)
292     z=h(y, x, ...)
293 jfenwick 2923 \end{python}
294    
295 caltinay 3291 The \code{resolve} command forces x to be evaluated immediately.
296 jfenwick 2923
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 caltinay 3291 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 jfenwick 2923

  ViewVC Help
Powered by ViewVC 1.1.26