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

Revision 625 - (hide annotations)
Thu Mar 23 00:41:25 2006 UTC (13 years ago) by gross
File MIME type: application/x-tex
File size: 19361 byte(s)
some updates and linearPDE.tex switched off

 1 jgs 102 % $Id$ 2 gross 625 % 3 % Copyright © 2006 by ACcESS MNRF 4 % \url{http://www.access.edu.au 5 % Primary Business: Queensland, Australia. 6 % Licensed under the Open Software License version 3.0 7 8 % 9 jgs 102 10 11 gross 625 12 jgs 102 \chapter{ The module \finley} 13 \label{CHAPTER ON FINLEY} 14 15 \begin{figure} 16 gross 599 \centerline{\includegraphics[width=\figwidth]{figures/FinleyMesh.eps}} 17 jgs 102 \caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})} 18 \label{FINLEY FIG 0} 19 \end{figure} 20 21 \begin{figure} 22 gross 599 \centerline{\includegraphics[width=\figwidth]{figures/FinleyContact.eps}} 23 jgs 102 \caption{Mesh around a contact region (\finleyelement{Rec4})} 24 \label{FINLEY FIG 01} 25 \end{figure} 26 27 \declaremodule{extension}{finley} \modulesynopsis{Solving linear, steady partial differential equations using 28 finite elements} 29 30 {\it finley} is a library of C functions solving linear, steady partial differential equations 31 \index{partial differential equations} (PDEs) or systems of PDEs using isoparametrical finite 32 elements \index{FEM!isoparametrical}. 33 It supports unstructured, 1D, 2D and 3D meshes. The module \finley provides an access to the 34 library through the \LinearPDE class of \escript supporting its full functionality. {\it finley} 35 is parallelized using the OpenMP \index{OpenMP} paradigm. 36 37 \subsection{Meshes} 38 To understand the usage of \finley one needs to have an understanding of how the finite element meshes 39 jgs 107 \index{FEM!mesh} are defined. \fig{FINLEY FIG 0} shows an example of the 40 jgs 102 subdivision of an ellipse into so called elements \index{FEM!elements} \index{element}. 41 In this case, triangles have been used but other forms of subdivisions 42 can be constructed, e.g. into quadrilaterals or, in the three dimensional case, into tetrahedrons 43 and hexahedrons. The idea of the finite element method is to approximate the solution by a function 44 which is a polynomial of a certain order and is continuous across it boundary to neighbour elements. 45 jgs 107 In the example of \fig{FINLEY FIG 0} a linear polynomial is used on each triangle. As one can see, the triangulation 46 is quite a poor approximation of the ellipse. It can be improved by introducing a midpoint on each element edge then 47 positioning those nodes located on an edge expected to describe the boundary, onto the boundary. 48 jgs 102 In this case the triangle gets a curved edge which requires a parametrization of the triangle using a 49 quadratic polynomial. For this case, the solution is also approximated by a piecewise quadratic polynomial 50 (which explains the name isoparametrical elements), see \Ref{Zienc,NumHand} for more details. 51 52 The union of all elements defines the domain of the PDE. 53 jgs 107 Each element is defined by the nodes used to describe its shape. In \fig{FINLEY FIG 0} the element, 54 which has type \finleyelement{Tri3}, 55 with element reference number $19$ \index{element!reference number} is defined by the nodes 56 with reference numbers $9$, $11$ and $0$ \index{node!reference number}. Notice that the order is counterclockwise. 57 jgs 102 The coefficients of the PDE are evaluated at integration nodes with each individual element. 58 For quadrilateral elements a Gauss quadrature scheme is used. In the case of triangular elements a 59 jgs 107 modified form is applied. The boundary of the domain is also subdivided into elements. \index{element!face} In \fig{FINLEY FIG 0} 60 jgs 102 line elements with two nodes are used. The elements are also defined by their describing nodes, e.g. 61 the face element reference number $20$ which has type \finleyelement{Line2} is defined by the nodes 62 with the reference numbers $11$ and $0$. Again the order is crucial, if moving from the first 63 jgs 107 to second node the domain has to lie on the left hand side (in the case of a two dimension surface element 64 the domain has to lie on the left hand side when moving counterclockwise). If the gradient on the 65 surface of the domain is to be calculated rich face elements face to be used. Rich elements on a face 66 are identical to interior elements but with a modified order of nodes such that the 'first' face of the element aligns 67 jgs 102 with the surface of the domian. In \fig{FINLEY FIG 0} 68 elements of the type \finleyelement{Tri3Face} are used. 69 The face element reference number $20$ as a rich face element is defined by the nodes 70 jgs 107 with reference numbers $11$, $0$ and $9$. Notice that the face element $20$ is identical to the 71 interior element $19$ except that, in this case, the order of the node is different to align the first 72 jgs 102 edge of the triangle (which is the edge starting with the first node) with the boundary of the domain. 73 74 Be aware that face elements and elements in the interior of the domain must match, i.e. a face element must be the face 75 jgs 107 of an interior element or, in case of a rich face element, it must be identical to an interior element. 76 jgs 102 If no face elements are specified 77 \finley implicitly assumes homogeneous natural boundary conditions \index{natural boundary conditions!homogeneous}, 78 i.e. \var{d}=$0$ and \var{y}=$0$, on the entire boundary of the domain. For 79 inhomogeneous natural boundary conditions \index{natural boundary conditions!inhomogeneous}, 80 the boundary must be described by face elements. 81 82 If discontinuities of the PDE solution are considered contact elements 83 \index{element!contact}\index{contact conditions} are introduced to describe the contact region $\Gamma^{contact}$ 84 even if $d^{contact}$ and $y^{contact}$ are zero. \fig{FINLEY FIG 01} shows a simple example of a mesh 85 of rectangular elements around a contact region $\Gamma^{contact}$ \index{element!contact}. 86 The contact region is described by the 87 elements $4$, $3$ and $6$. Their element type is \finleyelement{Line2_Contact}. 88 jgs 107 The nodes $9$, $12$, $6$, $5$ define contact element $4$, where the coordinates of nodes $12$ and $5$ and 89 jgs 102 nodes $4$ and $6$ are identical with the idea that nodes $12$ and $9$ are located above and 90 jgs 107 nodes $5$ and $6$ below the contact region. 91 jgs 102 Again, the order of the nodes within an element is crucial. There is also the option of using rich elements 92 jgs 107 if the gradient is to be calculated on the contact region. Similarly to the rich face elements 93 these are constructed from two interior elements by reordering the nodes such that 94 jgs 102 the 'first' face of the element above and the 'first' face of the element below the 95 jgs 107 contact regions line up. The rich version of element 96 jgs 102 $4$ is of type \finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$, $18$, $6$, $5$, $0$ and 97 $2$. 98 99 \tab{FINLEY TAB 1} shows the interior element types and the corresponding element types to be used 100 jgs 107 on the face and contacts. \fig{FINLEY.FIG:1}, \fig{FINLEY.FIG:2} and \fig{FINLEY.FIG:4} show the ordering of 101 jgs 102 the nodes within an element. 102 103 \begin{table} 104 \begin{tablev}{l|llll}{textrm}{interior}{face}{rich face}{contact}{rich contact} 105 \linev{\finleyelement{Line2}}{\finleyelement{Point1}}{\finleyelement{Line2Face}}{\finleyelement{Point1_Contact}}{\finleyelement{Line2Face_Contact}} 106 \linev{\finleyelement{Line3}}{\finleyelement{Point1}}{\finleyelement{Line3Face}}{\finleyelement{Point1_Contact}}{\finleyelement{Line3Face_Contact}} 107 \linev{\finleyelement{Tri3}}{\finleyelement{Line2}}{\finleyelement{Tri3Face}}{\finleyelement{Line2_Contact}}{\finleyelement{Tri3Face_Contact}} 108 \linev{\finleyelement{Tri6}}{\finleyelement{Line3}}{\finleyelement{Tri6Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Tri6Face_Contact}} 109 \linev{\finleyelement{Rec4}}{\finleyelement{Line2}}{\finleyelement{Rec4Face}}{\finleyelement{Line2_Contact}}{\finleyelement{Rec4Face_Contact}} 110 \linev{\finleyelement{Rec8}}{\finleyelement{Line3}}{\finleyelement{Rec8Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Rec8Face_Contact}} 111 \linev{\finleyelement{Rec9}}{\finleyelement{Line3}}{\finleyelement{Rec9Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Rec9Face_Contact}} 112 \linev{\finleyelement{Tet4}}{\finleyelement{Tri6}}{\finleyelement{Tet4Face}}{\finleyelement{Tri6_Contact}}{\finleyelement{Tet4Face_Contact}} 113 \linev{\finleyelement{Tet10}}{\finleyelement{Tri9}}{\finleyelement{Tet10Face}}{\finleyelement{Tri9_Contact}}{\finleyelement{Tet10Face_Contact}} 114 \linev{\finleyelement{Hex8}}{\finleyelement{Rec4}}{\finleyelement{Hex8Face}}{\finleyelement{Rec4_Contact}}{\finleyelement{Hex8Face_Contact}} 115 \linev{\finleyelement{Hex20}}{\finleyelement{Rec8}}{\finleyelement{Hex20Face}}{\finleyelement{Rec8_Contact}}{\finleyelement{Hex20Face_Contact}} 116 \end{tablev} 117 \caption{Finley elements and corresponding elements to be used on domain faces and contacts. 118 jgs 107 The rich types have to be used if the gradient of function is to be calculated on faces and contacts, resepctively.} 119 jgs 102 \label{FINLEY TAB 1} 120 \end{table} 121 122 The native \finley file format is defined as follows. 123 Each node \var{i} has \var{dim} spatial coordinates \var{Node[i]}, a reference number 124 \var{Node_ref[i]}, a degree of freedom \var{Node_DOF[i]} and tag \var{Node_tag[i]}. 125 jgs 107 In most cases \var{Node_DOF[i]}=\var{Node_ref[i]} however, for periodic boundary conditions, 126 jgs 102 \var{Node_DOF[i]} is chosen differently, see example below. The tag can be used to mark nodes sharing 127 the same properties. Element \var{i} is defined by the \var{Element_numNodes} nodes \var{Element_Nodes[i]} 128 which is a list of node reference numbers. The order is crucial. 129 It has a reference number \var{Element_ref[i]} and a tag \var{Element_tag[i]}. The tag 130 can be used to mark elements sharing the same properties. For instance elements above 131 jgs 107 a contact region are marked with $2$ and elements below a contact region are marked with $1$. 132 jgs 102 \var{Element_Type} and \var{Element_Num} give the element type and the number of elements in the mesh. 133 Analogue notations are used for face and contact elements. The following Python script 134 prints the mesh definition in the \finley file format: 135 \begin{python} 136 print "%s\n"%mesh_name 137 # node coordinates: 138 print "%dD-nodes %d\n"%(dim,numNodes) 139 for i in range(numNodes): 140 print "%d %d %d"%(Node_ref[i],Node_DOF[i],Node_tag[i]) 141 for j in range(dim): print " %e"%Node[i][j] 142 print "\n" 143 # interior elements 144 print "%s %d\n"%(Element_Type,Element_Num) 145 for i in range(Element_Num): 146 print "%d %d"%(Element_ref[i],Element_tag[i]) 147 for j in range(Element_numNodes): print " %d"%Element_Nodes[i][j] 148 print "\n" 149 # face elements 150 print "%s %d\n"%(FaceElement_Type,FaceElement_Num) 151 for i in range(FaceElement_Num): 152 print "%d %d"%(FaceElement_ref[i],FaceElement_tag[i]) 153 for j in range(FaceElement_numNodes): print " %d"%FaceElement_Nodes[i][j] 154 print "\n" 155 # contact elements 156 print "%s %d\n"%(ContactElement_Type,ContactElement_Num) 157 for i in range(ContactElement_Num): 158 print "%d %d"%(ContactElement_ref[i],ContactElement_tag[i]) 159 for j in range(ContactElement_numNodes): print " %d"%ContactElement_Nodes[i][j] 160 print "\n" 161 # point sources (not supported yet) 162 write("Point1 0",face_element_typ,numFaceElements) 163 \end{python} 164 165 The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}: 166 \begin{verbatim} 167 Example 1 168 2D Nodes 16 169 0 0 0 0. 0. 170 2 2 0 0.33 0. 171 3 3 0 0.66 0. 172 7 4 0 1. 0. 173 5 5 0 0. 0.5 174 6 6 0 0.33 0.5 175 8 8 0 0.66 0.5 176 10 10 0 1.0 0.5 177 12 12 0 0. 0.5 178 9 9 0 0.33 0.5 179 13 13 0 0.66 0.5 180 15 15 0 1.0 0.5 181 16 16 0 0. 1.0 182 18 18 0 0.33 1.0 183 19 19 0 0.66 1.0 184 20 20 0 1.0 1.0 185 Rec4 6 186 0 1 0 2 6 5 187 1 1 2 3 8 6 188 2 1 3 7 10 8 189 5 2 12 9 18 16 190 7 2 13 19 18 9 191 10 2 20 19 13 15 192 Line2 0 193 Line2_Contact 3 194 4 0 9 12 6 5 195 3 0 13 9 8 6 196 6 0 15 13 10 8 197 Point1 0 198 \end{verbatim} 199 Notice that the order in which the nodes and elements are given is arbitrary. 200 jgs 107 In the case that rich contact elements are used the contact element section gets 201 the form 202 jgs 102 \begin{verbatim} 203 Rec4Face_Contact 3 204 4 0 9 12 16 18 6 5 0 2 205 3 0 13 9 18 19 8 6 2 3 206 6 0 15 13 19 20 10 8 3 7 207 \end{verbatim} 208 Periodic boundary condition \index{boundary conditions!periodic} can be introduced by altering \var{Node_DOF}. 209 jgs 107 It allows identification of nodes even if they have different physical locations. For instance, to 210 jgs 102 enforce periodic boundary conditions at the face $x_0=0$ and $x_0=1$ one identifies 211 the degrees of freedom for nodes $0$, $5$, $12$ and $16$ with the degrees of freedom for 212 $7$, $10$, $15$ and $20$, respectively. The node section of the \finley mesh gets now the form: 213 \begin{verbatim} 214 2D Nodes 16 215 0 0 0 0. 0. 216 2 2 0 0.33 0. 217 3 3 0 0.66 0. 218 7 0 0 1. 0. 219 5 5 0 0. 0.5 220 6 6 0 0.33 0.5 221 8 8 0 0.66 0.5 222 10 5 0 1.0 0.5 223 12 12 0 0. 0.5 224 9 9 0 0.33 0.5 225 13 13 0 0.66 0.5 226 15 12 0 1.0 0.5 227 16 16 0 0. 1.0 228 18 18 0 0.33 1.0 229 19 19 0 0.66 1.0 230 20 16 0 1.0 1.0 231 \end{verbatim} 232 233 234 \include{finleyelements} 235 236 \subsection{Linear Solvers in \LinearPDE} 237 jgs 107 Currently \finley supports the linear solvers \PCG, \GMRES, \PRESTWENTY and \BiCGStab. 238 jgs 102 For \GMRES the options \var{trancation} and \var{restart} of the \method{getSolution} can be 239 used to control the trunction and restart during iteration. Default values are 240 \var{truncation}=5 and \var{restart}=20. 241 jgs 107 The default solver is \BiCGStab but if the symmetry flag is set \PCG is the default solver. 242 jgs 102 \finley supports the solver options \var{iter_max} which specifies the maximum number of iterations steps, 243 \var{verbose}=\True or \False and \var{preconditioner}=\constant{JACOBI} or \constant {ILU0}. 244 jgs 107 In some installations \finley supports the \Direct solver and the 245 jgs 102 solver options \var{reordering}=\constant{util.NO_REORDERING}, 246 \constant{util.MINIMUM_FILL_IN} or \constant{util.NESTED_DISSECTION} (default is \constant{util.NO_REORDERING}), 247 \var{drop_tolerance} specifying the threshold for values to be dropped in the 248 incomplete elimation process (default is 0.01) and \var{drop_storage} specifying the maximum increase 249 in storage allowed in the 250 incomplete elimation process (default is 1.20). 251 252 \subsection{Functions} 253 \begin{funcdesc}{Mesh}{fileName,integrationOrder=-1} 254 creates a \Domain object form the FEM mesh defined in 255 file \var{fileName}. The file must be given the \finley file format. 256 If \var{integrationOrder} is positive, a numerical integration scheme 257 chosen which is accurate on each element up to a polynomial of 258 degree \var{integrationOrder} \index{integration order}. Otherwise 259 an appropriate integration order is chosen independently. 260 \end{funcdesc} 261 262 \begin{funcdesc}{Interval}{n0,order=1,l0=1.,integrationOrder=-1, \\ 263 periodic0=\False,useElementsOnFace=\False} 264 Generates a \Domain object representing a interval $[0,l0]$. The interval is filled with 265 \var{n0} elements. 266 For \var{order}=1 and \var{order}=2 267 \finleyelement{Line2} and 268 \finleyelement{Line3} are used, respectively. 269 In the case of \var{useElementsOnFace}=\False, 270 \finleyelement{Point1} are used to describe the boundary points. 271 In the case of \var{useElementsOnFace}=\True (this option should be used if gradients 272 are calculated on domain faces), 273 \finleyelement{Line2} and 274 \finleyelement{Line3} are used on both ends of the interval. 275 If \var{integrationOrder} is positive, a numerical integration scheme 276 chosen which is accurate on each element up to a polynomial of 277 degree \var{integrationOrder} \index{integration order}. Otherwise 278 an appropriate integration order is chosen independently. If 279 \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions} 280 along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley 281 the value at $x_0=0$ will be identical to the values at $x_0=\var{l0}$. 282 \end{funcdesc} 283 284 \begin{funcdesc}{Rectangle}{n0,n1,order=1,l0=1.,l1=1., integrationOrder=-1, \\ 285 periodic0=\False,periodic1=\False,useElementsOnFace=\False} 286 Generates a \Domain object representing a two dimensional rectangle between 287 $(0,0)$ and $(l0,l1)$ with orthogonal edges. The rectangle is filled with 288 \var{n0} elements along the $x_0$-axis and 289 \var{n1} elements along the $x_1$-axis. 290 For \var{order}=1 and \var{order}=2 291 \finleyelement{Rec4} and 292 \finleyelement{Rec8} are used, respectively. 293 In the case of \var{useElementsOnFace}=\False, 294 \finleyelement{Line2} and 295 \finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively. 296 In the case of \var{useElementsOnFace}=\True (this option should be used if gradients 297 are calculated on domain faces), 298 \finleyelement{Rec4Face} and 299 \finleyelement{Rec8Face} are used on the edges, respectively. 300 If \var{integrationOrder} is positive, a numerical integration scheme 301 chosen which is accurate on each element up to a polynomial of 302 degree \var{integrationOrder} \index{integration order}. Otherwise 303 an appropriate integration order is chosen independently. If 304 \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions} 305 along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley 306 the value on the line $x_0=0$ will be identical to the values on $x_0=\var{l0}$. 307 Correspondingly, 308 \var{periodic1}=\False sets periodic boundary conditions 309 in $x_1$-direction. 310 \end{funcdesc} 311 312 \begin{funcdesc}{Brick}{n0,n1,n2,order=1,l0=1.,l1=1.,l2=1., integrationOrder=-1, \\ 313 periodic0=\False,periodic1=\False,periodic2=\False,useElementsOnFace=\False} 314 Generates a \Domain object representing a three dimensional brick between 315 $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with 316 \var{n0} elements along the $x_0$-axis, 317 \var{n1} elements along the $x_1$-axis and 318 \var{n2} elements along the $x_2$-axis. 319 For \var{order}=1 and \var{order}=2 320 \finleyelement{Hex8} and 321 \finleyelement{Hex20} are used, respectively. 322 In the case of \var{useElementsOnFace}=\False, 323 \finleyelement{Rec4} and 324 \finleyelement{Rec8} are used to subdivide the faces of the brick, respectively. 325 In the case of \var{useElementsOnFace}=\True (this option should be used if gradients 326 are calculated on domain faces), 327 \finleyelement{Hex8Face} and 328 \finleyelement{Hex20Face} are used on the brick faces, respectively. 329 If \var{integrationOrder} is positive, a numerical integration scheme 330 chosen which is accurate on each element up to a polynomial of 331 degree \var{integrationOrder} \index{integration order}. Otherwise 332 an appropriate integration order is chosen independently. If 333 \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions} 334 along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley 335 the value on the plane $x_0=0$ will be identical to the values on $x_0=\var{l0}$. Correspondingly, 336 \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions 337 in $x_1$-direction and $x_2$-direction, respectively. 338 \end{funcdesc} 339 340 \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. 342 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. 344 345 TODO: explain \var{safetyFactor} and show an example. 346 \end{funcdesc} 347 348 \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. 350 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} 352 The corresponding face elements are removed from the mesh. 353 354 TODO: explain \var{safetyFactor} and show an example. 355 \end{funcdesc}

## Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision