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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 999 by gross, Tue Feb 27 08:12:37 2007 UTC revision 1318 by ksteube, Wed Sep 26 04:39:14 2007 UTC
# Line 1  Line 1 
1  \chapter{The module \pycad}  \chapter{The Module \pycad} \label{PYCAD CHAP}
 \label{PYCAD CHAP}  
   
2    
3    
4  \section{Introduction}  \section{Introduction}
5    
6    \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    
12    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  \section{\pycad Classes}  \section{\pycad Classes}
103  \declaremodule{extension}{esys.pycad}  \declaremodule{extension}{esys.pycad}
# Line 12  Line 105 
105    
106  \subsection{Primitives}  \subsection{Primitives}
107    
108  \begin{classdesc}{Point}{}  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    
111    \begin{classdesc}{Point}{x1, x2, x3}
112    Create a point with from coordinates.
113  \end{classdesc}  \end{classdesc}
114    
115  \begin{classdesc}{Manifold1D}{}  \begin{classdesc}{Line}{point1, point2}
116    Create a line with between starting and ending points.
117    \end{classdesc}
118    
119    \begin{classdesc}{Curve}{point1, point2, ...}
120    Create a \code{Curve}, which is simply a list of points.
121  \end{classdesc}  \end{classdesc}
122    
123  \begin{classdesc}{Manifold2D}{}  \begin{classdesc}{Spline}{curve}
124    Interpret a \code{Curve} using a spline.
125    \end{classdesc}
126    
127    \begin{classdesc}{BSpline}{curve}
128    Interpret a \code{Curve} using a b-spline.
129  \end{classdesc}  \end{classdesc}
130    
131  \begin{classdesc}{Manifold3D}{}  \begin{classdesc}{BezierCurve}{curve}
132    Interpret a \code{Curve} using a Bezier curve.
133    \end{classdesc}
134    
135    \begin{classdesc}{CurveLoop}{list}
136    Create a closed \code{Curve} connecting the lines and/or points given in the \code{list}.
137  \end{classdesc}  \end{classdesc}
138    
139  %============================================================================================================  \begin{classdesc}{Arc}{center_point, start_point, end_point}
140  \subsection{Transformations}  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  Transformations are used to move geometrical objects in the 3-dimensional space:  \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{datadesc}{DEG}  \begin{classdesc}{RuledSurface}{list}
148  The unit of degree. For instance use \code{90*DEG} for $90$ degrees.  Create a surface that can be interpolated using transfinite interpolation.
149  \end{datadesc}  \end{classdesc}
150    
151  \begin{datadesc}{RAD}  \begin{classdesc}{SurfaceLoop}{list}
152  The unit of radiant. For instance use \code{math.pi*RAD} for $180$ degrees.  Create a loop of 2D primitives, which defines the shell of a volume.
153  \end{datadesc}  \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    %============================================================================================================
164    \subsection{Transformations}
165    
166    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    
171  \begin{classdesc}{Translation}{\optional{b=[0,0,0]}}  \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  defines a translation $x \to x+b$. \var{b} can be any object that can be converted
# Line 70  into a \numarray object of shape $(3,)$. Line 197  into a \numarray object of shape $(3,)$.
197  \var{normal} does not have to be normalized but must have positive length.  \var{normal} does not have to be normalized but must have positive length.
198  \end{classdesc}  \end{classdesc}
199    
200    \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  \subsection{Properties}  \subsection{Properties}
205    
206  Property sets are used to bundle a set of geometrical objects in a group. The group  If you are building a larger geometry you may find it convenient to
207  is identified by a name. Typically a property set is used to mark  create it in smaller pieces and then assemble them into the whole.
208  subregions with share the same material properties or to mark portions of the boundary.  Property sets make this easy, and they allow you to name the smaller
209  For efficiency, the \Design class object assigns a integer to each of its property sets,  pieces for convenience.
210  a so-called tag \index{tag}. The appropriate tag is attached to the elements at generation time.  
211  The \TagMap generated by the \Design allows mapping the a name onto the corresponding tag.  Property sets are used to bundle a set of geometrical objects in a
212  In order to avoid ambiguity it is recommended to have unique names of property sets within a \Design.  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    
219    See the file \code{pycad/examples/quad.py} for an example using a {\it PropertySet}.
220    
221    
222  \begin{classdesc}{PropertySet}{name,*items}  \begin{classdesc}{PropertySet}{name,*items}
223  defines a group geometrical objects which can be accessed through a \var{name}  defines a group geometrical objects which can be accessed through a \var{name}
# Line 121  clears the list of items Line 259  clears the list of items
259  returns the tag used for this property set  returns the tag used for this property set
260  \end{methoddesc}  \end{methoddesc}
261    
262  \subsection{Accessing \PropertySet Names}  \section{Interface to the mesh generation software}
 During mesh generation the \PropertySet objects are not identified by their name but an integer tag (mainly to provide  
 a quicker indexing mechanism). The \TagMap which is generated by a \Design class object at mesh generation time  
 provides an mechanism to map the property set names onto tags and vice versa.  
 The following example illustrates the mechanis: In this case, the \TagMap \var{tm}  
 maps the names \var{x}, \var{a} onto the tags \var{5} and \var{4} and the tag \var{4}, respectively:    
 \begin{python}  
 tm=TagMap({5 : "x" })  
 tm.setMap(a=1,x=4)  
 print tm.getTags("a"), tm.getTags("x")  
 \end{python}  
 Th output is  
 \begin{python}  
    [ 1 ], [ 5, 4 ]  
 \end{python}  
   
 \begin{python}  
 d=Design()  
 d.add(PropertySet(name="a"))  
 print d.getTagMap().getTags("a")  
 \end{python}  
   
 \begin{python}  
 d=Design()  
 d.add(PropertySet(name="a"))  
 domain=esys.finley.  
 print d.getTagMap().getTags("a")  
 \end{python}  
   
 \begin{classdesc}{TagMap}{\optional{map = \{\} }}  
 defines a mapping between names (str) and tags (int).  
 The dictionary \var{map} sets an initial mapping from tag to name.  
 \end{classdesc}  
   
 \begin{methoddesc}[TagMap]{setMap}{**kwargs}  
 adds a map from names to tags using keyword arguments. For instance  
 \var{top=1234} assigns the tag \var{123} to name \var{top}. The tag has to be integer.  
 If a tag has been assigned to a name before the mapping will be overwritten.  
 Notice that a single name can be assigned to different tags.  
 \end{methoddesc}  
   
 \begin{methoddesc}[TagMap]{getTags}{\optional{name=None}}  
 returns a list of the tags assigned to \var{name}. If \var{name} is not present  
 a list of tags is returned.  
 \end{methoddesc}  
   
  \begin{methoddesc}[TagMap]{getName}{\optional{tag=None}}  
 returns a the name assigned to \var{name}. If \var{tag} is not present  
 a list of all names is returned.  
 \end{methoddesc}  
   
   
 \begin{methoddesc}[TagMap]{getMapping}{}  
 returns a dictionary where the tags define the keys and the values the corresponding names.  
 \end{methoddesc}  
   
 \begin{methoddesc}[TagMap]{map}{\optional{default=0}, \optional{**kwargs}}  
 returns a dictionary where the keys are the tags and the values are the corresponding values assigned  
 to the tag via the keyword arguments \var{**kwargs}. The value of \var{default} is used for tags  
 which map onto name with unspecified values.  
   
 The following example demonstrate the usage:  
 \begin{python}  
 tm=TagMap(x=5)  
 tm.setMap(a=1,x=4,z=10)  
 print tm.map(default = "unknown", x="john",  a="peter")  
 \end{python}    
 The output is  
 \begin{python}  
 { 5 : "john", 4: "john", 1 : "peter", 10 : "unknown" }  
 \end{python}    
 \end{methoddesc}  
   
 \begin{methoddesc}[TagMap]{insert}{data,\optional{default=0, \optional{**kwargs}}}  
 inserts the values assigned to name via the keyword arguments \var{**kwargs}  
 into the \Data object \var{Data}. The value \var{default} is used for names with no given value.  
 \end{methoddesc}  
   
 \begin{methoddesc}[TagMap]{writeXML}{\optional{iostream=None}}  
 writes an XML serialization into the \var{iostream} or if not present returns the XML representation  
 as a string.  
 \end{methoddesc}  
   
 \begin{methoddesc}[TagMap]{fillFromXML}{iostream}  
 uses XML data \var{iostream} defining an iostream or string. This method is the  
 inverse method of \var{writeXML}.  
   
 The following example demonstrates the usage:  
 \begin{python}  
 tm=TagMap(x=5)  
 tm.setMap(a=1,x=4,z=10)  
 tm.writeXML(open("tag_map.xml", "w"))  
 tm2=TagMap()  
 tm2.fillFromXML(open("tag_map.xml", "r"))  
 \end{python}    
 \end{methoddesc}          
   
   
   
 \section{Interface to \gmshextern}  
