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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1384 - (hide annotations)
Fri Jan 11 02:29:38 2008 UTC (11 years, 2 months ago) by phornby
Original Path: temp_trunk_copy/doc/user/finley.tex
File MIME type: application/x-tex
File size: 19170 byte(s)
Make a temp copy of the trunk before checking in the windows changes


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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26