%!TEX root = install.tex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Copyright (c) 2012-2020 by The University of Queensland
% http://www.uq.edu.au
%
% Primary Business: Queensland, Australia
% Licensed under the Apache License, version 2.0
% http://www.apache.org/licenses/LICENSE-2.0
%
% Development until 2012 by Earth Systems Science Computational Center (ESSCC)
% Development 2012-2013 by School of Earth Sciences
% Development from 2014 by Centre for Geoscience Computing (GeoComp)
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Notes about compilers

\chapter{Installing from Source}\label{chap:source}

This chapter describes installing \escript from source on unix/posix like
systems (including MacOSX) and Windows 10.

\section{Parallel Technologies}\label{sec:par}
It is likely that the computer you run \escript on, will have more than one processor core.
Escript can make use of multiple cores [in order to solve problems more quickly] if it is told to do so,
but this functionality must be enabled at compile time.
Section~\ref{sec:needpar} gives some rough guidelines to help you determine what you need.

There are two technologies which \escript can employ here.
\begin{itemize}
 \item OpenMP -- the more efficient of the two [thread level parallelism].
 \item MPI -- Uses multiple processes (less efficient), needs less help from
   the compiler (not supported on Windows).
\end{itemize}

Escript is primarily tested on recent versions of the GNU and Intel suites
(``g++'' / ``icpc''), and Microsoft Visual C++ (MSVC).  However, it also passes
our tests when compiled using ``clang++''.  Escript now requires compiler
support for some features of the C++11 standard.  See
Appendix~\ref{app:cxxfeatures} for a list.


Our current test compilers include:
\begin{itemize}
 \item g++ 8
 \item clang++ 7
 \item intel icpc v17
 \item MSVC 2017 or 2019
\end{itemize}

Note that:
\begin{itemize}
 \item OpenMP will not function correctly for g++ $\leq$ 4.2.1 (and is not currently supported by clang).
 \item icpc v11 has a subtle bug involving OpenMP and C++ exception handling, so this combination should not be used.
\end{itemize}

\subsection{What parallel technology do I need?}\label{sec:needpar} If you are
using any version of Linux released in the past few years, then your system
compiler will support \openmp with no extra work (and give better performance);
so you should use it. MSVC 2017 and 2019 also have \openmp support on Windows
(\openmp 2.0). You will not need MPI unless your computer is some form of
cluster. MPI is not recommended on Windows as it will interfer with Jupyter.

If you are using BSD or MacOSX and you are just experimenting with \escript, then performance is
probably not a major issue for you at the moment so you don't need to use either \openmp or MPI.
This also applies if you write and polish your scripts on your computer and then send them to a cluster to execute.
If in the future you find escript useful and your scripts take significant time to run, then you may want to recompile
\escript with more options.



Note that even if your version of \escript has support for \openmp or MPI, you will still need to tell the system to
use it when you run your scripts.
If you are using the \texttt{run-escript} launcher, then this is controlled by
the \texttt{-t}, \texttt{-p}, and \texttt{-n} flags.
If not, then consult the documentation for your MPI libraries (or the compiler documentation in the case of OpenMP
\footnote{It may be enough to set the \texttt{OMP\_NUM\_THREADS} environment variable.}).

If you are using MacOSX, then see the next section, if not, then skip to Section~\ref{sec:build}.

\section{MacOS}
This release of \escript has only been tested on OSX 10.13.
For this section we assume you are using either \texttt{homebrew} or \texttt{MacPorts} as a package
manager\footnote{Note that package managers will make changes to your computer based on programs configured by other people from
various places around the internet. It is important to satisfy yourself as to the security of those systems.}.
You can of course install prerequisite software in other ways.
For example, we have had \emph{some} success changing the default
compilers used by those systems. However this is more complicated and we do not provide a guide here.