263  \declaremodule{extension}{esys.pycad.gmsh}  \declaremodule{extension}{esys.pycad.gmsh}
264  \modulesynopsis{Python geometry description and meshing interface}  \modulesynopsis{Python geometry description and meshing interface}
265    
266    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  \begin{classdesc}{Design}{  \begin{classdesc}{Design}{
272  \optional{dim=3, \optional{element_size=1., \optional{order=1, \optional{keep_files=False}}}}}  \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.  The \class{Design} describes the geometry defined by primitives to be meshed.
# Line 262  returns the global element size. Line 306  returns the global element size.
306  \end{methoddesc}  \end{methoddesc}
307    
308  \begin{memberdesc}[Design]{DELAUNAY}  \begin{memberdesc}[Design]{DELAUNAY}
309  the \gmshextern Delauny triangulator.  the gmsh Delauny triangulator.
310  \end{memberdesc}  \end{memberdesc}
311    
312  \begin{memberdesc}[Design]{TETGEN}  \begin{memberdesc}[Design]{TETGEN}
# Line 286  returns \True if work files are kept. Ot Line 330  returns \True if work files are kept. Ot
330  \end{methoddesc}  \end{methoddesc}
331    
332  \begin{methoddesc}[Design]{setScriptFileName}{\optional{name=None}}  \begin{methoddesc}[Design]{setScriptFileName}{\optional{name=None}}
333  set the filename for the \gmshextern input script. if no name is given a name with extension "geo" is generated.  set the filename for the gmsh input script. if no name is given a name with extension "geo" is generated.
334  \end{methoddesc}  \end{methoddesc}
335    
336  \begin{methoddesc}[Design]{getScriptFileName}{}  \begin{methoddesc}[Design]{getScriptFileName}{}
337  returns the name of the file for the \gmshextern script.  returns the name of the file for the gmsh script.
338  \end{methoddesc}  \end{methoddesc}
339    
340    
341  \begin{methoddesc}[Design]{setMeshFileName}{\optional{name=None}}  \begin{methoddesc}[Design]{setMeshFileName}{\optional{name=None}}
342  sets the name for the \gmshextern  mesh file. if no name is given a name with extension "msh" is generated.  sets the name for the gmsh  mesh file. if no name is given a name with extension "msh" is generated.
343  \end{methoddesc}  \end{methoddesc}
344    
345  \begin{methoddesc}[Design]{getMeshFileName}{}  \begin{methoddesc}[Design]{getMeshFileName}{}
# Line 322  resets the items in design Line 366  resets the items in design
366  \begin{methoddesc}[Design]{getMeshHandler}{}  \begin{methoddesc}[Design]{getMeshHandler}{}
367  returns a handle to the mesh. The call of this method generates the mesh from the geometry and  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  returns a mechnism to access the mesh data. In the current implementation this
369  is this method returns a file name for a \gmshextern file containing the mesh data but this may change in  method returns a file name for a gmsh file containing the mesh data.
 later versions.  
370  \end{methoddesc}  \end{methoddesc}
371    
372  \begin{methoddesc}[Design]{getScriptString}{}  \begin{methoddesc}[Design]{getScriptString}{}
373  returns the \gmshextern script to generate the mesh as string.  returns the gmsh script to generate the mesh as a string.
374  \end{methoddesc}  \end{methoddesc}
375    
376  \begin{methoddesc}[Design]{getCommandString}{}  \begin{methoddesc}[Design]{getCommandString}{}
377  returns the \gmshextern command used to generate the mesh as string..  returns the gmsh command used to generate the mesh as string.
378  \end{methoddesc}  \end{methoddesc}
379    
380  \begin{methoddesc}[Design]{setOptions}{\optional{algorithm=None, \optional{ optimize_quality=True,\optional{ smoothing=1}}}}  \begin{methoddesc}[Design]{setOptions}{\optional{algorithm=None, \optional{ optimize_quality=True,\optional{ smoothing=1}}}}
# Line 342  or \var{Design.NETGEN}. By default \var{ Line 385  or \var{Design.NETGEN}. By default \var{
385  \end{methoddesc}  \end{methoddesc}
386    
387  \begin{methoddesc}[Design]{getTagMap}{}  \begin{methoddesc}[Design]{getTagMap}{}
388  returns a \class{TagMap} to map the name \class{PropertySet} in the class to tag numbers generated by \gmshextern.  returns a \class{TagMap} to map the name \class{PropertySet} in the class to tag numbers generated by gmsh.
389  \end{methoddesc}  \end{methoddesc}
Legend:
Removed from v.999  
changed lines
  Added in v.1318
  ViewVC Help
Powered by ViewVC 1.1.26