/[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 1318 by ksteube, Wed Sep 26 04:39:14 2007 UTC revision 2558 by gross, Mon Jul 27 05:03:32 2009 UTC
# Line 1  Line 1 
1    
2    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3  %  %
4  % $Id$  % Copyright (c) 2003-2009 by University of Queensland
5  %  % Earth Systems Science Computational Center (ESSCC)
6  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  % http://www.uq.edu.au/esscc
 %  
 %           Copyright 2003-2007 by ACceSS MNRF  
 %       Copyright 2007 by University of Queensland  
 %  
 %                http://esscc.uq.edu.au  
 %        Primary Business: Queensland, Australia  
 %  Licensed under the Open Software License version 3.0  
 %     http://www.opensource.org/licenses/osl-3.0.php  
7  %  %
8  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  % Primary Business: Queensland, Australia
9    % Licensed under the Open Software License version 3.0
10    % http://www.opensource.org/licenses/osl-3.0.php
11  %  %
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 63  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 252  $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    
 \include{finleyelements}  
257    
258  \subsection{Linear Solvers in \LinearPDE}  \begin{table}
259  Currently \finley supports the linear solvers \PCG, \GMRES, \PRESTWENTY and \BiCGStab.  {\small
260  For \GMRES the options \var{truncation} and \var{restart} of the \method{getSolution} can be  \begin{tabular}{l||c|c|c|c|c|c|c|c}
261  used to control the truncation and restart during iteration. Default values are  \member{setSolverMethod} & \member{DIRECT}& \member{PCG} & \member{GMRES} & \member{TFQMR} & \member{MINRES} & \member{PRES20} & \member{BICGSTAB} & \member{LUMPING} \\
262  \var{truncation}=5 and \var{restart}=20.  \hline
263  The default solver is \BiCGStab  but if the symmetry flag is set \PCG is the default solver.   \hline
264  \finley supports the solver options \var{iter_max} which specifies the maximum number of iterations steps,   \member{setReordering} & $\checkmark$ & & & & & &\\
265  \var{verbose}=\True or \False and \var{preconditioner}=\constant{JACOBI} or \constant {ILU0}.   \hline  \member{setRestart} &  & & $\checkmark$ & & & $20$ & \\
266  In some installations \finley supports the \Direct solver and the   \hline\member{setTruncation} &  & & $\checkmark$ & & & $5$ & \\
267  solver options \var{reordering}=\constant{util.NO_REORDERING},     \hline\member{setIterMax} &  & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
268  \constant{util.MINIMUM_FILL_IN} or \constant{util.NESTED_DISSECTION} (default is \constant{util.NO_REORDERING}),   \hline\member{setTolerance} &  & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
269  \var{drop_tolerance} specifying the threshold for values to be dropped in the   \hline\member{setAbsoluteTolerance} &  & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
270  incomplete elimination process (default is 0.01) and \var{drop_storage} specifying the maximum increase  \end{tabular}
271  in storage allowed in the  }
272  incomplete elimination process (default is 1.20).  \caption{Solvers available for \finley and the \PASO package and the relevant options in \class{SolverOptions}
273     \label{TAB FINLEY SOLVER OPTIONS 1}}
274    \end{table}
275    
276    \begin{table}
277    {\scriptsize
278    \begin{tabular}{l||c|c|c|c|c|c|c|c}
279    \member{setPreconditioner} &
280    \member{NO_PRECONDITIONER} &
281    \member{AMG} &
282    \member{JACOBI} &
283    \member{GAUSS_SEIDEL}&
284    \member{REC_ILU}&
285    \member{RILU} &
286    \member{ILU0} &
287    \member{DIRECT} \\
288     \hline
289     status: &
290    later &
291    later &
292    $\checkmark$ &
293    $\checkmark$&
294    $\checkmark$ &
295    later &
296    $\checkmark$ &
297    later \\
298    \hline
299    \hline
300    \member{setCoarsening}&
301     &
302    $\checkmark$ &
303    &
304    &
305    &
306     &
307     &
308     \\
309    
310    
311    \hline\member{setLevelMax}&
312     &
313    $\checkmark$ &
314     &
315    &
316    &
317     &
318     &
319     \\
320    
321    \hline\member{setCoarseningThreshold}&
322    &
323    $\checkmark$ &
324     &
325    &
326    &
327     &
328     &
329     \\
330    
331    \hline\member{setMinCoarseMatrixSize} &
332     &
333    $\checkmark$ &
334     &
335    &
336    &
337     &
338     &
339     \\
340    
341    \hline\member{setNumSweeps} &
342     &
343     &
344    $\checkmark$ &
345    $\checkmark$ &
346    &
347     &
348     &
349     \\
350    
351    \hline\member{setNumPreSweeps}&
352     &
353    $\checkmark$ &
354      &
355     &
356     &
357      &
358      &
359      \\
360    
361    \hline\member{setNumPostSweeps} &
362     &
363    $\checkmark$ &
364     &
365    &
366    &
367     &
368    &
369     \\
370    
371    \hline\member{setInnerTolerance}&
372     &
373     &
374     &
375    &
376    &
377     &
378    &
379     \\
380    
381    \hline\member{setDropTolerance}&
382     &
383     &
384     &
385    &
386    &
387     &
388    &
389     \\
390    
391    \hline\member{setDropStorage}&
392     &
393     &
394     &
395    &
396    &
397     &
398    &
399     \\
400    
401    \hline\member{setRelaxationFactor}&
402     &
403     &
404     &
405    &
406    &
407    $\checkmark$  &
408     &
409     \\
410    
411    \hline\member{adaptInnerTolerance}&
412     &
413     &
414     &
415    &
416    &
417     &
418    &
419     \\
420    
421    \hline\member{setInnerIterMax}&
422     &
423     &
424     &
425    &
426    &
427     &
428    &
429     \\
430    \end{tabular}
431    }
432    \caption{Preconditioners available for \finley and the \PASO package and the relevant options in \class{SolverOptions}. \label{TAB FINLEY SOLVER OPTIONS 2}}
433    \end{table}
434    
435    \subsection{Linear Solvers in \SolverOptions}
436    Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and
437    Table~\ref{TAB FINLEY SOLVER OPTIONS 2} show the solvers and preconditioners supported by
438    \finley through the \PASO library. Currently direct solvers are not supported under MPI.
439    By default, \finley is using the iterative solvers \PCG for symmetric and \BiCGStab for non-symmetric problems.
440    If the direct solver is selected which can be useful when solving very ill-posedequations
441    \finley uses the \MKL solver package. If \MKL is not available \UMFPACK is used. If \UMFPACK is not available
442    a suitable iterative solver from the \PASO is used.
443    
444  \subsection{Functions}  \subsection{Functions}
445  \begin{funcdesc}{Mesh}{fileName,integrationOrder=-1}  \begin{funcdesc}{ReadMesh}{fileName,integrationOrder=-1}
446  creates a \Domain object form the FEM mesh defined in  creates a \Domain object form the FEM mesh defined in
447  file \var{fileName}. The file must be given the \finley file format.  file \var{fileName}. The file must be given the \finley file format.
448  If \var{integrationOrder} is positive, a numerical integration scheme  If \var{integrationOrder} is positive, a numerical integration scheme
# Line 281  degree \var{integrationOrder} \index{int Line 451  degree \var{integrationOrder} \index{int
451  an appropriate integration order is chosen independently.  an appropriate integration order is chosen independently.
452  \end{funcdesc}  \end{funcdesc}
453    
454  \begin{funcdesc}{Interval}{n0,order=1,l0=1.,integrationOrder=-1, \\  \begin{funcdesc}{load}{fileName}
455    periodic0=\False,useElementsOnFace=\False}  recovers a \Domain object from a dump file created by the \
456  Generates a \Domain object representing a interval $[0,l0]$. The interval is filled with  eateseates a \Domain object form the FEM mesh defined in
457  \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.    
458  If \var{integrationOrder} is positive, a numerical integration scheme  If \var{integrationOrder} is positive, a numerical integration scheme
459  chosen which is accurate on each element up to a polynomial of  chosen which is accurate on each element up to a polynomial of
460  degree \var{integrationOrder} \index{integration order}. Otherwise  degree \var{integrationOrder} \index{integration order}. Otherwise
461  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}$.  
462  \end{funcdesc}  \end{funcdesc}
463    
464  \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, \\
465    periodic0=\False,periodic1=\False,useElementsOnFace=\False}    periodic0=\False,periodic1=\False,useElementsOnFace=\False,optimize=\False}
466  Generates a \Domain object representing a two dimensional rectangle between  Generates a \Domain object representing a two dimensional rectangle between
467  $(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
468  \var{n0} elements along the $x_0$-axis and  \var{n0} elements along the $x_0$-axis and
# Line 329  the value on the line $x_0=0$ will be id Line 487  the value on the line $x_0=0$ will be id
487  Correspondingly,  Correspondingly,
488  \var{periodic1}=\False sets periodic boundary conditions  \var{periodic1}=\False sets periodic boundary conditions
489  in $x_1$-direction.  in $x_1$-direction.
490    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.
491  \end{funcdesc}  \end{funcdesc}
492    
493  \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, \\
494    periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False}    periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False,optimize=\False}
495  Generates a \Domain object representing a three dimensional brick between  Generates a \Domain object representing a three dimensional brick between
496  $(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
497  \var{n0} elements along the $x_0$-axis,  \var{n0} elements along the $x_0$-axis,
# Line 357  along the $x_0$-directions are enforced. Line 516  along the $x_0$-directions are enforced.
516  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,
517  \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions  \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions
518  in $x_1$-direction and $x_2$-direction, respectively.  in $x_1$-direction and $x_2$-direction, respectively.
519    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.
520  \end{funcdesc}  \end{funcdesc}
521    
522  \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}  \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}

Legend:
Removed from v.1318  
changed lines
  Added in v.2558

  ViewVC Help
Powered by ViewVC 1.1.26