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

revision 2748 by gross, Tue Nov 17 07:32:59 2009 UTC revision 3306 by caltinay, Mon Oct 25 05:09:13 2010 UTC
# Line 1  Line 1
1
2  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3  %  %
4  % Copyright (c) 2003-2009 by University of Queensland  % Copyright (c) 2003-2010 by University of Queensland
5  % Earth Systems Science Computational Center (ESSCC)  % Earth Systems Science Computational Center (ESSCC)
6  % http://www.uq.edu.au/esscc  % http://www.uq.edu.au/esscc
7  %  %
# Line 12  Line 12
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]{figures/FinleyMesh}}  \centerline{\includegraphics[width=\figwidth]{FinleyMesh}}
19  \caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})}  \caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})}
20  \label{FINLEY FIG 0}  \label{FINLEY FIG 0}
21  \end{figure}  \end{figure}
22
23  \begin{figure}  \begin{figure}
24  \centerline{\includegraphics[width=\figwidth]{figures/FinleyContact}}  \centerline{\includegraphics[width=\figwidth]{FinleyContact}}
25  \caption{Mesh around a contact region (\finleyelement{Rec4})}  \caption{Mesh around a contact region (\finleyelement{Rec4})}
26  \label{FINLEY FIG 01}  \label{FINLEY FIG 01}
27  \end{figure}  \end{figure}
28
29  \declaremodule{extension}{finley} \modulesynopsis{Solving linear, steady partial differential equations using  %\declaremodule{extension}{finley}
30  finite elements}  %\modulesynopsis{Solving linear, steady partial differential equations using 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
# Line 44  following form: Line 43  following form:
43  \label{FINLEY.SINGLE.1}  \label{FINLEY.SINGLE.1}
44  \begin{array}{cl} &  \begin{array}{cl} &
45  \displaystyle{  \displaystyle{
46  \int\hackscore{\Omega}  \int_{\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_{jl} \cdot v_{,j}u_{,l}+ B_{j} \cdot v_{,j} u+ C_{l} \cdot v u_{,l}+D \cdot vu \; d\Omega }  \\
48  + & \displaystyle{\int\hackscore{\Gamma} d \cdot vu \; d{\Gamma} }  + & \displaystyle{\int_{\Gamma} d \cdot vu \; d{\Gamma} }
49  +  \displaystyle{\int\hackscore{\Gamma^{contact}} d^{contact} \cdot [v][u] \; d{\Gamma} } \\  +  \displaystyle{\int_{\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_{\Omega}  X_{j} \cdot v_{,j}+ Y \cdot v \; d\Omega }\\
51  + & \displaystyle{\int\hackscore{\Gamma} y \cdot v \; d{\Gamma}}  +  + & \displaystyle{\int_{\Gamma} y \cdot v \; d{\Gamma}}  +
52  \displaystyle{\int\hackscore{\Gamma^{contact}} y^{contact}\cdot [v] \; d{\Gamma}} \\  \displaystyle{\int_{\Gamma^{contact}} y^{contact}\cdot [v] \; d{\Gamma}} \\
53  \end{array}  \end{array}
54
55
56  \section{Meshes}  \section{Meshes}
57    \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
# Line 65  which is a polynomial of a certain order Line 65  which is a polynomial of a certain order
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 parametrization 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
# Line 86  the domain has to lie on the left hand s Line 86  the domain has to lie on the left hand s
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
# Line 96  Be aware that face elements and elements Line 96  Be aware that face elements and elements
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
# Line 124  on the face and contacts. \fig{FINLEY.FI Line 124  on the face and contacts. \fig{FINLEY.FI
124  the nodes within an element.  the nodes within an element.
125
126  \begin{table}  \begin{table}
127  \begin{tablev}{l|llll}{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}{l|llll}
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}
# Line 154  In most cases \var{Node_DOF[i]}=\var{Nod Line 157  In most cases \var{Node_DOF[i]}=\var{Nod
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:
# Line 164  prints the mesh definition in the \finle Line 167  prints the mesh definition in the \finle
167  print "%s\n"%mesh_name  print "%s\n"%mesh_name
168  # node coordinates:  # node coordinates:
169  print "%dD-nodes %d\n"%(dim,numNodes)  print "%dD-nodes %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"
# Line 237  Periodic boundary condition \index{bound Line 240  Periodic boundary condition \index{bound
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.
# Line 262  $7$, $10$, $15$ and $20$, respectively. Line 265  $7$, $10$, $15$ and $20$, respectively.
265  \input{finleyelements}  \input{finleyelements}
266  \clearpage  \clearpage
267
268    \begin{figure}[th]
269    \begin{center}
270    \subfigure[Triangle]{\label{FINLEY MACRO TRI}\includegraphics[scale=0.25]{FinleyMacroTri}}
272    \includegraphics[scale=0.2]{FinleyMacroLeg}
273    \end{center}
274    Macro elements in \finley.
275    \end{figure}
276
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
280    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
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
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
284    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
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.
287    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
289    more details on the supported macro elements.
290
291
292
# Line 283  $7$, $10$, $15$ and $20$, respectively. Line 306  $7$, $10$, $15$ and $20$, respectively.
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}{l||c|c|c|c|c|c|c|c}  \begin{tabular}{l||c|c|c|c|c|c|c|c}
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} &
# Line 309  Currently the \UMFPACK interface does no Line 332  Currently the \UMFPACK interface does no
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$ &  $\checkmark$ &
358   &   &
359  &  &
360  &  &
361   &   &
362   &   &
# Line 341  $\checkmark$ & Line 364  $\checkmark$ &
364
365  \hline\member{setCoarseningThreshold}&  \hline\member{setCoarseningThreshold}&
366  &  &
367  $\checkmark$ &  $\checkmark$ &
368   &   &
369  &  &
370  &  &
371   &   &
372   &   &
# Line 351  $\checkmark$ & Line 374  $\checkmark$ &
374
375  \hline\member{setMinCoarseMatrixSize} &  \hline\member{setMinCoarseMatrixSize} &
376   &   &
377  $\checkmark$ &  $\checkmark$ &
378   &   &
379  &  &
380  &  &
381   &   &
382   &   &
# Line 361  $\checkmark$ & Line 384  $\checkmark$ &
384
385  \hline\member{setNumSweeps} &  \hline\member{setNumSweeps} &
386   &   &
387   &   &
388  $\checkmark$ &  $\checkmark$ &
389  $\checkmark$ &  $\checkmark$ &
390  &  &
391   &   &
392   &   &
# Line 371  $\checkmark$ & Line 394  $\checkmark$ &
394
395  \hline\member{setNumPreSweeps}&  \hline\member{setNumPreSweeps}&
396   &   &
397  $\checkmark$ &  $\checkmark$ &
398    &    &
399   &   &
400   &   &
401    &    &
402    &    &
# Line 381  $\checkmark$ & Line 404  $\checkmark$ &
404
405  \hline\member{setNumPostSweeps} &  \hline\member{setNumPostSweeps} &
406   &   &
407  $\checkmark$ &  $\checkmark$ &
408   &   &
409  &  &
410  &  &
411   &   &
412  &  &
# Line 391  $\checkmark$ & Line 414  $\checkmark$ &
414
415  \hline\member{setInnerTolerance}&  \hline\member{setInnerTolerance}&
416   &   &
417   &   &
418   &   &
419  &  &
420  &  &
421   &   &
422  &  &
# Line 401  $\checkmark$ & Line 424  $\checkmark$ &
424
425  \hline\member{setDropTolerance}&  \hline\member{setDropTolerance}&
426   &   &
427   &   &
428   &   &
429  &  &
430  &  &
431   &   &
432  &  &
# Line 411  $\checkmark$ & Line 434  $\checkmark$ &
434
435  \hline\member{setDropStorage}&  \hline\member{setDropStorage}&
436   &   &
437   &   &
438   &   &
439  &  &
440  &  &
441   &   &
442  &  &
# Line 421  $\checkmark$ & Line 444  $\checkmark$ &
444
445  \hline\member{setRelaxationFactor}&  \hline\member{setRelaxationFactor}&
446   &   &
447   &   &
448   &   &
449  &  &
450  &  &
451  $\checkmark$  &  $\checkmark$  &
452   &   &
# Line 431  $\checkmark$  & Line 454  $\checkmark$  &
454
456   &   &
457   &   &
458   &   &
459  &  &
460  &  &
461   &   &
462  &  &
# Line 441  $\checkmark$  & Line 464  $\checkmark$  &
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  \subsection{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 non-symmetric problems.  By default, \finley is using the iterative solvers \PCG for symmetric and \BiCGStab for non-symmetric problems.
484  If the direct solver is selected which can be useful when solving very ill-posedequations  If the direct solver is selected which can be useful when solving very ill-posed equations
485  \finley uses the \MKL \footnote{If the stiffness matrix is non-regular \MKL may return without  \finley uses the \MKL \footnote{If the stiffness matrix is non-regular \MKL may return without
486  returning a proper error code. If you observe suspicious solutions when using MKL, this may cause by a non-invertible 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 be caused by a non-invertible 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  \subsection{Functions}  \section{Functions}
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
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 interpreated 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 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
# Line 497  degree \var{integrationOrder} \index{int Line 520  degree \var{integrationOrder} \index{int
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
528  recovers a \Domain object from a dump file created by the \  recovers a \Domain object from a dump file created by the \
529  eateseates a \Domain object form the FEM mesh defined in  \function{dump} method of a \Domain object defined in
530  file \var{fileName}. The file must be given the \finley file format.  file \var{fileName}.
If \var{integrationOrder} is positive, a numerical integration scheme
chosen which is accurate on each element up to a polynomial of
degree \var{integrationOrder} \index{integration order}. Otherwise
an appropriate integration order is chosen independently.
531  \end{funcdesc}  \end{funcdesc}
532
533
534  \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, \\
535    periodic0=\False, periodic1=\False, useElementsOnFace=\False, useMacroElements=\False, optimize=\False}    periodic0=\False, periodic1=\False, useElementsOnFace=\False, useMacroElements=\False,\\ optimize=\False}
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
# Line 542  in $x_1$-direction. Line 561  in $x_1$-direction.
561  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 computation and also ParMETIS will be used to improve the mesh partition if running on multiple CPUs with MPI.
562  \end{funcdesc}  \end{funcdesc}
563
564  \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,
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
# Line 574  If \var{optimize}=\True mesh node relabe Line 593  If \var{optimize}=\True mesh node relabe
593
594  \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}  \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
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.e-13}  \begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
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}

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