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

trunk/esys2/doc/user/finley.tex revision 107 by jgs, Thu Jan 27 06:21:48 2005 UTC trunk/doc/user/finley.tex revision 1811 by ksteube, Thu Sep 25 23:11:13 2008 UTC
# Line 1  Line 1
% $Id$
1
2    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3    %
4    % Copyright (c) 2003-2008 by University of Queensland
5    % Earth Systems Science Computational Center (ESSCC)
6    % http://www.uq.edu.au/esscc
7    %
8    % Primary Business: Queensland, Australia
9    % Licensed under the Open Software License version 3.0
11    %
12    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13
14  \chapter{ The module \finley}
15    \chapter{ The Module \finley}
16   \label{CHAPTER ON FINLEY}   \label{CHAPTER ON FINLEY}
17
18  \begin{figure}  \begin{figure}
19  \centerline{\includegraphics[width=\figwidth]{FinleyMesh}}  \centerline{\includegraphics[width=\figwidth]{figures/FinleyMesh.eps}}
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]{FinleyContact}}  \centerline{\includegraphics[width=\figwidth]{figures/FinleyContact.eps}}
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 26  It supports unstructured, 1D, 2D and 3D Line 37  It supports unstructured, 1D, 2D and 3D
37  library through the \LinearPDE class of \escript supporting its full functionality. {\it finley}  library through the \LinearPDE class of \escript supporting its full functionality. {\it finley}
38  is parallelized using the OpenMP \index{OpenMP} paradigm.  is parallelized using the OpenMP \index{OpenMP} paradigm.
39
40  \subsection{Meshes}  \section{Formulation}
41
42    For a single PDE with a solution with a single component the linear PDE is defined in the
43    following form:
44    \label{FINLEY.SINGLE.1}
45    \begin{array}{cl} &
46    \displaystyle{
47    \int\hackscore{\Omega}
48    A\hackscore{jl} \cdot v\hackscore{,j}u\hackscore{,l}+ B\hackscore{j} \cdot v\hackscore{,j} u+ C\hackscore{l} \cdot v u\hackscore{,l}+D \cdot vu \; d\Omega }  \\
49    + & \displaystyle{\int\hackscore{\Gamma} d \cdot vu \; d{\Gamma} }
50    +  \displaystyle{\int\hackscore{\Gamma^{contact}} d^{contact} \cdot [v][u] \; d{\Gamma} } \\
51    = & \displaystyle{\int\hackscore{\Omega}  X\hackscore{j} \cdot v\hackscore{,j}+ Y \cdot v \; d\Omega }\\
52    + & \displaystyle{\int\hackscore{\Gamma} y \cdot v \; d{\Gamma}}  +
53    \displaystyle{\int\hackscore{\Gamma^{contact}} y^{contact}\cdot [v] \; d{\Gamma}} \\
54    \end{array}
55
56
57    \section{Meshes}
58  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
59  \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
60  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}.
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 56  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 107  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 151  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 227  $7$, $10$, $15$ and $20$, respectively. Line 255  $7$, $10$, $15$ and $20$, respectively.
255
256  \subsection{Linear Solvers in \LinearPDE}  \subsection{Linear Solvers in \LinearPDE}
257  Currently \finley supports the linear solvers \PCG, \GMRES, \PRESTWENTY and \BiCGStab.  Currently \finley supports the linear solvers \PCG, \GMRES, \PRESTWENTY and \BiCGStab.
258  For \GMRES the options \var{trancation} and \var{restart} of the \method{getSolution} can be  For \GMRES the options \var{truncation} and \var{restart} of the \method{getSolution} can be
259  used to control the trunction and restart during iteration. Default values are  used to control the truncation and restart during iteration. Default values are
260  \var{truncation}=5 and \var{restart}=20.  \var{truncation}=5 and \var{restart}=20.
261  The default solver is \BiCGStab  but if the symmetry flag is set \PCG is the default solver.  The default solver is \BiCGStab  but if the symmetry flag is set \PCG is the default solver.
262  \finley supports the solver options \var{iter_max} which specifies the maximum number of iterations steps,  \finley supports the solver options \var{iter_max} which specifies the maximum number of iterations steps,
# Line 237  In some installations \finley supports t Line 265  In some installations \finley supports t
265  solver options \var{reordering}=\constant{util.NO_REORDERING},  solver options \var{reordering}=\constant{util.NO_REORDERING},
266  \constant{util.MINIMUM_FILL_IN} or \constant{util.NESTED_DISSECTION} (default is \constant{util.NO_REORDERING}),  \constant{util.MINIMUM_FILL_IN} or \constant{util.NESTED_DISSECTION} (default is \constant{util.NO_REORDERING}),
267  \var{drop_tolerance} specifying the threshold for values to be dropped in the  \var{drop_tolerance} specifying the threshold for values to be dropped in the
268  incomplete elimation process (default is 0.01) and \var{drop_storage} specifying the maximum increase  incomplete elimination process (default is 0.01) and \var{drop_storage} specifying the maximum increase
269  in storage allowed in the  in storage allowed in the
270  incomplete elimation process (default is 1.20).  incomplete elimination process (default is 1.20).
271
272  \subsection{Functions}  \subsection{Functions}
273  \begin{funcdesc}{Mesh}{fileName,integrationOrder=-1}  \begin{funcdesc}{Mesh}{fileName,integrationOrder=-1}
# Line 251  degree \var{integrationOrder} \index{int Line 279  degree \var{integrationOrder} \index{int
279  an appropriate integration order is chosen independently.  an appropriate integration order is chosen independently.
280  \end{funcdesc}  \end{funcdesc}
281
\begin{funcdesc}{Interval}{n0,order=1,l0=1.,integrationOrder=-1, \\
periodic0=\False,useElementsOnFace=\False}
Generates a \Domain object representing a interval $[0,l0]$. The interval is filled with
\var{n0} elements.
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.
If \var{integrationOrder} is positive, a numerical integration scheme
chosen which is accurate on each element up to a polynomial of
degree \var{integrationOrder} \index{integration order}. Otherwise
an appropriate integration order is chosen independently. If
\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}$.
\end{funcdesc}

