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