 # Diff of /trunk/doc/user/finley.tex

revision 3306 by caltinay, Mon Oct 25 05:09:13 2010 UTC revision 3330 by caltinay, Mon Nov 1 04:29:09 2010 UTC
# Line 11  Line 11
11  %  %
12  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13

14  \chapter{The \finley Module}\label{CHAPTER ON FINLEY}  \chapter{The \finley Module}\label{CHAPTER ON FINLEY}

\begin{figure}
\centerline{\includegraphics[width=\figwidth]{FinleyMesh}}
\caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})}
\label{FINLEY FIG 0}
\end{figure}

\begin{figure}
\centerline{\includegraphics[width=\figwidth]{FinleyContact}}
\caption{Mesh around a contact region (\finleyelement{Rec4})}
\label{FINLEY FIG 01}
\end{figure}

15  %\declaremodule{extension}{finley}  %\declaremodule{extension}{finley}
16  %\modulesynopsis{Solving linear, steady partial differential equations using finite elements}  %\modulesynopsis{Solving linear, steady partial differential equations using finite elements}
17
18  {\it finley} is a library of C functions solving linear, steady partial differential equations  {\it finley} is a library of C functions solving linear, steady partial
19  \index{partial differential equations} (PDEs) or systems of PDEs using isoparametrical finite  differential equations\index{partial differential equations} (PDEs) or systems
20  elements \index{FEM!isoparametrical}.  of PDEs using isoparametrical finite elements\index{FEM!isoparametrical}.
21  It supports unstructured, 1D, 2D and 3D meshes. The module \finley provides an access to the  It supports unstructured 1D, 2D and 3D meshes.
22  library through the \LinearPDE class of \escript supporting its full functionality. {\it finley}  The module \finley provides access to the library through the \LinearPDE class
23  is parallelized using the OpenMP \index{OpenMP} paradigm.  of \escript supporting its full functionality.
24    {\it finley} is parallelized using the OpenMP\index{OpenMP} paradigm.
25
26  \section{Formulation}  \section{Formulation}
27    For a single PDE that has a solution with a single component the linear PDE is
28  For a single PDE with a solution with a single component the linear PDE is defined in the  defined in the following form:
following form:
29  \begin{equation}\label{FINLEY.SINGLE.1}  \begin{equation}\label{FINLEY.SINGLE.1}
30  \begin{array}{cl} &  \begin{array}{cl} &
31  \displaystyle{  \displaystyle{
# Line 55  A_{jl} \cdot v_{,j}u_{,l}+ B_{j} \cdot v Line 41  A_{jl} \cdot v_{,j}u_{,l}+ B_{j} \cdot v
41
42  \section{Meshes}  \section{Meshes}
43  \label{FINLEY MESHES}  \label{FINLEY MESHES}
To understand the usage of \finley one needs to have an understanding of how the finite element meshes
\index{FEM!mesh} are defined. \fig{FINLEY FIG 0} shows an example of the
subdivision of an ellipse into so called elements \index{FEM!elements} \index{element}.
In this case, triangles have been used but other forms of subdivisions
can be constructed, e.g. into quadrilaterals or, in the three dimensional case, into tetrahedrons
and hexahedrons. The idea of the finite element method is to approximate the solution by a function
which is a polynomial of a certain order and is continuous across it boundary to neighbor elements.
In the example of \fig{FINLEY FIG 0} a linear polynomial is used on each triangle. As one can see, the triangulation
is quite a poor approximation of the ellipse. It can be improved by introducing a midpoint on each element edge then
positioning those nodes located on an edge expected to describe the boundary, onto the boundary.
In this case the triangle gets a curved edge which requires a parameterization of the triangle using a
quadratic polynomial. For this case, the solution is also approximated by a piecewise quadratic polynomial
(which explains the name isoparametrical elements), see \Ref{Zienc,NumHand} for more details.
\finley supports macro elements\index{macro elements}. For these elements a piecewise linear approximation is used on an element which is further subdivided (in the case \finley halved). As such these elements do not provide more than a further mesh refinement but should be used in the case of incompressible flows, see \class{StokesProblemCartesian}. For these problems a linear approximation of the pressure across the element is used (use the \ReducedSolutionFS \FunctionSpace) while the refined element is used to approximate velocity. So a macro element provides a continuous pressure approximation together with a velocity approximation on a refined mesh. This approach is necessary to make sure that the  incompressible flow has a unique solution.
44
45  The union of all elements defines the domain of the PDE.  \begin{figure}
46  Each element is defined by the nodes used to describe its shape. In \fig{FINLEY FIG 0} the element,  \centerline{\includegraphics{FinleyMesh}}
47  which has type \finleyelement{Tri3},  \caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})}
48  with element reference number $19$ \index{element!reference number} is defined by the nodes  \label{FINLEY FIG 0}
49  with reference numbers $9$, $11$ and $0$ \index{node!reference number}. Notice that the order is counterclockwise.  \end{figure}
The coefficients of the PDE are evaluated at integration nodes with each individual element.
For quadrilateral elements a Gauss quadrature scheme is used. In the case of triangular elements a
modified form is applied. The boundary of the domain is also subdivided into elements. \index{element!face} In \fig{FINLEY FIG 0}
line elements with two nodes are used. The elements are also defined by their describing nodes, e.g.
the face element reference number $20$ which has type \finleyelement{Line2} is defined by the nodes
with the reference numbers $11$ and $0$. Again the order is crucial, if moving from the first
to second node the domain has to lie on the left hand side (in the case of a two dimension surface element
the domain has to lie on the left hand side when moving counterclockwise). If the gradient on the
surface of the domain is to be calculated rich face elements face to be used. Rich elements on a face
are identical to interior elements but with a modified order of nodes such that the 'first' face of the element aligns
with the surface of the domain. In \fig{FINLEY FIG 0}
elements of the type \finleyelement{Tri3Face} are used.
The face element reference number $20$ as a rich face element is defined by the nodes
with reference numbers $11$, $0$ and $9$. Notice that the face element $20$ is identical to the
interior element $19$ except that, in this case, the order of the node is different to align the first
edge of the triangle (which is the edge starting with the first node) with the boundary of the domain.