282  \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, \\
283    periodic0=\False,periodic1=\False,useElementsOnFace=\False}    periodic0=\False,periodic1=\False,useElementsOnFace=\False,optimize=\False}
284  Generates a \Domain object representing a two dimensional rectangle between  Generates a \Domain object representing a two dimensional rectangle between
285  $(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
286  \var{n0} elements along the $x_0$-axis and  \var{n0} elements along the $x_0$-axis and
# Line 299  the value on the line $x_0=0$ will be id Line 305  the value on the line $x_0=0$ will be id
305  Correspondingly,  Correspondingly,
306  \var{periodic1}=\False sets periodic boundary conditions  \var{periodic1}=\False sets periodic boundary conditions
307  in $x_1$-direction.  in $x_1$-direction.
308    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.
309  \end{funcdesc}  \end{funcdesc}
310
311  \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, \\
312    periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False}    periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False,optimize=\False}
313  Generates a \Domain object representing a three dimensional brick between  Generates a \Domain object representing a three dimensional brick between
314  $(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
315  \var{n0} elements along the $x_0$-axis,  \var{n0} elements along the $x_0$-axis,
# Line 327  along the $x_0$-directions are enforced. Line 334  along the $x_0$-directions are enforced.
334  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,
335  \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions  \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions
336  in $x_1$-direction and $x_2$-direction, respectively.  in $x_1$-direction and $x_2$-direction, respectively.
337    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.
338  \end{funcdesc}  \end{funcdesc}
339
340  \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}  \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
341  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.
342  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
343  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.
344
# Line 338  TODO: explain \var{safetyFactor} and sho Line 346  TODO: explain \var{safetyFactor} and sho
346  \end{funcdesc}  \end{funcdesc}
347
348  \begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}  \begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13}
349  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.
350  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
351  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}
352  The corresponding face elements are removed from the mesh.    The corresponding face elements are removed from the mesh.

Legend:
 Removed from v.107 changed lines Added in v.1811