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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5677 - (show annotations)
Mon Jun 22 08:05:28 2015 UTC (3 years, 10 months ago) by jduplessis
File MIME type: application/x-tex
File size: 27850 byte(s)
brick and rectangle documentations updates

1
2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 % Copyright (c) 2003-2015 by The University of Queensland
4 % http://www.uq.edu.au
5 %
6 % Primary Business: Queensland, Australia
7 % Licensed under the Open Software License version 3.0
8 % http://www.opensource.org/licenses/osl-3.0.php
9 %
10 % Development until 2012 by Earth Systems Science Computational Center (ESSCC)
11 % Development 2012-2013 by School of Earth Sciences
12 % Development from 2014 by Centre for Geoscience Computing (GeoComp)
13 %
14 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15
16 \chapter{The \finley Module}\label{chap:finley}
17 %\declaremodule{extension}{finley}
18 %\modulesynopsis{Solving linear, steady partial differential equations using finite elements}
19
20 The \finley library allows the creation of domains for solving
21 linear, steady partial differential
22 equations\index{partial differential equations} (PDEs) or systems
23 of PDEs using isoparametrical finite elements\index{FEM!isoparametrical}.
24 It supports unstructured 1D, 2D and 3D meshes.
25 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
31 \section{Formulation}
32 For a single PDE that has a solution with a single component the linear PDE is
33 defined in the following form:
34 \begin{equation}\label{FINLEY.SINGLE.1}
35 \begin{array}{cl} &
36 \displaystyle{
37 \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 \end{array}
45 \end{equation}
46
47 \section{Meshes}
48 \label{FINLEY MESHES}
49
50 \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 The union of all elements defines the domain of the PDE.
88 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
117 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 the boundary must be described by face elements.
125
126 \begin{figure}
127 \centerline{\includegraphics{FinleyContact}}
128 \caption{Mesh around a contact region (\finleyelement{Rec4})}
129 \label{FINLEY FIG 01}
130 \end{figure}
131
132 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
157 \begin{table}
158 \centering
159 \begin{tabular}{l|llll}
160 \textbf{interior}&\textbf{face}&\textbf{rich face}&\textbf{contact}&\textbf{rich contact}\\
161 \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 \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 \end{tabular}
179 \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 \label{FINLEY TAB 1}
184 \end{table}
185
186 The native \finley file format is defined as follows.
187 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 \begin{python}
206 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 for j in range(ContactElement_numNodes): print(" %d"%ContactElement_Nodes[i][j])
230 print("\n")
231 # point sources (not supported yet)
232 print("Point1 0")
233 \end{python}
234
235 The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}:
236 \begin{verbatim}
237 Example 1
238 2D Nodes 16
239 0 0 0 0. 0.
240 2 2 0 0.33 0.
241 3 3 0 0.66 0.
242 7 4 0 1. 0.
243 5 5 0 0. 0.5
244 6 6 0 0.33 0.5
245 8 8 0 0.66 0.5
246 10 10 0 1.0 0.5
247 12 12 0 0. 0.5
248 9 9 0 0.33 0.5
249 13 13 0 0.66 0.5
250 15 15 0 1.0 0.5
251 16 16 0 0. 1.0
252 18 18 0 0.33 1.0
253 19 19 0 0.66 1.0
254 20 20 0 1.0 1.0
255 Rec4 6
256 0 1 0 2 6 5
257 1 1 2 3 8 6
258 2 1 3 7 10 8
259 5 2 12 9 18 16
260 7 2 13 19 18 9
261 10 2 20 19 13 15
262 Line2 0
263 Line2_Contact 3
264 4 0 9 12 6 5
265 3 0 13 9 8 6
266 6 0 15 13 10 8
267 Point1 0
268 \end{verbatim}
269 Notice that the order in which the nodes and elements are given is arbitrary.
270 In the case that rich contact elements are used the contact element section
271 gets the form
272 \begin{verbatim}
273 Rec4Face_Contact 3
274 4 0 9 12 16 18 6 5 0 2
275 3 0 13 9 18 19 8 6 2 3
276 6 0 15 13 19 20 10 8 3 7
277 \end{verbatim}
278 Periodic boundary conditions\index{boundary conditions!periodic} can be
279 introduced by altering \var{Node_DOF}.
280 It allows identification of nodes even if they have different physical locations.
281 For instance, to enforce periodic boundary conditions at the face $x_0=0$ and
282 $x_0=1$ one identifies the degrees of freedom for nodes $0$, $5$, $12$ and $16$
283 with the degrees of freedom for $7$, $10$, $15$ and $20$, respectively.
284 The node section of the \finley mesh now reads:
285 \begin{verbatim}
286 2D Nodes 16
287 0 0 0 0. 0.
288 2 2 0 0.33 0.
289 3 3 0 0.66 0.
290 7 0 0 1. 0.
291 5 5 0 0. 0.5
292 6 6 0 0.33 0.5
293 8 8 0 0.66 0.5
294 10 5 0 1.0 0.5
295 12 12 0 0. 0.5
296 9 9 0 0.33 0.5
297 13 13 0 0.66 0.5
298 15 12 0 1.0 0.5
299 16 16 0 0. 1.0
300 18 18 0 0.33 1.0
301 19 19 0 0.66 1.0
302 20 16 0 1.0 1.0
303 \end{verbatim}
304
305 \clearpage
306 \input{finleyelements}
307 \clearpage
308
309 \section{Macro Elements}
310 \label{SEC FINLEY MACRO}
311
312 \begin{figure}[th]
313 \begin{center}
314 \includegraphics{FinleyMacroLeg}\\
315 \subfigure[Triangle]{\label{FINLEY MACRO TRI}\includegraphics{FinleyMacroTri}}\quad
316 \subfigure[Quadrilateral]{\label{FINLEY MACRO REC}\includegraphics{FinleyMacroRec}}
317 \end{center}
318 \caption{Macro elements in \finley}
319 \end{figure}
320
321 \finley supports the usage of macro elements\index{macro elements} which can be
322 used to achieve LBB compliance when solving incompressible fluid flow problems.
323 LBB compliance is required to get a problem which has a unique solution for
324 pressure and velocity. For macro elements the pressure and velocity are
325 approximated by a polynomial of order 1 but the velocity approximation bases on
326 a refinement of the elements. The nodes of a triangle and quadrilateral element
327 are shown in Figures~\ref{FINLEY MACRO TRI} and~\ref{FINLEY MACRO REC},
328 respectively. In essence, the velocity uses the same nodes like a quadratic
329 polynomial approximation but replaces the quadratic polynomial by piecewise
330 linear polynomials. In fact, this is the way \finley defines the macro elements.
331 In particular \finley uses the same local ordering of the nodes for the macro
332 element as for the corresponding quadratic element. Another interpretation is
333 that one uses a linear approximation of the velocity together with a linear
334 approximation of the pressure but on elements created by combining elements to
335 macro elements. Notice that the macro elements still use quadratic
336 interpolation to represent the element and domain boundary.
337 However, if elements have linear boundaries a macro element approximation for
338 the velocity is equivalent to using a linear approximation on a mesh which is
339 created through a one-step global refinement.
340 Typically macro elements are only required to use when an incompressible fluid
341 flow problem is solved, e.g. the Stokes problem in \Sec{STOKES PROBLEM}.
342 Please see \Sec{FINLEY MESHES} for more details on the supported macro elements.
343
344 \section{Linear Solvers in \SolverOptions}
345
346 Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and
347 Table~\ref{TAB FINLEY SOLVER OPTIONS 2} show the solvers and preconditioners
348 supported by \finley through the \PASO library.
349 Currently direct solvers are not supported under \MPI.
350 By default, \finley uses the iterative solvers \PCG for symmetric and \BiCGStab
351 for non-symmetric problems.
352 If the direct solver is selected, which can be useful when solving very
353 ill-posed equations, \finley uses the \MKL\footnote{If the stiffness matrix is
354 non-regular \MKL may return without a proper error code. If you observe
355 suspicious solutions when using \MKL, this may be caused by a non-invertible
356 operator.} solver package. If \MKL is not available \UMFPACK is used.
357 If \UMFPACK is not available a suitable iterative solver from \PASO is used.
358
359 \begin{table}
360 \centering
361 {\scriptsize
362 \begin{tabular}{l||c|c|c|c|c|c|c|c}
363 \member{setSolverMethod} & \member{DIRECT}& \member{PCG} & \member{GMRES} & \member{TFQMR} & \member{MINRES} & \member{PRES20} & \member{BICGSTAB} & lumping \\
364 \hline
365 \hline
366 \member{setReordering} & $\checkmark$ & & & & & &\\
367 \hline \member{setRestart} & & & $\checkmark$ & & & $20$ & \\
368 \hline\member{setTruncation} & & & $\checkmark$ & & & $5$ & \\
369 \hline\member{setIterMax} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
370 \hline\member{setTolerance} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
371 \hline\member{setAbsoluteTolerance} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
372 \hline\member{setReordering} & $\checkmark$ & & & & & & & \\
373 \end{tabular}
374 }
375 \caption{Solvers available for \finley and the \PASO package and the relevant
376 options in \class{SolverOptions}.
377 \MKL supports \member{MINIMUM_FILL_IN}\index{linear solver!minimum fill-in ordering}\index{minimum fill-in ordering}
378 and \member{NESTED_DISSECTION}\index{linear solver!nested dissection ordering}\index{nested dissection}
379 reordering.
380 Currently the \UMFPACK interface does not support any reordering.
381 \label{TAB FINLEY SOLVER OPTIONS 1}}
382 \end{table}
383
384 \begin{table}
385 \begin{center}
386 {\scriptsize
387 \begin{tabular}{l||c|c|c|c|c|c|c}
388 \member{NO_PRECONDITIONER}&
389 \member{AMG}&
390 \member{JACOBI}&
391 \member{GAUSS_SEIDEL}&
392 \member{REC_ILU}&
393 \member{RILU}&
394 \member{ILU0}&
395 \member{DIRECT}\\
396 \hline
397 status:& $\checkmark$ &$\checkmark$&$\checkmark$&$\checkmark$&later&$\checkmark$&later\\
398 \hline
399 \hline
400 \member{setLevelMax}&$\checkmark$& & & & & &\\
401 \hline
402 \member{setCoarseningThreshold}&$\checkmark$& & & & & &\\
403 \hline
404 \member{setMinCoarseMatrixSize}&$\checkmark$& & & & & &\\
405 \hline
406 \member{setMinCoarseMatrixSparsity}&$\checkmark$& & & & & &\\
407 \hline
408 \member{setNumSweeps}& &$\checkmark$&$\checkmark$& & & &\\
409 \hline
410 \member{setNumPreSweeps}&$\checkmark$& & & & & &\\
411 \hline
412 \member{setNumPostSweeps}&$\checkmark$& & & & & &\\
413 \hline
414 \member{setDiagonalDominanceThreshold}&$\checkmark$& & & & & &\\
415 \hline
416 \member{setAMGInterpolation}&$\checkmark$& & & & & &\\
417 \hline
418 \member{setRelaxationFactor}& & & & &$\checkmark$& &\\
419 \end{tabular}
420 }
421 \caption{Preconditioners available for \finley and the \PASO package and the
422 relevant options in \class{SolverOptions}.
423 \label{TAB FINLEY SOLVER OPTIONS 2}}
424 \end{center}
425 \end{table}
426
427 \section{Functions}
428 \begin{funcdesc}{ReadMesh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True}}
429 creates a \Domain object from the FEM mesh defined in file \var{fileName}.
430 The file must be in the \finley file format.
431 If \var{integrationOrder} is positive, a numerical integration scheme is chosen
432 which is accurate on each element up to a polynomial of degree
433 \var{integrationOrder}\index{integration order}.
434 Otherwise an appropriate integration order is chosen independently.
435 By default the labeling of mesh nodes and element distribution is optimized.
436 Set \var{optimize=False} to switch off relabeling and redistribution.
437 \end{funcdesc}
438
439 \begin{funcdesc}{ReadGmsh}{fileName, numDim, \optional{, \optional{integrationOrder=-1}, optimize=True\optional{, useMacroElements=False}}}
440 creates a \Domain object from the FEM mesh defined in file \var{fileName} for
441 a domain of dimension \var{numDim}.
442 The file must be in the \gmshextern file format.
443 If \var{integrationOrder} is positive, a numerical integration scheme is chosen
444 which is accurate on each element up to a polynomial of degree
445 \var{integrationOrder}\index{integration order}.
446 Otherwise an appropriate integration order is chosen independently.
447 By default the labeling of mesh nodes and element distribution is optimized.
448 Set \var{optimize=False} to switch off relabeling and redistribution.
449 If \var{useMacroElements} is set, second order elements are interpreted as
450 macro elements\index{macro elements}.
451 \end{funcdesc}
452
453 \begin{funcdesc}{MakeDomain}{design\optional{, integrationOrder=-1\optional{, optimizeLabeling=True\optional{, useMacroElements=False}}}}
454 creates a \finley \Domain from a \pycad \class{Design} object using \gmshextern.
455 The \class{Design} \var{design} defines the geometry.
456 If \var{integrationOrder} is positive, a numerical integration scheme is chosen
457 which is accurate on each element up to a polynomial of degree
458 \var{integrationOrder}\index{integration order}.
459 Otherwise an appropriate integration order is chosen independently.
460 Set \var{optimizeLabeling=False} to switch off relabeling and redistribution
461 (not recommended).
462 If \var{useMacroElements} is set, macro elements\index{macro elements} are used.
463 Currently \function{MakeDomain} does not support \MPI.
464 \end{funcdesc}
465
466 \begin{funcdesc}{load}{fileName}
467 recovers a \Domain object from a dump file \var{fileName} created by the
468 \function{dump} method of a \Domain object.
469 \end{funcdesc}
470
471 \begin{funcdesc}{Rectangle}{n0,n1,order=1,l0=1.,l1=1., integrationOrder=-1, \\
472 periodic0=\False, periodic1=\False, useElementsOnFace=\False, optimize=\False}
473 generates a \Domain object representing a two-dimensional rectangle between
474 $(0,0)$ and $(l0,l1)$ with orthogonal edges.
475 The rectangle is filled with \var{n0} elements along the $x_0$-axis and
476 \var{n1} elements along the $x_1$-axis.
477 For \var{order}=1 and \var{order}=2, elements of type \finleyelement{Rec4} and
478 \finleyelement{Rec8} are used, respectively.
479 In the case of \var{useElementsOnFace}=\False, \finleyelement{Line2} and
480 \finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively.
481 If \var{order}=-1, \finleyelement{Rec8Macro} and \finleyelement{Line3Macro}\index{macro elements}
482 are used. This option should be used when solving incompressible fluid flow
483 problems, e.g. \class{StokesProblemCartesian}.
484 In the case of \var{useElementsOnFace}=\True (this option should be used if
485 gradients are calculated on domain faces), \finleyelement{Rec4Face} and
486 \finleyelement{Rec8Face} are used on the edges, respectively.
487 If \var{integrationOrder} is positive, a numerical integration scheme is chosen
488 which is accurate on each element up to a polynomial of degree
489 \var{integrationOrder}\index{integration order}.
490 Otherwise an appropriate integration order is chosen independently.
491 If \var{periodic0}=\True, periodic boundary conditions\index{periodic boundary conditions}
492 along the $x_0$-direction are enforced.
493 That means for any solution of a PDE solved by \finley the values on the line
494 $x_0=0$ will be identical to the values on $x_0=\var{l0}$.
495 Correspondingly, \var{periodic1}=\True sets periodic boundary conditions in the
496 $x_1$-direction.
497 If \var{optimize}=\True mesh node relabeling will be attempted to reduce the
498 computation and also ParMETIS will be used to improve the mesh partition if
499 running on multiple CPUs with \MPI.
500 \end{funcdesc}
501
502 \begin{funcdesc}{Brick}{n0,n1,n2,order=1,l0=1.,l1=1.,l2=1., integrationOrder=-1,
503 periodic0=\False, periodic1=\False, \\ periodic2=\False, useElementsOnFace=\False,useFullElementOrder=\False, optimize=\False}
504 generates a \Domain object representing a three-dimensional brick between
505 $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with
506 \var{n0} elements along the $x_0$-axis,
507 \var{n1} elements along the $x_1$-axis and
508 \var{n2} elements along the $x_2$-axis.
509 For \var{order}=1 and \var{order}=2, elements of type \finleyelement{Hex8} and
510 \finleyelement{Hex20} are used, respectively.
511 In the case of \var{useElementsOnFace}=\False, \finleyelement{Rec4} and
512 \finleyelement{Rec8} are used to subdivide the faces of the brick, respectively.
513 In the case of \var{useElementsOnFace}=\True (this option should be used if
514 gradients are calculated on domain faces), \finleyelement{Hex8Face} and
515 \finleyelement{Hex20Face} are used on the brick faces, respectively.
516 If \var{order}=-1, \finleyelement{Hex20Macro} and \finleyelement{Rec8Macro}\index{macro elements}
517 are used. This option should be used when solving incompressible fluid flow
518 problems, e.g. \class{StokesProblemCartesian}.
519 If \var{integrationOrder} is positive, a numerical integration scheme is chosen
520 which is accurate on each element up to a polynomial of degree
521 \var{integrationOrder}\index{integration order}.
522 Otherwise an appropriate integration order is chosen independently.
523 If \var{periodic0}=\True, periodic boundary conditions\index{periodic boundary conditions}
524 along the $x_0$-direction are enforced.
525 That means for any solution of a PDE solved by \finley the values on the plane
526 $x_0=0$ will be identical to the values on $x_0=\var{l0}$.
527 Correspondingly, \var{periodic1}=\True and \var{periodic2}=\True sets periodic
528 boundary conditions in the $x_1$-direction and $x_2$-direction, respectively.
529 If \var{optimize}=\True mesh node relabeling will be attempted to reduce the
530 computation and also ParMETIS will be used to improve the mesh partition if
531 running on multiple CPUs with \MPI.
532 \end{funcdesc}
533
534 \begin{funcdesc}{GlueFaces}{meshList, tolerance=1.e-13}
535 generates a new \Domain object from the list \var{meshList} of \finley meshes.
536 Nodes in face elements whose difference of coordinates is less than
537 \var{tolerance} times the diameter of the domain are merged.
538 The corresponding face elements are removed from the mesh.
539 \function{GlueFaces} is not supported under \MPI with more than one rank.
540 \end{funcdesc}
541
542 \begin{funcdesc}{JoinFaces}{meshList, tolerance=1.e-13}
543 generates a new \Domain object from the list \var{meshList} of \finley meshes.
544 Face elements whose node coordinates differ by less than \var{tolerance} times
545 the diameter of the domain are combined to form a contact element\index{element!contact}.
546 The corresponding face elements are removed from the mesh.
547 \function{JoinFaces} is not supported under \MPI with more than one rank.
548 \end{funcdesc}
549
550 \section{\dudley}
551 \label{sec:dudley}
552 The {\it dudley} library is a restricted version of {\it finley}.
553 So in many ways it can be used as a ``drop-in'' replacement.
554 Dudley domains are simpler in that only triangular (2D), tetrahedral (3D) and line elements are supported.
555 Note, this also means that dudley does not support:
556 \begin{itemize}
557 \item dirac delta functions
558 \item contact elements
559 \item macro elements
560 \end{itemize}
561

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26