Be aware that face elements and elements in the interior of the domain must match, i.e. a face element must be the face
of an interior element or, in case of a rich face element, it must be identical to an interior element.
If no face elements are specified
\finley implicitly assumes homogeneous natural boundary conditions \index{natural boundary conditions!homogeneous},
i.e. \var{d}=$0$ and \var{y}=$0$, on the entire boundary of the domain. For
inhomogeneous natural boundary conditions \index{natural boundary conditions!inhomogeneous},
the boundary must be described by face elements.
50
51  If discontinuities of the PDE solution are considered contact elements  To understand the usage of \finley one needs to have an understanding of how
52  \index{element!contact}\index{contact conditions} are introduced to describe the contact region $\Gamma^{contact}$  the finite element meshes\index{FEM!mesh} are defined.
53  even if $d^{contact}$ and $y^{contact}$ are zero. \fig{FINLEY FIG 01} shows a simple example of a mesh  \fig{FINLEY FIG 0} shows an example of the subdivision of an ellipse into
54  of rectangular elements around a contact region $\Gamma^{contact}$ \index{element!contact}.  so-called elements\index{FEM!elements}\index{element}.
55  The contact region is described by the  In this case, triangles have been used but other forms of subdivisions can be
56  elements $4$, $3$ and $6$. Their element type is \finleyelement{Line2_Contact}.  constructed, e.g. quadrilaterals or, in the three-dimensional case, into
57  The nodes $9$, $12$, $6$, $5$ define contact element $4$, where the coordinates of nodes $12$ and $5$ and  tetrahedra and hexahedra. The idea of the finite element method is to
58  nodes $4$ and $6$ are identical with the idea that nodes $12$ and $9$ are located above and  approximate the solution by a function which is a polynomial of a certain order
59  nodes $5$ and $6$ below the contact region.  and is continuous across its boundary to neighbour elements.
60  Again, the order of the nodes within an element is crucial. There is also the option of using rich elements  In the example of \fig{FINLEY FIG 0} a linear polynomial is used on each
61  if the gradient is to be calculated on the contact region. Similarly to the rich face elements  triangle. As one can see, the triangulation is quite a poor approximation of
62  these are constructed from two interior elements by reordering the nodes such that  the ellipse. It can be improved by introducing a midpoint on each element edge
63  the 'first' face of the element above and the 'first' face of the element below the  then positioning those nodes located on an edge expected to describe the
64  contact regions line up.  The rich version of element  boundary, onto the boundary.
65  $4$ is of type \finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$, $18$, $6$, $5$, $0$ and  In this case the triangle gets a curved edge which requires a parameterization
66  $2$.  of the triangle using a quadratic polynomial.
67    For this case, the solution is also approximated by a piecewise quadratic
68    polynomial (which explains the name isoparametrical elements),
69    see \Ref{Zienc,NumHand} for more details.
70    \finley also supports macro elements\index{macro elements}.
71    For these elements a piecewise linear approximation is used on an element which
72    is further subdivided (in the case of \finley halved).
73    As such, these elements do not provide more than a further mesh refinement but
74    should be used in the case of incompressible flows, see \class{StokesProblemCartesian}.
75    For these problems a linear approximation of the pressure across the element is
76    used (use the \ReducedSolutionFS) while the refined element is used to
77    approximate velocity. So a macro element provides a continuous pressure
78    approximation together with a velocity approximation on a refined mesh.
79    This approach is necessary to make sure that the incompressible flow has a
80    unique solution.
81
82    The union of all elements defines the domain of the PDE.
83    Each element is defined by the nodes used to describe its shape.
84    In \fig{FINLEY FIG 0} the element, which has type \finleyelement{Tri3}, with
85    element reference number $19$\index{element!reference number} is defined by the
86    nodes with reference numbers $9$, $11$ and $0$\index{node!reference number}.
87    Notice that the order is counterclockwise.
88    The coefficients of the PDE are evaluated at integration nodes with each
89    individual element.
90    For quadrilateral elements a Gauss quadrature scheme is used.
91    In the case of triangular elements a modified form is applied.
92    The boundary of the domain is also subdivided into elements\index{element!face}.
93    In \fig{FINLEY FIG 0} line elements with two nodes are used.
94    The elements are also defined by their describing nodes, e.g. the face element
95    with reference number $20$, which has type \finleyelement{Line2}, is defined by
96    the nodes with the reference numbers $11$ and $0$.
97    Again the order is crucial, if moving from the first to second node the domain
98    has to lie on the left hand side (in the case of a two-dimensional surface
99    element the domain has to lie on the left hand side when moving
100    counterclockwise). If the gradient on the surface of the domain is to be
101    calculated rich face elements need to be used. Rich elements on a face are
102    identical to interior elements but with a modified order of nodes such that the
103    'first' face of the element aligns with the surface of the domain.
104    In \fig{FINLEY FIG 0} elements of the type \finleyelement{Tri3Face} are used.
105    The face element reference number $20$ as a rich face element is defined by the
106    nodes with reference numbers $11$, $0$ and $9$.
107    Notice that the face element $20$ is identical to the interior element $19$
108    except that, in this case, the order of the node is different to align the first
109    edge of the triangle (which is the edge starting with the first node) with the
110    boundary of the domain.
111
112    Be aware that face elements and elements in the interior of the domain must
113    match, i.e. a face element must be the face of an interior element or, in case
114    of a rich face element, it must be identical to an interior element.
115    If no face elements are specified \finley implicitly assumes homogeneous
116    natural boundary conditions\index{natural boundary conditions!homogeneous},
117    i.e. \var{d}=$0$ and \var{y}=$0$, on the entire boundary of the domain.
118    For inhomogeneous natural boundary conditions\index{natural boundary conditions!inhomogeneous},
119    the boundary must be described by face elements.
120
121    \begin{figure}
122    \centerline{\includegraphics{FinleyContact}}
123    \caption{Mesh around a contact region (\finleyelement{Rec4})}
124    \label{FINLEY FIG 01}
125    \end{figure}
126
127  \tab{FINLEY TAB 1} shows the interior element types and the corresponding element types to be used  If discontinuities of the PDE solution are considered, contact
128  on the face and contacts. \fig{FINLEY.FIG:1}, \fig{FINLEY.FIG:2} and \fig{FINLEY.FIG:4} show the ordering of  elements\index{element!contact}\index{contact conditions} are introduced to
129  the nodes within an element.  describe the contact region $\Gamma^{contact}$ even if $d^{contact}$ and
130    $y^{contact}$ are zero.
131    \fig{FINLEY FIG 01} shows a simple example of a mesh of rectangular elements
132    around a contact region $\Gamma^{contact}$\index{element!contact}.
133    The contact region is described by the elements $4$, $3$ and $6$.
134    Their element type is \finleyelement{Line2_Contact}.
135    The nodes $9$, $12$, $6$ and $5$ define contact element $4$, where the
136    coordinates of nodes $12$ and $5$ and nodes $4$ and $6$ are identical, with the
137    idea that nodes $12$ and $9$ are located above and nodes $5$ and $6$ below the
138    contact region.
139    Again, the order of the nodes within an element is crucial.
140    There is also the option of using rich elements if the gradient is to be
141    calculated on the contact region. Similarly to the rich face elements these
142    are constructed from two interior elements by reordering the nodes such that
143    the 'first' face of the element above and the 'first' face of the element below
144    the contact regions line up. The rich version of element $4$ is of type
145    \finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$,
146    $18$, $6$, $5$, $0$ and $2$.
147    \tab{FINLEY TAB 1} shows the interior element types and the corresponding
148    element types to be used on the face and contacts.
149    \fig{FINLEY.FIG:1}, \fig{FINLEY.FIG:2} and \fig{FINLEY.FIG:4} show the ordering
150    of the nodes within an element.
151
152  \begin{table}  \begin{table}
153  \centering  \centering
154  \begin{tabular}{l|llll}  \begin{tabular}{l|llll}
155  \bfseries interior & face & rich face & contact & rich contact\\  \textbf{interior}&\textbf{face}&\textbf{rich face}&\textbf{contact}&\textbf{rich contact}\\
156  \hline  \hline
157  \finleyelement{Line2} & \finleyelement{Point1} & \finleyelement{Line2Face} & \finleyelement{Point1_Contact} & \finleyelement{Line2Face_Contact}\\  \finleyelement{Line2} & \finleyelement{Point1} & \finleyelement{Line2Face} & \finleyelement{Point1_Contact} & \finleyelement{Line2Face_Contact}\\
158  \finleyelement{Line3} & \finleyelement{Point1} & \finleyelement{Line3Face} & \finleyelement{Point1_Contact} & \finleyelement{Line3Face_Contact}\\  \finleyelement{Line3} & \finleyelement{Point1} & \finleyelement{Line3Face} & \finleyelement{Point1_Contact} & \finleyelement{Line3Face_Contact}\\
# Line 139  the nodes within an element. Line 165  the nodes within an element.
165  \finleyelement{Tet10} & \finleyelement{Tri9} & \finleyelement{Tet10Face} & \finleyelement{Tri9_Contact} & \finleyelement{Tet10Face_Contact}\\  \finleyelement{Tet10} & \finleyelement{Tri9} & \finleyelement{Tet10Face} & \finleyelement{Tri9_Contact} & \finleyelement{Tet10Face_Contact}\\
166  \finleyelement{Hex8} & \finleyelement{Rec4} & \finleyelement{Hex8Face} & \finleyelement{Rec4_Contact} & \finleyelement{Hex8Face_Contact}\\  \finleyelement{Hex8} & \finleyelement{Rec4} & \finleyelement{Hex8Face} & \finleyelement{Rec4_Contact} & \finleyelement{Hex8Face_Contact}\\
167  \finleyelement{Hex20} & \finleyelement{Rec8} & \finleyelement{Hex20Face} & \finleyelement{Rec8_Contact} & \finleyelement{Hex20Face_Contact}\\  \finleyelement{Hex20} & \finleyelement{Rec8} & \finleyelement{Hex20Face} & \finleyelement{Rec8_Contact} & \finleyelement{Hex20Face_Contact}\\
168  \finleyelement{Hex27} & \finleyelement{Rec9} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\  \finleyelement{Hex27} & \finleyelement{Rec9} & N/A & N/A & N/A\\
169  \finleyelement{Hex27Macro} & \finleyelement{Rec9Macro} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\  \finleyelement{Hex27Macro} & \finleyelement{Rec9Macro} & N/A & N/A & N/A\\
170  \finleyelement{Tet10Macro} & \finleyelement{Tri6Macro} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\  \finleyelement{Tet10Macro} & \finleyelement{Tri6Macro} & N/A & N/A & N/A\\
171  \finleyelement{Rec9Macro} & \finleyelement{Line3Macro} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\  \finleyelement{Rec9Macro} & \finleyelement{Line3Macro} & N/A & N/A & N/A\\
172  \finleyelement{Tri6Macro} & \finleyelement{Line3Macro} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\  \finleyelement{Tri6Macro} & \finleyelement{Line3Macro} & N/A & N/A & N/A\\
173  \end{tabular}  \end{tabular}
174  \caption{Finley elements and corresponding elements to be used on domain faces and contacts.  \caption{Finley elements and corresponding elements to be used on domain faces
175  The rich types have to be used if the gradient of function is to be calculated on faces and contacts, respectively.}  and contacts.
176    The rich types have to be used if the gradient of the function is to be
177    calculated on faces and contacts, respectively.}
178  \label{FINLEY TAB 1}  \label{FINLEY TAB 1}
179  \end{table}  \end{table}
180
181  The native \finley file format is defined as follows.  The native \finley file format is defined as follows.
182  Each node \var{i} has \var{dim} spatial coordinates \var{Node[i]}, a reference number  Each node \var{i} has \var{dim} spatial coordinates \var{Node[i]}, a reference
183  \var{Node_ref[i]}, a degree of freedom \var{Node_DOF[i]} and tag \var{Node_tag[i]}.  number \var{Node_ref[i]}, a degree of freedom \var{Node_DOF[i]} and a tag
184  In most cases \var{Node_DOF[i]}=\var{Node_ref[i]} however, for periodic boundary conditions,  \var{Node_tag[i]}.
185  \var{Node_DOF[i]} is chosen differently, see example below. The tag can be used to mark nodes sharing  In most cases \var{Node_DOF[i]}=\var{Node_ref[i]} however, for periodic
186  the same properties. Element \var{i} is defined by the \var{Element_numNodes} nodes \var{Element_Nodes[i]}  boundary conditions, \var{Node_DOF[i]} is chosen differently, see example below.
187  which is a list of node reference numbers. The order is crucial.  The tag can be used to mark nodes sharing the same properties.
188  It has a reference number \var{Element_ref[i]} and a tag \var{Element_tag[i]}. The tag  Element \var{i} is defined by the \var{Element_numNodes} nodes
189  can be used to mark elements  sharing the same properties. For instance elements above  \var{Element_Nodes[i]} which is a list of node reference numbers.
190  a contact region are marked with $2$ and elements below a contact region are marked with $1$.  The order of these is crucial. Each element has a reference number
191  \var{Element_Type} and \var{Element_Num} give the element type and the number of elements in the mesh.  \var{Element_ref[i]} and a tag \var{Element_tag[i]}.
192  Analogue notations are used for face and contact elements. The following Python script  The tag can be used to mark elements sharing the same properties.
193  prints the mesh definition in the \finley file format:  For instance elements above a contact region are marked with tag $2$ and
194    elements below a contact region are marked with tag $1$.
195    \var{Element_Type} and \var{Element_Num} give the element type and the number
196    of elements in the mesh.
197    Analogue notations are used for face and contact elements.
198    The following \PYTHON script prints the mesh definition in the \finley file
199    format:
200  \begin{python}  \begin{python}
201  print "%s\n"%mesh_name    print("%s\n"%mesh_name)
202  # node coordinates:    # node coordinates:
203  print "%dD-nodes %d\n"%(dim,numNodes)    print("%dD-nodes %d\n"%(dim, numNodes))
204  for i in range(numNodes):    for i in range(numNodes):
205     print "%d %d %d"%(Node_ref[i],Node_DOF[i],Node_tag[i])       print("%d %d %d"%(Node_ref[i], Node_DOF[i], Node_tag[i]))
206     for j in range(dim): print " %e"%Node[i][j]       for j in range(dim): print(" %e"%Node[i][j])
207     print "\n"       print("\n")
208  # interior elements    # interior elements
209  print "%s %d\n"%(Element_Type,Element_Num)    print("%s %d\n"%(Element_Type, Element_Num))
210  for i in range(Element_Num):    for i in range(Element_Num):
211     print "%d %d"%(Element_ref[i],Element_tag[i])       print("%d %d"%(Element_ref[i], Element_tag[i]))
212     for j in range(Element_numNodes): print " %d"%Element_Nodes[i][j]       for j in range(Element_numNodes): print(" %d"%Element_Nodes[i][j])
213     print "\n"       print("\n")
214  # face elements    # face elements
215  print "%s %d\n"%(FaceElement_Type,FaceElement_Num)    print("%s %d\n"%(FaceElement_Type, FaceElement_Num))
216  for i in range(FaceElement_Num):    for i in range(FaceElement_Num):
217     print "%d %d"%(FaceElement_ref[i],FaceElement_tag[i])       print("%d %d"%(FaceElement_ref[i], FaceElement_tag[i]))
218     for j in range(FaceElement_numNodes): print " %d"%FaceElement_Nodes[i][j]       for j in range(FaceElement_numNodes): print(" %d"%FaceElement_Nodes[i][j])
219     print "\n"       print("\n")
220  # contact elements    # contact elements
221  print "%s %d\n"%(ContactElement_Type,ContactElement_Num)    print("%s %d\n"%(ContactElement_Type, ContactElement_Num))
222  for i in range(ContactElement_Num):    for i in range(ContactElement_Num):
223     print "%d %d"%(ContactElement_ref[i],ContactElement_tag[i])       print("%d %d"%(ContactElement_ref[i], ContactElement_tag[i]))
224     for j in range(ContactElement_numNodes): print " %d"%ContactElement_Nodes[i][j]       for j in range(ContactElement_numNodes): print(" %d"%ContactElement_Nodes[i][j])
225     print "\n"       print("\n")
226  # point sources (not supported yet)    # point sources (not supported yet)
227  write("Point1 0",face_element_type,numFaceElements)    print("Point1 0")
228  \end{python}  \end{python}
229
230  The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}:  The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}:
# Line 228  Line2_Contact 3 Line 262  Line2_Contact 3
262  Point1 0  Point1 0
263  \end{verbatim}  \end{verbatim}
264  Notice that the order in which the nodes and elements are given is arbitrary.  Notice that the order in which the nodes and elements are given is arbitrary.
265  In the case that rich contact elements are used the contact element section gets  In the case that rich contact elements are used the contact element section
266   the form  gets the form
267  \begin{verbatim}  \begin{verbatim}
268  Rec4Face_Contact 3  Rec4Face_Contact 3
269   4 0  9 12 16 18  6  5  0  2   4 0  9 12 16 18  6  5  0  2
270   3 0 13  9 18 19  8  6  2  3   3 0 13  9 18 19  8  6  2  3
271   6 0 15 13 19 20 10  8  3  7   6 0 15 13 19 20 10  8  3  7
272  \end{verbatim}  \end{verbatim}
273  Periodic boundary condition \index{boundary conditions!periodic} can be introduced by altering \var{Node_DOF}.  Periodic boundary conditions\index{boundary conditions!periodic} can be
274  It allows identification of nodes even if they have different physical locations. For instance, to  introduced by altering \var{Node_DOF}.
275  enforce periodic boundary conditions at the face $x_0=0$ and $x_0=1$ one identifies  It allows identification of nodes even if they have different physical locations.
276  the degrees of freedom for nodes $0$, $5$, $12$ and $16$ with the degrees of freedom for  For instance, to enforce periodic boundary conditions at the face $x_0=0$ and
277  $7$, $10$, $15$ and $20$, respectively. The node section of the \finley mesh gets now the form:  $x_0=1$ one identifies the degrees of freedom for nodes $0$, $5$, $12$ and $16$
278    with the degrees of freedom for $7$, $10$, $15$ and $20$, respectively.
279    The node section of the \finley mesh now reads:
280  \begin{verbatim}  \begin{verbatim}
281  2D Nodes 16  2D Nodes 16
282  0   0 0 0.   0.  0   0 0 0.   0.
# Line 265  $7$, $10$, $15$ and $20$, respectively. Line 301  $7$, $10$, $15$ and $20$, respectively.
301  \input{finleyelements}  \input{finleyelements}
302  \clearpage  \clearpage
303
304    \section{Macro Elements}
305    \label{SEC FINLEY MACRO}
306
307  \begin{figure}[th]  \begin{figure}[th]
308  \begin{center}  \begin{center}
309  \subfigure[Triangle]{\label{FINLEY MACRO TRI}\includegraphics[scale=0.25]{FinleyMacroTri}}  \includegraphics{FinleyMacroLeg}\\
310  \subfigure[Quadrilateral]{\label{FINLEY MACRO REC}\includegraphics[scale=0.25]{FinleyMacroRec}}  \subfigure[Triangle]{\label{FINLEY MACRO TRI}\includegraphics{FinleyMacroTri}}\quad
311  \includegraphics[scale=0.2]{FinleyMacroLeg}  \subfigure[Quadrilateral]{\label{FINLEY MACRO REC}\includegraphics{FinleyMacroRec}}
312  \end{center}  \end{center}
313  Macro elements in \finley.  \caption{Macro elements in \finley}
314  \end{figure}  \end{figure}
315
316  \section{Macro Elements}  \finley supports the usage of macro elements\index{macro elements} which can be
317  \label{SEC FINLEY MACRO}  used to achieve LBB compliance when solving incompressible fluid flow problems.
318  \finley supports the usage of macro elements~\index{macro elements} which can be used to  LBB compliance is required to get a problem which has a unique solution for
319  achieve LBB compliance when solving incompressible fluid flow problems. LBB compliance is required to  pressure and velocity. For macro elements the pressure and velocity are
320  get a problem which has a unique solution for pressure and velocity. For macro elements the  approximated by a polynomial of order 1 but the velocity approximation bases on
321  pressure and velocity are approximated by a polynomial of order 1 but the velocity approximation bases on a refinement of the element. The nodes of a triangle and quadrilateral element is shown in Figures~\ref{FINLEY MACRO TRI} and~\ref{FINLEY MACRO REC}, respectively. In essence, the velocity uses the same nodes like a quadratic polynomial approximation but replaces the quadratic polynomial by piecewise linear polynomials. In fact, this is the  a refinement of the elements. The nodes of a triangle and quadrilateral element
322  way \finley is defining the macro elements. In particular \finley uses the same local ordering of the nodes for the macro element as for the corresponding quadratic element. Another interpretation is that  are shown in Figures~\ref{FINLEY MACRO TRI} and~\ref{FINLEY MACRO REC},
323  one uses a linear approximation of the velocity together with a linear approximation of the pressure but on elements  respectively. In essence, the velocity uses the same nodes like a quadratic
324  created by combining elements to macro elements. Notice that the macro elements still use quadratic interpolation to represent the element and domain boundary. However, if elements have linear boundary  polynomial approximation but replaces the quadratic polynomial by piecewise
325  a macro element approximation for the velocity is equivalent to using a linear approximation on a mesh which is created through a one step, global refinement.  linear polynomials. In fact, this is the way \finley defines the macro elements.
326  Typically macro elements are only required to use when an incompressible fluid flow problem  In particular \finley uses the same local ordering of the nodes for the macro
327  is solved, e.g the Stokes problem in Section \ref{STOKES PROBLEM}. Please see Section~\ref{FINLEY MESHES} for  element as for the corresponding quadratic element. Another interpretation is
328  more details on the supported macro elements.  that one uses a linear approximation of the velocity together with a linear
329    approximation of the pressure but on elements created by combining elements to
330    macro elements. Notice that the macro elements still use quadratic
331    interpolation to represent the element and domain boundary.
332    However, if elements have linear boundaries a macro element approximation for
333    the velocity is equivalent to using a linear approximation on a mesh which is
334    created through a one-step global refinement.
335    Typically macro elements are only required to use when an incompressible fluid
336    flow problem is solved, e.g. the Stokes problem in \Sec{STOKES PROBLEM}.
337    Please see \Sec{FINLEY MESHES} for more details on the supported macro elements.
338
339    \section{Linear Solvers in \SolverOptions}
340
341    Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and
342    Table~\ref{TAB FINLEY SOLVER OPTIONS 2} show the solvers and preconditioners
343    supported by \finley through the \PASO library.
344    Currently direct solvers are not supported under \MPI.
345    By default, \finley uses the iterative solvers \PCG for symmetric and \BiCGStab
346    for non-symmetric problems.
347    If the direct solver is selected, which can be useful when solving very
348    ill-posed equations, \finley uses the \MKL\footnote{If the stiffness matrix is
349    non-regular \MKL may return without a proper error code. If you observe
350    suspicious solutions when using \MKL, this may be caused by a non-invertible
351    operator.} solver package. If \MKL is not available \UMFPACK is used.
352    If \UMFPACK is not available a suitable iterative solver from \PASO is used.
353
354  \begin{table}  \begin{table}
355    \centering
356  {\scriptsize  {\scriptsize
357  \begin{tabular}{l||c|c|c|c|c|c|c|c}  \begin{tabular}{l||c|c|c|c|c|c|c|c}
358  \member{setSolverMethod} & \member{DIRECT}& \member{PCG} & \member{GMRES} & \member{TFQMR} & \member{MINRES} & \member{PRES20} & \member{BICGSTAB} & \member{LUMPING} \\  \member{setSolverMethod} & \member{DIRECT}& \member{PCG} & \member{GMRES} & \member{TFQMR} & \member{MINRES} & \member{PRES20} & \member{BICGSTAB} & \member{LUMPING} \\
# Line 305  more details on the supported macro elem Line 367  more details on the supported macro elem
367  \hline\member{setReordering} & $\checkmark$ & & & & & & & \\  \hline\member{setReordering} & $\checkmark$ & & & & & & & \\
368  \end{tabular}  \end{tabular}
369  }  }
370  \caption{Solvers available for  \caption{Solvers available for \finley and the \PASO package and the relevant
371  \finley  options in \class{SolverOptions}.
372  and the \PASO package and the relevant options in \class{SolverOptions}.  \MKL supports \member{MINIMUM_FILL_IN}\index{linear solver!minimum fill-in ordering}\index{minimum fill-in ordering}
373  \MKL supports  and \member{NESTED_DISSECTION}\index{linear solver!nested dissection ordering}\index{nested dissection}
\MINIMUMFILLIN
and
\NESTEDDESCTION
374  reordering.  reordering.
375  Currently the \UMFPACK interface does not support any reordering.  Currently the \UMFPACK interface does not support any reordering.
376  \label{TAB FINLEY SOLVER OPTIONS 1} }  \label{TAB FINLEY SOLVER OPTIONS 1}}
377  \end{table}  \end{table}
378
379  \begin{table}  \begin{table}
380  {\scriptsize  {\scriptsize
381  \begin{tabular}{l||c|c|c|c|c|c|c|c}  \begin{tabular}{l||c|c|c|c|c|c|c|c}
382  \member{setPreconditioner} &  \member{setPreconditioner}&
383  \member{NO_PRECONDITIONER} &  \member{NO_PRECONDITIONER}&
384  \member{AMG} &  \member{AMG}&
385  \member{JACOBI} &  \member{JACOBI}&
386  \member{GAUSS_SEIDEL}&  \member{GAUSS_SEIDEL}&
387  \member{REC_ILU}&  \member{REC_ILU}&
388  \member{RILU} &  \member{RILU}&
389  \member{ILU0} &  \member{ILU0}&
390  \member{DIRECT} \\  \member{DIRECT}\\
391   \hline  \hline
392   status: &  status:&later&later&$\checkmark$&$\checkmark$&$\checkmark$&later&$\checkmark$&later\\
393  later &  \hline
394  later &  \hline
395  $\checkmark$ &  \member{setCoarsening}& &$\checkmark$& & & & & &\\
396  $\checkmark$&  \hline
397  $\checkmark$ &  \member{setLevelMax}& &$\checkmark$& & & & & &\\
398  later &  \hline
399  $\checkmark$ &  \member{setCoarseningThreshold}& &$\checkmark$& & & & & &\\
400  later \\  \hline
401  \hline  \member{setMinCoarseMatrixSize}& &$\checkmark$& & & & & &\\
402  \hline  \hline
403  \member{setCoarsening}&  \member{setNumSweeps}& & &$\checkmark$&$\checkmark$& & & &\\
404   &  \hline
405  $\checkmark$ &  \member{setNumPreSweeps}& &$\checkmark$& & & & & &\\
406  &  \hline
407  &  \member{setNumPostSweeps}& &$\checkmark$& & & & & &\\
408  &  \hline
409   &  \member{setInnerTolerance}& & & & & & & &\\
410   &  \hline
411   \\  \member{setDropTolerance}& & & & & & & &\\
412    \hline
413    \member{setDropStorage}& & & & & & & &\\
414  \hline\member{setLevelMax}&  \hline
415   &  \member{setRelaxationFactor}& & & & & &$\checkmark$& &\\
416  $\checkmark$ &  \hline
417   &  \member{adaptInnerTolerance}& & & & & & & &\\
418  &  \hline
419  &  \member{setInnerIterMax}& & & & & & & &\\
&
&
\\

\hline\member{setCoarseningThreshold}&
&
$\checkmark$ &
&
&
&
&
&
\\

\hline\member{setMinCoarseMatrixSize} &
&
$\checkmark$ &
&
&
&
&
&
\\

\hline\member{setNumSweeps} &
&
&
$\checkmark$ &
$\checkmark$ &
&
&
&
\\

\hline\member{setNumPreSweeps}&
&
$\checkmark$ &
&
&
&
&
&
\\

\hline\member{setNumPostSweeps} &
&
$\checkmark$ &
&
&
&
&
&
\\

\hline\member{setInnerTolerance}&
&
&
&
&
&
&
&
\\

\hline\member{setDropTolerance}&
&
&
&
&
&
&
&
\\

\hline\member{setDropStorage}&
&
&
&
&
&
&
&
\\

\hline\member{setRelaxationFactor}&
&
&
&
&
&
$\checkmark$  &
&
\\

&
&
&
&
&
&
&
\\

\hline\member{setInnerIterMax}&
&
&
&
&
&
&
&
\\
420  \end{tabular}  \end{tabular}
421  }  }
422  \caption{Preconditioners available for \finley and the \PASO package and the relevant options in \class{SolverOptions}. \label{TAB FINLEY SOLVER OPTIONS 2}}  \caption{Preconditioners available for \finley and the \PASO package and the
423    relevant options in \class{SolverOptions}.
424    \label{TAB FINLEY SOLVER OPTIONS 2}}
425  \end{table}  \end{table}
426
\section{Linear Solvers in \SolverOptions}
Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and
Table~\ref{TAB FINLEY SOLVER OPTIONS 2} show the solvers and preconditioners supported by
\finley through the \PASO library. Currently direct solvers are not supported under MPI.
By default, \finley is using the iterative solvers \PCG for symmetric and \BiCGStab for non-symmetric problems.
If the direct solver is selected which can be useful when solving very ill-posed equations
\finley uses the \MKL \footnote{If the stiffness matrix is non-regular \MKL may return without
returning a proper error code. If you observe suspicious solutions when using MKL, this may be caused by a non-invertible operator. } solver package. If \MKL is not available \UMFPACK is used. If \UMFPACK is not available
a suitable iterative solver from the \PASO is used.

