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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2923 - (show annotations)
Thu Feb 4 04:05:36 2010 UTC (9 years, 6 months ago) by jfenwick
File MIME type: application/x-tex
File size: 13368 byte(s)
Bringing non-release specific things from stage3.1 r2922 back to trunk

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

  ViewVC Help
Powered by ViewVC 1.1.26