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

revision 3323 by gross, Thu Oct 28 05:02:41 2010 UTC revision 3324 by caltinay, Thu Oct 28 23:43:09 2010 UTC
# Line 16  Line 16
16  \section{Introduction}  \section{Introduction}
17
18  \pycad provides a simple way to build a mesh for your finite element  \pycad provides a simple way to build a mesh for your finite element
19  simulation.  You begin by building what we call a \class{Design} using  simulation. You begin by building what we call a \class{Design} using
20  primitive geometric objects, and then to go on to build a mesh from  primitive geometric objects, and then go on to build a mesh from this.
21  this.  The final step of generating the mesh from a \class{Design}  The final step of generating the mesh from a \class{Design} uses freely
22  uses freely available mesh generation software, such as \gmshextern.  available mesh generation software, such as \gmshextern.
23
24  A \class{Design} is built by defining points, which are used to specify  A \class{Design} is built by defining points, which are used to specify
25  the corners of geometric objects and the vertices of curves.  Using  the corners of geometric objects and the vertices of curves. Using
26  points you construct more interesting objects such as lines,  points you construct more interesting objects such as lines,
27  rectangles, and arcs.  By adding many of these objects into what we  rectangles, and arcs. By adding many of these objects into a \class{Design},
28  call a \class{Design}, you can build meshes for arbitrarily complex 2-D  you can build meshes for arbitrarily complex 2-D and 3-D structures.
and 3-D structures.
29
30  \section{The Unit Square}  \section{The Unit Square}
31  So the simplest geometry is the unit square. First we generate the  The simplest geometry is the unit square. First we generate the corner points
corner points
32  \begin{python}  \begin{python}
33  from esys.pycad import *    from esys.pycad import *
34  p0=Point(0.,0.,0.)    p0=Point(0.,0.,0.)
35  p1=Point(1.,0.,0.)    p1=Point(1.,0.,0.)
36  p2=Point(1.,1.,0.)    p2=Point(1.,1.,0.)
37  p3=Point(0.,1.,0.)    p3=Point(0.,1.,0.)
38  \end{python}  \end{python}
39  which are then linked to define the edges of the square  which are then linked to define the edges of the square
40  \begin{python}  \begin{python}
41  l01=Line(p0,p1)    l01=Line(p0,p1)
42  l12=Line(p1,p2)    l12=Line(p1,p2)
43  l23=Line(p2,p3)    l23=Line(p2,p3)
44  l30=Line(p3,p0)    l30=Line(p3,p0)
45  \end{python}  \end{python}
46  The lines are put together to form a loop  The lines are put together to form a loop
47  \begin{python}  \begin{python}
48  c=CurveLoop(l01,l12,l23,l30)    c=CurveLoop(l01,l12,l23,l30)
49  \end{python}  \end{python}
50  The orientation of the line defining the \class{CurveLoop} is important. It is assumed that the surrounded  The orientation of the line defining the \class{CurveLoop} is important.
51  area is to the left when moving along the lines from their starting points towards the end points. Moreover,  It is assumed that the surrounded area is to the left when moving along the
52  the line need to form a closed loop.  lines from their starting points towards the end points.
53    Moreover, the line needs to form a closed loop.
54  We use the \class{CurveLoop} to define a surface  We now use the \class{CurveLoop} to define a surface
55  \begin{python}  \begin{python}
56  s=PlaneSurface(c)    s=PlaneSurface(c)
57  \end{python}  \end{python}
58  Notice there is difference between the \class{CurveLoop} defining the boundary  Note that there is a difference between the \class{CurveLoop}, which defines
59  of the surface and the actually surface \class{PlaneSurface}. This difference becomes clearer in the next example with a hole. The direction of the lines is important.  the boundary of the surface, and the actual surface \class{PlaneSurface}.
60  New we are ready to define the geometry which described by an instance of \class{Design} class:  This difference becomes clearer in the next example with a hole.
61    Now we are ready to define the geometry which is described by an instance of
62    the \class{Design} class:
63  \begin{python}  \begin{python}
64  d=Design(dim=2,element_size=0.05)    d=Design(dim=2,element_size=0.05)
65  \end{python}  \end{python}
66  Here we use the two dimensional domain with a local element size in the finite element mesh of $0.05$.  Here we use the two-dimensional domain with a local element size in the finite
67    element mesh of $0.05$.
68  We then add the surface \code{s} to the geometry  We then add the surface \code{s} to the geometry
69  \begin{python}  \begin{python}
71  \end{python}  \end{python}
72  This will automatically import all items used to construct \code{s} into the \class{Design} \code{d}.  This will automatically import all items used to construct \code{s} into the
73  Now we are ready to construct a \finley FEM mesh and then write it to the file \file{quad.fly}:  \class{Design} \code{d}.
74  \begin{python}  Now we are ready to construct a \finley FEM mesh and then write it to the file
75  from esys.finley import MakeDomain  \file{quad.fly}:
76  dom=MakeDomain(d)  \begin{python}
77  dom.write("quad.fly")    from esys.finley import MakeDomain
78  \end{python}    dom=MakeDomain(d)
79  In some cases it is useful to access the script used to generate the geometry. You can specify a specific name    dom.write("quad.fly")
80  for the script file. In our case we use  \end{python}
81  \begin{python}  In some cases it is useful to access the script used to generate the geometry.
82  d.setScriptFileName("quad.geo")  You can specify a specific name for the script file. In our case we use
83  \end{python}  \begin{python}
84  It is also useful to check error messages generated during the mesh generation process. \gmshextern writes    d.setScriptFileName("quad.geo")
85  messages to the \file{.gmsh-errors} in your home directory.  \end{python}
86    It is also useful to check error messages generated during the mesh generation
87  If we put everything together we get the script  process. \gmshextern writes messages to the file \file{.gmsh-errors} in your
88  \begin{python}  home directory.
89  from esys.pycad import *  Putting everything together we get the script
90  from esys.pycad.gmsh import Design  \begin{python}
91  from esys.finley import MakeDomain    from esys.pycad import *
92  p0=Point(0.,0.,0.)    from esys.pycad.gmsh import Design
93  p1=Point(1.,0.,0.)    from esys.finley import MakeDomain
94  p2=Point(1.,1.,0.)    p0=Point(0.,0.,0.)
95  p3=Point(0.,1.,0.)    p1=Point(1.,0.,0.)
96  l01=Line(p0,p1)    p2=Point(1.,1.,0.)
97  l12=Line(p1,p2)    p3=Point(0.,1.,0.)
98  l23=Line(p2,p3)    l01=Line(p0,p1)
99  l30=Line(p3,p0)    l12=Line(p1,p2)
100  c=CurveLoop(l01,l12,l23,l30)    l23=Line(p2,p3)
101  s=PlaneSurface(c)    l30=Line(p3,p0)
102  d=Design(dim=2,element_size=0.05)    c=CurveLoop(l01,l12,l23,l30)
107  d.addItems(pl1, pl2)    pl1=PropertySet("sides",l01,l23)
108  dom=MakeDomain(d)    pl2=PropertySet("top_and_bottom",l12,l30)
110  \end{python}    dom=MakeDomain(d)
111  This example is included with the software in    dom.write("quad.fly")
112  \file{quad.py} in the \ExampleDirectory.  \end{python}
113    This example is included with the software in \file{quad.py} in the
114  There are three extra statements which we have not discussed yet: By default the mesh used to subdivide  \ExampleDirectory.
115  the boundary are not written into the mesh file mainly to reduce the size of the data file. One need to explicitly add the lines to the  \Design which should be present in the mesh data. Here we additionally labeled the
116  lines on the top and the bottom with the name top_and_bottom and the lines on the left and right hand side  There are three extra statements which we have not discussed yet.
117  with the name sides using \class{PropertySet} objects. The labeling is convenient  By default the mesh used to subdivide the boundary is not written into the
118  when using tagging \index{tagging}, see Chapter~\ref{ESCRIPT CHAP}.  mesh file mainly to reduce the size of the data file.
119    One needs to explicitly add the lines to the \Design which should be present
120    in the mesh data. Here we additionally labeled the lines on the top and the
121    bottom with the name top_and_bottom and the lines on the left and right
122    hand side with the name sides using \class{PropertySet} objects.
123    The labeling is convenient when using tagging\index{tagging}, see \Chap{ESCRIPT CHAP}.
124
125  \begin{figure}  \begin{figure}
127  % \centerline{\includegraphics[width=\figwidth]{quad}}  \caption{Quadrilateral with mesh of triangles}
\caption{Trapozid with triangle Hole.}
129  \end{figure}  \end{figure}
130
131  If you have \gmshextern installed you can run the example and view the geometry and mesh with:  If you have \gmshextern installed you can run the example and view the
132  \begin{python}  geometry and mesh with:
133    \begin{verbatim}
137  \end{python}  \end{verbatim}
You can access error messages from \gmshextern in the \file{.gmsh-errors} in your home directory.
138  See Figure~\ref{fig:PYCAD 0} for a result.  See Figure~\ref{fig:PYCAD 0} for a result.
139
140  In most cases it is best practice to generate the mesh and to solve the mathematical  In most cases it is best practice to generate the mesh and solve the
141  model in to different scripts. In our example you can read the \finley mesh into your simulation  mathematical model in two separate scripts. In our example you can read the
142  code\footnote{\gmshextern files can be directly read using the \function{ReadGmsh}, see Chapter~\ref{CHAPTER ON FINLEY}} using  \finley mesh into your simulation code\footnote{\gmshextern files can be
143    directly read using \function{ReadGmsh}, see \Chap{CHAPTER ON FINLEY}} using
144  \begin{python}  \begin{python}
145  from finley import ReadMesh    from finley import ReadMesh
147  \end{python}  \end{python}
148  Note that the underlying mesh generation software will not accept all  Note that the underlying mesh generation software will not accept all
149  the geometries you can create.  For example, \pycad  the geometries you can create.  For example, \pycad will happily allow
150  will happily allow you to create a 2-D \class{Design} that is a  you to create a 2-D \class{Design} that is a closed loop with some
151  closed loop with some additional points or lines lying outside of the  additional points or lines lying outside of the enclosed area, but
152  enclosed area, but \gmshextern will fail to create a mesh for it.  \gmshextern will fail to create a mesh for it.

