12 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
13 


14 


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

\label{CHAPTER ON FINLEY} 

16 


17 
\begin{figure} 
\begin{figure} 
18 
\centerline{\includegraphics[width=\figwidth]{FinleyMesh}} 
\centerline{\includegraphics[width=\figwidth]{FinleyMesh}} 
30 
finite elements} 
finite elements} 
31 


32 
{\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 differential equations 
33 
\index{partial differential equations} (PDEs) or systems of PDEs using isoparametrical finite 
\index{partial differential equations} (PDEs) or systems of PDEs using isoparametrical finite 
34 
elements \index{FEM!isoparametrical}. 
elements \index{FEM!isoparametrical}. 
35 
It supports unstructured, 1D, 2D and 3D meshes. The module \finley provides an access to the 
It supports unstructured, 1D, 2D and 3D meshes. The module \finley provides an access to the 
36 
library through the \LinearPDE class of \escript supporting its full functionality. {\it finley} 
library through the \LinearPDE class of \escript supporting its full functionality. {\it finley} 
37 
is parallelized using the OpenMP \index{OpenMP} paradigm. 
is parallelized using the OpenMP \index{OpenMP} paradigm. 
38 


39 
\section{Formulation} 
\section{Formulation} 
40 


43 
\begin{equation}\label{FINLEY.SINGLE.1} 
\begin{equation}\label{FINLEY.SINGLE.1} 
44 
\begin{array}{cl} & 
\begin{array}{cl} & 
45 
\displaystyle{ 
\displaystyle{ 
46 
\int\hackscore{\Omega} 
\int\hackscore{\Omega} 
47 
A\hackscore{jl} \cdot v\hackscore{,j}u\hackscore{,l}+ B\hackscore{j} \cdot v\hackscore{,j} u+ C\hackscore{l} \cdot v u\hackscore{,l}+D \cdot vu \; d\Omega } \\ 
A\hackscore{jl} \cdot v\hackscore{,j}u\hackscore{,l}+ B\hackscore{j} \cdot v\hackscore{,j} u+ C\hackscore{l} \cdot v u\hackscore{,l}+D \cdot vu \; d\Omega } \\ 
48 
+ & \displaystyle{\int\hackscore{\Gamma} d \cdot vu \; d{\Gamma} } 
+ & \displaystyle{\int\hackscore{\Gamma} d \cdot vu \; d{\Gamma} } 
49 
+ \displaystyle{\int\hackscore{\Gamma^{contact}} d^{contact} \cdot [v][u] \; d{\Gamma} } \\ 
+ \displaystyle{\int\hackscore{\Gamma^{contact}} d^{contact} \cdot [v][u] \; d{\Gamma} } \\ 
50 
= & \displaystyle{\int\hackscore{\Omega} X\hackscore{j} \cdot v\hackscore{,j}+ Y \cdot v \; d\Omega }\\ 
= & \displaystyle{\int\hackscore{\Omega} X\hackscore{j} \cdot v\hackscore{,j}+ Y \cdot v \; d\Omega }\\ 
51 
+ & \displaystyle{\int\hackscore{\Gamma} y \cdot v \; d{\Gamma}} + 
+ & \displaystyle{\int\hackscore{\Gamma} y \cdot v \; d{\Gamma}} + 
52 
\displaystyle{\int\hackscore{\Gamma^{contact}} y^{contact}\cdot [v] \; d{\Gamma}} \\ 
\displaystyle{\int\hackscore{\Gamma^{contact}} y^{contact}\cdot [v] \; d{\Gamma}} \\ 
53 
\end{array} 
\end{array} 
54 
\end{equation} 
\end{equation} 
57 
\label{FINLEY MESHES} 
\label{FINLEY MESHES} 
58 
To understand the usage of \finley one needs to have an understanding of how the finite element meshes 
To understand the usage of \finley one needs to have an understanding of how the finite element meshes 
59 
\index{FEM!mesh} are defined. \fig{FINLEY FIG 0} shows an example of the 
\index{FEM!mesh} are defined. \fig{FINLEY FIG 0} shows an example of the 
60 
subdivision of an ellipse into so called elements \index{FEM!elements} \index{element}. 
subdivision of an ellipse into so called elements \index{FEM!elements} \index{element}. 
61 
In this case, triangles have been used but other forms of subdivisions 
In this case, triangles have been used but other forms of subdivisions 
62 
can be constructed, e.g. into quadrilaterals or, in the three dimensional case, into tetrahedrons 
can be constructed, e.g. into quadrilaterals or, in the three dimensional case, into tetrahedrons 
63 
and hexahedrons. The idea of the finite element method is to approximate the solution by a function 
and hexahedrons. The idea of the finite element method is to approximate the solution by a function 
65 
In the example of \fig{FINLEY FIG 0} a linear polynomial is used on each triangle. As one can see, the triangulation 
In the example of \fig{FINLEY FIG 0} a linear polynomial is used on each triangle. As one can see, the triangulation 
66 
is quite a poor approximation of the ellipse. It can be improved by introducing a midpoint on each element edge then 
is quite a poor approximation of the ellipse. It can be improved by introducing a midpoint on each element edge then 
67 
positioning those nodes located on an edge expected to describe the boundary, onto the boundary. 
positioning those nodes located on an edge expected to describe the boundary, onto the boundary. 
68 
In this case the triangle gets a curved edge which requires a parameterization of the triangle using a 
In this case the triangle gets a curved edge which requires a parameterization of the triangle using a 
69 
quadratic polynomial. For this case, the solution is also approximated by a piecewise quadratic polynomial 
quadratic polynomial. For this case, the solution is also approximated by a piecewise quadratic polynomial 
70 
(which explains the name isoparametrical elements), see \Ref{Zienc,NumHand} for more details. 
(which explains the name isoparametrical elements), see \Ref{Zienc,NumHand} for more details. 
71 
\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. 
\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. 
72 


73 
The union of all elements defines the domain of the PDE. 
The union of all elements defines the domain of the PDE. 
74 
Each element is defined by the nodes used to describe its shape. In \fig{FINLEY FIG 0} the element, 
Each element is defined by the nodes used to describe its shape. In \fig{FINLEY FIG 0} the element, 
75 
which has type \finleyelement{Tri3}, 
which has type \finleyelement{Tri3}, 
76 
with element reference number $19$ \index{element!reference number} is defined by the nodes 
with element reference number $19$ \index{element!reference number} is defined by the nodes 
77 
with reference numbers $9$, $11$ and $0$ \index{node!reference number}. Notice that the order is counterclockwise. 
with reference numbers $9$, $11$ and $0$ \index{node!reference number}. Notice that the order is counterclockwise. 
78 
The coefficients of the PDE are evaluated at integration nodes with each individual element. 
The coefficients of the PDE are evaluated at integration nodes with each individual element. 
79 
For quadrilateral elements a Gauss quadrature scheme is used. In the case of triangular elements a 
For quadrilateral elements a Gauss quadrature scheme is used. In the case of triangular elements a 
80 
modified form is applied. The boundary of the domain is also subdivided into elements. \index{element!face} In \fig{FINLEY FIG 0} 
modified form is applied. The boundary of the domain is also subdivided into elements. \index{element!face} In \fig{FINLEY FIG 0} 
81 
line elements with two nodes are used. The elements are also defined by their describing nodes, e.g. 
line elements with two nodes are used. The elements are also defined by their describing nodes, e.g. 
82 
the face element reference number $20$ which has type \finleyelement{Line2} is defined by the nodes 
the face element reference number $20$ which has type \finleyelement{Line2} is defined by the nodes 
86 
surface of the domain is to be calculated rich face elements face to be used. Rich elements on a face 
surface of the domain is to be calculated rich face elements face to be used. Rich elements on a face 
87 
are identical to interior elements but with a modified order of nodes such that the 'first' face of the element aligns 
are identical to interior elements but with a modified order of nodes such that the 'first' face of the element aligns 
88 
with the surface of the domain. In \fig{FINLEY FIG 0} 
with the surface of the domain. In \fig{FINLEY FIG 0} 
89 
elements of the type \finleyelement{Tri3Face} are used. 
elements of the type \finleyelement{Tri3Face} are used. 
90 
The face element reference number $20$ as a rich face element is defined by the nodes 
The face element reference number $20$ as a rich face element is defined by the nodes 
91 
with reference numbers $11$, $0$ and $9$. Notice that the face element $20$ is identical to the 
with reference numbers $11$, $0$ and $9$. Notice that the face element $20$ is identical to the 
92 
interior element $19$ except that, in this case, the order of the node is different to align the first 
interior element $19$ except that, in this case, the order of the node is different to align the first 
96 
of an interior element or, in case of a rich face element, it must be identical to an interior element. 
of an interior element or, in case of a rich face element, it must be identical to an interior element. 
97 
If no face elements are specified 
If no face elements are specified 
98 
\finley implicitly assumes homogeneous natural boundary conditions \index{natural boundary conditions!homogeneous}, 
\finley implicitly assumes homogeneous natural boundary conditions \index{natural boundary conditions!homogeneous}, 
99 
i.e. \var{d}=$0$ and \var{y}=$0$, on the entire boundary of the domain. For 
i.e. \var{d}=$0$ and \var{y}=$0$, on the entire boundary of the domain. For 
100 
inhomogeneous natural boundary conditions \index{natural boundary conditions!inhomogeneous}, 
inhomogeneous natural boundary conditions \index{natural boundary conditions!inhomogeneous}, 
101 
the boundary must be described by face elements. 
the boundary must be described by face elements. 
102 


103 
If discontinuities of the PDE solution are considered contact elements 
If discontinuities of the PDE solution are considered contact elements 
104 
\index{element!contact}\index{contact conditions} are introduced to describe the contact region $\Gamma^{contact}$ 
\index{element!contact}\index{contact conditions} are introduced to describe the contact region $\Gamma^{contact}$ 
105 
even if $d^{contact}$ and $y^{contact}$ are zero. \fig{FINLEY FIG 01} shows a simple example of a mesh 
even if $d^{contact}$ and $y^{contact}$ are zero. \fig{FINLEY FIG 01} shows a simple example of a mesh 
106 
of rectangular elements around a contact region $\Gamma^{contact}$ \index{element!contact}. 
of rectangular elements around a contact region $\Gamma^{contact}$ \index{element!contact}. 
107 
The contact region is described by the 
The contact region is described by the 
108 
elements $4$, $3$ and $6$. Their element type is \finleyelement{Line2_Contact}. 
elements $4$, $3$ and $6$. Their element type is \finleyelement{Line2_Contact}. 
109 
The nodes $9$, $12$, $6$, $5$ define contact element $4$, where the coordinates of nodes $12$ and $5$ and 
The nodes $9$, $12$, $6$, $5$ define contact element $4$, where the coordinates of nodes $12$ and $5$ and 
110 
nodes $4$ and $6$ are identical with the idea that nodes $12$ and $9$ are located above and 
nodes $4$ and $6$ are identical with the idea that nodes $12$ and $9$ are located above and 
111 
nodes $5$ and $6$ below the contact region. 
nodes $5$ and $6$ below the contact region. 
112 
Again, the order of the nodes within an element is crucial. There is also the option of using rich elements 
Again, the order of the nodes within an element is crucial. There is also the option of using rich elements 
113 
if the gradient is to be calculated on the contact region. Similarly to the rich face elements 
if the gradient is to be calculated on the contact region. Similarly to the rich face elements 
114 
these are constructed from two interior elements by reordering the nodes such that 
these are constructed from two interior elements by reordering the nodes such that 
115 
the 'first' face of the element above and the 'first' face of the element below the 
the 'first' face of the element above and the 'first' face of the element below the 
116 
contact regions line up. The rich version of element 
contact regions line up. The rich version of element 
117 
$4$ is of type \finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$, $18$, $6$, $5$, $0$ and 
$4$ is of type \finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$, $18$, $6$, $5$, $0$ and 
118 
$2$. 
$2$. 
119 


120 


124 
the nodes within an element. 
the nodes within an element. 
125 


126 
\begin{table} 
\begin{table} 
127 
\begin{tablev}{lllll}{textrm}{interior}{face}{rich face}{contact}{rich contact} 
\centering 
128 
\linev{\finleyelement{Line2}}{\finleyelement{Point1}}{\finleyelement{Line2Face}}{\finleyelement{Point1_Contact}}{\finleyelement{Line2Face_Contact}} 
\begin{tabular}{lllll} 
129 
\linev{\finleyelement{Line3}}{\finleyelement{Point1}}{\finleyelement{Line3Face}}{\finleyelement{Point1_Contact}}{\finleyelement{Line3Face_Contact}} 
\bfseries interior & face & rich face & contact & rich contact\\ 
130 
\linev{\finleyelement{Tri3}}{\finleyelement{Line2}}{\finleyelement{Tri3Face}}{\finleyelement{Line2_Contact}}{\finleyelement{Tri3Face_Contact}} 
\hline 
131 
\linev{\finleyelement{Tri6}}{\finleyelement{Line3}}{\finleyelement{Tri6Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Tri6Face_Contact}} 
\finleyelement{Line2} & \finleyelement{Point1} & \finleyelement{Line2Face} & \finleyelement{Point1_Contact} & \finleyelement{Line2Face_Contact}\\ 
132 
\linev{\finleyelement{Rec4}}{\finleyelement{Line2}}{\finleyelement{Rec4Face}}{\finleyelement{Line2_Contact}}{\finleyelement{Rec4Face_Contact}} 
\finleyelement{Line3} & \finleyelement{Point1} & \finleyelement{Line3Face} & \finleyelement{Point1_Contact} & \finleyelement{Line3Face_Contact}\\ 
133 
\linev{\finleyelement{Rec8}}{\finleyelement{Line3}}{\finleyelement{Rec8Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Rec8Face_Contact}} 
\finleyelement{Tri3} & \finleyelement{Line2} & \finleyelement{Tri3Face} & \finleyelement{Line2_Contact} & \finleyelement{Tri3Face_Contact}\\ 
134 
\linev{\finleyelement{Rec9}}{\finleyelement{Line3}}{\finleyelement{Rec9Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Rec9Face_Contact}} 
\finleyelement{Tri6} & \finleyelement{Line3} & \finleyelement{Tri6Face} & \finleyelement{Line3_Contact} & \finleyelement{Tri6Face_Contact}\\ 
135 
\linev{\finleyelement{Tet4}}{\finleyelement{Tri6}}{\finleyelement{Tet4Face}}{\finleyelement{Tri6_Contact}}{\finleyelement{Tet4Face_Contact}} 
\finleyelement{Rec4} & \finleyelement{Line2} & \finleyelement{Rec4Face} & \finleyelement{Line2_Contact} & \finleyelement{Rec4Face_Contact}\\ 
136 
\linev{\finleyelement{Tet10}}{\finleyelement{Tri9}}{\finleyelement{Tet10Face}}{\finleyelement{Tri9_Contact}}{\finleyelement{Tet10Face_Contact}} 
\finleyelement{Rec8} & \finleyelement{Line3} & \finleyelement{Rec8Face} & \finleyelement{Line3_Contact} & \finleyelement{Rec8Face_Contact}\\ 
137 
\linev{\finleyelement{Hex8}}{\finleyelement{Rec4}}{\finleyelement{Hex8Face}}{\finleyelement{Rec4_Contact}}{\finleyelement{Hex8Face_Contact}} 
\finleyelement{Rec9} & \finleyelement{Line3} & \finleyelement{Rec9Face} & \finleyelement{Line3_Contact} & \finleyelement{Rec9Face_Contact}\\ 
138 
\linev{\finleyelement{Hex20}}{\finleyelement{Rec8}}{\finleyelement{Hex20Face}}{\finleyelement{Rec8_Contact}}{\finleyelement{Hex20Face_Contact}} 
\finleyelement{Tet4} & \finleyelement{Tri6} & \finleyelement{Tet4Face} & \finleyelement{Tri6_Contact} & \finleyelement{Tet4Face_Contact}\\ 
139 
\linev{\finleyelement{Hex27}}{\finleyelement{Rec9}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A} 
\finleyelement{Tet10} & \finleyelement{Tri9} & \finleyelement{Tet10Face} & \finleyelement{Tri9_Contact} & \finleyelement{Tet10Face_Contact}\\ 
140 
\linev{\finleyelement{Hex27Macro}}{\finleyelement{Rec9Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A} 
\finleyelement{Hex8} & \finleyelement{Rec4} & \finleyelement{Hex8Face} & \finleyelement{Rec4_Contact} & \finleyelement{Hex8Face_Contact}\\ 
141 
\linev{\finleyelement{Tet10Macro}}{\finleyelement{Tri6Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A} 
\finleyelement{Hex20} & \finleyelement{Rec8} & \finleyelement{Hex20Face} & \finleyelement{Rec8_Contact} & \finleyelement{Hex20Face_Contact}\\ 
142 
\linev{\finleyelement{Rec9Macro}}{\finleyelement{Line3Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A} 
\finleyelement{Hex27} & \finleyelement{Rec9} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\ 
143 
\linev{\finleyelement{Tri6Macro}}{\finleyelement{Line3Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A} 
\finleyelement{Hex27Macro} & \finleyelement{Rec9Macro} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\ 
144 
\end{tablev} 
\finleyelement{Tet10Macro} & \finleyelement{Tri6Macro} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\ 
145 

\finleyelement{Rec9Macro} & \finleyelement{Line3Macro} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\ 
146 

\finleyelement{Tri6Macro} & \finleyelement{Line3Macro} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\ 
147 

\end{tabular} 
148 
\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 and contacts. 
149 
The rich types have to be used if the gradient of function is to be calculated on faces and contacts, respectively.} 
The rich types have to be used if the gradient of function is to be calculated on faces and contacts, respectively.} 
150 
\label{FINLEY TAB 1} 
\label{FINLEY TAB 1} 
157 
\var{Node_DOF[i]} is chosen differently, see example below. The tag can be used to mark nodes sharing 
\var{Node_DOF[i]} is chosen differently, see example below. The tag can be used to mark nodes sharing 
158 
the same properties. Element \var{i} is defined by the \var{Element_numNodes} nodes \var{Element_Nodes[i]} 
the same properties. Element \var{i} is defined by the \var{Element_numNodes} nodes \var{Element_Nodes[i]} 
159 
which is a list of node reference numbers. The order is crucial. 
which is a list of node reference numbers. The order is crucial. 
160 
It has a reference number \var{Element_ref[i]} and a tag \var{Element_tag[i]}. The tag 
It has a reference number \var{Element_ref[i]} and a tag \var{Element_tag[i]}. The tag 
161 
can be used to mark elements sharing the same properties. For instance elements above 
can be used to mark elements sharing the same properties. For instance elements above 
162 
a contact region are marked with $2$ and elements below a contact region are marked with $1$. 
a contact region are marked with $2$ and elements below a contact region are marked with $1$. 
163 
\var{Element_Type} and \var{Element_Num} give the element type and the number of elements in the mesh. 
\var{Element_Type} and \var{Element_Num} give the element type and the number of elements in the mesh. 
164 
Analogue notations are used for face and contact elements. The following Python script 
Analogue notations are used for face and contact elements. The following Python script 
165 
prints the mesh definition in the \finley file format: 
prints the mesh definition in the \finley file format: 
167 
print "%s\n"%mesh_name 
print "%s\n"%mesh_name 
168 
# node coordinates: 
# node coordinates: 
169 
print "%dDnodes %d\n"%(dim,numNodes) 
print "%dDnodes %d\n"%(dim,numNodes) 
170 
for i in range(numNodes): 
for i in range(numNodes): 
171 
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]) 
172 
for j in range(dim): print " %e"%Node[i][j] 
for j in range(dim): print " %e"%Node[i][j] 
173 
print "\n" 
print "\n" 
240 
It allows identification of nodes even if they have different physical locations. For instance, to 
It allows identification of nodes even if they have different physical locations. For instance, to 
241 
enforce periodic boundary conditions at the face $x_0=0$ and $x_0=1$ one identifies 
enforce periodic boundary conditions at the face $x_0=0$ and $x_0=1$ one identifies 
242 
the degrees of freedom for nodes $0$, $5$, $12$ and $16$ with the degrees of freedom for 
the degrees of freedom for nodes $0$, $5$, $12$ and $16$ with the degrees of freedom for 
243 
$7$, $10$, $15$ and $20$, respectively. The node section of the \finley mesh gets now the form: 
$7$, $10$, $15$ and $20$, respectively. The node section of the \finley mesh gets now the form: 
244 
\begin{verbatim} 
\begin{verbatim} 
245 
2D Nodes 16 
2D Nodes 16 
246 
0 0 0 0. 0. 
0 0 0 0. 0. 
277 
\section{Macro Elements} 
\section{Macro Elements} 
278 
\label{SEC FINLEY MACRO} 
\label{SEC FINLEY MACRO} 
279 
\finley supports the usage of macro elements~\index{macro elements} which can be used to 
\finley supports the usage of macro elements~\index{macro elements} which can be used to 
280 
achieve LBB compliance when solving incompressible fluid flow problems. LBB compliance is required to 
achieve LBB compliance when solving incompressible fluid flow problems. LBB compliance is required to 
281 
get a problem which has a unique solution for pressure and velocity. For macro elements the 
get a problem which has a unique solution for pressure and velocity. For macro elements the 
282 
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 
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 
283 
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 
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 
284 
one uses a linear approximation of the velocity together with a linear approximation of the pressure but on elements 
one uses a linear approximation of the velocity together with a linear approximation of the pressure but on elements 
285 
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 
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 
286 
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. 
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. 
287 
Typically macro elements are only required to use when an incompressible fluid flow problem 
Typically macro elements are only required to use when an incompressible fluid flow problem 
288 
is solved, e.g the Stokes problem in Section \ref{STOKES PROBLEM}. Please see Section~\ref{FINLEY MESHES} for 
is solved, e.g the Stokes problem in Section \ref{STOKES PROBLEM}. Please see Section~\ref{FINLEY MESHES} for 
289 
more details on the supported macro elements. 
more details on the supported macro elements. 
290 


291 


292 


306 
\end{tabular} 
\end{tabular} 
307 
} 
} 
308 
\caption{Solvers available for 
\caption{Solvers available for 
309 
\finley 
\finley 
310 
and the \PASO package and the relevant options in \class{SolverOptions}. 
and the \PASO package and the relevant options in \class{SolverOptions}. 
311 
\MKL supports 
\MKL supports 
312 
\MINIMUMFILLIN 
\MINIMUMFILLIN 
313 
and 
and 
314 
\NESTEDDESCTION 
\NESTEDDESCTION 
315 
reordering. 
reordering. 
316 
Currently the \UMFPACK interface does not support any reordering. 
Currently the \UMFPACK interface does not support any reordering. 
317 
\label{TAB FINLEY SOLVER OPTIONS 1} } 
\label{TAB FINLEY SOLVER OPTIONS 1} } 
318 
\end{table} 
\end{table} 
319 


