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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2748 - (hide annotations)
Tue Nov 17 07:32:59 2009 UTC (9 years, 4 months ago) by gross
File MIME type: application/x-tex
File size: 26086 byte(s)
Macro elements are implemented now. VTK writer for macro elements still needs testing.
1 ksteube 1811
2     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 ksteube 1316 %
4 jfenwick 2548 % Copyright (c) 2003-2009 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 jgs 102 To understand the usage of \finley one needs to have an understanding of how the finite element meshes
59 jgs 107 \index{FEM!mesh} are defined. \fig{FINLEY FIG 0} shows an example of the
60 jgs 102 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
62     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
64 lgraham 1700 which is a polynomial of a certain order and is continuous across it boundary to neighbor elements.
65 jgs 107 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
67     positioning those nodes located on an edge expected to describe the boundary, onto the boundary.
68 jgs 102 In this case the triangle gets a curved edge which requires a parametrization of the triangle using a
69     quadratic polynomial. For this case, the solution is also approximated by a piecewise quadratic polynomial
70 gross 2748 (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.
72 jgs 102
73     The union of all elements defines the domain of the PDE.
74 jgs 107 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},
76     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.
78 jgs 102 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
80 jgs 107 modified form is applied. The boundary of the domain is also subdivided into elements. \index{element!face} In \fig{FINLEY FIG 0}
81 jgs 102 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
83     with the reference numbers $11$ and $0$. Again the order is crucial, if moving from the first
84 jgs 107 to second node the domain has to lie on the left hand side (in the case of a two dimension surface element
85     the domain has to lie on the left hand side when moving counterclockwise). If the gradient on the
86     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
88 ksteube 1316 with the surface of the domain. In \fig{FINLEY FIG 0}
89 jgs 102 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
91 jgs 107 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
93 jgs 102 edge of the triangle (which is the edge starting with the first node) with the boundary of the domain.
94    
95     Be aware that face elements and elements in the interior of the domain must match, i.e. a face element must be the face
96 jgs 107 of an interior element or, in case of a rich face element, it must be identical to an interior element.
97 jgs 102 If no face elements are specified
98     \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
100     inhomogeneous natural boundary conditions \index{natural boundary conditions!inhomogeneous},
101     the boundary must be described by face elements.
102    
103     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}$
105     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}.
107     The contact region is described by the
108     elements $4$, $3$ and $6$. Their element type is \finleyelement{Line2_Contact}.
109 jgs 107 The nodes $9$, $12$, $6$, $5$ define contact element $4$, where the coordinates of nodes $12$ and $5$ and
110 jgs 102 nodes $4$ and $6$ are identical with the idea that nodes $12$ and $9$ are located above and
111 jgs 107 nodes $5$ and $6$ below the contact region.
112 jgs 102 Again, the order of the nodes within an element is crucial. There is also the option of using rich elements
113 jgs 107 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
115 jgs 102 the 'first' face of the element above and the 'first' face of the element below the
116 jgs 107 contact regions line up. The rich version of element
117 jgs 102 $4$ is of type \finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$, $18$, $6$, $5$, $0$ and
118     $2$.
119    
120 gross 2748
121    
122 jgs 102 \tab{FINLEY TAB 1} shows the interior element types and the corresponding element types to be used
123 jgs 107 on the face and contacts. \fig{FINLEY.FIG:1}, \fig{FINLEY.FIG:2} and \fig{FINLEY.FIG:4} show the ordering of
124 jgs 102 the nodes within an element.
125    
126     \begin{table}
127     \begin{tablev}{l|llll}{textrm}{interior}{face}{rich face}{contact}{rich contact}
128     \linev{\finleyelement{Line2}}{\finleyelement{Point1}}{\finleyelement{Line2Face}}{\finleyelement{Point1_Contact}}{\finleyelement{Line2Face_Contact}}
129     \linev{\finleyelement{Line3}}{\finleyelement{Point1}}{\finleyelement{Line3Face}}{\finleyelement{Point1_Contact}}{\finleyelement{Line3Face_Contact}}
130     \linev{\finleyelement{Tri3}}{\finleyelement{Line2}}{\finleyelement{Tri3Face}}{\finleyelement{Line2_Contact}}{\finleyelement{Tri3Face_Contact}}
131     \linev{\finleyelement{Tri6}}{\finleyelement{Line3}}{\finleyelement{Tri6Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Tri6Face_Contact}}
132     \linev{\finleyelement{Rec4}}{\finleyelement{Line2}}{\finleyelement{Rec4Face}}{\finleyelement{Line2_Contact}}{\finleyelement{Rec4Face_Contact}}
133     \linev{\finleyelement{Rec8}}{\finleyelement{Line3}}{\finleyelement{Rec8Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Rec8Face_Contact}}
134     \linev{\finleyelement{Rec9}}{\finleyelement{Line3}}{\finleyelement{Rec9Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Rec9Face_Contact}}
135     \linev{\finleyelement{Tet4}}{\finleyelement{Tri6}}{\finleyelement{Tet4Face}}{\finleyelement{Tri6_Contact}}{\finleyelement{Tet4Face_Contact}}
136     \linev{\finleyelement{Tet10}}{\finleyelement{Tri9}}{\finleyelement{Tet10Face}}{\finleyelement{Tri9_Contact}}{\finleyelement{Tet10Face_Contact}}
137     \linev{\finleyelement{Hex8}}{\finleyelement{Rec4}}{\finleyelement{Hex8Face}}{\finleyelement{Rec4_Contact}}{\finleyelement{Hex8Face_Contact}}
138     \linev{\finleyelement{Hex20}}{\finleyelement{Rec8}}{\finleyelement{Hex20Face}}{\finleyelement{Rec8_Contact}}{\finleyelement{Hex20Face_Contact}}
139 gross 2748 \linev{\finleyelement{Hex27}}{\finleyelement{Rec9}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
140     \linev{\finleyelement{Hex27Macro}}{\finleyelement{Rec9Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
141     \linev{\finleyelement{Tet10Macro}}{\finleyelement{Tri6Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
142     \linev{\finleyelement{Rec9Macro}}{\finleyelement{Line3Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
143     \linev{\finleyelement{Tri6Macro}}{\finleyelement{Line3Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
144 jgs 102 \end{tablev}
145     \caption{Finley elements and corresponding elements to be used on domain faces and contacts.
146 ksteube 1316 The rich types have to be used if the gradient of function is to be calculated on faces and contacts, respectively.}
147 jgs 102 \label{FINLEY TAB 1}
148     \end{table}
149    
150     The native \finley file format is defined as follows.
151     Each node \var{i} has \var{dim} spatial coordinates \var{Node[i]}, a reference number
152     \var{Node_ref[i]}, a degree of freedom \var{Node_DOF[i]} and tag \var{Node_tag[i]}.
153 jgs 107 In most cases \var{Node_DOF[i]}=\var{Node_ref[i]} however, for periodic boundary conditions,
154 jgs 102 \var{Node_DOF[i]} is chosen differently, see example below. The tag can be used to mark nodes sharing
155     the same properties. Element \var{i} is defined by the \var{Element_numNodes} nodes \var{Element_Nodes[i]}
156     which is a list of node reference numbers. The order is crucial.
157     It has a reference number \var{Element_ref[i]} and a tag \var{Element_tag[i]}. The tag
158     can be used to mark elements sharing the same properties. For instance elements above
159 jgs 107 a contact region are marked with $2$ and elements below a contact region are marked with $1$.
160 jgs 102 \var{Element_Type} and \var{Element_Num} give the element type and the number of elements in the mesh.
161     Analogue notations are used for face and contact elements. The following Python script
162     prints the mesh definition in the \finley file format:
163     \begin{python}
164     print "%s\n"%mesh_name
165     # node coordinates:
166     print "%dD-nodes %d\n"%(dim,numNodes)
167     for i in range(numNodes):
168     print "%d %d %d"%(Node_ref[i],Node_DOF[i],Node_tag[i])
169     for j in range(dim): print " %e"%Node[i][j]
170     print "\n"
171     # interior elements
172     print "%s %d\n"%(Element_Type,Element_Num)
173     for i in range(Element_Num):
174     print "%d %d"%(Element_ref[i],Element_tag[i])
175     for j in range(Element_numNodes): print " %d"%Element_Nodes[i][j]
176     print "\n"
177     # face elements
178     print "%s %d\n"%(FaceElement_Type,FaceElement_Num)
179     for i in range(FaceElement_Num):
180     print "%d %d"%(FaceElement_ref[i],FaceElement_tag[i])
181     for j in range(FaceElement_numNodes): print " %d"%FaceElement_Nodes[i][j]
182     print "\n"
183     # contact elements
184     print "%s %d\n"%(ContactElement_Type,ContactElement_Num)
185     for i in range(ContactElement_Num):
186     print "%d %d"%(ContactElement_ref[i],ContactElement_tag[i])
187     for j in range(ContactElement_numNodes): print " %d"%ContactElement_Nodes[i][j]
188     print "\n"
189     # point sources (not supported yet)
190 ksteube 1316 write("Point1 0",face_element_type,numFaceElements)
191 jgs 102 \end{python}
192    
193     The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}:
194     \begin{verbatim}
195     Example 1
196     2D Nodes 16
197     0 0 0 0. 0.
198     2 2 0 0.33 0.
199     3 3 0 0.66 0.
200     7 4 0 1. 0.
201     5 5 0 0. 0.5
202     6 6 0 0.33 0.5
203     8 8 0 0.66 0.5
204     10 10 0 1.0 0.5
205     12 12 0 0. 0.5
206     9 9 0 0.33 0.5
207     13 13 0 0.66 0.5
208     15 15 0 1.0 0.5
209     16 16 0 0. 1.0
210     18 18 0 0.33 1.0
211     19 19 0 0.66 1.0
212     20 20 0 1.0 1.0
213     Rec4 6
214     0 1 0 2 6 5
215     1 1 2 3 8 6
216     2 1 3 7 10 8
217     5 2 12 9 18 16
218     7 2 13 19 18 9
219     10 2 20 19 13 15
220     Line2 0
221     Line2_Contact 3
222     4 0 9 12 6 5
223     3 0 13 9 8 6
224     6 0 15 13 10 8
225     Point1 0
226     \end{verbatim}
227     Notice that the order in which the nodes and elements are given is arbitrary.
228 jgs 107 In the case that rich contact elements are used the contact element section gets
229     the form
230 jgs 102 \begin{verbatim}
231     Rec4Face_Contact 3
232     4 0 9 12 16 18 6 5 0 2
233     3 0 13 9 18 19 8 6 2 3
234     6 0 15 13 19 20 10 8 3 7
235     \end{verbatim}
236     Periodic boundary condition \index{boundary conditions!periodic} can be introduced by altering \var{Node_DOF}.
237 jgs 107 It allows identification of nodes even if they have different physical locations. For instance, to
238 jgs 102 enforce periodic boundary conditions at the face $x_0=0$ and $x_0=1$ one identifies
239     the degrees of freedom for nodes $0$, $5$, $12$ and $16$ with the degrees of freedom for
240     $7$, $10$, $15$ and $20$, respectively. The node section of the \finley mesh gets now the form:
241     \begin{verbatim}
242     2D Nodes 16
243     0 0 0 0. 0.
244     2 2 0 0.33 0.
245     3 3 0 0.66 0.
246     7 0 0 1. 0.
247     5 5 0 0. 0.5
248     6 6 0 0.33 0.5
249     8 8 0 0.66 0.5
250     10 5 0 1.0 0.5
251     12 12 0 0. 0.5
252     9 9 0 0.33 0.5
253     13 13 0 0.66 0.5
254     15 12 0 1.0 0.5
255     16 16 0 0. 1.0
256     18 18 0 0.33 1.0
257     19 19 0 0.66 1.0
258     20 16 0 1.0 1.0
259     \end{verbatim}
260    
261 jfenwick 1955 \clearpage
262     \input{finleyelements}
263     \clearpage
264 jgs 102
265 gross 2748 \section{Macro Elements}
266     \label{SEC FINLEY MACRO}
267 jgs 102
268 gross 2748
269    
270 gross 2558 \begin{table}
271 jfenwick 2651 {\scriptsize
272 gross 2558 \begin{tabular}{l||c|c|c|c|c|c|c|c}
273     \member{setSolverMethod} & \member{DIRECT}& \member{PCG} & \member{GMRES} & \member{TFQMR} & \member{MINRES} & \member{PRES20} & \member{BICGSTAB} & \member{LUMPING} \\
274     \hline
275     \hline
276     \member{setReordering} & $\checkmark$ & & & & & &\\
277     \hline \member{setRestart} & & & $\checkmark$ & & & $20$ & \\
278     \hline\member{setTruncation} & & & $\checkmark$ & & & $5$ & \\
279     \hline\member{setIterMax} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
280     \hline\member{setTolerance} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
281     \hline\member{setAbsoluteTolerance} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
282 gross 2573 \hline\member{setReordering} & $\checkmark$ & & & & & & & \\
283 gross 2558 \end{tabular}
284     }
285 gross 2573 \caption{Solvers available for
286     \finley
287     and the \PASO package and the relevant options in \class{SolverOptions}.
288     \MKL supports
289     \MINIMUMFILLIN
290     and
291     \NESTEDDESCTION
292     reordering.
293     Currently the \UMFPACK interface does not support any reordering.
294     \label{TAB FINLEY SOLVER OPTIONS 1} }
295 gross 2558 \end{table}
296    
297     \begin{table}
298     {\scriptsize
299     \begin{tabular}{l||c|c|c|c|c|c|c|c}
300     \member{setPreconditioner} &
301     \member{NO_PRECONDITIONER} &
302     \member{AMG} &
303     \member{JACOBI} &
304     \member{GAUSS_SEIDEL}&
305     \member{REC_ILU}&
306     \member{RILU} &
307     \member{ILU0} &
308     \member{DIRECT} \\
309     \hline
310     status: &
311     later &
312     later &
313     $\checkmark$ &
314     $\checkmark$&
315     $\checkmark$ &
316     later &
317     $\checkmark$ &
318     later \\
319     \hline
320     \hline
321     \member{setCoarsening}&
322     &
323     $\checkmark$ &
324     &
325     &
326     &
327     &
328     &
329     \\
330    
331    
332     \hline\member{setLevelMax}&
333     &
334     $\checkmark$ &
335     &
336     &
337     &
338     &
339     &
340     \\
341    
342     \hline\member{setCoarseningThreshold}&
343     &
344     $\checkmark$ &
345     &
346     &
347     &
348     &
349     &
350     \\
351    
352     \hline\member{setMinCoarseMatrixSize} &
353     &
354     $\checkmark$ &
355     &
356     &
357     &
358     &
359     &
360     \\
361    
362     \hline\member{setNumSweeps} &
363     &
364     &
365     $\checkmark$ &
366     $\checkmark$ &
367     &
368     &
369     &
370     \\
371    
372     \hline\member{setNumPreSweeps}&
373     &
374     $\checkmark$ &
375     &
376     &
377     &
378     &
379     &
380     \\
381    
382     \hline\member{setNumPostSweeps} &
383     &
384     $\checkmark$ &
385     &
386     &
387     &
388     &
389     &
390     \\
391    
392     \hline\member{setInnerTolerance}&
393     &
394     &
395     &
396     &
397     &
398     &
399     &
400     \\
401    
402     \hline\member{setDropTolerance}&
403     &
404     &
405     &
406     &
407     &
408     &
409     &
410     \\
411    
412     \hline\member{setDropStorage}&
413     &
414     &
415     &
416     &
417     &
418     &
419     &
420     \\
421    
422     \hline\member{setRelaxationFactor}&
423     &
424     &
425     &
426     &
427     &
428     $\checkmark$ &
429     &
430     \\
431    
432     \hline\member{adaptInnerTolerance}&
433     &
434     &
435     &
436     &
437     &
438     &
439     &
440     \\
441    
442     \hline\member{setInnerIterMax}&
443     &
444     &
445     &
446     &
447     &
448     &
449     &
450     \\
451     \end{tabular}
452     }
453     \caption{Preconditioners available for \finley and the \PASO package and the relevant options in \class{SolverOptions}. \label{TAB FINLEY SOLVER OPTIONS 2}}
454     \end{table}
455    
456     \subsection{Linear Solvers in \SolverOptions}
457     Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and
458     Table~\ref{TAB FINLEY SOLVER OPTIONS 2} show the solvers and preconditioners supported by
459     \finley through the \PASO library. Currently direct solvers are not supported under MPI.
460     By default, \finley is using the iterative solvers \PCG for symmetric and \BiCGStab for non-symmetric problems.
461     If the direct solver is selected which can be useful when solving very ill-posedequations
462 gross 2748 \finley uses the \MKL \footnote{If the stiffness matrix is non-regular \MKL may return without
463     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
464 gross 2558 a suitable iterative solver from the \PASO is used.
465    
466 jgs 102 \subsection{Functions}
467 gross 2690 \begin{funcdesc}{ReadMesh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True}}
468 jgs 102 creates a \Domain object form the FEM mesh defined in
469     file \var{fileName}. The file must be given the \finley file format.
470     If \var{integrationOrder} is positive, a numerical integration scheme
471     chosen which is accurate on each element up to a polynomial of
472     degree \var{integrationOrder} \index{integration order}. Otherwise
473 gross 2690 an appropriate integration order is chosen independently.
474     By default the labeling of mesh nodes and element distribution is
475     optimized. Set \var{optimize=False} to switch off relabeling and redistribution.
476     \end{funcdesc}
477    
478 gross 2748 \begin{funcdesc}{ReadGmsh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True\optional{, useMacroElements=False}}}
479 gross 2690 creates a \Domain object form the FEM mesh defined in
480     file \var{fileName}. The file must be given the \gmshextern file format.
481     If \var{integrationOrder} is positive, a numerical integration scheme
482     chosen which is accurate on each element up to a polynomial of
483     degree \var{integrationOrder} \index{integration order}. Otherwise
484 jgs 102 an appropriate integration order is chosen independently.
485 gross 2690 By default the labeling of mesh nodes and element distribution is
486     optimized. Set \var{optimize=False} to switch off relabeling and redistribution.
487 gross 2748 If \var{useMacroElements} is set, second order elements are interpreated as macro elements~\index{macro elements}.
488 gross 2690 Currently \function{ReadGmsh} does not support MPI.
489 jgs 102 \end{funcdesc}
490    
491 gross 2748 \begin{funcdesc}{MakeDomain}{design\optional{, integrationOrder=-1\optional{, optimizeLabeling=True\optional{, useMacroElements=False}}}}
492     Creates a Finley \Domain from a \class{Design} object using \gmshextern.
493     The \class{Design} \var{design} defines the geometry.
494     If \var{integrationOrder} is positive, a numerical integration scheme
495     chosen which is accurate on each element up to a polynomial of
496     degree \var{integrationOrder} \index{integration order}. Otherwise
497     an appropriate integration order is chosen independently.
498     Set \var{optimizeLabeling=False} to switch off relabeling and redistribution (not recommended).
499     If \var{useMacroElements} is set, macro elements~\index{macro elements} are used.
500     Currently \function{MakeDomain} does not support MPI.
501     \end{funcdesc}
502 gross 2690
503 gross 2748
504 gross 2417 \begin{funcdesc}{load}{fileName}
505     recovers a \Domain object from a dump file created by the \
506     eateseates a \Domain object form the FEM mesh defined in
507     file \var{fileName}. The file must be given the \finley file format.
508     If \var{integrationOrder} is positive, a numerical integration scheme
509     chosen which is accurate on each element up to a polynomial of
510     degree \var{integrationOrder} \index{integration order}. Otherwise
511     an appropriate integration order is chosen independently.
512     \end{funcdesc}
513    
514 gross 2748
515 jgs 102 \begin{funcdesc}{Rectangle}{n0,n1,order=1,l0=1.,l1=1., integrationOrder=-1, \\
516 gross 2748 periodic0=\False, periodic1=\False, useElementsOnFace=\False, useMacroElements=\False, optimize=\False}
517 jgs 102 Generates a \Domain object representing a two dimensional rectangle between
518     $(0,0)$ and $(l0,l1)$ with orthogonal edges. The rectangle is filled with
519     \var{n0} elements along the $x_0$-axis and
520     \var{n1} elements along the $x_1$-axis.
521     For \var{order}=1 and \var{order}=2
522     \finleyelement{Rec4} and
523     \finleyelement{Rec8} are used, respectively.
524     In the case of \var{useElementsOnFace}=\False,
525     \finleyelement{Line2} and
526     \finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively.
527 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}.
528 jgs 102 In the case of \var{useElementsOnFace}=\True (this option should be used if gradients
529     are calculated on domain faces),
530     \finleyelement{Rec4Face} and
531     \finleyelement{Rec8Face} are used on the edges, respectively.
532     If \var{integrationOrder} is positive, a numerical integration scheme
533     chosen which is accurate on each element up to a polynomial of
534     degree \var{integrationOrder} \index{integration order}. Otherwise
535     an appropriate integration order is chosen independently. If
536     \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions}
537     along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley
538     the value on the line $x_0=0$ will be identical to the values on $x_0=\var{l0}$.
539     Correspondingly,
540     \var{periodic1}=\False sets periodic boundary conditions
541     in $x_1$-direction.
542 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.
543 jgs 102 \end{funcdesc}
544    
545     \begin{funcdesc}{Brick}{n0,n1,n2,order=1,l0=1.,l1=1.,l2=1., integrationOrder=-1, \\
546 gross 2748 periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False, useMacroElements=\False, optimize=\False}
547 jgs 102 Generates a \Domain object representing a three dimensional brick between
548     $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with
549     \var{n0} elements along the $x_0$-axis,
550     \var{n1} elements along the $x_1$-axis and
551     \var{n2} elements along the $x_2$-axis.
552     For \var{order}=1 and \var{order}=2
553     \finleyelement{Hex8} and
554     \finleyelement{Hex20} are used, respectively.
555     In the case of \var{useElementsOnFace}=\False,
556     \finleyelement{Rec4} and
557     \finleyelement{Rec8} are used to subdivide the faces of the brick, respectively.
558     In the case of \var{useElementsOnFace}=\True (this option should be used if gradients
559     are calculated on domain faces),
560     \finleyelement{Hex8Face} and
561     \finleyelement{Hex20Face} are used on the brick faces, respectively.
562 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}.
563 jgs 102 If \var{integrationOrder} is positive, a numerical integration scheme
564     chosen which is accurate on each element up to a polynomial of
565     degree \var{integrationOrder} \index{integration order}. Otherwise
566     an appropriate integration order is chosen independently. If
567     \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions}
568     along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley
569     the value on the plane $x_0=0$ will be identical to the values on $x_0=\var{l0}$. Correspondingly,
570     \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions
571     in $x_1$-direction and $x_2$-direction, respectively.
572 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.
573 jgs 102 \end{funcdesc}
574    
575     \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
576 ksteube 1316 Generates a new \Domain object from the list \var{meshList} of \finley meshes.
577 jgs 102 Nodes in face elements whose difference of coordinates is less then \var{tolerance} times the
578     diameter of the domain are merged. The corresponding face elements are removed from the mesh.
579    
580     TODO: explain \var{safetyFactor} and show an example.
581     \end{funcdesc}
582    
583     \begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
584 ksteube 1316 Generates a new \Domain object from the list \var{meshList} of \finley meshes.
585 jgs 102 Face elements whose nodes coordinates have difference is less then \var{tolerance} times the
586     diameter of the domain are combined to form a contact element \index{element!contact}
587     The corresponding face elements are removed from the mesh.
588    
589     TODO: explain \var{safetyFactor} and show an example.
590     \end{funcdesc}

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26