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

Revision 3989 - (show annotations)
Tue Sep 25 02:21:54 2012 UTC (6 years, 10 months ago) by jfenwick
File MIME type: application/x-tex
File size: 33247 byte(s)
More copyright fixes.
pyvisi traces removed.
Some install doco

 1 2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 3 % Copyright (c) 2003-2012 by University of Queensland 4 5 % 6 % Primary Business: Queensland, Australia 7 % Licensed under the Open Software License version 3.0 8 9 % 10 % Development until 2012 by Earth Systems Science Computational Center (ESSCC) 11 % Development since 2012 by School of Earth Sciences 12 % 13 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 14 15 \chapter{The \pycad Module}\label{PYCAD CHAP} 16 17 \section{Introduction} 18 19 \pycad provides a simple way to build a mesh for your finite element 20 simulation. You begin by building what we call a \class{Design} using 21 primitive geometric objects, and then go on to build a mesh from this. 22 The final step of generating the mesh from a \class{Design} uses freely 23 available mesh generation software, such as \gmshextern. 24 25 A \class{Design} is built by defining points, which are used to specify 26 the corners of geometric objects and the vertices of curves. Using 27 points you construct more interesting objects such as lines, 28 rectangles, and arcs. By adding many of these objects into a \class{Design}, 29 you can build meshes for arbitrarily complex 2-D and 3-D structures. 30 31 \section{The Unit Square} 32 The simplest geometry is the unit square. First we generate the corner points 33 \begin{python} 34 from esys.pycad import * 35 p0=Point(0.,0.,0.) 36 p1=Point(1.,0.,0.) 37 p2=Point(1.,1.,0.) 38 p3=Point(0.,1.,0.) 39 \end{python} 40 which are then linked to define the edges of the square 41 \begin{python} 42 l01=Line(p0,p1) 43 l12=Line(p1,p2) 44 l23=Line(p2,p3) 45 l30=Line(p3,p0) 46 \end{python} 47 The lines are put together to form a loop 48 \begin{python} 49 c=CurveLoop(l01,l12,l23,l30) 50 \end{python} 51 The orientation of the line defining the \class{CurveLoop} is important. 52 It is assumed that the surrounded area is to the left when moving along the 53 lines from their starting points towards the end points. 54 Moreover, the line needs to form a closed loop. 55 We now use the \class{CurveLoop} to define a surface 56 \begin{python} 57 s=PlaneSurface(c) 58 \end{python} 59 Note that there is a difference between the \class{CurveLoop}, which defines 60 the boundary of the surface, and the actual surface \class{PlaneSurface}. 61 This difference becomes clearer in the next example with a hole. 62 Now we are ready to define the geometry which is described by an instance of 63 the \class{Design} class: 64 \begin{python} 65 d=Design(dim=2,element_size=0.05) 66 \end{python} 67 Here we use the two-dimensional domain with a local element size in the finite 68 element mesh of $0.05$. 69 We then add the surface \code{s} to the geometry 70 \begin{python} 71 d.addItems(s) 72 \end{python} 73 This will automatically import all items used to construct \code{s} into the 74 \class{Design} \code{d}. 75 Now we are ready to construct a \finley FEM mesh and then write it to the file 76 \file{quad.fly}: 77 \begin{python} 78 from esys.finley import MakeDomain 79 dom=MakeDomain(d) 80 dom.write("quad.fly") 81 \end{python} 82 In some cases it is useful to access the script used to generate the geometry. 83 You can specify a specific name for the script file. In our case we use 84 \begin{python} 85 d.setScriptFileName("quad.geo") 86 \end{python} 87 It is also useful to check error messages generated during the mesh generation 88 process. \gmshextern writes messages to the file \file{.gmsh-errors} in your 89 home directory. 90 Putting everything together we get the script 91 \begin{python} 92 from esys.pycad import * 93 from esys.pycad.gmsh import Design 94 from esys.finley import MakeDomain 95 p0=Point(0.,0.,0.) 96 p1=Point(1.,0.,0.) 97 p2=Point(1.,1.,0.) 98 p3=Point(0.,1.,0.) 99 l01=Line(p0,p1) 100 l12=Line(p1,p2) 101 l23=Line(p2,p3) 102 l30=Line(p3,p0) 103 c=CurveLoop(l01,l12,l23,l30) 104 s=PlaneSurface(c) 105 d=Design(dim=2,element_size=0.05) 106 d.setScriptFileName("quad.geo") 107 d.addItems(s) 108 pl1=PropertySet("sides",l01,l23) 109 pl2=PropertySet("top_and_bottom",l12,l30) 110 d.addItems(pl1, pl2) 111 dom=MakeDomain(d) 112 dom.write("quad.fly") 113 \end{python} 114 This example is included with the software in \file{quad.py} in the 115 \ExampleDirectory. 116 117 There are three extra statements which we have not discussed yet. 118 By default the mesh used to subdivide the boundary is not written into the 119 mesh file mainly to reduce the size of the data file. 120 One needs to explicitly add the lines to the \Design which should be present 121 in the mesh data. Here we additionally labeled the lines on the top and the 122 bottom with the name top_and_bottom and the lines on the left and right 123 hand side with the name sides using \class{PropertySet} objects. 124 The labeling is convenient when using tagging\index{tagging}, see \Chap{ESCRIPT CHAP}. 125 126 \begin{figure} 127 \centerline{\includegraphics{quad}} 128 \caption{Quadrilateral with mesh of triangles} 129 \label{fig:PYCAD 0} 130 \end{figure} 131 132 If you have \gmshextern installed you can run the example and view the 133 geometry and mesh with: 134 \begin{verbatim} 135 run-escript quad.py 136 gmsh quad.geo 137 gmsh quad.msh 138 \end{verbatim} 139 See Figure~\ref{fig:PYCAD 0} for a result. 140 141 In most cases it is best practice to generate the mesh and solve the 142 mathematical model in two separate scripts. In our example you can read the 143 \finley mesh into your simulation code\footnote{\gmshextern files can be 144 directly read using \function{ReadGmsh}, see \Chap{CHAPTER ON FINLEY}} using 145 \begin{python} 146 from finley import ReadMesh 147 mesh=ReadMesh("quad.fly") 148 \end{python} 149 Note that the underlying mesh generation software will not accept all 150 the geometries you can create. For example, \pycad will happily allow 151 you to create a 2-D \class{Design} that is a closed loop with some 152 additional points or lines lying outside of the enclosed area, but 153 \gmshextern will fail to create a mesh for it. 154 155 \section{Holes} 156 The example included below shows how to use \pycad to create a 2-D mesh 157 in the shape of a trapezoid with a cut-out area as in Figure~\ref{fig:PYCAD 1}. 158 159 \begin{python} 160 from esys.pycad import * 161 from esys.pycad.gmsh import Design 162 from esys.finley import MakeDomain 163 164 # A trapezoid 165 p0=Point(0.0, 0.0, 0.0) 166 p1=Point(1.0, 0.0, 0.0) 167 p2=Point(1.0, 0.5, 0.0) 168 p3=Point(0.0, 1.0, 0.0) 169 l01=Line(p0, p1) 170 l12=Line(p1, p2) 171 l23=Line(p2, p3) 172 l30=Line(p3, p0) 173 c=CurveLoop(l01, l12, l23, l30) 174 175 # A small triangular cutout 176 x0=Point(0.1, 0.1, 0.0) 177 x1=Point(0.5, 0.1, 0.0) 178 x2=Point(0.5, 0.2, 0.0) 179 x01=Line(x0, x1) 180 x12=Line(x1, x2) 181 x20=Line(x2, x0) 182 cutout=CurveLoop(x01, x12, x20) 183 184 # Create the surface with cutout 185 s=PlaneSurface(c, holes=[cutout]) 186 187 # Create a Design which can make the mesh 188 d=Design(dim=2, element_size=0.05) 189 190 # Add the trapezoid with cutout 191 d.addItems(s) 192 193 # Create the geometry, mesh and Escript domain 194 d.setScriptFileName("trapezoid.geo") 195 d.setMeshFileName("trapezoid.msh") 196 domain=MakeDomain(d) 197 # write mesh to a finley file: 198 domain.write("trapezoid.fly") 199 \end{python} 200 This example is included with the software in \file{trapezoid.py} in the 201 \ExampleDirectory. 202 203 \begin{figure} 204 \centerline{\includegraphics{trapezoid}} 205 \caption{Trapezoid with triangular hole} 206 \label{fig:PYCAD 1} 207 \end{figure} 208 209 A \code{CurveLoop} is used to connect several lines into a single curve. 210 It is used in the example above to create the trapezoidal outline for the grid 211 and also for the triangular cutout area. 212 You can define any number of lines when creating a \class{CurveLoop}, but 213 the end of one line must be identical to the start of the next. 214 215 \section{A 3D example} 216 217 In this section we discuss the definition of 3D geometries. As an example 218 consider the unit cube as shown in Figure~\ref{fig:PYCAD 2}. 219 First we generate the vertices of the cube: 220 \begin{python} 221 from esys.pycad import * 222 p0=Point(0.,0.,0.) 223 p1=Point(1.,0.,0.) 224 p2=Point(0.,1.,0.) 225 p3=Point(1.,1.,0.) 226 p4=Point(0.,0.,1.) 227 p5=Point(1.,0.,1.) 228 p6=Point(0.,1.,1.) 229 p7=Point(1.,1.,1.) 230 \end{python} 231 232 We connect the points to form the bottom and top surfaces of the cube: 233 \begin{python} 234 l01=Line(p0,p1) 235 l13=Line(p1,p3) 236 l32=Line(p3,p2) 237 l20=Line(p2,p0) 238 bottom=PlaneSurface(-CurveLoop(l01,l13,l32,l20)) 239 \end{python} 240 241 \begin{figure} 242 \centerline{\includegraphics{brick}} 243 \caption{Three dimensional block} 244 \label{fig:PYCAD 2} 245 \end{figure} 246 247 Similar to the definition of a \code{CurvedLoop} the orientation of the 248 surfaces in a \code{SurfaceLoop} is relevant. 249 In fact, the surface normal direction defined by the right-hand rule needs to 250 point outwards as indicated by the surface normals in Figure~\ref{fig:PYCAD 2}. 251 As the \code{bottom} face is directed upwards it is inserted with the minus 252 sign into the \code{SurfaceLoop} in order to adjust the orientation of the 253 surface. Similarly we set 254 \begin{python} 255 l45=Line(p4,p5) 256 l57=Line(p5,p7) 257 l76=Line(p7,p6) 258 l64=Line(p6,p4) 259 top=PlaneSurface(CurveLoop(l45,l57,l76,l64)) 260 \end{python} 261 To form the front face we introduce the two additional lines connecting the 262 left and right front points of the \code{top} and \code{bottom} face: 263 \begin{python} 264 l15=Line(p1,p5) 265 l40=Line(p4,p0) 266 \end{python} 267 To form the front face we encounter the problem as the line \code{l45} used 268 to define the \code{top} face is pointing the wrong direction. 269 In \pycad you can reversing direction of an object by changing its sign. 270 So we write \code{-l45} to indicate that the direction is to be reversed. 271 With this notation we can write 272 \begin{python} 273 front=PlaneSurface(CurveLoop(l01,l15,-l45,l40)) 274 \end{python} 275 Keep in mind that if you use \code{Line(p4,p5)} instead of \code{-l45} both 276 objects are treated as different although connecting the same points with a 277 straight line in the same direction. The resulting geometry would include an 278 opening along the \code{p4}--\code{p5} connection. 279 This will lead to an inconsistent mesh and may result in a failure of the 280 volumetric mesh generator. Similarly we can define the other sides of the cube: 281 \begin{python} 282 l37=Line(p3,p7) 283 l62=Line(p6,p2) 284 back=PlaneSurface(CurveLoop(l32,-l62,-l76,-l37)) 285 left=PlaneSurface(CurveLoop(-l40,-l64,l62,l20)) 286 right=PlaneSurface(CurveLoop(-l15,l13,l37,-l57)) 287 \end{python} 288 We can now put the six surfaces together to form a \class{SurfaceLoop} 289 defining the boundary of the volume of the cube: 290 \begin{python} 291 sl=SurfaceLoop(top,bottom,front,back,left,right) 292 v=Volume(sl) 293 \end{python} 294 As in the 2D case, the \class{Design} class is used to define the geometry: 295 \begin{python} 296 from esys.pycad.gmsh import Design 297 from esys.finley import MakeDomain 298 299 des=Design(dim=3, element_size = 0.1, keep_files=True) 300 des.setScriptFileName("brick.geo") 301 des.addItems(v, top, bottom, back, front, left, right) 302 303 dom=MakeDomain(des) 304 dom.write("brick.fly") 305 \end{python} 306 Note that the \finley mesh file \file{brick.fly} will contain the 307 triangles used to define the surfaces as they are added to the \class{Design}. 308 The example script of the cube is included with the software in 309 \file{brick.py} in the \ExampleDirectory. 310 311 \section{Alternative File Formats} 312 \pycad supports other file formats including I-DEAS universal file, VRML, 313 Nastran and STL. The following example shows how to generate the STL file 314 \file{brick.stl}: 315 \begin{python} 316 from esys.pycad.gmsh import Design 317 318 des=Design(dim=3, element_size = 0.1, keep_files=True) 319 des.addItems(v, top, bottom, back, front, left , right) 320 321 des.setFileFormat(des.STL) 322 des.setMeshFileName("brick.stl") 323 des.generate() 324 \end{python} 325 The example script of the cube is included with the software in 326 \file{brick_stl.py} in the \ExampleDirectory. 327 328 \section{Element Sizes} 329 The element size used globally is defined by the \code{element_size} argument 330 of the \class{Design}. The mesh generator will try to use this mesh size 331 everywhere in the geometry. In some cases it can be desirable to use a finer 332 mesh locally. A local refinement can be defined at each \class{Point}: 333 \begin{python} 334 p0=Point(0., 0., 0., local_scale=0.01) 335 \end{python} 336 Here the mesh generator will create a mesh with an element size which is by 337 the factor \code{0.01} times smaller than the global mesh size 338 \code{element_size=0.3}, see Figure~\ref{fig:PYCAD 5}. 339 The point where a refinement is defined must be a point on a curve used to 340 define the geometry. 341 342 \begin{figure} 343 \centerline{\includegraphics{refine}} 344 \caption{Local refinement at the origin by \var{local_scale=0.01} 345 with \var{element_size=0.3} and number of elements on the top set to 10} 346 \label{fig:PYCAD 5} 347 \end{figure} 348 349 Alternatively, one can define a mesh size along a curve by defining the number 350 of elements to be used to subdivide the curve. For instance, to use $20$ 351 elements on line \code{l23}: 352 \begin{python} 353 l23=Line(p2, p3) 354 l23.setElementDistribution(20) 355 \end{python} 356 Setting the number of elements on a curve overwrites the global mesh size 357 \code{element_size}. The result is shown in Figure~\ref{fig:PYCAD 5}. 358 359 \section{\pycad Classes} 360 %\declaremodule{extension}{esys.pycad} 361 %\modulesynopsis{Python geometry description and meshing interface} 362 363 \subsection{Primitives} 364 Some of the most commonly-used objects in \pycad are listed here. 365 For a more complete list see the full API documentation. 366 367 \begin{classdesc}{Point}{x=0.,y=0.,z=0.\optional{,local_scale=1.}} 368 creates a point at the given coordinates with local characteristic length \var{local_scale} 369 \end{classdesc} 370 371 \begin{classdesc}{CurveLoop}{list} 372 creates a closed curve from a \code{list} of 373 \class{Line}, \class{Arc}, \class{Spline}, \class{BSpline}, 374 \class{BezierSpline} objects. 375 \end{classdesc} 376 377 \begin{classdesc}{SurfaceLoop}{list} 378 creates a loop of \class{PlaneSurface} or \class{RuledSurface}, which defines 379 the shell of a volume. 380 \end{classdesc} 381 382 \subsubsection{Lines} 383 \begin{classdesc}{Line}{point1, point2} 384 creates a line between two points. 385 \end{classdesc} 386 387 \begin{methoddesc}[Line]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}} 388 defines the number of elements on the line. If set, it overwrites the local 389 length setting which would be applied. 390 The progression factor \var{progression} defines the change of element size 391 between neighboured elements. If \var{createBump} is set progression is 392 applied towards the centre of the line. 393 \end{methoddesc} 394 395 \begin{methoddesc}[Line]{resetElementDistribution}{} 396 removes a previously set element distribution from the line. 397 \end{methoddesc} 398 \begin{methoddesc}[Line]{getElementDistribution}{} 399 returns the element distribution as a tuple of number of elements, progression 400 factor and bump flag. If no element distribution is set None is returned. 401 \end{methoddesc} 402 403 \subsubsection{Splines} 404 \begin{classdesc}{Spline}{point0, point1, ...} 405 A spline curve defined by a list of points \var{point0}, \var{point1}, \ldots 406 \end{classdesc} 407 408 \begin{methoddesc}[Spline]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}} 409 defines the number of elements on the spline. If set, it overwrites the local 410 length setting which would be applied. 411 The progression factor \var{progression} defines the change of element size 412 between neighboured elements. If \var{createBump} is set progression is 413 applied towards the centre of the spline. 414 \end{methoddesc} 415 416 \begin{methoddesc}[Spline]{resetElementDistribution}{} 417 removes a previously set element distribution from the spline. 418 \end{methoddesc} 419 420 \begin{methoddesc}[Spline]{getElementDistribution}{} 421 returns the element distribution as a tuple of number of elements, progression 422 factor and bump flag. If no element distribution is set None is returned. 423 \end{methoddesc} 424 425 \subsubsection{BSplines} 426 \begin{classdesc}{BSpline}{point0, point1, ...} 427 A B-spline curve defined by a list of points \var{point0}, \var{point1}, \ldots 428 \end{classdesc} 429 430 \begin{methoddesc}[BSpline]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}} 431 defines the number of elements on the curve. If set, it overwrites the local 432 length setting which would be applied. 433 The progression factor \var{progression} defines the change of element size 434 between neighboured elements. If \var{createBump} is set progression is 435 applied towards the centre of the curve. 436 \end{methoddesc} 437 438 \begin{methoddesc}[BSpline]{resetElementDistribution}{} 439 removes a previously set element distribution from the curve. 440 \end{methoddesc} 441 442 \begin{methoddesc}[BSpline]{getElementDistribution}{} 443 returns the element distribution as a tuple of number of elements, progression 444 factor and bump flag. If no element distribution is set None is returned. 445 \end{methoddesc} 446 447 \subsubsection{Bezier Curves} 448 \begin{classdesc}{BezierCurve}{point0, point1, ...} 449 A Bezier spline curve defined by a list of points \var{point0}, \var{point1}, \ldots 450 \end{classdesc} 451 452 \begin{methoddesc}[BezierCurve]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}} 453 defines the number of elements on the curve. If set, it overwrites the local 454 length setting which would be applied. 455 The progression factor \var{progression} defines the change of element size 456 between neighboured elements. If \var{createBump} is set progression is 457 applied towards the centre of the curve. 458 \end{methoddesc} 459 460 \begin{methoddesc}[BezierCurve]{resetElementDistribution}{} 461 removes a previously set element distribution from the curve. 462 \end{methoddesc} 463 464 \begin{methoddesc}[BezierCurve]{getElementDistribution}{} 465 returns the element distribution as a tuple of number of elements, progression 466 factor and bump flag. If no element distribution is set None is returned. 467 \end{methoddesc} 468 469 \subsubsection{Arcs} 470 \begin{classdesc}{Arc}{centre_point, start_point, end_point} 471 creates an arc by specifying a centre for a circle and start and end points. 472 An arc may subtend an angle of at most $\pi$ radians. 473 \end{classdesc} 474 475 \begin{methoddesc}[Arc]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}} 476 defines the number of elements on the arc. If set, it overwrites the local 477 length setting which would be applied. 478 The progression factor \var{progression} defines the change of element size 479 between neighboured elements. If \var{createBump} is set progression is 480 applied towards the centre of the arc. 481 \end{methoddesc} 482 483 \begin{methoddesc}[Arc]{resetElementDistribution}{} 484 removes a previously set element distribution from the arc. 485 \end{methoddesc} 486 487 \begin{methoddesc}[Arc]{getElementDistribution}{} 488 returns the element distribution as a tuple of number of elements, progression 489 factor and bump flag. If no element distribution is set None is returned. 490 \end{methoddesc} 491 492 \subsubsection{Plane surfaces} 493 \begin{classdesc}{PlaneSurface}{loop, \optional{holes=[list]}} 494 creates a plane surface from a \class{CurveLoop}, which may have one or more 495 holes described by a \var{list} of \class{CurveLoop} objects. 496 \end{classdesc} 497 498 \begin{methoddesc}[PlaneSurface]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}} 499 defines the number of elements on all lines. 500 \end{methoddesc} 501 502 \begin{methoddesc}[PlaneSurface]{setRecombination}{\optional{max_deviation=45 * \var{DEG} }} 503 the mesh generator will try to recombine triangular elements into 504 quadrilateral elements. \var{max_deviation} (in radians) defines the 505 maximum deviation of any angle in the quadrilaterals from the right angle. 506 Set \var{max_deviation}=\var{None} to remove recombination. 507 \end{methoddesc} 508 509 \begin{methoddesc}[PlaneSurface]{setTransfiniteMeshing}{\optional{orientation="Left"}} 510 applies 2D transfinite meshing to the surface. 511 \var{orientation} defines the orientation of triangles. Allowed values 512 are \var{Left''}, \var{Right''} and \var{Alternate''}. 513 The boundary of the surface must be defined by three or four lines and an 514 element distribution must be defined on all faces where opposite 515 faces use the same element distribution. No holes must be present. 516 \end{methoddesc} 517 518 \subsubsection{Ruled Surfaces} 519 \begin{classdesc}{RuledSurface}{list} 520 creates a surface that can be interpolated using transfinite interpolation. 521 \var{list} gives a list of three or four lines defining the boundary of the 522 surface. 523 \end{classdesc} 524 525 \begin{methoddesc}[RuledSurface]{setRecombination}{\optional{max_deviation=45 * \var{DEG} }} 526 the mesh generator will try to recombine triangular elements into 527 quadrilateral elements. \var{max_deviation} (in radians) defines the 528 maximum deviation of any angle in the quadrilaterals from the right angle. 529 Set \var{max_deviation}=\var{None} to remove recombination. 530 \end{methoddesc} 531 532 \begin{methoddesc}[RuledSurface]{setTransfiniteMeshing}{\optional{orientation="Left"}} 533 applies 2D transfinite meshing to the surface. 534 \var{orientation} defines the orientation of triangles. Allowed values 535 are \var{Left''}, \var{Right''} and \var{Alternate''}. 536 The boundary of the surface must be defined by three or four lines and an 537 element distribution must be defined on all faces where opposite 538 faces use the same element distribution. No holes must be present. 539 \end{methoddesc} 540 541 \begin{methoddesc}[RuledSurface]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}} 542 defines the number of elements on all lines. 543 \end{methoddesc} 544 545 \subsubsection{Volumes} 546 \begin{classdesc}{Volume}{loop, \optional{holes=[list]}} 547 creates a volume given a \class{SurfaceLoop}, which may have one or more holes 548 define by the list of \class{SurfaceLoop}. 549 \end{classdesc} 550 551 \begin{methoddesc}[Volume]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}} 552 defines the number of elements on all lines. 553 \end{methoddesc} 554 555 \begin{methoddesc}[Volume]{setRecombination}{\optional{max_deviation=45 * \var{DEG} }} 556 the mesh generator will try to recombine triangular elements into 557 quadrilateral elements. These meshes are then used to generate the volume mesh 558 if possible. 559 Together with transfinite meshing one can construct rectangular meshes. 560 \var{max_deviation} (in radians) defines the maximum deviation of any angle in 561 the quadrilaterals from the right angle. 562 Set \var{max_deviation}=\var{None} to remove recombination. 563 \end{methoddesc} 564 565 \begin{methoddesc}[Volume]{setTransfiniteMeshing}{\optional{orientation="Left"}} 566 applies transfinite meshing to the volume and all surfaces (if 567 \var{orientation} is not equal to \var{None}). 568 \var{orientation} defines the orientation of triangles. Allowed values 569 are \var{Left''}, \var{Right''} and \var{Alternate''}. 570 The boundary of the surface must be defined by three or four lines and an 571 element distribution must be defined on all faces where opposite 572 faces use the same element distribution. 573 If \var{orientation} is equal to \var{None} transfinite meshing is not 574 switched on for the surfaces but needs to be set by the user. 575 No holes must be present. 576 \textbf{Warning: The functionality of transfinite meshing without 577 recombination is not entirely clear in \gmshextern. 578 So please apply this method with care.} 579 \end{methoddesc} 580 581 %============================================================================ 582 \subsection{Transformations} 583 584 Sometimes it is convenient to create an object and then make copies at 585 different orientations or in different sizes. This can be achieved by 586 applying transformations which are used to move geometrical objects in the 587 3-dimensional space and to resize them. 588 589 \begin{classdesc}{Translation}{\optional{b=[0,0,0]}} 590 defines a translation $x \to x+b$. \var{b} can be any object that can be 591 converted into a \numpy object of shape $(3,)$. 592 \end{classdesc} 593 594 \begin{classdesc}{Rotation}{\optional{axis=[1,1,1], \optional{ point = [0,0,0], \optional{angle=0*RAD} } } } 595 defines a rotation by \var{angle} around axis through point \var{point} and direction \var{axis}. 596 \var{axis} and \var{point} can be any object that can be converted into a 597 \numpy object of shape $(3,)$. 598 \var{axis} does not have to be normalised but must have positive length. 599 The right-hand rule~\cite{RIGHTHANDRULE} applies. 600 \end{classdesc} 601 602 \begin{classdesc}{Dilation}{\optional{factor=1., \optional{centre=[0,0,0]}}} 603 defines a dilation by the expansion/contraction \var{factor} with 604 \var{centre} as the dilation centre. 605 \var{centre} can be any object that can be converted into a \numpy object of 606 shape $(3,)$. 607 \end{classdesc} 608 609 \begin{classdesc}{Reflection}{\optional{normal=[1,1,1], \optional{offset=0}}} 610 defines a reflection on a plane defined in normal form $n^t x = d$ 611 where $n$ is the surface normal \var{normal} and $d$ is the plane \var{offset}. 612 \var{normal} can be any object that can be converted into a \numpy object of 613 shape $(3,)$. 614 \var{normal} does not have to be normalised but must have positive length. 615 \end{classdesc} 616 617 \begin{datadesc}{DEG} 618 a constant to convert from degrees to an internal angle representation in 619 radians. For instance use \code{90*DEG} for $90$ degrees. 620 \end{datadesc} 621 622 \subsection{Properties} 623 If you are building a larger geometry you may find it convenient to 624 create it in smaller pieces and then assemble them. 625 Property Sets make this easy, and they allow you to name the smaller 626 pieces for convenience. 627 628 Property Sets are used to bundle a set of geometrical objects in a 629 group. The group is identified by a name. Typically a Property Set 630 is used to mark subregions which share the same material properties or 631 to mark portions of the boundary. For efficiency, the \Design class 632 assigns an integer to each of its Property Sets, a so-called tag\index{tag}. 633 The appropriate tag is attached to the elements at generation time. 634 635 See the file \code{pycad/examples/quad.py} for an example using a {\it PropertySet}. 636 637 \begin{classdesc}{PropertySet}{name,*items} 638 defines a group geometrical objects which can be accessed through a \var{name} 639 The objects in the tuple \var{items} mast all be \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD objects. 640 \end{classdesc} 641 642 \begin{methoddesc}[PropertySet]{getManifoldClass}{} 643 returns the manifold class \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD 644 expected from the items in the property set. 645 \end{methoddesc} 646 647 \begin{methoddesc}[PropertySet]{getDim}{} 648 returns the spatial dimension of the items in the property set. 649 \end{methoddesc} 650 651 \begin{methoddesc}[PropertySet]{getName}{} 652 returns the name of the set 653 \end{methoddesc} 654 655 \begin{methoddesc}[PropertySet]{setName}{name} 656 sets the name. This name should be unique within a \Design. 657 \end{methoddesc} 658 659 \begin{methoddesc}[PropertySet]{addItem}{*items} 660 adds a tuple of items. They need to be objects of class \ManifoldOneD, 661 \ManifoldTwoD or \ManifoldThreeD. 662 \end{methoddesc} 663 664 \begin{methoddesc}[PropertySet]{getItems}{} 665 returns the list of items 666 \end{methoddesc} 667 668 \begin{methoddesc}[PropertySet]{clearItems}{} 669 clears the list of items 670 \end{methoddesc} 671 672 \begin{methoddesc}[PropertySet]{getTag}{} 673 returns the tag used for this property set 674 \end{methoddesc} 675 676 \section{Interface to the mesh generation software} 677 %\declaremodule{extension}{esys.pycad.gmsh} 678 %\modulesynopsis{Python geometry description and meshing interface} 679 680 The class and methods described here provide an interface to the mesh 681 generation software, which is currently \gmshextern. This interface could be 682 adopted to \emph{triangle} or another mesh generation package if this is 683 deemed to be desirable in the future. 684 685 \begin{classdesc}{Design}{ 686 \optional{dim=3, \optional{element_size=1., \optional{order=1, \optional{keep_files=False}}}}} 687 describes the geometry defined by primitives to be meshed. 688 \var{dim} specifies the spatial dimension, while \var{element_size} defines 689 the global element size which is multiplied by the local scale to set the 690 element size at each \Point. 691 The argument \var{order} defines the element order to be used. 692 If \var{keep_files} is set to \True temporary files are kept, otherwise they 693 are removed when the instance of the class is deleted. 694 \end{classdesc} 695 696 \begin{memberdesc}[Design]{GMSH} 697 gmsh file format~\cite{GMSH} 698 \end{memberdesc} 699 700 \begin{memberdesc}[Design]{IDEAS} 701 I-DEAS universal file format~\cite{IDEAS} 702 \end{memberdesc} 703 704 \begin{memberdesc}[Design]{VRML} 705 VRML file format, \cite{VRML} 706 \end{memberdesc} 707 708 \begin{memberdesc}[Design]{STL} 709 STL file format~\cite{STL} 710 \end{memberdesc} 711 712 \begin{memberdesc}[Design]{NASTRAN} 713 NASTRAN bulk data format~\cite{NASTRAN} 714 \end{memberdesc} 715 716 \begin{memberdesc}[Design]{MEDIT} 717 Medit file format~\cite{MEDIT} 718 \end{memberdesc} 719 720 \begin{memberdesc}[Design]{CGNS} 721 CGNS file format~\cite{CGNS} 722 \end{memberdesc} 723 724 \begin{memberdesc}[Design]{PLOT3D} 725 Plot3D file format~\cite{PLOT3D} 726 \end{memberdesc} 727 728 \begin{memberdesc}[Design]{DIFFPACK} 729 Diffpack 3D file format~\cite{DIFFPACK} 730 \end{memberdesc} 731 732 \begin{memberdesc}[Design]{DELAUNAY} 733 the Delaunay triangulator, see \gmshextern and \cite{TETGEN} 734 \end{memberdesc} 735 736 \begin{memberdesc}[Design]{MESHADAPT} 737 the gmsh triangulator, see \gmshextern 738 \end{memberdesc} 739 740 \begin{memberdesc}[Design]{FRONTAL} 741 the NETGEN~\cite{NETGEN} triangulator 742 \end{memberdesc} 743 744 \begin{methoddesc}[Design]{generate}{} 745 generates the mesh file. The data are written to the file \var{Design.getMeshFileName}. 746 \end{methoddesc} 747 748 \begin{methoddesc}[Design]{setDim}{\optional{dim=3}} 749 sets the spatial dimension which needs to be $1$, $2$ or $3$. 750 \end{methoddesc} 751 752 \begin{methoddesc}[Design]{getDim}{} 753 returns the spatial dimension. 754 \end{methoddesc} 755 756 \begin{methoddesc}[Design]{setElementOrder}{\optional{order=1}} 757 sets the element order which needs to be $1$ or $2$. 758 \end{methoddesc} 759 760 \begin{methoddesc}[Design]{getElementOrder}{} 761 returns the element order. 762 \end{methoddesc} 763 764 \begin{methoddesc}[Design]{setElementSize}{\optional{element_size=1}} 765 sets the global element size. The local element size at a point is defined as 766 the global element size multiplied by the local scale. 767 The element size must be positive. 768 \end{methoddesc} 769 770 \begin{methoddesc}[Design]{getElementSize}{} 771 returns the global element size. 772 \end{methoddesc} 773 774 \begin{methoddesc}[Design]{setKeepFilesOn}{} 775 work files are kept at the end of the generation. 776 \end{methoddesc} 777 778 \begin{methoddesc}[Design]{setKeepFilesOff}{} 779 work files are deleted at the end of the generation. 780 \end{methoddesc} 781 782 \begin{methoddesc}[Design]{keepFiles}{} 783 returns \True if work files are kept, \False otherwise. 784 \end{methoddesc} 785 786 \begin{methoddesc}[Design]{setScriptFileName}{\optional{name=None}} 787 sets the file name for the gmsh input script. 788 If no name is given a name with extension "geo" is generated. 789 \end{methoddesc} 790 791 \begin{methoddesc}[Design]{getScriptFileName}{} 792 returns the name of the file for the gmsh script. 793 \end{methoddesc} 794 795 \begin{methoddesc}[Design]{setMeshFileName}{\optional{name=None}} 796 sets the name for the mesh file. If no name is given a name is generated. 797 The format is set by \\\var{Design.setFileFormat}. 798 \end{methoddesc} 799 800 \begin{methoddesc}[Design]{getMeshFileName}{} 801 returns the name of the mesh file. 802 \end{methoddesc} 803 804 \begin{methoddesc}[Design]{addItems}{*items} 805 adds the tuple of \var{items}. An item can be any primitive or a 806 \class{PropertySet}. 807 \warning{If a \PropertySet is added which includes an object that is not 808 part of a \PropertySet, it may not be considered in the meshing.} 809 \end{methoddesc} 810 811 \begin{methoddesc}[Design]{getItems}{} 812 returns a list of the items. 813 \end{methoddesc} 814 815 \begin{methoddesc}[Design]{clearItems}{} 816 resets the items in this design. 817 \end{methoddesc} 818 819 \begin{methoddesc}[Design]{getMeshHandler}{} 820 returns a handle to the mesh. 821 Calling this method generates the mesh from the geometry and returns a 822 mechanism to access the mesh data. In the current implementation this 823 method returns a file name for a file containing the mesh data. 824 \end{methoddesc} 825 826 \begin{methoddesc}[Design]{getScriptString}{} 827 returns the gmsh script to generate the mesh as a string. 828 \end{methoddesc} 829 830 \begin{methoddesc}[Design]{getCommandString}{} 831 returns the gmsh command used to generate the mesh as a string. 832 \end{methoddesc} 833 834 \begin{methoddesc}[Design]{setOptions}{ 835 \optional{optimize_quality=\True 836 \optional{, smoothing=1 837 \optional{, curvature_based_element_size=\False\\ 838 \optional{, algorithm2D=\var{Design.MESHADAPT} 839 \optional{, algorithm3D=\var{Design.FRONTAL}\\ 840 \optional{, generate_hexahedra=False}}}}}}} 841 sets options for the mesh generator. 842 \var{algorithm2D} sets the 2D meshing algorithm to be used. 843 The algorithm needs to be \var{Design.DELAUNAY}, \var{Design.FRONTAL}, 844 or \var{Design.MESHADAPT}. By default \var{Design.MESHADAPT} is used. 845 \var{algorithm3D} sets the 3D meshing algorithm to be used. 846 The algorithm needs to be \var{Design.DELAUNAY} or \var{Design.FRONTAL}. 847 By default \var{Design.FRONTAL} is used. 848 \var{optimize_quality}=\True invokes an optimization of the mesh quality. 849 \var{smoothing} sets the number of smoothing steps to be applied to the mesh. 850 \var{curvature_based_element_size}=\True switches on curvature based 851 definition of element size. 852 \var{generate_hexahedra}=\True switches on the usage of quadrilateral or 853 hexahedral elements. 854 \end{methoddesc} 855 856 \begin{methoddesc}[Design]{getTagMap}{} 857 returns a \class{TagMap} to map the \class{PropertySet} names to tag numbers 858 generated by gmsh. 859 \end{methoddesc} 860 861 \begin{methoddesc}[Design]{setFileFormat}{\optional{format=\var{Design.GMSH}}} 862 sets the file format. \var{format} must be one of the values:\\ 863 \var{Design.GMSH}\\ 864 \var{Design.IDEAS}\\ 865 \var{Design.VRML}\\ 866 \var{Design.STL}\\ 867 \var{Design.NASTRAN}\\ 868 \var{Design.MEDIT}\\ 869 \var{Design.CGNS}\\ 870 \var{Design.PLOT3D}\\ 871 \var{Design.DIFFPACK}. 872 \end{methoddesc} 873 874 \begin{methoddesc}[Design]{getFileFormat}{} 875 returns the file format. 876 \end{methoddesc} 877

 ViewVC Help Powered by ViewVC 1.1.26