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

Revision 3306 - (show annotations)
Mon Oct 25 05:09:13 2010 UTC (8 years, 6 months ago) by caltinay
File MIME type: application/x-tex
File size: 27497 byte(s)
Commented declaremodule and modulesynopsis.


 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 \finley Module}\label{CHAPTER ON FINLEY} 16 17 \begin{figure} 18 \centerline{\includegraphics[width=\figwidth]{FinleyMesh}} 19 \caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})} 20 \label{FINLEY FIG 0} 21 \end{figure} 22 23 \begin{figure} 24 \centerline{\includegraphics[width=\figwidth]{FinleyContact}} 25 \caption{Mesh around a contact region (\finleyelement{Rec4})} 26 \label{FINLEY FIG 01} 27 \end{figure} 28 29 %\declaremodule{extension}{finley} 30 %\modulesynopsis{Solving linear, steady partial differential equations using finite elements} 31 32 {\it finley} is a library of C functions solving linear, steady partial differential equations 33 \index{partial differential equations} (PDEs) or systems of PDEs using isoparametrical finite 34 elements \index{FEM!isoparametrical}. 35 It supports unstructured, 1D, 2D and 3D meshes. The module \finley provides an access to the 36 library through the \LinearPDE class of \escript supporting its full functionality. {\it finley} 37 is parallelized using the OpenMP \index{OpenMP} paradigm. 38 39 \section{Formulation} 40 41 For a single PDE with a solution with a single component the linear PDE is defined in the 42 following form: 43 \begin{equation}\label{FINLEY.SINGLE.1} 44 \begin{array}{cl} & 45 \displaystyle{ 46 \int_{\Omega} 47 A_{jl} \cdot v_{,j}u_{,l}+ B_{j} \cdot v_{,j} u+ C_{l} \cdot v u_{,l}+D \cdot vu \; d\Omega } \\ 48 + & \displaystyle{\int_{\Gamma} d \cdot vu \; d{\Gamma} } 49 + \displaystyle{\int_{\Gamma^{contact}} d^{contact} \cdot [v][u] \; d{\Gamma} } \\ 50 = & \displaystyle{\int_{\Omega} X_{j} \cdot v_{,j}+ Y \cdot v \; d\Omega }\\ 51 + & \displaystyle{\int_{\Gamma} y \cdot v \; d{\Gamma}} + 52 \displaystyle{\int_{\Gamma^{contact}} y^{contact}\cdot [v] \; d{\Gamma}} \\ 53 \end{array} 54 \end{equation} 55 56 \section{Meshes} 57 \label{FINLEY MESHES} 58 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 60 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 62 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 64 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 66 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. 68 In this case the triangle gets a curved edge which requires a parameterization of the triangle using a 69 quadratic polynomial. For this case, the solution is also approximated by a piecewise quadratic polynomial 70 (which explains the name isoparametrical elements), see \Ref{Zienc,NumHand} for more details. 71 \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. 72 73 The union of all elements defines the domain of the PDE. 74 Each element is defined by the nodes used to describe its shape. In \fig{FINLEY FIG 0} the element, 75 which has type \finleyelement{Tri3}, 76 with element reference number $19$ \index{element!reference number} is defined by the nodes 77 with reference numbers $9$, $11$ and $0$ \index{node!reference number}. Notice that the order is counterclockwise. 78 The coefficients of the PDE are evaluated at integration nodes with each individual element. 79 For quadrilateral elements a Gauss quadrature scheme is used. In the case of triangular elements a 80 modified form is applied. The boundary of the domain is also subdivided into elements. \index{element!face} In \fig{FINLEY FIG 0} 81 line elements with two nodes are used. The elements are also defined by their describing nodes, e.g. 82 the face element reference number $20$ which has type \finleyelement{Line2} is defined by the nodes 83 with the reference numbers $11$ and $0$. Again the order is crucial, if moving from the first 84 to second node the domain has to lie on the left hand side (in the case of a two dimension surface element 85 the domain has to lie on the left hand side when moving counterclockwise). If the gradient on the 86 surface of the domain is to be calculated rich face elements face to be used. Rich elements on a face 87 are identical to interior elements but with a modified order of nodes such that the 'first' face of the element aligns 88 with the surface of the domain. In \fig{FINLEY FIG 0} 89 elements of the type \finleyelement{Tri3Face} are used. 90 The face element reference number $20$ as a rich face element is defined by the nodes 91 with reference numbers $11$, $0$ and $9$. Notice that the face element $20$ is identical to the 92 interior element $19$ except that, in this case, the order of the node is different to align the first 93 edge of the triangle (which is the edge starting with the first node) with the boundary of the domain. 94 95 Be aware that face elements and elements in the interior of the domain must match, i.e. a face element must be the face 96 of an interior element or, in case of a rich face element, it must be identical to an interior element. 97 If no face elements are specified 98 \finley implicitly assumes homogeneous natural boundary conditions \index{natural boundary conditions!homogeneous}, 99 i.e. \var{d}=$0$ and \var{y}=$0$, on the entire boundary of the domain. For 100 inhomogeneous natural boundary conditions \index{natural boundary conditions!inhomogeneous}, 101 the boundary must be described by face elements. 102 103 If discontinuities of the PDE solution are considered contact elements 104 \index{element!contact}\index{contact conditions} are introduced to describe the contact region $\Gamma^{contact}$ 105 even if $d^{contact}$ and $y^{contact}$ are zero. \fig{FINLEY FIG 01} shows a simple example of a mesh 106 of rectangular elements around a contact region $\Gamma^{contact}$ \index{element!contact}. 107 The contact region is described by the 108 elements $4$, $3$ and $6$. Their element type is \finleyelement{Line2_Contact}. 109 The nodes $9$, $12$, $6$, $5$ define contact element $4$, where the coordinates of nodes $12$ and $5$ and 110 nodes $4$ and $6$ are identical with the idea that nodes $12$ and $9$ are located above and 111 nodes $5$ and $6$ below the contact region. 112 Again, the order of the nodes within an element is crucial. There is also the option of using rich elements 113 if the gradient is to be calculated on the contact region. Similarly to the rich face elements 114 these are constructed from two interior elements by reordering the nodes such that 115 the 'first' face of the element above and the 'first' face of the element below the 116 contact regions line up. The rich version of element 117 $4$ is of type \finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$, $18$, $6$, $5$, $0$ and 118 $2$. 119 120 121 122 \tab{FINLEY TAB 1} shows the interior element types and the corresponding element types to be used 123 on the face and contacts. \fig{FINLEY.FIG:1}, \fig{FINLEY.FIG:2} and \fig{FINLEY.FIG:4} show the ordering of 124 the nodes within an element. 125 126 \begin{table} 127 \centering 128 \begin{tabular}{l|llll} 129 \bfseries interior & face & rich face & contact & rich contact\\ 130 \hline 131 \finleyelement{Line2} & \finleyelement{Point1} & \finleyelement{Line2Face} & \finleyelement{Point1_Contact} & \finleyelement{Line2Face_Contact}\\ 132 \finleyelement{Line3} & \finleyelement{Point1} & \finleyelement{Line3Face} & \finleyelement{Point1_Contact} & \finleyelement{Line3Face_Contact}\\ 133 \finleyelement{Tri3} & \finleyelement{Line2} & \finleyelement{Tri3Face} & \finleyelement{Line2_Contact} & \finleyelement{Tri3Face_Contact}\\ 134 \finleyelement{Tri6} & \finleyelement{Line3} & \finleyelement{Tri6Face} & \finleyelement{Line3_Contact} & \finleyelement{Tri6Face_Contact}\\ 135 \finleyelement{Rec4} & \finleyelement{Line2} & \finleyelement{Rec4Face} & \finleyelement{Line2_Contact} & \finleyelement{Rec4Face_Contact}\\ 136 \finleyelement{Rec8} & \finleyelement{Line3} & \finleyelement{Rec8Face} & \finleyelement{Line3_Contact} & \finleyelement{Rec8Face_Contact}\\ 137 \finleyelement{Rec9} & \finleyelement{Line3} & \finleyelement{Rec9Face} & \finleyelement{Line3_Contact} & \finleyelement{Rec9Face_Contact}\\ 138 \finleyelement{Tet4} & \finleyelement{Tri6} & \finleyelement{Tet4Face} & \finleyelement{Tri6_Contact} & \finleyelement{Tet4Face_Contact}\\ 139 \finleyelement{Tet10} & \finleyelement{Tri9} & \finleyelement{Tet10Face} & \finleyelement{Tri9_Contact} & \finleyelement{Tet10Face_Contact}\\ 140 \finleyelement{Hex8} & \finleyelement{Rec4} & \finleyelement{Hex8Face} & \finleyelement{Rec4_Contact} & \finleyelement{Hex8Face_Contact}\\ 141 \finleyelement{Hex20} & \finleyelement{Rec8} & \finleyelement{Hex20Face} & \finleyelement{Rec8_Contact} & \finleyelement{Hex20Face_Contact}\\ 142 \finleyelement{Hex27} & \finleyelement{Rec9} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\ 143 \finleyelement{Hex27Macro} & \finleyelement{Rec9Macro} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\ 144 \finleyelement{Tet10Macro} & \finleyelement{Tri6Macro} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\ 145 \finleyelement{Rec9Macro} & \finleyelement{Line3Macro} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\ 146 \finleyelement{Tri6Macro} & \finleyelement{Line3Macro} & N\textbackslash A & N\textbackslash A & N\textbackslash A\\ 147 \end{tabular} 148 \caption{Finley elements and corresponding elements to be used on domain faces and contacts. 149 The rich types have to be used if the gradient of function is to be calculated on faces and contacts, respectively.} 150 \label{FINLEY TAB 1} 151 \end{table} 152 153 The native \finley file format is defined as follows. 154 Each node \var{i} has \var{dim} spatial coordinates \var{Node[i]}, a reference number 155 \var{Node_ref[i]}, a degree of freedom \var{Node_DOF[i]} and tag \var{Node_tag[i]}. 156 In most cases \var{Node_DOF[i]}=\var{Node_ref[i]} however, for periodic boundary conditions, 157 \var{Node_DOF[i]} is chosen differently, see example below. The tag can be used to mark nodes sharing 158 the same properties. Element \var{i} is defined by the \var{Element_numNodes} nodes \var{Element_Nodes[i]} 159 which is a list of node reference numbers. The order is crucial. 160 It has a reference number \var{Element_ref[i]} and a tag \var{Element_tag[i]}. The tag 161 can be used to mark elements sharing the same properties. For instance elements above 162 a contact region are marked with $2$ and elements below a contact region are marked with $1$. 163 \var{Element_Type} and \var{Element_Num} give the element type and the number of elements in the mesh. 164 Analogue notations are used for face and contact elements. The following Python script 165 prints the mesh definition in the \finley file format: 166 \begin{python} 167 print "%s\n"%mesh_name 168 # node coordinates: 169 print "%dD-nodes %d\n"%(dim,numNodes) 170 for i in range(numNodes): 171 print "%d %d %d"%(Node_ref[i],Node_DOF[i],Node_tag[i]) 172 for j in range(dim): print " %e"%Node[i][j] 173 print "\n" 174 # interior elements 175 print "%s %d\n"%(Element_Type,Element_Num) 176 for i in range(Element_Num): 177 print "%d %d"%(Element_ref[i],Element_tag[i]) 178 for j in range(Element_numNodes): print " %d"%Element_Nodes[i][j] 179 print "\n" 180 # face elements 181 print "%s %d\n"%(FaceElement_Type,FaceElement_Num) 182 for i in range(FaceElement_Num): 183 print "%d %d"%(FaceElement_ref[i],FaceElement_tag[i]) 184 for j in range(FaceElement_numNodes): print " %d"%FaceElement_Nodes[i][j] 185 print "\n" 186 # contact elements 187 print "%s %d\n"%(ContactElement_Type,ContactElement_Num) 188 for i in range(ContactElement_Num): 189 print "%d %d"%(ContactElement_ref[i],ContactElement_tag[i]) 190 for j in range(ContactElement_numNodes): print " %d"%ContactElement_Nodes[i][j] 191 print "\n" 192 # point sources (not supported yet) 193 write("Point1 0",face_element_type,numFaceElements) 194 \end{python} 195 196 The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}: 197 \begin{verbatim} 198 Example 1 199 2D Nodes 16 200 0 0 0 0. 0. 201 2 2 0 0.33 0. 202 3 3 0 0.66 0. 203 7 4 0 1. 0. 204 5 5 0 0. 0.5 205 6 6 0 0.33 0.5 206 8 8 0 0.66 0.5 207 10 10 0 1.0 0.5 208 12 12 0 0. 0.5 209 9 9 0 0.33 0.5 210 13 13 0 0.66 0.5 211 15 15 0 1.0 0.5 212 16 16 0 0. 1.0 213 18 18 0 0.33 1.0 214 19 19 0 0.66 1.0 215 20 20 0 1.0 1.0 216 Rec4 6 217 0 1 0 2 6 5 218 1 1 2 3 8 6 219 2 1 3 7 10 8 220 5 2 12 9 18 16 221 7 2 13 19 18 9 222 10 2 20 19 13 15 223 Line2 0 224 Line2_Contact 3 225 4 0 9 12 6 5 226 3 0 13 9 8 6 227 6 0 15 13 10 8 228 Point1 0 229 \end{verbatim} 230 Notice that the order in which the nodes and elements are given is arbitrary. 231 In the case that rich contact elements are used the contact element section gets 232 the form 233 \begin{verbatim} 234 Rec4Face_Contact 3 235 4 0 9 12 16 18 6 5 0 2 236 3 0 13 9 18 19 8 6 2 3 237 6 0 15 13 19 20 10 8 3 7 238 \end{verbatim} 239 Periodic boundary condition \index{boundary conditions!periodic} can be introduced by altering \var{Node_DOF}. 240 It allows identification of nodes even if they have different physical locations. For instance, to 241 enforce periodic boundary conditions at the face $x_0=0$ and $x_0=1$ one identifies 242 the degrees of freedom for nodes $0$, $5$, $12$ and $16$ with the degrees of freedom for 243 $7$, $10$, $15$ and $20$, respectively. The node section of the \finley mesh gets now the form: 244 \begin{verbatim} 245 2D Nodes 16 246 0 0 0 0. 0. 247 2 2 0 0.33 0. 248 3 3 0 0.66 0. 249 7 0 0 1. 0. 250 5 5 0 0. 0.5 251 6 6 0 0.33 0.5 252 8 8 0 0.66 0.5 253 10 5 0 1.0 0.5 254 12 12 0 0. 0.5 255 9 9 0 0.33 0.5 256 13 13 0 0.66 0.5 257 15 12 0 1.0 0.5 258 16 16 0 0. 1.0 259 18 18 0 0.33 1.0 260 19 19 0 0.66 1.0 261 20 16 0 1.0 1.0 262 \end{verbatim} 263 264 \clearpage 265 \input{finleyelements} 266 \clearpage 267 268 \begin{figure}[th] 269 \begin{center} 270 \subfigure[Triangle]{\label{FINLEY MACRO TRI}\includegraphics[scale=0.25]{FinleyMacroTri}} 271 \subfigure[Quadrilateral]{\label{FINLEY MACRO REC}\includegraphics[scale=0.25]{FinleyMacroRec}} 272 \includegraphics[scale=0.2]{FinleyMacroLeg} 273 \end{center} 274 Macro elements in \finley. 275 \end{figure} 276 277 \section{Macro Elements} 278 \label{SEC FINLEY MACRO} 279 \finley supports the usage of macro elements~\index{macro elements} which can be used to 280 achieve LBB compliance when solving incompressible fluid flow problems. LBB compliance is required to 281 get a problem which has a unique solution for pressure and velocity. For macro elements the 282 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 283 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 284 one uses a linear approximation of the velocity together with a linear approximation of the pressure but on elements 285 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 286 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. 287 Typically macro elements are only required to use when an incompressible fluid flow problem 288 is solved, e.g the Stokes problem in Section \ref{STOKES PROBLEM}. Please see Section~\ref{FINLEY MESHES} for 289 more details on the supported macro elements. 290 291 292 293 \begin{table} 294 {\scriptsize 295 \begin{tabular}{l||c|c|c|c|c|c|c|c} 296 \member{setSolverMethod} & \member{DIRECT}& \member{PCG} & \member{GMRES} & \member{TFQMR} & \member{MINRES} & \member{PRES20} & \member{BICGSTAB} & \member{LUMPING} \\ 297 \hline 298 \hline 299 \member{setReordering} & $\checkmark$ & & & & & &\\ 300 \hline \member{setRestart} & & & $\checkmark$ & & & $20$ & \\ 301 \hline\member{setTruncation} & & & $\checkmark$ & & & $5$ & \\ 302 \hline\member{setIterMax} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\ 303 \hline\member{setTolerance} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\ 304 \hline\member{setAbsoluteTolerance} & & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\ 305 \hline\member{setReordering} & $\checkmark$ & & & & & & & \\ 306 \end{tabular} 307 } 308 \caption{Solvers available for 309 \finley 310 and the \PASO package and the relevant options in \class{SolverOptions}. 311 \MKL supports 312 \MINIMUMFILLIN 313 and 314 \NESTEDDESCTION 315 reordering. 316 Currently the \UMFPACK interface does not support any reordering. 317 \label{TAB FINLEY SOLVER OPTIONS 1} } 318 \end{table} 319 320 \begin{table} 321 {\scriptsize 322 \begin{tabular}{l||c|c|c|c|c|c|c|c} 323 \member{setPreconditioner} & 324 \member{NO_PRECONDITIONER} & 325 \member{AMG} & 326 \member{JACOBI} & 327 \member{GAUSS_SEIDEL}& 328 \member{REC_ILU}& 329 \member{RILU} & 330 \member{ILU0} & 331 \member{DIRECT} \\ 332 \hline 333 status: & 334 later & 335 later & 336 $\checkmark$ & 337 $\checkmark$& 338 $\checkmark$ & 339 later & 340 $\checkmark$ & 341 later \\ 342 \hline 343 \hline 344 \member{setCoarsening}& 345 & 346 $\checkmark$ & 347 & 348 & 349 & 350 & 351 & 352 \\ 353 354 355 \hline\member{setLevelMax}& 356 & 357 $\checkmark$ & 358 & 359 & 360 & 361 & 362 & 363 \\ 364 365 \hline\member{setCoarseningThreshold}& 366 & 367 $\checkmark$ & 368 & 369 & 370 & 371 & 372 & 373 \\ 374 375 \hline\member{setMinCoarseMatrixSize} & 376 & 377 $\checkmark$ & 378 & 379 & 380 & 381 & 382 & 383 \\ 384 385 \hline\member{setNumSweeps} & 386 & 387 & 388 $\checkmark$ & 389 $\checkmark$ & 390 & 391 & 392 & 393 \\ 394 395 \hline\member{setNumPreSweeps}& 396 & 397 $\checkmark$ & 398 & 399 & 400 & 401 & 402 & 403 \\ 404 405 \hline\member{setNumPostSweeps} & 406 & 407 $\checkmark$ & 408 & 409 & 410 & 411 & 412 & 413 \\ 414 415 \hline\member{setInnerTolerance}& 416 & 417 & 418 & 419 & 420 & 421 & 422 & 423 \\ 424 425 \hline\member{setDropTolerance}& 426 & 427 & 428 & 429 & 430 & 431 & 432 & 433 \\ 434 435 \hline\member{setDropStorage}& 436 & 437 & 438 & 439 & 440 & 441 & 442 & 443 \\ 444 445 \hline\member{setRelaxationFactor}& 446 & 447 & 448 & 449 & 450 & 451 $\checkmark$ & 452 & 453 \\ 454 455 \hline\member{adaptInnerTolerance}& 456 & 457 & 458 & 459 & 460 & 461 & 462 & 463 \\ 464 465 \hline\member{setInnerIterMax}& 466 & 467 & 468 & 469 & 470 & 471 & 472 & 473 \\ 474 \end{tabular} 475 } 476 \caption{Preconditioners available for \finley and the \PASO package and the relevant options in \class{SolverOptions}. \label{TAB FINLEY SOLVER OPTIONS 2}} 477 \end{table} 478 479 \section{Linear Solvers in \SolverOptions} 480 Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and 481 Table~\ref{TAB FINLEY SOLVER OPTIONS 2} show the solvers and preconditioners supported by 482 \finley through the \PASO library. Currently direct solvers are not supported under MPI. 483 By default, \finley is using the iterative solvers \PCG for symmetric and \BiCGStab for non-symmetric problems. 484 If the direct solver is selected which can be useful when solving very ill-posed equations 485 \finley uses the \MKL \footnote{If the stiffness matrix is non-regular \MKL may return without 486 returning a proper error code. If you observe suspicious solutions when using MKL, this may be caused by a non-invertible operator. } solver package. If \MKL is not available \UMFPACK is used. If \UMFPACK is not available 487 a suitable iterative solver from the \PASO is used. 488 489 \section{Functions} 490 \begin{funcdesc}{ReadMesh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True}} 491 creates a \Domain object form the FEM mesh defined in 492 file \var{fileName}. The file must be given the \finley file format. 493 If \var{integrationOrder} is positive, a numerical integration scheme 494 chosen which is accurate on each element up to a polynomial of 495 degree \var{integrationOrder} \index{integration order}. Otherwise 496 an appropriate integration order is chosen independently. 497 By default the labeling of mesh nodes and element distribution is 498 optimized. Set \var{optimize=False} to switch off relabeling and redistribution. 499 \end{funcdesc} 500 501 \begin{funcdesc}{ReadGmsh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True\optional{, useMacroElements=False}}} 502 creates a \Domain object form the FEM mesh defined in 503 file \var{fileName}. The file must be given the \gmshextern file format. 504 If \var{integrationOrder} is positive, a numerical integration scheme 505 chosen which is accurate on each element up to a polynomial of 506 degree \var{integrationOrder} \index{integration order}. Otherwise 507 an appropriate integration order is chosen independently. 508 By default the labeling of mesh nodes and element distribution is 509 optimized. Set \var{optimize=False} to switch off relabeling and redistribution. 510 If \var{useMacroElements} is set, second order elements are interpreted as macro elements~\index{macro elements}. 511 Currently \function{ReadGmsh} does not support MPI. 512 \end{funcdesc} 513 514 \begin{funcdesc}{MakeDomain}{design\optional{, integrationOrder=-1\optional{, optimizeLabeling=True\optional{, useMacroElements=False}}}} 515 Creates a Finley \Domain from a \class{Design} object from \pycad using \gmshextern. 516 The \class{Design} \var{design} defines the geometry. 517 If \var{integrationOrder} is positive, a numerical integration scheme 518 chosen which is accurate on each element up to a polynomial of 519 degree \var{integrationOrder} \index{integration order}. Otherwise 520 an appropriate integration order is chosen independently. 521 Set \var{optimizeLabeling=False} to switch off relabeling and redistribution (not recommended). 522 If \var{useMacroElements} is set, macro elements~\index{macro elements} are used. 523 Currently \function{MakeDomain} does not support MPI. 524 \end{funcdesc} 525 526 527 \begin{funcdesc}{load}{fileName} 528 recovers a \Domain object from a dump file created by the \ 529 \function{dump} method of a \Domain object defined in 530 file \var{fileName}. 531 \end{funcdesc} 532 533 534 \begin{funcdesc}{Rectangle}{n0,n1,order=1,l0=1.,l1=1., integrationOrder=-1, \\ 535 periodic0=\False, periodic1=\False, useElementsOnFace=\False, useMacroElements=\False,\\ optimize=\False} 536 Generates a \Domain object representing a two dimensional rectangle between 537 $(0,0)$ and $(l0,l1)$ with orthogonal edges. The rectangle is filled with 538 \var{n0} elements along the $x_0$-axis and 539 \var{n1} elements along the $x_1$-axis. 540 For \var{order}=1 and \var{order}=2 541 \finleyelement{Rec4} and 542 \finleyelement{Rec8} are used, respectively. 543 In the case of \var{useElementsOnFace}=\False, 544 \finleyelement{Line2} and 545 \finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively. 546 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}. 547 In the case of \var{useElementsOnFace}=\True (this option should be used if gradients 548 are calculated on domain faces), 549 \finleyelement{Rec4Face} and 550 \finleyelement{Rec8Face} are used on the edges, respectively. 551 If \var{integrationOrder} is positive, a numerical integration scheme 552 chosen which is accurate on each element up to a polynomial of 553 degree \var{integrationOrder} \index{integration order}. Otherwise 554 an appropriate integration order is chosen independently. If 555 \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions} 556 along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley 557 the value on the line $x_0=0$ will be identical to the values on $x_0=\var{l0}$. 558 Correspondingly, 559 \var{periodic1}=\False sets periodic boundary conditions 560 in $x_1$-direction. 561 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. 562 \end{funcdesc} 563 564 \begin{funcdesc}{Brick}{n0,n1,n2,order=1,l0=1.,l1=1.,l2=1., integrationOrder=-1, 565 periodic0=\False, periodic1=\False, \\ periodic2=\False, useElementsOnFace=\False, useMacroElements=\False, optimize=\False} 566 Generates a \Domain object representing a three dimensional brick between 567 $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with 568 \var{n0} elements along the $x_0$-axis, 569 \var{n1} elements along the $x_1$-axis and 570 \var{n2} elements along the $x_2$-axis. 571 For \var{order}=1 and \var{order}=2 572 \finleyelement{Hex8} and 573 \finleyelement{Hex20} are used, respectively. 574 In the case of \var{useElementsOnFace}=\False, 575 \finleyelement{Rec4} and 576 \finleyelement{Rec8} are used to subdivide the faces of the brick, respectively. 577 In the case of \var{useElementsOnFace}=\True (this option should be used if gradients 578 are calculated on domain faces), 579 \finleyelement{Hex8Face} and 580 \finleyelement{Hex20Face} are used on the brick faces, respectively. 581 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}. 582 If \var{integrationOrder} is positive, a numerical integration scheme 583 chosen which is accurate on each element up to a polynomial of 584 degree \var{integrationOrder} \index{integration order}. Otherwise 585 an appropriate integration order is chosen independently. If 586 \var{periodic0}=\True, periodic boundary conditions \index{periodic boundary conditions} 587 along the $x_0$-directions are enforced. That means when for any solution of a PDE solved by \finley 588 the value on the plane $x_0=0$ will be identical to the values on $x_0=\var{l0}$. Correspondingly, 589 \var{periodic1}=\False and \var{periodic2}=\False sets periodic boundary conditions 590 in $x_1$-direction and $x_2$-direction, respectively. 591 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. 592 \end{funcdesc} 593 594 \begin{funcdesc}{GlueFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13} 595 Generates a new \Domain object from the list \var{meshList} of \finley meshes. 596 Nodes in face elements whose difference of coordinates is less then \var{tolerance} times the 597 diameter of the domain are merged. The corresponding face elements are removed from the mesh. 598 599 TODO: explain \var{safetyFactor} and show an example. 600 \end{funcdesc} 601 602 \begin{funcdesc}{JoinFaces}{meshList,safetyFactor=0.2,tolerance=1.e-13} 603 Generates a new \Domain object from the list \var{meshList} of \finley meshes. 604 Face elements whose nodes coordinates have difference is less then \var{tolerance} times the 605 diameter of the domain are combined to form a contact element \index{element!contact} 606 The corresponding face elements are removed from the mesh. 607 608 TODO: explain \var{safetyFactor} and show an example. 609 \end{funcdesc}

## Properties

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