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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 6678 - (hide annotations)
Mon Jun 11 04:05:30 2018 UTC (7 months, 1 week ago) by jfenwick
File MIME type: application/x-tex
File size: 27850 byte(s)
Fixing overfull hboxes

1 ksteube 1811
2 jfenwick 3989 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 jfenwick 6651 % Copyright (c) 2003-2018 by The University of Queensland
4 jfenwick 3989 % http://www.uq.edu.au
5 gross 625 %
6 ksteube 1811 % Primary Business: Queensland, Australia
7 jfenwick 6112 % Licensed under the Apache License, version 2.0
8     % http://www.apache.org/licenses/LICENSE-2.0
9 gross 625 %
10 jfenwick 3989 % Development until 2012 by Earth Systems Science Computational Center (ESSCC)
11 jfenwick 4657 % Development 2012-2013 by School of Earth Sciences
12     % Development from 2014 by Centre for Geoscience Computing (GeoComp)
13 jfenwick 3989 %
14     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15 jgs 102
16 caltinay 5295 \chapter{The \finley Module}\label{chap:finley}
17 caltinay 3306 %\declaremodule{extension}{finley}
18     %\modulesynopsis{Solving linear, steady partial differential equations using finite elements}
19 jgs 102
20 jfenwick 5658 The \finley library allows the creation of domains for solving
21     linear, steady partial differential
22 caltinay 4891 equations\index{partial differential equations} (PDEs) or systems
23 caltinay 3330 of PDEs using isoparametrical finite elements\index{FEM!isoparametrical}.
24     It supports unstructured 1D, 2D and 3D meshes.
25 jfenwick 5658 The PDEs themselves are represented by the \LinearPDE class
26     of \escript.
27     \finley is parallelized under both \OPENMP and \MPI.
28     A more restricted form of this library ({\it dudley}) is described in
29     Section~\ref{sec:dudley}.
30 jgs 102
31 gross 993 \section{Formulation}
32 caltinay 3330 For a single PDE that has a solution with a single component the linear PDE is
33     defined in the following form:
34 gross 993 \begin{equation}\label{FINLEY.SINGLE.1}
35     \begin{array}{cl} &
36     \displaystyle{
37 jfenwick 3295 \int_{\Omega}
38     A_{jl} \cdot v_{,j}u_{,l}+ B_{j} \cdot v_{,j} u+ C_{l} \cdot v u_{,l}+D \cdot vu \; d\Omega } \\
39     + & \displaystyle{\int_{\Gamma} d \cdot vu \; d{\Gamma} }
40     + \displaystyle{\int_{\Gamma^{contact}} d^{contact} \cdot [v][u] \; d{\Gamma} } \\
41     = & \displaystyle{\int_{\Omega} X_{j} \cdot v_{,j}+ Y \cdot v \; d\Omega }\\
42     + & \displaystyle{\int_{\Gamma} y \cdot v \; d{\Gamma}} +
43     \displaystyle{\int_{\Gamma^{contact}} y^{contact}\cdot [v] \; d{\Gamma}} \\
44 gross 993 \end{array}
45     \end{equation}
46    
47     \section{Meshes}
48 gross 2793 \label{FINLEY MESHES}
49 jgs 102
50 caltinay 3330 \begin{figure}
51     \centerline{\includegraphics{FinleyMesh}}
52     \caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})}
53     \label{FINLEY FIG 0}
54     \end{figure}
55    
56     To understand the usage of \finley one needs to have an understanding of how
57     the finite element meshes\index{FEM!mesh} are defined.
58     \fig{FINLEY FIG 0} shows an example of the subdivision of an ellipse into
59     so-called elements\index{FEM!elements}\index{element}.
60     In this case, triangles have been used but other forms of subdivisions can be
61     constructed, e.g. quadrilaterals or, in the three-dimensional case, into
62     tetrahedra and hexahedra. The idea of the finite element method is to
63     approximate the solution by a function which is a polynomial of a certain order
64     and is continuous across its boundary to neighbour elements.
65     In the example of \fig{FINLEY FIG 0} a linear polynomial is used on each
66     triangle. As one can see, the triangulation is quite a poor approximation of
67     the ellipse. It can be improved by introducing a midpoint on each element edge
68     then positioning those nodes located on an edge expected to describe the
69     boundary, onto the boundary.
70     In this case the triangle gets a curved edge which requires a parameterization
71     of the triangle using a quadratic polynomial.
72     For this case, the solution is also approximated by a piecewise quadratic
73     polynomial (which explains the name isoparametrical elements),
74     see \Ref{Zienc,NumHand} for more details.
75     \finley also supports macro elements\index{macro elements}.
76     For these elements a piecewise linear approximation is used on an element which
77     is further subdivided (in the case of \finley halved).
78     As such, these elements do not provide more than a further mesh refinement but
79     should be used in the case of incompressible flows, see \class{StokesProblemCartesian}.
80     For these problems a linear approximation of the pressure across the element is
81     used (use the \ReducedSolutionFS) while the refined element is used to
82     approximate velocity. So a macro element provides a continuous pressure
83     approximation together with a velocity approximation on a refined mesh.
84     This approach is necessary to make sure that the incompressible flow has a
85     unique solution.
86    
87 jgs 102 The union of all elements defines the domain of the PDE.
88 caltinay 3330 Each element is defined by the nodes used to describe its shape.
89     In \fig{FINLEY FIG 0} the element, which has type \finleyelement{Tri3}, with
90     element reference number $19$\index{element!reference number} is defined by the
91     nodes with reference numbers $9$, $11$ and $0$\index{node!reference number}.
92     Notice that the order is counterclockwise.
93     The coefficients of the PDE are evaluated at integration nodes with each
94     individual element.
95     For quadrilateral elements a Gauss quadrature scheme is used.
96     In the case of triangular elements a modified form is applied.
97     The boundary of the domain is also subdivided into elements\index{element!face}.
98     In \fig{FINLEY FIG 0} line elements with two nodes are used.
99     The elements are also defined by their describing nodes, e.g. the face element
100     with reference number $20$, which has type \finleyelement{Line2}, is defined by
101     the nodes with the reference numbers $11$ and $0$.
102     Again the order is crucial, if moving from the first to second node the domain
103     has to lie on the left hand side (in the case of a two-dimensional surface
104     element the domain has to lie on the left hand side when moving
105     counterclockwise). If the gradient on the surface of the domain is to be
106     calculated rich face elements need to be used. Rich elements on a face are
107     identical to interior elements but with a modified order of nodes such that the
108     'first' face of the element aligns with the surface of the domain.
109     In \fig{FINLEY FIG 0} elements of the type \finleyelement{Tri3Face} are used.
110     The face element reference number $20$ as a rich face element is defined by the
111     nodes with reference numbers $11$, $0$ and $9$.
112     Notice that the face element $20$ is identical to the interior element $19$
113     except that, in this case, the order of the node is different to align the first
114     edge of the triangle (which is the edge starting with the first node) with the
115     boundary of the domain.
116 jgs 102
117 caltinay 3330 Be aware that face elements and elements in the interior of the domain must
118     match, i.e. a face element must be the face of an interior element or, in case
119     of a rich face element, it must be identical to an interior element.
120     If no face elements are specified \finley implicitly assumes homogeneous
121     natural boundary conditions\index{natural boundary conditions!homogeneous},
122     i.e. \var{d}=$0$ and \var{y}=$0$, on the entire boundary of the domain.
123     For inhomogeneous natural boundary conditions\index{natural boundary conditions!inhomogeneous},
124 caltinay 3293 the boundary must be described by face elements.
125 jgs 102
126 caltinay 3330 \begin{figure}
127     \centerline{\includegraphics{FinleyContact}}
128     \caption{Mesh around a contact region (\finleyelement{Rec4})}
129     \label{FINLEY FIG 01}
130     \end{figure}
131 jgs 102
132 caltinay 3330 If discontinuities of the PDE solution are considered, contact
133     elements\index{element!contact}\index{contact conditions} are introduced to
134     describe the contact region $\Gamma^{contact}$ even if $d^{contact}$ and
135     $y^{contact}$ are zero.
136     \fig{FINLEY FIG 01} shows a simple example of a mesh of rectangular elements
137     around a contact region $\Gamma^{contact}$\index{element!contact}.
138     The contact region is described by the elements $4$, $3$ and $6$.
139     Their element type is \finleyelement{Line2_Contact}.
140     The nodes $9$, $12$, $6$ and $5$ define contact element $4$, where the
141     coordinates of nodes $12$ and $5$ and nodes $4$ and $6$ are identical, with the
142     idea that nodes $12$ and $9$ are located above and nodes $5$ and $6$ below the
143     contact region.
144     Again, the order of the nodes within an element is crucial.
145     There is also the option of using rich elements if the gradient is to be
146     calculated on the contact region. Similarly to the rich face elements these
147     are constructed from two interior elements by reordering the nodes such that
148     the 'first' face of the element above and the 'first' face of the element below
149     the contact regions line up. The rich version of element $4$ is of type
150     \finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$,
151     $18$, $6$, $5$, $0$ and $2$.
152     \tab{FINLEY TAB 1} shows the interior element types and the corresponding
153     element types to be used on the face and contacts.
154     \fig{FINLEY.FIG:1}, \fig{FINLEY.FIG:2} and \fig{FINLEY.FIG:4} show the ordering
155     of the nodes within an element.
156 gross 2748
157 jgs 102 \begin{table}
158 caltinay 3293 \centering
159     \begin{tabular}{l|llll}
160 caltinay 3330 \textbf{interior}&\textbf{face}&\textbf{rich face}&\textbf{contact}&\textbf{rich contact}\\
161 caltinay 3293 \hline
162     \finleyelement{Line2} & \finleyelement{Point1} & \finleyelement{Line2Face} & \finleyelement{Point1_Contact} & \finleyelement{Line2Face_Contact}\\
163     \finleyelement{Line3} & \finleyelement{Point1} & \finleyelement{Line3Face} & \finleyelement{Point1_Contact} & \finleyelement{Line3Face_Contact}\\
164     \finleyelement{Tri3} & \finleyelement{Line2} & \finleyelement{Tri3Face} & \finleyelement{Line2_Contact} & \finleyelement{Tri3Face_Contact}\\
165     \finleyelement{Tri6} & \finleyelement{Line3} & \finleyelement{Tri6Face} & \finleyelement{Line3_Contact} & \finleyelement{Tri6Face_Contact}\\
166     \finleyelement{Rec4} & \finleyelement{Line2} & \finleyelement{Rec4Face} & \finleyelement{Line2_Contact} & \finleyelement{Rec4Face_Contact}\\
167     \finleyelement{Rec8} & \finleyelement{Line3} & \finleyelement{Rec8Face} & \finleyelement{Line3_Contact} & \finleyelement{Rec8Face_Contact}\\
168     \finleyelement{Rec9} & \finleyelement{Line3} & \finleyelement{Rec9Face} & \finleyelement{Line3_Contact} & \finleyelement{Rec9Face_Contact}\\
169     \finleyelement{Tet4} & \finleyelement{Tri6} & \finleyelement{Tet4Face} & \finleyelement{Tri6_Contact} & \finleyelement{Tet4Face_Contact}\\
170     \finleyelement{Tet10} & \finleyelement{Tri9} & \finleyelement{Tet10Face} & \finleyelement{Tri9_Contact} & \finleyelement{Tet10Face_Contact}\\
171     \finleyelement{Hex8} & \finleyelement{Rec4} & \finleyelement{Hex8Face} & \finleyelement{Rec4_Contact} & \finleyelement{Hex8Face_Contact}\\
172     \finleyelement{Hex20} & \finleyelement{Rec8} & \finleyelement{Hex20Face} & \finleyelement{Rec8_Contact} & \finleyelement{Hex20Face_Contact}\\
173 caltinay 3330 \finleyelement{Hex27} & \finleyelement{Rec9} & N/A & N/A & N/A\\
174     \finleyelement{Hex27Macro} & \finleyelement{Rec9Macro} & N/A & N/A & N/A\\
175     \finleyelement{Tet10Macro} & \finleyelement{Tri6Macro} & N/A & N/A & N/A\\
176     \finleyelement{Rec9Macro} & \finleyelement{Line3Macro} & N/A & N/A & N/A\\
177     \finleyelement{Tri6Macro} & \finleyelement{Line3Macro} & N/A & N/A & N/A\\
178 caltinay 3293 \end{tabular}
179 caltinay 3330 \caption{Finley elements and corresponding elements to be used on domain faces
180     and contacts.
181     The rich types have to be used if the gradient of the function is to be
182     calculated on faces and contacts, respectively.}
183 jgs 102 \label{FINLEY TAB 1}
184     \end{table}
185    
186     The native \finley file format is defined as follows.
187 caltinay 3330 Each node \var{i} has \var{dim} spatial coordinates \var{Node[i]}, a reference
188     number \var{Node_ref[i]}, a degree of freedom \var{Node_DOF[i]} and a tag
189     \var{Node_tag[i]}.
190     In most cases \var{Node_DOF[i]}=\var{Node_ref[i]} however, for periodic
191     boundary conditions, \var{Node_DOF[i]} is chosen differently, see example below.
192     The tag can be used to mark nodes sharing the same properties.
193     Element \var{i} is defined by the \var{Element_numNodes} nodes
194     \var{Element_Nodes[i]} which is a list of node reference numbers.
195     The order of these is crucial. Each element has a reference number
196     \var{Element_ref[i]} and a tag \var{Element_tag[i]}.
197     The tag can be used to mark elements sharing the same properties.
198     For instance elements above a contact region are marked with tag $2$ and
199     elements below a contact region are marked with tag $1$.
200     \var{Element_Type} and \var{Element_Num} give the element type and the number
201     of elements in the mesh.
202     Analogue notations are used for face and contact elements.
203     The following \PYTHON script prints the mesh definition in the \finley file
204     format:
205 jgs 102 \begin{python}
206 caltinay 3330 print("%s\n"%mesh_name)
207     # node coordinates:
208     print("%dD-nodes %d\n"%(dim, numNodes))
209     for i in range(numNodes):
210     print("%d %d %d"%(Node_ref[i], Node_DOF[i], Node_tag[i]))
211     for j in range(dim): print(" %e"%Node[i][j])
212     print("\n")
213     # interior elements
214     print("%s %d\n"%(Element_Type, Element_Num))
215     for i in range(Element_Num):
216     print("%d %d"%(Element_ref[i], Element_tag[i]))
217     for j in range(Element_numNodes): print(" %d"%Element_Nodes[i][j])
218     print("\n")
219     # face elements
220     print("%s %d\n"%(FaceElement_Type, FaceElement_Num))
221     for i in range(FaceElement_Num):
222     print("%d %d"%(FaceElement_ref[i], FaceElement_tag[i]))
223     for j in range(FaceElement_numNodes): print(" %d"%FaceElement_Nodes[i][j])
224     print("\n")
225     # contact elements
226     print("%s %d\n"%(ContactElement_Type, ContactElement_Num))
227     for i in range(ContactElement_Num):
228     print("%d %d"%(ContactElement_ref[i], ContactElement_tag[i]))
229 jfenwick 6678 for j in range(ContactElement_numNodes):
230     print(" %d"%ContactElement_Nodes[i][j])
231 caltinay 3330 print("\n")
232     # point sources (not supported yet)
233     print("Point1 0")
234 jgs 102 \end{python}
235    
236     The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}:
237     \begin{verbatim}
238     Example 1
239     2D Nodes 16
240     0 0 0 0. 0.
241     2 2 0 0.33 0.
242     3 3 0 0.66 0.
243     7 4 0 1. 0.
244     5 5 0 0. 0.5
245     6 6 0 0.33 0.5
246     8 8 0 0.66 0.5
247     10 10 0 1.0 0.5
248     12 12 0 0. 0.5
249     9 9 0 0.33 0.5
250     13 13 0 0.66 0.5
251     15 15 0 1.0 0.5
252     16 16 0 0. 1.0
253     18 18 0 0.33 1.0
254     19 19 0 0.66 1.0
255     20 20 0 1.0 1.0
256     Rec4 6
257     0 1 0 2 6 5
258     1 1 2 3 8 6
259     2 1 3 7 10 8
260     5 2 12 9 18 16
261     7 2 13 19 18 9
262     10 2 20 19 13 15
263     Line2 0
264     Line2_Contact 3
265     4 0 9 12 6 5
266     3 0 13 9 8 6
267     6 0 15 13 10 8
268     Point1 0
269     \end{verbatim}
270     Notice that the order in which the nodes and elements are given is arbitrary.
271 caltinay 3330 In the case that rich contact elements are used the contact element section
272     gets the form
273 jgs 102 \begin{verbatim}
274     Rec4Face_Contact 3
275     4 0 9 12 16 18 6 5 0 2
276     3 0 13 9 18 19 8 6 2 3
277     6 0 15 13 19 20 10 8 3 7
278     \end{verbatim}
279 caltinay 3330 Periodic boundary conditions\index{boundary conditions!periodic} can be
280     introduced by altering \var{Node_DOF}.
281     It allows identification of nodes even if they have different physical locations.
282     For instance, to enforce periodic boundary conditions at the face $x_0=0$ and
283     $x_0=1$ one identifies the degrees of freedom for nodes $0$, $5$, $12$ and $16$
284     with the degrees of freedom for $7$, $10$, $15$ and $20$, respectively.
285     The node section of the \finley mesh now reads:
286 jgs 102 \begin{verbatim}
287     2D Nodes 16
288     0 0 0 0. 0.
289     2 2 0 0.33 0.
290     3 3 0 0.66 0.
291     7 0 0 1. 0.
292     5 5 0 0. 0.5
293     6 6 0 0.33 0.5
294     8 8 0 0.66 0.5
295     10 5 0 1.0 0.5
296     12 12 0 0. 0.5
297     9 9 0 0.33 0.5
298     13 13 0 0.66 0.5
299     15 12 0 1.0 0.5
300     16 16 0 0. 1.0
301     18 18 0 0.33 1.0
302     19 19 0 0.66 1.0
303     20 16 0 1.0 1.0
304     \end{verbatim}
305    
306 jfenwick 1955 \clearpage
307     \input{finleyelements}
308     \clearpage
309 jgs 102
310 caltinay 3330 \section{Macro Elements}
311     \label{SEC FINLEY MACRO}
312    
313 gross 2793 \begin{figure}[th]
314     \begin{center}
315 caltinay 3330 \includegraphics{FinleyMacroLeg}\\
316     \subfigure[Triangle]{\label{FINLEY MACRO TRI}\includegraphics{FinleyMacroTri}}\quad
317     \subfigure[Quadrilateral]{\label{FINLEY MACRO REC}\includegraphics{FinleyMacroRec}}
318 gross 2793 \end{center}
319 caltinay 3330 \caption{Macro elements in \finley}
320 gross 2793 \end{figure}
321    
322 caltinay 3330 \finley supports the usage of macro elements\index{macro elements} which can be
323     used to achieve LBB compliance when solving incompressible fluid flow problems.
324     LBB compliance is required to get a problem which has a unique solution for
325     pressure and velocity. For macro elements the pressure and velocity are
326     approximated by a polynomial of order 1 but the velocity approximation bases on
327     a refinement of the elements. The nodes of a triangle and quadrilateral element
328     are shown in Figures~\ref{FINLEY MACRO TRI} and~\ref{FINLEY MACRO REC},
329     respectively. In essence, the velocity uses the same nodes like a quadratic
330     polynomial approximation but replaces the quadratic polynomial by piecewise
331     linear polynomials. In fact, this is the way \finley defines the macro elements.
332     In particular \finley uses the same local ordering of the nodes for the macro
333     element as for the corresponding quadratic element. Another interpretation is
334     that one uses a linear approximation of the velocity together with a linear
335     approximation of the pressure but on elements created by combining elements to
336     macro elements. Notice that the macro elements still use quadratic
337     interpolation to represent the element and domain boundary.
338     However, if elements have linear boundaries a macro element approximation for
339     the velocity is equivalent to using a linear approximation on a mesh which is
340     created through a one-step global refinement.
341     Typically macro elements are only required to use when an incompressible fluid
342     flow problem is solved, e.g. the Stokes problem in \Sec{STOKES PROBLEM}.
343     Please see \Sec{FINLEY MESHES} for more details on the supported macro elements.
344 jgs 102
345 caltinay 3330 \section{Linear Solvers in \SolverOptions}
346 gross 2748
347 caltinay 3330 Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and
348     Table~\ref{TAB FINLEY SOLVER OPTIONS 2} show the solvers and preconditioners
349     supported by \finley through the \PASO library.
350     Currently direct solvers are not supported under \MPI.
351     By default, \finley uses the iterative solvers \PCG for symmetric and \BiCGStab
352     for non-symmetric problems.
353     If the direct solver is selected, which can be useful when solving very
354     ill-posed equations, \finley uses the \MKL\footnote{If the stiffness matrix is
355     non-regular \MKL may return without a proper error code. If you observe
356     suspicious solutions when using \MKL, this may be caused by a non-invertible
357     operator.} solver package. If \MKL is not available \UMFPACK is used.
358     If \UMFPACK is not available a suitable iterative solver from \PASO is used.
359 gross 2748
360 gross 2558 \begin{table}
361 caltinay 3330 \centering
362 jfenwick 2651 {\scriptsize
363 gross 2558 \begin{tabular}{l||c|c|c|c|c|c|c|c}
364 gross 3379 \member{setSolverMethod} & \member{DIRECT}& \member{PCG} & \member{GMRES} & \member{TFQMR} & \member{MINRES} & \member{PRES20} & \member{BICGSTAB} & lumping \\
365 gross 2558 \hline
366     \hline
367     \member{setReordering} & $\checkmark$ & & & & & &\\
368     \hline \member{setRestart} & & & $\checkmark$ & & & $20$ & \\
369     \hline\member{setTruncation} & & & $\checkmark$ & & & $5$ & \\
370     \hline\member{setIterMax} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
371     \hline\member{setTolerance} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
372     \hline\member{setAbsoluteTolerance} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
373 gross 2573 \hline\member{setReordering} & $\checkmark$ & & & & & & & \\
374 gross 2558 \end{tabular}
375     }
376 caltinay 3330 \caption{Solvers available for \finley and the \PASO package and the relevant
377     options in \class{SolverOptions}.
378     \MKL supports \member{MINIMUM_FILL_IN}\index{linear solver!minimum fill-in ordering}\index{minimum fill-in ordering}
379     and \member{NESTED_DISSECTION}\index{linear solver!nested dissection ordering}\index{nested dissection}
380 caltinay 3293 reordering.
381     Currently the \UMFPACK interface does not support any reordering.
382 caltinay 3330 \label{TAB FINLEY SOLVER OPTIONS 1}}
383 caltinay 3293 \end{table}
384 gross 2558
385     \begin{table}
386 jfenwick 3616 \begin{center}
387 gross 2558 {\scriptsize
388 gross 3439 \begin{tabular}{l||c|c|c|c|c|c|c}
389 caltinay 3330 \member{NO_PRECONDITIONER}&
390     \member{AMG}&
391     \member{JACOBI}&
392 caltinay 3293 \member{GAUSS_SEIDEL}&
393 gross 2558 \member{REC_ILU}&
394 caltinay 3330 \member{RILU}&
395     \member{ILU0}&
396     \member{DIRECT}\\
397 gross 2558 \hline
398 gross 3439 status:& $\checkmark$ &$\checkmark$&$\checkmark$&$\checkmark$&later&$\checkmark$&later\\
399 gross 2558 \hline
400 caltinay 3330 \hline
401 gross 3439 \member{setLevelMax}&$\checkmark$& & & & & &\\
402 caltinay 3330 \hline
403 gross 3439 \member{setCoarseningThreshold}&$\checkmark$& & & & & &\\
404 caltinay 3330 \hline
405 gross 3439 \member{setMinCoarseMatrixSize}&$\checkmark$& & & & & &\\
406 caltinay 3330 \hline
407 gross 3439 \member{setMinCoarseMatrixSparsity}&$\checkmark$& & & & & &\\
408 gross 3353 \hline
409 gross 3439 \member{setNumSweeps}& &$\checkmark$&$\checkmark$& & & &\\
410 caltinay 3330 \hline
411 gross 3439 \member{setNumPreSweeps}&$\checkmark$& & & & & &\\
412 caltinay 3330 \hline
413 gross 3439 \member{setNumPostSweeps}&$\checkmark$& & & & & &\\
414 caltinay 3330 \hline
415 gross 3439 \member{setDiagonalDominanceThreshold}&$\checkmark$& & & & & &\\
416 gross 3402 \hline
417 gross 3439 \member{setAMGInterpolation}&$\checkmark$& & & & & &\\
418     \hline
419     \member{setRelaxationFactor}& & & & &$\checkmark$& &\\
420 gross 2558 \end{tabular}
421     }
422 caltinay 3330 \caption{Preconditioners available for \finley and the \PASO package and the
423     relevant options in \class{SolverOptions}.
424     \label{TAB FINLEY SOLVER OPTIONS 2}}
425 jfenwick 3616 \end{center}
426 gross 2558 \end{table}
427    
428 gross 2793 \section{Functions}
429 gross 2690 \begin{funcdesc}{ReadMesh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True}}
430 caltinay 3330 creates a \Domain object from the FEM mesh defined in file \var{fileName}.
431     The file must be in the \finley file format.
432     If \var{integrationOrder} is positive, a numerical integration scheme is chosen
433     which is accurate on each element up to a polynomial of degree
434     \var{integrationOrder}\index{integration order}.
435     Otherwise an appropriate integration order is chosen independently.
436     By default the labeling of mesh nodes and element distribution is optimized.
437     Set \var{optimize=False} to switch off relabeling and redistribution.
438 gross 2690 \end{funcdesc}
439    
440 gross 3625 \begin{funcdesc}{ReadGmsh}{fileName, numDim, \optional{, \optional{integrationOrder=-1}, optimize=True\optional{, useMacroElements=False}}}
441     creates a \Domain object from the FEM mesh defined in file \var{fileName} for
442     a domain of dimension \var{numDim}.
443 caltinay 3330 The file must be in the \gmshextern file format.
444     If \var{integrationOrder} is positive, a numerical integration scheme is chosen
445     which is accurate on each element up to a polynomial of degree
446     \var{integrationOrder}\index{integration order}.
447     Otherwise an appropriate integration order is chosen independently.
448     By default the labeling of mesh nodes and element distribution is optimized.
449     Set \var{optimize=False} to switch off relabeling and redistribution.
450     If \var{useMacroElements} is set, second order elements are interpreted as
451     macro elements\index{macro elements}.
452 jgs 102 \end{funcdesc}
453    
454 gross 2748 \begin{funcdesc}{MakeDomain}{design\optional{, integrationOrder=-1\optional{, optimizeLabeling=True\optional{, useMacroElements=False}}}}
455 caltinay 3330 creates a \finley \Domain from a \pycad \class{Design} object using \gmshextern.
456 gross 2748 The \class{Design} \var{design} defines the geometry.
457 caltinay 3330 If \var{integrationOrder} is positive, a numerical integration scheme is chosen
458     which is accurate on each element up to a polynomial of degree
459     \var{integrationOrder}\index{integration order}.
460     Otherwise an appropriate integration order is chosen independently.
461     Set \var{optimizeLabeling=False} to switch off relabeling and redistribution
462     (not recommended).
463     If \var{useMacroElements} is set, macro elements\index{macro elements} are used.
464     Currently \function{MakeDomain} does not support \MPI.
465 gross 2748 \end{funcdesc}
466 gross 2690
467 gross 2417 \begin{funcdesc}{load}{fileName}
468 caltinay 3330 recovers a \Domain object from a dump file \var{fileName} created by the
469     \function{dump} method of a \Domain object.
470 gross 2417 \end{funcdesc}
471    
472 jgs 102 \begin{funcdesc}{Rectangle}{n0,n1,order=1,l0=1.,l1=1., integrationOrder=-1, \\
473 gross 3904 periodic0=\False, periodic1=\False, useElementsOnFace=\False, optimize=\False}
474 caltinay 3330 generates a \Domain object representing a two-dimensional rectangle between
475     $(0,0)$ and $(l0,l1)$ with orthogonal edges.
476     The rectangle is filled with \var{n0} elements along the $x_0$-axis and
477 caltinay 3293 \var{n1} elements along the $x_1$-axis.
478 caltinay 3330 For \var{order}=1 and \var{order}=2, elements of type \finleyelement{Rec4} and
479 caltinay 3293 \finleyelement{Rec8} are used, respectively.
480 caltinay 3330 In the case of \var{useElementsOnFace}=\False, \finleyelement{Line2} and
481 caltinay 3293 \finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively.
482 caltinay 3330 If \var{order}=-1, \finleyelement{Rec8Macro} and \finleyelement{Line3Macro}\index{macro elements}
483     are used. This option should be used when solving incompressible fluid flow
484     problems, e.g. \class{StokesProblemCartesian}.
485     In the case of \var{useElementsOnFace}=\True (this option should be used if
486     gradients are calculated on domain faces), \finleyelement{Rec4Face} and
487 caltinay 3293 \finleyelement{Rec8Face} are used on the edges, respectively.
488 caltinay 3330 If \var{integrationOrder} is positive, a numerical integration scheme is chosen
489     which is accurate on each element up to a polynomial of degree
490     \var{integrationOrder}\index{integration order}.
491     Otherwise an appropriate integration order is chosen independently.
492     If \var{periodic0}=\True, periodic boundary conditions\index{periodic boundary conditions}
493     along the $x_0$-direction are enforced.
494     That means for any solution of a PDE solved by \finley the values on the line
495     $x_0=0$ will be identical to the values on $x_0=\var{l0}$.
496     Correspondingly, \var{periodic1}=\True sets periodic boundary conditions in the
497     $x_1$-direction.
498     If \var{optimize}=\True mesh node relabeling will be attempted to reduce the
499     computation and also ParMETIS will be used to improve the mesh partition if
500     running on multiple CPUs with \MPI.
501 jgs 102 \end{funcdesc}
502    
503 jfenwick 3301 \begin{funcdesc}{Brick}{n0,n1,n2,order=1,l0=1.,l1=1.,l2=1., integrationOrder=-1,
504 jduplessis 5677 periodic0=\False, periodic1=\False, \\ periodic2=\False, useElementsOnFace=\False,useFullElementOrder=\False, optimize=\False}
505 caltinay 3330 generates a \Domain object representing a three-dimensional brick between
506 jgs 102 $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with
507 caltinay 3293 \var{n0} elements along the $x_0$-axis,
508     \var{n1} elements along the $x_1$-axis and
509     \var{n2} elements along the $x_2$-axis.
510 caltinay 3330 For \var{order}=1 and \var{order}=2, elements of type \finleyelement{Hex8} and
511 caltinay 3293 \finleyelement{Hex20} are used, respectively.
512 caltinay 3330 In the case of \var{useElementsOnFace}=\False, \finleyelement{Rec4} and
513 caltinay 3293 \finleyelement{Rec8} are used to subdivide the faces of the brick, respectively.
514 caltinay 3330 In the case of \var{useElementsOnFace}=\True (this option should be used if
515     gradients are calculated on domain faces), \finleyelement{Hex8Face} and
516 caltinay 3293 \finleyelement{Hex20Face} are used on the brick faces, respectively.
517 caltinay 3330 If \var{order}=-1, \finleyelement{Hex20Macro} and \finleyelement{Rec8Macro}\index{macro elements}
518     are used. This option should be used when solving incompressible fluid flow
519     problems, e.g. \class{StokesProblemCartesian}.
520     If \var{integrationOrder} is positive, a numerical integration scheme is chosen
521     which is accurate on each element up to a polynomial of degree
522     \var{integrationOrder}\index{integration order}.
523     Otherwise an appropriate integration order is chosen independently.
524     If \var{periodic0}=\True, periodic boundary conditions\index{periodic boundary conditions}
525     along the $x_0$-direction are enforced.
526     That means for any solution of a PDE solved by \finley the values on the plane
527     $x_0=0$ will be identical to the values on $x_0=\var{l0}$.
528     Correspondingly, \var{periodic1}=\True and \var{periodic2}=\True sets periodic
529     boundary conditions in the $x_1$-direction and $x_2$-direction, respectively.
530     If \var{optimize}=\True mesh node relabeling will be attempted to reduce the
531     computation and also ParMETIS will be used to improve the mesh partition if
532     running on multiple CPUs with \MPI.
533 jgs 102 \end{funcdesc}
534    
535 gross 3567 \begin{funcdesc}{GlueFaces}{meshList, tolerance=1.e-13}
536 caltinay 3330 generates a new \Domain object from the list \var{meshList} of \finley meshes.
537     Nodes in face elements whose difference of coordinates is less than
538     \var{tolerance} times the diameter of the domain are merged.
539     The corresponding face elements are removed from the mesh.
540 gross 3567 \function{GlueFaces} is not supported under \MPI with more than one rank.
541 jgs 102 \end{funcdesc}
542    
543 gross 3567 \begin{funcdesc}{JoinFaces}{meshList, tolerance=1.e-13}
544 caltinay 3330 generates a new \Domain object from the list \var{meshList} of \finley meshes.
545     Face elements whose node coordinates differ by less than \var{tolerance} times
546     the diameter of the domain are combined to form a contact element\index{element!contact}.
547 caltinay 3293 The corresponding face elements are removed from the mesh.
548 gross 3567 \function{JoinFaces} is not supported under \MPI with more than one rank.
549 caltinay 3330 \end{funcdesc}
550 jgs 102
551 jfenwick 5658 \section{\dudley}
552     \label{sec:dudley}
553     The {\it dudley} library is a restricted version of {\it finley}.
554     So in many ways it can be used as a ``drop-in'' replacement.
555     Dudley domains are simpler in that only triangular (2D), tetrahedral (3D) and line elements are supported.
556     Note, this also means that dudley does not support:
557     \begin{itemize}
558     \item dirac delta functions
559     \item contact elements
560     \item macro elements
561     \end{itemize}
562    

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26