doc/user/Installation.tex

% $Id$
%
%           Copyright © 2006 by ACcESS MNRF
%               \url{http://www.access.edu.au
%         Primary Business: Queensland, Australia.
%   Licensed under the Open Software License version 3.0
%      http://www.opensource.org/licenses/osl-3.0.php
%
\chapter{Installation}
\label{INSTALL}

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

\section{Software needed for installation}

\begin{itemize}
   \item scons  0.96.91 or newer, see \url{http://www.scons.org/}
   \item python  2.3.4 or higher, see \url{http://www.python.org/}
   \item numarray  0.9 or higher, see \url{http://www.stsci.edu/resources/software_hardware/numarray}
   \item python boost boost  1.31.0 or higher (build system defaults to boost 1.33.0), see \url{http://www.boost.org/}
   \item g++, see \url{http://gcc.gnu.org/}, or intel c++  compiler, see \\
\url{http://www.intel.com/cd/software/products/asmo-na/eng/compilers/}.
\end{itemize}

\subsection{optional Libraries}
These libraries are optional at compile time. By default, thay are switched off.
\begin{itemize}
   \item parallel direct solver from the SGI SCSL library, see \url{http://www.sgi.com/products/software/scsl.html} 
   \item parallel direct solver from intel MKL library  (delivered with intel compilers), see \url{http://www.intel.com/cd/software/products/asmo-na/eng/perflib/mkl/}.
\end{itemize}

\subsection{optional Software}

\begin{itemize}
   \item off-line visualization:
      \begin{itemize}
      \item mayavi, see \url{http://mayavi.sourceforge.net/}.
      \item opendx, see \url{http://www.opendx.org/}
      \end{itemize}
   \item on-line visualization with pyvisi:
\begin{itemize}
      \item vtk  4.2.1 or newer with with python interface, see \url{http://public.kitware.com/VTK/}
      \item gnuplot  with with python interface, see \url{http://www.gnuplot.info/}
      \item  povray, see \url{http://www.povray.org/}.
\end{itemize}
\end{itemize}

\section{Get the source code}

You can download the source code, examples and, if required, release tests from \url{http://shake200.esscc.uq.edu.au/joomla/content/view/78//}.
Files can be downloaded as *.zip or *.tar.gz files. 
Usage is under the Open Software License version 3.0, see \url{http://www.opensource.org/licenses/osl-3.0.php}.

\subsection{Unpack zip file}
Use the commands

\begin{verbatim}
   mkdir <my esys dir>
   mv escript*.zip <my esys dir>
  cd <my esys dir>
  unzip escript*.zip
\end{verbatim}

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

\subsection{Unpack tar file}
  
Use the commands

\begin{verbatim}
  mkdir <my esys dir>
  mv escriot*.tar.gz <my esys dir>
  cd <my esys dir>
  tar xzf escript*.tar.gz
\end{verbatim}

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

\section{Installation}

The installation is started by 
\begin{verbatim}
  cd <my esys dir>
  scons dodebug=no
\end{verbatim}
By default the configuration for Linux is used. If there is a file \verb|scons/<hostname>_options.py| where is \verb|hostname| is the name of the machine the installation is running (non-literal or non-numerical charcters are replaed by underscore)  options is this file are overwrite the default setting. Use =scons/ess_options.py= as a staring point to create a file for your machine. If you want to use personalied setting in the file myoptions.py you can run
\begin{verbatim}
  cd <my esys dir>
  scons dodebug=no options_file=myoptions.py
\end{verbatim}
You can also over-ride individual setting through the command line. e.g.
\begin{verbatim}
   cd <my esys dir>
  scons dodebug=no libinstall=/usr/lib
\end{verbatim}
will install the libraries into the directory \verb|/usr/lib|. 

Get help on options with the following command
\begin{verbatim}
  cd <my esys dir>
  scons -h
\end{verbatim}
To uninstall use
\begin{verbatim}
  cd <my esys dir>
  scons -c
\end{verbatim}

If you have more than one processor available for compilation you can use the -j option to tell scons to do parallel compiles:
\begin{verbatim}
   cd <my esys dir>
   scons dodebug=no -j 8
\end{verbatim}
\section{Running Release Tests}
To test your installation you have to download and unpack the release tests. You can run the tests by
\begin{verbatim}
   cd <my esys dir>
   scons dodebug=no all_tests
\end{verbatim}
The tests can take a while (up to several hours). In some cases it can be sufficient to run the test for the C/C++ components only. Use  
\begin{verbatim}
   cd <my esys dir>
   scons dodebug=no run_tests
\end{verbatim}
to run these tests.
It can be usefull to run the tests in the debug mode:
\begin{verbatim}
   cd <my esys dir>
   scons dodebug=yes run_tests
\end{verbatim}
Keep in mind that this will rebuild the libraries in the debug mode. You have to rebuild the libraries with option =dodebug=no= to get back to a productive installation.


\section{Environment setup}
To make esys accessible from python you have to set
\begin{verbatim}
export PYTHONPATH=<my esys dir>:${PYTHONPATH}
export LD_LIBRARY_PATH=<my esys dir>/lib:${LD_LIBRARY_PATH}
\end{verbatim}
Currently an installation into the python site-packages directory is not supported.

If you want to check your setup and you have download the examples you can run
\begin{verbatim}
cd <my esys dir>/doc/examples
python poisson.py
\end{verbatim}

\subsection{OpenMP support}

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):
\begin{verbatim}
export OMP_NUM_THREADS=4
cd <my esys dir>/doc/examples
python poisson.py
\end{verbatim}

If you do not set OMP_NUM_THREADS you will get one thread for each processor on the system, even though you probably will not use that many processors. Be sure to always set OMP_NUM_THREADS before running the program on a system where OpenMP is enabled.

\section{Getting help}
If there is a problem or question please contact \url{mailto:esys@esscc.uq.edu.au}.
1	% $Id$
2	%
3	% Copyright © 2006 by ACcESS MNRF
4	% \url{http://www.access.edu.au
5	% Primary Business: Queensland, Australia.
6	% Licensed under the Open Software License version 3.0
7	% http://www.opensource.org/licenses/osl-3.0.php
8	%
9	\chapter{Installation}
10	\label{INSTALL}
11
12	Visit \url{http://iservo.edu.au/twiki/bin/view/ESSCC/EsysUser} for more information.
13
14	\section{Software needed for installation}
15
16	\begin{itemize}
17	\item scons 0.96.91 or newer, see \url{http://www.scons.org/}
18	\item python 2.3.4 or higher, see \url{http://www.python.org/}
19	\item numarray 0.9 or higher, see \url{http://www.stsci.edu/resources/software_hardware/numarray}
20	\item python boost boost 1.31.0 or higher (build system defaults to boost 1.33.0), see \url{http://www.boost.org/}
21	\item g++, see \url{http://gcc.gnu.org/}, or intel c++ compiler, see \\
22	\url{http://www.intel.com/cd/software/products/asmo-na/eng/compilers/}.
23	\end{itemize}
24
25	\subsection{optional Libraries}
26	These libraries are optional at compile time. By default, thay are switched off.
27	\begin{itemize}
28	\item parallel direct solver from the SGI SCSL library, see \url{http://www.sgi.com/products/software/scsl.html}
29	\item parallel direct solver from intel MKL library (delivered with intel compilers), see \url{http://www.intel.com/cd/software/products/asmo-na/eng/perflib/mkl/}.
30	\end{itemize}
31
32	\subsection{optional Software}
33
34	\begin{itemize}
35	\item off-line visualization:
36	\begin{itemize}
37	\item mayavi, see \url{http://mayavi.sourceforge.net/}.
38	\item opendx, see \url{http://www.opendx.org/}
39	\end{itemize}
40	\item on-line visualization with pyvisi:
41	\begin{itemize}
42	\item vtk 4.2.1 or newer with with python interface, see \url{http://public.kitware.com/VTK/}
43	\item gnuplot with with python interface, see \url{http://www.gnuplot.info/}
44	\item povray, see \url{http://www.povray.org/}.
45	\end{itemize}
46	\end{itemize}
47
48	\section{Get the source code}
49
50	You can download the source code, examples and, if required, release tests from \url{http://shake200.esscc.uq.edu.au/joomla/content/view/78//}.
51	Files can be downloaded as .zip or .tar.gz files.
52	Usage is under the Open Software License version 3.0, see \url{http://www.opensource.org/licenses/osl-3.0.php}.
53
54	\subsection{Unpack zip file}
55	Use the commands
56
57	\begin{verbatim}
58	mkdir <my esys dir>
59	mv escript*.zip <my esys dir>
60	cd <my esys dir>
61	unzip escript*.zip
62	\end{verbatim}
63
64	to unzip the source files into the directory \verb\|<my esys dir>\|.
65
66	\subsection{Unpack tar file}
67
68	Use the commands
69
70	\begin{verbatim}
71	mkdir <my esys dir>
72	mv escriot*.tar.gz <my esys dir>
73	cd <my esys dir>
74	tar xzf escript*.tar.gz
75	\end{verbatim}
76
77	to unpack the source files into the directory \verb\|<my esys dir>\|.
78
79	\section{Installation}
80
81	The installation is started by
82	\begin{verbatim}
83	cd <my esys dir>
84	scons dodebug=no
85	\end{verbatim}
86	By default the configuration for Linux is used. If there is a file \verb\|scons/<hostname>_options.py\| where is \verb\|hostname\| is the name of the machine the installation is running (non-literal or non-numerical charcters are replaed by underscore) options is this file are overwrite the default setting. Use =scons/ess_options.py= as a staring point to create a file for your machine. If you want to use personalied setting in the file myoptions.py you can run
87	\begin{verbatim}
88	cd <my esys dir>
89	scons dodebug=no options_file=myoptions.py
90	\end{verbatim}
91	You can also over-ride individual setting through the command line. e.g.
92	\begin{verbatim}
93	cd <my esys dir>
94	scons dodebug=no libinstall=/usr/lib
95	\end{verbatim}
96	will install the libraries into the directory \verb\|/usr/lib\|.
97
98	Get help on options with the following command
99	\begin{verbatim}
100	cd <my esys dir>
101	scons -h
102	\end{verbatim}
103	To uninstall use
104	\begin{verbatim}
105	cd <my esys dir>
106	scons -c
107	\end{verbatim}
108
109	If you have more than one processor available for compilation you can use the -j option to tell scons to do parallel compiles:
110	\begin{verbatim}
111	cd <my esys dir>
112	scons dodebug=no -j 8
113	\end{verbatim}
114	\section{Running Release Tests}
115	To test your installation you have to download and unpack the release tests. You can run the tests by
116	\begin{verbatim}
117	cd <my esys dir>
118	scons dodebug=no all_tests
119	\end{verbatim}
120	The tests can take a while (up to several hours). In some cases it can be sufficient to run the test for the C/C++ components only. Use
121	\begin{verbatim}
122	cd <my esys dir>
123	scons dodebug=no run_tests
124	\end{verbatim}
125	to run these tests.
126	It can be usefull to run the tests in the debug mode:
127	\begin{verbatim}
128	cd <my esys dir>
129	scons dodebug=yes run_tests
130	\end{verbatim}
131	Keep in mind that this will rebuild the libraries in the debug mode. You have to rebuild the libraries with option =dodebug=no= to get back to a productive installation.
132
133
134	\section{Environment setup}
135	To make esys accessible from python you have to set
136	\begin{verbatim}
137	export PYTHONPATH=<my esys dir>:${PYTHONPATH}
138	export LD_LIBRARY_PATH=<my esys dir>/lib:${LD_LIBRARY_PATH}
139	\end{verbatim}
140	Currently an installation into the python site-packages directory is not supported.
141
142	If you want to check your setup and you have download the examples you can run
143	\begin{verbatim}
144	cd <my esys dir>/doc/examples
145	python poisson.py
146	\end{verbatim}
147
148	\subsection{OpenMP support}
149
150	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):
151	\begin{verbatim}
152	export OMP_NUM_THREADS=4
153	cd <my esys dir>/doc/examples
154	python poisson.py
155	\end{verbatim}
156
157	If you do not set OMP_NUM_THREADS you will get one thread for each processor on the system, even though you probably will not use that many processors. Be sure to always set OMP_NUM_THREADS before running the program on a system where OpenMP is enabled.
158
159	\section{Getting help}
160	If there is a problem or question please contact \url{mailto:esys@esscc.uq.edu.au}.
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision