1 
% $Id$ 
2 

3 
\chapter{The module \escript} 
4 

5 
\declaremodule{extension}{escript} 
6 
\modulesynopsis{Data manipulation} 
7 

8 
\begin{figure} 
9 
\includegraphics[width=\textwidth]{EscriptDiagram1.eps} 
10 
\caption{\label{ESCRIPT DEP}Dependency of Function Spaces. An arrow indicates that a function in the 
11 
function space at the starting point can be interpreted as a function in the function space of the arrow target.} 
12 
\end{figure} 
13 

14 
\escript is an extension of Python to handle functions represented by their values on 
15 
\DataSamplePoints. The \DataSamplePoints for the geometrical region on which 
16 
the function is defined. The region as well as the method which is used 
17 
to interpolate value on the \DataSamplePoints is defined by 
18 
\Domain class objects. For instance when using 
19 
the finite element method (FEM) \index{finite element method} 
20 
\Domain object holds the information about the FEM mesh, eg. 
21 
a table of nodes and a table of elements. Although \Domain contains 
22 
the discretization method to be used \escript does not use this information directly. 
23 
\Domain objects are created from a module which want to make use 
24 
\escript, e.g. \finley. 
25 

26 
The solution of a PDE is a function of its location in the domain of interest $\Omega$. 
27 
When solving a partial differential equation \index{partial differential equation} (PDE) using FEM 
28 
the solution is (piecewise) differentiable but, in general, its gradient 
29 
is discontinuous. To reflect these different degrees of smoothness different 
30 
representations of the functions are used. For instance; in FEM 
31 
the displacement field is represented by its values at the nodes of the mesh, while the 
32 
strain, which is the symmetric part of the gradient of the displacement field, is stored on the 
33 
element centers. To be able to classify functions with respect to their smoothness, \escript has the 
34 
concept of the "function space". A function space is described by a \FunctionSpace object. 
35 
The following statement generates the object \var{solution_space} which is 
36 
a \FunctionSpace object and provides access to the function space of 
37 
PDE solutions on the \Domain \var{mydomain}: 
38 
\begin{python} 
39 
solution_space=Solution(mydomain) 
40 
\end{python} 
41 
The following generators for function spaces on a \Domain \var{mydomin} are available: 
42 
\begin{itemize} 
43 
\item \var{Solution(mydomain)}: solutions of a PDE. 
44 
\item \var{ContinuousFunction(mydomain)}: continuous functions, eg. a temperature distribution. 
45 
\item \var{Function(mydomain)}: general functions which are not necessarily continuous, eg. a stress field. 
46 
\item \var{FunctionOnBoundary(mydomain)}: functions on the boundary of the domain, eg. a surface pressure. 
47 
\item \var{FunctionOnContact0(mydomain)}: functions on side $0$ of the discontinuity. 
48 
\item \var{FunctionOnContact1(mydomain)}: functions on side $1$ of the discontinuity. 
49 
\end{itemize} 
50 
A discontinuity \index{discontinuity} is a region within the domain across which functions may be discontinuous. 
51 
The location of discontinuity is defined in the \Domain object. 
52 
\fig{ESCRIPT DEP} shows the dependency between the types of function spaces. 
53 
The solution of a PDE is a continuous function. Any continuous function can be seen as a general function 
54 
on the domain and can be restricted to the boundary as well as to any side of the 
55 
discontinuity (the result will be different depending on 
56 
which side is chosen). Functions on any side of the 
57 
discontinuity can be seen as a function on the corresponding other side. 
58 
A function on the boundary or on one side of 
59 
the discontinuity cannot be seen as a general function on the domain as there are no values 
60 
defined for the interior. For most PDE solver libraries 
61 
the space of the solution and continuous functions is identical, however in some cases, eg. 
62 
when periodic boundary conditions are used in \finley, a solution 
63 
fulfils periodic boundary conditions while a continuous function does not have to be periodic. 
64 

65 
The concept of function spaces describes the properties of 
66 
functions and allows abstraction from the actual representation 
67 
of the function in the context of a particular application. For instance, 
68 
in the FEM context a 
69 
function in the \Function function space 
70 
is typically represented by its values at the element center, 
71 
but in a finite difference scheme the edge midpoint of cells is preferred. 
72 
Using the concept of function spaces 
73 
allows the user to run the same script on different 
74 
PDE solver libraries by just changing the creator of the \Domain object. 
75 
Changing the function space of a particular function 
76 
will typically lead to a change of its representation. 
77 
So, when seen as a general function, 
78 
a continuous function which is typically represented by its values 
79 
on the node of the FEM mesh or finite difference grid 
80 
has to be interpolated to the element centers or the cell edges, 
81 
respectively. 
82 

83 
\Data class objects store functions of the location in a domain. 
84 
The function is represented through its values on \DataSamplePoints where 
85 
the \DataSamplePoints are chosen according to the function space 
86 
of the function. 
87 
\Data class objects are used to define the coefficients 
88 
of the PDEs to be solved by a PDE solver library 
89 
and to store the returned solutions. 
90 

91 
The values of the function have a rank which gives the 
92 
number of indexes, and a \Shape defining the range of each index. 
93 
The rank in \escript is limited to the range $0$ through $4$ and 
94 
it is assumed that the rank and \Shape is the same for all \DataSamplePoints. 
95 
The \Shape of a \Data object is a tuple \var{s} of integers. The length 
96 
of \var{s} is the rank of the \Data object and \var{s[i]} is the maximum 
97 
value for the \var{i}th index. 
98 
For instance, a stress field has rank $2$ and 
99 
\Shape $(d,d)$ where $d$ is the spatial dimension. 
100 
The following statement creates the \Data object 
101 
\var{mydat} representing a 
102 
continuous function with values 
103 
of \Shape $(2,3)$ and rank $2$: 
104 
\begin{python} 
105 
mydat=Data(value=1,what=ContinuousFunction(myDomain),shape=(2,3)) 
106 
\end{python} 
107 
The initial value is the constant $1$ for all \DataSamplePoints and 
108 
all components. 
109 