320 
\begin{table} 
\begin{table} 
321 
{\scriptsize 
{\scriptsize 
322 
\begin{tabular}{lcccccccc} 
\begin{tabular}{lcccccccc} 
323 
\member{setPreconditioner} & 
\member{setPreconditioner} & 
324 
\member{NO_PRECONDITIONER} & 
\member{NO_PRECONDITIONER} & 
325 
\member{AMG} & 
\member{AMG} & 
326 
\member{JACOBI} & 
\member{JACOBI} & 
327 
\member{GAUSS_SEIDEL}& 
\member{GAUSS_SEIDEL}& 
328 
\member{REC_ILU}& 
\member{REC_ILU}& 
329 
\member{RILU} & 
\member{RILU} & 
330 
\member{ILU0} & 
\member{ILU0} & 
332 
\hline 
\hline 
333 
status: & 
status: & 
334 
later & 
later & 
335 
later & 
later & 
336 
$\checkmark$ & 
$\checkmark$ & 
337 
$\checkmark$& 
$\checkmark$& 
338 
$\checkmark$ & 
$\checkmark$ & 
339 
later & 
later & 
340 
$\checkmark$ & 
$\checkmark$ & 
341 
later \\ 
later \\ 
342 
\hline 
\hline 
343 
\hline 
\hline 
344 
\member{setCoarsening}& 
\member{setCoarsening}& 
345 
& 
& 
346 
$\checkmark$ & 
$\checkmark$ & 
347 
& 
& 
348 
& 
& 
349 
& 
& 
350 
& 
& 
351 
& 
& 
352 
\\ 
\\ 
353 


354 


355 
\hline\member{setLevelMax}& 
\hline\member{setLevelMax}& 
356 

& 
357 

$\checkmark$ & 
358 
& 
& 
359 
$\checkmark$ & 
& 

& 


& 

360 
& 
& 
361 
& 
& 
362 
& 
& 
364 


365 
\hline\member{setCoarseningThreshold}& 
\hline\member{setCoarseningThreshold}& 
366 
& 
& 
367 
$\checkmark$ & 
$\checkmark$ & 
368 
& 
& 
369 
& 
& 
370 
& 
& 
371 
& 
& 
372 
& 
& 
374 


375 
\hline\member{setMinCoarseMatrixSize} & 
\hline\member{setMinCoarseMatrixSize} & 
376 
& 
& 
377 
$\checkmark$ & 
$\checkmark$ & 
378 
& 
& 
379 
& 
& 
380 
& 
& 
381 
& 
& 
382 
& 
& 
384 


385 
\hline\member{setNumSweeps} & 
\hline\member{setNumSweeps} & 
386 
& 
& 
387 
& 
& 
388 
$\checkmark$ & 
$\checkmark$ & 
389 
$\checkmark$ & 
$\checkmark$ & 
390 
& 
& 
391 
& 
& 
392 
& 
& 
394 


395 
\hline\member{setNumPreSweeps}& 
\hline\member{setNumPreSweeps}& 
396 
& 
& 
397 
$\checkmark$ & 
$\checkmark$ & 
398 
& 
& 
399 
& 
& 
400 
& 
& 
401 
& 
& 
402 
& 
& 
404 


405 
\hline\member{setNumPostSweeps} & 
\hline\member{setNumPostSweeps} & 
406 
& 
& 
407 
$\checkmark$ & 
$\checkmark$ & 
408 
& 
& 
409 
& 
& 
410 
& 
& 
411 
& 
& 
412 
& 
& 
414 


415 
\hline\member{setInnerTolerance}& 
\hline\member{setInnerTolerance}& 
416 
& 
& 
417 
& 
& 
418 
& 
& 
419 
& 
& 
420 
& 
& 
421 
& 
& 
422 
& 
& 
424 


425 
\hline\member{setDropTolerance}& 
\hline\member{setDropTolerance}& 
426 
& 
& 
427 
& 
& 
428 
& 
& 
429 
& 
& 
430 
& 
& 
431 
& 
& 
432 
& 
& 
434 


435 
\hline\member{setDropStorage}& 
\hline\member{setDropStorage}& 
436 
& 
& 
437 
& 
& 
438 
& 
& 
439 
& 
& 
440 
& 
& 
441 
& 
& 
442 
& 
& 
444 


445 
\hline\member{setRelaxationFactor}& 
\hline\member{setRelaxationFactor}& 
446 
& 
& 
447 
& 
& 
448 
& 
& 
449 
& 
& 
450 
& 
& 
451 
$\checkmark$ & 
$\checkmark$ & 
452 
& 
& 
454 


455 
\hline\member{adaptInnerTolerance}& 
\hline\member{adaptInnerTolerance}& 
456 
& 
& 
457 
& 
& 
458 
& 
& 
459 
& 
& 
460 
& 
& 
461 
& 
& 
462 
& 
& 
464 


465 
\hline\member{setInnerIterMax}& 
\hline\member{setInnerIterMax}& 
466 
& 
& 
467 
& 
& 
468 
& 
& 
469 
& 
& 
470 
& 
& 
471 
& 
& 
472 
& 
& 
473 
\\ 
\\ 
474 
\end{tabular} 
\end{tabular} 
475 
} 
} 
476 
\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 relevant options in \class{SolverOptions}. \label{TAB FINLEY SOLVER OPTIONS 2}} 
477 
\end{table} 
\end{table} 
478 


