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 Vector} class}
18
19The purpose of the {\class Vector} class is mainly to deal with complex or real vector. It
20is derived from the {\class std:vector<K>} and templated by the vector type:
21\vspace{.2cm}
22\begin{lstlisting}
23template<typename K>
24class Vector : public std::vector<K>
25{
26public:
27    typedef K type_t;
28    typedef typename std::vector<K>::iterator ivk_t;
29    typedef typename std::vector<K>::const_iterator civk_t;
30    ...
31\end{lstlisting}
32\vspace{.2cm}
33As it is templated, it is also possible to deal with vector of vectors and generally vector
34of anything. But some algebraic functions no longer work.\\
35
36It offers some basic constructors and assignment function:
37\vspace{.2cm}
38\begin{lstlisting}[]{}
39Vector();                        //default constructor
40Vector(const dimen_t);           //constructor by length
41Vector(const dimen_t, const K&); //constructor by length for constant vector
42void assign(const K&);           //assign const scalar value to all entries
43Vector<K>& operator=(const K&);  //assign const scalar value to all entries
44\end{lstlisting}
45\vspace{.2cm}
46The default constructor initializes a vector of lengh 1 with a "0" value (\emph{K()}).\\
47
48One can access (both read and read/write access) to the component either by iterators ({\cmd begin()}
49and {\cmd end()}) or by index from 1 to the length:
50\vspace{.2cm}
51\begin{lstlisting}[]{}
52size_t size() const;        //overloaded size
53ivk_t begin();              //overloaded iterator begin()
54civk_t begin() const;       //overloaded const iterator begin()
55ivk_t end();                //overloaded iterator end()
56civk_t end() const;         //overloaded const iterator end()
57K  operator()(int i) const; //i-th component (i=1..n) (r)
58K& operator()(int i);       //i-th component (i=1..n) (r/w)
59\end{lstlisting}
60\vspace{.2cm}
61
62There are also generalized accessors that allow to get or set a part of vector, indices being given either by lower and upper indices or by a vector of indices:
63\vspace{.2cm}
64\begin{lstlisting}[]{}
65Vector<K> get(Number i1, Number i2) const;          //get i1->i2 components
66Vector<K> get(const std::vector<Number>& is) const; //get 'is' components
67void set(Number i1, Number i2, const std::vector<K>& vec);  //set i1->i2 components
68void set(const std::vector<Number>& is, const std::vector<K>& vec); //set 'is' components
69Vector<K> operator()(const std::vector<Number>& is) const;  //get 'is' components
70Vector<K> operator()(Number i1, Number i2) const;     //get i1->i2 components
71\end{lstlisting}
72\vspace{.2cm}
73
74Through overloaded operators, the {\class Vector} class provides the following (internal) algebraic
75operations:
76\vspace{.2cm}
77\begin{lstlisting}[]{}
78Vector<K>& operator+=(const K&); //add a scalar to current vector
79Vector<K>& operator-=(const K&); //substract a scalar to current vector
80Vector<K>& operator*=(const K&); //multiply the current vector by a scalar
81Vector<K>& operator/=(const K&); //divide the current vector by a scalar
82Vector<K>& operator+=(const Vector<K>&); //add a vector to current vector
83Vector<K>& operator-=(const Vector<K>&); //substract a vector to current vector
84\end{lstlisting}
85\vspace{.2cm}
86Note that compatibility tests are performed on such computations:
87\vspace{.2cm}
88\begin{lstlisting}[]{}
89void mismatchSize(const String&, const size_t) const;
90void divideByZero(const String&) const;
91void complexCastWarning(const String&, const dimen_t) const;
92\end{lstlisting}
93\vspace{.2cm}
94The class also provides norm computations:
95\vspace{.2cm}
96\begin{lstlisting}[]{}
97Real norminfty() const;     //sup norm
98Real norm2squared() const;  //squared quadratic norm
99Real norm2() const;         //<quadratic norm
100\end{lstlisting}
101\vspace{.2cm}
102and output facilities (templated ostream $<<$):
103\vspace{.2cm}
104\begin{lstlisting}[]{}
105void print(std::ostream& ) const;
106template<typename K>
107  std::ostream& operator<<(std::ostream&,const Vector<K>&);
108\end{lstlisting}
109\vspace{.2cm}
110Algebraic operations are defined as external templated functions (\emph{template <typename
111K>} is omitted):
112\vspace{.2cm}
113\begin{lstlisting}[]{}
114Vector<K> operator+(const Vector<K>&);                  //+U
115Vector<K> operator-(const Vector<K>&);                  //-U
116Vector<K> operator+(const Vector<K>&,const Vector<K>&); //U+V
117Vector<K> operator+(const K&, const Vector<K>&);        //x+U
118Vector<K> operator+(const Vector<K>&,const K&);         //U+x
119Vector<K> operator-(const Vector<K>&,const Vector<K>&); //U-V
120Vector<K> operator-(const K&, const Vector<K>&);        //x-U
121Vector<K> operator-(const Vector<K>&,const K&);         //U-x
122Vector<K> operator*(const K&, const Vector<K>&);        //x*U
123Vector<K> operator*(const Vector<K>&, const K&);        //U*x
124Vector<K> operator/(const Vector<K>&, const K&);        //U/x
125Vector<K> conj(const Vector<K>&);                       //conjugate(U)
126\end{lstlisting}
127\vspace{.2cm}
128Not that the conjugate function is defined for every vector of type \emph{K}; it assumes that
129the \emph{conj} function is also defined for \emph{K} value and returns a \emph{K} value.\\
130
131To insure automatic cast from real to complex (not the contrary) and particular functions related
132to complex, some template specializations are provided:
133\begin{lstlisting}[]{}
134std::ostream& operator<<(std::ostream&, const Vector<Real>&);    // real vector flux insertion
135std::ostream& operator<<(std::ostream&, const Vector<Complex>&); //complex vector flux insertion
136Vector<Complex> operator+(const Vector<Real>&, const Vector<Complex>&); //rU+cV
137Vector<Complex> operator+(const Vector<Complex>&, const Vector<Real>&); //cV+rU
138Vector<Complex> operator-(const Vector<Real>&, const Vector<Complex>&); //rU-cV
139Vector<Complex> operator-(const Vector<Complex>&, const Vector<Real>&); //cV-rU
140Vector<Complex> operator+(const Vector<Real>&, const Complex&);         //rU+cx
141Vector<Complex> operator+(const Complex&, const Vector<Real>&);         //cx+rU
142Vector<Complex> operator+(const Vector<Complex>&, const Real&);         //cU+rx
143Vector<Complex> operator+(const Real&, const Vector<Complex>&);         //rx+cU
144Vector<Complex> operator-(const Vector<Real>&, const Complex&);         //rU-cx
145Vector<Complex> operator-(const Complex&, const Vector<Real>&);         //cx-rU
146Vector<Complex> operator-(const Vector<Complex>&, const Real&);         //cU-rx
147Vector<Complex> operator-(const Real&, const Vector<Complex>&);         //rx-cU
148Vector<Complex> operator*(const Complex&, const Vector<Real>&);         //cx*rU
149Vector<Complex> operator*(const Vector<Real>&, const Complex&);         //rU*cx
150Vector<Complex> operator*(const Real&, const Vector<Complex>&);         //rx*cU
151Vector<Complex> operator*(const Vector<Complex>&, const Real&);         //cU*rx
152Vector<Complex> operator/(const Vector<Real>&, const Complex&);         //rU/cx
153Vector<Complex> operator/(const Vector<Complex>&, const Real&);         //cU/rx
154Vector<Real> real(const Vector<Complex>&);                                //real(U)
155Vector<Real> imag(const Vector<Complex>&);                                //imag(U)
156Vector<Complex> cmplx(const Vector<Real>&);
157Vector<Complex> cmplx(const Vector<Complex>&);
158\end{lstlisting}
159\vspace{.2cm}
160Note that the operations and their specializations allow all standard operations a user can
161wait from a real or complex vector. In particular, operations involving a casting from real
162to complex. On the other hand, be cautious when using a \emph{Vector$<$Vector$<$K$>>$ V} ,
163all algebraic operations involving \emph{V} and a scalar (of type K) are not supported, only
164those involving  \emph{V} and a \emph{vector<K>} are working. Besides, automatic casting from
165real to complex of vector of vectors is not supported, use the \emph{cmplx} function to convert
166to complex type.
167\vspace{.1cm}
168\begin{lstlisting}
169Vector<Vector<Complex> > cmplx(const Vector<Vector<Real> >&);
170\end{lstlisting}
171\vspace{.1cm}
172\begin{remark}
173Although the {\class Point} class also inherits from {\class std::vector} and offers similar
174algebraic computations facilities to the {\class Vector} class, it is not linked to the {\class
175Vector} class because it deals only with real vector and offers other functionalities, in particular
176comparison capabilities.
177\end{remark}\\
178
179Useful aliases hiding template syntax, are available for end users:
180\begin{lstlisting}
181typedef Vector<Real> Reals;
182typedef Vector<Complex> Complexes;
183typedef Vector<Real> RealVector;
184typedef Vector<Complex> ComplexVector;
185typedef Vector<Vector<Real> > RealVectors;
186typedef Vector<Vector<Complex> > ComplexVectors;
187\end{lstlisting}
188They are defined in \emph{users\_typedef.hpp} ({\lib init} library).
189
190\displayInfos{library=utils, header=Vector.hpp, implementation=Vector.cpp, test=test\_Vector.cpp,
191header dep=config.h}
192