\begin{figure}
% \centerline{\includegraphics[width=\figwidth]{trap}}
\caption{Trapozid with triangle Hole.}
\end{figure}

153
154  \section{Holes}  \section{Holes}
155  The example included below shows how to use \pycad to create a 2-D mesh  The example included below shows how to use \pycad to create a 2-D mesh
156  in the shape of a trapezoid with a cut-out area, see  Figure~\ref{fig:PYCAD 1}:  in the shape of a trapezoid with a cut-out area as in Figure~\ref{fig:PYCAD 1}.
157
158  \begin{python}  \begin{python}
159  from esys.pycad import *    from esys.pycad import *
160  from esys.pycad.gmsh import Design    from esys.pycad.gmsh import Design
161  from esys.finley import MakeDomain    from esys.finley import MakeDomain
162
163  # A trapezoid    # A trapezoid
164  p0=Point(0.0, 0.0, 0.0)    p0=Point(0.0, 0.0, 0.0)
165  p1=Point(1.0, 0.0, 0.0)    p1=Point(1.0, 0.0, 0.0)
166  p2=Point(1.0, 0.5, 0.0)    p2=Point(1.0, 0.5, 0.0)
167  p3=Point(0.0, 1.0, 0.0)    p3=Point(0.0, 1.0, 0.0)
168  l01=Line(p0, p1)    l01=Line(p0, p1)
169  l12=Line(p1, p2)    l12=Line(p1, p2)
170  l23=Line(p2, p3)    l23=Line(p2, p3)
171  l30=Line(p3, p0)    l30=Line(p3, p0)
172  c=CurveLoop(l01, l12, l23, l30)    c=CurveLoop(l01, l12, l23, l30)
173
174  # A small triangular cutout    # A small triangular cutout
175  x0=Point(0.1, 0.1, 0.0)    x0=Point(0.1, 0.1, 0.0)
176  x1=Point(0.5, 0.1, 0.0)    x1=Point(0.5, 0.1, 0.0)
177  x2=Point(0.5, 0.2, 0.0)    x2=Point(0.5, 0.2, 0.0)
178  x01=Line(x0, x1)    x01=Line(x0, x1)
179  x12=Line(x1, x2)    x12=Line(x1, x2)
180  x20=Line(x2, x0)    x20=Line(x2, x0)
181  cutout=CurveLoop(x01, x12, x20)    cutout=CurveLoop(x01, x12, x20)
182
183  # Create the surface with cutout    # Create the surface with cutout
184  s=PlaneSurface(c, holes=[cutout])    s=PlaneSurface(c, holes=[cutout])
185
186  # Create a Design which can make the mesh    # Create a Design which can make the mesh
187  d=Design(dim=2, element_size=0.05)    d=Design(dim=2, element_size=0.05)
188
189  # Add the trapezoid with cutout    # Add the trapezoid with cutout
191
192  # Create the geometry, mesh and Escript domain    # Create the geometry, mesh and Escript domain
193  d.setScriptFileName("trapezoid.geo")    d.setScriptFileName("trapezoid.geo")
194  d.setMeshFileName("trapezoid.msh")    d.setMeshFileName("trapezoid.msh")
195  domain=MakeDomain(d)    domain=MakeDomain(d)
196  # write mesh to a finley file:    # write mesh to a finley file:
197  domain.write("trapezoid.fly")    domain.write("trapezoid.fly")
198  \end{python}  \end{python}
199  This example is included with the software in  This example is included with the software in \file{trapezoid.py} in the
200  \file{trapezoid.py} in the \ExampleDirectory.  \ExampleDirectory.
201
202    \begin{figure}
203    \centerline{\includegraphics{trapezoid}}
204    \caption{Trapezoid with triangular hole}
206    \end{figure}
207
208  A \code{CurveLoop} is used to connect several lines into a single curve.  A \code{CurveLoop} is used to connect several lines into a single curve.
209  It is used in the example above to create the trapezoidal outline for the grid  It is used in the example above to create the trapezoidal outline for the grid
210  and also for the triangular cutout area.  and also for the triangular cutout area.
211  You can use any number of lines when creating a \class{CurveLoop}, but  You can define any number of lines when creating a \class{CurveLoop}, but
212  the end of one line must be identical to the start of the next.  the end of one line must be identical to the start of the next.
213
214    \section{A 3D example}
215
216    In this section we discuss the definition of 3D geometries. As an example
217    consider the unit cube as shown in Figure~\ref{fig:PYCAD 2}.
218    First we generate the vertices of the cube:
219    \begin{python}
220      from esys.pycad import *
221      p0=Point(0.,0.,0.)
222      p1=Point(1.,0.,0.)
223      p2=Point(0.,1.,0.)
224      p3=Point(1.,1.,0.)
225      p4=Point(0.,0.,1.)
226      p5=Point(1.,0.,1.)
227      p6=Point(0.,1.,1.)
228      p7=Point(1.,1.,1.)
229    \end{python}
230
231    We connect the points to form the bottom and top surfaces of the cube:
232    \begin{python}
233      l01=Line(p0,p1)
234      l13=Line(p1,p3)
235      l32=Line(p3,p2)
236      l20=Line(p2,p0)
237      bottom=PlaneSurface(-CurveLoop(l01,l13,l32,l20))
238    \end{python}
239
240  \begin{figure}  \begin{figure}
241  % \centerline{\includegraphics[width=\figwidth]{brick}}  \centerline{\includegraphics{brick}}
242  \caption{Three dimensional Block.}  \caption{Three dimensional block}
244  \end{figure}  \end{figure}
245
246  \section{A 3D example}  Similar to the definition of a \code{CurvedLoop} the orientation of the
247  In this section we discuss the definition of 3D geometries. The example is the unit cube, see Figure~\ref{fig:PYCAD 2}. First we generate the vertices of the cube:  surfaces in a \code{SurfaceLoop} is relevant.
248  \begin{python}  In fact, the surface normal direction defined by the right-hand rule needs to
249  from esys.pycad import *  point outwards as indicated by the surface normals in Figure~\ref{fig:PYCAD 2}.
250  p0=Point(0.,0.,0.)  As the \code{bottom} face is directed upwards it is inserted with the minus
251  p1=Point(1.,0.,0.)  sign into the \code{SurfaceLoop} in order to adjust the orientation of the
252  p2=Point(0.,1.,0.)  surface. Similarly we set
253  p3=Point(1.,1.,0.)  \begin{python}
254  p4=Point(0.,0.,1.)    l45=Line(p4,p5)
255  p5=Point(1.,0.,1.)    l57=Line(p5,p7)
256  p6=Point(0.,1.,1.)    l76=Line(p7,p6)
257  p7=Point(1.,1.,1.)    l64=Line(p6,p4)
258      top=PlaneSurface(CurveLoop(l45,l57,l76,l64))
259    \end{python}
260    To form the front face we introduce the two additional lines connecting the
261    left and right front points of the \code{top} and \code{bottom} face:
262    \begin{python}
263      l15=Line(p1,p5)
264      l40=Line(p4,p0)
265    \end{python}
266    To form the front face we encounter the problem as the line \code{l45} used
267    to define the \code{top} face is pointing the wrong direction.
268    In \pycad you can reversing direction of an object by changing its sign.
269    So we write \code{-l45} to indicate that the direction is to be reversed.
270    With this notation we can write
271    \begin{python}
272      front=PlaneSurface(CurveLoop(l01,l15,-l45,l40))
273    \end{python}
274    Keep in mind that if you use \code{Line(p4,p5)} instead of \code{-l45} both
275    objects are treated as different although connecting the same points with a
276    straight line in the same direction. The resulting geometry would include an
277    opening along the \code{p4}--\code{p5} connection.
278    This will lead to an inconsistent mesh and may result in a failure of the
279    volumetric mesh generator. Similarly we can define the other sides of the cube:
280    \begin{python}
281      l37=Line(p3,p7)
282      l62=Line(p6,p2)
283      back=PlaneSurface(CurveLoop(l32,-l62,-l76,-l37))
284      left=PlaneSurface(CurveLoop(-l40,-l64,l62,l20))
285      right=PlaneSurface(CurveLoop(-l15,l13,l37,-l57))
286  \end{python}  \end{python}
287  We connect the points to form the bottom and top surfaces of the cube:  We can now put the six surfaces together to form a \class{SurfaceLoop}
288    defining the boundary of the volume of the cube:
289  \begin{python}  \begin{python}
290  l01=Line(p0,p1)    sl=SurfaceLoop(top,bottom,front,back,left,right)
291  l13=Line(p1,p3)    v=Volume(sl)
l32=Line(p3,p2)
l20=Line(p2,p0)
bottom=PlaneSurface(-CurveLoop(l01,l13,l32,l20))
\end{python}
Similar to the definition of a \code{CurvedLoop} the orientation of the surfaces \code{SurfaceLoop} is relevant. In fact the surface normal direction defined by the the right hand rule needs to point outwards as indicated by the surface normals in
Figure~\ref{fig:PYCAD 2}. As the \code{bottom} face is directed upwards it is inserted with the minus sign
into the \code{SurfaceLoop} in order to adjust the orientation of the surface.
Similarly we set
\begin{python}
l45=Line(p4,p5)
l57=Line(p5,p7)
l76=Line(p7,p6)
l64=Line(p6,p4)
top=PlaneSurface(CurveLoop(l45,l57,l76,l64))
\end{python}
To form the front face we introduce the two additional lines connecting the left and right front
points of the the \code{top} and \code{bottom} face:
\begin{python}
l15=Line(p1,p5)
l40=Line(p4,p0)
\end{python}
To form the front face we encounter the problem as the line \code{l45} used to define the
\code{top} face is pointing the wrong direction.  In \pycad you can reversing direction of an
object by changing its sign. So we write \code{-l45} to indicate that the direction is to be reversed. With this notation we can write
\begin{python}
front=PlaneSurface(CurveLoop(l01,l15,-l45,l40))
\end{python}
Keep in mind that if you use \code{Line(p4,p5)} instead \code{-l45} both objects are treated as different although the connecting the same points with a straight line in the same direction. The resulting geometry would include an opening along the \code{p4}--\code{p5} connection. This will lead to an inconsistent mesh and may result in a failure of the volumetric mesh generator. Similarly we can define the other sides of the cube:
\begin{python}
l37=Line(p3,p7)
l62=Line(p6,p2)
back=PlaneSurface(CurveLoop(l32,-l62,-l76,-l37))
left=PlaneSurface(CurveLoop(-l40,-l64,l62,l20))
right=PlaneSurface(CurveLoop(-l15,l13,l37,-l57))
\end{python}
We can now put the six surfaces together to form a \class{SurfaceLoop} defining the
boundary of the volume of the cube:
\begin{python}
sl=SurfaceLoop(top,bottom,front,back,left,right)
v=Volume(sl)
292  \end{python}  \end{python}
293  As in the 2D case, the \class{Design} class is used to define the geometry:  As in the 2D case, the \class{Design} class is used to define the geometry:
294  \begin{python}  \begin{python}
295  from esys.pycad.gmsh import Design    from esys.pycad.gmsh import Design
296  from esys.finley import MakeDomain    from esys.finley import MakeDomain
297
298  des=Design(dim=3, element_size = 0.1, keep_files=True)    des=Design(dim=3, element_size = 0.1, keep_files=True)
299  des.setScriptFileName("brick.geo")    des.setScriptFileName("brick.geo")
300  des.addItems(v, top, bottom, back, front, left , right)    des.addItems(v, top, bottom, back, front, left, right)
301
302  dom=MakeDomain(des)    dom=MakeDomain(des)
303  dom.write("brick.fly")    dom.write("brick.fly")
304  \end{python}  \end{python}
305  Note that the \finley mesh file \file{brick.fly} will contain the  Note that the \finley mesh file \file{brick.fly} will contain the
306  triangles used to define the surfaces as they are added to the \class{Design}.  triangles used to define the surfaces as they are added to the \class{Design}.
# Line 288  The example script of the cube is includ Line 308  The example script of the cube is includ
308  \file{brick.py} in the \ExampleDirectory.  \file{brick.py} in the \ExampleDirectory.
309
310  \section{Alternative File Formats}  \section{Alternative File Formats}
311  \code{pycad} supports other file formats in including  \pycad supports other file formats including I-DEAS universal file, VRML,
312  I-DEAS universal file, VRML, Nastran and STL. The following example shows how  Nastran and STL. The following example shows how to generate the STL file
313  to generate the STL file \file{brick.stl}:  \file{brick.stl}:
314  \begin{python}  \begin{python}
315  from esys.pycad.gmsh import Design    from esys.pycad.gmsh import Design
316
317  des=Design(dim=3, element_size = 0.1, keep_files=True)    des=Design(dim=3, element_size = 0.1, keep_files=True)
318  des.addItems(v, top, bottom, back, front, left , right)    des.addItems(v, top, bottom, back, front, left , right)
319
320  des.setFileFormat(des.STL)    des.setFileFormat(des.STL)
321  des.setMeshFileName("brick.stl")    des.setMeshFileName("brick.stl")
322  des.generate()    des.generate()
323  \end{python}  \end{python}
324  The example script of the cube is included with the software in  The example script of the cube is included with the software in
325  \file{brick_stl.py} in the \ExampleDirectory.  \file{brick_stl.py} in the \ExampleDirectory.
326
327    \section{Element Sizes}
328    The element size used globally is defined by the \code{element_size} argument
329    of the \class{Design}. The mesh generator will try to use this mesh size
330    everywhere in the geometry. In some cases it can be desirable to use a finer
331    mesh locally. A local refinement can be defined at each \class{Point}:
332    \begin{python}
333      p0=Point(0., 0., 0., local_scale=0.01)
334    \end{python}
335    Here the mesh generator will create a mesh with an element size which is by
336    the factor \code{0.01} times smaller than the global mesh size
337    \code{element_size=0.3}, see Figure~\ref{fig:PYCAD 5}.
338    The point where a refinement is defined must be a point on a curve used to
339    define the geometry.
340
341  \begin{figure}  \begin{figure}
342  % \centerline{\includegraphics[width=\figwidth]{refine1}}  \centerline{\includegraphics{refine}}
343  \caption{Local refinement at the origin by  \caption{Local refinement at the origin by \var{local_scale=0.01}
344  \var{local_scale=0.01}  with \var{element_size=0.3} and number of elements on the top set to 10}
with \var{element_size=0.3} and number of elements on the top set to 10.}
346  \end{figure}  \end{figure}
347
348  \section{Element Sizes}  Alternatively, one can define a mesh size along a curve by defining the number
349  The element size used globally is defined by the  of elements to be used to subdivide the curve. For instance, to use $20$
350  \code{element_size} argument of the \class{Design}. The mesh generator  elements on line \code{l23}:
will try to use this mesh size everywhere in the geometry. In some cases it can be
desirable to use locally a finer mesh. A local refinement can be defined at each
\class{Point}:
351  \begin{python}  \begin{python}
352  p0=Point(0.,0.,0.,local_scale=0.01)    l23=Line(p2, p3)
353      l23.setElementDistribution(20)
354  \end{python}  \end{python}
355  Here the mesh generator will create a mesh with an element size which is by the factor \code{0.01}  Setting the number of elements on a curve overwrites the global mesh size
356  times smaller than the global mesh size \code{element_size=0.3}, see Figure~\ref{fig:PYCAD 5}. The point where a refinement is defined must be a point of curve used to define the geometry.  \code{element_size}. The result is shown in Figure~\ref{fig:PYCAD 5}.