\noindent Both of those systems require the XCode command line tools to be installed\footnote{As of OSX10.9, the
command \texttt{xcode-select --install} will allow you to download and install the commandline tools.}.

\section{Building}\label{sec:build}

\esfinley is built using \textit{SCons}. To simplify the installation process, we have prepared \textit{SCons} \textit{_options.py} files for a number of common systems\footnote{These are correct a time of writing but later versions of those systems may require tweaks.
Also, these systems represent a cross section of possible platforms rather than meaning those systems get particular support.}.
The options files are located in the \textit{scons/templates} directory. We suggest that the file most relevant to your OS
be copied from the templates directory to the scons directory and renamed to the form XXXX_options.py where XXXX
should be replaced with your computer's (host-)name.
If your particular system is not in the list below, or if you want a more customised
build,
see Section~\ref{sec:othersrc} for instructions.
\begin{itemize}
 \item Debian - \ref{sec:debsrc}
 \item Ubuntu - \ref{sec:ubsrc}
 \item OpenSuse - \ref{sec:susesrc}
 \item Centos - \ref{sec:centossrc}
 \item Fedora - \ref{sec:fedorasrc}
 \item MacOS (macports) - \ref{sec:macportsrc}
 \item MacOS (homebrew) - \ref{sec:homebrewsrc}
 \item FreeBSD - \ref{sec:freebsdsrc}
 \item Windows - \ref{sec:windowssrc}
\end{itemize}

Once these are done proceed to Section~\ref{sec:cleanup} for cleanup steps.

\noindent All of these instructions assume that you have obtained the \escript source (and uncompressed it if necessary).
\subsection{Debian}\label{sec:debsrc}
\noindent These instructions were prepared on Debian 10 \textit{Buster}.

\noindent As a preliminary step, you should install the dependencies that \esfinley requires from the repository.
If you intend to use Python 2.7, then you should install the following
\begin{shellCode}
sudo apt-get install python-dev python-numpy python-pyproj python-gdal
sudo apt-get install python-sympy python-matplotlib python-scipy
sudo apt-get install libboost-python-dev libboost-random-dev
sudo apt-get install libnetcdf-dev libnetcdf-cxx-legacy-dev libnetcdf-c++4-dev
sudo apt-get install scons lsb-release libsuitesparse-dev gmsh
\end{shellCode}

\noindent If you intend to use Python 3.0+, then you should install the following
\begin{shellCode}
sudo apt-get install python3-dev python3-numpy python3-pyproj python3-gdal
sudo apt-get install python3-sympy python3-matplotlib python3-scipy
sudo apt-get install libboost-python-dev libboost-random-dev
sudo apt-get install libnetcdf-dev libnetcdf-cxx-legacy-dev libnetcdf-c++4-dev
sudo apt-get install libsuitesparse-dev scons lsb-release gmsh
\end{shellCode}

\noindent In the source directory execute the following (substitute \textit{buster_py2} or \textit{buster_py3} for XXXX):
\begin{shellCode}
scons -j1 options_file=scons/templates/XXXX_options.py
\end{shellCode}

\noindent If you wish to test your build, you can use the following:
\begin{shellCode}
scons -j1 py_tests options_file=scons/templates/XXXX_options.py
\end{shellCode}

% \begin{optionalstep}
% If for some reason, you wish to rebuild the documentation, you would also need the following:
% \begin{shellCode}
% sudo aptitude install python-sphinx doxygen python-docutils texlive
% sudo aptitude install zip texlive-latex-extra latex-xcolor
% \end{shellCode}
% \end{optionalstep}

\subsection{Ubuntu}\label{sec:ubsrc}
These instructions were prepared on Ubuntu 20.04 LTS \textit{Focal Fossa}. \newline


