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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2881 - (hide annotations)
Thu Jan 28 02:03:15 2010 UTC (8 years, 11 months ago) by jfenwick
File MIME type: application/x-tex
File size: 27819 byte(s)
Don't panic.
Updating copyright stamps

1 ksteube 1811
2     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 ksteube 1316 %
4 jfenwick 2881 % Copyright (c) 2003-2010 by University of Queensland
5 ksteube 1811 % Earth Systems Science Computational Center (ESSCC)
6     % http://www.uq.edu.au/esscc
7 gross 625 %
8 ksteube 1811 % Primary Business: Queensland, Australia
9     % Licensed under the Open Software License version 3.0
10     % http://www.opensource.org/licenses/osl-3.0.php
11 gross 625 %
12 ksteube 1811 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13 jgs 102
14 ksteube 1811
15 ksteube 1318 \chapter{ The Module \finley}
16 jgs 102 \label{CHAPTER ON FINLEY}
17    
18     \begin{figure}
19 jfenwick 2335 \centerline{\includegraphics[width=\figwidth]{figures/FinleyMesh}}
20 jgs 102 \caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})}
21     \label{FINLEY FIG 0}
22     \end{figure}
23    
24     \begin{figure}
25 jfenwick 2335 \centerline{\includegraphics[width=\figwidth]{figures/FinleyContact}}
26 jgs 102 \caption{Mesh around a contact region (\finleyelement{Rec4})}
27     \label{FINLEY FIG 01}
28     \end{figure}
29    
30     \declaremodule{extension}{finley} \modulesynopsis{Solving linear, steady partial differential equations using
31     finite elements}
32    
33     {\it finley} is a library of C functions solving linear, steady partial differential equations
34     \index{partial differential equations} (PDEs) or systems of PDEs using isoparametrical finite
35     elements \index{FEM!isoparametrical}.
36     It supports unstructured, 1D, 2D and 3D meshes. The module \finley provides an access to the
37     library through the \LinearPDE class of \escript supporting its full functionality. {\it finley}
38     is parallelized using the OpenMP \index{OpenMP} paradigm.
39    
40 gross 993 \section{Formulation}
41    
42     For a single PDE with a solution with a single component the linear PDE is defined in the
43     following form:
44     \begin{equation}\label{FINLEY.SINGLE.1}
45     \begin{array}{cl} &
46     \displaystyle{
47     \int\hackscore{\Omega}
48     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 } \\
49     + & \displaystyle{\int\hackscore{\Gamma} d \cdot vu \; d{\Gamma} }
50     + \displaystyle{\int\hackscore{\Gamma^{contact}} d^{contact} \cdot [v][u] \; d{\Gamma} } \\
51     = & \displaystyle{\int\hackscore{\Omega} X\hackscore{j} \cdot v\hackscore{,j}+ Y \cdot v \; d\Omega }\\
52     + & \displaystyle{\int\hackscore{\Gamma} y \cdot v \; d{\Gamma}} +
53     \displaystyle{\int\hackscore{\Gamma^{contact}} y^{contact}\cdot [v] \; d{\Gamma}} \\
54     \end{array}
55     \end{equation}
56    
57     \section{Meshes}
58 gross 2793 \label{FINLEY MESHES}
59 jgs 102 To understand the usage of \finley one needs to have an understanding of how the finite element meshes
60 jgs 107 \index{FEM!mesh} are defined. \fig{FINLEY FIG 0} shows an example of the
61 jgs 102 subdivision of an ellipse into so called elements \index{FEM!elements} \index{element}.
62     In this case, triangles have been used but other forms of subdivisions
63     can be constructed, e.g. into quadrilaterals or, in the three dimensional case, into tetrahedrons
64     and hexahedrons. The idea of the finite element method is to approximate the solution by a function
65 lgraham 1700 which is a polynomial of a certain order and is continuous across it boundary to neighbor elements.
66 jgs 107 In the example of \fig{FINLEY FIG 0} a linear polynomial is used on each triangle. As one can see, the triangulation
67     is quite a poor approximation of the ellipse. It can be improved by introducing a midpoint on each element edge then
68     positioning those nodes located on an edge expected to describe the boundary, onto the boundary.
69 gross 2793 In this case the triangle gets a curved edge which requires a parameterization of the triangle using a
70 jgs 102 quadratic polynomial. For this case, the solution is also approximated by a piecewise quadratic polynomial
71 gross 2748 (which explains the name isoparametrical elements), see \Ref{Zienc,NumHand} for more details.
72     \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.
73 jgs 102
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 gross 2748
122    
123 jgs 102 \tab{FINLEY TAB 1} shows the interior element types and the corresponding element types to be used
124 jgs 107 on the face and contacts. \fig{FINLEY.FIG:1}, \fig{FINLEY.FIG:2} and \fig{FINLEY.FIG:4} show the ordering of
125 jgs 102 the nodes within an element.
126    
127     \begin{table}
128     \begin{tablev}{l|llll}{textrm}{interior}{face}{rich face}{contact}{rich contact}
129     \linev{\finleyelement{Line2}}{\finleyelement{Point1}}{\finleyelement{Line2Face}}{\finleyelement{Point1_Contact}}{\finleyelement{Line2Face_Contact}}
130     \linev{\finleyelement{Line3}}{\finleyelement{Point1}}{\finleyelement{Line3Face}}{\finleyelement{Point1_Contact}}{\finleyelement{Line3Face_Contact}}
131     \linev{\finleyelement{Tri3}}{\finleyelement{Line2}}{\finleyelement{Tri3Face}}{\finleyelement{Line2_Contact}}{\finleyelement{Tri3Face_Contact}}
132     \linev{\finleyelement{Tri6}}{\finleyelement{Line3}}{\finleyelement{Tri6Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Tri6Face_Contact}}
133     \linev{\finleyelement{Rec4}}{\finleyelement{Line2}}{\finleyelement{Rec4Face}}{\finleyelement{Line2_Contact}}{\finleyelement{Rec4Face_Contact}}
134     \linev{\finleyelement{Rec8}}{\finleyelement{Line3}}{\finleyelement{Rec8Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Rec8Face_Contact}}
135     \linev{\finleyelement{Rec9}}{\finleyelement{Line3}}{\finleyelement{Rec9Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Rec9Face_Contact}}
136     \linev{\finleyelement{Tet4}}{\finleyelement{Tri6}}{\finleyelement{Tet4Face}}{\finleyelement{Tri6_Contact}}{\finleyelement{Tet4Face_Contact}}
137     \linev{\finleyelement{Tet10}}{\finleyelement{Tri9}}{\finleyelement{Tet10Face}}{\finleyelement{Tri9_Contact}}{\finleyelement{Tet10Face_Contact}}
138     \linev{\finleyelement{Hex8}}{\finleyelement{Rec4}}{\finleyelement{Hex8Face}}{\finleyelement{Rec4_Contact}}{\finleyelement{Hex8Face_Contact}}
139     \linev{\finleyelement{Hex20}}{\finleyelement{Rec8}}{\finleyelement{Hex20Face}}{\finleyelement{Rec8_Contact}}{\finleyelement{Hex20Face_Contact}}
140 gross 2748 \linev{\finleyelement{Hex27}}{\finleyelement{Rec9}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
141     \linev{\finleyelement{Hex27Macro}}{\finleyelement{Rec9Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
142     \linev{\finleyelement{Tet10Macro}}{\finleyelement{Tri6Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
143     \linev{\finleyelement{Rec9Macro}}{\finleyelement{Line3Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
144     \linev{\finleyelement{Tri6Macro}}{\finleyelement{Line3Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
145 jgs 102 \end{tablev}
146     \caption{Finley elements and corresponding elements to be used on domain faces and contacts.
147 ksteube 1316 The rich types have to be used if the gradient of function is to be calculated on faces and contacts, respectively.}
148 jgs 102 \label{FINLEY TAB 1}
149     \end{table}
150    
151     The native \finley file format is defined as follows.
152     Each node \var{i} has \var{dim} spatial coordinates \var{Node[i]}, a reference number
153     \var{Node_ref[i]}, a degree of freedom \var{Node_DOF[i]} and tag \var{Node_tag[i]}.
154 jgs 107 In most cases \var{Node_DOF[i]}=\var{Node_ref[i]} however, for periodic boundary conditions,
155 jgs 102 \var{Node_DOF[i]} is chosen differently, see example below. The tag can be used to mark nodes sharing
156     the same properties. Element \var{i} is defined by the \var{Element_numNodes} nodes \var{Element_Nodes[i]}
157     which is a list of node reference numbers. The order is crucial.
158     It has a reference number \var{Element_ref[i]} and a tag \var{Element_tag[i]}. The tag
159     can be used to mark elements sharing the same properties. For instance elements above
160 jgs 107 a contact region are marked with $2$ and elements below a contact region are marked with $1$.
161 jgs 102 \var{Element_Type} and \var{Element_Num} give the element type and the number of elements in the mesh.
162     Analogue notations are used for face and contact elements. The following Python script
163     prints the mesh definition in the \finley file format:
164     \begin{python}
165     print "%s\n"%mesh_name
166     # node coordinates:
167     print "%dD-nodes %d\n"%(dim,numNodes)
168     for i in range(numNodes):
169     print "%d %d %d"%(Node_ref[i],Node_DOF[i],Node_tag[i])
170     for j in range(dim): print " %e"%Node[i][j]
171     print "\n"
172     # interior elements
173     print "%s %d\n"%(Element_Type,Element_Num)
174     for i in range(Element_Num):
175     print "%d %d"%(Element_ref[i],Element_tag[i])
176     for j in range(Element_numNodes): print " %d"%Element_Nodes[i][j]
177     print "\n"
178     # face elements
179     print "%s %d\n"%(FaceElement_Type,FaceElement_Num)
180     for i in range(FaceElement_Num):
181     print "%d %d"%(FaceElement_ref[i],FaceElement_tag[i])
182     for j in range(FaceElement_numNodes): print " %d"%FaceElement_Nodes[i][j]
183     print "\n"
184     # contact elements
185     print "%s %d\n"%(ContactElement_Type,ContactElement_Num)
186     for i in range(ContactElement_Num):
187     print "%d %d"%(ContactElement_ref[i],ContactElement_tag[i])
188     for j in range(ContactElement_numNodes): print " %d"%ContactElement_Nodes[i][j]
189     print "\n"
190     # point sources (not supported yet)
191 ksteube 1316 write("Point1 0",face_element_type,numFaceElements)
192 jgs 102 \end{python}
193    
194     The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}:
195     \begin{verbatim}
196     Example 1
197     2D Nodes 16
198     0 0 0 0. 0.
199     2 2 0 0.33 0.
200     3 3 0 0.66 0.
201     7 4 0 1. 0.
202     5 5 0 0. 0.5
203     6 6 0 0.33 0.5
204     8 8 0 0.66 0.5
205     10 10 0 1.0 0.5
206     12 12 0 0. 0.5
207     9 9 0 0.33 0.5
208     13 13 0 0.66 0.5
209     15 15 0 1.0 0.5
210     16 16 0 0. 1.0
211     18 18 0 0.33 1.0
212     19 19 0 0.66 1.0
213     20 20 0 1.0 1.0
214     Rec4 6
215     0 1 0 2 6 5
216     1 1 2 3 8 6
217     2 1 3 7 10 8
218     5 2 12 9 18 16
219     7 2 13 19 18 9
220     10 2 20 19 13 15
221     Line2 0
222     Line2_Contact 3
223     4 0 9 12 6 5
224     3 0 13 9 8 6
225     6 0 15 13 10 8
226     Point1 0
227     \end{verbatim}
228     Notice that the order in which the nodes and elements are given is arbitrary.
229 jgs 107 In the case that rich contact elements are used the contact element section gets
230     the form
231 jgs 102 \begin{verbatim}
232     Rec4Face_Contact 3
233     4 0 9 12 16 18 6 5 0 2
234     3 0 13 9 18 19 8 6 2 3
235     6 0 15 13 19 20 10 8 3 7
236     \end{verbatim}
237     Periodic boundary condition \index{boundary conditions!periodic} can be introduced by altering \var{Node_DOF}.
238 jgs 107 It allows identification of nodes even if they have different physical locations. For instance, to
239 jgs 102 enforce periodic boundary conditions at the face $x_0=0$ and $x_0=1$ one identifies
240     the degrees of freedom for nodes $0$, $5$, $12$ and $16$ with the degrees of freedom for
241     $7$, $10$, $15$ and $20$, respectively. The node section of the \finley mesh gets now the form:
242     \begin{verbatim}
243     2D Nodes 16
244     0 0 0 0. 0.
245     2 2 0 0.33 0.
246     3 3 0 0.66 0.
247     7 0 0 1. 0.
248     5 5 0 0. 0.5
249     6 6 0 0.33 0.5
250     8 8 0 0.66 0.5
251     10 5 0 1.0 0.5
252     12 12 0 0. 0.5
253     9 9 0 0.33 0.5
254     13 13 0 0.66 0.5
255     15 12 0 1.0 0.5
256     16 16 0 0. 1.0
257     18 18 0 0.33 1.0
258     19 19 0 0.66 1.0
259     20 16 0 1.0 1.0
260     \end{verbatim}
261    
262 jfenwick 1955 \clearpage
263     \input{finleyelements}
264     \clearpage
265 jgs 102
266 gross 2793 \begin{figure}[th]
267     \begin{center}
268     \subfigure[Triangle]{\label{FINLEY MACRO TRI}\includegraphics[scale=0.25]{figures/FinleyMacroTri}}
269     \subfigure[Quadrilateral]{\label{FINLEY MACRO REC}\includegraphics[scale=0.25]{figures/FinleyMacroRec}}
270     \includegraphics[scale=0.2]{figures/FinleyMacroLeg}
271     \end{center}
272     Macro elements in \finley.
273     \end{figure}
274    
275 gross 2748 \section{Macro Elements}
276     \label{SEC FINLEY MACRO}
277 gross 2793 \finley supports the usage of macro elements~\index{macro elements} which can be used to
278     achieve LBB compliance when solving incompressible fluid flow problems. LBB compliance is required to
279     get a problem which has a unique solution for pressure and velocity. For macro elements the
280     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
281     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
282     one uses a linear approximation of the velocity together with a linear approximation of the pressure but on elements
283     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
284     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.
285     Typically macro elements are only required to use when an incompressible fluid flow problem
286     is solved, e.g the Stokes problem in Section \ref{STOKES PROBLEM}. Please see Section~\ref{FINLEY MESHES} for
287     more details on the supported macro elements.
288 jgs 102
289 gross 2748
290    
291 gross 2558 \begin{table}
292 jfenwick 2651 {\scriptsize
293 gross 2558 \begin{tabular}{l||c|c|c|c|c|c|c|c}
294     \member{setSolverMethod} & \member{DIRECT}& \member{PCG} & \member{GMRES} & \member{TFQMR} & \member{MINRES} & \member{PRES20} & \member{BICGSTAB} & \member{LUMPING} \\
295     \hline
296     \hline
297     \member{setReordering} & $\checkmark$ & & & & & &\\
298     \hline \member{setRestart} & & & $\checkmark$ & & & $20$ & \\
299     \hline\member{setTruncation} & & & $\checkmark$ & & & $5$ & \\
300     \hline\member{setIterMax} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
301     \hline\member{setTolerance} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
302     \hline\member{setAbsoluteTolerance} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
303 gross 2573 \hline\member{setReordering} & $\checkmark$ & & & & & & & \\
304 gross 2558 \end{tabular}
305     }
306 gross 2573 \caption{Solvers available for
307     \finley
308     and the \PASO package and the relevant options in \class{SolverOptions}.
309     \MKL supports
310     \MINIMUMFILLIN
311     and
312     \NESTEDDESCTION
313     reordering.
314     Currently the \UMFPACK interface does not support any reordering.
315     \label{TAB FINLEY SOLVER OPTIONS 1} }
316 gross 2558 \end{table}
317    
318     \begin{table}
319     {\scriptsize
320     \begin{tabular}{l||c|c|c|c|c|c|c|c}
321     \member{setPreconditioner} &
322     \member{NO_PRECONDITIONER} &
323     \member{AMG} &
324     \member{JACOBI} &
325     \member{GAUSS_SEIDEL}&
326     \member{REC_ILU}&
327     \member{RILU} &
328     \member{ILU0} &
329     \member{DIRECT} \\
330     \hline
331     status: &
332     later &
333     later &
334     $\checkmark$ &
335     $\checkmark$&
336     $\checkmark$ &
337     later &
338     $\checkmark$ &
339     later \\
340     \hline
341     \hline
342     \member{setCoarsening}&
343     &
344     $\checkmark$ &
345     &
346     &
347     &
348     &
349     &
350     \\
351    
352    
353     \hline\member{setLevelMax}&
354     &
355     $\checkmark$ &
356     &
357     &
358     &
359     &
360     &
361     \\
362    
363     \hline\member{setCoarseningThreshold}&
364     &
365     $\checkmark$ &
366     &
367     &
368     &
369     &
370     &
371     \\
372    
373     \hline\member{setMinCoarseMatrixSize} &
374     &
375     $\checkmark$ &
376     &
377     &
378     &
379     &
380     &
381     \\
382    
383     \hline\member{setNumSweeps} &
384     &
385     &
386     $\checkmark$ &
387     $\checkmark$ &
388     &
389     &
390     &
391     \\
392    
393     \hline\member{setNumPreSweeps}&
394     &
395     $\checkmark$ &
396     &
397     &
398     &
399     &
400     &
401     \\
402    
403     \hline\member{setNumPostSweeps} &
404     &
405     $\checkmark$ &
406     &
407     &
408     &
409     &
410     &
411     \\
412    
413     \hline\member{setInnerTolerance}&
414     &
415     &
416     &
417     &
418     &
419     &
420     &
421     \\
422    
423     \hline\member{setDropTolerance}&
424     &
425     &
426     &
427     &
428     &
429     &
430     &
431     \\
432    
433     \hline\member{setDropStorage}&
434     &
435     &
436     &
437     &
438     &
439     &
440     &
441     \\
442    
443     \hline\member{setRelaxationFactor}&
444     &
445     &
446     &
447     &
448     &
449     $\checkmark$ &
450     &
451     \\
452    
453     \hline\member{adaptInnerTolerance}&
454     &
455     &
456     &
457     &
458     &
459     &
460     &
461     \\
462    
463     \hline\member{setInnerIterMax}&
464     &
465     &
466     &
467     &
468     &
469     &
470     &
471     \\
472     \end{tabular}
473     }
474     \caption{Preconditioners available for \finley and the \PASO package and the relevant options in \class{SolverOptions}. \label{TAB FINLEY SOLVER OPTIONS 2}}
475     \end{table}
476    
477 gross 2793 \section{Linear Solvers in \SolverOptions}
478 gross 2558 Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and
479     Table~\ref{TAB FINLEY SOLVER OPTIONS 2} show the solvers and preconditioners supported by
480     \finley through the \PASO library. Currently direct solvers are not supported under MPI.
481     By default, \finley is using the iterative solvers \PCG for symmetric and \BiCGStab for non-symmetric problems.
482 gross 2793 If the direct solver is selected which can be useful when solving very ill-posed equations
483 gross 2748 \finley uses the \MKL \footnote{If the stiffness matrix is non-regular \MKL may return without
484     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
485 gross 2558 a suitable iterative solver from the \PASO is used.
486    
487 gross 2793 \section{Functions}
488 gross 2690 \begin{funcdesc}{ReadMesh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True}}
489 jgs 102 creates a \Domain object form the FEM mesh defined in
490     file \var{fileName}. The file must be given the \finley file format.
491     If \var{integrationOrder} is positive, a numerical integration scheme
492     chosen which is accurate on each element up to a polynomial of
493     degree \var{integrationOrder} \index{integration order}. Otherwise
494 gross 2690 an appropriate integration order is chosen independently.
495     By default the labeling of mesh nodes and element distribution is
496     optimized. Set \var{optimize=False} to switch off relabeling and redistribution.
497     \end{funcdesc}
498    
499 gross 2748 \begin{funcdesc}{ReadGmsh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True\optional{, useMacroElements=False}}}
500 gross 2690 creates a \Domain object form the FEM mesh defined in
501     file \var{fileName}. The file must be given the \gmshextern file format.
502     If \var{integrationOrder} is positive, a numerical integration scheme
503     chosen which is accurate on each element up to a polynomial of
504     degree \var{integrationOrder} \index{integration order}. Otherwise
505 jgs 102 an appropriate integration order is chosen independently.
506 gross 2690 By default the labeling of mesh nodes and element distribution is
507     optimized. Set \var{optimize=False} to switch off relabeling and redistribution.
508 gross 2793 If \var{useMacroElements} is set, second order elements are interpreted as macro elements~\index{macro elements}.
509 gross 2690 Currently \function{ReadGmsh} does not support MPI.
510 jgs 102 \end{funcdesc}
511    
512 gross 2748 \begin{funcdesc}{MakeDomain}{design\optional{, integrationOrder=-1\optional{, optimizeLabeling=True\optional{, useMacroElements=False}}}}
513 gross 2793 Creates a Finley \Domain from a \class{Design} object from \pycad using \gmshextern.
514 gross 2748 The \class{Design} \var{design} defines the geometry.
515     If \var{integrationOrder} is positive, a numerical integration scheme
516     chosen which is accurate on each element up to a polynomial of
517     degree \var{integrationOrder} \index{integration order}. Otherwise
518     an appropriate integration order is chosen independently.
519     Set \var{optimizeLabeling=False} to switch off relabeling and redistribution (not recommended).
520     If \var{useMacroElements} is set, macro elements~\index{macro elements} are used.
521     Currently \function{MakeDomain} does not support MPI.
522     \end{funcdesc}
523 gross 2690
524 gross 2748
525 gross 2417 \begin{funcdesc}{load}{fileName}
526     recovers a \Domain object from a dump file created by the \
527 gross 2793 \function{dump} method of a \Domain object defined in
528     file \var{fileName}.
529 gross 2417 \end{funcdesc}
530    
531 gross 2748
532 jgs 102 \begin{funcdesc}{Rectangle}{n0,n1,order=1,l0=1.,l1=1., integrationOrder=-1, \\
533 gross 2748 periodic0=\False, periodic1=\False, useElementsOnFace=\False, useMacroElements=\False, optimize=\False}
534 jgs 102 Generates a \Domain object representing a two dimensional rectangle between
535     $(0,0)$ and $(l0,l1)$ with orthogonal edges. The rectangle is filled with
536     \var{n0} elements along the $x_0$-axis and
537     \var{n1} elements along the $x_1$-axis.
538     For \var{order}=1 and \var{order}=2
539     \finleyelement{Rec4} and
540     \finleyelement{Rec8} are used, respectively.
541     In the case of \var{useElementsOnFace}=\False,
542     \finleyelement{Line2} and
543     \finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively.
544 gross 2748 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}.
545 jgs 102 In the case of \var{useElementsOnFace}=\True (this option should be used if gradients
546     are calculated on domain faces),
547     \finleyelement{Rec4Face} and
548     \finleyelement{Rec8Face} are used on the edges, respectively.
549     If \var{integrationOrder} is positive, a numerical integration scheme
550     chosen which is accurate on each element up to a polynomial of
551     degree \var{integrationOrder} \index{integration order}. Otherwise
552     an appropriate integration order is chosen independently. If
553     \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions}
554     along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley
555     the value on the line $x_0=0$ will be identical to the values on $x_0=\var{l0}$.
556     Correspondingly,
557     \var{periodic1}=\False sets periodic boundary conditions
558     in $x_1$-direction.
559 ksteube 1459 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.
560 jgs 102 \end{funcdesc}
561    
562     \begin{funcdesc}{Brick}{n0,n1,n2,order=1,l0=1.,l1=1.,l2=1., integrationOrder=-1, \\
563 gross 2748 periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False, useMacroElements=\False, optimize=\False}
564 jgs 102 Generates a \Domain object representing a three dimensional brick between
565     $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with
566     \var{n0} elements along the $x_0$-axis,
567     \var{n1} elements along the $x_1$-axis and
568     \var{n2} elements along the $x_2$-axis.
569     For \var{order}=1 and \var{order}=2
570     \finleyelement{Hex8} and
571     \finleyelement{Hex20} are used, respectively.
572     In the case of \var{useElementsOnFace}=\False,
573     \finleyelement{Rec4} and
574     \finleyelement{Rec8} are used to subdivide the faces of the brick, respectively.
575     In the case of \var{useElementsOnFace}=\True (this option should be used if gradients
576     are calculated on domain faces),
577     \finleyelement{Hex8Face} and
578     \finleyelement{Hex20Face} are used on the brick faces, respectively.
579 gross 2748 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}.
580 jgs 102 If \var{integrationOrder} is positive, a numerical integration scheme
581     chosen which is accurate on each element up to a polynomial of
582     degree \var{integrationOrder} \index{integration order}. Otherwise
583     an appropriate integration order is chosen independently. If
584     \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions}
585     along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley
586     the value on the plane $x_0=0$ will be identical to the values on $x_0=\var{l0}$. Correspondingly,
587     \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions
588     in $x_1$-direction and $x_2$-direction, respectively.
589 ksteube 1459 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.
590 jgs 102 \end{funcdesc}
591    
592     \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
593 ksteube 1316 Generates a new \Domain object from the list \var{meshList} of \finley meshes.
594 jgs 102 Nodes in face elements whose difference of coordinates is less then \var{tolerance} times the
595     diameter of the domain are merged. The corresponding face elements are removed from the mesh.
596    
597     TODO: explain \var{safetyFactor} and show an example.
598     \end{funcdesc}
599    
600     \begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
601 ksteube 1316 Generates a new \Domain object from the list \var{meshList} of \finley meshes.
602 jgs 102 Face elements whose nodes coordinates have difference is less then \var{tolerance} times the
603     diameter of the domain are combined to form a contact element \index{element!contact}
604     The corresponding face elements are removed from the mesh.
605    
606     TODO: explain \var{safetyFactor} and show an example.
607     \end{funcdesc}

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26