427  \section{Functions}  \section{Functions}
428  \begin{funcdesc}{ReadMesh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True}}  \begin{funcdesc}{ReadMesh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True}}
429  creates a \Domain object form the FEM mesh defined in  creates a \Domain object from the FEM mesh defined in file \var{fileName}.
430  file \var{fileName}. The file must be given the \finley file format.  The file must be in the \finley file format.
431  If \var{integrationOrder} is positive, a numerical integration scheme  If \var{integrationOrder} is positive, a numerical integration scheme is chosen
432  chosen which is accurate on each element up to a polynomial of  which is accurate on each element up to a polynomial of degree
433  degree \var{integrationOrder} \index{integration order}. Otherwise  \var{integrationOrder}\index{integration order}.
434  an appropriate integration order is chosen independently.  Otherwise an appropriate integration order is chosen independently.
435  By default the labeling of mesh nodes and element distribution is  By default the labeling of mesh nodes and element distribution is optimized.
436  optimized. Set \var{optimize=False} to switch off relabeling and redistribution.  Set \var{optimize=False} to switch off relabeling and redistribution.
437  \end{funcdesc}  \end{funcdesc}
438
439  \begin{funcdesc}{ReadGmsh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True\optional{, useMacroElements=False}}}  \begin{funcdesc}{ReadGmsh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True\optional{, useMacroElements=False}}}
440  creates a \Domain object form the FEM mesh defined in  creates a \Domain object from the FEM mesh defined in file \var{fileName}.
441  file \var{fileName}. The file must be given the \gmshextern file format.  The file must be in the \gmshextern file format.
442  If \var{integrationOrder} is positive, a numerical integration scheme  If \var{integrationOrder} is positive, a numerical integration scheme is chosen
443  chosen which is accurate on each element up to a polynomial of  which is accurate on each element up to a polynomial of degree
444  degree \var{integrationOrder} \index{integration order}. Otherwise  \var{integrationOrder}\index{integration order}.
445  an appropriate integration order is chosen independently.  Otherwise an appropriate integration order is chosen independently.
446  By default the labeling of mesh nodes and element distribution is  By default the labeling of mesh nodes and element distribution is optimized.
447  optimized. Set \var{optimize=False} to switch off relabeling and redistribution.  Set \var{optimize=False} to switch off relabeling and redistribution.
448  If \var{useMacroElements} is set, second order elements are interpreted as macro elements~\index{macro elements}.  If \var{useMacroElements} is set, second order elements are interpreted as
449  Currently \function{ReadGmsh} does not support MPI.  macro elements\index{macro elements}.
450    Currently \function{ReadGmsh} does not support \MPI.
451  \end{funcdesc}  \end{funcdesc}
452
453  \begin{funcdesc}{MakeDomain}{design\optional{, integrationOrder=-1\optional{, optimizeLabeling=True\optional{, useMacroElements=False}}}}  \begin{funcdesc}{MakeDomain}{design\optional{, integrationOrder=-1\optional{, optimizeLabeling=True\optional{, useMacroElements=False}}}}
454  Creates a Finley \Domain from a \class{Design} object from \pycad using \gmshextern.  creates a \finley \Domain from a \pycad \class{Design} object using \gmshextern.
455  The \class{Design} \var{design} defines the geometry.  The \class{Design} \var{design} defines the geometry.
456  If \var{integrationOrder} is positive, a numerical integration scheme  If \var{integrationOrder} is positive, a numerical integration scheme is chosen
457  chosen which is accurate on each element up to a polynomial of  which is accurate on each element up to a polynomial of degree
458  degree \var{integrationOrder} \index{integration order}. Otherwise  \var{integrationOrder}\index{integration order}.
459  an appropriate integration order is chosen independently.  Otherwise an appropriate integration order is chosen independently.
460  Set \var{optimizeLabeling=False} to switch off relabeling and redistribution (not recommended).  Set \var{optimizeLabeling=False} to switch off relabeling and redistribution
461  If \var{useMacroElements} is set, macro elements~\index{macro elements} are used.  (not recommended).
462  Currently \function{MakeDomain} does not support MPI.  If \var{useMacroElements} is set, macro elements\index{macro elements} are used.
463    Currently \function{MakeDomain} does not support \MPI.
464  \end{funcdesc}  \end{funcdesc}
465