110 
\Data objects can also be created from any \numarray 
111 
array or any object, such as a list of floating point numbers, 
112 
that can be converted into a \numarray array \Ref{NUMARRAY}. 
113 
The following two statements 
114 
create objects which are equivalent to \var{mydat}: 
115 
\begin{python} 
116 
mydat1=Data(value=numarray.ones((2,3)),what=ContinuousFunction(myDomain)) 
117 
mydat2=Data(value=[[1,1],[1,1],[1,1]],what=ContinuousFunction(myDomain)) 
118 
\end{python} 
119 
In the first case the initial value is \var{numarray.ones((2,3))} 
120 
which generates a $2 \times 3$ matrix as a \numarray array 
121 
filled with ones. The \Shape of the created \Data object 
122 
it taken from the \Shape of the array. In the second 
123 
case, the creator converts the initial value, which is a list of lists, 
124 
and converts it into a \numarray array before creating the actuall 
125 
\Data object. 
126 

127 
For convenience \escript provides creators for the most common types 
128 
of \Data objects in the following forms (\var{d} defines the 
129 
spatial dimension): 
130 
\begin{itemize} 
131 
\item \var{Scalar(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(,))}, 
132 
e.g a temperature field. 
133 
\item \var{Vector(0,Function(mydomain))}is the same as \var{Data(0,Function(myDomain),(d))}, e.g 
134 
a velocity field. 
135 
\item \var{Tensor(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d,d))}, 
136 
eg. a stress field. 
137 
\item \var{Tensor4(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d,d,d,d))} 
138 
eg. a Hook tensor field. 
139 
\end{itemize} 
140 
Here the initial value is $0$ but any object that can be converted into a \numarray array and whose \Shape 
141 
is consistent with \Shape of the \Data object to be created can be used as the initial value. 
142 

143 
\Data objects can be manipulated by applying unitary operations (eg. cos, sin, log) 
144 
and be combined by applying binary operations (eg. +,  ,* , /). 
145 
It is to be emphasized that \escript itself does not handle any spatial dependencies itself as 
146 
it does not know how values are interpreted by the processing PDE solver library. 
147 
However \escript invokes interpolation if this is needed during data manipulations. 
148 
Typically, this occurs in binary operation when both arguments belong to different 
149 
function spaces or when data are handed over to a PDE solver library 
150 
which requires functions to be represented in a particular way. 
151 

152 
The following example shows the usage of {\tt Data} objects: Assume we have a 
153 
displacement field $u$ and we want to calculate the corresponding stress field 
154 
$\sigma$ using the linearelastic isotropic material model 
155 
\begin{eqnarray}\label{eq: linear elastic stress} 
156 
\sigma\hackscore {ij}=\lambda u\hackscore {k,k} \delta\hackscore {ij} + \mu ( u\hackscore {i,j} + u\hackscore {j,i}) 
157 
\end{eqnarray} 
158 
where $\delta\hackscore {ij}$ is the Kronecker symbol and 
159 
$\lambda$ and $\mu$ are the Lame coefficients. The following function 
160 
takes the displacement {\tt u} and the Lame coefficients 
161 
\var{lam} and \var{mu} as arguments and returns the corresponding stress: 
162 
\begin{python} 
163 
import numarray 
164 
def getStress(u,lam,mu): 
165 
d=u.getDomain().getDim() 
166 
g=grad(u) 
167 
stress=lam*trace(g)*numarray.identity(d)+ \ 
168 
mu*(g+transpose(g)) 
169 
return stress 
170 
\end{python} 
171 
The variable 
172 
\var{d} gives the spatial dimension of the 
173 
domain on which the displacements are defined. 
174 
\var{identity} is a \numarray function which returns the Kronecker symbol with indexes 
175 
$i$ and $j$ running from $0$ to \var{d}1. The call \var{grad(u)} requires 
176 
the displacement field \var{u} to be in the \var{Solution} or \ContinuousFunction 
177 
function space. The result \var{g} as well as the returned stress will be in the \Function function space. 
178 
If \var{u} is available, eg. by solving a PDE, \var{getStress} might be called 
179 
in the following way: 
180 
\begin{python} 
181 
s=getStress(u,1.,2.) 
182 
\end{python} 
183 
However \var{getStress} can also be called with \Data objects as values for 
184 
\var{lam} and \var{mu} which, 
185 
for instance in the case of a temperature dependency, are calculated by an expression. 
186 
The following call is equivalent to the previous example: 
187 
\begin{python} 
188 
lam=Scalar(1.,ContinuousFunction(mydomain)) 
189 
mu=Scalar(2.,Function(mydomain)) 
190 
s=getStress(u,lam,mu) 
191 
\end{python} 
192 
The function \var{lam} belongs to the \ContinuousFunction function space 
193 
but with \var{g} the function \var{trace(g)} is in the \Function function space. 
194 
Therefore the evaluation of the product \var{lam*trace(g)} in the stress calculation 
195 
produces a problem, as both functions are represented differently, eg. in FEM 
196 
\var{lam} by its values on the node, and in \var{trace(g)} by its values at the element centers. 
197 
In the case of inconsistent function spaces of arguments in a binary operation, \escript 
198 
interprets the arguments in the appropriate function space according to the inclusion 
199 
defined in Table~\ref{ESCRIPT DEP}. In this example that means 
200 
\escript sees \var{lam} as a function of the \Function function space. 
201 
In the context of FEM this means the nodal values of 
202 
\var{lam} are interpolated to the element centers. Behind the scenes 
203 
\escript calls the appropriate function from the PDE solver library. 
204 

205 
\begin{figure} 
206 
\includegraphics[width=\textwidth]{EscriptDiagram2.eps} 
207 
\caption{\label{Figure: tag}Element Tagging. A rectangular mesh over a region with two rock types {\it white} and {\it gray}. 
208 
The number in each cell refers to the major rock type present in the cell ($1$ for {\it white} and $2$ for {\it gray}). 
209 
} 
210 
\end{figure} 
211 