479 
\section{Linear Solvers in \SolverOptions} 
\section{Linear Solvers in \SolverOptions} 
480 
Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and 
Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and 
481 
Table~\ref{TAB FINLEY SOLVER OPTIONS 2} show the solvers and preconditioners supported by 
Table~\ref{TAB FINLEY SOLVER OPTIONS 2} show the solvers and preconditioners supported by 
482 
\finley through the \PASO library. Currently direct solvers are not supported under MPI. 
\finley through the \PASO library. Currently direct solvers are not supported under MPI. 
483 
By default, \finley is using the iterative solvers \PCG for symmetric and \BiCGStab for nonsymmetric problems. 
By default, \finley is using the iterative solvers \PCG for symmetric and \BiCGStab for nonsymmetric problems. 
484 
If the direct solver is selected which can be useful when solving very illposed equations 
If the direct solver is selected which can be useful when solving very illposed equations 
485 
\finley uses the \MKL \footnote{If the stiffness matrix is nonregular \MKL may return without 
\finley uses the \MKL \footnote{If the stiffness matrix is nonregular \MKL may return without 
486 
returning a proper error code. If you observe suspicious solutions when using MKL, this may cause by a noninvertible operator. } solver package. If \MKL is not available \UMFPACK is used. If \UMFPACK is not available 
returning a proper error code. If you observe suspicious solutions when using MKL, this may cause by a noninvertible operator. } solver package. If \MKL is not available \UMFPACK is used. If \UMFPACK is not available 
487 
a suitable iterative solver from the \PASO is used. 
a suitable iterative solver from the \PASO is used. 
488 


