doc/user/pycad.tex

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


\section{Introduction}


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

\subsection{Primitives}

\begin{classdesc}{Point}{}

\end{classdesc}

\begin{classdesc}{Manifold1D}{}

\end{classdesc}

\begin{classdesc}{Manifold2D}{}

\end{classdesc}

\begin{classdesc}{Manifold3D}{}

\end{classdesc}

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

Transformations are used to move geometrical objects in the 3-dimensional space:

\begin{datadesc}{DEG}
The unit of degree. For instance use \code{90*DEG} for $90$ degrees.
\end{datadesc}

\begin{datadesc}{RAD}
The unit of radiant. For instance use \code{math.pi*RAD} for $180$ degrees.
\end{datadesc}

\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}

\subsection{Properties}

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.


\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 \gmshextern}
\declaremodule{extension}{esys.pycad.gmsh}
\modulesynopsis{Python geometry description and meshing interface}

\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 multipied 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 \gmshextern 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 \gmshextern 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 \gmshextern script.
\end{methoddesc}


\begin{methoddesc}[Design]{setMeshFileName}{\optional{name=None}}
sets the name for the \gmshextern  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 mechnism to access the mesh data. In the current implementation this
is this method returns a file name for a \gmshextern file containing the mesh data but this may change in
later versions.
\end{methoddesc}

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

