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 {\classtitle SymbolicTermMatrix} class}
18
19Sometimes, numerical methods involve more complex combinations of {\class TermMatrix}  than linear combinations, for instance
20$ \mathbb{A}=\mathbb{M} + \mathbb{K}  \mathbb{M}^{-1}\mathbb{K}^t$  where  $\mathbb{M}$ and  $\mathbb{K}$ are sparse matrices. Generally, it is not a good idea to compute  $\mathbb{A}$ because the result is a dense matrix. The purpose of the {\class SymbolicTermMatrix} class is to describe as symbolic this matrix, not to compute it but to compute $\mathbb{A}X$ with $X$ a {\class TermVector}.\\
21A {\class SymbolicTermMatrix} object is a node of the binary tree with the following data
22\begin{itemize}
23	\item a symbolic operation (one of id, +, -,*, /, inv, tran, conj, adj )
24	\item a TermMatrix object (pointer to), may be 0
25	\item up to two SymbolicTermMatrix objects (pointer to)
26	\item a coefficient (complex scalar)  applied to the operation
27\end{itemize}
28Using these data, the symbolic form of the $ \mathbb{A}$ matrix is presented on figure \ref{fig_tree_symb_matrix}. On a node, there is either a {\class TermMatrix} (leaves) or a pair of {\class SymbolicTermMatrix}.
29\vspace{.1cm}
30\begin{figure}[H]
31	\centering
32	\includePict[width=12cm]{SymbolicTermMatrix.png}
33	\caption{ Tree representation of matrix $\mathbb{M} + \mathbb{K}  \mathbb{M}^{-1}\mathbb{K}^t$}
34	\label{fig_tree_symb_matrix}
35\end{figure}
36So the {\class SymbolicTermMatrix} class has the following data members
37\vspace{.1cm}
38\begin{lstlisting}[]{}
39class SymbolicTermMatrix
40{public:
41  SymbolicTermMatrix* st1_, *st2_;
42  const TermMatrix* tm_;
43  complex_t coef_;
44  SymbolicOperation op_;
45  bool delMat_;
46\end{lstlisting}
47\vspace{.2cm}
48the following constructors and destructor stuff
49\vspace{.1cm}
50\begin{lstlisting}[]{}
51SymbolicTermMatrix();
52SymbolicTermMatrix(const TermMatrix&, const complex_t& =complex_t(1.,0.));
53SymbolicTermMatrix(SymbolicOperation, SymbolicTermMatrix*, SymbolicTermMatrix*=0);
54SymbolicTermMatrix(LcTerm<TermMatrix>& lc);
55~SymbolicTermMatrix();
56void add(LcTerm<TermMatrix>&, std::vector<std::pair<const TermMatrix*, complex_t> >::iterator);
57SymbolicTermMatrix(const SymbolicTermMatrix&);
58SymbolicTermMatrix& operator=(const SymbolicTermMatrix&);
59\end{lstlisting}
60The {\var delMat} variable is a flag telling the TermMatrix can be deleted because one of the constructors creates a copy of the original one. \\
61
62\vspace{.1cm}
63\begin{lstlisting}[]{}
64SymbolicTermMatrix();
65SymbolicTermMatrix(const TermMatrix&, const complex_t& =complex_t(1.,0.));
66SymbolicTermMatrix(SymbolicOperation, SymbolicTermMatrix*, SymbolicTermMatrix*=0);
67SymbolicTermMatrix(LcTerm<TermMatrix>& lc);
68~SymbolicTermMatrix();
69void add(LcTerm<TermMatrix>&, std::vector<std::pair<const TermMatrix*, complex_t> >::iterator);
70SymbolicTermMatrix(const SymbolicTermMatrix&);
71SymbolicTermMatrix& operator=(const SymbolicTermMatrix&);
72\end{lstlisting}
73\vspace{.2cm}
74The class offers classic print stuff :
75\vspace{.1cm}
76\begin{lstlisting}[]{}
77string_t asString() const;
78void print(std::ostream&) const;
79void print(PrintStream& os) const {print(os.currentStream());}
80friend std::ostream& operator<<(std::ostream& ,const SymbolicTermMatrix&)
81\end{lstlisting}
82\vspace{.2cm}
83
84Besides a lot of operator are provided :
85\vspace{.1cm}
86\begin{lstlisting}[]{}
87SymbolicTermMatrix& operator *(const TermMatrix&,SymbolicTermMatrix&);
88SymbolicTermMatrix& operator *(SymbolicTermMatrix&, const TermMatrix&);
89SymbolicTermMatrix& operator +(const TermMatrix&,SymbolicTermMatrix&);
90SymbolicTermMatrix& operator +(SymbolicTermMatrix&, const TermMatrix&);
91SymbolicTermMatrix& operator -(const TermMatrix&,SymbolicTermMatrix&);
92SymbolicTermMatrix& operator -(SymbolicTermMatrix&, const TermMatrix&);
93SymbolicTermMatrix& operator +(LcTerm<TermMatrix>&,SymbolicTermMatrix&);
94SymbolicTermMatrix& operator +(SymbolicTermMatrix&, LcTerm<TermMatrix>&);
95SymbolicTermMatrix& operator -(LcTerm<TermMatrix>&,SymbolicTermMatrix&);
96SymbolicTermMatrix& operator -(SymbolicTermMatrix&, LcTerm<TermMatrix>&);
97SymbolicTermMatrix& operator *(LcTerm<TermMatrix>&,SymbolicTermMatrix&);
98SymbolicTermMatrix& operator *(SymbolicTermMatrix&, LcTerm<TermMatrix>&);
99SymbolicTermMatrix& operator *(SymbolicTermMatrix&, SymbolicTermMatrix&);
100SymbolicTermMatrix& operator +(SymbolicTermMatrix&, SymbolicTermMatrix&);
101SymbolicTermMatrix& operator -(SymbolicTermMatrix&, SymbolicTermMatrix&);
102SymbolicTermMatrix& conj(SymbolicTermMatrix&);
103SymbolicTermMatrix& adj(SymbolicTermMatrix&);
104SymbolicTermMatrix& tran(SymbolicTermMatrix&);
105SymbolicTermMatrix& operator *(SymbolicTermMatrix&, const complex_t&);
106SymbolicTermMatrix& operator *(const complex_t&, SymbolicTermMatrix&);
107SymbolicTermMatrix& operator /(SymbolicTermMatrix&, const complex_t&);
108SymbolicTermMatrix& inv(const TermMatrix&);
109SymbolicTermMatrix& inv(SymbolicTermMatrix&);
110\end{lstlisting}
111\vspace{.2cm}
112Because some syntaxes may be ambiguous,the operator \verb|~| is overloaded in order to move a {\class TermMatrix} to a {\class SymbolicTermMatrix}:
113\vspace{.1cm}
114\begin{lstlisting}[]{}
115SymbolicTermMatrix& operator~(const TermMatrix&):
116\end{lstlisting}
117\vspace{.2cm}
118The most important functions are function that compute recursively the matrix vector product $\mathbb{A}X$ :
119\vspace{.1cm}
120\begin{lstlisting}[]{}
121TermVector operator*(const SymbolicTermMatrix&, const TermVector&);
122TermVector multMatrixVector(const SymbolicTermMatrix&, const TermVector&);
123TermVector operator*(const TermVector&, const SymbolicTermMatrix&);
124TermVector multVectorMatrix(const TermVector&, const SymbolicTermMatrix&);
125\end{lstlisting}
126\vspace{.2cm}
127\displayInfos{
128	library=term,
129	header=SymbolicTermMatrix.hpp,
130	implementation=SymbolicTermMatrix.cpp,
131	test=unit\_TermMatrix.cpp,
132	header dep={TermMatrix.hpp, config.h, utils.h}
133}