1 

2 
% $Id$ 
3 

4 
\chapter{The module \escript} 
5 

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

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

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

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

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

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

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

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

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

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

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

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

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

234 
The \Data class provides a transparent interface to various data representations and the 
235 
translations between them. As shown in the example of stress calculation, this allows the user to 
236 
develop and test algorithms for a simple case (for instance with the Lame coefficients as constants) 
237 
and then without further modifications of the program code to apply the algorithm in a 
238 
more complex application (for instance a definition of the Lame coefficients using tags). 
239 
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): 
240 
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. 
241 
Any operation on this constant data will only be performed on the single value. 
242 
In the expanded case, each sample point has an individual value, eg. the solution of a PDE, 
243 
and the values are stored as a complete array. The tagged case has already been discussed above. 
244 

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

251 

252 

253 
\section{\Domain class} 
254 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

382 
\section{\Data Class} 
383 
\label{SEC ESCRIPT DATA} 
384 

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

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

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

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

457 

458 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

709 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

825 

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

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

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

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

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

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

866 

867 
\section{\Operator Class} 
868 

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

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

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

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

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

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

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