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{Unknown management} 18 19\subsection{The {\classtitle Unknown} class} 20 21The {\class Unknown} class manages element of a space ({\class Space}). It is mainly used as 22an abstract object in the description of a variational problem. It has the {\class ComponentOfUnknown} 23class as child which represents a component of a vector unknown. Do not confuse vector unknown on a scalar space and scalar unknown on a vector space. Vector unknown on a scalar space is a way to define an unknown on a product of scalar spaces (same space!), for instance the displacement field. Whereas on a vector space (say a space spanned by vector functions), unknown are generaly a scalar one; for instance Hrot or Hdiv comform spaces. Up to now, it is not possible to deal with general product spaces. 24\vspace{.1cm} 25\begin{lstlisting} 26class Unknown 27{protected: 28 String name_; // name of the unknown 29 Space * space_p; // pointer to the space where the unknown lives 30 mutable bool conjugate_; // temporary flag for conjugate operation 31 Unknown * dualUnknown_; // pointer to dual Unknown (test function) 32 Number rank_; // rank to order unknowns 33 public: 34 bool isUnknown; // true if an unknown, false if a test function 35 static std::vector<Unknown*> theUnknowns; //list of all Unknowns 36\end{lstlisting} 37\vspace{.1cm} 38The temporary \verb?conjugate_? flag is used to mark in a {\class OperatorOnUnknown} construction 39that an unknown is conjugate. The static attribute \verb?theUnknowns? traces all defined unknowns. 40Besides, each unknown has a rank, by default its creation number (first unknown created has rank 1 and so on). 41This rank is used to order blocks in vector or matrix in case of multiple unknowns terms.\\ 42There is no class to deal with test function. There exists only an alias \verb?TestFunction? of {\class Unknown}: 43\vspace{.1cm} 44\begin{lstlisting}[] 45typedef Unknown TestFunction; 46\end{lstlisting} 47\vspace{.1cm} 48So, to distinguish, unknown from test function, the flag \verb?isUnknown? is used. It is set to true when using the constructor from a Space and set to false when using the constructor from unknown, implicitely the test function constructor: 49\vspace{.1cm} 50\begin{lstlisting}[] 51Unknown(); 52Unknown(const string_t&, Space&, 53 dimen_t d=1, number_t r=0);// unknown constructor from space 54Unknown(Unknown&,const string_t& na="", 55 number_t r=0); // test function constructor from unknown 56~Unknown(); 57\end{lstlisting} 58\vspace{.2cm} 59and the following accessors: 60\vspace{.1cm} 61\begin{lstlisting}[] 62String name() const; // return name 63Space * space() const; // return pointer to space 64UnknownType type() const; // return type of unknown 65StrucType strucType() const; // return the structure type of an unknown 66number_t index() const; // return index of unknown 67bool conjugate() const; // return the conjugate state flag 68bool& conjugate(); // return the conjugate state flag 69void conjugate(bool v) const ; // set the conjugate state flag 70friend Unknown& conj(Unknown &); // conjugate an unknown 71Number rank() const; // return the unknown rank 72\end{lstlisting} 73\vspace{.1cm} 74The member function \verb?index()? returns the rank of the unknown in the \verb?theUnknowns? 75list. It may be useful to order the unknowns. The member function \verb?type()? returns the 76type of unknown as an element of the UnknownType enumeration (defined in \textit{config.hpp} 77header file): 78\vspace{.1cm} 79\begin{lstlisting}[] 80enum UnknownType {_feUnknown,_spUnknown,_mixedUnknown}; 81\end{lstlisting} 82\vspace{.2cm} 83There are particular virtual member functions linked to the {\class ComponentOfUnknown} child 84class: 85\vspace{.1cm} 86\begin{lstlisting}[] 87virtual dimen_t nbOfComponents() const; // dimension of unknown 88virtual bool isComponent() const; // true if a ComponentOfUnknown 89virtual const Unknown* parent() const; // return parent (or itself) 90virtual Dimen componentIndex() const; // return component index if a ComponentOfUnknown, 0 if not 91virtual const ComponentOfUnknown* asComponent() const; // return Unknown as a ComponentOfUnknown if it is 92Unknown& operator[](dimen_t); // create the ComponentOfUnknown u_i 93\end{lstlisting} 94\vspace{.2cm} 95{\class Unknown} class provides printing facility also: 96\vspace{.1cm} 97\begin{lstlisting}[] 98friend std::ostream& operator<<(std::ostream&, const Unknown&); 99 100void setRanks(std::vector<Unknown*>&, const std::vector<Number>&); 101void setRanks(Unknown&, Number r); 102void setRanks(Unknown&, Number, Unknown&, Number); 103void setRanks(Unknown&, Number, Unknown&, Number, ...); 104\end{lstlisting} 105\vspace{.1cm} 106The \verb?setRanks? functions are useful to define the internal order of unknowns in multiple unknowns objects such as {\class TermMatrix} or {\class TermVector}. The unknown ranks have to be unique but it is not mandatory that they follow. By default, first created unknown has rank 1, the second created has rank 2, and so on. 107\vspace{.2cm} 108 109\subsection{The {\classtitle ComponentOfUnknown} class} 110 111To access to a component of a vector unknown as an unknown, the {\class ComponentOfUnknown} 112child class is provided: 113\vspace{.1cm} 114\begin{lstlisting} 115class ComponentOfUnknown: public Unknown 116{protected : 117 const Unknown * u_p; //Unknown which this unknown is a component 118 Dimen i_; //index of the component 119 public : 120 ComponentOfUnknown(const Unknown &,dimen_t); 121 virtual Dimen nbOfComponents() const; 122 virtual Dimen dimFun() const; 123 virtual bool isComponent() const; 124 virtual const Unknown* parent() const; 125 virtual Dimen componentIndex() const; 126 virtual const ComponentOfUnknown* asComponent() const; 127}; 128\end{lstlisting} 129\vspace{.1cm} 130Note that the operator \verb?Unknown::[](Dimen)? creates a \verb?ComponentOnUnknown? object 131returned as an \verb?Unknown? object. 132 133\subsection{The {\classtitle Unknowns} class} 134{\class Unknowns} is an alias of {\class PCollection<Unknown>} class that manages a collection of {\class Unknown} objects, in fact a {\var std::vector<Unknown*>}. Be cautious when using it because the Unknown pointers are shared; in particular when using temporary instance of Unknown! It is the reason why the {\class PCollectionItem} class is overloaded to protect pointer in assign syntax {\cmd sp(i)=Unknown(...)}: 135\vspace{.1cm} 136\begin{lstlisting}[] 137template<> class PCollectionItem<Unknown> 138{public: 139typename std::vector<Unknown*>::iterator itp; 140PCollectionItem(typename std::vector<Unknown*>::iterator it) : itp(it){} 141Unknown& operator = (const Unknown& sp); //protected assignment 142operator Unknown&(){return **itp;} //autocast PCollectionItem->Unknown& 143}; 144\end{lstlisting} 145\vspace{.2cm} 146Main usages of this class are the following: 147\vspace{.1cm} 148\begin{lstlisting}[] 149Unknown u1(V1,"u1"), u2(V2,"u2"), u3(V3,"u3"); 150Unknowns us1(u1,u2,u3); 151Unknowns us2; us2<<u1<<u2<<u3; 152Unknowns us5(5); 153for(Number i=1;i<=5;i++) us5(i)=Unknown(Vs5(i),"u_"+tostring(i)); 154\end{lstlisting} 155\vspace{.2cm} 156\begin{cpp11} 157If C++11 is available (the library has to be compiled in C++11), the following syntax is also working: 158\vspace{.1cm} 159\begin{lstlisting}[] 160Unknowns us={u1,u2,u3}; 161\end{lstlisting} 162\end{cpp11} 163 164\vspace{.2cm} 165In a same way, {\class TestFunctions} is an alias of {\class PCollection<TestFunction*>} class that manages a collection of {\class TestFunction} objects. It works as the {\class Unknowns} class. The following function allows to create a collection of testfunctions related to a collection of unknowns: 166\vspace{.1cm} 167\begin{lstlisting}[] 168TestFunctions dualOf(const Unknowns& us); 169\end{lstlisting} 170 171 172\displayInfos{library=space, header=Unknown.hpp, implementation=Unknown.cpp, test=test\_Space.cpp, 173header dep={config.h, utils.h}} 174