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

Revision 6932 - (show annotations)
Thu Dec 12 02:48:08 2019 UTC (2 months, 1 week ago) by acodd
File MIME type: application/x-tex
File size: 28069 byte(s)
LBFGS comments


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

## Properties

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