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

revision 104 by jgs, Fri Dec 17 07:43:12 2004 UTC revision 107 by jgs, Thu Jan 27 06:21:48 2005 UTC
# Line 28  is parallelized using the OpenMP \index{ Line 28  is parallelized using the OpenMP \index{
28
29  \subsection{Meshes}  \subsection{Meshes}
30  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
31  \index{FEM!mesh} are defined. \fig{FINLEY FIG 0} shoes an example of the  \index{FEM!mesh} are defined. \fig{FINLEY FIG 0} shows an example of the
32  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}.
33  In this case, triangles have been used but other forms of subdivisions  In this case, triangles have been used but other forms of subdivisions
34  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
35  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
36  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 neighbour elements.
37  In the example of \fig{FINLEY FIG 0} a linear polynomial is used on each triangle. As one can seen, the triangulation  In the example of \fig{FINLEY FIG 0} a linear polynomial is used on each triangle. As one can see, the triangulation
38  is a quite poor approximation of the ellipse. It can be improved by introducing a midpoint on each element edge and  is quite a poor approximation of the ellipse. It can be improved by introducing a midpoint on each element edge then
39  position those nodes, which are located on an edge expecting to describing the boundary, onto the boundary.  positioning those nodes located on an edge expected to describe the boundary, onto the boundary.
40  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 parametrization of the triangle using a
41  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
42  (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.
43
44  The union of all elements defines the domain of the PDE.  The union of all elements defines the domain of the PDE.
45  Each element is defined by the nodes used to describe is 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,
46  which have type \finleyelement{Tri3},  which has type \finleyelement{Tri3},
47  with the element reference number $19$ \index{element!reference number} is defined by the nodes  with element reference number $19$ \index{element!reference number} is defined by the nodes
48  with the reference numbers $9$, $11$ and $0$ \index{node!reference number}. Notice that the order is counterclockwise.  with reference numbers $9$, $11$ and $0$ \index{node!reference number}. Notice that the order is counterclockwise.
49  The coefficients of the PDE are evaluated at integration nodes with each individual element.  The coefficients of the PDE are evaluated at integration nodes with each individual element.
50  For quadrilateral elements a Gauss quadrature scheme is used. In the case of triangular elements a  For quadrilateral elements a Gauss quadrature scheme is used. In the case of triangular elements a
51  modified from is applied. The boundary of the domain is also subdivided into elements \index{element!face}. In \fig{FINLEY FIG 0}  modified form is applied. The boundary of the domain is also subdivided into elements. \index{element!face} In \fig{FINLEY FIG 0}
52  line elements with two nodes are used. The elements are also defined by their describing nodes, e.g.  line elements with two nodes are used. The elements are also defined by their describing nodes, e.g.
53  the face element reference number $20$ which has type \finleyelement{Line2} is defined by the nodes  the face element reference number $20$ which has type \finleyelement{Line2} is defined by the nodes
54  with the reference numbers $11$ and $0$. Again the order is crucial, if moving from the first  with the reference numbers $11$ and $0$. Again the order is crucial, if moving from the first
55  to second node the domain has to lay on the left hand side (in case of a two dimension surface element  to second node the domain has to lie on the left hand side (in the case of a two dimension surface element
56  the domain has to lay on 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
57  surface of the domain wants 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
58  is 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
59  with the surface of the domian. In \fig{FINLEY FIG 0}  with the surface of the domian. In \fig{FINLEY FIG 0}
60  elements of the type \finleyelement{Tri3Face} are used.  elements of the type \finleyelement{Tri3Face} are used.
61  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
62  with the 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
63  interior element $19$ however, in this case, the order of the node is different to align the first  interior element $19$ except that, in this case, the order of the node is different to align the first
64  edge of the triangle (which is the edge starting with the first node) with the boundary of the domain.  edge of the triangle (which is the edge starting with the first node) with the boundary of the domain.
65
66  Be aware that face elements and elements in the interior of the domain must match, i.e. a face element must be the face  Be aware that face elements and elements in the interior of the domain must match, i.e. a face element must be the face
67  of an interior element or, in case of a rich face element, must be identical to an interior element.  of an interior element or, in case of a rich face element, it must be identical to an interior element.
68  If no face elements are specified  If no face elements are specified
69  \finley implicitly assumes homogeneous natural boundary conditions \index{natural boundary conditions!homogeneous},  \finley implicitly assumes homogeneous natural boundary conditions \index{natural boundary conditions!homogeneous},
70  i.e. \var{d}=$0$ and \var{y}=$0$, on the entire boundary of the domain. For    i.e. \var{d}=$0$ and \var{y}=$0$, on the entire boundary of the domain. For
# Line 77  even if $d^{contact}$ and $y^{contact}$ Line 77  even if $d^{contact}$ and $y^{contact}$
77  of rectangular elements around a contact region $\Gamma^{contact}$ \index{element!contact}.  of rectangular elements around a contact region $\Gamma^{contact}$ \index{element!contact}.
78  The contact region is described by the  The contact region is described by the
79  elements $4$, $3$ and $6$. Their element type is \finleyelement{Line2_Contact}.  elements $4$, $3$ and $6$. Their element type is \finleyelement{Line2_Contact}.
80  The nodes $9$, $12$, $6$, $5$ are defining contact element $4$, where the coordinates of nodes $12$ and $5$ and  The nodes $9$, $12$, $6$, $5$ define contact element $4$, where the coordinates of nodes $12$ and $5$ and
81  nodes $4$ and $6$ are identical with the idea that nodes $12$ and $9$ are located above and  nodes $4$ and $6$ are identical with the idea that nodes $12$ and $9$ are located above and
82  nodes $5$ and $6$ are below the contact region.    nodes $5$ and $6$ below the contact region.
83  Again, the order of the nodes within an element is crucial. There is also the option of using rich elements  Again, the order of the nodes within an element is crucial. There is also the option of using rich elements
84  if the gradient wants to be calculated on the contact region. Similar to the rich face elements  if the gradient is to be calculated on the contact region. Similarly to the rich face elements
85  they are constructed from two interior elements with reordering the nodes such that  these are constructed from two interior elements by reordering the nodes such that
86  the 'first' face of the element above and the 'first' face of the element below the  the 'first' face of the element above and the 'first' face of the element below the
87  contact regions are lining up.  The rich version of element  contact regions line up.  The rich version of element
88  $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
89  $2$.  $2$.
90
91  \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
92  on 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
93  the nodes within an element.  the nodes within an element.
94
95  \begin{table}  \begin{table}
# Line 107  the nodes within an element. Line 107  the nodes within an element.
107  \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}}
108  \end{tablev}  \end{tablev}
109  \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.
110  The rich types have to be used if the gradient of function wants to 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, resepctively.}
111  \label{FINLEY TAB 1}  \label{FINLEY TAB 1}
112  \end{table}  \end{table}
113
114  The native \finley file format is defined as follows.  The native \finley file format is defined as follows.
115  Each node \var{i} has \var{dim} spatial coordinates \var{Node[i]}, a reference number  Each node \var{i} has \var{dim} spatial coordinates \var{Node[i]}, a reference number
116  \var{Node_ref[i]}, a degree of freedom \var{Node_DOF[i]} and tag \var{Node_tag[i]}.  \var{Node_ref[i]}, a degree of freedom \var{Node_DOF[i]} and tag \var{Node_tag[i]}.
117  In most cases \var{Node_DOF[i]}=\var{Node_ref[i]} however for periodic boundary conditions  In most cases \var{Node_DOF[i]}=\var{Node_ref[i]} however, for periodic boundary conditions,
118  \var{Node_DOF[i]} is chosen differently, see example below. The tag can be used to mark nodes sharing  \var{Node_DOF[i]} is chosen differently, see example below. The tag can be used to mark nodes sharing
119  the same properties. Element \var{i} is defined by the \var{Element_numNodes} nodes \var{Element_Nodes[i]}  the same properties. Element \var{i} is defined by the \var{Element_numNodes} nodes \var{Element_Nodes[i]}
120  which is a list of node reference numbers. The order is crucial.  which is a list of node reference numbers. The order is crucial.
121  It has a reference number \var{Element_ref[i]} and a tag \var{Element_tag[i]}. The tag  It has a reference number \var{Element_ref[i]} and a tag \var{Element_tag[i]}. The tag
122  can be used to mark elements  sharing the same properties. For instance elements above  can be used to mark elements  sharing the same properties. For instance elements above
123  a contact region are marked with $2$ and element below a contact region are marked with $1$.  a contact region are marked with $2$ and elements below a contact region are marked with $1$.
124  \var{Element_Type} and \var{Element_Num} give the element type and the number of elements in the mesh.  \var{Element_Type} and \var{Element_Num} give the element type and the number of elements in the mesh.
125  Analogue notations are used for face and contact elements. The following Python script  Analogue notations are used for face and contact elements. The following Python script
126  prints the mesh definition in the \finley file format:  prints the mesh definition in the \finley file format:
# Line 189  Line2_Contact 3 Line 189  Line2_Contact 3
189  Point1 0  Point1 0
190  \end{verbatim}  \end{verbatim}
191  Notice that the order in which the nodes and elements are given is arbitrary.  Notice that the order in which the nodes and elements are given is arbitrary.
192  In that case rich contact element are used the contact element section get the form  In the case that rich contact elements are used the contact element section gets
193     the form
194  \begin{verbatim}  \begin{verbatim}
195  Rec4Face_Contact 3  Rec4Face_Contact 3
196   4 0  9 12 16 18  6  5  0  2   4 0  9 12 16 18  6  5  0  2
# Line 197  Rec4Face_Contact 3 Line 198  Rec4Face_Contact 3
198   6 0 15 13 19 20 10  8  3  7   6 0 15 13 19 20 10  8  3  7
199  \end{verbatim}  \end{verbatim}
200  Periodic boundary condition \index{boundary conditions!periodic} can be introduced by altering \var{Node_DOF}.  Periodic boundary condition \index{boundary conditions!periodic} can be introduced by altering \var{Node_DOF}.
201  It allows to identify nodes even if they have different physical locations. For instance, to  It allows identification of nodes even if they have different physical locations. For instance, to
202  enforce periodic boundary conditions at the face $x_0=0$ and $x_0=1$ one identifies  enforce periodic boundary conditions at the face $x_0=0$ and $x_0=1$ one identifies
203  the degrees of freedom for nodes $0$, $5$, $12$ and $16$ with the degrees of freedom for  the degrees of freedom for nodes $0$, $5$, $12$ and $16$ with the degrees of freedom for
204  $7$, $10$, $15$ and $20$, respectively. The node section of the \finley mesh gets now the form:    $7$, $10$, $15$ and $20$, respectively. The node section of the \finley mesh gets now the form:
# Line 225  $7$, $10$, $15$ and $20$, respectively. Line 226  $7$, $10$, $15$ and $20$, respectively.
226  \include{finleyelements}  \include{finleyelements}
227
228  \subsection{Linear Solvers in \LinearPDE}  \subsection{Linear Solvers in \LinearPDE}
229  Currently \finley support the linear solvers \PCG, \GMRES, \PRESTWENTY and \BiCGStab.  Currently \finley supports the linear solvers \PCG, \GMRES, \PRESTWENTY and \BiCGStab.
230  For \GMRES the options \var{trancation} and \var{restart} of the \method{getSolution} can be  For \GMRES the options \var{trancation} and \var{restart} of the \method{getSolution} can be
231  used to control the trunction and restart during iteration. Default values are  used to control the trunction and restart during iteration. Default values are
232  \var{truncation}=5 and \var{restart}=20.  \var{truncation}=5 and \var{restart}=20.
233  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.
234  \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,
235  \var{verbose}=\True or \False and \var{preconditioner}=\constant{JACOBI} or \constant {ILU0}.  \var{verbose}=\True or \False and \var{preconditioner}=\constant{JACOBI} or \constant {ILU0}.
236  In some installation \finley supports \Direct solver and the  In some installations \finley supports the \Direct solver and the
237  solver options \var{reordering}=\constant{util.NO_REORDERING},  solver options \var{reordering}=\constant{util.NO_REORDERING},
238  \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}),
239  \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

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