\noindent As a preliminary step, you should install the dependencies that \esfinley requires from the repository.
% If you intend to use Python 2.7, then you should install the following packages:
% \begin{shellCode}
% sudo apt-get install python-dev python-numpy python-pyproj python-gdal
% sudo apt-get install python-sympy python-matplotlib python-scipy
% sudo apt-get install libnetcdf-cxx-legacy-dev libnetcdf-c++4-dev libnetcdf-dev
% sudo apt-get install libboost-random-dev libboost-python-dev libboost-iostreams-dev
% sudo apt-get install scons lsb-release libsuitesparse-dev
% \end{shellCode}

For Python 3.0+, you should instead install the following packages:
\begin{shellCode}
sudo apt-get install python3-dev python3-numpy python3-pyproj python3-gdal
sudo apt-get install python3-sympy python3-matplotlib python3-scipy
sudo apt-get install libnetcdf-cxx-legacy-dev libnetcdf-c++4-dev libnetcdf-dev
sudo apt-get install libboost-random-dev libboost-python-dev libboost-iostreams-dev
sudo apt-get install scons lsb-release libsuitesparse-dev
\end{shellCode}

% \begin{optionalstep}
% If for some reason, you wish to rebuild the documentation, you would also need the following:
% \begin{shellCode}
% sudo aptitude install python-sphinx doxygen python-docutils texlive
% sudo aptitude install zip texlive-latex-extra latex-xcolor
% \end{shellCode}
% \end{optionalstep}

% \noindent Then navigate to the source directory and execute the following (substitute \textit{focus_py2} or \textit{focus_py3} as appropriate for XXXX):
% \begin{shellCode}
% scons -j1 options_file=scons/templates/XXXX_options.py
% \end{shellCode}

\noindent Then navigate to the source directory and execute the following 
\begin{shellCode}
scons -j1 options_file=scons/templates/focus_options.py
\end{shellCode}

% \noindent If you wish to test your build, you can use the following:
% \begin{shellCode}
% scons -j1 py_tests options_file=scons/templates/XXXX_options.py
% \end{shellCode}



\subsection{OpenSuse}\label{sec:susesrc}
These instructions were prepared using OpenSUSE Leap 15.2. \newline

\noindent As a preliminary step, you should install the dependencies that \esfinley requires from the repository.
\noindent  If you intend to use Python 2.7, then you should install the following packages
\begin{shellCode}
sudo zypper in python-devel python2-numpy python-gdal
sudo zypper in python2-scipy python2-sympy python2-matplotlib
sudo zypper in gcc gcc-c++ scons netcdf-devel libnetcdf_c++-devel
sudo zypper in libboost_python-py2_7-1_66_0-devel libboost_numpy-py2_7-1_66_0-devel
sudo zypper in libboost_iostreams1_66_0-devel suitesparse-devel
\end{shellCode}

\noindent If you intend to use Python 3.0, then you should instead install the following packages
\begin{shellCode}
sudo zypper in python3-devel python3-numpy python3-GDAL
sudo zypper in python3-scipy python3-sympy python3-matplotlib
sudo zypper in gcc gcc-c++ scons netcdf-devel libnetcdf_c++-devel
sudo zypper in libboost_python-py3-1_66_0-devel libboost_numpy-py3-1_66_0-devel
sudo zypper in libboost_random1_66_0-devel libboost_iostreams1_66_0-devel
sudo zypper in suitesparse-devel
\end{shellCode}

\noindent Now to build escript itself.
\noindent In the escript source directory execute the following (substitute \textit{opensuse_py2} or \textit{opensuse_py3} as appropriate for XXXX):
\begin{shellCode}
scons -j1 options_file=scons/templates/XXXX_options.py
\end{shellCode}

\noindent If you wish to test your build, you can use the following:
\begin{shellCode}
scons -j1 py_tests options_file=scons/templates/XXXX_options.py
\end{shellCode}

\noindent Now go to Section~\ref{sec:cleanup} for cleanup.