489 
\section{Functions} 
\section{Functions} 
490 
\begin{funcdesc}{ReadMesh}{fileName \optional{, \optional{integrationOrder=1}, optimize=True}} 
\begin{funcdesc}{ReadMesh}{fileName \optional{, \optional{integrationOrder=1}, optimize=True}} 
491 
creates a \Domain object form the FEM mesh defined in 
creates a \Domain object form the FEM mesh defined in 
492 
file \var{fileName}. The file must be given the \finley file format. 
file \var{fileName}. The file must be given the \finley file format. 
493 
If \var{integrationOrder} is positive, a numerical integration scheme 
If \var{integrationOrder} is positive, a numerical integration scheme 
494 
chosen which is accurate on each element up to a polynomial of 
chosen which is accurate on each element up to a polynomial of 
495 
degree \var{integrationOrder} \index{integration order}. Otherwise 
degree \var{integrationOrder} \index{integration order}. Otherwise 
496 
an appropriate integration order is chosen independently. 
an appropriate integration order is chosen independently. 
497 
By default the labeling of mesh nodes and element distribution is 
By default the labeling of mesh nodes and element distribution is 
498 
optimized. Set \var{optimize=False} to switch off relabeling and redistribution. 
optimized. Set \var{optimize=False} to switch off relabeling and redistribution. 
499 
\end{funcdesc} 
\end{funcdesc} 
500 


