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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2651 - (show annotations)
Mon Sep 7 03:39:45 2009 UTC (11 years, 5 months ago) by jfenwick
File MIME type: application/x-tex
File size: 20384 byte(s)
Fixed latex compile error.
Fixed some overful hboxes

1
2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %
4 % Copyright (c) 2003-2009 by University of Queensland
5 % Earth Systems Science Computational Center (ESSCC)
6 % http://www.uq.edu.au/esscc
7 %
8 % Primary Business: Queensland, Australia
9 % Licensed under the Open Software License version 3.0
10 % http://www.opensource.org/licenses/osl-3.0.php
11 %
12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13
14
15 \chapter{The Module \pycad} \label{PYCAD CHAP}
16
17
18 \section{Introduction}
19
20 \pycad provides a simple way to build a mesh for your finite element
21 simulation. You begin by building what we call a {\it Design} using
22 primitive geometric objects, and then to go on to build a mesh from
23 the {\it Design}. The final step of generating the mesh from a {\it
24 Design} uses freely available mesh generation software, such as \gmshextern.
25
26 A {\it Design} is built by defining points, which are used to specify
27 the corners of geometric objects and the vertices of curves. Using
28 points you construct more interesting objects such as lines,
29 rectangles, and arcs. By adding many of these objects into what we
30 call a {\it Design}, you can build meshes for arbitrarily complex 2-D
31 and 3-D structures.
32
33 The example included below shows how to use {\it pycad} to create a 2-D mesh
34 in the shape of a trapezoid with a cutout area.
35
36 \begin{python}
37 from esys.pycad import *
38 from esys.pycad.gmsh import Design
39 from esys.finley import MakeDomain
40
41 # A trapezoid
42 p0=Point(0.0, 0.0, 0.0)
43 p1=Point(1.0, 0.0, 0.0)
44 p2=Point(1.0, 0.5, 0.0)
45 p3=Point(0.0, 1.0, 0.0)
46 l01=Line(p0, p1)
47 l12=Line(p1, p2)
48 l23=Line(p2, p3)
49 l30=Line(p3, p0)
50 c=CurveLoop(l01, l12, l23, l30)
51
52 # A small triangular cutout
53 x0=Point(0.1, 0.1, 0.0)
54 x1=Point(0.5, 0.1, 0.0)
55 x2=Point(0.5, 0.2, 0.0)
56 x01=Line(x0, x1)
57 x12=Line(x1, x2)
58 x20=Line(x2, x0)
59 cutout=CurveLoop(x01, x12, x20)
60
61 # Create the surface with cutout
62 s=PlaneSurface(c, holes=[cutout])
63
64 # Create a Design which can make the mesh
65 d=Design(dim=2, element_size=0.05)
66
67 # Add the trapezoid with cutout
68 d.addItems(s)
69
70 # Create the geometry, mesh and Escript domain
71 d.setScriptFileName("trapezoid.geo")
72 d.setMeshFileName("trapezoid.msh")
73 domain=MakeDomain(d, integrationOrder=-1, reducedIntegrationOrder=-1,
74 optimizeLabeling=True)
75
76 # Create a file that can be read back in to python with
77 # mesh=ReadMesh(fileName)
78 domain.write("trapezoid.fly")
79 \end{python}
80
81 This example is included with the software in
82 \code{pycad/examples/trapezoid.py}. If you have gmsh installed you can
83 run the example and view the geometry and mesh with:
84
85 \begin{python}
86 python trapezoid.py
87 gmsh trapezoid.geo
88 gmsh trapezoid.msh
89 \end{python}
90
91 A \code{CurveLoop} is used to connect several lines into a single curve.
92 It is used in the example above to create the trapezoidal outline for the grid
93 and also for the triangular cutout area.
94 You can use any number of lines when creating a \code{CurveLoop}, but
95 the end of one line must be identical to the start of the next.
96
97 Sometimes you might see us write \code{-c} where \code{c} is a
98 \code{CurveLoop}. This is the reverse curve of the curve \code{c}.
99 It is identical to the original except that its points are traversed
100 in the opposite order. This may make it easier to connect two curves
101 in a \code{CurveLoop}.
102
103 The example python script above calls both
104 \code{d.setScriptFileName()} and \code{d.setMeshFileName()}. You need
105 only call these if you wish to save the gmsh geometry and mesh files.
106
107 Note that the underlying mesh generation software will not accept all
108 the geometries you can create with {\it pycad}. For example, {\it
109 pycad} will happily allow you to create a 2-D {\it Design} that is a
110 closed loop with some additional points or lines lying outside of the
111 enclosed area, but gmsh will fail to create a mesh for it.
112
113
114
115
116
117
118 \section{\pycad Classes}
119 \declaremodule{extension}{esys.pycad}
120 \modulesynopsis{Python geometry description and meshing interface}
121
122 \subsection{Primitives}
123
124 Some of the most commonly-used objects in {\it pycad} are listed here. For a more complete
125 list see the full API documentation.
126
127 \begin{classdesc}{Point}{x=0.,y=0.,z=0.\optional{,local_scale=1.}}
128 Create a point with from coordinates with local characteristic length \var{local_scale}
129 \end{classdesc}
130
131 \begin{classdesc}{Line}{point1, point2}
132 Create a line with between starting and ending points.
133 \end{classdesc}
134 \begin{methoddesc}[Line]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
135 Defines the number of elements on the line. If set it overwrites the local length setting which would be applied. The progression factor \var{progression} defines the change of element size between naighboured elements. If \var{createBump} is set
136 progression is applied towards the center of the line.
137 \end{methoddesc}
138 \begin{methoddesc}[Line]{resetElementDistribution}{}
139 removes a previously set element distribution from the line.
140 \end{methoddesc}
141 \begin{methoddesc}[Line]{getElemenofDistribution}{}
142 Returns the element distribution as tuple of
143 number of elements, progression factor and bump flag. If
144 no element distribution is set None is returned.
145 \end{methoddesc}
146
147
148 \begin{classdesc}{Spline}{point0, point1, ...}
149 A spline curve defined by a list of points \var{point0}, \var{point1},....
150 \end{classdesc}
151 \begin{methoddesc}[Spline]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
152 Defines the number of elements on the line. If set it overwrites the local length setting which would be applied. The progression factor \var{progression} defines the change of element size between naighboured elements. If \var{createBump} is set
153 progression is applied towards the center of the line.
154 \end{methoddesc}
155 \begin{methoddesc}[Spline]{resetElementDistribution}{}
156 removes a previously set element distribution from the line.
157 \end{methoddesc}
158 \begin{methoddesc}[Spline]{getElemenofDistribution}{}
159 Returns the element distribution as tuple of
160 number of elements, progression factor and bump flag. If
161 no element distribution is set None is returned.
162 \end{methoddesc}
163
164 \begin{classdesc}{BSpline}{point0, point1, ...}
165 A B-spline curve defined by a list of points \var{point0}, \var{point1},....
166 \end{classdesc}
167 \begin{methoddesc}[BSpline]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
168 Defines the number of elements on the line. If set it overwrites the local length setting which would be applied. The progression factor \var{progression} defines the change of element size between naighboured elements. If \var{createBump} is set
169 progression is applied towards the center of the line.
170 \end{methoddesc}
171 \begin{methoddesc}[BSpline]{resetElementDistribution}{}
172 removes a previously set element distribution from the line.
173 \end{methoddesc}
174 \begin{methoddesc}[BSpline]{getElemenofDistribution}{}
175 Returns the element distribution as tuple of
176 number of elements, progression factor and bump flag. If
177 no element distribution is set None is returned.
178 \end{methoddesc}
179
180 \begin{classdesc}{BezierCurve}{point0, point1, ...}
181 A Brezier spline curve defined by a list of points \var{point0}, \var{point1},....
182 \end{classdesc}
183 \begin{methoddesc}[BezierCurve]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
184 Defines the number of elements on the line. If set it overwrites the local length setting which would be applied. The progression factor \var{progression} defines the change of element size between naighboured elements. If \var{createBump} is set
185 progression is applied towards the center of the line.
186 \end{methoddesc}
187 \begin{methoddesc}[BezierCurve]{resetElementDistribution}{}
188 removes a previously set element distribution from the line.
189 \end{methoddesc}
190 \begin{methoddesc}[BezierCurve]{getElemenofDistribution}{}
191 Returns the element distribution as tuple of
192 number of elements, progression factor and bump flag. If
193 no element distribution is set None is returned.
194 \end{methoddesc}
195
196 \begin{classdesc}{Arc}{center_point, start_point, end_point}
197 Create an arc by specifying a center for a circle and start and end points. An arc may subtend an angle of at most $\pi$ radians.
198 \end{classdesc}
199 \begin{methoddesc}[Arc]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
200 Defines the number of elements on the line. If set it overwrites the local length setting which would be applied. The progression factor \var{progression} defines the change of element size between naighboured elements. If \var{createBump} is set
201 progression is applied towards the center of the line.
202 \end{methoddesc}
203 \begin{methoddesc}[Arc]{resetElementDistribution}{}
204 removes a previously set element distribution from the line.
205 \end{methoddesc}
206 \begin{methoddesc}[Arc]{getElemenofDistribution}{}
207 Returns the element distribution as tuple of
208 number of elements, progression factor and bump flag. If
209 no element distribution is set None is returned.
210 \end{methoddesc}
211
212 \begin{classdesc}{CurveLoop}{list}
213 Create a closed curve from the \code{list}. of
214 \class{Line}, \class{Arc}, \class{Spline}, \class{BSpline},
215 \class{BrezierSpline}.
216 \end{classdesc}
217
218 \begin{classdesc}{PlaneSurface}{loop, \optional{holes=[list]}}
219 Create a plane surface from a \class{CurveLoop}, which may have one or more holes
220 described by \var{list} of \class{CurveLoop}.
221 \end{classdesc}
222 \begin{methoddesc}[PlaneSurface]{setRecombination}{max_deviation}
223 the mesh generator will try to recombine triangular elements
224 into quadrilateral elements. \var{max_deviation} (in radians) defines the
225 maximum deviation of any angle in the quadrilaterals from the right angle.
226 Set \var{max_deviation}=\var{None} to remove recombination.
227 \end{methoddesc}
228 \begin{methoddesc}[PlaneSurface]{setTransfiniteMeshing}{\optional{orientation="Left"}}
229 applies 2D transfinite meshing to the surface.
230 \var{orientation} defines the orientation of triangles. Allowed values
231 are \var{``Left''}, \var{``Right''} or \var{``Alternate''}. The
232 boundary of the surface muist be defined by three or four lines where an
233 element distribution must be defined on all faces where opposite
234 faces uses the same element distribution. No holes must be present.
235 \end{methoddesc}
236
237
238
239 \begin{classdesc}{RuledSurface}{list}
240 Create a surface that can be interpolated using transfinite interpolation.
241 \var{list} gives a list of three or four lines defining the boundary of the
242 surface.
243 \end{classdesc}
244 \begin{methoddesc}[RuledSurface]{setRecombination}{max_deviation}
245 the mesh generator will try to recombine triangular elements
246 into quadrilateral elements. \var{max_deviation} (in radians) defines the
247 maximum deviation of any angle in the quadrilaterals from the right angle.
248 Set \var{max_deviation}=\var{None} to remove recombination.
249 \end{methoddesc}
250 \begin{methoddesc}[RuledSurface]{setTransfiniteMeshing}{\optional{orientation="Left"}}
251 applies 2D transfinite meshing to the surface.
252 \var{orientation} defines the orientation of triangles. Allowed values
253 are \var{``Left''}, \var{``Right''} or \var{``Alternate''}. The
254 boundary of the surface muist be defined by three or four lines where an
255 element distribution must be defined on all faces where opposite
256 faces uses the same element distribution. No holes must be present.
257 \end{methoddesc}
258
259
260 \begin{classdesc}{SurfaceLoop}{list}
261 Create a loop of \class{PlaneSurface} or \class{RuledSurface}, which defines the shell of a volume.
262 \end{classdesc}
263
264 \begin{classdesc}{Volume}{loop, \optional{holes=[list]}}
265 Create a volume given a \class{SurfaceLoop}, which may have one or more holes
266 define by the list of \class{SurfaceLoop}.
267 \end{classdesc}
268
269 \begin{classdesc}{PropertySet}{list}
270 Create a PropertySet given a list of 1-D, 2-D or 3-D items. See the section on Properties below for more information.
271 \end{classdesc}
272
273 %============================================================================================================
274 \subsection{Transformations}
275
276 Sometimes it's convenient to create an object and then make copies at
277 different orientations and in different sizes. Transformations are
278 used to move geometrical objects in the 3-dimensional space and to
279 resize them.
280
281 \begin{classdesc}{Translation}{\optional{b=[0,0,0]}}
282 defines a translation $x \to x+b$. \var{b} can be any object that can be converted
283 into a \numpy object of shape $(3,)$.
284 \end{classdesc}
285
286 \begin{classdesc}{Rotatation}{\optional{axis=[1,1,1], \optional{ point = [0,0,0], \optional{angle=0*RAD} } } }
287 defines a rotation by \var{angle} around axis through point \var{point} and direction \var{axis}.
288 \var{axis} and \var{point} can be any object that can be converted
289 into a \numpy object of shape $(3,)$.
290 \var{axis} does not have to be normalized but must have positive length. The right hand rule~\cite{RIGHTHANDRULE}
291 applies.
292 \end{classdesc}
293
294
295 \begin{classdesc}{Dilation}{\optional{factor=1., \optional{center=[0,0,0]}}}
296 defines a dilation by the expansion/contraction \var{factor} with
297 \var{center} as the dilation center.
298 \var{center} can be any object that can be converted
299 into a \numpy object of shape $(3,)$.
300 \end{classdesc}
301
302 \begin{classdesc}{Reflection}{\optional{normal=[1,1,1], \optional{offset=0}}}
303 defines a reflection on a plane defined in normal form $n^t x = d$
304 where $n$ is the surface normal \var{normal} and $d$ is the plane \var{offset}.
305 \var{normal} can be any object that can be converted
306 into a \numpy object of shape $(3,)$.
307 \var{normal} does not have to be normalized but must have positive length.
308 \end{classdesc}
309
310 \begin{datadesc}{DEG}
311 A constant to convert from degrees to an internal angle representation in radians. For instance use \code{90*DEG} for $90$ degrees.
312 \end{datadesc}
313
314 \subsection{Properties}
315
316 If you are building a larger geometry you may find it convenient to
317 create it in smaller pieces and then assemble them into the whole.
318 Property sets make this easy, and they allow you to name the smaller
319 pieces for convenience.
320
321 Property sets are used to bundle a set of geometrical objects in a
322 group. The group is identified by a name. Typically a property set
323 is used to mark subregions with share the same material properties or
324 to mark portions of the boundary. For efficiency, the \Design class
325 object assigns a integer to each of its property sets, a so-called tag
326 \index{tag}. The appropriate tag is attached to the elements at
327 generation time.
328
329 See the file \code{pycad/examples/quad.py} for an example using a {\it PropertySet}.
330
331
332 \begin{classdesc}{PropertySet}{name,*items}
333 defines a group geometrical objects which can be accessed through a \var{name}
334 The objects in the tuple \var{items} mast all be \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD objects.
335 \end{classdesc}
336
337
338 \begin{methoddesc}[PropertySet]{getManifoldClass}{}
339 returns the manifold class \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD expected from the items
340 in the property set.
341 \end{methoddesc}
342
343 \begin{methoddesc}[PropertySet]{getDim}{}
344 returns the spatial dimension of the items
345 in the property set.
346 \end{methoddesc}
347
348 \begin{methoddesc}[PropertySet]{getName}{}
349 returns the name of the set
350 \end{methoddesc}
351
352 \begin{methoddesc}[PropertySet]{setName}{name}
353 sets the name. This name should be unique within a \Design.
354 \end{methoddesc}
355
356 \begin{methoddesc}[PropertySet]{addItem}{*items}
357 adds a tuple of items. They need to be objects of class \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD.
358 \end{methoddesc}
359
360 \begin{methoddesc}[PropertySet]{getItems}{}
361 returns the list of items
362 \end{methoddesc}
363
364 \begin{methoddesc}[PropertySet]{clearItems}{}
365 clears the list of items
366 \end{methoddesc}
367
368 \begin{methoddesc}[PropertySet]{getTag}{}
369 returns the tag used for this property set
370 \end{methoddesc}
371
372 \section{Interface to the mesh generation software}
373 \declaremodule{extension}{esys.pycad.gmsh}
374 \modulesynopsis{Python geometry description and meshing interface}
375
376 The class and methods described here provide an interface to the mesh
377 generation software, which is currently gmsh. This interface could be
378 adopted to triangle or another mesh generation package if this is
379 deemed to be desirable in the future.
380
381 \begin{classdesc}{Design}{
382 \optional{dim=3, \optional{element_size=1., \optional{order=1, \optional{keep_files=False}}}}}
383 The \class{Design} describes the geometry defined by primitives to be meshed.
384 The \var{dim} specifies the spatial dimension. The argument \var{element_size} defines the global
385 element size which is multiplied by the local scale to set the element size at each \Point.
386 The argument \var{order} defines the element order to be used. If \var{keep_files} is set to
387 \True temporary files a kept otherwise they are removed when the instance of the class is deleted.
388 \end{classdesc}
389
390
391 \begin{methoddesc}[Design]{setDim}{\optional{dim=3}}
392 sets the spatial dimension which needs to be $1$, $2$ or $3$.
393 \end{methoddesc}
394
395 \begin{methoddesc}[Design]{getDim}{}
396 returns the spatial dimension.
397 \end{methoddesc}
398
399 \begin{methoddesc}[Design]{setElementOrder}{\optional{order=1}}
400 sets the element order which needs to be $1$ or $2$.
401 \end{methoddesc}
402
403 \begin{methoddesc}[Design]{getElementOrder}{}
404 returns the element order.
405 \end{methoddesc}
406
407
408 \begin{methoddesc}[Design]{setElementSize}{\optional{element_size=1}}
409 set the global element size. The local element size at a point is defined as
410 the global element size multiplied by the local scale. The element size must be positive.
411 \end{methoddesc}
412
413
414 \begin{methoddesc}[Design]{getElementSize}{}
415 returns the global element size.
416 \end{methoddesc}
417
418 \begin{memberdesc}[Design]{DELAUNAY}
419 the gmsh Delauny triangulator.
420 \end{memberdesc}
421
422 \begin{memberdesc}[Design]{TETGEN}
423 the TetGen~\cite{TETGEN} triangulator.
424 \end{memberdesc}
425
426 \begin{memberdesc}[Design]{NETGEN}
427 the NETGEN~\cite{NETGEN} triangulator.
428 \end{memberdesc}
429
430 \begin{methoddesc}[Design]{setKeepFilesOn}{}
431 work files are kept at the end of the generation.
432 \end{methoddesc}
433
434 \begin{methoddesc}[Design]{setKeepFilesOff}{}
435 work files are deleted at the end of the generation.
436 \end{methoddesc}
437
438 \begin{methoddesc}[Design]{keepFiles}{}
439 returns \True if work files are kept. Otherwise \False is returned.
440 \end{methoddesc}
441
442 \begin{methoddesc}[Design]{setScriptFileName}{\optional{name=None}}
443 set the filename for the gmsh input script. if no name is given a name with extension "geo" is generated.
444 \end{methoddesc}
445
446 \begin{methoddesc}[Design]{getScriptFileName}{}
447 returns the name of the file for the gmsh script.
448 \end{methoddesc}
449
450
451 \begin{methoddesc}[Design]{setMeshFileName}{\optional{name=None}}
452 sets the name for the gmsh mesh file. if no name is given a name with extension "msh" is generated.
453 \end{methoddesc}
454
455 \begin{methoddesc}[Design]{getMeshFileName}{}
456 returns the name of the file for the gmsh msh
457 \end{methoddesc}
458
459
460 \begin{methoddesc}[Design]{addItems}{*items}
461 adds the tuple of var{items}. An item can be any primitive or a \class{PropertySet}.
462 \warning{If a \PropertySet is added as an item added object that are not
463 part of a \PropertySet are not considered in the messing.
464 }
465
466 \end{methoddesc}
467
468 \begin{methoddesc}[Design]{getItems}{}
469 returns a list of the items
470 \end{methoddesc}
471
472 \begin{methoddesc}[Design]{clearItems}{}
473 resets the items in design
474 \end{methoddesc}
475
476 \begin{methoddesc}[Design]{getMeshHandler}{}
477 returns a handle to the mesh. The call of this method generates the mesh from the geometry and
478 returns a mechanism to access the mesh data. In the current implementation this
479 method returns a file name for a gmsh file containing the mesh data.
480 \end{methoddesc}
481
482 \begin{methoddesc}[Design]{getScriptString}{}
483 returns the gmsh script to generate the mesh as a string.
484 \end{methoddesc}
485
486 \begin{methoddesc}[Design]{getCommandString}{}
487 returns the gmsh command used to generate the mesh as string.
488 \end{methoddesc}
489
490 \begin{methoddesc}[Design]{setOptions}{\optional{algorithm=None, \optional{ optimize_quality=True,\optional{ smoothing=1}}}}
491 sets options for the mesh generator. \var{algorithm} sets the algorithm to be used.
492 The algorithm needs to be \var{Design.DELAUNAY}
493 \var{Design.TETGEN}
494 or \var{Design.NETGEN}. By default \var{Design.DELAUNAY} is used. \var{optimize_quality}=\True invokes an optimization of the mesh quality. \var{smoothing} sets the number of smoothing steps to be applied to the mesh.
495 \end{methoddesc}
496
497 \begin{methoddesc}[Design]{getTagMap}{}
498 returns a \class{TagMap} to map the name \class{PropertySet} in the class to tag numbers generated by gmsh.
499 \end{methoddesc}

  ViewVC Help
Powered by ViewVC 1.1.26