/[escript]/trunk/doc/user/pycad.tex
ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log


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 % http://www.uq.edu.au
5 %
6 % Primary Business: Queensland, Australia
7 % Licensed under the Open Software License version 3.0
8 % http://www.opensource.org/licenses/osl-3.0.php
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