212 
Material parameters such as the Lame coefficients are typically dependent on rock types present in the 
213 
area of interest. A common technique to handle these kinds of material parameters is "tagging". \fig{Figure: tag} 
214 
shows an example. In this case two rock types {\it white} and {\it gray} can be found in the domain. The domain 
215 
is subdivided into rectangular shaped cells (which is not necessarily the best subdivision for this case). Each 
216 
cell has a tag indicating the rock type predominately found in this cell. Here $1$ is used to indicate 
217 
rock type {\it white} and $2$ for rock type {\it gray}. The tags are assigned at the time when the cells are generated 
218 
(\escript provides tools to manipulate tags at a later stage) 
219 
and stored in the \Domain class object. The following statements show how for the 
220 
example of \fig{Figure: tag} and the stress calculation discussed before tagged values are used for 
221 
\var{lam}: 
222 
\begin{python} 
223 
lam=Scalar(value=2.,what=Function(mydomain)) 
224 
lam.setTaggedValue(1,30.) 
225 
lam.setTaggedValue(2,5000.) 
226 
s=getStress(u,lam,2.) 
227 
\end{python} 
228 
In this example \var{lam} is set to $30$ for those cells with tag $1$ and to $5000.$ for those cells 
229 
with tag $2$. The initial value $2$ of \var{lam} is used as a default value for the case when a tag 
230 
is encountered which has not been linked with a value. Note that the \var{getStress} method 
231 
is called without modification. \escript resolves the tags when \var{lam*trace(g)} is calculated. 
232 

233 
The \Data class provides a transparent interface to various data representations and the 
234 
translations between them. As shown in the example of stress calculation, this allows the user to 
235 
develop and test algorithms for a simple case (for instance with the Lame coefficients as constants) 
236 
and then without further modifications of the program code to apply the algorithm in a 
237 
more complex application (for instance a definition of the Lame coefficients using tags). 
238 
As described here, there are three ways in which \Data objects are represented internally, constant, tagged, and expanded (other representions will become available in later versions of \escript): 
239 
In the constant case, if the same value is used at each sample point a single value is stored to save memory and compute time. 
240 
Any operation on this constant data will only be performed on the single value. 
241 
In the expanded case, each sample point has an individual value, eg. the solution of a PDE, 
242 
and the values are stored as a complete array. The tagged case has already been discussed above. 
243 

244 
Values are accessed through a sample reference number. Operations on expanded \Data 
245 
objects have to be performed for each sample point individually. If tagged values are used values are 
246 
held in a dictionary. Operations on tagged data require processing the set of tagged values only, rather than 
247 
processing the value for each individual sample point. 
248 
\escript allows use of constant, tagged and expanded data in a single expression. 
249 

250 

251 

252 
\section{\Domain class} 
253 

254 
\begin{classdesc}{Domain}{} 
255 
A \Domain objects is used to describe a geometrical region together with 
256 
a way of representing functions over this region. 
257 
The \Domain class provides an abstract access to the domain of \FunctionSpace and \Data objects. 
258 
\Domain itself has no initialization but implementations of \Domain are 
259 
instantiated by numerical libraries making use of \Data objects. 
260 
\end{classdesc} 
261 

262 
\begin{methoddesc}[Domain]{getDim}{} 
263 
returns the spatial dimension of the \Domain. 
264 
\end{methoddesc} 
265 

266 
\begin{methoddesc}[Domain]{getX}{} 
267 
returns the locations in the \Domain. The \FunctionSpace of the returned 
268 
\Data object is chosen by the \Domain implementation. Typically it will be 
269 
in the \Function. 
270 
\end{methoddesc} 
271 

272 
\begin{methoddesc}[Domain]{setX}{newX} 
273 
assigns a new location to the \Domain. \var{newX} has to have \Shape $(d,)$ 
274 
where $d$ is the spatial dimension of the domain. Typically \var{newX} must be 
275 
in the \ContinuousFunction but the space actually to be used depends on the \Domain implementation. 
276 
\end{methoddesc} 
277 

278 
\begin{methoddesc}[Domain]{getNormal}{} 
279 
returns the surface normals on the boundary of the \Domain as \Data object. 
280 
\end{methoddesc} 
281 

282 
\begin{methoddesc}[Domain]{getSize}{} 
283 
returns the local sample size, e.g. the element diameter, as \Data object. 
284 
\end{methoddesc} 
285 

286 
\begin{methoddesc}[Domain]{__eq__}{arg} 
287 
returns \True of the \Domain \var{arg} describes the same domain. Otherwise 
288 
\False is returned. 
289 
\end{methoddesc} 
290 

291 
\begin{methoddesc}[Domain]{__ne__}{arg} 
292 
returns \True of the \Domain \var{arg} does not describe the same domain. 
293 
Otherwise \False is returned. 
294 
\end{methoddesc} 
295 

296 
\section{\Domain class} 
297 
\begin{classdesc}{FunctionSpace}{} 
298 
\FunctionSpace objects are used to define properties of \Data objects, such as continuity. \FunctionSpace objects 
299 
are instantiated by generator functions. \Data objects in particular \FunctionSpace are 
300 
represented by their values at \DataSamplePoints which are defined by the type and the \Domain of the 
301 
\FunctionSpace. 
302 
\end{classdesc} 
303 

304 
\begin{methoddesc}[FunctionSpace]{getDim}{} 
305 
returns the spatial dimension of the \Domain of the \FunctionSpace. 
306 
\end{methoddesc} 
307 

308 
\begin{methoddesc}[FunctionSpace]{getX}{} 
309 
returns the location of the \DataSamplePoints. 
310 
\end{methoddesc} 
311 

312 
\begin{methoddesc}[FunctionSpace]{getNormal}{} 
313 
If the domain of functions in the \FunctionSpace 
314 
is a hypermanifold (e.g. the boundary of a domain) 
315 
the method returns the outer normal at each of the 
316 
\DataSamplePoints. Otherwise an exception is raised. 
317 
\end{methoddesc} 
318 

319 
\begin{methoddesc}[FunctionSpace]{getSize}{} 
320 
returns a \Data objects measuring the spacing of the \DataSamplePoints. 
321 
The size may be zero. 
322 
\end{methoddesc} 
323 

324 
\begin{methoddesc}[FunctionSpace]{getDomain}{} 
325 
returns the \Domain of the \FunctionSpace. 
326 
\end{methoddesc} 
327 