Alternatively, one can define a mesh size along a curve by defining the number of elements to be used to subdivide the curve. For instance, to use $20$ element on line \code{l23} on uses:
\begin{python}
l23=Line(p2, p3)
l23.setElementDistribution(20)
\end{python}
Setting the number of elements on a curve overwrites the global mesh size \code{element_size}. The result is shown in Figure~\ref{fig:PYCAD 5}.
357
360  %\modulesynopsis{Python geometry description and meshing interface}  %\modulesynopsis{Python geometry description and meshing interface}
361
362  \subsection{Primitives}  \subsection{Primitives}
363    Some of the most commonly-used objects in \pycad are listed here.
364  Some of the most commonly-used objects in \pycad are listed here. For a more complete  For a more complete list see the full API documentation.
list see the full API documentation.

365
366  \begin{classdesc}{Point}{x=0.,y=0.,z=0.\optional{,local_scale=1.}}  \begin{classdesc}{Point}{x=0.,y=0.,z=0.\optional{,local_scale=1.}}
367  Create a point with from coordinates with local characteristic length \var{local_scale}  creates a point at the given coordinates with local characteristic length \var{local_scale}
368  \end{classdesc}  \end{classdesc}
369
370  \begin{classdesc}{CurveLoop}{list}  \begin{classdesc}{CurveLoop}{list}
371  Create a closed curve from the \code{list}. of  creates a closed curve from a \code{list} of
372  \class{Line}, \class{Arc}, \class{Spline}, \class{BSpline},  \class{Line}, \class{Arc}, \class{Spline}, \class{BSpline},
373  \class{BrezierSpline}.  \class{BezierSpline} objects.
374  \end{classdesc}  \end{classdesc}
375
376  \begin{classdesc}{SurfaceLoop}{list}  \begin{classdesc}{SurfaceLoop}{list}
377  Create a loop of \class{PlaneSurface} or \class{RuledSurface}, which defines the shell of a volume.  creates a loop of \class{PlaneSurface} or \class{RuledSurface}, which defines
378    the shell of a volume.
379  \end{classdesc}  \end{classdesc}
380
381  \subsubsection{Lines}  \subsubsection{Lines}
382  \begin{classdesc}{Line}{point1, point2}  \begin{classdesc}{Line}{point1, point2}
383  Create a line with between starting and ending points.  creates a line between two points.
384  \end{classdesc}  \end{classdesc}
385
386  \begin{methoddesc}[Line]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}  \begin{methoddesc}[Line]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
387  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 neighboured elements. If \var{createBump} is set  defines the number of elements on the line. If set, it overwrites the local
388  progression is applied towards the centre of the line.  length setting which would be applied.
389    The progression factor \var{progression} defines the change of element size
390    between neighboured elements. If \var{createBump} is set progression is
391    applied towards the centre of the line.
392  \end{methoddesc}  \end{methoddesc}
393
394  \begin{methoddesc}[Line]{resetElementDistribution}{}  \begin{methoddesc}[Line]{resetElementDistribution}{}
395  removes a previously set element distribution from the line.  removes a previously set element distribution from the line.
396  \end{methoddesc}  \end{methoddesc}
397  \begin{methoddesc}[Line]{getElemenofDistribution}{}  \begin{methoddesc}[Line]{getElementDistribution}{}
398  Returns the element distribution as tuple of  returns the element distribution as a tuple of number of elements, progression
399  number of elements, progression factor and bump flag. If  factor and bump flag. If no element distribution is set None is returned.
no element distribution is set None is returned.
400  \end{methoddesc}  \end{methoddesc}
401
402  \subsubsection{Splines}  \subsubsection{Splines}
403  \begin{classdesc}{Spline}{point0, point1, ...}  \begin{classdesc}{Spline}{point0, point1, ...}
404  A spline curve defined by a list of points \var{point0}, \var{point1},....  A spline curve defined by a list of points \var{point0}, \var{point1}, \ldots
405  \end{classdesc}  \end{classdesc}
406
407  \begin{methoddesc}[Spline]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}  \begin{methoddesc}[Spline]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
408  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 neighboured elements. If \var{createBump} is set  defines the number of elements on the spline. If set, it overwrites the local
409  progression is applied towards the centre of the line.  length setting which would be applied.
410    The progression factor \var{progression} defines the change of element size
411    between neighboured elements. If \var{createBump} is set progression is
412    applied towards the centre of the spline.
413  \end{methoddesc}  \end{methoddesc}
414
415  \begin{methoddesc}[Spline]{resetElementDistribution}{}  \begin{methoddesc}[Spline]{resetElementDistribution}{}
416  removes a previously set element distribution from the line.  removes a previously set element distribution from the spline.
417  \end{methoddesc}  \end{methoddesc}
418  \begin{methoddesc}[Spline]{getElemenofDistribution}{}
419  Returns the element distribution as tuple of  \begin{methoddesc}[Spline]{getElementDistribution}{}
420  number of elements, progression factor and bump flag. If  returns the element distribution as a tuple of number of elements, progression
421  no element distribution is set None is returned.  factor and bump flag. If no element distribution is set None is returned.
422  \end{methoddesc}  \end{methoddesc}
423
424  \subsubsection{BSplines}  \subsubsection{BSplines}
425  \begin{classdesc}{BSpline}{point0, point1, ...}  \begin{classdesc}{BSpline}{point0, point1, ...}
426  A B-spline curve defined by a list of points \var{point0}, \var{point1},....  A B-spline curve defined by a list of points \var{point0}, \var{point1}, \ldots
427  \end{classdesc}  \end{classdesc}
428
429  \begin{methoddesc}[BSpline]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}  \begin{methoddesc}[BSpline]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
430  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 neighboured elements. If \var{createBump} is set  defines the number of elements on the curve. If set, it overwrites the local
431  progression is applied towards the centre of the line.  length setting which would be applied.
432    The progression factor \var{progression} defines the change of element size
433    between neighboured elements. If \var{createBump} is set progression is
434    applied towards the centre of the curve.
435  \end{methoddesc}  \end{methoddesc}
436
437  \begin{methoddesc}[BSpline]{resetElementDistribution}{}  \begin{methoddesc}[BSpline]{resetElementDistribution}{}
438  removes a previously set element distribution from the line.  removes a previously set element distribution from the curve.
439  \end{methoddesc}  \end{methoddesc}
440  \begin{methoddesc}[BSpline]{getElemenofDistribution}{}
441  Returns the element distribution as tuple of  \begin{methoddesc}[BSpline]{getElementDistribution}{}
442  number of elements, progression factor and bump flag. If  returns the element distribution as a tuple of number of elements, progression
443  no element distribution is set None is returned.  factor and bump flag. If no element distribution is set None is returned.
444  \end{methoddesc}  \end{methoddesc}
445
446  \subsubsection{Brezier Curves}  \subsubsection{Bezier Curves}
447  \begin{classdesc}{BezierCurve}{point0, point1, ...}  \begin{classdesc}{BezierCurve}{point0, point1, ...}
448  A Brezier spline curve defined by a list of points \var{point0}, \var{point1},....  A Bezier spline curve defined by a list of points \var{point0}, \var{point1}, \ldots
449  \end{classdesc}  \end{classdesc}
450
451  \begin{methoddesc}[BezierCurve]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}  \begin{methoddesc}[BezierCurve]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
452  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 neighboured elements. If \var{createBump} is set  defines the number of elements on the curve. If set, it overwrites the local
453  progression is applied towards the centre of the line.  length setting which would be applied.
454    The progression factor \var{progression} defines the change of element size
455    between neighboured elements. If \var{createBump} is set progression is
456    applied towards the centre of the curve.
457  \end{methoddesc}  \end{methoddesc}
458
459  \begin{methoddesc}[BezierCurve]{resetElementDistribution}{}  \begin{methoddesc}[BezierCurve]{resetElementDistribution}{}
460  removes a previously set element distribution from the line.  removes a previously set element distribution from the curve.
461  \end{methoddesc}  \end{methoddesc}
462  \begin{methoddesc}[BezierCurve]{getElemenofDistribution}{}
463  Returns the element distribution as tuple of  \begin{methoddesc}[BezierCurve]{getElementDistribution}{}
464  number of elements, progression factor and bump flag. If  returns the element distribution as a tuple of number of elements, progression
465  no element distribution is set None is returned.  factor and bump flag. If no element distribution is set None is returned.
466  \end{methoddesc}  \end{methoddesc}
467
468  \subsubsection{Arcs}  \subsubsection{Arcs}
469  \begin{classdesc}{Arc}{centre_point, start_point, end_point}  \begin{classdesc}{Arc}{centre_point, start_point, end_point}
470  Create an arc by specifying a centre for a circle and start and end points. An arc may subtend an angle of at most $\pi$ radians.  creates an arc by specifying a centre for a circle and start and end points.
471    An arc may subtend an angle of at most $\pi$ radians.
472  \end{classdesc}  \end{classdesc}
473
474  \begin{methoddesc}[Arc]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}  \begin{methoddesc}[Arc]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
475  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 neighboured elements. If \var{createBump} is set  defines the number of elements on the arc. If set, it overwrites the local
476  progression is applied towards the centre of the line.  length setting which would be applied.
477    The progression factor \var{progression} defines the change of element size
478    between neighboured elements. If \var{createBump} is set progression is
479    applied towards the centre of the arc.
480  \end{methoddesc}  \end{methoddesc}
481
482  \begin{methoddesc}[Arc]{resetElementDistribution}{}  \begin{methoddesc}[Arc]{resetElementDistribution}{}
483  removes a previously set element distribution from the line.  removes a previously set element distribution from the arc.
\end{methoddesc}
\begin{methoddesc}[Arc]{getElemenofDistribution}{}
Returns the element distribution as tuple of
number of elements, progression factor and bump flag. If
no element distribution is set None is returned.
484  \end{methoddesc}  \end{methoddesc}
485
486    \begin{methoddesc}[Arc]{getElementDistribution}{}
487    returns the element distribution as a tuple of number of elements, progression
488    factor and bump flag. If no element distribution is set None is returned.
489    \end{methoddesc}
490
491    \subsubsection{Plane surfaces}
\subsubsection{Plain surfaces}
492  \begin{classdesc}{PlaneSurface}{loop, \optional{holes=[list]}}  \begin{classdesc}{PlaneSurface}{loop, \optional{holes=[list]}}
493  Create a plane surface from a \class{CurveLoop}, which may have one or more holes  creates a plane surface from a \class{CurveLoop}, which may have one or more
494  described by \var{list} of \class{CurveLoop}.  holes described by a \var{list} of \class{CurveLoop} objects.
495  \end{classdesc}  \end{classdesc}
496
497  \begin{methoddesc}[PlaneSurface]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}  \begin{methoddesc}[PlaneSurface]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
498  Defines the number of elements on all lines.  defines the number of elements on all lines.
499  \end{methoddesc}  \end{methoddesc}
500
501  \begin{methoddesc}[PlaneSurface]{setRecombination}{\optional{max_deviation=45 * \var{DEG} }}  \begin{methoddesc}[PlaneSurface]{setRecombination}{\optional{max_deviation=45 * \var{DEG} }}
502  the mesh generator will try to recombine triangular elements  the mesh generator will try to recombine triangular elements into
503  into quadrilateral elements. \var{max_deviation} (in radians) defines the  quadrilateral elements. \var{max_deviation} (in radians) defines the
504  maximum deviation of any angle in the quadrilaterals from the right angle.  maximum deviation of any angle in the quadrilaterals from the right angle.
505  Set \var{max_deviation}=\var{None} to remove recombination.  Set \var{max_deviation}=\var{None} to remove recombination.
506  \end{methoddesc}  \end{methoddesc}
507
508  \begin{methoddesc}[PlaneSurface]{setTransfiniteMeshing}{\optional{orientation="Left"}}  \begin{methoddesc}[PlaneSurface]{setTransfiniteMeshing}{\optional{orientation="Left"}}
509  applies 2D transfinite meshing to the surface.  applies 2D transfinite meshing to the surface.
510  \var{orientation} defines the orientation of triangles. Allowed values  \var{orientation} defines the orientation of triangles. Allowed values
511  are \var{Left''}, \var{Right''} or \var{Alternate''}. The  are \var{Left''}, \var{Right''} and \var{Alternate''}.
512  boundary of the surface must be defined by three or four lines where an  The boundary of the surface must be defined by three or four lines and an
513  element distribution must be defined on all faces where opposite  element distribution must be defined on all faces where opposite
514  faces uses the same element distribution. No holes must be present.  faces use the same element distribution. No holes must be present.
515  \end{methoddesc}  \end{methoddesc}
516