501 
\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}}} 
502 
creates a \Domain object form the FEM mesh defined in 
creates a \Domain object form the FEM mesh defined in 
503 
file \var{fileName}. The file must be given the \gmshextern file format. 
file \var{fileName}. The file must be given the \gmshextern file format. 
504 
If \var{integrationOrder} is positive, a numerical integration scheme 
If \var{integrationOrder} is positive, a numerical integration scheme 
505 
chosen which is accurate on each element up to a polynomial of 
chosen which is accurate on each element up to a polynomial of 
506 
degree \var{integrationOrder} \index{integration order}. Otherwise 
degree \var{integrationOrder} \index{integration order}. Otherwise 
507 
an appropriate integration order is chosen independently. 
an appropriate integration order is chosen independently. 
508 
By default the labeling of mesh nodes and element distribution is 
By default the labeling of mesh nodes and element distribution is 
509 
optimized. Set \var{optimize=False} to switch off relabeling and redistribution. 
optimized. Set \var{optimize=False} to switch off relabeling and redistribution. 
510 
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 macro elements~\index{macro elements}. 
511 
Currently \function{ReadGmsh} does not support MPI. 
Currently \function{ReadGmsh} does not support MPI. 
512 
\end{funcdesc} 
\end{funcdesc} 
513 