328 
\begin{methoddesc}[FunctionSpace]{__eq__}{arg} 
329 
returns \True of the \Domain \var{arg} describes the same domain. Otherwise 
330 
\False is returned. 
331 
\end{methoddesc} 
332 

333 
\begin{methoddesc}[FunctionSpace]{__ne__}{arg} 
334 
returns \True of the \Domain \var{arg} describes the note same domain. 
335 
Otherwise \False is returned. 
336 
\end{methoddesc} 
337 

338 
The following function provide generators for \FunctionSpace objects: 
339 
\begin{funcdesc}{Function}{domain} 
340 
returns the \Function on the \Domain \var{domain}. \Data objects in this type of \Function 
341 
are defined over the whole geometrical region defined by \var{domain}. 
342 
\end{funcdesc} 
343 

344 
\begin{funcdesc}{ContinuousFunction}{domain} 
345 
returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function 
346 
are defined over the whole geometrical region defined by \var{domain} and assumed to represent 
347 
a continuous function. 
348 
\end{funcdesc} 
349 

350 
\begin{funcdesc}{FunctionOnBoundary}{domain} 
351 
returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function 
352 
are defined on the boundary of the geometrical region defined by \var{domain}. 
353 
\end{funcdesc} 
354 

355 
\begin{funcdesc}{FunctionOnContactZero}{domain} 
356 
returns the \FunctionOnContactZero the \Domain domain. \Data objects in this type of \Function 
357 
are defined on side 0 of a discontinutiy within the geometrical region defined by \var{domain}. 
358 
The discontinutiy is defined when \var{domain} is instantiated. 
359 
\end{funcdesc} 
360 

361 
\begin{funcdesc}{FunctionOnContactOne}{domain} 
362 
returns the \FunctionOnContactOne on the \Domain domain. 
363 
\Data objects in this type of \Function 
364 
are defined on side 1 of a discontinutiy within the geometrical region defined by \var{domain}. 
365 
The discontinutiy is defined when \var{domain} is instantiated. 
366 
\end{funcdesc} 
367 

368 
\begin{funcdesc}{Solution}{domain} 
369 
returns the \SolutionFS on the \Domain domain. \Data objects in this type of \Function 
370 
are defined on geometrical region defined by \var{domain} and are solutions of 
371 
partial differential equations \index{partial differential equation}. 
372 
\end{funcdesc} 
373 

374 
\begin{funcdesc}{ReducedSolution}{domain} 
375 
returns the \ReducedSolutionFS on the \Domain domain. \Data objects in this type of \Function 
376 
are defined on geometrical region defined by \var{domain} and are solutions of 
377 
partial differential equations \index{partial differential equation} with a reduced smoothness 
378 
for the solution approximation. 
379 
\end{funcdesc} 
380 

381 
\section{\Data Class} 
382 

383 

384 
The following table shows binary and unitary operations that can be applied to 
385 
\Data objects: 
386 
\begin{tableii}{ll}{textrm}{expression}{Description} 
387 
\lineii{+\var{arg1}} {just \var{arg} \index{+}} 
388 
\lineii{\var{arg1}} {swapping the sign\index{}} 
389 
\lineii{\var{arg1}+\var{arg2}} {adds \var{arg1} and \var{arg2} \index{+}} 
390 
\lineii{\var{arg1}*\var{arg2}} {multiplies \var{arg1} and \var{arg2} \index{*}} 
391 
\lineii{\var{arg1}\var{arg2}} {difference \var{arg2} from\var{arg2} \index{}} 
392 
\lineii{\var{arg1}/\var{arg2}} {ratio \var{arg1} by \var{arg2} \index{/}} 
393 
\lineii{\var{arg1}**\var{arg2}} {raises \var{arg1} to the power of \var{arg2} \index{**}} 
394 
\end{tableii} 
395 
At least on of the arguments \var{arg1} or \var{arg2} must be a 
396 
\Data object. One of the arguments may be an object that can be 
397 
converted into a \Data object. If \var{arg1} or \var{arg2} are 
398 
defined on different \FunctionSpace it is tried to embed \var{arg1} 
399 
into the \FunctionSpace of \var{arg2} or to embed \var{arg2} into 
400 
the \FunctionSpace of \var{arg1}. Boths arguments must have the same 
401 
\Shape or one of the arguments my be of rank 0 or \Shape (1,). In the 
402 
latter case it is assumed that the particular argument is of the same 
403 
\Shape like the other argument but constant over all components. 
404 

405 
The returned \Data object has the same \Shape and is defined on 
406 
the \DataSamplePoints like \var{arg1} or \var{arg2}. 
407 

408 
The following table shows the update operations that can be applied to 
409 
\Data objects: 
410 
\begin{tableii}{ll}{textrm}{expression}{Description} 
411 
\lineii{\var{arg1}+=\var{arg2}} {adds \var{arg1} to \var{arg2} \index{+}} 
412 
\lineii{\var{arg1}*=\var{arg2}} {multiplies \var{arg1} with \var{arg2} \index{*}} 
413 
\lineii{\var{arg1}=\var{arg2}} {subtracts \var{arg2} from\var{arg2} \index{}} 
414 
\lineii{\var{arg1}/=\var{arg2}} {divides \var{arg1} by \var{arg2} \index{/}} 
415 
\end{tableii} 
416 
\var{arg1} must be a \Data object. \var{arg1} must be a 
417 
\Data object or an object that can be converted into a 
418 
\Data object. \var{arg1} must have the same \Shape like 
419 
\var{arg1} or has rank 0 or \Shape (1,). In the latter case it is 
420 
assumed that the values of \var{arg1} are constant for all 
421 
components. \var{arg2} must be defined on the same \DataSamplePoints like 
422 
\var{arg1} or it must be possible to interpolate \var{arg2} onto the 
423 
\DataSamplePoints where \var{arg1} is hold. 
424 