517  \subsubsection{Ruled Surfaces}  \subsubsection{Ruled Surfaces}
518  \begin{classdesc}{RuledSurface}{list}  \begin{classdesc}{RuledSurface}{list}
519  Create a surface that can be interpolated using transfinite interpolation.  creates a surface that can be interpolated using transfinite interpolation.
520  \var{list} gives a list of three or four lines defining the boundary of the  \var{list} gives a list of three or four lines defining the boundary of the
521  surface.  surface.
522  \end{classdesc}  \end{classdesc}
523
524  \begin{methoddesc}[RuledSurface]{setRecombination}{\optional{max_deviation=45 * \var{DEG} }}  \begin{methoddesc}[RuledSurface]{setRecombination}{\optional{max_deviation=45 * \var{DEG} }}
525  the mesh generator will try to recombine triangular elements  the mesh generator will try to recombine triangular elements into
526  into quadrilateral elements. \var{max_deviation} (in radians) defines the  quadrilateral elements. \var{max_deviation} (in radians) defines the
527  maximum deviation of any angle in the quadrilaterals from the right angle.  maximum deviation of any angle in the quadrilaterals from the right angle.
528  Set \var{max_deviation}=\var{None} to remove recombination.  Set \var{max_deviation}=\var{None} to remove recombination.
529  \end{methoddesc}  \end{methoddesc}
# Line 486  Set \var{max_deviation}=\var{None} to re Line 531  Set \var{max_deviation}=\var{None} to re
531  \begin{methoddesc}[RuledSurface]{setTransfiniteMeshing}{\optional{orientation="Left"}}  \begin{methoddesc}[RuledSurface]{setTransfiniteMeshing}{\optional{orientation="Left"}}
532  applies 2D transfinite meshing to the surface.  applies 2D transfinite meshing to the surface.
533  \var{orientation} defines the orientation of triangles. Allowed values  \var{orientation} defines the orientation of triangles. Allowed values
534  are \var{Left''}, \var{Right''} or \var{Alternate''}. The  are \var{Left''}, \var{Right''} and \var{Alternate''}.
535  boundary of the surface must be defined by three or four lines where an  The boundary of the surface must be defined by three or four lines and an
536  element distribution must be defined on all faces where opposite  element distribution must be defined on all faces where opposite
537  faces uses the same element distribution. No holes must be present.  faces use the same element distribution. No holes must be present.
538  \end{methoddesc}  \end{methoddesc}
539
540  \begin{methoddesc}[RuledSurface]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}  \begin{methoddesc}[RuledSurface]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
541  Defines the number of elements on all lines.  defines the number of elements on all lines.
542  \end{methoddesc}  \end{methoddesc}
543
544  \subsubsection{Volumes}  \subsubsection{Volumes}

