ViewVC logotype

Contents of /release/5.2/doc/install/source.tex

Parent Directory Parent Directory | Revision Log Revision Log

Revision 6699 - (show annotations)
Tue Jun 26 02:33:36 2018 UTC (2 years, 9 months ago) by jfenwick
File MIME type: application/x-tex
File size: 17932 byte(s)
bring mac change over
1 %!TEX root = install.tex
2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 % Copyright (c) 2012-2018 by The University of Queensland
4 % http://www.uq.edu.au
5 %
6 % Primary Business: Queensland, Australia
7 % Licensed under the Apache License, version 2.0
8 % http://www.apache.org/licenses/LICENSE-2.0
9 %
10 % Development until 2012 by Earth Systems Science Computational Center (ESSCC)
11 % Development 2012-2013 by School of Earth Sciences
12 % Development from 2014 by Centre for Geoscience Computing (GeoComp)
13 %
14 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16 % Notes about compilers
18 \chapter{Installing from Source}\label{chap:source}
20 This chapter assumes you are using a unix/posix like system (including MacOSX).
22 \section{Parallel Technologies}\label{sec:par}
23 It is likely that the computer you run \escript on, will have more than one processor core.
24 Escript can make use of multiple cores [in order to solve problems more quickly] if it is told to do so,
25 but this functionality must be enabled at compile time.
26 Section~\ref{sec:needpar} gives some rough guidelines to help you determine what you need.
28 There are two technologies which \escript can employ here.
29 \begin{itemize}
30 \item OpenMP -- the more efficient of the two [thread level parallelism].
31 \item MPI -- Uses multiple processes (less efficient), needs less help from the compiler.
32 \end{itemize}
34 Escript is primarily tested on recent versions of the GNU and Intel suites (``g++'' / ``icpc'').
35 However, it also passes our tests when compiled using ``clang++''.
36 Escript now requires compiler support for some features of the C++11 standard.
37 See Appendix~\ref{app:cxxfeatures} for a list.
40 Our current test compilers include:
41 \begin{itemize}
42 \item g++ 6
43 \item clang++ 7
44 \item intel icpc v17
45 \end{itemize}
47 Note that:
48 \begin{itemize}
49 \item OpenMP will not function correctly for g++ $\leq$ 4.2.1 (and is not currently supported by clang).
50 \item icpc v11 has a subtle bug involving OpenMP and C++ exception handling, so this combination should not be used.
51 \end{itemize}
53 \subsection{What parallel technology do I need?}\label{sec:needpar}
54 If you are using any version of Linux released in the past few years, then your system compiler will support
55 \openmp with no extra work (and give better performance); so you should use it.
56 You will not need MPI unless your computer is some form of cluster.
58 If you are using BSD or MacOSX and you are just experimenting with \escript, then performance is
59 probably not a major issue for you at the moment so you don't need to use either \openmp or MPI.
60 This also applies if you write and polish your scripts on your computer and then send them to a cluster to execute.
61 If in the future you find escript useful and your scripts take significant time to run, then you may want to recompile
62 \escript with more options.
66 Note that even if your version of \escript has support for \openmp or MPI, you will still need to tell the system to
67 use it when you run your scripts.
68 If you are using the \texttt{run-escript} launcher, then this is controlled by
69 the \texttt{-t}, \texttt{-p}, and \texttt{-n} options.
70 If not, then consult the documentation for your MPI libraries (or the compiler documentation in the case of OpenMP
71 \footnote{It may be enough to set the \texttt{OMP\_NUM\_THREADS} environment variable.}).
73 If you are using MacOSX, then see the next section, if not, then skip to Section~\ref{sec:build}.
75 \section{MacOS}
76 This release of \escript has only been tested on OSX 10.13.
77 For this section we assume you are using either \texttt{homebrew} or \texttt{MacPorts} as a package
78 manager\footnote{Note that package managers will make changes to your computer based on programs configured by other people from
79 various places around the internet. It is important to satisfy yourself as to the security of those systems.}.
80 You can of course install prerequisite software in other ways.
81 For example, we have had \emph{some} success changing the default
82 compilers used by those systems. However this is more complicated and we do not provide a guide here.
84 \noindent Both of those systems require the XCode command line tools to be installed\footnote{As of OSX10.9, the
85 command \texttt{xcode-select --install} will allow you to download and install the commandline tools.}.
87 \section{Building}\label{sec:build}
89 To simplify things for people, we have prepared \texttt{_options.py} files for a number of
90 systems\footnote{These are correct a time of writing but later versions of those systems may require tweaks.
91 Also, these systems represent a cross section of possible platforms rather than meaning those systems get particular support.}.
92 The options files are located in the \texttt{scons/templates} directory. We suggest that the file most relevant to your OS
93 be copied from the templates directory to the scons directory and renamed to the form XXXX_options.py where XXXX
94 should be replaced with your computer's (host-)name.
95 If your particular system is not in the list below, or if you want a more customised
96 build,
97 see Section~\ref{sec:othersrc} for instructions.
98 \begin{itemize}
99 \item Debian - \ref{sec:debsrc}
100 \item Ubuntu - \ref{sec:ubsrc}
101 \item OpenSuse - \ref{sec:susesrc}
102 \item Centos - \ref{sec:centossrc}
103 \item Fedora - \ref{sec:fedorasrc}
104 \item MacOS (macports) - \ref{sec:macportsrc}
105 \item MacOS (homebrew) - \ref{sec:homebrewsrc}
106 \item FreeBSD - \ref{sec:freebsdsrc}
107 \end{itemize}
109 Once these are done proceed to Section~\ref{sec:cleanup} for cleanup steps.
111 All of these instructions assume that you have obtained the \escript source (and uncompressed it if necessary).
112 \subsection{Debian}\label{sec:debsrc}
114 \begin{shellCode}
115 sudo aptitude install python-dev python-numpy libboost-python-dev libnetcdf-dev
116 sudo aptitude install libnetcdf-cxx-legacy-dev libnetcdf-c++4-dev
117 sudo aptitude install scons lsb-release libboost-random-dev
118 sudo aptitude install python-sympy python-matplotlib python-scipy
119 sudo aptitude install python-pyproj python-gdal
120 \end{shellCode}
122 \noindent If you are running \textit{Wheezy}, you can use:
123 \begin{shellCode}
124 sudo aptitude install gmsh
125 \end{shellCode}
126 to add extra meshing functionality.
128 \begin{optionalstep}
129 If for some reason, you wish to rebuild the documentation, you would also need the following:
130 \begin{shellCode}
131 sudo aptitude install python-sphinx doxygen python-docutils texlive
132 sudo aptitude install zip texlive-latex-extra latex-xcolor
133 \end{shellCode}
134 \end{optionalstep}
136 \noindent In the source directory execute the following (substitute jessie for XXXX):
137 \begin{shellCode}
138 scons -j1 options_file=scons/templates/XXXX_options.py
139 \end{shellCode}
141 \noindent If you wish to test your build, you can use the following:
142 \begin{shellCode}
143 scons -j1 py_tests options_file=scons/templates/XXXX_options.py
144 \end{shellCode}
146 \subsection{Ubuntu}\label{sec:ubsrc}
148 If you have not installed \texttt{aptitude}, then substitute \texttt{apt-get} in the following.
149 \begin{shellCode}
150 sudo aptitude install python-dev python-numpy libboost-python-dev
151 sudo aptitude install libnetcdf-cxx-legacy-dev libnetcdf-c++4-dev
152 sudo aptitude install libnetcdf-dev libboost-random-dev
153 sudo aptitude install scons lsb-release
154 sudo aptitude install python-sympy python-matplotlib python-scipy
155 sudo aptitude install python-pyproj python-gdal gmsh
156 \end{shellCode}
159 \begin{optionalstep}
160 If for some reason, you wish to rebuild the documentation, you would also need the following:
161 \begin{shellCode}
162 sudo aptitude install python-sphinx doxygen python-docutils texlive
163 sudo aptitude install zip texlive-latex-extra latex-xcolor
164 \end{shellCode}
165 \end{optionalstep}
167 \noindent In the source directory execute the following (substitute precise, quantal or raring as appropriate for XXXX):
168 \begin{shellCode}
169 scons -j1 options_file=scons/templates/XXXX_options.py
170 \end{shellCode}
172 \noindent If you wish to test your build, you can use the following:
173 \begin{shellCode}
174 scons -j1 py_tests options_file=scons/templates/XXXX_options.py
175 \end{shellCode}
179 \subsection{OpenSuse}\label{sec:susesrc}
180 These instructions were prepared using version $42$ of Leap.
182 \noindent Install packages from the main distribution:
183 \begin{shellCode}
184 sudo zypper in python-devel python-numpy libnetcdf_c++-devel
185 sudo zypper in python-scipy python-sympy python-matplotlib
186 sudo zypper in gcc gcc-c++ scons boost-devel netcdf-devel
187 \end{shellCode}
189 Now to build escript itself.
190 In the escript source directory:
191 \begin{shellCode}
192 scons -j1 options_file=scons/templates/opensuse_options.py
193 \end{shellCode}
195 \noindent If you wish to test your build, you can use the following:
196 \begin{shellCode}
197 scons -j1 py_tests options_file=scons/templates/opensuse_options.py
198 \end{shellCode}
200 \noindent Now go to Section~\ref{sec:cleanup} for cleanup.
202 \subsection{CentOS}\label{sec:centossrc}
203 These instructions were prepared using CentOS release $7$ (from late 2016).
204 The core of escript works, however some functionality is not available because the default packages for some dependencies in CentOS are too old.
206 \noindent Add the \texttt{EPEL} repository.
207 \begin{shellCode}
208 yum install epel-release.noarch
209 \end{shellCode}
211 \noindent Install packages:
212 \begin{shellCode}
213 yum install netcdf-devel netcdf-cxx-devel gdal-python
214 yum install python-devel numpy scipy scons boost-devel
215 yum install python-matplotlib gcc gcc-c++
216 yum install boost-python
217 \end{shellCode}
219 The above packages will allow you to use most features except
220 the \downunder inversion library.
221 If you wish to use those it, you will need to install some additional packages.
223 \noindent For some coordinate transformations, \downunder can also make use of the python interface to a tool called \texttt{proj}.
224 There does not seem to be an obvious CentOS repository for this though.
225 If it turns out to be necessary for your particular application, the source can be downloaded.
227 \noindent Now to build escript itself.
228 In the escript source directory:
229 \begin{shellCode}
230 scons -j1 options_file=scons/templates/centos7_0_options.py
231 \end{shellCode}
233 \noindent Now go to Section~\ref{sec:cleanup} for cleanup.
235 \subsection{Fedora}\label{sec:fedorasrc}
236 These instructions were prepared using the $26$ alpha.
238 \noindent Install packages
239 \begin{shellCode}
240 yum install netcdf-cxx-devel gcc-c++ scipy
241 yum install sympy scons pyproj gdal python-matplotlib
242 yum install boost-devel
243 \end{shellCode}
245 \noindent Now to build escript itself.
246 In the escript source directory:
247 \begin{shellCode}
248 scons -j1 options_file=scons/templates/fedora_options.py
249 \end{shellCode}
251 \noindent If you wish to test your build, you can use the following:
252 \begin{shellCode}
253 scons -j1 py_tests options_file=scons/templates/fedora_options.py
254 \end{shellCode}
256 \noindent Now go to Section~\ref{sec:cleanup} for cleanup.
258 \subsection{MacOS 10.10 and later (macports)}\label{sec:macportsrc}
260 The following will install the capabilities needed for the \texttt{macports_10.10_options.py} file (later versions can use the same options file).
262 \begin{shellCode}
263 sudo port install scons
264 sudo port select --set python python27
265 sudo port install boost
266 sudo port install py27-numpy
267 sudo port install py27-sympy
268 sudo port select --set py-sympy py27-sympy
269 sudo port install py27-scipy
270 sudo port install py27-pyproj
271 sudo port install py27-gdal
272 sudo port install netcdf-cxx
273 sudo port install silo
274 \end{shellCode}
276 \begin{shellCode}
277 scons -j1 options_file=scons/templates/macports_10.10options.py
278 \end{shellCode}
281 \subsection{MacOS 10.13 and later (homebrew)}\label{sec:homebrewsrc}
283 The following will install the capabilities needed for the \texttt{homebrew_10.13_options.py} file.
285 \begin{shellCode}
286 brew install scons
287 brew install boost-python
288 brew install netcdf
289 \end{shellCode}
291 There do not appear to be formulae for \texttt{sympy} or \texttt{pyproj} so if you wish to use those features, then
292 you will need to install them separately.
295 \begin{shellCode}
296 scons -j1 options_file=scons/templates/homebrew_10.13_options.py
297 \end{shellCode}
300 \subsection{FreeBSD}\label{sec:freebsdsrc}
302 At time of writing, \texttt{numpy} does not install correctly on FreeBSD.
303 Since \texttt{numpy} is a critical dependency for \escript, we have been unable to test on FreeBSD.
305 \begin{comment}
306 \subsubsection{Release 10.0}
308 Install the following packages:
309 \begin{itemize}
310 \item python
311 \item scons
312 \item boost-python-libs
313 \item bash
314 \item netcdf
315 \item silo
316 \item py27-scipy
317 \item py27-gdal
318 \item py27-matplotlib
319 \item py27-pyproj
320 \item py27-sympy
321 \end{itemize}
323 \noindent Next choose (or create) your options file.
324 For the setup as above the escript source comes with a prepared file in
325 \texttt{scons/templates/freebsd10.0_options.py}.
326 Finally to build escript issue the following in the escript source directory
327 (replace the options file as required):
328 \begin{shellCode}
329 scons -j1 options_file=scons/templates/freebsd10.0_options.py
330 \end{shellCode}
332 \emph{Note:} Some packages installed above are built with gcc 4.7. Somewhere
333 in the toolchain a system-installed gcc library is pulled in which is
334 incompatible with the one from version 4.7 and would prevent escript from
335 executing successfully. As explained in the FreeBSD
336 documentation\footnote{see \url{http://www.freebsd.org/doc/en/articles/custom-gcc/article.html}}
337 this can be fixed by adding a line to \texttt{/etc/libmap.conf}:
338 \begin{shellCode}
339 libgcc_s.so.1 gcc47/libgcc_s.so.1
340 \end{shellCode}
342 \end{comment}
343 \subsection{Other Systems / Custom Builds}\label{sec:othersrc}
345 \escript has support for a number of optional packages.
346 Some, like \texttt{netcdf} need to be enabled at compile time, while others, such as \texttt{sympy} and the projection packages
347 used in \downunder are checked at run time.
348 For the second type, you can install them at any time (ensuring that python can find them) and they should work.
349 For the first type, you need to modify the options file and recompile with scons.
350 The rest of this section deals with this.
352 To avoid having to specify the options file each time you run scons, copy an existing \texttt{_options.py} file from the
353 \texttt{scons/} or \texttt{scons/templates/} directories. Put the file in the \texttt{scons} directory and name
354 it \textit{yourmachinename}\texttt{_options.py}.\footnote{If the name
355 has - or other non-alpha characters, they must be replaced with underscores in the filename}.
356 For example: on a machine named toybox, the file would be \texttt{scons/toybox_options.py}.
358 Individual lines can be enabled/disabled, by removing or adding \# (the python comment character) to the beginning of the line.
359 For example, to enable OpenMP, change the line
360 \begin{verbatim}
361 #openmp = True
362 \end{verbatim}
363 to
364 \begin{verbatim}
365 openmp = True
366 \end{verbatim}
368 If you are using libraries which are not installed in the standard places (or have different names) you will need to
369 change the relevant lines.
370 A common need for this would be using a more recent version of the boost::python library.
371 You can also change the compiler or the options passed to it by modifying the relevant lines.
373 \subsubsection*{MPI}
374 If you wish to enable or disable MPI, or if you wish to use a different implementation of MPI, you can use the \texttt{mpi}
375 configuration variable.
376 You will also need to ensure that the \texttt{mpi_prefix} and \texttt{mpi_libs} variables are uncommented and set correctly.
377 To disable MPI use, \verb|mpi = 'none'|.
379 \subsubsection{Python3}
380 \escript works with \texttt{python3} but until recently, many distributions have not distributed python3 versions of their packages.
381 You can try it out though by modifying or adding the following variables in your options file:
383 \begin{verbatim}
384 pythoncmd='python3'
385 \end{verbatim}
387 \begin{verbatim}
388 usepython3=True
389 \end{verbatim}
391 \begin{verbatim}
392 pythonlibname='whatever_your_python3_library_is_called'
393 \end{verbatim}
398 \subsubsection{Testing}
399 As indicated earlier, you can test your build using \texttt{scons py_tests}.
400 Note however, that some features like \texttt{netCDF} are optional for using \escript, the tests will report a failure if
401 they are missing.
403 \section{Cleaning up}
404 \label{sec:cleanup}
406 Once the build (and optional testing) is complete, you can remove everything except:
407 \begin{itemize}
408 \item bin
409 \item esys
410 \item lib
411 \item doc
412 \item CREDITS
413 \item LICENSE
414 \item README
415 \end{itemize}
416 The last three aren't strictly required for operation.
417 The \texttt{doc} directory is not required either but does contain examples of escript scripts.
419 You can run escript using \texttt{\textit{path_to_escript_files}/bin/run-escript}.\\
420 Where \texttt{\textit{path_to_escript_files}} is replaced with the real path.
422 \begin{optionalstep}
423 You can add the escript \texttt{bin} directory to your \texttt{PATH} variable.
424 The launcher will then take care of the rest of the environment.
425 \end{optionalstep}
427 \section{Optional Extras}
429 Some other packages which might be useful include:
430 \begin{itemize}
431 \item Lapack and UMFPACK --- direct solvers (install the relevant libraries and enable them in the options file).
432 \item support for the Silo file format (install the relevant libraries and enable them in the options file).
433 \item VisIt --- visualisation package. Can be used independently but our \texttt{weipa} library can make a Visit
434 plug-in to allow direct visualisation of escript simulations.
435 \item gmsh --- meshing software used by our \texttt{pycad} library.
436 \item Mayavi2 --- another visualisation tool.
437 \end{itemize}
440 \subsection{Trilinos}
441 \escript now has some support for Trilinos\footnote{\url{https://trilinos.org/}}
442 solvers and preconditioners.
443 The most significant limitation is that the current Trilinos release does not
444 support block matrices so \escript can only use Trilinos solvers for single
445 PDEs (i.e. no PDE systems).
447 If your distribution does not provide Trilinos packages you can build a working
448 version from source. (See Appendix~\ref{app:trilinos})

  ViewVC Help
Powered by ViewVC 1.1.26