\subsection{CentOS}\label{sec:centossrc}
It is possible to install \escript on both CentOS releases $7$ and $8$. We include separate instructions for each of these CentOS releases in this section.
\subsubsection{CentOS release $7$}
The core of escript works, however some functionality is not available because the default packages for some dependencies in CentOS are too old.
At present, it is not possible to compile \escript using Python 3.0+ on CentOS $7$ as Python 3.0+ versions of many of the dependencies are not currently available in any of the CentOS repositories, but this may change in the future. 
In this section we only outline how to install a version of \escript that uses Python 2.7.

\noindent First, add the \texttt{EPEL} repository.
\begin{shellCode}
yum install epel-release.noarch
\end{shellCode}

\noindent Install packages:
\begin{shellCode}
yum install netcdf-devel netcdf-cxx-devel gdal-python
yum install python-devel numpy scipy sympy python2-scons
yum install python-matplotlib gcc gcc-c++ boost-devel
yum install boost-python gdal-devel suitesparse-devel pyproj
\end{shellCode}

\noindent Now to build escript itself.
In the escript source directory:
\begin{shellCode}
scons -j1 options_file=scons/templates/centos7_0_options.py
\end{shellCode}

\noindent Now go to Section~\ref{sec:cleanup} for cleanup.

\subsubsection{CentOS release $8$}
The core of escript works in CentOS $8$, however some functionality is not available because the default packages for some dependencies in CentOS are too old. This install is for Python 3.

First, add the EPEL, PowerTools and Okay repositories:
\begin{shellCode}
yum update
yum install epel-release.noarch dnf-plugins-core
yum config-manager --set-enabled PowerTools
rpm -ivh http://repo.okay.com.mx/centos/8/x86_64/release/okay-release-1-3.el8.noarch.rpm
yum update
\end{shellCode}

Now, install the packages:
\begin{shellCode}
yum install python3-devel python3-numpy python3-scipy python3-pyproj
yum install boost-devel boost-python3 boost-python3-devel
yum install gcc gcc-c++ scons
yum install suitesparse suitesparse-devel 
\end{shellCode}

Finally, you can compile \escript with the command
\begin{shellCode}
scons -j1 options_file=scons/templates/centos8_0_options.py
\end{shellCode}

\subsection{Fedora}\label{sec:fedorasrc}
These instructions were prepared using Fedora $31$ Workstation.

\noindent To build the a version of \escript that uses Python 2.7, install the following packages:
\begin{shellCode}
yum install gcc-c++ scons suitesparse-devel
yum install python2-devel boost-python2-devel
yum install python2-scipy
yum install netcdf-devel netcdf-cxx-devel netcdf-cxx4-devel
\end{shellCode}

\noindent To build the a version of \escript that uses Python 3.0+, install the following packages:
\begin{shellCode}
yum install gcc-c++ scons suitesparse-devel
yum install python3-devel boost-python3-devel
yum install python3-scipy python3-pyproj python3-matplotlib
yum install netcdf-devel netcdf-cxx-devel netcdf-cxx4-devel
\end{shellCode}

\noindent In the source directory execute the following (substitute \textit{fedora_py2} or \textit{fedora_py3} for XXXX):
\begin{shellCode}
scons -j1 options_file=scons/templates/XXXX_options.py
\end{shellCode}

\noindent Now go to Section~\ref{sec:cleanup} for cleanup.

\subsection{MacOS 10.10 and later (macports)}\label{sec:macportsrc}

The following will install the capabilities needed for the \texttt{macports_10.10_options.py} file (later versions can use the same options file).

\begin{shellCode}
sudo port install scons
sudo port select --set python python27
sudo port install boost
sudo port install py27-numpy
sudo port install py27-sympy
sudo port select --set py-sympy py27-sympy
sudo port install py27-scipy
sudo port install py27-pyproj
sudo port install py27-gdal
sudo port install netcdf-cxx
sudo port install silo
\end{shellCode}

\begin{shellCode}
scons -j1 options_file=scons/templates/macports_10.10options.py
\end{shellCode}


