doc/user/pycad.tex


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright (c) 2003-2008 by University of Queensland
% Earth Systems Science Computational Center (ESSCC)
% http://www.uq.edu.au/esscc
%
% Primary Business: Queensland, Australia
% Licensed under the Open Software License version 3.0
% http://www.opensource.org/licenses/osl-3.0.php
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\chapter{The Module \pycad} \label{PYCAD CHAP}


\section{Introduction}

\pycad provides a simple way to build a mesh for your finite element
simulation.  You begin by building what we call a {\it Design} using
primitive geometric objects, and then to go on to build a mesh from
the {\it Design}.  The final step of generating the mesh from a {\it
Design} uses freely available mesh generation software, such as \gmshextern.

A {\it Design} is built by defining points, which are used to specify
the corners of geometric objects and the vertices of curves.  Using
points you construct more interesting objects such as lines,
rectangles, and arcs.  By adding many of these objects into what we
call a {\it Design}, you can build meshes for arbitrarily complex 2-D
and 3-D structures.

The example included below shows how to use {\it pycad} to create a 2-D mesh
in the shape of a trapezoid with a cutout area.

\begin{python}
    from esys.pycad import *
    from esys.pycad.gmsh import Design
    from esys.finley import MakeDomain

    # A trapezoid
    p0=Point(0.0, 0.0, 0.0)
    p1=Point(1.0, 0.0, 0.0)
    p2=Point(1.0, 0.5, 0.0)
    p3=Point(0.0, 1.0, 0.0)
    l01=Line(p0, p1)
    l12=Line(p1, p2)
    l23=Line(p2, p3)
    l30=Line(p3, p0)
    c=CurveLoop(l01, l12, l23, l30)

    # A small triangular cutout
    x0=Point(0.1, 0.1, 0.0)
    x1=Point(0.5, 0.1, 0.0)
    x2=Point(0.5, 0.2, 0.0)
    x01=Line(x0, x1)
    x12=Line(x1, x2)
    x20=Line(x2, x0)
    cutout=CurveLoop(x01, x12, x20)

    # Create the surface with cutout
    s=PlaneSurface(c, holes=[cutout])

    # Create a Design which can make the mesh
    d=Design(dim=2, element_size=0.05)

    # Add the trapezoid with cutout
    d.addItems(s)

    # Create the geometry, mesh and Escript domain
    d.setScriptFileName("trapezoid.geo")
    d.setMeshFileName("trapezoid.msh")
    domain=MakeDomain(d, integrationOrder=-1, reducedIntegrationOrder=-1, optimizeLabeling=True)

    # Create a file that can be read back in to python with mesh=ReadMesh(fileName)
    domain.write("trapezoid.fly")
\end{python}

This example is included with the software in
\code{pycad/examples/trapezoid.py}.  If you have gmsh installed you can
run the example and view the geometry and mesh with:

\begin{python}
    python trapezoid.py
    gmsh trapezoid.geo
    gmsh trapezoid.msh
\end{python}

A \code{CurveLoop} is used to connect several lines into a single curve.
It is used in the example above to create the trapezoidal outline for the grid
and also for the triangular cutout area.
You can use any number of lines when creating a \code{CurveLoop}, but
the end of one line must be identical to the start of the next.

Sometimes you might see us write \code{-c} where \code{c} is a
\code{CurveLoop}.  This is the reverse curve of the curve \code{c}. 
It is identical to the original except that its points are traversed
in the opposite order.  This may make it easier to connect two curves
in a \code{CurveLoop}.

The example python script above calls both
\code{d.setScriptFileName()} and \code{d.setMeshFileName()}.  You need
only call these if you wish to save the gmsh geometry and mesh files.

Note that the underlying mesh generation software will not accept all
the geometries you can create with {\it pycad}.  For example, {\it
pycad} will happily allow you to create a 2-D {\it Design} that is a
closed loop with some additional points or lines lying outside of the
enclosed area, but gmsh will fail to create a mesh for it.


\section{\pycad Classes}
\declaremodule{extension}{esys.pycad}
\modulesynopsis{Python geometry description and meshing interface}

\subsection{Primitives}

Some of the most commonly-used objects in {\it pycad} are listed here. For a more complete
list see the full API documentation.

\begin{classdesc}{Point}{x1, x2, x3}
Create a point with from coordinates.
\end{classdesc}

\begin{classdesc}{Line}{point1, point2}
Create a line with between starting and ending points.
\end{classdesc}

\begin{classdesc}{Curve}{point1, point2, ...}
Create a \code{Curve}, which is simply a list of points.
\end{classdesc}

\begin{classdesc}{Spline}{curve}
Interpret a \code{Curve} using a spline.
\end{classdesc}