425 
The \Data class supports getting slices as well as assigning new values to components in an existing 
426 
\Data object \index{slicing}. 
427 
The following expression for getting (expression on the right hand side of the 
428 
equal sign) and setting slices (expression on the left hand side of the 
429 
equal sign) are valid: 
430 
\begin{tableiii}{lll}{textrm}{rank of \var{arg}}{slicing expression}{\Shape of returned and assigned object} 
431 
\lineiii{0}{ no slicing } {} 
432 
\lineiii{1}{\var{arg[l0:u0]}} {(\var{u0}\var{l0},)} 
433 
\lineiii{2}{\var{arg[l0:u0,l1:u1]}} {(\var{u0}\var{l0},\var{u1}\var{l1})} 
434 
\lineiii{3}{\var{arg[l0:u0,l1:u1,l2:u2]} } {(\var{u0}\var{l0},\var{u1}\var{l1},\var{u2}\var{l2})} 
435 
\lineiii{4}{\var{arg[l0:u0,l1:u1,l2:u2,l3:u3]}} {(\var{u0}\var{l0},\var{u1}\var{l1},\var{u2}\var{l2},\var{u3}\var{l3})} 
436 
\end{tableiii} 
437 
where 
438 
$0 \le \var{l0} \le \var{u0} \le \var{s[0]}$, 
439 
$0 \le \var{l1} \le \var{u1} \le \var{s[1]}$, 
440 
$0 \le \var{l2} \le \var{u2} \le \var{s[2]}$, 
441 
$0 \le \var{l3} \le \var{u3} \le \var{s[3]}$ and \var{s} the \Shape if \var{arg}. 
442 
Any of the lower indexes \var{l0}, \var{l1}, \var{l2} and \var{l3} may not be present in which case 
443 
$0$ is assumed. 
444 
Any of the upper indexes \var{u0}, \var{u1}, \var{u2} and \var{u3} may not be present in which case 
445 
\var{s} is assumed. The lower and upper index may be identical, in which case the column and the lower or upper 
446 
index may be dropped. In the returned or in the object assigned to a slice the corresponding component is dropped, 
447 
i.e. the rank is reduced by one in comparison to \var{arg}. 
448 
The follwing examples showing the usage of slicing: 
449 
\begin{python} 
450 
t[1,1,1,0]=9. 
451 
s=t[:2,:,2:6,5] # s has rank 3 
452 
s[:,:,1]=1. 
453 
t[:2,:2,5,5]=s[2:4,1,:2] 
454 
\end{python} 
455 

456 

457 

458 
\begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expanded=\False} 
459 
creates a \Data object with \Shape \var{shape} in the \FunctionSpace \var{what}. 
460 
The values at all \DataSamplePoints are set to the double value \var{value}. If \var{expanded} is \True 
461 
the \Data object is represented in expanded from. 
462 
\end{classdesc} 
463 

464 
\begin{classdesc}{Data}{value,what=FunctionSpace(),expanded=\False} 
465 
creates a \Data object in the \FunctionSpace \var{what}. 
466 
The value for each \DataSamplePoints is set to \numarray object \var{value}. 
467 
The \Shape of the returned object is equal to the \Shape of \var{value}. If \var{expanded} is \True 
468 
the \Data object is represented in expanded from. 
469 
\end{classdesc} 
470 

471 
\begin{classdesc}{Data}{value,what=FunctionSpace()} 
472 
creates a \Data object in the \FunctionSpace \var{what} from the \Data object \var{value}. 
473 
The \Shape of the created \Data object is equal to the \Shape of \var{value}. 
474 
If the \FunctionSpace of \var{value} is equal to the \var{what}, a shallow copy, i.e. 
475 
a reference to the representation of \var{value} is greated. Otherwise, 
476 
\var{value} is interpolated into the \var{what}. 
477 
\end{classdesc} 
478 

479 
\begin{classdesc}{Data}{} 
480 
creates an \EmptyData object. The \EmptyData object is used to indicate that an argument is not present 
481 
where a \Data object is required. 
482 
\end{classdesc} 
483 

484 
\begin{methoddesc}[Data]{getFunctionSpace}{} 
485 
returns the \FunctionSpace of the object. 
486 
\end{methoddesc} 
487 

488 
\begin{methoddesc}[Data]{getFunctionSpace}{} 
489 
returns the \Domain of the object. 
490 
\end{methoddesc} 
491 

492 
\begin{methoddesc}[Data]{getShape}{} 
493 
returns the \Shape of the object as a \class{tuple} of 
494 
integers. 
495 
\end{methoddesc} 
496 

497 
\begin{methoddesc}[Data]{getRank}{} 
498 
returns the rank of the data on each data point. \index{rank} 
499 
\end{methoddesc} 
500 

501 
\begin{methoddesc}[Data]{isEmpty}{} 
502 
returns \True id the \Data object is the \EmptyData object. 
503 
Otherwise \False is returned. 
504 
\end{methoddesc} 
505 

506 
\begin{methoddesc}[Data]{setTaggedValue}{tag,value} 
507 
assigns the \var{value} to all \DataSamplePoints which have the tag 
508 
\var{tag}. \var{value} must be an object of class 
509 
\class{numarray.array} or must be convertable into a 
510 
\class{numarray.array} object. \var{value} (or the cooresponding 
511 
\class{numarray.array} object) must be of rank $0$ or must have the 
512 
same rank like the object. 
513 
If a value has already be defined for tag \var{tag} within the object 
514 
it is overwritten by the new \var{value}. If the object is expanded, 
515 
the value assigned to \DataSamplePoints with tag \var{tag} is replaced by 
516 
\var{value}. 
517 
\end{methoddesc} 
518 

519 
\begin{methoddesc}[Data]{wherePositive}{} 
520 
returns \Data object which has the same \Shape and is defined on 
521 
the same \FunctionSpace like the object. The returned values are $1$ 
522 
where the object is positive and $0$ elsewhere. 
523 
\end{methoddesc} 
524 

525 
\begin{methoddesc}[Data]{wherePositive}{} 
526 
returns \Data object which has the same \Shape and is defined on 
527 
the same \FunctionSpace like the object. The returned values are $1$ 
528 
where the object is nonpositive and $0$ elsewhere. 
529 
\end{methoddesc} 
530 