514 
\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}}}} 
515 
Creates a Finley \Domain from a \class{Design} object from \pycad using \gmshextern. 
Creates a Finley \Domain from a \class{Design} object from \pycad using \gmshextern. 
516 
The \class{Design} \var{design} defines the geometry. 
The \class{Design} \var{design} defines the geometry. 
517 
If \var{integrationOrder} is positive, a numerical integration scheme 
If \var{integrationOrder} is positive, a numerical integration scheme 
518 
chosen which is accurate on each element up to a polynomial of 
chosen which is accurate on each element up to a polynomial of 
520 
an appropriate integration order is chosen independently. 
an appropriate integration order is chosen independently. 
521 
Set \var{optimizeLabeling=False} to switch off relabeling and redistribution (not recommended). 
Set \var{optimizeLabeling=False} to switch off relabeling and redistribution (not recommended). 
522 
If \var{useMacroElements} is set, macro elements~\index{macro elements} are used. 
If \var{useMacroElements} is set, macro elements~\index{macro elements} are used. 
523 
Currently \function{MakeDomain} does not support MPI. 
Currently \function{MakeDomain} does not support MPI. 
524 
\end{funcdesc} 
\end{funcdesc} 
525 


526 


527 
\begin{funcdesc}{load}{fileName} 
\begin{funcdesc}{load}{fileName} 
528 
recovers a \Domain object from a dump file created by the \ 
recovers a \Domain object from a dump file created by the \ 
529 
\function{dump} method of a \Domain object defined in 
\function{dump} method of a \Domain object defined in 
530 
file \var{fileName}. 
file \var{fileName}. 
531 
\end{funcdesc} 
\end{funcdesc} 
532 