\subsection{MacOS 10.13 and later (homebrew)}\label{sec:homebrewsrc}

The following will install the capabilities needed for the \texttt{homebrew_10.13_options.py} file.

\begin{shellCode}
brew install scons
brew install boost-python
brew install netcdf
\end{shellCode}

There do not appear to be formulae for \texttt{sympy} or \texttt{pyproj} so if you wish to use those features, then
you will need to install them separately.


\begin{shellCode}
scons -j1 options_file=scons/templates/homebrew_10.13_options.py
\end{shellCode}


\subsection{FreeBSD}\label{sec:freebsdsrc}

At time of writing, \texttt{numpy} does not install correctly on FreeBSD.
Since \texttt{numpy} is a critical dependency for \escript, we have been unable to test on FreeBSD.

\begin{comment}
\subsubsection{Release 10.0}

Install the following packages:
\begin{itemize}
 \item python
 \item scons
 \item boost-python-libs
 \item bash
 \item netcdf
 \item silo
 \item py27-scipy
 \item py27-gdal
 \item py27-matplotlib
 \item py27-pyproj
 \item py27-sympy
\end{itemize}

\noindent Next choose (or create) your options file.
For the setup as above the escript source comes with a prepared file in
\texttt{scons/templates/freebsd10.0_options.py}.
Finally to build escript issue the following in the escript source directory
(replace the options file as required):
\begin{shellCode}
scons -j1 options_file=scons/templates/freebsd10.0_options.py
\end{shellCode}

