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