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

Revision 2881 - (show annotations)
Thu Jan 28 02:03:15 2010 UTC (9 years, 4 months ago) by jfenwick
File MIME type: application/x-tex
File size: 27819 byte(s)
Don't panic.

 1 2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 3 % 4 % Copyright (c) 2003-2010 by University of Queensland 5 % Earth Systems Science Computational Center (ESSCC) 6 7 % 8 % Primary Business: Queensland, Australia 9 % Licensed under the Open Software License version 3.0 10 11 % 12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 13 14 15 \chapter{ The Module \finley} 16 \label{CHAPTER ON FINLEY} 17 18 \begin{figure} 19 \centerline{\includegraphics[width=\figwidth]{figures/FinleyMesh}} 20 \caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})} 21 \label{FINLEY FIG 0} 22 \end{figure} 23 24 \begin{figure} 25 \centerline{\includegraphics[width=\figwidth]{figures/FinleyContact}} 26 \caption{Mesh around a contact region (\finleyelement{Rec4})} 27 \label{FINLEY FIG 01} 28 \end{figure} 29 30 \declaremodule{extension}{finley} \modulesynopsis{Solving linear, steady partial differential equations using 31 finite elements} 32 33 {\it finley} is a library of C functions solving linear, steady partial differential equations 34 \index{partial differential equations} (PDEs) or systems of PDEs using isoparametrical finite 35 elements \index{FEM!isoparametrical}. 36 It supports unstructured, 1D, 2D and 3D meshes. The module \finley provides an access to the 37 library through the \LinearPDE class of \escript supporting its full functionality. {\it finley} 38 is parallelized using the OpenMP \index{OpenMP} paradigm. 39 40 \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 \begin{equation}\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 \end{equation} 56 57 \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 60 \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}. 62 In this case, triangles have been used but other forms of subdivisions 63 can be constructed, e.g. into quadrilaterals or, in the three dimensional case, into tetrahedrons 64 and hexahedrons. The idea of the finite element method is to approximate the solution by a function 65 which is a polynomial of a certain order and is continuous across it boundary to neighbor elements. 66 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 68 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 parameterization of the triangle using a 70 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. 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. 75 Each element is defined by the nodes used to describe its shape. In \fig{FINLEY FIG 0} the element, 76 which has type \finleyelement{Tri3}, 77 with element reference number $19$ \index{element!reference number} is defined by the nodes 78 with reference numbers $9$, $11$ and $0$ \index{node!reference number}. Notice that the order is counterclockwise. 79 The coefficients of the PDE are evaluated at integration nodes with each individual element. 80 For quadrilateral elements a Gauss quadrature scheme is used. In the case of triangular elements a 81 modified form is applied. The boundary of the domain is also subdivided into elements. \index{element!face} In \fig{FINLEY FIG 0} 82 line elements with two nodes are used. The elements are also defined by their describing nodes, e.g. 83 the face element reference number $20$ which has type \finleyelement{Line2} is defined by the nodes 84 with the reference numbers $11$ and $0$. Again the order is crucial, if moving from the first 85 to second node the domain has to lie on the left hand side (in the case of a two dimension surface element 86 the domain has to lie on the left hand side when moving counterclockwise). If the gradient on the 87 surface of the domain is to be calculated rich face elements face to be used. Rich elements on a face 88 are identical to interior elements but with a modified order of nodes such that the 'first' face of the element aligns 89 with the surface of the domain. In \fig{FINLEY FIG 0} 90 elements of the type \finleyelement{Tri3Face} are used. 91 The face element reference number $20$ as a rich face element is defined by the nodes 92 with reference numbers $11$, $0$ and $9$. Notice that the face element $20$ is identical to the 93 interior element $19$ except that, in this case, the order of the node is different to align the first 94 edge of the triangle (which is the edge starting with the first node) with the boundary of the domain. 95 96 Be aware that face elements and elements in the interior of the domain must match, i.e. a face element must be the face 97 of an interior element or, in case of a rich face element, it must be identical to an interior element. 98 If no face elements are specified 99 \finley implicitly assumes homogeneous natural boundary conditions \index{natural boundary conditions!homogeneous}, 100 i.e. \var{d}=$0$ and \var{y}=$0$, on the entire boundary of the domain. For 101 inhomogeneous natural boundary conditions \index{natural boundary conditions!inhomogeneous}, 102 the boundary must be described by face elements. 103 104 If discontinuities of the PDE solution are considered contact elements 105 \index{element!contact}\index{contact conditions} are introduced to describe the contact region $\Gamma^{contact}$ 106 even if $d^{contact}$ and $y^{contact}$ are zero. \fig{FINLEY FIG 01} shows a simple example of a mesh 107 of rectangular elements around a contact region $\Gamma^{contact}$ \index{element!contact}. 108 The contact region is described by the 109 elements $4$, $3$ and $6$. Their element type is \finleyelement{Line2_Contact}. 110 The nodes $9$, $12$, $6$, $5$ define contact element $4$, where the coordinates of nodes $12$ and $5$ and 111 nodes $4$ and $6$ are identical with the idea that nodes $12$ and $9$ are located above and 112 nodes $5$ and $6$ below the contact region. 113 Again, the order of the nodes within an element is crucial. There is also the option of using rich elements 114 if the gradient is to be calculated on the contact region. Similarly to the rich face elements 115 these are constructed from two interior elements by reordering the nodes such that 116 the 'first' face of the element above and the 'first' face of the element below the 117 contact regions line up. The rich version of element 118 $4$ is of type \finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$, $18$, $6$, $5$, $0$ and 119 $2$. 120 121 122 123 \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 125 the nodes within an element. 126 127 \begin{table} 128 \begin{tablev}{l|llll}{textrm}{interior}{face}{rich face}{contact}{rich contact} 129 \linev{\finleyelement{Line2}}{\finleyelement{Point1}}{\finleyelement{Line2Face}}{\finleyelement{Point1_Contact}}{\finleyelement{Line2Face_Contact}} 130 \linev{\finleyelement{Line3}}{\finleyelement{Point1}}{\finleyelement{Line3Face}}{\finleyelement{Point1_Contact}}{\finleyelement{Line3Face_Contact}} 131 \linev{\finleyelement{Tri3}}{\finleyelement{Line2}}{\finleyelement{Tri3Face}}{\finleyelement{Line2_Contact}}{\finleyelement{Tri3Face_Contact}} 132 \linev{\finleyelement{Tri6}}{\finleyelement{Line3}}{\finleyelement{Tri6Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Tri6Face_Contact}} 133 \linev{\finleyelement{Rec4}}{\finleyelement{Line2}}{\finleyelement{Rec4Face}}{\finleyelement{Line2_Contact}}{\finleyelement{Rec4Face_Contact}} 134 \linev{\finleyelement{Rec8}}{\finleyelement{Line3}}{\finleyelement{Rec8Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Rec8Face_Contact}} 135 \linev{\finleyelement{Rec9}}{\finleyelement{Line3}}{\finleyelement{Rec9Face}}{\finleyelement{Line3_Contact}}{\finleyelement{Rec9Face_Contact}} 136 \linev{\finleyelement{Tet4}}{\finleyelement{Tri6}}{\finleyelement{Tet4Face}}{\finleyelement{Tri6_Contact}}{\finleyelement{Tet4Face_Contact}} 137 \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}} 139 \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} 146 \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.} 148 \label{FINLEY TAB 1} 149 \end{table} 150 151 The native \finley file format is defined as follows. 152 Each node \var{i} has \var{dim} spatial coordinates \var{Node[i]}, a reference number 153 \var{Node_ref[i]}, a degree of freedom \var{Node_DOF[i]} and tag \var{Node_tag[i]}. 154 In most cases \var{Node_DOF[i]}=\var{Node_ref[i]} however, for periodic boundary conditions, 155 \var{Node_DOF[i]} is chosen differently, see example below. The tag can be used to mark nodes sharing 156 the same properties. Element \var{i} is defined by the \var{Element_numNodes} nodes \var{Element_Nodes[i]} 157 which is a list of node reference numbers. The order is crucial. 158 It has a reference number \var{Element_ref[i]} and a tag \var{Element_tag[i]}. The tag 159 can be used to mark elements sharing the same properties. For instance elements above 160 a contact region are marked with $2$ and elements below a contact region are marked with $1$. 161 \var{Element_Type} and \var{Element_Num} give the element type and the number of elements in the mesh. 162 Analogue notations are used for face and contact elements. The following Python script 163 prints the mesh definition in the \finley file format: 164 \begin{python} 165 print "%s\n"%mesh_name 166 # node coordinates: 167 print "%dD-nodes %d\n"%(dim,numNodes) 168 for i in range(numNodes): 169 print "%d %d %d"%(Node_ref[i],Node_DOF[i],Node_tag[i]) 170 for j in range(dim): print " %e"%Node[i][j] 171 print "\n" 172 # interior elements 173 print "%s %d\n"%(Element_Type,Element_Num) 174 for i in range(Element_Num): 175 print "%d %d"%(Element_ref[i],Element_tag[i]) 176 for j in range(Element_numNodes): print " %d"%Element_Nodes[i][j] 177 print "\n" 178 # face elements 179 print "%s %d\n"%(FaceElement_Type,FaceElement_Num) 180 for i in range(FaceElement_Num): 181 print "%d %d"%(FaceElement_ref[i],FaceElement_tag[i]) 182 for j in range(FaceElement_numNodes): print " %d"%FaceElement_Nodes[i][j] 183 print "\n" 184 # contact elements 185 print "%s %d\n"%(ContactElement_Type,ContactElement_Num) 186 for i in range(ContactElement_Num): 187 print "%d %d"%(ContactElement_ref[i],ContactElement_tag[i]) 188 for j in range(ContactElement_numNodes): print " %d"%ContactElement_Nodes[i][j] 189 print "\n" 190 # point sources (not supported yet) 191 write("Point1 0",face_element_type,numFaceElements) 192 \end{python} 193 194 The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}: 195 \begin{verbatim} 196 Example 1 197 2D Nodes 16 198 0 0 0 0. 0. 199 2 2 0 0.33 0. 200 3 3 0 0.66 0. 201 7 4 0 1. 0. 202 5 5 0 0. 0.5 203 6 6 0 0.33 0.5 204 8 8 0 0.66 0.5 205 10 10 0 1.0 0.5 206 12 12 0 0. 0.5 207 9 9 0 0.33 0.5 208 13 13 0 0.66 0.5 209 15 15 0 1.0 0.5 210 16 16 0 0. 1.0 211 18 18 0 0.33 1.0 212 19 19 0 0.66 1.0 213 20 20 0 1.0 1.0 214 Rec4 6 215 0 1 0 2 6 5 216 1 1 2 3 8 6 217 2 1 3 7 10 8 218 5 2 12 9 18 16 219 7 2 13 19 18 9 220 10 2 20 19 13 15 221 Line2 0 222 Line2_Contact 3 223 4 0 9 12 6 5 224 3 0 13 9 8 6 225 6 0 15 13 10 8 226 Point1 0 227 \end{verbatim} 228 Notice that the order in which the nodes and elements are given is arbitrary. 229 In the case that rich contact elements are used the contact element section gets 230 the form 231 \begin{verbatim} 232 Rec4Face_Contact 3 233 4 0 9 12 16 18 6 5 0 2 234 3 0 13 9 18 19 8 6 2 3 235 6 0 15 13 19 20 10 8 3 7 236 \end{verbatim} 237 Periodic boundary condition \index{boundary conditions!periodic} can be introduced by altering \var{Node_DOF}. 238 It allows identification of nodes even if they have different physical locations. For instance, to 239 enforce periodic boundary conditions at the face $x_0=0$ and $x_0=1$ one identifies 240 the degrees of freedom for nodes $0$, $5$, $12$ and $16$ with the degrees of freedom for 241 $7$, $10$, $15$ and $20$, respectively. The node section of the \finley mesh gets now the form: 242 \begin{verbatim} 243 2D Nodes 16 244 0 0 0 0. 0. 245 2 2 0 0.33 0. 246 3 3 0 0.66 0. 247 7 0 0 1. 0. 248 5 5 0 0. 0.5 249 6 6 0 0.33 0.5 250 8 8 0 0.66 0.5 251 10 5 0 1.0 0.5 252 12 12 0 0. 0.5 253 9 9 0 0.33 0.5 254 13 13 0 0.66 0.5 255 15 12 0 1.0 0.5 256 16 16 0 0. 1.0 257 18 18 0 0.33 1.0 258 19 19 0 0.66 1.0 259 20 16 0 1.0 1.0 260 \end{verbatim} 261 262 \clearpage 263 \input{finleyelements} 264 \clearpage 265 266 \begin{figure}[th] 267 \begin{center} 268 \subfigure[Triangle]{\label{FINLEY MACRO TRI}\includegraphics[scale=0.25]{figures/FinleyMacroTri}} 269 \subfigure[Quadrilateral]{\label{FINLEY MACRO REC}\includegraphics[scale=0.25]{figures/FinleyMacroRec}} 270 \includegraphics[scale=0.2]{figures/FinleyMacroLeg} 271 \end{center} 272 Macro elements in \finley. 273 \end{figure} 274 275 \section{Macro Elements} 276 \label{SEC FINLEY MACRO} 277 \finley supports the usage of macro elements~\index{macro elements} which can be used to 278 achieve LBB compliance when solving incompressible fluid flow problems. LBB compliance is required to 279 get a problem which has a unique solution for pressure and velocity. For macro elements the 280 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 \section{Linear Solvers in \SolverOptions} 478 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 490 file \var{fileName}. The file must be given the \finley file format. 491 If \var{integrationOrder} is positive, a numerical integration scheme 492 chosen which is accurate on each element up to a polynomial of 493 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. 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} 511 512 \begin{funcdesc}{MakeDomain}{design\optional{, integrationOrder=-1\optional{, optimizeLabeling=True\optional{, useMacroElements=False}}}} 513 Creates a Finley \Domain from a \class{Design} object from \pycad using \gmshextern. 514 The \class{Design} \var{design} defines the geometry. 515 If \var{integrationOrder} is positive, a numerical integration scheme 516 chosen which is accurate on each element up to a polynomial of 517 degree \var{integrationOrder} \index{integration order}. Otherwise 518 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} 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, \\ 533 periodic0=\False, periodic1=\False, useElementsOnFace=\False, useMacroElements=\False, optimize=\False} 534 Generates a \Domain object representing a two dimensional rectangle between 535 $(0,0)$ and $(l0,l1)$ with orthogonal edges. The rectangle is filled with 536 \var{n0} elements along the $x_0$-axis and 537 \var{n1} elements along the $x_1$-axis. 538 For \var{order}=1 and \var{order}=2 539 \finleyelement{Rec4} and 540 \finleyelement{Rec8} are used, respectively. 541 In the case of \var{useElementsOnFace}=\False, 542 \finleyelement{Line2} and 543 \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 546 are calculated on domain faces), 547 \finleyelement{Rec4Face} and 548 \finleyelement{Rec8Face} are used on the edges, respectively. 549 If \var{integrationOrder} is positive, a numerical integration scheme 550 chosen which is accurate on each element up to a polynomial of 551 degree \var{integrationOrder} \index{integration order}. Otherwise 552 an appropriate integration order is chosen independently. If 553 \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions} 554 along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley 555 the value on the line $x_0=0$ will be identical to the values on $x_0=\var{l0}$. 556 Correspondingly, 557 \var{periodic1}=\False sets periodic boundary conditions 558 in $x_1$-direction. 559 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. 560 \end{funcdesc} 561 562 \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, useMacroElements=\False, optimize=\False} 564 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 566 \var{n0} elements along the $x_0$-axis, 567 \var{n1} elements along the $x_1$-axis and 568 \var{n2} elements along the $x_2$-axis. 569 For \var{order}=1 and \var{order}=2 570 \finleyelement{Hex8} and 571 \finleyelement{Hex20} are used, respectively. 572 In the case of \var{useElementsOnFace}=\False, 573 \finleyelement{Rec4} and 574 \finleyelement{Rec8} are used to subdivide the faces of the brick, respectively. 575 In the case of \var{useElementsOnFace}=\True (this option should be used if gradients 576 are calculated on domain faces), 577 \finleyelement{Hex8Face} and 578 \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 581 chosen which is accurate on each element up to a polynomial of 582 degree \var{integrationOrder} \index{integration order}. Otherwise 583 an appropriate integration order is chosen independently. If 584 \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions} 585 along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley 586 the value on the plane $x_0=0$ will be identical to the values on $x_0=\var{l0}$. Correspondingly, 587 \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions 588 in $x_1$-direction and $x_2$-direction, respectively. 589 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. 590 \end{funcdesc} 591 592 \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13} 593 Generates a new \Domain object from the list \var{meshList} of \finley meshes. 594 Nodes in face elements whose difference of coordinates is less then \var{tolerance} times the 595 diameter of the domain are merged. The corresponding face elements are removed from the mesh. 596 597 TODO: explain \var{safetyFactor} and show an example. 598 \end{funcdesc} 599 600 \begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13} 601 Generates a new \Domain object from the list \var{meshList} of \finley meshes. 602 Face elements whose nodes coordinates have difference is less then \var{tolerance} times the 603 diameter of the domain are combined to form a contact element \index{element!contact} 604 The corresponding face elements are removed from the mesh. 605 606 TODO: explain \var{safetyFactor} and show an example. 607 \end{funcdesc}