1 

% 
2 
% $Id$ 
% $Id$ 
3 

% 
4 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
5 

% 
6 

% Copyright 20032007 by ACceSS MNRF 
7 

% Copyright 2007 by University of Queensland 
8 

% 
9 

% http://esscc.uq.edu.au 
10 

% Primary Business: Queensland, Australia 
11 

% Licensed under the Open Software License version 3.0 
12 

% http://www.opensource.org/licenses/osl3.0.php 
13 

% 
14 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
15 

% 
16 


17 

\chapter{Installation} 
18 

\label{INSTALL} 
19 


20 

Visit \url{http://iservo.edu.au/twiki/bin/view/ESSCC/EsysUser} for more information. 
21 


22 

\section{Software Needed for Installation} 
23 


24 

\begin{itemize} 
25 

\item scons 0.96.91 or newer (see \url{http://www.scons.org/}) 
26 

\item python 2.3.4 or higher (see \url{http://www.python.org/}) 
27 

\item numarray 0.9 or higher (see \url{http://www.stsci.edu/resources/software_hardware/numarray}) 
28 

\item python boost boost 1.31.0 or higher (see \url{http://www.boost.org/}) 
29 

\item g++ (see \url{http://gcc.gnu.org/}) or Intel c++ compiler (see \\ 
30 

\url{http://www.intel.com/cd/software/products/asmona/eng/compilers/}). 
31 

\end{itemize} 
32 


33 

\subsection{Optional Libraries} 
34 

These libraries are optional at compile time. By default, thay are switched off. 
35 

\begin{itemize} 
36 

\item parallel direct solver from the SGI SCSL library (see \url{http://www.sgi.com/products/software/scsl.html}) 
37 

\item parallel direct solver from Intel MKL library which is included with the Intel compilers (see \url{http://www.intel.com/cd/software/products/asmona/eng/perflib/mkl/}). 
38 

\end{itemize} 
39 


40 

\subsection{Optional Software} 
41 


42 

\begin{itemize} 
43 

\item visualization with our pyvisi interface to VTK: 
44 

\item vtk 4.2.1 or newer with with python interface (see \url{http://public.kitware.com/VTK/}). 
45 

\item Alternatives for offline visualization: 
46 

\begin{itemize} 
47 

\item mayavi (see \url{http://mayavi.sourceforge.net/}). 
48 

\item opendx (see \url{http://www.opendx.org/}). 
49 

\end{itemize} 
50 

\item Alternatives for online visualization: 
51 

\begin{itemize} 
52 

\item gnuplot with with python interface (see \url{http://www.gnuplot.info/}). 
53 

\item povray (see \url{http://www.povray.org/}). 
54 

\end{itemize} 
55 

\end{itemize} 
56 


57 

\section{Get the Source Code} 
58 


59 

You can download the complete source code, examples and release tests from \url{https://shake200.esscc.uq.edu.au/twiki/bin/view/ESSCC/EsysUser}. 
60 

Files can be downloaded as *.zip or *.tar.gz files. 
61 

This software is distributed under the Open Software License version 3.0 (see \url{http://www.opensource.org/licenses/osl3.0.php}). 
62 


63 

\subsection{Unpack zip File} 
64 

Use the commands 
65 


66 

\begin{verbatim} 
67 

mkdir <my esys dir> 
68 

mv escript*.zip <my esys dir> 
69 

cd <my esys dir> 
70 

unzip escript*.zip 
71 

\end{verbatim} 
72 


73 

to unzip the source files into the directory \verb<my esys dir>. 
74 


75 

\subsection{Unpack tar File} 
76 


77 

Use the commands 
78 


79 

\begin{verbatim} 
80 

mkdir <my esys dir> 
81 

mv escript*.tar.gz <my esys dir> 
82 

cd <my esys dir> 
83 

tar xzf escript*.tar.gz 
84 

\end{verbatim} 
85 


86 

to unpack the source files into the directory \verb<my esys dir>. 
87 


88 

\section{Installation} 
89 


90 

The installation is started by 
91 

\begin{verbatim} 
92 

cd <my esys dir> 
93 

scons dodebug=no 
94 

\end{verbatim} 
95 

By default the configuration for Linux is used. If there is a file \verbscons/<hostname>_options.py it will contain values to override the default settings. Use =scons/ess_options.py= as a staring point to create a file for your machine. If you want to use personalized settings in a file called =myoptions.py= you can run 
96 

\begin{verbatim} 
97 

cd <my esys dir> 
98 

scons dodebug=no options_file=myoptions.py 
99 

\end{verbatim} 
100 

You can also override individual settings through the command line: 
101 

\begin{verbatim} 
102 

cd <my esys dir> 
103 

scons dodebug=no libinstall=/usr/lib 
104 

\end{verbatim} 
105 

This will install the libraries into the directory \verb/usr/lib. 
106 


107 

Help on options is available with: 
108 

\begin{verbatim} 
109 

cd <my esys dir> 
110 

scons h 
111 

\end{verbatim} 
112 

To uninstall the software use 
113 

\begin{verbatim} 
114 

cd <my esys dir> 
115 

scons c 
116 

\end{verbatim} 
117 


118 

If you have more than one processor available for compilation you can use the j option to tell scons to do parallel compiles: 
119 

\begin{verbatim} 
120 

cd <my esys dir> 
121 

scons dodebug=no j 8 
122 

\end{verbatim} 
123 

\section{Running Release Tests} 
124 

You can run the test suite of approximately 30,000 unit tests in a few hours with 
125 

\begin{verbatim} 
126 

cd <my esys dir> 
127 

scons dodebug=no all_tests 
128 

\end{verbatim} 
129 


130 

\section{Environment Setup} 
131 

To make esys accessible from python you have to set 
132 

\begin{verbatim} 
133 

export PYTHONPATH=<my esys dir>:${PYTHONPATH} 
134 

export LD_LIBRARY_PATH=<my esys dir>/lib:${LD_LIBRARY_PATH} 
135 

\end{verbatim} 
136 


137 

If you build \esys with 
138 

\begin{verbatim} 
139 

cd <my esys dir> 
140 

scons dodebug=no prefix=/usr 
141 

\end{verbatim} 
142 

then your libraries and python modules will be installed in system directories and you will 
143 

not have to set LD_LIBRARY_PATH and PYTHONPATH (assuming python is installed in 
144 

/usr/lib/python/sitemodules). 
145 


146 

Now you are ready to test your setup by running one of the supplied examples 
147 

\begin{verbatim} 
148 

cd <my esys dir>/doc/examples 
149 

python poisson.py 
150 

\end{verbatim} 
151 


152 

\subsection{OpenMP Support} 
153 


154 

If your system and compiler support OpenMP parallelization and OpenMP parallelization has been switched on during compilation you need to set the following environment variable to run scripts in parallel (in this case with four threads): 
155 

\begin{verbatim} 
156 

export OMP_NUM_THREADS=4 
157 

cd <my esys dir>/doc/examples 
158 

python poisson.py 
159 

\end{verbatim} 
160 


161 

\subsection{MPI Support} 
162 


163 

If you wish to use MPI parallelization, and it has been switched on during compilation with useMPI=yes, you need to use the following commands to run scripts in parallel (in this case with four CPUs): 
164 

\begin{verbatim} 
165 

cd <my esys dir>/doc/examples 
166 

mpirun np 4 <my esys dir>/lib/pythonMPI poisson.py 
167 

\end{verbatim} 
168 


169 
\chapter{The First Steps} 
When running an MPI job the standard output of process zero goes to the screen, while the standard output of the other processes 
170 

is automatically redirected to files with names like stdout_cpu_0001.out. 
171 


172 
\section{Introduction} 
\section{Getting Help} 
173 

Please direct any questions you might have to \url{mailto:esys@esscc.uq.edu.au}. 

\subsection{Getting the software} 





\escript, \ESyS, all freely available. Where do people get \finley from? 





\begin{enumerate} 


\item how to get the software 


\item a few words about the general structure 


\item installation 


\end{enumerate} 





\section{How to solve a linear PDE} 





\begin{figure} 


\centerline{\includegraphics[width=\figwidth]{FirstStepDomain}} 


\caption{Domain $\Omega$ with outer normal field $n$.} 


\label{fig:FirstSteps.1} 


\end{figure} 





\begin{figure} 


\centerline{\includegraphics[width=\figwidth]{FirstStepMesh}} 


\caption{Mesh of $4 \time 4$ elements on a rectangular domain. Here 


each element is a quadrilateral and described by four nodes, namely 


the corner points. The solution is interpolated by a bilinear 


polynomial.} 


\label{fig:FirstSteps.2} 


\end{figure} 





We want to solve the \index{partial differential equation}(\index{PDE}) 


\begin{equation} 


\Delta u + \alpha u =f 


\label{eq:FirstSteps.1} 


\end{equation} 


for the solution $u$ on the domain $\Omega$. Here we assume that the 


domain is the rectangle of length $1$ and height $2$, see 


\fig{fig:FirstSteps.1}. $\Delta$ denotes the \index{Laplace 


operator} which is defined by 


\begin{equation} 


\Delta u = (u\hackscore {,1})\hackscore{,1}+(u\hackscore{,2})\hackscore{,2} 


\label{eq:FirstSteps.1.1} 


\end{equation} 


where for any function $w$ and any direction $i$ $u\hackscore{,i}$ 


denotes the derivative of $w$ with respect to $i$. $\alpha$ is a 


known constant (we will set $\alpha=10$) and $f$ is a given function 


which may depend on the location in the domain. On the boundary of 


the domain $\Omega$ the solution $u$ shall fulfill the socalled 


homogeneous \index{Neumann boundary condition} 


\begin{equation} 


\frac{\partial u}{\partial n} = 0 


\label{eq:FirstSteps.2} 


\end{equation} 


where $n=(n\hackscore1,n\hackscore2)$ denotes the outer normal field 


of the domain, see Figure~\ref{fig:FirstSteps.1} and 


\begin{equation} 


\frac{\partial u}{\partial n} = n\hackscore1 u\hackscore{,1} + 


n\hackscore2 u\hackscore{,2} 


\label{eq:FirstSteps.2.1} 


\end{equation} 


denotes the normal derivative on the boundary. The partial 


differential \eqn{eq:FirstSteps.1}) together with the 


boundary condition~(\eqn{eq:FirstSteps.2}) forms a boundary value 


problem (\index{BVP}) for unknown function $u$. 





In most cases, the BVP cannot be solved analytically and numerical 


methods have to be used construct an approximation of the solution 


$u$. Here we will use the \index{finite element method} 


(\index{FEM}). The basic idea is to fill the domain with a set of 


points, so called nodes. The solution is approximated by its values on 


the nodes. Moreover, the domain is subdivide into small subdomain, 


socalled elements. On each element the solution is represented by a 


polynomial of a certain degree through its values at the nodes located 


in the element. The nodes and its connection through elements is 


called a \index{mesh}. \fig{fig:FirstSteps.2} shows an example 


of a FEM mesh with four elements in the $x_0$ and for elements in the 


$x_1$ direction over a rectangular domain. On more details we referring 


to the literature, for instance \cite{X1,X2,X3}. 





\escript provides the class \linearPDE to define a 


general linear, steady differential partial differential equation of 


second order. We will discuss the most general form that can be 


defined through \class{linearPDE} later. The components which are 


relevant for us here is as follows: 


\begin{equation} 


\sum\hackscore{i,j=0}^k (A\hackscore{ij} 


u\hackscore{,j})\hackscore{,i} + D u = Y 


\label{eq:FirstSteps.3} 


\end{equation} 


In this form $D$ and $Y$ are scalars and $A$ is a $k \times k$ matrix 


where $k$ denotes the spatial dimension (in our example we have 


$k=2$). By comparing the template~(\ref{eq:FirstSteps.3}) with the 


differential equation~(\ref{eq:FirstSteps.1}) we want to solve we can 


immediately identify the appropriate values for $A$, $D$ and $Y$: 


\begin{equation} 


\begin{array}{lcccc} 


A\hackscore{ij} & = & \delta\hackscore{ij}& =& 


\left[ 


\begin{array}{cc} 


1 & 0\\ 


0 & 1 


\end{array} 


\right] \\ 


D & =& \alpha \\ 


Y & = & f \\ 


\end{array} 


\label{eq:FirstSteps.3.1} 


\end{equation} 


When the PDE is defined via~(\eqn{eq:FirstSteps.3}), \class{linearPDE} 


makes a particular assumptions about the boundary conditions: 


\begin{equation} 


\sum\hackscore{i,j=0}^k n\hackscore{i} A\hackscore{ij} 


u\hackscore{,j} = 0 


\label{eq:FirstSteps.4} 


\end{equation} 


Note that this boundary condition does not require extra information 


as it only refers to the coefficient $A$ which already appears in the 


PDE and so natural for it. Therefore this boundary condition is called 


a \index{natural boundary condition}. 





We will set $\alpha=10$ and $f=10$ such that $u=1$ becomes the exact 


solution of the boundary value problem. We make this very simple 


choice to be able to test our program as we can compare the result 


with the exact solution. Later we will set $\alpha$ and $f$ to 


functions of their locations in the domain in which case we will not 


be able to give an analytic solution. However, after testing our 


program on this very simple case, we can be confident that it working 


correctly before we apply it is a more complicated situation. 





This is the program to solve the boundary value problem: (Remember that 


lines starting with '\#' are commend lines in Python) 


%\verbatiminput{examples/FirstSteps1.py} 


\begin{python} 


# import ESyS and finley 


from ESyS import * 


import finley 


# set a value for alpha: 


alpha=10 


# generate mesh: 


mydomain=finley.Rectangle(n0=40,n1=20,l0=2.,l1=1.) 


# generate a system: 


mypde=linearPDE(A=[[1,0],[0,1]],D=alpha,Y=10,domain=mydomain) 


# generate a test solution: 


u=mypde.getSolution() 


# calculate the error of the solution 


error=u1. 


print "norm of the approximation error is ",Lsup(error) 


\end{python} 


Line 2 import \escript and a few other tools for \ESyS. In Line 3 is 


importing \finley which is used to solve the partial differential 


equation. In line 7, a rectangular domain of length $l\hackscore 0=2$ 


and height $l\hackscore 1=1$ is generated and subdivided in 


$n\hackscore 0=40$ and $n\hackscore 1=20$ elements in $x\hackscore 0$ 


and $x\hackscore 1$ direction, respectively. 





We are using a function of \finley. This determines later in the code 


which solver for the PDE is actually being used to solve the PDE. 





The solution is done in three steps: 


\begin{enumerate} 


\item generate a finite element mesh subdividing the domain into elements. 


\item assemble the system of linear equations $Mu=b$ from the BVP 


\item solve the linear system to get $u$ 


\end{enumerate} 


The returned $u$ is given an approximation of the solution of the BVP 


at the nodes of the finite element mesh. The quality of the 


approximation depends on the size of the elements of the finite 


element mesh: As smaller the element size the better the 


approximation. In our example we know the solution of the BVP so we 


can compare the returned approximation with the true solution. In 


fact, as the true solution is simple, we can expect that the 


approximation is exact. 





The first step imports the package \ESyS which includes among 


others the module \finley. 





\section{A Time Dependent Problem} 





% \verbatiminput{exam/finley\hackscoretime.py} 





\section{With Dirichlet Conditions} 





% \verbatiminput{exam/finley\hackscoredirichlet.py} 





\section{Systems of PDEs} 





% \verbatiminput{exam/system\hackscoretime.py} 





\section{Explicit Schemes} 


% \verbatiminput{exam/explicit\hackscoretime.py} 