531 
\begin{methoddesc}[Data]{whereNonnegative}{} 
532 
returns \Data object which has the same \Shape and is defined on 
533 
the same \FunctionSpace like the object. The returned values are $1$ 
534 
where the object is nonnegative and $0$ elsewhere. 
535 
\end{methoddesc} 
536 

537 
\begin{methoddesc}[Data]{whereNegative}{} 
538 
returns \Data object which has the same \Shape and is defined on 
539 
the same \FunctionSpace like the object. The returned values are $1$ 
540 
where the object is negative and $0$ elsewhere. 
541 
\end{methoddesc} 
542 

543 
\begin{methoddesc}[Data]{whereZero}{tolerance=1.e8} 
544 
returns \Data object which has the same \Shape and is defined on 
545 
the same \FunctionSpace like the object. The returned values are $1$ 
546 
where the object is nearly zero, i.e. where the absolute value is less 
547 
than \var{tolerance}, and $0$ elsewhere. 
548 
\end{methoddesc} 
549 

550 
\begin{methoddesc}[Data]{whereNonzero}{tolerance=1.e8} 
551 
returns \Data object which has the same \Shape and is defined on 
552 
the same \FunctionSpace like the object. The returned values are $1$ 
553 
where the object is nearly nonzero, i.e. where the absolute value is 
554 
greater or equal than \var{tolerance}, and $0$ elsewhere. 
555 
\end{methoddesc} 
556 

557 
\begin{methoddesc}[Data]{sign}{} 
558 
returns \Data object which has the same \Shape and is defined on 
559 
the same \FunctionSpace like the object. The returned values are $1$ 
560 
where the object is positive, $1$ where the value is negative and $0$ elsewhere. 
561 
\end{methoddesc} 
562 

563 
\begin{methoddesc}[Data]{copyWithMask}{arg,mask} 
564 
copies the \Data object \var{arg} into the object 
565 
where the \Data object \var{mask} is positive. \var{arg} 
566 
and \var{mask} must have the same \Shape 
567 
and must belong to same \FunctionSpace as 
568 
the object. 
569 
\end{methoddesc} 
570 

571 
\begin{methoddesc}[Data]{Lsup}{} 
572 
returns the $L^{sup}$norm of the object. This is maximum absolute values over all components and all \DataSamplePoints. \index{$L^{sup}$norm}. 
573 
\end{methoddesc} 
574 
\begin{methoddesc}[Data]{inf}{} 
575 
returns the minimum value (infimum) of the object. The minimum is 
576 
taken over all components and all \DataSamplePoints . \index{infimum} 
577 
\end{methoddesc} 
578 

579 
\begin{methoddesc}[Data]{sup}{} 
580 
returns the maximum value (supremum) of the object. The maximum is 
581 
taken over all components and all \DataSamplePoints . \index{supremum} 
582 
\end{methoddesc} 
583 

584 
\begin{methoddesc}[Data]{grad}{\optional{on}} 
585 
returns the gradient of the function represented by the object. 
586 
\Data object is in \FunctionSpace \var{on} and has rank r+1 where r is the rank of the object. 
587 
If \var{on} is not present, a suitbale \FunctionSpace is used. 
588 
\index{gradient} 
589 
\end{methoddesc} 
590 

591 
\begin{methoddesc}[Data]{integrate}{} 
592 
returns the integral of the function represented by the object. The method returns 
593 
a \class{numarray.array} object of the same \Shape like the object. A 
594 
component of the returned object is the integral of the corresponding 
595 
component of the object. \index{integral} 
596 
\end{methoddesc} 
597 

598 
\begin{methoddesc}[Data]{interpolate}{on} 
599 
interpolates 
600 
the function represented by the object 
601 
into the \FunctionSpace\var{on}. 
602 
\index{interpolation} 
603 
\end{methoddesc} 
604 

605 
\begin{methoddesc}[Data]{abs}{} 
606 
applies the absolute value function to the object. The 
607 
return \Data object has the same \Shape and is in the same 
608 
\FunctionSpace like the object. For all \DataSamplePoints and all 
609 
components the value is calculated by applying the exponential 
610 
function. \index{function!absolute value} 
611 
\end{methoddesc} 
612 

613 
\begin{methoddesc}[Data]{exp}{} 
614 
applies the exponential function to the object. The 
615 
return \Data object has the same \Shape and is in the same 
616 
\FunctionSpace like the object. For all \DataSamplePoints and all 
617 
components the value is calculated by applying the exponential 
618 
function. \index{function!exponential} 
619 
\end{methoddesc} 
620 

621 
\begin{methoddesc}[Data]{sqrt}{} 
622 
applies the square root function to the object. The 
623 
return \Data object has the same \Shape and is in the same 
624 
\FunctionSpace like the object. For all \DataSamplePoints and all 
625 
components the value is calculated by applying the square root function. 
626 
An exception is 
627 
raised if the value is negative. \index{function!square root} 
628 
\end{methoddesc} 
629 

630 
\begin{methoddesc}[Data]{sin}{} 
631 
applies the sine function to the object. The 
632 
return \Data object has the same \Shape and is in the same 
633 
\FunctionSpace like the object. For all \DataSamplePoints and all 
634 
components the value is calculated by applying the sine function. \index{function!sine} 
635 
\end{methoddesc} 
636 

637 
\begin{methoddesc}[Data]{cos}{} 
638 
applies the cosine function to the object. The 
639 
return \Data object has the same \Shape and is in the same 
640 
\FunctionSpace like the object. For all \DataSamplePoints and all 
641 
components the value is calculated by applying the cosine function. \index{function!cosine} 
642 
\end{methoddesc} 
643 

644 
\begin{methoddesc}[Data]{tan}{} 
645 
applies the tangent function to the object. The 
646 
return \Data object has the same \Shape and is in the same 
647 
\FunctionSpace like the object. For all \DataSamplePoints and all 
648 
components the value is calculated by applying the tangent function. \index{function!tangent} 
649 
\end{methoddesc} 
650 

