1%%%%%%%%%%%%%%%%%%%
2% XLiFE++ is an extended library of finite elements written in C++
3%     Copyright (C) 2014  Lunéville, Eric; Kielbasiewicz, Nicolas; Lafranche, Yvon; Nguyen, Manh-Ha; Chambeyron, Colin
4%
5%     This program is free software: you can redistribute it and/or modify
6%     it under the terms of the GNU General Public License as published by
7%     the Free Software Foundation, either version 3 of the License, or
8%     (at your option) any later version.
9%     This program is distributed in the hope that it will be useful,
10%     but WITHOUT ANY WARRANTY; without even the implied warranty of
11%     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12%     GNU General Public License for more details.
13%     You should have received a copy of the GNU General Public License
14%     along with this program.  If not, see <http://www.gnu.org/licenses/>.
15%%%%%%%%%%%%%%%%%%%
16
17\section{The computation algorithms}
18
19\subsection{Matrix computation}
20
21In this section, we explain how the computation of matrix from bilinear form works. This computation depends on the type of the  bilinear form (single integral term, double integral term, ...) and the types of unknown and test function. This section addresses only the computation of {\class SuTermMatrix}.\\
22
23The principle of computation, implemented in  \verb?SuTermMatrix::compute()?, consists in 4 steps:
24\begin{itemize}
25\item collect basic bilinear forms along their domain and their computation type (see \verb?SuTermMatrix::getSuBlfs()? function.):\\
26
27\begin{tabular}{|l|p{7cm}|p{3.5cm}|}
28\hline\verb?_FEComputation?   & single integral on a domain & u,v in FE spaces \\
29\hline\verb?_FEextComputation?   & single integral on a boundary domain with non tangential derivatives & u,v in FE spaces \\
30\hline\verb?_IEComputation?   & double integral on a domains pair & u,v in FE space, standard Kernel \\
31\hline\verb?_SPComputation?   & single integral on a domain & u,v in SP spaces \\
32\hline\verb?_FESPComputation? & single integral on a domain & one in SP space, other in FE space \\
33\hline\verb?_IESPComputation? & double integral on a domains pair & u,v in FE space, TensorKernel \\
34\hline\verb?_IEHMComputation? & double integral on a domains pair & u,v in FE space, HMatrix \\
35\hline
36\end{tabular}
37\item construct a storage consistent with all collections to compute (imposed by user or chosen between compressed sparse storage or dense storage)
38\item create {\class MatrixEntry} with the right structure and value types
39\item for each collection, call the computation function regarding its computation type
40\end{itemize}
41This last step looks like in \verb?SuTermMatrix::compute()?:
42\vspace{.1cm}
43\begin{lstlisting}[deletekeywords={[3] str}]
44if(FEsublfs.size()>0)    compute<_FEComputation>(FEsublfs, vt, str);
45if(FEextsublfs.size()>0) compute<_FEextComputation>(FEextsublfs, vt, str);
46if(SPsublfs.size()>0)    compute<_SPComputation>(SPsublfs, vt, str);
47if(FESPsublfs.size()>0)  compute<_FESPComputation>(FESPsublfs, vt, str);
48if(IEsublfs.size()>0)    compute<_IEComputation>(IEsublfs, vt, str);
49if(IESPsublfs.size()>0)  compute<_IESPComputation>(IESPsublfs, vt, str);
50\end{lstlisting}
51where all specializations of \verb?compute<unsigned int CM>? are implemented in the \textit{XXMatrixComputation.hpp} files included add the end of the \textit{SuTermMatrix.hpp} file. All the computation algorithms mainly work as follows:
52\begin{verbatim}
53retry general data (spaces, subspaces, domains, ...)
54loop on element on domain 1
55  retry element data (local to global numbering)
56  (loop on element on domain 2)     only for IE and IESP computation
57    (retry element data)
58     compute shapevalues
59     loop on basic bilinear form
60        loop on quadrature points
61           compute operator on unknowns
62          add in elementary matrix using tensorial operations
63        assembly in global matrix
64\end{verbatim}
65\vspace{.2cm}
66\begin{remark}
67For sake of simplicity, evaluation of operators returns always a \textbf{scalar vector}, even if the unknowns are vector ones. So this vector has to be correctly reinterpreted when it is added in elementary block matrix.
68\end{remark}
69
70
71When there is a HMatrix computation that requires a specific representation (HMatrixEntry), this one is achieved after all the computations requiring a MatrixEntry. Then the MatrixEntry (if it exists one) is merged in the HMatrixEntry. Obviously, anything cannot be merged to HMatrixEntry!\\
72
73For IE computation, some  specialized function are devoted to particular integration method adapted to singular kernels (Sauter-Schwab method for instance). They are implemented in particular files (\textit{SauterSchwabbIM.hpp}, \textit{LenoirSallesM.hpp},\textit{DuffyIM.hpp}),  see the \textit{src/term/computation} directory.\\
74
75Up to now, most of the computation functions have been parallelized (multi-threading with omp).
76
77\subsection{Understanding TermMatrix operations}
78The following figure sketchs out how the operations are processed in the class hierarchy from {\class TermMatrix} to storage classes that implement the compution algorithms:
79\begin{figure}[H]
80\begin{center}
81\includePict[width=14cm]{TermMatrix_Operation.png}
82\end{center}
83\caption{The process of a TermMatrix operation}
84\end{figure}
85
86\subsection{Vector computation}
87
88For the moment, the {\class SuTermVector} class provides
89\begin{itemize}
90	\item the \verb?computeFE? function that computes single integral on a FE space
91	\item the \verb?computeIR? function that computes integral representation
92\end{itemize}
93These functions are implemented in the \textit{FeVectorComputation.hpp} file included by the \textit{SuTermVector.hpp} file. It works as matrix computation but it is simpler.
94