\begin{classdesc}{BSpline}{curve}
Interpret a \code{Curve} using a b-spline.
\end{classdesc}

\begin{classdesc}{BezierCurve}{curve}
Interpret a \code{Curve} using a Bezier curve.
\end{classdesc}

\begin{classdesc}{CurveLoop}{list}
Create a closed \code{Curve} connecting the lines and/or points given in the \code{list}.
\end{classdesc}

\begin{classdesc}{Arc}{center_point, start_point, end_point}
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.
\end{classdesc}

\begin{classdesc}{PlaneSurface}{loop, \optional{holes=[list]}}
Create a surface for a 2-D mesh, which may have one or more holes.
\end{classdesc}

\begin{classdesc}{RuledSurface}{list}
Create a surface that can be interpolated using transfinite interpolation.
\end{classdesc}

\begin{classdesc}{SurfaceLoop}{list}
Create a loop of 2D primitives, which defines the shell of a volume.
\end{classdesc}

\begin{classdesc}{Volume}{loop, \optional{holes=[list]}}
Create a volume for a 3-D mesh given a SurfaceLoop, which may have one or more holes.
\end{classdesc}

\begin{classdesc}{PropertySet}{list}
Create a PropertySet given a list of 1-D, 2-D or 3-D items. See the section on Properties below for more information.
\end{classdesc}

%============================================================================================================
\subsection{Transformations}

Sometimes it's convenient to create an object and then make copies at
different orientations and in different sizes.  Transformations are
used to move geometrical objects in the 3-dimensional space and to
resize them.

\begin{classdesc}{Translation}{\optional{b=[0,0,0]}}
defines a translation $x \to x+b$. \var{b} can be any object that can be converted 
into a \numarray object of shape $(3,)$.
\end{classdesc}
              
\begin{classdesc}{Rotatation}{\optional{axis=[1,1,1], \optional{ point = [0,0,0], \optional{angle=0*RAD} } } }
defines a rotation by \var{angle} around axis through point \var{point} and direction \var{axis}. 
\var{axis} and \var{point} can be any object that can be converted 
into a \numarray object of shape $(3,)$.
\var{axis} does not have to be normalized but must have positive length. The right hand rule~\cite{RIGHTHANDRULE}
applies.
\end{classdesc}


\begin{classdesc}{Dilation}{\optional{factor=1., \optional{center=[0,0,0]}}}
defines a dilation by the expansion/contraction \var{factor} with 
\var{center} as the dilation center.
\var{center} can be any object that can be converted 
into a \numarray object of shape $(3,)$.
\end{classdesc}

\begin{classdesc}{Reflection}{\optional{normal=[1,1,1], \optional{offset=0}}}
defines a reflection on a plane defined in normal form $n^t x = d$ 
where $n$ is the surface normal \var{normal} and $d$ is the plane \var{offset}.
\var{normal} can be any object that can be converted 
into a \numarray object of shape $(3,)$.
\var{normal} does not have to be normalized but must have positive length. 
\end{classdesc}

\begin{datadesc}{DEG}
A constant to convert from degrees to an internal angle representation in radians. For instance use \code{90*DEG} for $90$ degrees.
\end{datadesc}

\subsection{Properties}

If you are building a larger geometry you may find it convenient to
create it in smaller pieces and then assemble them into the whole. 
Property sets make this easy, and they allow you to name the smaller
pieces for convenience.

Property sets are used to bundle a set of geometrical objects in a
group.  The group is identified by a name.  Typically a property set
is used to mark subregions with share the same material properties or
to mark portions of the boundary.  For efficiency, the \Design class
object assigns a integer to each of its property sets, a so-called tag
\index{tag}.  The appropriate tag is attached to the elements at
generation time.

See the file \code{pycad/examples/quad.py} for an example using a {\it PropertySet}.


\begin{classdesc}{PropertySet}{name,*items}
defines a group geometrical objects which can be accessed through a \var{name}
The objects in the tuple \var{items} mast all be \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD objects.
\end{classdesc}


\begin{methoddesc}[PropertySet]{getManifoldClass}{}
returns the manifold class \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD expected from the items
in the property set.
\end{methoddesc}

\begin{methoddesc}[PropertySet]{getDim}{}
returns the spatial dimension of the items
in the property set. 
\end{methoddesc}

\begin{methoddesc}[PropertySet]{getName}{}
returns the name of the set
\end{methoddesc}

\begin{methoddesc}[PropertySet]{setName}{name}
sets the name. This name should be unique within a \Design.
\end{methoddesc}

\begin{methoddesc}[PropertySet]{addItem}{*items}
adds a tuple of items. They need to be objects of class \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD. 
\end{methoddesc}

\begin{methoddesc}[PropertySet]{getItems}{}
returns the list of items
\end{methoddesc}