545  \begin{classdesc}{Volume}{loop, \optional{holes=[list]}}  \begin{classdesc}{Volume}{loop, \optional{holes=[list]}}
546  Create a volume given a \class{SurfaceLoop}, which may have one or more holes  creates a volume given a \class{SurfaceLoop}, which may have one or more holes
547  define by the list of \class{SurfaceLoop}.  define by the list of \class{SurfaceLoop}.
548  \end{classdesc}  \end{classdesc}
549
550  \begin{methoddesc}[Volume]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}  \begin{methoddesc}[Volume]{setElementDistribution}{n\optional{,progression=1\optional{,createBump=\False}}}
551  Defines the number of elements on all lines.  defines the number of elements on all lines.
552  \end{methoddesc}  \end{methoddesc}
553
554  \begin{methoddesc}[Volume]{setRecombination}{\optional{max_deviation=45 * \var{DEG} }}  \begin{methoddesc}[Volume]{setRecombination}{\optional{max_deviation=45 * \var{DEG} }}
555  the mesh generator will try to recombine triangular elements  the mesh generator will try to recombine triangular elements into
556  into quadrilateral elements. These meshes are then used to generate the volume mesh if possible.  quadrilateral elements. These meshes are then used to generate the volume mesh
557  Together with transfinite meshing one can construct rectanglar meshes.  if possible.
558  \var{max_deviation} (in radians) defines the maximum deviation of any angle in the quadrilaterals from the right angle.  Together with transfinite meshing one can construct rectangular meshes.
559    \var{max_deviation} (in radians) defines the maximum deviation of any angle in
560    the quadrilaterals from the right angle.
561  Set \var{max_deviation}=\var{None} to remove recombination.  Set \var{max_deviation}=\var{None} to remove recombination.
562  \end{methoddesc}  \end{methoddesc}
563
564  \begin{methoddesc}[Volume]{setTransfiniteMeshing}{\optional{orientation="Left"}}  \begin{methoddesc}[Volume]{setTransfiniteMeshing}{\optional{orientation="Left"}}
565  applies transfinite meshing to the volume and all surfaces (if \var{orientation} is not equal to \var{None})  applies transfinite meshing to the volume and all surfaces (if
566    \var{orientation} is not equal to \var{None}).
567  \var{orientation} defines the orientation of triangles. Allowed values  \var{orientation} defines the orientation of triangles. Allowed values
568  are \var{Left''}, \var{Right''} or \var{Alternate''}. The  are \var{Left''}, \var{Right''} and \var{Alternate''}.
569  boundary of the surface must be defined by three or four lines where an  The boundary of the surface must be defined by three or four lines and an
570  element distribution must be defined on all faces where opposite  element distribution must be defined on all faces where opposite
571  faces uses the same element distribution.  faces use the same element distribution.
572  If \var{orientation} is equal to \var{None} transfinite meshing is not switched on for the surfaces but needs  If \var{orientation} is equal to \var{None} transfinite meshing is not
573  to be set by the user. No holes must be present.  switched on for the surfaces but needs to be set by the user.
574  \textbf{Warning: The functionality of transfinite meshing without recombination is not entirely clear in \gmshextern.  No holes must be present.
575    \textbf{Warning: The functionality of transfinite meshing without
576    recombination is not entirely clear in \gmshextern.
577  So please apply this method with care.}  So please apply this method with care.}
578  \end{methoddesc}  \end{methoddesc}
579
580    %============================================================================
%============================================================================================================
581  \subsection{Transformations}  \subsection{Transformations}
582
583  Sometimes it's convenient to create an object and then make copies at  Sometimes it is convenient to create an object and then make copies at
584  different orientations and in different sizes.  Transformations are  different orientations or in different sizes. This can be achieved by
585  used to move geometrical objects in the 3-dimensional space and to  applying transformations which are used to move geometrical objects in the
586  resize them.  3-dimensional space and to resize them.
587
588  \begin{classdesc}{Translation}{\optional{b=[0,0,0]}}  \begin{classdesc}{Translation}{\optional{b=[0,0,0]}}
589  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
590  into a \numpy object of shape $(3,)$.  converted into a \numpy object of shape $(3,)$.
591  \end{classdesc}  \end{classdesc}
592
593  \begin{classdesc}{Rotation}{\optional{axis=[1,1,1], \optional{ point = [0,0,0], \optional{angle=0*RAD} } } }  \begin{classdesc}{Rotation}{\optional{axis=[1,1,1], \optional{ point = [0,0,0], \optional{angle=0*RAD} } } }
594  defines a rotation by \var{angle} around axis through point \var{point} and direction \var{axis}.  defines a rotation by \var{angle} around axis through point \var{point} and direction \var{axis}.
595  \var{axis} and \var{point} can be any object that can be converted  \var{axis} and \var{point} can be any object that can be converted into a
596  into a \numpy object of shape $(3,)$.  \numpy object of shape $(3,)$.
597  \var{axis} does not have to be normalised but must have positive length. The right hand rule~\cite{RIGHTHANDRULE}  \var{axis} does not have to be normalised but must have positive length.
598  applies.  The right-hand rule~\cite{RIGHTHANDRULE} applies.
599  \end{classdesc}  \end{classdesc}
600