536 
Generates a \Domain object representing a two dimensional rectangle between 
Generates a \Domain object representing a two dimensional rectangle between 
537 
$(0,0)$ and $(l0,l1)$ with orthogonal edges. The rectangle is filled with 
$(0,0)$ and $(l0,l1)$ with orthogonal edges. The rectangle is filled with 
538 
\var{n0} elements along the $x_0$axis and 
\var{n0} elements along the $x_0$axis and 
539 
\var{n1} elements along the $x_1$axis. 
\var{n1} elements along the $x_1$axis. 
540 
For \var{order}=1 and \var{order}=2 
For \var{order}=1 and \var{order}=2 
541 
\finleyelement{Rec4} and 
\finleyelement{Rec4} and 
542 
\finleyelement{Rec8} are used, respectively. 
\finleyelement{Rec8} are used, respectively. 
543 
In the case of \var{useElementsOnFace}=\False, 
In the case of \var{useElementsOnFace}=\False, 
544 
\finleyelement{Line2} and 
\finleyelement{Line2} and 
545 
\finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively. 
\finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively. 
546 
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}. This option should be used when solving incompressible fluid flow problem, e.g. \class{StokesProblemCartesian}. 
547 
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 gradients 
548 
are calculated on domain faces), 
are calculated on domain faces), 
549 
\finleyelement{Rec4Face} and 
\finleyelement{Rec4Face} and 
550 
\finleyelement{Rec8Face} are used on the edges, respectively. 
\finleyelement{Rec8Face} are used on the edges, respectively. 
551 
If \var{integrationOrder} is positive, a numerical integration scheme 
If \var{integrationOrder} is positive, a numerical integration scheme 
552 
chosen which is accurate on each element up to a polynomial of 
chosen which is accurate on each element up to a polynomial of 
553 
degree \var{integrationOrder} \index{integration order}. Otherwise 
degree \var{integrationOrder} \index{integration order}. Otherwise 
565 
periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False, useMacroElements=\False, optimize=\False} 
periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False, useMacroElements=\False, optimize=\False} 
566 
Generates a \Domain object representing a three dimensional brick between 
Generates a \Domain object representing a three dimensional brick between 
567 
$(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 
568 
\var{n0} elements along the $x_0$axis, 
\var{n0} elements along the $x_0$axis, 
569 
\var{n1} elements along the $x_1$axis and 
\var{n1} elements along the $x_1$axis and 
570 
\var{n2} elements along the $x_2$axis. 
\var{n2} elements along the $x_2$axis. 
571 
For \var{order}=1 and \var{order}=2 
For \var{order}=1 and \var{order}=2 
572 
\finleyelement{Hex8} and 
\finleyelement{Hex8} and 
573 
\finleyelement{Hex20} are used, respectively. 
\finleyelement{Hex20} are used, respectively. 
574 
In the case of \var{useElementsOnFace}=\False, 
In the case of \var{useElementsOnFace}=\False, 
575 
\finleyelement{Rec4} and 
\finleyelement{Rec4} and 
576 
\finleyelement{Rec8} are used to subdivide the faces of the brick, respectively. 
\finleyelement{Rec8} are used to subdivide the faces of the brick, respectively. 
577 
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 gradients 
578 
are calculated on domain faces), 
are calculated on domain faces), 
579 
\finleyelement{Hex8Face} and 
\finleyelement{Hex8Face} and 
580 
\finleyelement{Hex20Face} are used on the brick faces, respectively. 
\finleyelement{Hex20Face} are used on the brick faces, respectively. 
581 
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}. This option should be used when solving incompressible fluid flow problem, e.g. \class{StokesProblemCartesian}. 
582 
If \var{integrationOrder} is positive, a numerical integration scheme 
If \var{integrationOrder} is positive, a numerical integration scheme 
583 
chosen which is accurate on each element up to a polynomial of 
chosen which is accurate on each element up to a polynomial of 
593 


594 
\begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e13} 
\begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e13} 
595 
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. 
596 
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 then \var{tolerance} times the 
597 
diameter of the domain are merged. The corresponding face elements are removed from the mesh. 
diameter of the domain are merged. The corresponding face elements are removed from the mesh. 
598 


599 
TODO: explain \var{safetyFactor} and show an example. 
TODO: explain \var{safetyFactor} and show an example. 
600 
\end{funcdesc} 
\end{funcdesc} 
601 


602 
\begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e13} 
\begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e13} 
603 
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. 
604 
Face elements whose nodes coordinates have difference is less then \var{tolerance} times the 
Face elements whose nodes coordinates have difference is less then \var{tolerance} times the 
605 
diameter of the domain are combined to form a contact element \index{element!contact} 
diameter of the domain are combined to form a contact element \index{element!contact} 
606 
The corresponding face elements are removed from the mesh. 
The corresponding face elements are removed from the mesh. 
607 


608 
TODO: explain \var{safetyFactor} and show an example. 
TODO: explain \var{safetyFactor} and show an example. 
609 
\end{funcdesc} 
\end{funcdesc} 