467  recovers a \Domain object from a dump file created by the \  recovers a \Domain object from a dump file \var{fileName} created by the
468  \function{dump} method of a \Domain object defined in  \function{dump} method of a \Domain object.
file \var{fileName}.
469  \end{funcdesc}  \end{funcdesc}
470

471  \begin{funcdesc}{Rectangle}{n0,n1,order=1,l0=1.,l1=1., integrationOrder=-1, \\  \begin{funcdesc}{Rectangle}{n0,n1,order=1,l0=1.,l1=1., integrationOrder=-1, \\
472    periodic0=\False, periodic1=\False, useElementsOnFace=\False, useMacroElements=\False,\\ optimize=\False}    periodic0=\False, periodic1=\False, useElementsOnFace=\False, useMacroElements=\False,\\ optimize=\False}
473  Generates a \Domain object representing a two dimensional rectangle between  generates a \Domain object representing a two-dimensional rectangle between
474  $(0,0)$ and $(l0,l1)$ with orthogonal edges. The rectangle is filled with  $(0,0)$ and $(l0,l1)$ with orthogonal edges.
475  \var{n0} elements along the $x_0$-axis and  The rectangle is filled with \var{n0} elements along the $x_0$-axis and
476  \var{n1} elements along the $x_1$-axis.  \var{n1} elements along the $x_1$-axis.
477  For \var{order}=1 and \var{order}=2  For \var{order}=1 and \var{order}=2, elements of type \finleyelement{Rec4} and
\finleyelement{Rec4} and
478  \finleyelement{Rec8} are used, respectively.  \finleyelement{Rec8} are used, respectively.
479  In the case of \var{useElementsOnFace}=\False,  In the case of \var{useElementsOnFace}=\False, \finleyelement{Line2} and
\finleyelement{Line2} and
480  \finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively.  \finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively.
481  If \var{order}=-1, \finleyelement{Rec8Macro} and \finleyelement{Line3Macro}~\index{macro elements}. This option should be used when solving incompressible fluid flow problem, e.g. \class{StokesProblemCartesian}.  If \var{order}=-1, \finleyelement{Rec8Macro} and \finleyelement{Line3Macro}\index{macro elements}
482  In the case of \var{useElementsOnFace}=\True (this option should be used if gradients  are used. This option should be used when solving incompressible fluid flow
483  are calculated on domain faces),  problems, e.g. \class{StokesProblemCartesian}.
484  \finleyelement{Rec4Face} and  In the case of \var{useElementsOnFace}=\True (this option should be used if
485    gradients are calculated on domain faces), \finleyelement{Rec4Face} and
486  \finleyelement{Rec8Face} are used on the edges, respectively.  \finleyelement{Rec8Face} are used on the edges, respectively.
487  If \var{integrationOrder} is positive, a numerical integration scheme  If \var{integrationOrder} is positive, a numerical integration scheme is chosen
488  chosen which is accurate on each element up to a polynomial of  which is accurate on each element up to a polynomial of degree
489  degree \var{integrationOrder} \index{integration order}. Otherwise  \var{integrationOrder}\index{integration order}.
490  an appropriate integration order is chosen independently. If  Otherwise an appropriate integration order is chosen independently.
491  \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions}  If \var{periodic0}=\True, periodic boundary conditions\index{periodic boundary conditions}
492  along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley  along the $x_0$-direction are enforced.
493  the value on the line $x_0=0$ will be identical to the values on $x_0=\var{l0}$.  That means for any solution of a PDE solved by \finley the values on the line
494  Correspondingly,  $x_0=0$ will be identical to the values on $x_0=\var{l0}$.
495  \var{periodic1}=\False sets periodic boundary conditions  Correspondingly, \var{periodic1}=\True sets periodic boundary conditions in the
496  in $x_1$-direction.  $x_1$-direction.
497  If \var{optimize}=\True mesh node relabeling will be attempted to reduce the computation and also ParMETIS will be used to improve the mesh partition if running on multiple CPUs with MPI.  If \var{optimize}=\True mesh node relabeling will be attempted to reduce the
498    computation and also ParMETIS will be used to improve the mesh partition if
499    running on multiple CPUs with \MPI.
500  \end{funcdesc}  \end{funcdesc}
501
502  \begin{funcdesc}{Brick}{n0,n1,n2,order=1,l0=1.,l1=1.,l2=1., integrationOrder=-1,  \begin{funcdesc}{Brick}{n0,n1,n2,order=1,l0=1.,l1=1.,l2=1., integrationOrder=-1,
503    periodic0=\False, periodic1=\False, \\ periodic2=\False, useElementsOnFace=\False, useMacroElements=\False, optimize=\False}    periodic0=\False, periodic1=\False, \\ periodic2=\False, useElementsOnFace=\False, useMacroElements=\False, optimize=\False}
504  Generates a \Domain object representing a three dimensional brick between  generates a \Domain object representing a three-dimensional brick between
505  $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with  $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with
506  \var{n0} elements along the $x_0$-axis,  \var{n0} elements along the $x_0$-axis,
507  \var{n1} elements along the $x_1$-axis and  \var{n1} elements along the $x_1$-axis and
508  \var{n2} elements along the $x_2$-axis.  \var{n2} elements along the $x_2$-axis.
509  For \var{order}=1 and \var{order}=2  For \var{order}=1 and \var{order}=2, elements of type \finleyelement{Hex8} and
\finleyelement{Hex8} and
510  \finleyelement{Hex20} are used, respectively.  \finleyelement{Hex20} are used, respectively.
511  In the case of \var{useElementsOnFace}=\False,  In the case of \var{useElementsOnFace}=\False, \finleyelement{Rec4} and
\finleyelement{Rec4} and
512  \finleyelement{Rec8} are used to subdivide the faces of the brick, respectively.  \finleyelement{Rec8} are used to subdivide the faces of the brick, respectively.
513  In the case of \var{useElementsOnFace}=\True (this option should be used if gradients  In the case of \var{useElementsOnFace}=\True (this option should be used if
514  are calculated on domain faces),  gradients are calculated on domain faces), \finleyelement{Hex8Face} and
\finleyelement{Hex8Face} and
515  \finleyelement{Hex20Face} are used on the brick faces, respectively.  \finleyelement{Hex20Face} are used on the brick faces, respectively.
516  If \var{order}=-1, \finleyelement{Hex20Macro} and \finleyelement{Rec8Macro}~\index{macro elements}. This option should be used when solving incompressible fluid flow problem, e.g. \class{StokesProblemCartesian}.  If \var{order}=-1, \finleyelement{Hex20Macro} and \finleyelement{Rec8Macro}\index{macro elements}
517  If \var{integrationOrder} is positive, a numerical integration scheme  are used. This option should be used when solving incompressible fluid flow
518  chosen which is accurate on each element up to a polynomial of  problems, e.g. \class{StokesProblemCartesian}.
519  degree \var{integrationOrder} \index{integration order}. Otherwise  If \var{integrationOrder} is positive, a numerical integration scheme is chosen
520  an appropriate integration order is chosen independently. If  which is accurate on each element up to a polynomial of degree
521  \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions}  \var{integrationOrder}\index{integration order}.
522  along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley  Otherwise an appropriate integration order is chosen independently.
523  the value on the plane $x_0=0$ will be identical to the values on $x_0=\var{l0}$. Correspondingly,  If \var{periodic0}=\True, periodic boundary conditions\index{periodic boundary conditions}
524  \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions  along the $x_0$-direction are enforced.
525  in $x_1$-direction and $x_2$-direction, respectively.  That means for any solution of a PDE solved by \finley the values on the plane
526  If \var{optimize}=\True mesh node relabeling will be attempted to reduce the computation and also ParMETIS will be used to improve the mesh partition if running on multiple CPUs with MPI.  $x_0=0$ will be identical to the values on $x_0=\var{l0}$.
527    Correspondingly, \var{periodic1}=\True and \var{periodic2}=\True sets periodic
528    boundary conditions in the $x_1$-direction and $x_2$-direction, respectively.
529    If \var{optimize}=\True mesh node relabeling will be attempted to reduce the
530    computation and also ParMETIS will be used to improve the mesh partition if
531    running on multiple CPUs with \MPI.
532  \end{funcdesc}  \end{funcdesc}
533
534  \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}  \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
535  Generates a new \Domain object from the list \var{meshList} of \finley meshes.  generates a new \Domain object from the list \var{meshList} of \finley meshes.
536  Nodes in face elements whose difference of coordinates is less then \var{tolerance} times the  Nodes in face elements whose difference of coordinates is less than
537  diameter of the domain are merged. The corresponding face elements are removed from the mesh.  \var{tolerance} times the diameter of the domain are merged.
538    The corresponding face elements are removed from the mesh.
539  TODO: explain \var{safetyFactor} and show an example.  %TODO: explain \var{safetyFactor} and show an example.
540  \end{funcdesc}  \end{funcdesc}
541
542  \begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}  \begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
543  Generates a new \Domain object from the list \var{meshList} of \finley meshes.  generates a new \Domain object from the list \var{meshList} of \finley meshes.
544  Face elements whose nodes coordinates have difference is less then \var{tolerance} times the  Face elements whose node coordinates differ by less than \var{tolerance} times
545  diameter of the domain are combined to form a contact element \index{element!contact}  the diameter of the domain are combined to form a contact element\index{element!contact}.
546  The corresponding face elements are removed from the mesh.  The corresponding face elements are removed from the mesh.
547    %TODO: explain \var{safetyFactor} and show an example.
TODO: explain \var{safetyFactor} and show an example.
548  \end{funcdesc}  \end{funcdesc}
549

Legend:
 Removed from v.3306 changed lines Added in v.3330