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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2417 by gross, Wed May 13 08:18:47 2009 UTC revision 3279 by caltinay, Fri Oct 15 04:02:06 2010 UTC
# Line 1  Line 1 
1    
2  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3  %  %
4  % Copyright (c) 2003-2008 by University of Queensland  % Copyright (c) 2003-2010 by University of Queensland
5  % Earth Systems Science Computational Center (ESSCC)  % Earth Systems Science Computational Center (ESSCC)
6  % http://www.uq.edu.au/esscc  % http://www.uq.edu.au/esscc
7  %  %
# Line 16  Line 16 
16   \label{CHAPTER ON FINLEY}   \label{CHAPTER ON FINLEY}
17    
18  \begin{figure}  \begin{figure}
19  \centerline{\includegraphics[width=\figwidth]{figures/FinleyMesh}}  \centerline{\includegraphics[width=\figwidth]{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}}  \centerline{\includegraphics[width=\figwidth]{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 55  A\hackscore{jl} \cdot v\hackscore{,j}u\h Line 55  A\hackscore{jl} \cdot v\hackscore{,j}u\h
55  \end{equation}  \end{equation}
56    
57  \section{Meshes}  \section{Meshes}
58    \label{FINLEY MESHES}
59  To understand the usage of \finley one needs to have an understanding of how the finite element meshes  To understand the usage of \finley one needs to have an understanding of how the finite element meshes
60  \index{FEM!mesh} are defined. \fig{FINLEY FIG 0} shows an example of the  \index{FEM!mesh} are defined. \fig{FINLEY FIG 0} shows an example of the
61  subdivision of an ellipse into so called elements \index{FEM!elements} \index{element}.  subdivision of an ellipse into so called elements \index{FEM!elements} \index{element}.
# Line 65  which is a polynomial of a certain order Line 66  which is a polynomial of a certain order
66  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
67  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
68  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.
69  In this case the triangle gets a curved edge which requires a parametrization of the triangle using a  In this case the triangle gets a curved edge which requires a parameterization of the triangle using a
70  quadratic polynomial. For this case, the solution is also approximated by a piecewise quadratic polynomial  quadratic polynomial. For this case, the solution is also approximated by a piecewise quadratic polynomial
71  (which explains the name isoparametrical elements), see \Ref{Zienc,NumHand} for more details.    (which explains the name isoparametrical elements), see \Ref{Zienc,NumHand} for more details.  
72    \finley supports macro elements\index{macro elements}. For these elements a piecewise linear approximation is used on an element which is further subdivided (in the case \finley halved). As such these elements do not provide more than a further mesh refinement but should be used in the case of incompressible flows, see \class{StokesProblemCartesian}. For these problems a linear approximation of the pressure across the element is used (use the \ReducedSolutionFS \FunctionSpace) while the refined element is used to approximate velocity. So a macro element provides a continuous pressure approximation together with a velocity approximation on a refined mesh. This approach is necessary to make sure that the  incompressible flow has a unique solution.
73    
74  The union of all elements defines the domain of the PDE.  The union of all elements defines the domain of the PDE.
75  Each element is defined by the nodes used to describe its shape. In \fig{FINLEY FIG 0} the element,  Each element is defined by the nodes used to describe its shape. In \fig{FINLEY FIG 0} the element,
# Line 116  contact regions line up.  The rich versi Line 118  contact regions line up.  The rich versi
118  $4$ is of type \finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$, $18$, $6$, $5$, $0$ and  $4$ is of type \finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$, $18$, $6$, $5$, $0$ and
119  $2$.  $2$.
120    
121    
122    
123  \tab{FINLEY TAB 1} shows the interior element types and the corresponding element types to be used  \tab{FINLEY TAB 1} shows the interior element types and the corresponding element types to be used
124  on the face and contacts. \fig{FINLEY.FIG:1}, \fig{FINLEY.FIG:2} and \fig{FINLEY.FIG:4} show the ordering of  on the face and contacts. \fig{FINLEY.FIG:1}, \fig{FINLEY.FIG:2} and \fig{FINLEY.FIG:4} show the ordering of
125  the nodes within an element.  the nodes within an element.
# Line 133  the nodes within an element. Line 137  the nodes within an element.
137  \linev{\finleyelement{Tet10}}{\finleyelement{Tri9}}{\finleyelement{Tet10Face}}{\finleyelement{Tri9_Contact}}{\finleyelement{Tet10Face_Contact}}  \linev{\finleyelement{Tet10}}{\finleyelement{Tri9}}{\finleyelement{Tet10Face}}{\finleyelement{Tri9_Contact}}{\finleyelement{Tet10Face_Contact}}
138  \linev{\finleyelement{Hex8}}{\finleyelement{Rec4}}{\finleyelement{Hex8Face}}{\finleyelement{Rec4_Contact}}{\finleyelement{Hex8Face_Contact}}  \linev{\finleyelement{Hex8}}{\finleyelement{Rec4}}{\finleyelement{Hex8Face}}{\finleyelement{Rec4_Contact}}{\finleyelement{Hex8Face_Contact}}
139  \linev{\finleyelement{Hex20}}{\finleyelement{Rec8}}{\finleyelement{Hex20Face}}{\finleyelement{Rec8_Contact}}{\finleyelement{Hex20Face_Contact}}  \linev{\finleyelement{Hex20}}{\finleyelement{Rec8}}{\finleyelement{Hex20Face}}{\finleyelement{Rec8_Contact}}{\finleyelement{Hex20Face_Contact}}
140    \linev{\finleyelement{Hex27}}{\finleyelement{Rec9}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
141    \linev{\finleyelement{Hex27Macro}}{\finleyelement{Rec9Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
142    \linev{\finleyelement{Tet10Macro}}{\finleyelement{Tri6Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
143    \linev{\finleyelement{Rec9Macro}}{\finleyelement{Line3Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
144    \linev{\finleyelement{Tri6Macro}}{\finleyelement{Line3Macro}}{N\textbackslash A}{N\textbackslash A}{N\textbackslash A}
145  \end{tablev}  \end{tablev}
146  \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.
147  The rich types have to be used if the gradient of function is to be calculated on faces and contacts, respectively.}  The rich types have to be used if the gradient of function is to be calculated on faces and contacts, respectively.}
# Line 254  $7$, $10$, $15$ and $20$, respectively. Line 263  $7$, $10$, $15$ and $20$, respectively.
263  \input{finleyelements}  \input{finleyelements}
264  \clearpage  \clearpage
265    
266  \subsection{Linear Solvers in \LinearPDE}  \begin{figure}[th]
267  Currently \finley supports the linear solvers \PCG, \GMRES, \PRESTWENTY and \BiCGStab.  \begin{center}
268  For \GMRES the options \var{truncation} and \var{restart} of the \method{getSolution} can be  \subfigure[Triangle]{\label{FINLEY MACRO TRI}\includegraphics[scale=0.25]{FinleyMacroTri}}
269  used to control the truncation and restart during iteration. Default values are  \subfigure[Quadrilateral]{\label{FINLEY MACRO REC}\includegraphics[scale=0.25]{FinleyMacroRec}}
270  \var{truncation}=5 and \var{restart}=20.  \includegraphics[scale=0.2]{FinleyMacroLeg}
271  The default solver is \BiCGStab  but if the symmetry flag is set \PCG is the default solver.  \end{center}
272  \finley supports the solver options \var{iter_max} which specifies the maximum number of iterations steps,  Macro elements in \finley.
273  \var{verbose}=\True or \False and \var{preconditioner}=\constant{JACOBI} or \constant {ILU0}.  \end{figure}
274  In some installations \finley supports the \Direct solver and the  
275  solver options \var{reordering}=\constant{util.NO_REORDERING},  \section{Macro Elements}
276  \constant{util.MINIMUM_FILL_IN} or \constant{util.NESTED_DISSECTION} (default is \constant{util.NO_REORDERING}),  \label{SEC FINLEY MACRO}
277  \var{drop_tolerance} specifying the threshold for values to be dropped in the  \finley supports the usage of macro elements~\index{macro elements} which can be used to
278  incomplete elimination process (default is 0.01) and \var{drop_storage} specifying the maximum increase  achieve LBB compliance when solving incompressible fluid flow problems. LBB compliance is required to
279  in storage allowed in the  get a problem which has a unique solution for pressure and velocity. For macro elements the
280  incomplete elimination process (default is 1.20).  pressure and velocity are approximated by a polynomial of order 1 but the velocity approximation bases on a refinement of the element. The nodes of a triangle and quadrilateral element is shown in Figures~\ref{FINLEY MACRO TRI} and~\ref{FINLEY MACRO REC}, respectively. In essence, the velocity uses the same nodes like a quadratic polynomial approximation but replaces the quadratic polynomial by piecewise linear polynomials. In fact, this is the
281    way \finley is defining the macro elements. In particular \finley uses the same local ordering of the nodes for the macro element as for the corresponding quadratic element. Another interpretation is that
282    one uses a linear approximation of the velocity together with a linear approximation of the pressure but on elements
283    created by combining elements to macro elements. Notice that the macro elements still use quadratic interpolation to represent the element and domain boundary. However, if elements have linear boundary
284    a macro element approximation for the velocity is equivalent to using a linear approximation on a mesh which is created through a one step, global refinement.
285    Typically macro elements are only required to use when an incompressible fluid flow problem
286    is solved, e.g the Stokes problem in Section \ref{STOKES PROBLEM}. Please see Section~\ref{FINLEY MESHES} for
287    more details on the supported macro elements.
288    
289    
290    
291    \begin{table}
292    {\scriptsize
293    \begin{tabular}{l||c|c|c|c|c|c|c|c}
294    \member{setSolverMethod} & \member{DIRECT}& \member{PCG} & \member{GMRES} & \member{TFQMR} & \member{MINRES} & \member{PRES20} & \member{BICGSTAB} & \member{LUMPING} \\
295    \hline
296     \hline
297     \member{setReordering} & $\checkmark$ & & & & & &\\
298     \hline  \member{setRestart} &  & & $\checkmark$ & & & $20$ & \\
299     \hline\member{setTruncation} &  & & $\checkmark$ & & & $5$ & \\
300       \hline\member{setIterMax} &  & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
301     \hline\member{setTolerance} &  & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
302     \hline\member{setAbsoluteTolerance} &  & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
303    \hline\member{setReordering} & $\checkmark$ & & & & & & & \\
304    \end{tabular}
305    }
306    \caption{Solvers available for
307    \finley
308    and the \PASO package and the relevant options in \class{SolverOptions}.
309    \MKL supports
310    \MINIMUMFILLIN
311    and
312    \NESTEDDESCTION
313    reordering.
314    Currently the \UMFPACK interface does not support any reordering.
315    \label{TAB FINLEY SOLVER OPTIONS 1} }
316    \end{table}
317    
318    \begin{table}
319    {\scriptsize
320    \begin{tabular}{l||c|c|c|c|c|c|c|c}
321    \member{setPreconditioner} &
322    \member{NO_PRECONDITIONER} &
323    \member{AMG} &
324    \member{JACOBI} &
325    \member{GAUSS_SEIDEL}&
326    \member{REC_ILU}&
327    \member{RILU} &
328    \member{ILU0} &
329    \member{DIRECT} \\
330     \hline
331     status: &
332    later &
333    later &
334    $\checkmark$ &
335    $\checkmark$&
336    $\checkmark$ &
337    later &
338    $\checkmark$ &
339    later \\
340    \hline
341    \hline
342    \member{setCoarsening}&
343     &
344    $\checkmark$ &
345    &
346    &
347    &
348     &
349     &
350     \\
351    
352    
353    \hline\member{setLevelMax}&
354     &
355    $\checkmark$ &
356     &
357    &
358    &
359     &
360     &
361     \\
362    
363    \hline\member{setCoarseningThreshold}&
364    &
365    $\checkmark$ &
366     &
367    &
368    &
369     &
370     &
371     \\
372    
373    \hline\member{setMinCoarseMatrixSize} &
374     &
375    $\checkmark$ &
376     &
377    &
378    &
379     &
380     &
381     \\
382    
383    \hline\member{setNumSweeps} &
384     &
385     &
386    $\checkmark$ &
387    $\checkmark$ &
388    &
389     &
390     &
391     \\
392    
393    \hline\member{setNumPreSweeps}&
394     &
395    $\checkmark$ &
396      &
397     &
398     &
399      &
400      &
401      \\
402    
403    \hline\member{setNumPostSweeps} &
404     &
405    $\checkmark$ &
406     &
407    &
408    &
409     &
410    &
411     \\
412    
413    \hline\member{setInnerTolerance}&
414     &
415     &
416     &
417    &
418    &
419     &
420    &
421     \\
422    
423    \hline\member{setDropTolerance}&
424     &
425     &
426     &
427    &
428    &
429     &
430    &
431     \\
432    
433    \hline\member{setDropStorage}&
434     &
435     &
436     &
437    &
438    &
439     &
440    &
441     \\
442    
443    \hline\member{setRelaxationFactor}&
444     &
445     &
446     &
447    &
448    &
449    $\checkmark$  &
450     &
451     \\
452    
453    \hline\member{adaptInnerTolerance}&
454     &
455     &
456     &
457    &
458    &
459     &
460    &
461     \\
462    
463    \hline\member{setInnerIterMax}&
464     &
465     &
466     &
467    &
468    &
469     &
470    &
471     \\
472    \end{tabular}
473    }
474    \caption{Preconditioners available for \finley and the \PASO package and the relevant options in \class{SolverOptions}. \label{TAB FINLEY SOLVER OPTIONS 2}}
475    \end{table}
476    
477  \subsection{Functions}  \section{Linear Solvers in \SolverOptions}
478  \begin{funcdesc}{ReadMesh}{fileName,integrationOrder=-1}  Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and
479    Table~\ref{TAB FINLEY SOLVER OPTIONS 2} show the solvers and preconditioners supported by
480    \finley through the \PASO library. Currently direct solvers are not supported under MPI.
481    By default, \finley is using the iterative solvers \PCG for symmetric and \BiCGStab for non-symmetric problems.
482    If the direct solver is selected which can be useful when solving very ill-posed equations
483    \finley uses the \MKL \footnote{If the stiffness matrix is non-regular \MKL may return without
484    returning a proper error code. If you observe suspicious solutions when using MKL, this may cause by a non-invertible operator. } solver package. If \MKL is not available \UMFPACK is used. If \UMFPACK is not available
485    a suitable iterative solver from the \PASO is used.
486    
487    \section{Functions}
488    \begin{funcdesc}{ReadMesh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True}}
489  creates a \Domain object form the FEM mesh defined in  creates a \Domain object form the FEM mesh defined in
490  file \var{fileName}. The file must be given the \finley file format.  file \var{fileName}. The file must be given the \finley file format.
491  If \var{integrationOrder} is positive, a numerical integration scheme  If \var{integrationOrder} is positive, a numerical integration scheme
492  chosen which is accurate on each element up to a polynomial of  chosen which is accurate on each element up to a polynomial of
493  degree \var{integrationOrder} \index{integration order}. Otherwise  degree \var{integrationOrder} \index{integration order}. Otherwise
494    an appropriate integration order is chosen independently.
495    By default the labeling of mesh nodes and element distribution is
496    optimized. Set \var{optimize=False} to switch off relabeling and redistribution.
497    \end{funcdesc}
498    
499    \begin{funcdesc}{ReadGmsh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True\optional{, useMacroElements=False}}}
500    creates a \Domain object form the FEM mesh defined in
501    file \var{fileName}. The file must be given the \gmshextern file format.
502    If \var{integrationOrder} is positive, a numerical integration scheme
503    chosen which is accurate on each element up to a polynomial of
504    degree \var{integrationOrder} \index{integration order}. Otherwise
505  an appropriate integration order is chosen independently.  an appropriate integration order is chosen independently.
506    By default the labeling of mesh nodes and element distribution is
507    optimized. Set \var{optimize=False} to switch off relabeling and redistribution.
508    If \var{useMacroElements} is set, second order elements are interpreted as macro elements~\index{macro elements}.
509    Currently \function{ReadGmsh} does not support MPI.  
510  \end{funcdesc}  \end{funcdesc}
511    
512  \begin{funcdesc}{load}{fileName}  \begin{funcdesc}{MakeDomain}{design\optional{, integrationOrder=-1\optional{, optimizeLabeling=True\optional{, useMacroElements=False}}}}
513  recovers a \Domain object from a dump file created by the \  Creates a Finley \Domain from a \class{Design} object from \pycad using \gmshextern.
514  eateseates a \Domain object form the FEM mesh defined in  The \class{Design} \var{design} defines the geometry.
 file \var{fileName}. The file must be given the \finley file format.  
515  If \var{integrationOrder} is positive, a numerical integration scheme  If \var{integrationOrder} is positive, a numerical integration scheme
516  chosen which is accurate on each element up to a polynomial of  chosen which is accurate on each element up to a polynomial of
517  degree \var{integrationOrder} \index{integration order}. Otherwise  degree \var{integrationOrder} \index{integration order}. Otherwise
518  an appropriate integration order is chosen independently.  an appropriate integration order is chosen independently.
519    Set \var{optimizeLabeling=False} to switch off relabeling and redistribution (not recommended).
520    If \var{useMacroElements} is set, macro elements~\index{macro elements} are used.
521    Currently \function{MakeDomain} does not support MPI.  
522  \end{funcdesc}  \end{funcdesc}
523    
524    
525    \begin{funcdesc}{load}{fileName}
526    recovers a \Domain object from a dump file created by the \
527    \function{dump} method of a \Domain object defined in
528    file \var{fileName}.
529    \end{funcdesc}
530    
531    
532  \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, \\
533    periodic0=\False,periodic1=\False,useElementsOnFace=\False,optimize=\False}    periodic0=\False, periodic1=\False, useElementsOnFace=\False, useMacroElements=\False, optimize=\False}
534  Generates a \Domain object representing a two dimensional rectangle between  Generates a \Domain object representing a two dimensional rectangle between
535  $(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
536  \var{n0} elements along the $x_0$-axis and  \var{n0} elements along the $x_0$-axis and
# Line 302  For \var{order}=1 and \var{order}=2 Line 541  For \var{order}=1 and \var{order}=2
541  In the case of \var{useElementsOnFace}=\False,  In the case of \var{useElementsOnFace}=\False,
542  \finleyelement{Line2} and    \finleyelement{Line2} and  
543  \finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively.  \finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively.
544    If \var{order}=-1, \finleyelement{Rec8Macro} and \finleyelement{Line3Macro}~\index{macro elements}. This option should be used when solving incompressible fluid flow problem, e.g. \class{StokesProblemCartesian}.
545  In the case of \var{useElementsOnFace}=\True (this option should be used if gradients  In the case of \var{useElementsOnFace}=\True (this option should be used if gradients
546  are calculated on domain faces),  are calculated on domain faces),
547  \finleyelement{Rec4Face} and    \finleyelement{Rec4Face} and  
# Line 320  If \var{optimize}=\True mesh node relabe Line 560  If \var{optimize}=\True mesh node relabe
560  \end{funcdesc}  \end{funcdesc}
561    
562  \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, \\
563    periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False,optimize=\False}    periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False, useMacroElements=\False, optimize=\False}
564  Generates a \Domain object representing a three dimensional brick between  Generates a \Domain object representing a three dimensional brick between
565  $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with  $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with
566  \var{n0} elements along the $x_0$-axis,  \var{n0} elements along the $x_0$-axis,
# Line 336  In the case of \var{useElementsOnFace}=\ Line 576  In the case of \var{useElementsOnFace}=\
576  are calculated on domain faces),  are calculated on domain faces),
577  \finleyelement{Hex8Face} and    \finleyelement{Hex8Face} and  
578  \finleyelement{Hex20Face} are used on the brick faces, respectively.    \finleyelement{Hex20Face} are used on the brick faces, respectively.  
579    If \var{order}=-1, \finleyelement{Hex20Macro} and \finleyelement{Rec8Macro}~\index{macro elements}. This option should be used when solving incompressible fluid flow problem, e.g. \class{StokesProblemCartesian}.
580  If \var{integrationOrder} is positive, a numerical integration scheme  If \var{integrationOrder} is positive, a numerical integration scheme
581  chosen which is accurate on each element up to a polynomial of  chosen which is accurate on each element up to a polynomial of
582  degree \var{integrationOrder} \index{integration order}. Otherwise  degree \var{integrationOrder} \index{integration order}. Otherwise

Legend:
Removed from v.2417  
changed lines
  Added in v.3279

  ViewVC Help
Powered by ViewVC 1.1.26