\emph{Note:} Some packages installed above are built with gcc 4.7. Somewhere
in the toolchain a system-installed gcc library is pulled in which is
incompatible with the one from version 4.7 and would prevent escript from
executing successfully. As explained in the FreeBSD
documentation\footnote{see \url{http://www.freebsd.org/doc/en/articles/custom-gcc/article.html}}
this can be fixed by adding a line to \texttt{/etc/libmap.conf}:
\begin{shellCode}
libgcc_s.so.1 gcc47/libgcc_s.so.1
\end{shellCode}

\end{comment}
\subsection{Windows}\label{sec:windowssrc}

\noindent These instructions were prepared for Microsoft Windows 10.

\noindent Start by installing \escript dependencies.

\begin{itemize}
\item Microsoft Visual Studio
\begin{enumerate}
\item Download the Microsoft Visual Studio Community 2017 (or VS 2019 if
preferred) installer from
\begin{itemize}
\item[] \url{https://visualstudio.microsoft.com}.
\end{itemize}
\item Launch the Visual Studio installer, selecting Individual components:
\begin{itemize}
\item VS 2017: \textbf{VC++ 2017 latest v141 tools} \\
VS 2019: \textbf{MSVC v142 - VS 2019 C++ build tools}
\item \textbf{Windows 10 SDK}
\end{itemize}
\end{enumerate}
\item Anaconda
\begin{enumerate}
\item Download the Python 3.7 64-Bit Graphical Installer for Windows from
\begin{itemize}
\item[] \url{https://anaconda.org/}.
\end{itemize}
\item Launch the Anaconda installer, selecting installation type: \textbf{Just
Me} and destination folder: \newline \verb!C:\Users\%USERNAME%\Anaconda3!.
\end{enumerate}
\end{itemize}

\noindent Next, open Windows Command Prompt (\file{cmd.exe}) and set-up the
\escript dependencies.

\begin{itemize}
\item Conda environment
\begin{enumerate}
\item Create and activate a new environment
\begin{shellCode}
C:\Users\%USERNAME%\Anaconda3\Scripts\activate
conda create --name escript python=3.7
conda deactivate
C:\Users\%USERNAME%\Anaconda3\Scripts\activate escript
\end{shellCode}
\item Install required conda modules
\begin{shellCode}
conda install numpy==1.15.4 matplotlib==2.2.2 sympy==1.1.1
    boost gdal git pyproj scons scipy m2-patch mumps gmsh
    -c defaults -c conda-forge
\end{shellCode}
\end{enumerate}
\item Vcpkg
\begin{enumerate}
\item Build vcpkg package manager
\begin{shellCode}
cd C:\Users\%USERNAME%
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
bootstrap-vcpkg
\end{shellCode}
\item Install the CppUnit vcpkg package
\begin{shellCode}
vcpkg install cppunit:x64-windows
\end{shellCode}
\end{enumerate}
\end{itemize}

\noindent Once the dependencies are installed and set-up, you can download and
build \escript from source.

\begin{enumerate}
\item Activate the conda environment (if not active).
\begin{shellCode}
C:\Users\%USERNAME%\Anaconda3\Scripts\activate escript
\end{shellCode}
\item Set-up the Command Prompt for the 64-bit MSVC command line build environment.
\begin{shellCode}
"C:\Program Files (x86)\Microsoft Visual Studio\2017\
    Community\VC\Auxiliary\Build\vcvars64.bat"
\end{shellCode}
\item Add CppUnit to the Windows System Path.
\begin{shellCode}
set PATH=%PATH%;C:\Users\%USERNAME%\vcpkg\packages\cppunit_x64-windows\bin
\end{shellCode}
\item Download the \escript source code tarball from
\begin{itemize}
\item[] \url{https://launchpad.net/escript-finley}
\end{itemize}
Extract the tarball to \verb!C:\Users\%USERNAME%\escript!
\item Build and install the netCDF-4 C++ library before starting the \escript
build.  Download the netCDF-4 C++ v4.3.1 source code tarball from
\begin{itemize}
\item[] \url{https://github.com/Unidata/netcdf-cxx4/archive/v4.3.1.tar.gz}
\end{itemize}
Extract the tarball to \verb!C:\Users\%USERNAME%\escript!
\item Apply the provided patch.
\begin{shellCode}
cd C:\Users\%USERNAME%\escript\netcdf-cxx4-4.3.1
patch -p1 < ..\src\tools\anaconda\Anaconda3\netcdf-cxx4.patch
\end{shellCode}
\item Configure, build, and install netcdf-cxx4.
\begin{shellCode}
mkdir build
cd build
cmake -G "Visual Studio 15 2017 Win64" -DBUILD_SHARED_LIBS=OFF
    -DCMAKE_INSTALL_PREFIX="%CONDA_PREFIX%\Library"
    -DCMAKE_LIBRARY_PATH="%CONDA_PREFIX%\Library\lib"
    -DCMAKE_PREFIX_PATH="%CONDA_PREFIX%\Library"
    -DNETCDF_LIB_NAME="netcdf" -DHDF5_LIB_NAME="hdf5" ..
cmake --build . --config Release
cmake --build . --config Release --target install
\end{shellCode}
\item Kick-off the \escript build when the netCDF-4 C++ install is complete.
\begin{shellCode}
cd C:\Users\%USERNAME%\escript\src
scons -j1 build_full options_file=scons/templates/windows_msvc141_options.py
\end{shellCode}
\item Once the build completes successfully, you can validate \escript using
the provided test script.
\begin{shellCode}
python utest.py C:\Users\%USERNAME%\escript\src\build -t8
\end{shellCode}
\end{enumerate}

\subsection{Other Systems / Custom Builds}\label{sec:othersrc}

\escript has support for a number of optional packages.
Some, like \texttt{netcdf} need to be enabled at compile time, while others, such as \texttt{sympy} and the projection packages
used in \downunder are checked at run time.
For the second type, you can install them at any time (ensuring that python can find them) and they should work.
For the first type, you need to modify the options file and recompile with scons.
The rest of this section deals with this.

To avoid having to specify the options file each time you run scons, copy an existing \texttt{_options.py} file from the
\texttt{scons/} or \texttt{scons/templates/} directories. Put the file in the \texttt{scons} directory and name
it \textit{yourmachinename}\texttt{_options.py}.\footnote{If the name
has - or other non-alpha characters, they must be replaced with underscores in the filename}.
For example: on a machine named toybox, the file would be \texttt{scons/toybox_options.py}.

Individual lines can be enabled/disabled, by removing or adding \# (the python comment character) to the beginning of the line.
For example, to enable OpenMP, change the line
\begin{verbatim}
#openmp = True
\end{verbatim}
to
\begin{verbatim}
openmp = True
\end{verbatim}

If you are using libraries which are not installed in the standard places (or have different names) you will need to
change the relevant lines.
A common need for this would be using a more recent version of the boost::python library.
You can also change the compiler or the options passed to it by modifying the relevant lines.

\subsubsection*{MPI}
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}
configuration variable.
You will also need to ensure that the \texttt{mpi_prefix} and \texttt{mpi_libs} variables are uncommented and set correctly.
To disable MPI use, \verb|mpi = 'none'|.


\subsubsection{Testing}
As indicated earlier, you can test your build using \texttt{scons py_tests}.
Note however, that some features like \texttt{netCDF} are optional for using \escript, the tests will report a failure if
they are missing.

\section{Cleaning up}
\label{sec:cleanup}

Once the build (and optional testing) is complete, you can remove everything except:
\begin{itemize}
 \item bin
 \item esys
 \item lib
 \item doc
 \item CREDITS
 \item LICENSE
 \item README
\end{itemize}
The last three aren't strictly required for operation.
The \texttt{doc} directory is not required either but does contain examples of escript scripts.

You can run escript using \texttt{\textit{path_to_escript_files}/bin/run-escript}.\\
Where \texttt{\textit{path_to_escript_files}} is replaced with the real path.

\begin{optionalstep}
You can add the escript \texttt{bin} directory to your \texttt{PATH} variable.
The launcher will then take care of the rest of the environment.
\end{optionalstep}

\section{Optional Extras}

Some other packages which might be useful include:
\begin{itemize}
 \item Lapack and UMFPACK --- direct solvers (install the relevant libraries and enable them in the options file).
 \item support for the Silo file format (install the relevant libraries and enable them in the options file).
 \item VisIt --- visualisation package. Can be used independently but our \texttt{weipa} library can make a Visit
plug-in to allow direct visualisation of escript simulations.
 \item gmsh --- meshing software used by our \texttt{pycad} library.
 \item Mayavi2 --- another visualisation tool.
\end{itemize}


\subsection{Trilinos}
\escript now has some support for Trilinos\footnote{\url{https://trilinos.org/}}
solvers and preconditioners.
The most significant limitation is that the current Trilinos release does not
support block matrices so \escript can only use Trilinos solvers for single
PDEs (i.e. no PDE systems).

If your distribution does not provide Trilinos packages you can build a working
version from source. (See Appendix~\ref{app:trilinos})


\section{Testing \escript}\label{chap:utest}

\escript has extensive testing that can be used to confirm that the program is working correctly. To run the unit testing, compile \escript with the flag \texttt{build_full}. This will build \escript normally and then create a shell script named \texttt{utest.sh}. Once this file has been created, you can run unit testing using the command
\begin{shellCode}
sh utest.sh path_to_build_folder '-tT -nN -pP'
\end{shellCode}
where \texttt{T}, \texttt{N} and \texttt{P} represent the number of threads, nodes and processes to run the testing on. Some of these terms can be omitted. For example, to run the testing in serial, you would run
\begin{shellCode}
sh utest.sh path_to_build_folder '-t1'
\end{shellCode}

Note that a careless selection of these parameters may cause the testing program to skip many of the tests. For example, if you compile \escript with OpenMP enabled but then instruct the testing program to run on a single thread, many of the OpenMP tests will not be run.