\begin{methoddesc}[Design]{getCommandString}{}
returns the \gmshextern 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 \gmshextern.
\end{methoddesc}
1	gross	993	\chapter{The module \pycad}
2			\label{PYCAD CHAP}
3
4	gross	999
5
6			\section{Introduction}
7
8
9			\section{\pycad Classes}
10			\declaremodule{extension}{esys.pycad}
11	gross	993	\modulesynopsis{Python geometry description and meshing interface}
12
13	gross	999	\subsection{Primitives}
14	gross	993
15	gross	999	\begin{classdesc}{Point}{}
16
17			\end{classdesc}
18
19			\begin{classdesc}{Manifold1D}{}
20
21			\end{classdesc}
22
23			\begin{classdesc}{Manifold2D}{}
24
25			\end{classdesc}
26
27			\begin{classdesc}{Manifold3D}{}
28
29			\end{classdesc}
30
31			%============================================================================================================
32			\subsection{Transformations}
33
34			Transformations are used to move geometrical objects in the 3-dimensional space:
35
36			\begin{datadesc}{DEG}
37			The unit of degree. For instance use \code{90*DEG} for $90$ degrees.
38			\end{datadesc}
39
40			\begin{datadesc}{RAD}
41			The unit of radiant. For instance use \code{math.pi*RAD} for $180$ degrees.
42			\end{datadesc}
43
44			\begin{classdesc}{Translation}{\optional{b=[0,0,0]}}
45			defines a translation $x \to x+b$. \var{b} can be any object that can be converted
46			into a \numarray object of shape $(3,)$.
47			\end{classdesc}
48
49			\begin{classdesc}{Rotatation}{\optional{axis=[1,1,1], \optional{ point = [0,0,0], \optional{angle=0*RAD} } } }
50			defines a rotation by \var{angle} around axis through point \var{point} and direction \var{axis}.
51			\var{axis} and \var{point} can be any object that can be converted
52			into a \numarray object of shape $(3,)$.
53			\var{axis} does not have to be normalized but must have positive length. The right hand rule~\cite{RIGHTHANDRULE}
54			applies.
55			\end{classdesc}
56
57
58			\begin{classdesc}{Dilation}{\optional{factor=1., \optional{center=[0,0,0]}}}
59			defines a dilation by the expansion/contraction \var{factor} with
60			\var{center} as the dilation center.
61			\var{center} can be any object that can be converted
62			into a \numarray object of shape $(3,)$.
63			\end{classdesc}
64
65			\begin{classdesc}{Reflection}{\optional{normal=[1,1,1], \optional{offset=0}}}
66			defines a reflection on a plane defined in normal form $n^t x = d$
67			where $n$ is the surface normal \var{normal} and $d$ is the plane \var{offset}.
68			\var{normal} can be any object that can be converted
69			into a \numarray object of shape $(3,)$.
70			\var{normal} does not have to be normalized but must have positive length.
71			\end{classdesc}
72
73			\subsection{Properties}
74
75			Property sets are used to bundle a set of geometrical objects in a group. The group
76			is identified by a name. Typically a property set is used to mark
77			subregions with share the same material properties or to mark portions of the boundary.
78			For efficiency, the \Design class object assigns a integer to each of its property sets,
79			a so-called tag \index{tag}. The appropriate tag is attached to the elements at generation time.
80
81	gross	1044
82	gross	999	\begin{classdesc}{PropertySet}{name,*items}
83			defines a group geometrical objects which can be accessed through a \var{name}
84			The objects in the tuple \var{items} mast all be \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD objects.
85			\end{classdesc}
86
87
88			\begin{methoddesc}[PropertySet]{getManifoldClass}{}
89			returns the manifold class \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD expected from the items
90			in the property set.
91			\end{methoddesc}
92
93			\begin{methoddesc}[PropertySet]{getDim}{}
94			returns the spatial dimension of the items
95			in the property set.
96			\end{methoddesc}
97
98			\begin{methoddesc}[PropertySet]{getName}{}
99			returns the name of the set
100			\end{methoddesc}
101
102			\begin{methoddesc}[PropertySet]{setName}{name}
103			sets the name. This name should be unique within a \Design.
104			\end{methoddesc}
105
106			\begin{methoddesc}[PropertySet]{addItem}{*items}
107			adds a tuple of items. They need to be objects of class \ManifoldOneD, \ManifoldTwoD or \ManifoldThreeD.
108			\end{methoddesc}
109
110			\begin{methoddesc}[PropertySet]{getItems}{}
111			returns the list of items
112			\end{methoddesc}
113
114			\begin{methoddesc}[PropertySet]{clearItems}{}
115			clears the list of items
116			\end{methoddesc}
117
118			\begin{methoddesc}[PropertySet]{getTag}{}
119			returns the tag used for this property set
120			\end{methoddesc}
121
122			\section{Interface to \gmshextern}
123			\declaremodule{extension}{esys.pycad.gmsh}
124			\modulesynopsis{Python geometry description and meshing interface}
125
126			\begin{classdesc}{Design}{
127			\optional{dim=3, \optional{element_size=1., \optional{order=1, \optional{keep_files=False}}}}}
128			The \class{Design} describes the geometry defined by primitives to be meshed.
129			The \var{dim} specifies the spatial dimension. The argument \var{element_size} defines the global
130			element size which is multiplied by the local scale to set the element size at each \Point.
131			The argument \var{order} defines the element order to be used. If \var{keep_files} is set to
132			\True temporary files a kept otherwise they are removed when the instance of the class is deleted.
133			\end{classdesc}
134
135
136			\begin{methoddesc}[Design]{setDim}{\optional{dim=3}}
137			sets the spatial dimension which needs to be $1$, $2$ or $3$.
138			\end{methoddesc}
139
140			\begin{methoddesc}[Design]{getDim}{}
141			returns the spatial dimension.
142			\end{methoddesc}
143
144			\begin{methoddesc}[Design]{setElementOrder}{\optional{order=1}}
145			sets the element order which needs to be $1$ or $2$.
146			\end{methoddesc}
147
148			\begin{methoddesc}[Design]{getElementOrder}{}
149			returns the element order.
150			\end{methoddesc}
151
152
153			\begin{methoddesc}[Design]{setElementSize}{\optional{element_size=1}}
154			set the global element size. The local element size at a point is defined as
155			the global element size multipied by the local scale. The element size must be positive.
156			\end{methoddesc}
157
158
159			\begin{methoddesc}[Design]{getElementSize}{}
160			returns the global element size.
161			\end{methoddesc}
162
163			\begin{memberdesc}[Design]{DELAUNAY}
164			the \gmshextern Delauny triangulator.
165			\end{memberdesc}
166
167			\begin{memberdesc}[Design]{TETGEN}
168			the TetGen~\cite{TETGEN} triangulator.
169			\end{memberdesc}
170
171			\begin{memberdesc}[Design]{TETGEN}
172			the NETGEN~\cite{NETGEN} triangulator.
173			\end{memberdesc}
174
175			\begin{methoddesc}[Design]{setKeepFilesOn}{}
176			work files are kept at the end of the generation.
177			\end{methoddesc}
178
179			\begin{methoddesc}[Design]{setKeepFilesOff}{}
180			work files are deleted at the end of the generation.
181			\end{methoddesc}
182
183			\begin{methoddesc}[Design]{keepFiles}{}
184			returns \True if work files are kept. Otherwise \False is returned.
185			\end{methoddesc}
186
187			\begin{methoddesc}[Design]{setScriptFileName}{\optional{name=None}}
188			set the filename for the \gmshextern input script. if no name is given a name with extension "geo" is generated.
189			\end{methoddesc}
190
191			\begin{methoddesc}[Design]{getScriptFileName}{}
192			returns the name of the file for the \gmshextern script.
193			\end{methoddesc}
194
195
196			\begin{methoddesc}[Design]{setMeshFileName}{\optional{name=None}}
197			sets the name for the \gmshextern mesh file. if no name is given a name with extension "msh" is generated.
198			\end{methoddesc}
199
200			\begin{methoddesc}[Design]{getMeshFileName}{}
201			returns the name of the file for the gmsh msh
202			\end{methoddesc}
203
204
205			\begin{methoddesc}[Design]{addItems}{*items}
206			adds the tuple of var{items}. An item can be any primitive or a \class{PropertySet}.
207			\warning{If a \PropertySet is added as an item added object that are not
208			part of a \PropertySet are not considered in the messing.
209			}
210
211			\end{methoddesc}
212
213			\begin{methoddesc}[Design]{getItems}{}
214			returns a list of the items
215			\end{methoddesc}
216
217			\begin{methoddesc}[Design]{clearItems}{}
218			resets the items in design
219			\end{methoddesc}
220
221			\begin{methoddesc}[Design]{getMeshHandler}{}
222			returns a handle to the mesh. The call of this method generates the mesh from the geometry and
223			returns a mechnism to access the mesh data. In the current implementation this
224			is this method returns a file name for a \gmshextern file containing the mesh data but this may change in
225			later versions.
226			\end{methoddesc}
227
228			\begin{methoddesc}[Design]{getScriptString}{}
229			returns the \gmshextern script to generate the mesh as string.
230			\end{methoddesc}
231
232			\begin{methoddesc}[Design]{getCommandString}{}
233			returns the \gmshextern command used to generate the mesh as string..
234			\end{methoddesc}
235
236			\begin{methoddesc}[Design]{setOptions}{\optional{algorithm=None, \optional{ optimize_quality=True,\optional{ smoothing=1}}}}
237			sets options for the mesh generator. \var{algorithm} sets the algorithm to be used.
238			The algorithm needs to be \var{Design.DELAUNAY}
239			\var{Design.TETGEN}
240			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.
241			\end{methoddesc}
242
243			\begin{methoddesc}[Design]{getTagMap}{}
244			returns a \class{TagMap} to map the name \class{PropertySet} in the class to tag numbers generated by \gmshextern.
245			\end{methoddesc}