# Diff of /trunk/doc/user/finley.tex

revision 993 by gross, Fri Feb 23 06:39:38 2007 UTC revision 2573 by gross, Mon Aug 3 04:30:09 2009 UTC
# Line 1  Line 1
1  % $Id$
2    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3  %  %
4  %           Copyright © 2006, 2007 by ACcESS MNRF  % Copyright (c) 2003-2009 by University of Queensland
5  %               \url{http://www.access.edu.au  % Earth Systems Science Computational Center (ESSCC)
6  %         Primary Business: Queensland, Australia.  % http://www.uq.edu.au/esscc
7  %  %
8    % Primary Business: Queensland, Australia
11    %
12    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13
14
15    \chapter{ The Module \finley}
\chapter{ The module \finley}
16   \label{CHAPTER ON FINLEY}   \label{CHAPTER ON FINLEY}
17
18  \begin{figure}  \begin{figure}
19  \centerline{\includegraphics[width=\figwidth]{figures/FinleyMesh.eps}}  \centerline{\includegraphics[width=\figwidth]{figures/FinleyMesh}}
20  \caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})}  \caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})}
21  \label{FINLEY FIG 0}  \label{FINLEY FIG 0}
22  \end{figure}  \end{figure}
23
24  \begin{figure}  \begin{figure}
25  \centerline{\includegraphics[width=\figwidth]{figures/FinleyContact.eps}}  \centerline{\includegraphics[width=\figwidth]{figures/FinleyContact}}
26  \caption{Mesh around a contact region (\finleyelement{Rec4})}  \caption{Mesh around a contact region (\finleyelement{Rec4})}
27  \label{FINLEY FIG 01}  \label{FINLEY FIG 01}
28  \end{figure}  \end{figure}
# Line 58  subdivision of an ellipse into so called Line 61  subdivision of an ellipse into so called
61  In this case, triangles have been used but other forms of subdivisions  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  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  and hexahedrons. The idea of the finite element method is to approximate the solution by a function
64  which is a polynomial of a certain order and is continuous across it boundary to neighbour elements.  which is a polynomial of a certain order and is continuous across it boundary to neighbor elements.
65  In the example of \fig{FINLEY FIG 0} a linear polynomial is used on each triangle. As one can see, the triangulation  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  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.  positioning those nodes located on an edge expected to describe the boundary, onto the boundary.
# Line 81  to second node the domain has to lie on Line 84  to second node the domain has to lie on
84  the domain has to lie on the left hand side when moving counterclockwise). If the gradient on the  the domain has to lie on the left hand side when moving counterclockwise). If the gradient on the
85  surface of the domain is to be calculated rich face elements face to be used. Rich elements on a face  surface of the domain is to be calculated rich face elements face to be used. Rich elements on a face
86  are identical to interior elements but with a modified order of nodes such that the 'first' face of the element aligns  are identical to interior elements but with a modified order of nodes such that the 'first' face of the element aligns
87  with the surface of the domian. In \fig{FINLEY FIG 0}  with the surface of the domain. In \fig{FINLEY FIG 0}
88  elements of the type \finleyelement{Tri3Face} are used.  elements of the type \finleyelement{Tri3Face} are used.
89  The face element reference number $20$ as a rich face element is defined by the nodes  The face element reference number $20$ as a rich face element is defined by the nodes
90  with reference numbers $11$, $0$ and $9$. Notice that the face element $20$ is identical to the  with reference numbers $11$, $0$ and $9$. Notice that the face element $20$ is identical to the
# Line 132  the nodes within an element. Line 135  the nodes within an element.
135  \linev{\finleyelement{Hex20}}{\finleyelement{Rec8}}{\finleyelement{Hex20Face}}{\finleyelement{Rec8_Contact}}{\finleyelement{Hex20Face_Contact}}  \linev{\finleyelement{Hex20}}{\finleyelement{Rec8}}{\finleyelement{Hex20Face}}{\finleyelement{Rec8_Contact}}{\finleyelement{Hex20Face_Contact}}
136  \end{tablev}  \end{tablev}
137  \caption{Finley elements and corresponding elements to be used on domain faces and contacts.  \caption{Finley elements and corresponding elements to be used on domain faces and contacts.
138  The rich types have to be used if the gradient of function is to be calculated on faces and contacts, resepctively.}  The rich types have to be used if the gradient of function is to be calculated on faces and contacts, respectively.}
139  \label{FINLEY TAB 1}  \label{FINLEY TAB 1}
140  \end{table}  \end{table}
141
# Line 176  for i in range(ContactElement_Num): Line 179  for i in range(ContactElement_Num):
179     for j in range(ContactElement_numNodes): print " %d"%ContactElement_Nodes[i][j]     for j in range(ContactElement_numNodes): print " %d"%ContactElement_Nodes[i][j]
180     print "\n"     print "\n"
181  # point sources (not supported yet)  # point sources (not supported yet)
182  write("Point1 0",face_element_typ,numFaceElements)  write("Point1 0",face_element_type,numFaceElements)
183  \end{python}  \end{python}
184
185  The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}:  The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}:
# Line 247  $7$, $10$, $15$ and $20$, respectively. Line 250  $7$, $10$, $15$ and $20$, respectively.
250  20 16 0 1.0  1.0  20 16 0 1.0  1.0
251  \end{verbatim}  \end{verbatim}
252
253    \clearpage
254    \input{finleyelements}
255    \clearpage
256
257
258    \begin{table}
259    {\small
260    \begin{tabular}{l||c|c|c|c|c|c|c|c}
261    \member{setSolverMethod} & \member{DIRECT}& \member{PCG} & \member{GMRES} & \member{TFQMR} & \member{MINRES} & \member{PRES20} & \member{BICGSTAB} & \member{LUMPING} \\
262    \hline
263     \hline
264     \member{setReordering} & $\checkmark$ & & & & & &\\
265     \hline  \member{setRestart} &  & & $\checkmark$ & & & $20$ & \\
266     \hline\member{setTruncation} &  & & $\checkmark$ & & & $5$ & \\
267       \hline\member{setIterMax} &  & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
268     \hline\member{setTolerance} &  & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
269     \hline\member{setAbsoluteTolerance} &  & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
270    \hline\member{setReordering} & $\checkmark$ & & & & & & & \\
271    \end{tabular}
272    }
273    \caption{Solvers available for
274    \finley
275    and the \PASO package and the relevant options in \class{SolverOptions}.
276    \MKL supports
277    \MINIMUMFILLIN
278    and
279    \NESTEDDESCTION
280    reordering.
281    Currently the \UMFPACK interface does not support any reordering.
282    \label{TAB FINLEY SOLVER OPTIONS 1} }
283    \end{table}
284
285  \include{finleyelements}  \begin{table}
286    {\scriptsize
287    \begin{tabular}{l||c|c|c|c|c|c|c|c}
288    \member{setPreconditioner} &
289    \member{NO_PRECONDITIONER} &
290    \member{AMG} &
291    \member{JACOBI} &
292    \member{GAUSS_SEIDEL}&
293    \member{REC_ILU}&
294    \member{RILU} &
295    \member{ILU0} &
296    \member{DIRECT} \\
297     \hline
298     status: &
299    later &
300    later &
301    $\checkmark$ &
302    $\checkmark$&
303    $\checkmark$ &
304    later &
305    $\checkmark$ &
306    later \\
307    \hline
308    \hline
309    \member{setCoarsening}&
310     &
311    $\checkmark$ &
312    &
313    &
314    &
315     &
316     &
317     \\
318
319
320    \hline\member{setLevelMax}&
321     &
322    $\checkmark$ &
323     &
324    &
325    &
326     &
327     &
328     \\
329
330    \hline\member{setCoarseningThreshold}&
331    &
332    $\checkmark$ &
333     &
334    &
335    &
336     &
337     &
338     \\
339
340    \hline\member{setMinCoarseMatrixSize} &
341     &
342    $\checkmark$ &
343     &
344    &
345    &
346     &
347     &
348     \\
349
350    \hline\member{setNumSweeps} &
351     &
352     &
353    $\checkmark$ &
354    $\checkmark$ &
355    &
356     &
357     &
358     \\
359
360    \hline\member{setNumPreSweeps}&
361     &
362    $\checkmark$ &
363      &
364     &
365     &
366      &
367      &
368      \\
369
370    \hline\member{setNumPostSweeps} &
371     &
372    $\checkmark$ &
373     &
374    &
375    &
376     &
377    &
378     \\
379
380    \hline\member{setInnerTolerance}&
381     &
382     &
383     &
384    &
385    &
386     &
387    &
388     \\
389
390    \hline\member{setDropTolerance}&
391     &
392     &
393     &
394    &
395    &
396     &
397    &
398     \\
399
400    \hline\member{setDropStorage}&
401     &
402     &
403     &
404    &
405    &
406     &
407    &
408     \\
409
410    \hline\member{setRelaxationFactor}&
411     &
412     &
413     &
414    &
415    &
416    $\checkmark$  &
417     &
418     \\
419
421     &
422     &
423     &
424    &
425    &
426     &
427    &
428     \\
429
430    \hline\member{setInnerIterMax}&
431     &
432     &
433     &
434    &
435    &
436     &
437    &
438     \\
439    \end{tabular}
440    }
441    \caption{Preconditioners available for \finley and the \PASO package and the relevant options in \class{SolverOptions}. \label{TAB FINLEY SOLVER OPTIONS 2}}
442    \end{table}
443
444  \subsection{Linear Solvers in \LinearPDE}  \subsection{Linear Solvers in \SolverOptions}
445  Currently \finley supports the linear solvers \PCG, \GMRES, \PRESTWENTY and \BiCGStab.  Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and
446  For \GMRES the options \var{trancation} and \var{restart} of the \method{getSolution} can be  Table~\ref{TAB FINLEY SOLVER OPTIONS 2} show the solvers and preconditioners supported by
447  used to control the trunction and restart during iteration. Default values are  \finley through the \PASO library. Currently direct solvers are not supported under MPI.
448  \var{truncation}=5 and \var{restart}=20.  By default, \finley is using the iterative solvers \PCG for symmetric and \BiCGStab for non-symmetric problems.
449  The default solver is \BiCGStab  but if the symmetry flag is set \PCG is the default solver.  If the direct solver is selected which can be useful when solving very ill-posedequations
450  \finley supports the solver options \var{iter_max} which specifies the maximum number of iterations steps,  \finley uses the \MKL solver package. If \MKL is not available \UMFPACK is used. If \UMFPACK is not available
451  \var{verbose}=\True or \False and \var{preconditioner}=\constant{JACOBI} or \constant {ILU0}.  a suitable iterative solver from the \PASO is used.
In some installations \finley supports the \Direct solver and the
solver options \var{reordering}=\constant{util.NO_REORDERING},
\constant{util.MINIMUM_FILL_IN} or \constant{util.NESTED_DISSECTION} (default is \constant{util.NO_REORDERING}),
\var{drop_tolerance} specifying the threshold for values to be dropped in the
incomplete elimation process (default is 0.01) and \var{drop_storage} specifying the maximum increase
in storage allowed in the
incomplete elimation process (default is 1.20).
452
453  \subsection{Functions}  \subsection{Functions}
455  creates a \Domain object form the FEM mesh defined in  creates a \Domain object form the FEM mesh defined in
456  file \var{fileName}. The file must be given the \finley file format.  file \var{fileName}. The file must be given the \finley file format.
457  If \var{integrationOrder} is positive, a numerical integration scheme  If \var{integrationOrder} is positive, a numerical integration scheme
# Line 276  degree \var{integrationOrder} \index{int Line 460  degree \var{integrationOrder} \index{int
460  an appropriate integration order is chosen independently.  an appropriate integration order is chosen independently.
461  \end{funcdesc}  \end{funcdesc}
462
464    periodic0=\False,useElementsOnFace=\False}  recovers a \Domain object from a dump file created by the \
465  Generates a \Domain object representing a interval $[0,l0]$. The interval is filled with  eateseates a \Domain object form the FEM mesh defined in
466  \var{n0} elements.  file \var{fileName}. The file must be given the \finley file format.
For \var{order}=1 and \var{order}=2
\finleyelement{Line2} and
\finleyelement{Line3} are used, respectively.
In the case of \var{useElementsOnFace}=\False,
\finleyelement{Point1} are used to describe the boundary points.
In the case of \var{useElementsOnFace}=\True (this option should be used if gradients
are calculated on domain faces),
\finleyelement{Line2} and
\finleyelement{Line3} are used on both ends of the interval.
467  If \var{integrationOrder} is positive, a numerical integration scheme  If \var{integrationOrder} is positive, a numerical integration scheme
468  chosen which is accurate on each element up to a polynomial of  chosen which is accurate on each element up to a polynomial of
469  degree \var{integrationOrder} \index{integration order}. Otherwise  degree \var{integrationOrder} \index{integration order}. Otherwise
470  an appropriate integration order is chosen independently. If  an appropriate integration order is chosen independently.
\var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions}
along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley
the value at $x_0=0$ will be identical to the values at $x_0=\var{l0}$.
471  \end{funcdesc}  \end{funcdesc}
472
473  \begin{funcdesc}{Rectangle}{n0,n1,order=1,l0=1.,l1=1., integrationOrder=-1, \\  \begin{funcdesc}{Rectangle}{n0,n1,order=1,l0=1.,l1=1., integrationOrder=-1, \\
474    periodic0=\False,periodic1=\False,useElementsOnFace=\False}    periodic0=\False,periodic1=\False,useElementsOnFace=\False,optimize=\False}
475  Generates a \Domain object representing a two dimensional rectangle between  Generates a \Domain object representing a two dimensional rectangle between
476  $(0,0)$ and $(l0,l1)$ with orthogonal edges. The rectangle is filled with  $(0,0)$ and $(l0,l1)$ with orthogonal edges. The rectangle is filled with
477  \var{n0} elements along the $x_0$-axis and  \var{n0} elements along the $x_0$-axis and
# Line 324  the value on the line $x_0=0$ will be id Line 496  the value on the line $x_0=0$ will be id
496  Correspondingly,  Correspondingly,
497  \var{periodic1}=\False sets periodic boundary conditions  \var{periodic1}=\False sets periodic boundary conditions
498  in $x_1$-direction.  in $x_1$-direction.
499    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.
500  \end{funcdesc}  \end{funcdesc}
501
502  \begin{funcdesc}{Brick}{n0,n1,n2,order=1,l0=1.,l1=1.,l2=1., integrationOrder=-1, \\  \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}    periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False,optimize=\False}
504  Generates a \Domain object representing a three dimensional brick between  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  $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with
506  \var{n0} elements along the $x_0$-axis,  \var{n0} elements along the $x_0$-axis,
# Line 352  along the $x_0$-directions are enforced. Line 525  along the $x_0$-directions are enforced.
525  the value on the plane $x_0=0$ will be identical to the values on $x_0=\var{l0}$. Correspondingly,  the value on the plane $x_0=0$ will be identical to the values on $x_0=\var{l0}$. Correspondingly,
526  \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions  \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions
527  in $x_1$-direction and $x_2$-direction, respectively.  in $x_1$-direction and $x_2$-direction, respectively.
528    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.
529  \end{funcdesc}  \end{funcdesc}
530
531  \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}  \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
532  Generates a new \Domain object from the list \var{mehList} of \finley meshes.  Generates a new \Domain object from the list \var{meshList} of \finley meshes.
533  Nodes in face elements whose difference of coordinates is less then \var{tolerance} times the  Nodes in face elements whose difference of coordinates is less then \var{tolerance} times the
534  diameter of the domain are merged. The corresponding face elements are removed from the mesh.    diameter of the domain are merged. The corresponding face elements are removed from the mesh.
535
# Line 363  TODO: explain \var{safetyFactor} and sho Line 537  TODO: explain \var{safetyFactor} and sho
537  \end{funcdesc}  \end{funcdesc}
538
539  \begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}  \begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
540  Generates a new \Domain object from the list \var{mehList} of \finley meshes.  Generates a new \Domain object from the list \var{meshList} of \finley meshes.
541  Face elements whose nodes coordinates have difference is less then \var{tolerance} times the  Face elements whose nodes coordinates have difference is less then \var{tolerance} times the
542  diameter of the domain are combined to form a contact element \index{element!contact}  diameter of the domain are combined to form a contact element \index{element!contact}
543  The corresponding face elements are removed from the mesh.    The corresponding face elements are removed from the mesh.

Legend:
 Removed from v.993 changed lines Added in v.2573