651 
\begin{methoddesc}[Data]{log}{} 
652 
applies the logarithmic function to the object. The 
653 
return \Data object has the same \Shape and is in the same 
654 
\FunctionSpace like the object. For all \DataSamplePoints and all 
655 
components the value is calculated by applying the logarithmic function. An exception is 
656 
raised if the value is negative.\index{function!logarithmic} 
657 
\end{methoddesc} 
658 

659 
\begin{methoddesc}[Data]{maxval}{} 
660 
returns the maximum value over all components. The 
661 
return value is a \Data object of rank 0 
662 
and is in the same 
663 
\FunctionSpace like the object. For all \DataSamplePoints 
664 
the value is calculated as the maximum value over all components. \index{function!maximum} 
665 
\end{methoddesc} 
666 

667 
\begin{methoddesc}[Data]{minval}{} 
668 
returns the minimum value over all components. The 
669 
return value is a \Data object of rank 0 
670 
and is in the same 
671 
\FunctionSpace like the object. For all \DataSamplePoints 
672 
the value is calculated as the minimum value over all components. \index{function!minimum} 
673 
\end{methoddesc} 
674 

675 
\begin{methoddesc}[Data]{length}{} 
676 
returns the Euclidean length at all \DataSamplePoints. The 
677 
return value is a \Data object of rank 0 
678 
and is in the same 
679 
\FunctionSpace like the object. For all \DataSamplePoints 
680 
the value is calculated as the square root of the sum of the square over all over all components. \index{function!length} 
681 
\end{methoddesc} 
682 
\begin{methoddesc}[Data]{transpose}{axis} 
683 
returns the transpose of the object around \var{axis}. \var{axis} is a nonnegative integer 
684 
which is less the rank $r$ of the object. Transpose swaps the indexes $0$ to \var{axis} 
685 
with the indexes \var{axis}+1 to $r$. If the \var{d} is \RankFour one has 
686 
\begin{python} 
687 
d[i,j,k,l]=d.transpose(0)[i,j,k,l] 
688 
d[i,j,k,l]=d.transpose(1)[j,k,l,i] 
689 
d[i,j,k,l]=d.transpose(2)[k,l,i,j] 
690 
d[i,j,k,l]=d.transpose(3)[l,i,j,k] 
691 
\end{python} 
692 
\index{function!transpose} 
693 
\end{methoddesc} 
694 

695 
\begin{methoddesc}[Data]{trace}{} 
696 
returns sum of the components with identical indexes. 
697 
The 
698 
return value is a \Data object of rank 0 
699 
and is in the same 
700 
\FunctionSpace like the object. 
701 
\index{function!trace} 
702 
\end{methoddesc} 
703 
\begin{methoddesc}[Data]{saveDX}{fileName} 
704 
saves the object to an openDX format file of name \var{fileName}, see 
705 
\ulink{www.opendx.org}{\url{www.opendx.org}}. \index{openDX} 
706 
\end{methoddesc} 
707 

708 

709 
For convenience the following factories are provided to created \Data object: 
710 

711 
\begin{funcdesc}{Scalar}{value=0.,what=escript::FunctionSpace(),expand=\False} 
712 
returns a \Data object of rank 0 in the \FunctionSpace \var{what}. 
713 
Values are initialed with the double \var{value}. If \var{expanded} is \True 
714 
the \Data object is represented in expanded from. 
715 
\end{funcdesc} 
716 

717 
\begin{funcdesc}{Vector}{value=0.,what=escript::FunctionSpace(),expand=\False} 
718 
returns a \Data object of \Shape \var{(d,)} in the \FunctionSpace \var{what} 
719 
where \var{d} is the spatial dimension of the \Domain of \var{what}. 
720 
Values are initialed with the double \var{value}. If \var{expanded} is \True 
721 
the \Data object is represented in expanded from. 
722 
\end{funcdesc} 
723 

724 
\begin{funcdesc}{Tensor}{value=0.,what=escript::FunctionSpace(),expand=\False} 
725 
returns a \Data object of \Shape \var{(d,d)} in the \FunctionSpace \var{what} 
726 
where \var{d} is the spatial dimension of the \Domain of \var{what}. 
727 
Values are initialed with the double \var{value}. If \var{expanded} is \True 
728 
the \Data object is represented in expanded from. 
729 
\end{funcdesc} 
730 

731 
\begin{funcdesc}{Tensor3}{value=0.,what=escript::FunctionSpace(),expand=\False} 
732 
returns a \Data object of \Shape \var{(d,d,d)} in the \FunctionSpace \var{what} 
733 
where \var{d} is the spatial dimension of the \Domain of \var{what}. 
734 
Values are initialed with the double \var{value}. If \var{expanded} is \True 
735 
the \Data object is re\var{arg}presented in expanded from. 
736 
\end{funcdesc} 
737 

738 
\begin{funcdesc}{Tensor4}{value=0.,what=escript::FunctionSpace(),expand=\False} 
739 
returns a \Data object of \Shape \var{(d,d,d,d)} in the \FunctionSpace \var{what} 
740 
where \var{d} is the spatial dimension of the \Domain of \var{what}. 
741 
Values are initialed with the double \var{value}. If \var{expanded} is \True 
742 
the \Data object is represented in expanded from. 
743 
\end{funcdesc} 
744 

745 
\begin{funcdesc}{abs}{arg} 
746 
returns the absolute value of \var{arg} where \var{arg} 
747 
can be double, a \Data object or an \numarray object. 
748 
\end{funcdesc} 
749 

750 
\begin{funcdesc}{sin}{arg} 
751 
returns the sine of \var{arg} where \var{arg} 
752 
can be double, a \Data object or an \numarray object. 
753 
\end{funcdesc} 
754 

755 
\begin{funcdesc}{cos}{arg} 
756 
returns the cosine of \var{arg} where \var{arg} 
757 
can be double, a \Data object or an \numarray object. 
758 
\end{funcdesc} 
759 

760 
\begin{funcdesc}{exp}{arg} 
761 
returns the value of the exponential function for \var{arg} where \var{arg} 
762 
can be double, a \Data object or an \numarray object. 
763 
\end{funcdesc} 
764 

765 
\begin{funcdesc}{sqrt}{arg} 
766 
returns the square root of \var{arg} where \var{arg} 
767 
can be double, a \Data object or an \numarray object. 
768 
\end{funcdesc} 
769 

