inputs/user/install_ext_libs.tex

%%%%%%%%%%%%%%%%%%%
% XLiFE++ is an extended library of finite elements written in C++
%     Copyright (C) 2014  Lunéville, Eric; Kielbasiewicz, Nicolas; Lafranche, Yvon; Nguyen, Manh-Ha; Chambeyron, Colin
%
%     This program is free software: you can redistribute it and/or modify
%     it under the terms of the GNU General Public License as published by
%     the Free Software Foundation, either version 3 of the License, or
%     (at your option) any later version.
%     This program is distributed in the hope that it will be useful,
%     but WITHOUT ANY WARRANTY; without even the implied warranty of
%     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%     GNU General Public License for more details.
%     You should have received a copy of the GNU General Public License
%     along with this program.  If not, see <http://www.gnu.org/licenses/>.
%%%%%%%%%%%%%%%%%%%

\section{Installation and use of \blas and \lapack libraries}\label{a.s.blas}

Using \umfpack or \arpack means using \blas and \lapack libraries. \xlifepp offers the ability to choose your \blas/\lapack installation :

\begin{itemize}
\item Using \blas/\lapack installed with \umfpack or \arpack
\item Using default \blas/\lapack installed on your computer
\item Using standard \blas/\lapack libraries, such as \openblas.
\end{itemize}

To do so, you juste have to use {\cmakeopt XLIFEPP\_LAPACK\_LIB\_DIR} and/or {\cmakeopt XLIFEPP\_BLAS\_LIB\_DIR} to set the directory containing \lapack and \blas libraries:

\begin{lstlisting}[language=]
cmake [...] -DXLIFEPP_BLAS_LIB_DIR=path/to/Blas/library/directory -DXLIFEPP_LAPACK_LIB_DIR=path/to/Lapack/library/directory path/to/CMakeLists.txt
\end{lstlisting}

\begin{remark}
It is useless to use {\cmakeopt XLIFEPP\_LAPACK\_LIB\_DIR} and/or {\cmakeopt XLIFEPP\_BLAS\_LIB\_DIR} options if you do not activates configuration with \umfpack or \arpack
\end{remark}

\section{Installation and use of \umfpack library}\label{a.s.umfpack}

The prerequisite to make use of \umfpack is to have it installed or at least its libraries are compiled. The {\lib umfpackSupport} can be linked with or without \umfpack in case of none of its functions is invoked. Otherwise, any try to use its provided functions can lead to a linkage error. Details to compile and install \umfpack can be found at \url{http://www.cise.ufl.edu/research/sparse/umfpack/}. All the steps will be described below supposing \umfpack \textbf{already installed or compiled} in the user's system. \\
In order to make use of \umfpack routines, user must configure \cmake with options: {\cmakeopt XLIFEPP\_ENABLE\_UMFPACK}, {\cmakeopt XLIFEPP\_UMFPACK\_INCLUDE\_DIR} and {\cmakeopt XLIFEPP\_UMFPACK\_LIB\_DIR}.

\vspace{.1cm}
\begin{lstlisting}[language=]
cmake  -DXLIFEPP_ENABLE_UMFPACK=ON -DXLIFEPP_UMFPACK_INCLUDE_DIR=path/to/UMFPACK/include/directory -DXLIFEPP_UMFPACK_LIB_DIR=path/to/UMFPACK/library/directory path/to/CMakeLists.txt
\end{lstlisting}
\vspace{.1cm}

\begin{remark}
Theoretically, \umfpack does not need to use \blas/\lapack, but as it is highly recommended by \umfpack (for accuracy reasons), \xlifepp demand that you use \blas/\lapack.
\end{remark}

\umfpack is provided by \suitesparse. When looking how \umfpack is compiled, it seems that it can depend (maybe in the same way as \blas/\lapack) from other libraries provided by \suitesparse.

In this case, you have a simpler way to define paths: by using {\cmakeopt XLIFEPP\_SUITESPARSE\_HOME\_DIR}. When given alone, it consider the given directory as the home directory containing every library provided by \suitesparse with a specific tree structure. If it is not the case, you can use more specific options of the form {\cmakeopt XLIFEPP\_XXX\_INCLUDE\_DIR} and {\cmakeopt XLIFEPP\_XXX\_LIB\_DIR}, where XXX can be AMD, COLAMD, CAMD, CCOLAMD, CHOLMOD, SUITESPARSECONFIG or UMFPACK.

\section{Installation and use of \arpack library}\label{a.s.arpack}

\arpack library can be obtained from the following URL: \url{http://www.caam.rice.edu/software/ARPACK/}. It requires \blas and \lapack routines, so make sure these two libraries are installed in the system. Like \arpack, these two libraries are available under some Unix-like systems.

By default, the intern eigensolver of \xlifepp is used for calculating eigenvalues and eigenvectors. To make use of \arpack instead, users must configure \cmake with options : {\cmakeopt XLIFEPP\_ENABLE\_ARPACK} and {\cmakeopt XLIFEPP\_ARPACK\_LIB\_DIR}.

The current directory is the root directory containing \xlifepp source code. To enable \arpack, we use the command:
\vspace{.1cm}
\begin{lstlisting}
cmake -DXLIFEPP_ENABLE_ARPACK=ON -DXLIFEPP_ARPACK_LIB_DIR=path/to/arpack/libraries/directory path/to/CMakeLists.txt
\end{lstlisting}
\vspace{.1cm}
After configuring, we can make the library
\vspace{.1cm}
\begin{lstlisting}
make
\end{lstlisting}
\vspace{.1cm}

\begin{remark}
\xlifepp uses the wrapper \arpackpp. Because of its deprecation, a patch at \url{http://reuter.mit.edu/index.php/software/arpackpatch/} needs to be applied to ensure a correct compilation. With the evolution of compilers, this patch is often not enough now. This is the reason why \xlifepp contains its own patched release of \arpackpp, used by default.
\end{remark}

\section{Installation of MinGW 64 bits}\label{s.mingw64}

When you download {\tt CodeBlocks}, the default compiler is MinGW 32bits. To use the full capabilities of \xlifepp, you may want to use a 64 bits compiler. 2 ways to download MinGW-W64:

\begin{itemize}
\item Download the installer from the url \url{https://downloads.sourceforge.net/project/mingw-w64/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/installer/mingw-w64-install.exe?r=&ts=1522254087&use_mirror=netcologne}. The installer
\item Download the binaries directly from the url from the \url{https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/mingw-builds/}. You select the version you need, for instance 7.3.0. You click on "threads-posix" directory, on one of the directories (sjlj, seh, \ldots). Personnally, I would choose the directory having the best download rate per week. FInally, you click on the archive to donwload it.
\end{itemize}