/[escript]/trunk/doc/user/finley.tex
ViewVC logotype

Annotation of /trunk/doc/user/finley.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 102 - (hide annotations)
Wed Dec 15 07:08:39 2004 UTC (14 years, 3 months ago) by jgs
Original Path: trunk/esys2/doc/user/finley.tex
File MIME type: application/x-tex
File size: 19071 byte(s)
*** empty log message ***

1 jgs 102 % $Id$
2    
3    
4     \chapter{ The module \finley}
5     \label{CHAPTER ON FINLEY}
6    
7     \begin{figure}
8     \centerline{\includegraphics[width=\figwidth]{Finley1}}
9     \caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})}
10     \label{FINLEY FIG 0}
11     \end{figure}
12    
13     \begin{figure}
14     \centerline{\includegraphics[width=\figwidth]{Finley2}}
15     \caption{Mesh around a contact region (\finleyelement{Rec4})}
16     \label{FINLEY FIG 01}
17     \end{figure}
18    
19     \declaremodule{extension}{finley} \modulesynopsis{Solving linear, steady partial differential equations using
20     finite elements}
21    
22     {\it finley} is a library of C functions solving linear, steady partial differential equations
23     \index{partial differential equations} (PDEs) or systems of PDEs using isoparametrical finite
24     elements \index{FEM!isoparametrical}.
25     It supports unstructured, 1D, 2D and 3D meshes. The module \finley provides an access to the
26     library through the \LinearPDE class of \escript supporting its full functionality. {\it finley}
27     is parallelized using the OpenMP \index{OpenMP} paradigm.
28    
29     \subsection{Meshes}
30     To understand the usage of \finley one needs to have an understanding of how the finite element meshes
31     \index{FEM!mesh} are defined. \fig{FINLEY FIG 0} shoes an example of the
32     subdivision of an ellipse into so called elements \index{FEM!elements} \index{element}.
33     In this case, triangles have been used but other forms of subdivisions
34     can be constructed, e.g. into quadrilaterals or, in the three dimensional case, into tetrahedrons
35     and hexahedrons. The idea of the finite element method is to approximate the solution by a function
36     which is a polynomial of a certain order and is continuous across it boundary to neighbour elements.
37     In the example of \fig{FINLEY FIG 0} a linear polynomial is used on each triangle. As one can seen, the triangulation
38     is a quite poor approximation of the ellipse. It can be improved by introducing a midpoint on each element edge and
39     position those nodes, which are located on an edge expecting to describing the boundary, onto the boundary.
40     In this case the triangle gets a curved edge which requires a parametrization of the triangle using a
41     quadratic polynomial. For this case, the solution is also approximated by a piecewise quadratic polynomial
42     (which explains the name isoparametrical elements), see \Ref{Zienc,NumHand} for more details.
43    
44     The union of all elements defines the domain of the PDE.
45     Each element is defined by the nodes used to describe is shape. In \fig{FINLEY FIG 0} the element,
46     which have type \finleyelement{Tri3},
47     with the element reference number $19$ \index{element!reference number} is defined by the nodes
48     with the reference numbers $9$, $11$ and $0$ \index{node!reference number}. Notice that the order is counterclockwise.
49     The coefficients of the PDE are evaluated at integration nodes with each individual element.
50     For quadrilateral elements a Gauss quadrature scheme is used. In the case of triangular elements a
51     modified from is applied. The boundary of the domain is also subdivided into elements \index{element!face}. In \fig{FINLEY FIG 0}
52     line elements with two nodes are used. The elements are also defined by their describing nodes, e.g.
53     the face element reference number $20$ which has type \finleyelement{Line2} is defined by the nodes
54     with the reference numbers $11$ and $0$. Again the order is crucial, if moving from the first
55     to second node the domain has to lay on the left hand side (in case of a two dimension surface element
56     the domain has to lay on left hand side when moving counterclockwise). If the gradient on the
57     surface of the domain wants to be calculated rich face elements face to be used. Rich elements on a face
58     is identical to interior elements but with a modified order of nodes such that the 'first' face of the element aligns
59     with the surface of the domian. In \fig{FINLEY FIG 0}
60     elements of the type \finleyelement{Tri3Face} are used.
61     The face element reference number $20$ as a rich face element is defined by the nodes
62     with the reference numbers $11$, $0$ and $9$. Notice that the face element $20$ is identical to the
63     interior element $19$ however, in this case, the order of the node is different to align the first
64     edge of the triangle (which is the edge starting with the first node) with the boundary of the domain.
65    
66     Be aware that face elements and elements in the interior of the domain must match, i.e. a face element must be the face
67     of an interior element or, in case of a rich face element, must be identical to an interior element.
68     If no face elements are specified
69     \finley implicitly assumes homogeneous natural boundary conditions \index{natural boundary conditions!homogeneous},
70     i.e. \var{d}=$0$ and \var{y}=$0$, on the entire boundary of the domain. For
71     inhomogeneous natural boundary conditions \index{natural boundary conditions!inhomogeneous},
72     the boundary must be described by face elements.
73    
74     If discontinuities of the PDE solution are considered contact elements
75     \index{element!contact}\index{contact conditions} are introduced to describe the contact region $\Gamma^{contact}$
76     even if $d^{contact}$ and $y^{contact}$ are zero. \fig{FINLEY FIG 01} shows a simple example of a mesh
77     of rectangular elements around a contact region $\Gamma^{contact}$ \index{element!contact}.
78     The contact region is described by the
79     elements $4$, $3$ and $6$. Their element type is \finleyelement{Line2_Contact}.
80     The nodes $9$, $12$, $6$, $5$ are defining contact element $4$, where the coordinates of nodes $12$ and $5$ and
81     nodes $4$ and $6$ are identical with the idea that nodes $12$ and $9$ are located above and
82     nodes $5$ and $6$ are below the contact region.
83     Again, the order of the nodes within an element is crucial. There is also the option of using rich elements
84     if the gradient wants to be calculated on the contact region. Similar to the rich face elements
85     they are constructed from two interior elements with reordering the nodes such that
86     the 'first' face of the element above and the 'first' face of the element below the
87     contact regions are lining up. The rich version of element
88     $4$ is of type \finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$, $18$, $6$, $5$, $0$ and
89     $2$.
90    
91     \tab{FINLEY TAB 1} shows the interior element types and the corresponding element types to be used
92     on face and contacts. \fig{FINLEY.FIG:1}, \fig{FINLEY.FIG:2} and \fig{FINLEY.FIG:4} show the ordering of
93     the nodes within an element.
94    
95     \begin{table}
96     \begin{tablev}{l|llll}{textrm}{interior}{face}{rich face}{contact}{rich contact}
97     \linev{\finleyelement{Line2}}{\finleyelement{Point1}}{\finleyelement{Line2Face}}{\finleyelement{Point1_Contact}}{\finleyelement{Line2Face_Contact}}
98     \linev{\finleyelement{Line3}}{\finleyelement{Point1}}{\finleyelement{Line3Face}}{\finleyelement{Point1_Contact}}{\finleyelement{Line3Face_Contact}}
99     \linev{\finleyelement{Tri3}}{\finleyelement{Line2}}{\finleyelement{Tri3Face}}{\finleyelement{Line2_Contact}}{\finleyelement{Tri3Face_Contact}}
100     \linev{\finleyelement{Tri6}}{\finleyelement{Line3}}{\finleyelement{Tri6Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Tri6Face_Contact}}
101     \linev{\finleyelement{Rec4}}{\finleyelement{Line2}}{\finleyelement{Rec4Face}}{\finleyelement{Line2_Contact}}{\finleyelement{Rec4Face_Contact}}
102     \linev{\finleyelement{Rec8}}{\finleyelement{Line3}}{\finleyelement{Rec8Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Rec8Face_Contact}}
103     \linev{\finleyelement{Rec9}}{\finleyelement{Line3}}{\finleyelement{Rec9Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Rec9Face_Contact}}
104     \linev{\finleyelement{Tet4}}{\finleyelement{Tri6}}{\finleyelement{Tet4Face}}{\finleyelement{Tri6_Contact}}{\finleyelement{Tet4Face_Contact}}
105     \linev{\finleyelement{Tet10}}{\finleyelement{Tri9}}{\finleyelement{Tet10Face}}{\finleyelement{Tri9_Contact}}{\finleyelement{Tet10Face_Contact}}
106     \linev{\finleyelement{Hex8}}{\finleyelement{Rec4}}{\finleyelement{Hex8Face}}{\finleyelement{Rec4_Contact}}{\finleyelement{Hex8Face_Contact}}
107     \linev{\finleyelement{Hex20}}{\finleyelement{Rec8}}{\finleyelement{Hex20Face}}{\finleyelement{Rec8_Contact}}{\finleyelement{Hex20Face_Contact}}
108     \end{tablev}
109     \caption{Finley elements and corresponding elements to be used on domain faces and contacts.
110     The rich types have to be used if the gradient of function wants to calculated on faces and contacts, resepctively.}
111     \label{FINLEY TAB 1}
112     \end{table}
113    
114     The native \finley file format is defined as follows.
115     Each node \var{i} has \var{dim} spatial coordinates \var{Node[i]}, a reference number
116     \var{Node_ref[i]}, a degree of freedom \var{Node_DOF[i]} and tag \var{Node_tag[i]}.
117     In most cases \var{Node_DOF[i]}=\var{Node_ref[i]} however for periodic boundary conditions
118     \var{Node_DOF[i]} is chosen differently, see example below. The tag can be used to mark nodes sharing
119     the same properties. Element \var{i} is defined by the \var{Element_numNodes} nodes \var{Element_Nodes[i]}
120     which is a list of node reference numbers. The order is crucial.
121     It has a reference number \var{Element_ref[i]} and a tag \var{Element_tag[i]}. The tag
122     can be used to mark elements sharing the same properties. For instance elements above
123     a contact region are marked with $2$ and element below a contact region are marked with $1$.
124     \var{Element_Type} and \var{Element_Num} give the element type and the number of elements in the mesh.
125     Analogue notations are used for face and contact elements. The following Python script
126     prints the mesh definition in the \finley file format:
127     \begin{python}
128     print "%s\n"%mesh_name
129     # node coordinates:
130     print "%dD-nodes %d\n"%(dim,numNodes)
131     for i in range(numNodes):
132     print "%d %d %d"%(Node_ref[i],Node_DOF[i],Node_tag[i])
133     for j in range(dim): print " %e"%Node[i][j]
134     print "\n"
135     # interior elements
136     print "%s %d\n"%(Element_Type,Element_Num)
137     for i in range(Element_Num):
138     print "%d %d"%(Element_ref[i],Element_tag[i])
139     for j in range(Element_numNodes): print " %d"%Element_Nodes[i][j]
140     print "\n"
141     # face elements
142     print "%s %d\n"%(FaceElement_Type,FaceElement_Num)
143     for i in range(FaceElement_Num):
144     print "%d %d"%(FaceElement_ref[i],FaceElement_tag[i])
145     for j in range(FaceElement_numNodes): print " %d"%FaceElement_Nodes[i][j]
146     print "\n"
147     # contact elements
148     print "%s %d\n"%(ContactElement_Type,ContactElement_Num)
149     for i in range(ContactElement_Num):
150     print "%d %d"%(ContactElement_ref[i],ContactElement_tag[i])
151     for j in range(ContactElement_numNodes): print " %d"%ContactElement_Nodes[i][j]
152     print "\n"
153     # point sources (not supported yet)
154     write("Point1 0",face_element_typ,numFaceElements)
155     \end{python}
156    
157     The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}:
158     \begin{verbatim}
159     Example 1
160     2D Nodes 16
161     0 0 0 0. 0.
162     2 2 0 0.33 0.
163     3 3 0 0.66 0.
164     7 4 0 1. 0.
165     5 5 0 0. 0.5
166     6 6 0 0.33 0.5
167     8 8 0 0.66 0.5
168     10 10 0 1.0 0.5
169     12 12 0 0. 0.5
170     9 9 0 0.33 0.5
171     13 13 0 0.66 0.5
172     15 15 0 1.0 0.5
173     16 16 0 0. 1.0
174     18 18 0 0.33 1.0
175     19 19 0 0.66 1.0
176     20 20 0 1.0 1.0
177     Rec4 6
178     0 1 0 2 6 5
179     1 1 2 3 8 6
180     2 1 3 7 10 8
181     5 2 12 9 18 16
182     7 2 13 19 18 9
183     10 2 20 19 13 15
184     Line2 0
185     Line2_Contact 3
186     4 0 9 12 6 5
187     3 0 13 9 8 6
188     6 0 15 13 10 8
189     Point1 0
190     \end{verbatim}
191     Notice that the order in which the nodes and elements are given is arbitrary.
192     In that case rich contact element are used the contact element section get the form
193     \begin{verbatim}
194     Rec4Face_Contact 3
195     4 0 9 12 16 18 6 5 0 2
196     3 0 13 9 18 19 8 6 2 3
197     6 0 15 13 19 20 10 8 3 7
198     \end{verbatim}
199     Periodic boundary condition \index{boundary conditions!periodic} can be introduced by altering \var{Node_DOF}.
200     It allows to identify nodes even if they have different physical locations. For instance, to
201     enforce periodic boundary conditions at the face $x_0=0$ and $x_0=1$ one identifies
202     the degrees of freedom for nodes $0$, $5$, $12$ and $16$ with the degrees of freedom for
203     $7$, $10$, $15$ and $20$, respectively. The node section of the \finley mesh gets now the form:
204     \begin{verbatim}
205     2D Nodes 16
206     0 0 0 0. 0.
207     2 2 0 0.33 0.
208     3 3 0 0.66 0.
209     7 0 0 1. 0.
210     5 5 0 0. 0.5
211     6 6 0 0.33 0.5
212     8 8 0 0.66 0.5
213     10 5 0 1.0 0.5
214     12 12 0 0. 0.5
215     9 9 0 0.33 0.5
216     13 13 0 0.66 0.5
217     15 12 0 1.0 0.5
218     16 16 0 0. 1.0
219     18 18 0 0.33 1.0
220     19 19 0 0.66 1.0
221     20 16 0 1.0 1.0
222     \end{verbatim}
223    
224    
225     \include{finleyelements}
226    
227     \subsection{Linear Solvers in \LinearPDE}
228     Currently \finley support the linear solvers \PCG, \GMRES, \PRESTWENTY and \BiCGStab.
229     For \GMRES the options \var{trancation} and \var{restart} of the \method{getSolution} can be
230     used to control the trunction and restart during iteration. Default values are
231     \var{truncation}=5 and \var{restart}=20.
232     The default solver is \BiCGStab but if the symmetry flag is set \PCG is the default solver.
233     \finley supports the solver options \var{iter_max} which specifies the maximum number of iterations steps,
234     \var{verbose}=\True or \False and \var{preconditioner}=\constant{JACOBI} or \constant {ILU0}.
235     In some installation \finley supports \Direct solver and the
236     solver options \var{reordering}=\constant{util.NO_REORDERING},
237     \constant{util.MINIMUM_FILL_IN} or \constant{util.NESTED_DISSECTION} (default is \constant{util.NO_REORDERING}),
238     \var{drop_tolerance} specifying the threshold for values to be dropped in the
239     incomplete elimation process (default is 0.01) and \var{drop_storage} specifying the maximum increase
240     in storage allowed in the
241     incomplete elimation process (default is 1.20).
242    
243     \subsection{Functions}
244     \begin{funcdesc}{Mesh}{fileName,integrationOrder=-1}
245     creates a \Domain object form the FEM mesh defined in
246     file \var{fileName}. The file must be given the \finley file format.
247     If \var{integrationOrder} is positive, a numerical integration scheme
248     chosen which is accurate on each element up to a polynomial of
249     degree \var{integrationOrder} \index{integration order}. Otherwise
250     an appropriate integration order is chosen independently.
251     \end{funcdesc}
252    
253     \begin{funcdesc}{Interval}{n0,order=1,l0=1.,integrationOrder=-1, \\
254     periodic0=\False,useElementsOnFace=\False}
255     Generates a \Domain object representing a interval $[0,l0]$. The interval is filled with
256     \var{n0} elements.
257     For \var{order}=1 and \var{order}=2
258     \finleyelement{Line2} and
259     \finleyelement{Line3} are used, respectively.
260     In the case of \var{useElementsOnFace}=\False,
261     \finleyelement{Point1} are used to describe the boundary points.
262     In the case of \var{useElementsOnFace}=\True (this option should be used if gradients
263     are calculated on domain faces),
264     \finleyelement{Line2} and
265     \finleyelement{Line3} are used on both ends of the interval.
266     If \var{integrationOrder} is positive, a numerical integration scheme
267     chosen which is accurate on each element up to a polynomial of
268     degree \var{integrationOrder} \index{integration order}. Otherwise
269     an appropriate integration order is chosen independently. If
270     \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions}
271     along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley
272     the value at $x_0=0$ will be identical to the values at $x_0=\var{l0}$.
273     \end{funcdesc}
274    
275     \begin{funcdesc}{Rectangle}{n0,n1,order=1,l0=1.,l1=1., integrationOrder=-1, \\
276     periodic0=\False,periodic1=\False,useElementsOnFace=\False}
277     Generates a \Domain object representing a two dimensional rectangle between
278     $(0,0)$ and $(l0,l1)$ with orthogonal edges. The rectangle is filled with
279     \var{n0} elements along the $x_0$-axis and
280     \var{n1} elements along the $x_1$-axis.
281     For \var{order}=1 and \var{order}=2
282     \finleyelement{Rec4} and
283     \finleyelement{Rec8} are used, respectively.
284     In the case of \var{useElementsOnFace}=\False,
285     \finleyelement{Line2} and
286     \finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively.
287     In the case of \var{useElementsOnFace}=\True (this option should be used if gradients
288     are calculated on domain faces),
289     \finleyelement{Rec4Face} and
290     \finleyelement{Rec8Face} are used on the edges, respectively.
291     If \var{integrationOrder} is positive, a numerical integration scheme
292     chosen which is accurate on each element up to a polynomial of
293     degree \var{integrationOrder} \index{integration order}. Otherwise
294     an appropriate integration order is chosen independently. If
295     \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions}
296     along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley
297     the value on the line $x_0=0$ will be identical to the values on $x_0=\var{l0}$.
298     Correspondingly,
299     \var{periodic1}=\False sets periodic boundary conditions
300     in $x_1$-direction.
301     \end{funcdesc}
302    
303     \begin{funcdesc}{Brick}{n0,n1,n2,order=1,l0=1.,l1=1.,l2=1., integrationOrder=-1, \\
304     periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False}
305     Generates a \Domain object representing a three dimensional brick between
306     $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with
307     \var{n0} elements along the $x_0$-axis,
308     \var{n1} elements along the $x_1$-axis and
309     \var{n2} elements along the $x_2$-axis.
310     For \var{order}=1 and \var{order}=2
311     \finleyelement{Hex8} and
312     \finleyelement{Hex20} are used, respectively.
313     In the case of \var{useElementsOnFace}=\False,
314     \finleyelement{Rec4} and
315     \finleyelement{Rec8} are used to subdivide the faces of the brick, respectively.
316     In the case of \var{useElementsOnFace}=\True (this option should be used if gradients
317     are calculated on domain faces),
318     \finleyelement{Hex8Face} and
319     \finleyelement{Hex20Face} are used on the brick faces, respectively.
320     If \var{integrationOrder} is positive, a numerical integration scheme
321     chosen which is accurate on each element up to a polynomial of
322     degree \var{integrationOrder} \index{integration order}. Otherwise
323     an appropriate integration order is chosen independently. If
324     \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions}
325     along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley
326     the value on the plane $x_0=0$ will be identical to the values on $x_0=\var{l0}$. Correspondingly,
327     \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions
328     in $x_1$-direction and $x_2$-direction, respectively.
329     \end{funcdesc}
330    
331     \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
332     Generates a new \Domain object from the list \var{mehList} of \finley meshes.
333     Nodes in face elements whose difference of coordinates is less then \var{tolerance} times the
334     diameter of the domain are merged. The corresponding face elements are removed from the mesh.
335    
336     TODO: explain \var{safetyFactor} and show an example.
337     \end{funcdesc}
338    
339     \begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
340     Generates a new \Domain object from the list \var{mehList} of \finley meshes.
341     Face elements whose nodes coordinates have difference is less then \var{tolerance} times the
342     diameter of the domain are combined to form a contact element \index{element!contact}
343     The corresponding face elements are removed from the mesh.
344    
345     TODO: explain \var{safetyFactor} and show an example.
346     \end{funcdesc}

Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision

  ViewVC Help
Powered by ViewVC 1.1.26