601  \begin{classdesc}{Dilation}{\optional{factor=1., \optional{centre=[0,0,0]}}}  \begin{classdesc}{Dilation}{\optional{factor=1., \optional{centre=[0,0,0]}}}
602  defines a dilation by the expansion/contraction \var{factor} with  defines a dilation by the expansion/contraction \var{factor} with
603  \var{centre} as the dilation centre.  \var{centre} as the dilation centre.
604  \var{centre} can be any object that can be converted  \var{centre} can be any object that can be converted into a \numpy object of
605  into a \numpy object of shape $(3,)$.  shape $(3,)$.
606  \end{classdesc}  \end{classdesc}
607
608  \begin{classdesc}{Reflection}{\optional{normal=[1,1,1], \optional{offset=0}}}  \begin{classdesc}{Reflection}{\optional{normal=[1,1,1], \optional{offset=0}}}
609  defines a reflection on a plane defined in normal form $n^t x = d$  defines a reflection on a plane defined in normal form $n^t x = d$
610  where $n$ is the surface normal \var{normal} and $d$ is the plane \var{offset}.  where $n$ is the surface normal \var{normal} and $d$ is the plane \var{offset}.
611  \var{normal} can be any object that can be converted  \var{normal} can be any object that can be converted into a \numpy object of
612  into a \numpy object of shape $(3,)$.  shape $(3,)$.
613  \var{normal} does not have to be normalised but must have positive length.  \var{normal} does not have to be normalised but must have positive length.
614  \end{classdesc}  \end{classdesc}
615
617  A constant to convert from degrees to an internal angle representation in radians. For instance use \code{90*DEG} for $90$ degrees.  a constant to convert from degrees to an internal angle representation in
618    radians. For instance use \code{90*DEG} for $90$ degrees.
620
621  \subsection{Properties}  \subsection{Properties}