\begin{methoddesc}[PropertySet]{clearItems}{}
clears the list of items 
\end{methoddesc}

\begin{methoddesc}[PropertySet]{getTag}{}
returns the tag used for this property set
\end{methoddesc}

\section{Interface to the mesh generation software}
\declaremodule{extension}{esys.pycad.gmsh}
\modulesynopsis{Python geometry description and meshing interface}

The class and methods described here provide an interface to the mesh
generation software, which is currently gmsh.  This interface could be
adopted to triangle or another mesh generation package if this is
deemed to be desirable in the future.

\begin{classdesc}{Design}{
\optional{dim=3, \optional{element_size=1., \optional{order=1, \optional{keep_files=False}}}}}
The \class{Design} describes the geometry defined by primitives to be meshed.
The \var{dim} specifies the spatial dimension. The argument \var{element_size} defines the global
element size which is multiplied by the local scale to set the element size at each \Point. 
The argument \var{order} defines the element order to be used. If \var{keep_files} is set to 
\True temporary files a kept otherwise they are removed when the instance of the class is deleted. 
\end{classdesc}


\begin{methoddesc}[Design]{setDim}{\optional{dim=3}}
sets the spatial dimension which needs to be $1$, $2$ or $3$.
\end{methoddesc}

\begin{methoddesc}[Design]{getDim}{}
returns the spatial dimension.
\end{methoddesc}

\begin{methoddesc}[Design]{setElementOrder}{\optional{order=1}}
sets the element order which needs to be $1$ or $2$.
\end{methoddesc}

\begin{methoddesc}[Design]{getElementOrder}{}
returns the element order.
\end{methoddesc}


\begin{methoddesc}[Design]{setElementSize}{\optional{element_size=1}}
set the global element size. The local element size at a point is defined as 
the global element size multiplied by the local scale. The element size must be positive.
\end{methoddesc}


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

\begin{memberdesc}[Design]{DELAUNAY}
the gmsh Delauny triangulator.
\end{memberdesc}

\begin{memberdesc}[Design]{TETGEN}
the TetGen~\cite{TETGEN} triangulator.
\end{memberdesc}

\begin{memberdesc}[Design]{TETGEN}
the NETGEN~\cite{NETGEN} triangulator.
\end{memberdesc}

\begin{methoddesc}[Design]{setKeepFilesOn}{}
work files are kept at the end of the generation.
\end{methoddesc}

\begin{methoddesc}[Design]{setKeepFilesOff}{}
work files are deleted at the end of the generation.
\end{methoddesc}

\begin{methoddesc}[Design]{keepFiles}{}
returns \True if work files are kept. Otherwise \False is returned.
\end{methoddesc}

\begin{methoddesc}[Design]{setScriptFileName}{\optional{name=None}}
set the filename for the gmsh input script. if no name is given a name with extension "geo" is generated.
\end{methoddesc}

\begin{methoddesc}[Design]{getScriptFileName}{}
returns the name of the file for the gmsh script.
\end{methoddesc}


\begin{methoddesc}[Design]{setMeshFileName}{\optional{name=None}}
sets the name for the gmsh  mesh file. if no name is given a name with extension "msh" is generated.
\end{methoddesc}

\begin{methoddesc}[Design]{getMeshFileName}{}
returns the name of the file for the gmsh msh
\end{methoddesc}


\begin{methoddesc}[Design]{addItems}{*items}
adds the tuple of var{items}. An item can be any primitive or a \class{PropertySet}.
\warning{If a \PropertySet is added as an item added object that are not 
part of a \PropertySet are not considered in the messing.  
}

\end{methoddesc}

\begin{methoddesc}[Design]{getItems}{}
returns a list of the items
\end{methoddesc}

\begin{methoddesc}[Design]{clearItems}{}
resets the items in design
\end{methoddesc}

\begin{methoddesc}[Design]{getMeshHandler}{}
returns a handle to the mesh. The call of this method generates the mesh from the geometry and
returns a mechanism to access the mesh data. In the current implementation this
method returns a file name for a gmsh file containing the mesh data.
\end{methoddesc}

\begin{methoddesc}[Design]{getScriptString}{}
returns the gmsh script to generate the mesh as a string.
\end{methoddesc}

\begin{methoddesc}[Design]{getCommandString}{}
returns the gmsh command used to generate the mesh as string.
\end{methoddesc}

\begin{methoddesc}[Design]{setOptions}{\optional{algorithm=None, \optional{ optimize_quality=True,\optional{ smoothing=1}}}}
sets options for the mesh generator. \var{algorithm} sets the algorithm to be used.
The algorithm needs to be \var{Design.DELAUNAY}
\var{Design.TETGEN}
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.  
\end{methoddesc}

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