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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2331 - (hide annotations)
Mon Mar 23 01:18:21 2009 UTC (10 years, 5 months ago) by jfenwick
File MIME type: application/x-tex
File size: 7436 byte(s)
Updated the escript execution section.
Added a few references.
1 gross 2316 \chapter{Execution of an {\it escript} Script}
2     \label{EXECUTION}
3    
4     \section{Overview}
5 jfenwick 2331 A typical way of starting your {\it escript} script \file{myscript.py} is with the \program{escript} command\footnote{The \program{escript} launcher is not supported under \WINDOWS yet.}:
6 gross 2316 \begin{verbatim}
7     escript myscript.py
8     \end{verbatim}
9 jfenwick 2331 as already shown in section~\ref{FirstSteps}\footnote{For this discussion, it is assumed that \program{escript} is included in your \env{PATH} environment. See installation guide for details.}
10     . In some cases
11     it can be useful to work interactively e.g. when debugging a script, with the command
12 gross 2316 \begin{verbatim}
13     escript -i myscript.py
14     \end{verbatim}
15 jfenwick 2331 This will execute \var{myscript.py} and when it completes (or an error occurs), a \PYTHON prompt will be provided.
16     To leave the prompt press \kbd{Control-d}.
17 gross 2316
18     To start
19     \program{escript} using four threads (eg. if you use a multi-core processor) you can use
20     \begin{verbatim}
21     escript -t 4 myscript.py
22     \end{verbatim}
23 jfenwick 2331 This will require {\it escript} to be compiled for \OPENMP\cite{OPENMP}.
24 gross 2316
25 jfenwick 2331 To start \program{escript} using \MPI\cite{MPI} with $8$ processes you use
26 gross 2316 \begin{verbatim}
27 jfenwick 2331 escript -p 8 myscript.py
28 gross 2316 \end{verbatim}
29 jfenwick 2331 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
30 gross 2316 \begin{verbatim}
31 jfenwick 2331 escript -p 8 -t 4 myscript.py
32 gross 2316 \end{verbatim}
33 jfenwick 2331 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}.
34     For example, to use $8$ nodes, with $4$ \MPI processes per node, write
35 gross 2316 \begin{verbatim}
36 jfenwick 2331 escript -n 8 -p 4 myscript.py
37 gross 2316 \end{verbatim}
38 jfenwick 2331 Since threading has some performance advantages over processes, you may specify a number of threads as well.
39     \begin{verbatim}
40     escript -n 8 -p 4 -t 2 myscript.py
41     \end{verbatim}
42     This runs the script on $8$ nodes, with $4$ processes per node and $2$ threads per process.
43 gross 2316
44     \section{Options}
45     The general form of the \program{escript} launcher is as follows:
46    
47     \program{escript}
48     \optional{\programopt{-n \var{nn}}}
49 jfenwick 2331 \optional{\programopt{-p \var{np}}}
50 gross 2316 \optional{\programopt{-t \var{nt}}}
51     \optional{\programopt{-f \var{hostfile}}}
52     \optional{\programopt{-x}}
53     \optional{\programopt{-V}}
54     \optional{\programopt{-e}}
55     \optional{\programopt{-h}}
56     \optional{\programopt{-v}}
57     \optional{\programopt{-o}}
58     \optional{\programopt{-c}}
59     \optional{\programopt{-i}}
60     \optional{\var{file}}
61     \optional{\var{ARGS}}
62    
63 jfenwick 2331 where \var{file} is the name of a script, \var{ARGS} are arguments for the script.
64     The \program{escript} program will import your current environment variables.
65     If no \var{file} is given, then you will be given a \PYTHON prompt (see \programopt{-i} for restrictions).
66    
67    
68 gross 2316 The options are used as follows:
69     \begin{itemize}
70    
71     \item[\programopt{-n} \var{nn}] the number of compute nodes \var{nn} to be used. The total number of process being used is
72     $\var{nn} \cdot \var{ns}$. This option overwrites the value of the \env{ESCRIPT_NUM_NODES} environment variable. If $\var{nn}>1$ but {\it escript} is not compiled for \MPI a warning is pronted but execution is continued with $\var{nn}=1$. The default value is 1.
73    
74 jfenwick 2331 \item[\programopt{-p} \var{np}] the number of processor slots per node. This options specifies how many \MPI processes are used on each node. The total number of process being used is
75     $\var{nn} \cdot \var{np}$. This option overwrites the value of the \env{ESCRIPT_NUM_PROC} 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.
76 gross 2316
77 jfenwick 2331 \item[\programopt{-t} \var{nt}] the number of threads used per processes.
78     The option overwrites the value of the \env{ESCRIPT_NUM_THREADS} environment variable.
79     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.
80 gross 2316
81     \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}. In order to avoid oversubsription the number of differnt
82 jfenwick 2331 hosts defined in \var{hostfile} must be greater or 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.
83 gross 2316 \item[\programopt{-c}] prints the information about the settings used to compile {\it escript} and stops execution..
84     \item[\programopt{-V}] prints the version of {\it escript} and stops execution.
85     \item[\programopt{-h}] prints a help message and stops execution.
86 jfenwick 2331 \item[\programopt{-i}] excutes 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.
87 gross 2316
88 jfenwick 2331 \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.
89 gross 2316
90     \item[\programopt{-o}] switches on the redirection of standart and error 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
91    
92 jfenwick 2331 % \item[\programopt{-x}] interpret \var{file} as an \esysxml \footnote{{\it esysxml} has not been released yet.} task.
93     % This option is still expermental.
94 gross 2316
95     \item[\programopt{-v}] prints some diagonstic information.
96     \end{itemize}
97    
98     \section{Input and Output}
99 jfenwick 2331 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.
100     Error output from any processor will be redirected to the node where \program{escript} has been envoked.
101     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
102     \var{r} is the rank of the process).
103 gross 2316
104 jfenwick 2331 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.
105     This will avoid problems if processes are using a shared file system.
106     Files which collect data which are global for all \MPI processors will created by the process with \MPI rank 0 only.
107     Users should keep in mind that if the file system is not shared, then a file containing global information
108 gross 2316 which is read by all processors needs to be copied to the local file system before \program{escript} is invoked.
109    
110    
111     \section{Hints for MPI programming}
112     Later

  ViewVC Help
Powered by ViewVC 1.1.26