622  If you are building a larger geometry you may find it convenient to  If you are building a larger geometry you may find it convenient to
623  create it in smaller pieces and then assemble them into the whole.  create it in smaller pieces and then assemble them.
624  Property sets make this easy, and they allow you to name the smaller  Property Sets make this easy, and they allow you to name the smaller
625  pieces for convenience.  pieces for convenience.
626
627  Property sets are used to bundle a set of geometrical objects in a  Property Sets are used to bundle a set of geometrical objects in a
628  group.  The group is identified by a name.  Typically a property set  group. The group is identified by a name. Typically a Property Set
629  is used to mark subregions with share the same material properties or  is used to mark subregions which share the same material properties or
630  to mark portions of the boundary.  For efficiency, the \Design class  to mark portions of the boundary. For efficiency, the \Design class
631  object assigns a integer to each of its property sets, a so-called tag  assigns an integer to each of its Property Sets, a so-called tag\index{tag}.
632  \index{tag}.  The appropriate tag is attached to the elements at  The appropriate tag is attached to the elements at generation time.
generation time.
633
634  See the file \code{pycad/examples/quad.py} for an example using a {\it PropertySet}.  See the file \code{pycad/examples/quad.py} for an example using a {\it PropertySet}.
635

636  \begin{classdesc}{PropertySet}{name,*items}  \begin{classdesc}{PropertySet}{name,*items}
637  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}
638  The objects in the tuple \var{items} mast all be \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD objects.  The objects in the tuple \var{items} mast all be \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD objects.
639  \end{classdesc}  \end{classdesc}
640

641  \begin{methoddesc}[PropertySet]{getManifoldClass}{}  \begin{methoddesc}[PropertySet]{getManifoldClass}{}
642  returns the manifold class \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD expected from the items  returns the manifold class \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD
643  in the property set.  expected from the items in the property set.
644  \end{methoddesc}  \end{methoddesc}
645
646  \begin{methoddesc}[PropertySet]{getDim}{}  \begin{methoddesc}[PropertySet]{getDim}{}
647  returns the spatial dimension of the items  returns the spatial dimension of the items in the property set.
in the property set.
648  \end{methoddesc}  \end{methoddesc}
649
650  \begin{methoddesc}[PropertySet]{getName}{}  \begin{methoddesc}[PropertySet]{getName}{}
# Line 613  sets the name. This name should be uniqu Line 656  sets the name. This name should be uniqu
656  \end{methoddesc}  \end{methoddesc}
657
659  adds a tuple of items. They need to be objects of class \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD.  adds a tuple of items. They need to be objects of class \ManifoldOneD,
660    \ManifoldTwoD or \ManifoldThreeD.
661  \end{methoddesc}  \end{methoddesc}
662
663  \begin{methoddesc}[PropertySet]{getItems}{}  \begin{methoddesc}[PropertySet]{getItems}{}
# Line 633  returns the tag used for this property s Line 677  returns the tag used for this property s
677  %\modulesynopsis{Python geometry description and meshing interface}  %\modulesynopsis{Python geometry description and meshing interface}
678
679  The class and methods described here provide an interface to the mesh  The class and methods described here provide an interface to the mesh
680  generation software, which is currently \gmshextern.  This interface could be  generation software, which is currently \gmshextern. This interface could be
681  adopted to triangle or another mesh generation package if this is  adopted to \emph{triangle} or another mesh generation package if this is
682  deemed to be desirable in the future.  deemed to be desirable in the future.
683
684  \begin{classdesc}{Design}{  \begin{classdesc}{Design}{
685  \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}}}}}
686  The \class{Design} describes the geometry defined by primitives to be meshed.  describes the geometry defined by primitives to be meshed.
687  The \var{dim} specifies the spatial dimension. The argument \var{element_size} defines the global  \var{dim} specifies the spatial dimension, while \var{element_size} defines
688  element size which is multiplied by the local scale to set the element size at each \Point.  the global element size which is multiplied by the local scale to set the
689  The argument \var{order} defines the element order to be used. If \var{keep_files} is set to  element size at each \Point.
690  \True temporary files a kept otherwise they are removed when the instance of the class is deleted.  The argument \var{order} defines the element order to be used.
691    If \var{keep_files} is set to \True temporary files are kept, otherwise they
692    are removed when the instance of the class is deleted.
693  \end{classdesc}  \end{classdesc}
694

695  \begin{memberdesc}[Design]{GMSH}  \begin{memberdesc}[Design]{GMSH}
696  gmsh file format~\cite{GMSH}.  gmsh file format~\cite{GMSH}
697  \end{memberdesc}  \end{memberdesc}
698
699  \begin{memberdesc}[Design]{IDEAS}  \begin{memberdesc}[Design]{IDEAS}
700  I-DEAS universal file format~\cite{IDEAS}.  I-DEAS universal file format~\cite{IDEAS}
701  \end{memberdesc}  \end{memberdesc}
702
703  \begin{memberdesc}[Design]{VRML}  \begin{memberdesc}[Design]{VRML}
704  VRML file format, \cite{VRML}.  VRML file format, \cite{VRML}
705  \end{memberdesc}  \end{memberdesc}
706
707  \begin{memberdesc}[Design]{STL}  \begin{memberdesc}[Design]{STL}
708  STL file format~\cite{STL}.  STL file format~\cite{STL}
709  \end{memberdesc}  \end{memberdesc}
710
711  \begin{memberdesc}[Design]{NASTRAN}  \begin{memberdesc}[Design]{NASTRAN}
712  NASTRAN  bulk data format~\cite{NASTRAN}.  NASTRAN bulk data format~\cite{NASTRAN}
713  \end{memberdesc}  \end{memberdesc}
714
715  \begin{memberdesc}[Design]{MEDIT}  \begin{memberdesc}[Design]{MEDIT}
716  Medit file format~\cite{MEDIT}.  Medit file format~\cite{MEDIT}
717  \end{memberdesc}  \end{memberdesc}
718
719  \begin{memberdesc}[Design]{CGNS}  \begin{memberdesc}[Design]{CGNS}
720  CGNS file format~\cite{CGNS}.  CGNS file format~\cite{CGNS}
721  \end{memberdesc}  \end{memberdesc}
722
723  \begin{memberdesc}[Design]{PLOT3D}  \begin{memberdesc}[Design]{PLOT3D}
724  Plot3D file format~\cite{PLOT3D}.  Plot3D file format~\cite{PLOT3D}
725  \end{memberdesc}  \end{memberdesc}
726

727  \begin{memberdesc}[Design]{DIFFPACK}  \begin{memberdesc}[Design]{DIFFPACK}
728  Diffpack 3D file format~\cite{DIFFPACK}.  Diffpack 3D file format~\cite{DIFFPACK}
729  \end{memberdesc}  \end{memberdesc}
730
731  \begin{memberdesc}[Design]{DELAUNAY}  \begin{memberdesc}[Design]{DELAUNAY}
732  the Delauny triangulator, see \gmshextern,~\cite{TETGEN}.  the Delaunay triangulator, see \gmshextern and \cite{TETGEN}
733  \end{memberdesc}  \end{memberdesc}
734
736  the gmsh triangulator, see \gmshextern.  the gmsh triangulator, see \gmshextern
737  \end{memberdesc}  \end{memberdesc}
738
739  \begin{memberdesc}[Design]{FRONTAL}  \begin{memberdesc}[Design]{FRONTAL}
740  the NETGEN~\cite{NETGEN} triangulator.  the NETGEN~\cite{NETGEN} triangulator
741  \end{memberdesc}  \end{memberdesc}
742
743  \begin{methoddesc}[Design]{generate}{}  \begin{methoddesc}[Design]{generate}{}
744  generates the mesh file. The data are are written to the file \var{Design.getMeshFileName}.  generates the mesh file. The data are written to the file \var{Design.getMeshFileName}.
745  \end{methoddesc}  \end{methoddesc}
746

747  \begin{methoddesc}[Design]{setDim}{\optional{dim=3}}  \begin{methoddesc}[Design]{setDim}{\optional{dim=3}}
748  sets the spatial dimension which needs to be $1$, $2$ or $3$.  sets the spatial dimension which needs to be $1$, $2$ or $3$.
749  \end{methoddesc}  \end{methoddesc}
# Line 717  returns the element order. Line 761  returns the element order.
761  \end{methoddesc}  \end{methoddesc}
762
763  \begin{methoddesc}[Design]{setElementSize}{\optional{element_size=1}}  \begin{methoddesc}[Design]{setElementSize}{\optional{element_size=1}}
764  set the global element size. The local element size at a point is defined as  sets the global element size. The local element size at a point is defined as
765  the global element size multiplied by the local scale. The element size must be positive.  the global element size multiplied by the local scale.
766    The element size must be positive.
767  \end{methoddesc}  \end{methoddesc}
768