770 
\begin{funcdesc}{maxval}{arg} 
771 
returns the maximum value over all component of \var{arg} where \var{arg} 
772 
can be double, a \Data object or an \numarray object. 
773 
\end{funcdesc} 
774 

775 
\begin{funcdesc}{minval}{arg} 
776 
returns the minumum value over all component of \var{arg} where \var{arg} 
777 
can be double, a \Data object or an \numarray object. 
778 
\end{funcdesc} 
779 

780 
\begin{funcdesc}{length}{arg} 
781 
returns the length of \var{arg} which is the 
782 
square root of the sum of the squares of all component of \var{arg}. \var{arg} 
783 
can be double, a \Data object or an \numarray object. 
784 
\end{funcdesc} 
785 

786 
\begin{funcdesc}{sign}{arg} 
787 
return the sign of \var{arg} where \var{arg} 
788 
can be double, a \Data object or an \numarray object. 
789 
\end{funcdesc} 
790 

791 
\begin{funcdesc}{transpose}{arg,\optional{axis}} 
792 
returns the transpose of \var{arg} around \var{axis}. \var{axis} is a nonnegative integer 
793 
which is less the rank $r$ of the object. Transpose swaps the indexes $0$ to \var{axis} 
794 
with the indexes \var{axis}+1 to $r$. If \var{axis} is not present, \var{axis}=$r/2$ is assumed. 
795 
\var{arg} 
796 
may be a \Data object or an \numarray object. 
797 
\end{funcdesc} 
798 

799 
\begin{funcdesc}{transpose}{arg,\optional{axis}} 
800 
returns the trace the object of \var{arg}. The trace is the sum over those components 
801 
with identical indexed. 
802 
\var{arg} 
803 
may be a \Data object or a \numarray object. 
804 
\end{funcdesc} 
805 

806 
\begin{funcdesc}{sum}{arg} 
807 
returns the sum over all components and all 
808 
\DataSamplePoints of \var{arg}, where \var{arg} 
809 
is a \Data object. 
810 
\end{funcdesc} 
811 

812 
\begin{funcdesc}{sup}{arg} 
813 
returns the maximum over all components and all 
814 
\DataSamplePoints of \var{arg}, where \var{arg} 
815 
is a \Data object. 
816 
\end{funcdesc} 
817 

818 
\begin{funcdesc}{inf}{arg} 
819 
returns the mimumum over all components and all 
820 
\DataSamplePoints of \var{arg}, where \var{arg} 
821 
is a \Data object. 
822 
\end{funcdesc} 
823 

824 

825 
\begin{funcdesc}{L2}{arg} 
826 
returns the $L^2$ norm of \var{arg}. This is the square root 
827 
of the sum of the squared value over all components and all 
828 
\DataSamplePoints of \var{arg}, where \var{arg} 
829 
is a \Data object. 
830 
\end{funcdesc} 
831 

832 
\begin{funcdesc}{Lsup}{arg} 
833 
returns the $L^{sup}$ norm of \var{arg}. This is the maximum of the absolute values 
834 
over all components and all 
835 
\DataSamplePoints of \var{arg}, where \var{arg} 
836 
is a \Data object. 
837 
\end{funcdesc} 
838 

839 
\begin{funcdesc}{dot}{arg1,arg2} 
840 
returns the dot product of of \var{arg1} and \var{arg2}. This is sum 
841 
of the product of corresponding entries in \var{arg1} and \var{arg2} over all 
842 
components and and all 
843 
\DataSamplePoints. \var{arg1} and \var{arg2} are \Data objects of the 
844 
same \Shape and in the same \FunctionSpace. 
845 
\end{funcdesc} 
846 

847 
\begin{funcdesc}{grad}{arg,\optional{where}} 
848 
returns the gradient of \var{arg} as a function in the \FunctionSpace \var{where}. 
849 
If \var{where} is not present a reasonable \FunctionSpace is chosen. 
850 
\var{arg} 
851 
is a \Data object. 
852 
\end{funcdesc} 
853 

854 
\begin{funcdesc}{integrate}{arg} 
855 
returns the integral of \var{arg} as a \numarray object. 
856 
If \var{where} is not present a reasonable \FunctionSpace is chosen. 
857 
\var{arg} 
858 
is a \Data object. 
859 
\end{funcdesc} 
860 

861 
\begin{funcdesc}{interpolate}{arg,where} 
862 
interpolate \Data object \var{arg} into the \FunctionSpace \var{where} 
863 
\end{funcdesc} 
864 

865 

866 
\section{\Operator Class} 
867 

868 
The \Operator class provides an abstract access to operators build 
869 
within the \LinearPDE class. \Operator objects are created 
870 
when a PDE is handed over to a PDE solver library and handled 
871 
by the \LinearPDE class defining the PDE. The user can gain access 
872 
to the \Operator of a \LinearPDE object through the \var{getOperator} 
873 
method. 
874 

875 
\begin{classdesc}{Operator}{} 
876 
creates an empty \Operator object. 
877 
\end{classdesc} 
878 

879 
\begin{methoddesc}[Operator]{isEmpty}{fileName} 
880 
returns \True is the object is empty. Otherwise \True is returned. 
881 
\end{methoddesc} 
882 

883 
\begin{methoddesc}[Operator]{setValue}{value} 
884 
resets all entires in the obeject representation to \var{value} 
885 
\end{methoddesc} 
886 

887 
\begin{methoddesc}[Operator]{solves}{rhs} 
888 
solves the operator equation with right hand side \var{rhs} 
889 
\end{methoddesc} 
890 

891 
\begin{methoddesc}[Operator]{of}{u} 
892 
applies the operator to the \Data object \var{u} 
893 
\end{methoddesc} 
894 

895 
\begin{methoddesc}[Operator]{saveMM}{fileName} 
896 
saves the object to a matrix market format file of name 
897 
\var{fileName}, see 
898 
\ulink{maths.nist.gov/MatrixMarket}{\url{http://maths.nist.gov/MatrixMarket}}. 
899 
\index{Matrix Market} 
900 
\end{methoddesc} 
901 
