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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1388 - (hide annotations)
Fri Jan 11 07:45:58 2008 UTC (11 years, 8 months ago) by trankine
File MIME type: application/x-tex
File size: 14007 byte(s)
And get the *(&(*&(* name right
1 ksteube 1318 \chapter{The Module \pycad} \label{PYCAD CHAP}
2 gross 993
3 gross 999
4     \section{Introduction}
5    
6 ksteube 1066 \pycad provides a simple way to build a mesh for your finite element
7     simulation. You begin by building what we call a {\it Design} using
8     primitive geometric objects, and then to go on to build a mesh from
9     the {\it Design}. The final step of generating the mesh from a {\it
10     Design} uses freely available mesh generation software, such as \gmshextern.
11 gross 999
12 ksteube 1066 A {\it Design} is built by defining points, which are used to specify
13     the corners of geometric objects and the vertices of curves. Using
14     points you construct more interesting objects such as lines,
15     rectangles, and arcs. By adding many of these objects into what we
16     call a {\it Design}, you can build meshes for arbitrarily complex 2-D
17     and 3-D structures.
18    
19     The example included below shows how to use {\it pycad} to create a 2-D mesh
20     in the shape of a trapezoid with a cutout area.
21    
22     \begin{python}
23     from esys.pycad import *
24     from esys.pycad.gmsh import Design
25     from esys.finley import MakeDomain
26    
27     # A trapezoid
28     p0=Point(0.0, 0.0, 0.0)
29     p1=Point(1.0, 0.0, 0.0)
30     p2=Point(1.0, 0.5, 0.0)
31     p3=Point(0.0, 1.0, 0.0)
32     l01=Line(p0, p1)
33     l12=Line(p1, p2)
34     l23=Line(p2, p3)
35     l30=Line(p3, p0)
36     c=CurveLoop(l01, l12, l23, l30)
37    
38     # A small triangular cutout
39     x0=Point(0.1, 0.1, 0.0)
40     x1=Point(0.5, 0.1, 0.0)
41     x2=Point(0.5, 0.2, 0.0)
42     x01=Line(x0, x1)
43     x12=Line(x1, x2)
44     x20=Line(x2, x0)
45     cutout=CurveLoop(x01, x12, x20)
46    
47     # Create the surface with cutout
48     s=PlaneSurface(c, holes=[cutout])
49    
50     # Create a Design which can make the mesh
51     d=Design(dim=2, element_size=0.05)
52    
53     # Add the trapezoid with cutout
54     d.addItems(s)
55    
56     # Create the geometry, mesh and Escript domain
57     d.setScriptFileName("trapezoid.geo")
58     d.setMeshFileName("trapezoid.msh")
59     domain=MakeDomain(d, integrationOrder=-1, reducedIntegrationOrder=-1, optimizeLabeling=True)
60    
61     # Create a file that can be read back in to python with mesh=ReadMesh(fileName)
62     domain.write("trapezoid.fly")
63     \end{python}
64    
65     This example is included with the software in
66     \code{pycad/examples/trapezoid.py}. If you have gmsh installed you can
67     run the example and view the geometry and mesh with:
68    
69     \begin{python}
70     python trapezoid.py
71     gmsh trapezoid.geo
72     gmsh trapezoid.msh
73     \end{python}
74    
75     A \code{CurveLoop} is used to connect several lines into a single curve.
76     It is used in the example above to create the trapezoidal outline for the grid
77     and also for the triangular cutout area.
78     You can use any number of lines when creating a \code{CurveLoop}, but
79     the end of one line must be identical to the start of the next.
80    
81     Sometimes you might see us write \code{-c} where \code{c} is a
82     \code{CurveLoop}. This is the reverse curve of the curve \code{c}.
83     It is identical to the original except that its points are traversed
84     in the opposite order. This may make it easier to connect two curves
85     in a \code{CurveLoop}.
86    
87     The example python script above calls both
88     \code{d.setScriptFileName()} and \code{d.setMeshFileName()}. You need
89     only call these if you wish to save the gmsh geometry and mesh files.
90    
91     Note that the underlying mesh generation software will not accept all
92     the geometries you can create with {\it pycad}. For example, {\it
93     pycad} will happily allow you to create a 2-D {\it Design} that is a
94     closed loop with some additional points or lines lying outside of the
95     enclosed area, but gmsh will fail to create a mesh for it.
96    
97    
98    
99    
100    
101    
102 gross 999 \section{\pycad Classes}
103     \declaremodule{extension}{esys.pycad}
104 gross 993 \modulesynopsis{Python geometry description and meshing interface}
105    
106 gross 999 \subsection{Primitives}
107 gross 993
108 ksteube 1066 Some of the most commonly-used objects in {\it pycad} are listed here. For a more complete
109     list see the full API documentation.
110 gross 999
111 ksteube 1066 \begin{classdesc}{Point}{x1, x2, x3}
112     Create a point with from coordinates.
113 gross 999 \end{classdesc}
114    
115 ksteube 1066 \begin{classdesc}{Line}{point1, point2}
116     Create a line with between starting and ending points.
117     \end{classdesc}
118 gross 999
119 ksteube 1066 \begin{classdesc}{Curve}{point1, point2, ...}
120     Create a \code{Curve}, which is simply a list of points.
121 gross 999 \end{classdesc}
122    
123 ksteube 1066 \begin{classdesc}{Spline}{curve}
124     Interpret a \code{Curve} using a spline.
125     \end{classdesc}
126 gross 999
127 ksteube 1066 \begin{classdesc}{BSpline}{curve}
128     Interpret a \code{Curve} using a b-spline.
129 gross 999 \end{classdesc}
130    
131 ksteube 1066 \begin{classdesc}{BezierCurve}{curve}
132     Interpret a \code{Curve} using a Bezier curve.
133     \end{classdesc}
134 gross 999
135 ksteube 1066 \begin{classdesc}{CurveLoop}{list}
136     Create a closed \code{Curve} connecting the lines and/or points given in the \code{list}.
137 gross 999 \end{classdesc}
138    
139 ksteube 1066 \begin{classdesc}{Arc}{center_point, start_point, end_point}
140     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.
141     \end{classdesc}
142    
143     \begin{classdesc}{PlaneSurface}{loop, \optional{holes=[list]}}
144     Create a surface for a 2-D mesh, which may have one or more holes.
145     \end{classdesc}
146    
147     \begin{classdesc}{RuledSurface}{list}
148     Create a surface that can be interpolated using transfinite interpolation.
149     \end{classdesc}
150    
151     \begin{classdesc}{SurfaceLoop}{list}
152     Create a loop of 2D primitives, which defines the shell of a volume.
153     \end{classdesc}
154    
155     \begin{classdesc}{Volume}{loop, \optional{holes=[list]}}
156     Create a volume for a 3-D mesh given a SurfaceLoop, which may have one or more holes.
157     \end{classdesc}
158    
159     \begin{classdesc}{PropertySet}{list}
160     Create a PropertySet given a list of 1-D, 2-D or 3-D items. See the section on Properties below for more information.
161     \end{classdesc}
162    
163 gross 999 %============================================================================================================
164     \subsection{Transformations}
165    
166 ksteube 1066 Sometimes it's convenient to create an object and then make copies at
167     different orientations and in different sizes. Transformations are
168     used to move geometrical objects in the 3-dimensional space and to
169     resize them.
170 gross 999
171     \begin{classdesc}{Translation}{\optional{b=[0,0,0]}}
172     defines a translation $x \to x+b$. \var{b} can be any object that can be converted
173     into a \numarray object of shape $(3,)$.
174     \end{classdesc}
175    
176     \begin{classdesc}{Rotatation}{\optional{axis=[1,1,1], \optional{ point = [0,0,0], \optional{angle=0*RAD} } } }
177     defines a rotation by \var{angle} around axis through point \var{point} and direction \var{axis}.
178     \var{axis} and \var{point} can be any object that can be converted
179     into a \numarray object of shape $(3,)$.
180     \var{axis} does not have to be normalized but must have positive length. The right hand rule~\cite{RIGHTHANDRULE}
181     applies.
182     \end{classdesc}
183    
184    
185     \begin{classdesc}{Dilation}{\optional{factor=1., \optional{center=[0,0,0]}}}
186     defines a dilation by the expansion/contraction \var{factor} with
187     \var{center} as the dilation center.
188     \var{center} can be any object that can be converted
189     into a \numarray object of shape $(3,)$.
190     \end{classdesc}
191    
192     \begin{classdesc}{Reflection}{\optional{normal=[1,1,1], \optional{offset=0}}}
193     defines a reflection on a plane defined in normal form $n^t x = d$
194     where $n$ is the surface normal \var{normal} and $d$ is the plane \var{offset}.
195     \var{normal} can be any object that can be converted
196     into a \numarray object of shape $(3,)$.
197     \var{normal} does not have to be normalized but must have positive length.
198     \end{classdesc}
199    
200 ksteube 1066 \begin{datadesc}{DEG}
201     A constant to convert from degrees to an internal angle representation in radians. For instance use \code{90*DEG} for $90$ degrees.
202     \end{datadesc}
203    
204 gross 999 \subsection{Properties}
205    
206 ksteube 1066 If you are building a larger geometry you may find it convenient to
207     create it in smaller pieces and then assemble them into the whole.
208     Property sets make this easy, and they allow you to name the smaller
209     pieces for convenience.
210 gross 999
211 ksteube 1066 Property sets are used to bundle a set of geometrical objects in a
212     group. The group is identified by a name. Typically a property set
213     is used to mark subregions with share the same material properties or
214     to mark portions of the boundary. For efficiency, the \Design class
215     object assigns a integer to each of its property sets, a so-called tag
216     \index{tag}. The appropriate tag is attached to the elements at
217     generation time.
218 gross 1044
219 ksteube 1066 See the file \code{pycad/examples/quad.py} for an example using a {\it PropertySet}.
220    
221    
222 gross 999 \begin{classdesc}{PropertySet}{name,*items}
223     defines a group geometrical objects which can be accessed through a \var{name}
224     The objects in the tuple \var{items} mast all be \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD objects.
225     \end{classdesc}
226    
227    
228     \begin{methoddesc}[PropertySet]{getManifoldClass}{}
229     returns the manifold class \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD expected from the items
230     in the property set.
231     \end{methoddesc}
232    
233     \begin{methoddesc}[PropertySet]{getDim}{}
234     returns the spatial dimension of the items
235     in the property set.
236     \end{methoddesc}
237    
238     \begin{methoddesc}[PropertySet]{getName}{}
239     returns the name of the set
240     \end{methoddesc}
241    
242     \begin{methoddesc}[PropertySet]{setName}{name}
243     sets the name. This name should be unique within a \Design.
244     \end{methoddesc}
245    
246     \begin{methoddesc}[PropertySet]{addItem}{*items}
247     adds a tuple of items. They need to be objects of class \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD.
248     \end{methoddesc}
249    
250     \begin{methoddesc}[PropertySet]{getItems}{}
251     returns the list of items
252     \end{methoddesc}
253    
254     \begin{methoddesc}[PropertySet]{clearItems}{}
255     clears the list of items
256     \end{methoddesc}
257    
258     \begin{methoddesc}[PropertySet]{getTag}{}
259     returns the tag used for this property set
260     \end{methoddesc}
261    
262 ksteube 1066 \section{Interface to the mesh generation software}
263 gross 999 \declaremodule{extension}{esys.pycad.gmsh}
264     \modulesynopsis{Python geometry description and meshing interface}
265    
266 ksteube 1066 The class and methods described here provide an interface to the mesh
267     generation software, which is currently gmsh. This interface could be
268     adopted to triangle or another mesh generation package if this is
269     deemed to be desireable in the future.
270    
271 gross 999 \begin{classdesc}{Design}{
272     \optional{dim=3, \optional{element_size=1., \optional{order=1, \optional{keep_files=False}}}}}
273     The \class{Design} describes the geometry defined by primitives to be meshed.
274     The \var{dim} specifies the spatial dimension. The argument \var{element_size} defines the global
275     element size which is multiplied by the local scale to set the element size at each \Point.
276     The argument \var{order} defines the element order to be used. If \var{keep_files} is set to
277     \True temporary files a kept otherwise they are removed when the instance of the class is deleted.
278     \end{classdesc}
279    
280    
281     \begin{methoddesc}[Design]{setDim}{\optional{dim=3}}
282     sets the spatial dimension which needs to be $1$, $2$ or $3$.
283     \end{methoddesc}
284    
285     \begin{methoddesc}[Design]{getDim}{}
286     returns the spatial dimension.
287     \end{methoddesc}
288    
289     \begin{methoddesc}[Design]{setElementOrder}{\optional{order=1}}
290     sets the element order which needs to be $1$ or $2$.
291     \end{methoddesc}
292    
293     \begin{methoddesc}[Design]{getElementOrder}{}
294     returns the element order.
295     \end{methoddesc}
296    
297    
298     \begin{methoddesc}[Design]{setElementSize}{\optional{element_size=1}}
299     set the global element size. The local element size at a point is defined as
300     the global element size multipied by the local scale. The element size must be positive.
301     \end{methoddesc}
302    
303    
304     \begin{methoddesc}[Design]{getElementSize}{}
305     returns the global element size.
306     \end{methoddesc}
307    
308     \begin{memberdesc}[Design]{DELAUNAY}
309 ksteube 1066 the gmsh Delauny triangulator.
310 gross 999 \end{memberdesc}
311    
312     \begin{memberdesc}[Design]{TETGEN}
313     the TetGen~\cite{TETGEN} triangulator.
314     \end{memberdesc}
315    
316     \begin{memberdesc}[Design]{TETGEN}
317     the NETGEN~\cite{NETGEN} triangulator.
318     \end{memberdesc}
319    
320     \begin{methoddesc}[Design]{setKeepFilesOn}{}
321     work files are kept at the end of the generation.
322     \end{methoddesc}
323    
324     \begin{methoddesc}[Design]{setKeepFilesOff}{}
325     work files are deleted at the end of the generation.
326     \end{methoddesc}
327    
328     \begin{methoddesc}[Design]{keepFiles}{}
329     returns \True if work files are kept. Otherwise \False is returned.
330     \end{methoddesc}
331    
332     \begin{methoddesc}[Design]{setScriptFileName}{\optional{name=None}}
333 ksteube 1066 set the filename for the gmsh input script. if no name is given a name with extension "geo" is generated.
334 gross 999 \end{methoddesc}
335    
336     \begin{methoddesc}[Design]{getScriptFileName}{}
337 ksteube 1066 returns the name of the file for the gmsh script.
338 gross 999 \end{methoddesc}
339    
340    
341     \begin{methoddesc}[Design]{setMeshFileName}{\optional{name=None}}
342 ksteube 1066 sets the name for the gmsh mesh file. if no name is given a name with extension "msh" is generated.
343 gross 999 \end{methoddesc}
344    
345     \begin{methoddesc}[Design]{getMeshFileName}{}
346     returns the name of the file for the gmsh msh
347     \end{methoddesc}
348    
349    
350     \begin{methoddesc}[Design]{addItems}{*items}
351     adds the tuple of var{items}. An item can be any primitive or a \class{PropertySet}.
352     \warning{If a \PropertySet is added as an item added object that are not
353     part of a \PropertySet are not considered in the messing.
354     }
355    
356     \end{methoddesc}
357    
358     \begin{methoddesc}[Design]{getItems}{}
359     returns a list of the items
360     \end{methoddesc}
361    
362     \begin{methoddesc}[Design]{clearItems}{}
363     resets the items in design
364     \end{methoddesc}
365    
366     \begin{methoddesc}[Design]{getMeshHandler}{}
367     returns a handle to the mesh. The call of this method generates the mesh from the geometry and
368     returns a mechnism to access the mesh data. In the current implementation this
369 ksteube 1066 method returns a file name for a gmsh file containing the mesh data.
370 gross 999 \end{methoddesc}
371    
372     \begin{methoddesc}[Design]{getScriptString}{}
373 ksteube 1066 returns the gmsh script to generate the mesh as a string.
374 gross 999 \end{methoddesc}
375    
376     \begin{methoddesc}[Design]{getCommandString}{}
377 ksteube 1066 returns the gmsh command used to generate the mesh as string.
378 gross 999 \end{methoddesc}
379    
380     \begin{methoddesc}[Design]{setOptions}{\optional{algorithm=None, \optional{ optimize_quality=True,\optional{ smoothing=1}}}}
381     sets options for the mesh generator. \var{algorithm} sets the algorithm to be used.
382     The algorithm needs to be \var{Design.DELAUNAY}
383     \var{Design.TETGEN}
384     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.
385     \end{methoddesc}
386    
387     \begin{methoddesc}[Design]{getTagMap}{}
388 ksteube 1066 returns a \class{TagMap} to map the name \class{PropertySet} in the class to tag numbers generated by gmsh.
389 gross 999 \end{methoddesc}

  ViewVC Help
Powered by ViewVC 1.1.26