769  \begin{methoddesc}[Design]{getElementSize}{}  \begin{methoddesc}[Design]{getElementSize}{}
770  returns the global element size.  returns the global element size.
771  \end{methoddesc}  \end{methoddesc}
772

773  \begin{methoddesc}[Design]{setKeepFilesOn}{}  \begin{methoddesc}[Design]{setKeepFilesOn}{}
774  work files are kept at the end of the generation.  work files are kept at the end of the generation.
775  \end{methoddesc}  \end{methoddesc}
# Line 737  work files are deleted at the end of the Line 779  work files are deleted at the end of the
779  \end{methoddesc}  \end{methoddesc}
780
781  \begin{methoddesc}[Design]{keepFiles}{}  \begin{methoddesc}[Design]{keepFiles}{}
782  returns \True if work files are kept. Otherwise \False is returned.  returns \True if work files are kept, \False otherwise.
783  \end{methoddesc}  \end{methoddesc}
784
785  \begin{methoddesc}[Design]{setScriptFileName}{\optional{name=None}}  \begin{methoddesc}[Design]{setScriptFileName}{\optional{name=None}}
786  set the file name for the gmsh input script. if no name is given a name with extension "geo" is generated.  sets the file name for the gmsh input script.
787    If no name is given a name with extension "geo" is generated.
788  \end{methoddesc}  \end{methoddesc}
789
790  \begin{methoddesc}[Design]{getScriptFileName}{}  \begin{methoddesc}[Design]{getScriptFileName}{}
791  returns the name of the file for the gmsh script.  returns the name of the file for the gmsh script.
792  \end{methoddesc}  \end{methoddesc}
793

794  \begin{methoddesc}[Design]{setMeshFileName}{\optional{name=None}}  \begin{methoddesc}[Design]{setMeshFileName}{\optional{name=None}}
795  sets the name for the mesh file. if no name is given a name is generated.  sets the name for the mesh file. If no name is given a name is generated.
796  The format is set by \\ \var{Design.setFileFormat}.  The format is set by \\\var{Design.setFileFormat}.
797  \end{methoddesc}  \end{methoddesc}
798
799  \begin{methoddesc}[Design]{getMeshFileName}{}  \begin{methoddesc}[Design]{getMeshFileName}{}
800  returns the name of the mesh file  returns the name of the mesh file.
801  \end{methoddesc}  \end{methoddesc}
802

804  adds the tuple of var{items}. An item can be any primitive or a \class{PropertySet}.  adds the tuple of \var{items}. An item can be any primitive or a
805  \warning{If a \PropertySet is added as an item added object that are not  \class{PropertySet}.
806  part of a \PropertySet are not considered in the messing.  %FIXME: \warning{If a \PropertySet is added as an item added object that is not
807  }  %part of a \PropertySet it is not considered in the meshing.}
808  \end{methoddesc}  \end{methoddesc}
809
810  \begin{methoddesc}[Design]{getItems}{}  \begin{methoddesc}[Design]{getItems}{}
811  returns a list of the items  returns a list of the items.
812  \end{methoddesc}  \end{methoddesc}
813
814  \begin{methoddesc}[Design]{clearItems}{}  \begin{methoddesc}[Design]{clearItems}{}
815  resets the items in design  resets the items in this design.
816  \end{methoddesc}  \end{methoddesc}
817
818  \begin{methoddesc}[Design]{getMeshHandler}{}  \begin{methoddesc}[Design]{getMeshHandler}{}
819  returns a handle to the mesh. The call of this method generates the mesh from the geometry and  returns a handle to the mesh.
820  returns a mechanism to access the mesh data. In the current implementation this  Calling this method generates the mesh from the geometry and returns a
821    mechanism to access the mesh data. In the current implementation this
822  method returns a file name for a file containing the mesh data.  method returns a file name for a file containing the mesh data.
823  \end{methoddesc}  \end{methoddesc}
824
# Line 785  returns the gmsh script to generate the Line 827  returns the gmsh script to generate the
827  \end{methoddesc}  \end{methoddesc}
828
829  \begin{methoddesc}[Design]{getCommandString}{}  \begin{methoddesc}[Design]{getCommandString}{}
830  returns the gmsh command used to generate the mesh as string.  returns the gmsh command used to generate the mesh as a string.
831  \end{methoddesc}  \end{methoddesc}
832
833  \begin{methoddesc}[Design]{setOptions}{  \begin{methoddesc}[Design]{setOptions}{
# Line 795  returns the gmsh command used to generat Line 837  returns the gmsh command used to generat
838  \optional{, algorithm3D=\var{Design.FRONTAL}\\  \optional{, algorithm3D=\var{Design.FRONTAL}\\
839  \optional{, generate_hexahedra=False}}}}}}}  \optional{, generate_hexahedra=False}}}}}}}
840  sets options for the mesh generator. \var{algorithm2D} sets the 2D meshing algorithm to be used.  sets options for the mesh generator.
841  The algorithm needs to be \var{Design.DELAUNAY}  \var{algorithm2D} sets the 2D meshing algorithm to be used.
842  \var{Design.FRONTAL}  The algorithm needs to be \var{Design.DELAUNAY}, \var{Design.FRONTAL},
843  or \var{Design.MESHADAPT}. By default \var{Design.MESHADAPT} is used.  or \var{Design.MESHADAPT}. By default \var{Design.MESHADAPT} is used.
844  \var{algorithm3D} sets the 3D  meshing algorithm to be used.  \var{algorithm3D} sets the 3D  meshing algorithm to be used.
845  The algorithm needs to be \var{Design.DELAUNAY}  The algorithm needs to be \var{Design.DELAUNAY} or \var{Design.FRONTAL}.
846  or \var{Design.FRONTAL}  By default \var{Design.FRONTAL} is used.
. By default \var{Design.FRONTAL} is used.
847  \var{optimize_quality}=\True invokes an optimization of the mesh quality.  \var{optimize_quality}=\True invokes an optimization of the mesh quality.
848  \var{smoothing} sets the number of smoothing steps to be applied to the mesh.  \var{smoothing} sets the number of smoothing steps to be applied to the mesh.
849  \var{curvature_based_element_size}=\True switches on curvature based definition of element size.  \var{curvature_based_element_size}=\True switches on curvature based
850  \var{generate_hexahedra}=\True switches on the usage of quadrilateral/hexahedra elements.  definition of element size.
851    \var{generate_hexahedra}=\True switches on the usage of quadrilateral or
852    hexahedral elements.
853  \end{methoddesc}  \end{methoddesc}
854
855  \begin{methoddesc}[Design]{getTagMap}{}  \begin{methoddesc}[Design]{getTagMap}{}
856  returns a \class{TagMap} to map the name \class{PropertySet} in the class to tag numbers generated by gmsh.  returns a \class{TagMap} to map the \class{PropertySet} names to tag numbers
857    generated by gmsh.
858  \end{methoddesc}  \end{methoddesc}
859
860  \begin{methoddesc}[Design]{setFileFormat}{\optional{format=\var{Design.GMSH}}}  \begin{methoddesc}[Design]{setFileFormat}{\optional{format=\var{Design.GMSH}}}
861  set the file format. \var{format} must be one of the values:\\  sets the file format. \var{format} must be one of the values:\\
862  \var{Design.GMSH} \\  \var{Design.GMSH}\\
863  \var{Design.IDEAS}\\  \var{Design.IDEAS}\\
864  \var{Design.VRML}\\  \var{Design.VRML}\\
865  \var{Design.STL}\\  \var{Design.STL}\\
# Line 829  set the file format. \var{format} must b Line 873  set the file format. \var{format} must b
873  \begin{methoddesc}[Design]{getFileFormat}{}  \begin{methoddesc}[Design]{getFileFormat}{}
874  returns the file format.  returns the file format.
875  \end{methoddesc}  \end{methoddesc}
876

Legend:
 Removed from v.3323 changed lines Added in v.3324