# Diff of /trunk/doc/user/execute.tex

revision 2374 by gross, Mon Apr 6 06:41:49 2009 UTC revision 2375 by gross, Tue Apr 7 04:41:28 2009 UTC
# Line 26  To start \program{escript} using \MPI\ci Line 26  To start \program{escript} using \MPI\ci
26  \begin{verbatim}  \begin{verbatim}
27  escript -p 8 myscript.py  escript -p 8 myscript.py
28  \end{verbatim}  \end{verbatim}
29  If the processors which are used are multi--core processors or multi--processor shared memory archtiectures you can use threading in addition to \MPI. For instance to run $8$ \MPI processes with using $4$ threads each, you use the command  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
30  \begin{verbatim}  \begin{verbatim}
31  escript -p 8 -t 4 myscript.py  escript -p 8 -t 4 myscript.py
32  \end{verbatim}  \end{verbatim}
# Line 87  If $\var{nt}>1$ but {\it escript} is not Line 87  If $\var{nt}>1$ but {\it escript} is not
87
88   \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   \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
89  the number of different  the number of different
90  hosts defined in \var{hostfile} must be equal to the number of requsted compute nodes \var{nn}. The option overwrites the value of the \env{ESCRIPT_HOSTFILE} environment variable. By default value no host file is used.  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.
91   \item[\programopt{-c}] prints the information about the settings used to compile {\it escript} and stops execution..   \item[\programopt{-c}] prints the information about the settings used to compile {\it escript} and stops execution..
92   \item[\programopt{-V}] prints the version of {\it escript} and stops execution.   \item[\programopt{-V}] prints the version of {\it escript} and stops execution.
93   \item[\programopt{-h}] prints a help message and stops execution.   \item[\programopt{-h}] prints a help message and stops execution.
94   \item[\programopt{-i}] executes the script \var{file} and switches to interactive mode after the execution is finished or an exception has occured. This option is useful for debugging a script. The option cannot be used if more then one process ($\var{nn} \cdot \var{np}>1$) is used.   \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 then one process ($\var{nn} \cdot \var{np}>1$) is used.
95  \item[\programopt{-b}] do not invoke python. This is used to run non-python programs.  \item[\programopt{-b}] do not invoke python. This is used to run non-python programs.
96
97   \item[\programopt{-e}] shows additional environment variables and commands used during \program{escript} execution. This option is useful if users wish to excute scripts without using the \program{escript} command.   \item[\programopt{-e}] shows additional environment variables and commands used during \program{escript} execution. This option is useful if users wish to execute scripts without using the \program{escript} command.
98
99   \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   \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
100
101  %  \item[\programopt{-x}] interpret \var{file} as an \esysxml \footnote{{\it esysxml} has not been released yet.} task.  %  \item[\programopt{-x}] interpret \var{file} as an \esysxml \footnote{{\it esysxml} has not been released yet.} task.
102  % This option is still expermental.  % This option is still experimental.
103
104   \item[\programopt{-v}] prints some diagonstic information.   \item[\programopt{-v}] prints some diagnostic information.
105  \end{itemize}  \end{itemize}
106  \subsection{Notes}  \subsection{Notes}
107  \begin{itemize}  \begin{itemize}
# Line 112  hosts defined in \var{hostfile} must be Line 112  hosts defined in \var{hostfile} must be
112
113  \section{Input and Output}  \section{Input and Output}
114  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 the the master process (\var{rank}=0) will not be available.  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 the the master process (\var{rank}=0) will not be available.
115  Error output from any processor will be redirected to the node where \program{escript} has been envoked.  Error output from any processor will be redirected to the node where \program{escript} has been invoked.
116  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  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
117  \var{r} is the rank of the process).  \var{r} is the rank of the process).
118
# Line 123  Users should keep in mind that if the fi Line 123  Users should keep in mind that if the fi
123  which is read by all processors needs to be copied to the local file system before \program{escript} is invoked.  which is read by all processors needs to be copied to the local file system before \program{escript} is invoked.
124
125
\section{Hints for MPI programming}
Later
126    \section{Hints for MPI Programming}
127    In general a script based on the \escript module does not require modifications when running under \MPI. However, one needs to be careful if other modules are used.
128
129    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
130    \footnote{In case of OpenMP only one copy is running but \escript temporarily spawns threads.} while data exchange is performed through the \escript module. At any time,
131    \escript assumes that an argument of the type \var{int}, \var{float}, \var{str}
132    and \numarray has an identical value across all processors. All
133    values of these types returned by \escript have the same value on all processors.
134    If values produced by other modules are used as argument the user has to make sure that
135    the value is identical on all processors. For instance, the usage of a random number
136     generator to create a value for argument bears the risk that the value may depend on
137    the processor.
138
139    An other case which needs special attention is the usage of files. When reading data
140    from a file it advisable to use the \var{'r'} for readable when opened. Keep in mind that
141    several scripts will simultaneously access the file. If data are written to a file
142    only one processor must open the file for writing. The function \function{getMPIRankWorld}
143    which returns the processor id between $0$ and the number of processors
144    helps to achieve this. The following script writes to the file
145    \var{'test.txt'} on the processor with id $0$ only:
146    \begin{python}
147    from esys.escript import *
148    if getMPIRankWorld() == 0 :
149       f = open('test.txt', 'w')
150       f.write('test message')
151       f.close()
152    \end{python}
153    Another technique is to extend the file name by the processor id to avoid conflicts while
154    writing into a shared file system:
155    \begin{python}
156    from esys.escript import *
157    f = open('test.txt.%s'%getMPIRankWorld(), 'w')
158    f.write('test message')
159    f.close()
160    \end{python}
161    creating files with names
162    \var{test.txt.0},
163    \var{test.txt.1},
164    \var{test.txt.2},
165    $\ldots$.
166
167    If there is the situation that if execution on one of the processors is throwing an exception,
168    for instance as opening a file for writing fails, are not made aware of this as \MPI
169    is not handling exceptions. However, \MPI will terminate the other processes but
170    may not inform the user of the reason in the obvious way. The user needs to inspect the
171    error output files to identify the exception.
172
173
174
175

Legend:
 Removed from v.2374 changed lines Added in v.2375