14 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
15 
% 
% 
16 


17 
\chapter{The module \escript} 
\chapter{The Module \escript} 
18 
\label{ESCRIPT CHAP} 
\label{ESCRIPT CHAP} 
19 


20 


24 
function space at the starting point can be interpreted as a function in the function space of the arrow target.} 
function space at the starting point can be interpreted as a function in the function space of the arrow target.} 
25 
\end{figure} 
\end{figure} 
26 


27 
\escript is an extension of Python to handle functions represented by their values on 
\escript is a Python module that allows you to represent the values of 
28 
\DataSamplePoints for the geometrical region on which 
a function at points in a \Domain in such a way that the function will 
29 
the function is defined. The region as well as the method which is used 
be useful for the Finite Element Method (FEM) simulation. It also 
30 
to interpolate value on the \DataSamplePoints is defined by 
provides what we call a function space that describes how the data is 
31 
\Domain class objects. For instance when using 
used in the simulation. Stored along with the data is information 
32 
the finite element method (FEM) \index{finite element method} 
about the elements and nodes which will be used by \finley. 
33 
\Domain object holds the information about the FEM mesh, eg. 

34 
a table of nodes and a table of elements. Although \Domain contains 
In order to understand what we mean by the term 'function space' 
35 
the discretization method to be used \escript does not use this information directly. 
consider that the solution of a partial differential equation 
36 
\Domain objects are created from a module which want to make use 
\index{partial differential equation} (PDE) is a function on a domain 
37 
\escript, e.g. \finley. 
$\Omega$. When solving a PDE using FEM the solution is 
38 

piecewisedifferentiable but, in general, its gradient is 
39 
The solution of a PDE is a function of its location in the domain of interest $\Omega$. 
discontinuous. To reflect these different degrees of smoothness 
40 
When solving a partial differential equation \index{partial differential equation} (PDE) using FEM 
different function spaces are used. For instance, in FEM the 
41 
the solution is (piecewise) differentiable but, in general, its gradient 
displacement field is represented by its values at the nodes of the 
42 
is discontinuous. To reflect these different degrees of smoothness different 
mesh, and is then continuous. The strain, which is the symmetric 
43 
representations of the functions are used. For instance; in FEM 
part of the gradient of the displacement field, is stored on the 
44 
the displacement field is represented by its values at the nodes of the mesh, while the 
element centers, and so is considered to be discontinuous. 
45 
strain, which is the symmetric part of the gradient of the displacement field, is stored on the 

46 
element centers. To be able to classify functions with respect to their smoothness, \escript has the 
A function space is described by a \FunctionSpace object. The 
47 
concept of the "function space". A function space is described by a \FunctionSpace object. 
following statement generates the object \var{solution_space} which is 
48 
The following statement generates the object \var{solution_space} which is 
a \FunctionSpace object and provides access to the function space of 

a \FunctionSpace object and provides access to the function space of 

49 
PDE solutions on the \Domain \var{mydomain}: 
PDE solutions on the \Domain \var{mydomain}: 
50 


51 
\begin{python} 
\begin{python} 
52 
solution_space=Solution(mydomain) 
solution_space=Solution(mydomain) 
53 
\end{python} 
\end{python} 
54 
The following generators for function spaces on a \Domain \var{mydomain} are available: 
The following generators for function spaces on a \Domain \var{mydomain} are available: 
55 
\begin{itemize} 
\begin{itemize} 
61 
\item \var{FunctionOnContact0(mydomain)}: functions on side $0$ of the discontinuity. 
\item \var{FunctionOnContact0(mydomain)}: functions on side $0$ of the discontinuity. 
62 
\item \var{FunctionOnContact1(mydomain)}: functions on side $1$ of the discontinuity. 
\item \var{FunctionOnContact1(mydomain)}: functions on side $1$ of the discontinuity. 
63 
\end{itemize} 
\end{itemize} 
64 


65 
The reduced smoothness for PDE solution is often used to fulfill the Ladyzhenskaya–Babuska–Brezzi condition \cite{LBB} when 
The reduced smoothness for PDE solution is often used to fulfill the Ladyzhenskaya–Babuska–Brezzi condition \cite{LBB} when 
66 
solving saddle point problems \index{saddle point problems}, eg. the Stokes equation. 
solving saddle point problems \index{saddle point problems}, eg. the Stokes equation. 
67 
A discontinuity \index{discontinuity} is a region within the domain across which functions may be discontinuous. 
A discontinuity \index{discontinuity} is a region within the domain across which functions may be discontinuous. 
68 
The location of discontinuity is defined in the \Domain object. 
The location of discontinuity is defined in the \Domain object. 
69 
\fig{ESCRIPT DEP} shows the dependency between the types of function spaces. 
\fig{ESCRIPT DEP} shows the dependency between the types of function spaces. 
70 


71 
The solution of a PDE is a continuous function. Any continuous function can be seen as a general function 
The solution of a PDE is a continuous function. Any continuous function can be seen as a general function 
72 
on the domain and can be restricted to the boundary as well as to any side of the 
on the domain and can be restricted to the boundary as well as to any side of the 
73 
discontinuity (the result will be different depending on 
discontinuity (the result will be different depending on 
74 
which side is chosen). Functions on any side of the 
which side is chosen). Functions on any side of the 
75 
discontinuity can be seen as a function on the corresponding other side. 
discontinuity can be seen as a function on the corresponding other side. 
76 


77 
A function on the boundary or on one side of 
A function on the boundary or on one side of 
78 
the discontinuity cannot be seen as a general function on the domain as there are no values 
the discontinuity cannot be seen as a general function on the domain as there are no values 
79 
defined for the interior. For most PDE solver libraries 
defined for the interior. For most PDE solver libraries 
80 
the space of the solution and continuous functions is identical, however in some cases, eg. 
the space of the solution and continuous functions is identical, however in some cases, eg. 
81 
when periodic boundary conditions are used in \finley, a solution 
when periodic boundary conditions are used in \finley, a solution 
82 
fulfills periodic boundary conditions while a continuous function does not have to be periodic. 
fulfills periodic boundary conditions while a continuous function does not have to be periodic. 
83 


84 
The concept of function spaces describes the properties of 
The concept of function spaces describes the properties of 
85 
functions and allows abstraction from the actual representation 
functions and allows abstraction from the actual representation 
86 
of the function in the context of a particular application. For instance, 
of the function in the context of a particular application. For instance, 
87 
in the FEM context a 
in the FEM context a 
88 
function in the \Function function space 
function of the \Function type 
89 
is typically represented by its values at the element center, 
is usually represented by its values at the element center, 
90 
but in a finite difference scheme the edge midpoint of cells is preferred. 
but in a finite difference scheme the edge midpoint of cells is preferred. 
91 
Using the concept of function spaces 
By changing its function space you can use the same function in a Finite Difference 
92 
allows the user to run the same script on different 
scheme instead of Finite Element scheme. 

PDE solver libraries by just changing the creator of the \Domain object. 

93 
Changing the function space of a particular function 
Changing the function space of a particular function 
94 
will typically lead to a change of its representation. 
will typically lead to a change of its representation. 
95 
So, when seen as a general function, 
So, when seen as a general function, 
96 
a continuous function which is typically represented by its values 
a continuous function which is typically represented by its values 
97 
on the node of the FEM mesh or finite difference grid 
on the node of the FEM mesh or finite difference grid 
98 
must be interpolated to the element centers or the cell edges, 
must be interpolated to the element centers or the cell edges, 
99 
respectively. 
respectively. Interpolation happens automatically in \escript 
100 

whenever it is required. 
101 


102 
\Data class objects store functions of the location in a domain. 
In \escript the class that stores these functions is called \Data. 
103 
The function is represented through its values on \DataSamplePoints where 
The function is represented through its values on \DataSamplePoints where 
104 
the \DataSamplePoints are chosen according to the function space 
the \DataSamplePoints are chosen according to the function space 
105 
of the function. 
of the function. 
106 
\Data class objects are used to define the coefficients 
\Data class objects are used to define the coefficients 
107 
of the PDEs to be solved by a PDE solver library 
of the PDEs to be solved by a PDE solver library 
108 
and to store the returned solutions. 
and also to store the solutions of the PDE. 
109 


110 
The values of the function have a rank which gives the 
The values of the function have a rank which gives the 
111 
number of indices, and a \Shape defining the range of each index. 
number of indices, and a \Shape defining the range of each index. 
121 
continuous function with values 
continuous function with values 
122 
of \Shape $(2,3)$ and rank $2$: 
of \Shape $(2,3)$ and rank $2$: 
123 
\begin{python} 
\begin{python} 
124 
mydat=Data(value=1,what=ContinuousFunction(myDomain),shape=(2,3)) 
mydat=Data(value=1,what=ContinuousFunction(myDomain),shape=(2,3)) 
125 
\end{python} 
\end{python} 
126 
The initial value is the constant $1$ for all \DataSamplePoints and 
The initial value is the constant $1$ for all \DataSamplePoints and 
127 
all components. 
all components. 
132 
The following two statements 
The following two statements 
133 
create objects which are equivalent to \var{mydat}: 
create objects which are equivalent to \var{mydat}: 
134 
\begin{python} 
\begin{python} 
135 
mydat1=Data(value=numarray.ones((2,3)),what=ContinuousFunction(myDomain)) 
mydat1=Data(value=numarray.ones((2,3)),what=ContinuousFunction(myDomain)) 
136 
mydat2=Data(value=[[1,1],[1,1],[1,1]],what=ContinuousFunction(myDomain)) 
mydat2=Data(value=[[1,1],[1,1],[1,1]],what=ContinuousFunction(myDomain)) 
137 
\end{python} 
\end{python} 
138 
In the first case the initial value is \var{numarray.ones((2,3))} 
In the first case the initial value is \var{numarray.ones((2,3))} 
139 
which generates a $2 \times 3$ matrix as a \numarray.NumArray 
which generates a $2 \times 3$ matrix as a \numarray.NumArray 
160 
is consistent with \Shape of the \Data object to be created can be used as the initial value. 
is consistent with \Shape of the \Data object to be created can be used as the initial value. 
161 


162 
\Data objects can be manipulated by applying unitary operations (eg. cos, sin, log) 
\Data objects can be manipulated by applying unitary operations (eg. cos, sin, log) 
163 
and can be combined by applying binary operations (eg. +,  ,* , /). 
and can be combined pointwise by applying arithmetic operations (eg. +,  ,* , /). 
164 
It is to be emphasized that \escript itself does not handle any spatial dependencies as 
It is to be emphasized that \escript itself does not handle any spatial dependencies as 
165 
it does not know how values are interpreted by the processing PDE solver library. 
it does not know how values are interpreted by the processing PDE solver library. 
166 
However \escript invokes interpolation if this is needed during data manipulations. 
However \escript invokes interpolation if this is needed during data manipulations. 
179 
takes the displacement {\tt u} and the Lame coefficients 
takes the displacement {\tt u} and the Lame coefficients 
180 
\var{lam} and \var{mu} as arguments and returns the corresponding stress: 
\var{lam} and \var{mu} as arguments and returns the corresponding stress: 
181 
\begin{python} 
\begin{python} 
182 
from esys.escript import * 
from esys.escript import * 
183 
def getStress(u,lam,mu): 
def getStress(u,lam,mu): 
184 
d=u.getDomain().getDim() 
d=u.getDomain().getDim() 
185 
g=grad(u) 
g=grad(u) 
186 
stress=lam*trace(g)*kronecker(d)+mu*(g+transpose(g)) 
stress=lam*trace(g)*kronecker(d)+mu*(g+transpose(g)) 
187 
return stress 
return stress 
188 
\end{python} 
\end{python} 
189 
The variable 
The variable 
190 
\var{d} gives the spatial dimension of the 
\var{d} gives the spatial dimension of the 
193 
$i$ and $j$ running from $0$ to \var{d}1. The call \var{grad(u)} requires 
$i$ and $j$ running from $0$ to \var{d}1. The call \var{grad(u)} requires 
194 
the displacement field \var{u} to be in the \var{Solution} or \ContinuousFunction 
the displacement field \var{u} to be in the \var{Solution} or \ContinuousFunction 
195 
function space. The result \var{g} as well as the returned stress will be in the \Function function space. 
function space. The result \var{g} as well as the returned stress will be in the \Function function space. 
196 
If \var{u} is available, eg. by solving a PDE, \var{getStress} might be called 
If, for example, \var{u} is the solution of a PDE then \var{getStress} might be called 
197 
in the following way: 
in the following way: 
198 
\begin{python} 
\begin{python} 
199 
s=getStress(u,1.,2.) 
s=getStress(u,1.,2.) 
200 
\end{python} 
\end{python} 
201 
However \var{getStress} can also be called with \Data objects as values for 
However \var{getStress} can also be called with \Data objects as values for 
202 
\var{lam} and \var{mu} which, 
\var{lam} and \var{mu} which, 
203 
for instance in the case of a temperature dependency, are calculated by an expression. 
for instance in the case of a temperature dependency, are calculated by an expression. 
204 
The following call is equivalent to the previous example: 
The following call is equivalent to the previous example: 
205 
\begin{python} 
\begin{python} 
206 
lam=Scalar(1.,ContinuousFunction(mydomain)) 
lam=Scalar(1.,ContinuousFunction(mydomain)) 
207 
mu=Scalar(2.,Function(mydomain)) 
mu=Scalar(2.,Function(mydomain)) 
208 
s=getStress(u,lam,mu) 
s=getStress(u,lam,mu) 
209 
\end{python} 
\end{python} 
210 


211 
The function \var{lam} belongs to the \ContinuousFunction function space 
The function \var{lam} belongs to the \ContinuousFunction function space 
212 
but with \var{g} the function \var{trace(g)} is in the \Function function space. 
but with \var{g} the function \var{trace(g)} is in the \Function function space. 
213 
Therefore the evaluation of the product \var{lam*trace(g)} in the stress calculation 
In the evaluation of the product \var{lam*trace(g)} we have different function 
214 
produces a problem, as both functions are represented differently, eg. in FEM 
spaces (on the nodes versus in the centers) and at first glance we have incompatible data. 
215 
\var{lam} by its values on the node, and in \var{trace(g)} by its values at the element centers. 
\escript converts the arguments in an appropriate function space according to 
216 
In the case of inconsistent function spaces of arguments in a binary operation, \escript 
Table~\ref{ESCRIPT DEP}. In this example that means 
217 
interprets the arguments in the appropriate function space according to the inclusion 
\escript sees \var{lam} as a function of the \Function function space. 

defined in Table~\ref{ESCRIPT DEP}. In this example that means 


\escript sees \var{lam} as a function of the \Function function space. 

218 
In the context of FEM this means the nodal values of 
In the context of FEM this means the nodal values of 
219 
\var{lam} are interpolated to the element centers. Behind the scenes 
\var{lam} are interpolated to the element centers. 
220 
\escript calls the appropriate function from the PDE solver library. 
The interpolation is automatic and requires no special handling. 
221 


222 
\begin{figure} 
\begin{figure} 
223 
\includegraphics[width=\textwidth]{figures/EscriptDiagram2.eps} 
\includegraphics[width=\textwidth]{figures/EscriptDiagram2.eps} 
227 
\end{figure} 
\end{figure} 
228 


229 
Material parameters such as the Lame coefficients are typically dependent on rock types present in the 
Material parameters such as the Lame coefficients are typically dependent on rock types present in the 
230 
area of interest. A common technique to handle these kinds of material parameters is "tagging". \fig{Figure: tag} 
area of interest. A common technique to handle these kinds of material parameters is "tagging", which 
231 

uses storage efficiently. \fig{Figure: tag} 
232 
shows an example. In this case two rock types {\it white} and {\it gray} can be found in the domain. The domain 
shows an example. In this case two rock types {\it white} and {\it gray} can be found in the domain. The domain 
233 
is subdivided into triangular shaped cells. Each 
is subdivided into triangular shaped cells. Each 
234 
cell has a tag indicating the rock type predominately found in this cell. Here $1$ is used to indicate 
cell has a tag indicating the rock type predominately found in this cell. Here $1$ is used to indicate 
240 
example of \fig{Figure: tag} and the stress calculation discussed before tagged values are used for 
example of \fig{Figure: tag} and the stress calculation discussed before tagged values are used for 
241 
\var{lam}: 
\var{lam}: 
242 
\begin{python} 
\begin{python} 
243 
lam=Scalar(value=2.,what=Function(mydomain)) 
lam=Scalar(value=2.,what=Function(mydomain)) 
244 
insertTaggedValue(lam,white=30.,gray=5000.) 
insertTaggedValue(lam,white=30.,gray=5000.) 
245 
s=getStress(u,lam,2.) 
s=getStress(u,lam,2.) 
246 
\end{python} 
\end{python} 
247 
In this example \var{lam} is set to $30$ for those cells with tag {\it white} (=$1$) and to $5000.$ for those cells 
In this example \var{lam} is set to $30$ for those cells with tag {\it white} (=$1$) and to $5000.$ for those cells 
248 
with tag {\it gray} (=$2$_. The initial value $2$ of \var{lam} is used as a default value for the case when a tag 
with tag {\it gray} (=$2$_. The initial value $2$ of \var{lam} is used as a default value for the case when a tag 
249 
is encountered which has not been linked with a value. Note that the \var{getStress} method 
is encountered which has not been linked with a value. The \var{getStress} method 
250 
is called without modification. \escript resolves the tags when \var{lam*trace(g)} is calculated. 
does not need to be changed now that we are using tags. 
251 

\escript resolves the tags when \var{lam*trace(g)} is calculated. 
252 


253 

This brings us to a very important point about \escript. 
254 

You can develop a simulation with constant Lame coefficients, and then later switch to tagged 
255 

Lame coefficients without otherwise changing your python script. 
256 

In short, you can use the same script to model with different domains and different types of input data. 
257 


258 

There are three ways in which \Data objects are represented internally: constant, tagged, and expanded. 
259 

In the constant case, the same value is used at each sample point and only a single value is stored to save memory. 
260 

In the expanded case, each sample point has an individual value (such as for the solution of a PDE). 
261 

This is where your largest data sets will be created because the values are stored as a complete array. 
262 

The tagged case has already been discussed above. 
263 


264 
The \Data class provides a transparent interface to various data representations and the 
Expanded data is created when you create a \Data object with expanded=True. 
265 
translations between them. As shown in the example of stress calculation, this allows the user to 
Tagged data sets are created when you use the insertTaggedValue() method as shown above. 

develop and test algorithms for a simple case (for instance with the Lame coefficients as constants) 


and then without further modifications of the program code to apply the algorithm in a 


more complex application (for instance a definition of the Lame coefficients using tags). 


As described here, there are three ways in which \Data objects are represented internally, constant, 


tagged, and expanded (other representations will become available in later versions of \escript): 


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. 


Any operation on this constant data will only be performed on the single value. 


In the expanded case, each sample point has an individual value, eg. the solution of a PDE, 


and the values are stored as a complete array. The tagged case has already been discussed above. 

266 


267 
Values are accessed through a sample reference number. Operations on expanded \Data 
Values are accessed through a sample reference number. Operations on expanded \Data 
268 
objects have to be performed for each sample point individually. If tagged values are used values are 
objects have to be performed for each sample point individually. When tagged values are used the values are 
269 
held in a dictionary. Operations on tagged data require processing the set of tagged values only, rather than 
held in a dictionary. Operations on tagged data require processing the set of tagged values only, rather than 
270 
processing the value for each individual sample point. 
processing the value for each individual sample point. 
271 
\escript allows use of constant, tagged and expanded data in a single expression. 
\escript allows any mixture of constant, tagged and expanded data in a single expression. 
272 


273 
The \var{dump} method provides a possibility to save \Data objects to a file, for instance to restart a simulation 
\Data objects can be written to disk files and read with \var{dump} and \var{load}, both of which use \netCDF. 
274 
or to save data for visualization. The file format uses \netCDF which commonly is using the file extension 
Use these to save data for visualization, checkpoint/restart or simply to save and reuse data that was expensive to compute. 
275 
{\tt nc}. For instance to save the coordinates of the data points of the \FunctionSpace 

276 
\ContinuousFunction to the file {\tt x.nc} one uses: 
For instance to save the coordinates of the data points of the \FunctionSpace 
277 

\ContinuousFunction to the file {\tt x.nc} use 
278 
\begin{python} 
\begin{python} 
279 
x=ContinuousFunction(mydomain).getX() 
x=ContinuousFunction(mydomain).getX() 
280 
x.dump("x.nc") 
x.dump("x.nc") 
281 
\end{python} 
\end{python} 
282 
In order to keep the dump files small {\tt x.nc} does not contain a representation of the \Domain. It has to be saved using 
To recover the object \var{x} use 

appropriate methods of \var{mydomain} to be loaded before \var{x}. Alternatively, the \Domain can be reconstructed. 


To recover the object \var{x} one uses 

283 
\begin{python} 
\begin{python} 
284 
x=load("x.nc", mydomain) 
x=load("x.nc", mydomain) 
285 
\end{python} 
\end{python} 
286 
The \Data object represented by {\tt x.nc} is tight to a \FunctionSpace  in this case \ContinuousFunction  but not 
The dump file {\tt x.nc} does not contain a representation of the \Domain, even though it is required to recreate \var{x}. 
287 
o a \Domain. That means that \Data objects that are constant or tagged can be recovered with any \Domain. If the \Data object 
It's common to simply recreate the \Domain before reading a \Data, or you may read and write your \Domain in a separate file with 
288 

\var{domain=ReadMesh(fileName)} and \var{domain.write(fileName)}. 
289 


290 

The function space of the \Data is stored in {\tt x.nc}, though. 
291 

That means that \Data objects that are constant or tagged can be recovered with a different \Domain. If the \Data object 
292 
is expanded, the number of data points in the file and of the \Domain for the particular \FunctionSpace must match. 
is expanded, the number of data points in the file and of the \Domain for the particular \FunctionSpace must match. 
293 
Moreover, the ordering of the value is checked using the reference identifiers provided by 
Moreover, the ordering of the values is checked using the reference identifiers provided by 
294 
\FunctionSpace on the \Domain. In some cases, data points will be reordered. 
\FunctionSpace on the \Domain. In some cases, data points will be reordered. Take care to be sure you get what you want! 
295 


296 


297 
\section{\escript Classes} 
\section{\escript Classes} 
456 
\subsection{\Data Class} 
\subsection{\Data Class} 
457 
\label{SEC ESCRIPT DATA} 
\label{SEC ESCRIPT DATA} 
458 


459 
The following table shows binary and unitary operations that can be applied to 
The following table shows arithmetic operations that can be performed pointwise on 
460 
\Data objects: 
\Data objects. 
461 
\begin{tableii}{ll}{textrm}{expression}{Description} 
\begin{tableii}{ll}{textrm}{expression}{Description} 
462 
\lineii{+\var{arg0}} {just \var{arg} \index{+}} 
\lineii{+\var{arg0}} {identical to \var{arg} \index{+}} 
463 
\lineii{\var{arg0}} {swapping the sign\index{}} 
\lineii{\var{arg0}} {negation\index{}} 
464 
\lineii{\var{arg0}+\var{arg1}} {adds \var{arg0} and \var{arg1} \index{+}} 
\lineii{\var{arg0}+\var{arg1}} {adds \var{arg0} and \var{arg1} \index{+}} 
465 
\lineii{\var{arg0}*\var{arg1}} {multiplies \var{arg0} and \var{arg1} \index{*}} 
\lineii{\var{arg0}*\var{arg1}} {multiplies \var{arg0} and \var{arg1} \index{*}} 
466 
\lineii{\var{arg0}\var{arg1}} {difference \var{arg1} from\var{arg1} \index{}} 
\lineii{\var{arg0}\var{arg1}} {difference \var{arg1} from\var{arg1} \index{}} 
467 
\lineii{\var{arg0}/\var{arg1}} {ratio \var{arg0} by \var{arg1} \index{/}} 
\lineii{\var{arg0}/\var{arg1}} {divide \var{arg0} by \var{arg1} \index{/}} 
468 
\lineii{\var{arg0}**\var{arg1}} {raises \var{arg0} to the power of \var{arg1} \index{**}} 
\lineii{\var{arg0}**\var{arg1}} {raises \var{arg0} to the power of \var{arg1} \index{**}} 
469 
\end{tableii} 
\end{tableii} 
470 
At least one of the arguments \var{arg0} or \var{arg1} must be a 
At least one of the arguments \var{arg0} or \var{arg1} must be a 
471 
\Data object. One of the arguments may be an object that can be 
\Data object. 
472 
converted into a \Data object. If \var{arg0} or \var{arg1} are 
Either of the arguments may be a \Data object, a python number or a numarray object. 
473 
defined on different \FunctionSpace an attempt is made to embed \var{arg0} 

474 
into the \FunctionSpace of \var{arg1} or to embed \var{arg1} into 
If \var{arg0} or \var{arg1} are 
475 

defined on different \FunctionSpace an attempt is made to convert \var{arg0} 
476 

to the \FunctionSpace of \var{arg1} or to convert \var{arg1} to 
477 
the \FunctionSpace of \var{arg0}. Both arguments must have the same 
the \FunctionSpace of \var{arg0}. Both arguments must have the same 
478 
\Shape or one of the arguments may be of rank 0. In the 
\Shape or one of the arguments may be of rank 0 (a constant). 

latter case it is assumed that the particular argument is of the same 


\Shape as the other argument but constant over all components. 

479 


480 
The returned \Data object has the same \Shape and is defined on 
The returned \Data object has the same \Shape and is defined on 
481 
the \DataSamplePoints as \var{arg0} or \var{arg1}. 
the \DataSamplePoints as \var{arg0} or \var{arg1}. 
498 
\var{arg0} or it must be possible to interpolate \var{arg1} onto the 
\var{arg0} or it must be possible to interpolate \var{arg1} onto the 
499 
\FunctionSpace of \var{arg1}. 
\FunctionSpace of \var{arg1}. 
500 


501 
The \Data class supports getting slices as well as assigning new values to components in an existing 
The \Data class supports taking slices from a \Data object as well as assigning new values to a slice of an existing 
502 
\Data object. \index{slicing} 
\Data object. \index{slicing} 
503 
The following expression for getting (expression on the right hand side of the 
The following expressions for taking and setting slices are valid: 

equal sign) and setting slices (expression on the left hand side of the 


equal sign) are valid: 

504 
\begin{tableiii}{lll}{textrm}{rank of \var{arg}}{slicing expression}{\Shape of returned and assigned object} 
\begin{tableiii}{lll}{textrm}{rank of \var{arg}}{slicing expression}{\Shape of returned and assigned object} 
505 
\lineiii{0}{ no slicing } {} 
\lineiii{0}{ no slicing } {} 
506 
\lineiii{1}{\var{arg[l0:u0]}} {(\var{u0}\var{l0},)} 
\lineiii{1}{\var{arg[l0:u0]}} {(\var{u0}\var{l0},)} 
519 
\var{s} is assumed. The lower and upper index may be identical, in which case the column and the lower or upper 
\var{s} is assumed. The lower and upper index may be identical, in which case the column and the lower or upper 
520 
index may be dropped. In the returned or in the object assigned to a slice the corresponding component is dropped, 
index may be dropped. In the returned or in the object assigned to a slice the corresponding component is dropped, 
521 
i.e. the rank is reduced by one in comparison to \var{arg}. 
i.e. the rank is reduced by one in comparison to \var{arg}. 
522 
The following examples show slicing usage: 
The following examples show slicing in action: 
523 
\begin{python} 
\begin{python} 
524 
t=Data(1.,(4,4,6,6),Function(mydomain)) 
t=Data(1.,(4,4,6,6),Function(mydomain)) 
525 
t[1,1,1,0]=9. 
t[1,1,1,0]=9. 
526 
s=t[:2,:,2:6,5] # s has rank 3 
s=t[:2,:,2:6,5] # s has rank 3 
527 
s[:,:,1]=1. 
s[:,:,1]=1. 
528 
t[:2,:2,5,5]=s[2:4,1,:2] 
t[:2,:2,5,5]=s[2:4,1,:2] 
529 
\end{python} 
\end{python} 
530 


531 
\subsection{Generation of \Data class objects} 
\subsection{Generation of \Data class objects} 
538 
\begin{classdesc}{Data}{value,what=FunctionSpace(),expand=\False} 
\begin{classdesc}{Data}{value,what=FunctionSpace(),expand=\False} 
539 
creates a \Data object in the \FunctionSpace \var{what}. 
creates a \Data object in the \FunctionSpace \var{what}. 
540 
The value for each \DataSamplePoints is set to \numarray, \Data object \var{value} or a dictionary of 
The value for each \DataSamplePoints is set to \numarray, \Data object \var{value} or a dictionary of 
541 
\numarray or floating point numbers. In the latter case the keys muts be integers and are used 
\numarray or floating point numbers. In the latter case the keys must be integers and are used 
542 
as tags. 
as tags. 
543 
The \Shape of the returned object is equal to the \Shape of \var{value}. If \var{expanded} is \True 
The \Shape of the returned object is equal to the \Shape of \var{value}. If \var{expanded} is \True 
544 
the \Data object is represented in expanded from. 
the \Data object is represented in expanded form. 
545 
\end{classdesc} 
\end{classdesc} 
546 


547 
\begin{classdesc}{Data}{} 
\begin{classdesc}{Data}{} 
550 
\end{classdesc} 
\end{classdesc} 
551 


552 
\begin{funcdesc}{Scalar}{value=0.,what=escript::FunctionSpace(),expand=\False} 
\begin{funcdesc}{Scalar}{value=0.,what=escript::FunctionSpace(),expand=\False} 
553 
returns a \Data object of rank 0 in the \FunctionSpace \var{what}. 
returns a \Data object of rank 0 (a constant) in the \FunctionSpace \var{what}. 
554 
Values are initialed with the double \var{value}. If \var{expanded} is \True 
Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True 
555 
the \Data object is represented in expanded from. 
the \Data object is represented in expanded from. 
556 
\end{funcdesc} 
\end{funcdesc} 
557 


558 
\begin{funcdesc}{Vector}{value=0.,what=escript::FunctionSpace(),expand=\False} 
\begin{funcdesc}{Vector}{value=0.,what=escript::FunctionSpace(),expand=\False} 
559 
returns a \Data object of \Shape \var{(d,)} in the \FunctionSpace \var{what} 
returns a \Data object of \Shape \var{(d,)} in the \FunctionSpace \var{what} 
560 
where \var{d} is the spatial dimension of the \Domain of \var{what}. 
where \var{d} is the spatial dimension of the \Domain of \var{what}. 
561 
Values are initialed with the double \var{value}. If \var{expanded} is \True 
Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True 
562 
the \Data object is represented in expanded from. 
the \Data object is represented in expanded from. 
563 
\end{funcdesc} 
\end{funcdesc} 
564 


565 
\begin{funcdesc}{Tensor}{value=0.,what=escript::FunctionSpace(),expand=\False} 
\begin{funcdesc}{Tensor}{value=0.,what=escript::FunctionSpace(),expand=\False} 
566 
returns a \Data object of \Shape \var{(d,d)} in the \FunctionSpace \var{what} 
returns a \Data object of \Shape \var{(d,d)} in the \FunctionSpace \var{what} 
567 
where \var{d} is the spatial dimension of the \Domain of \var{what}. 
where \var{d} is the spatial dimension of the \Domain of \var{what}. 
568 
Values are initialed with the double \var{value}. If \var{expanded} is \True 
Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True 
569 
the \Data object is represented in expanded from. 
the \Data object is represented in expanded from. 
570 
\end{funcdesc} 
\end{funcdesc} 
571 


572 
\begin{funcdesc}{Tensor3}{value=0.,what=escript::FunctionSpace(),expand=\False} 
\begin{funcdesc}{Tensor3}{value=0.,what=escript::FunctionSpace(),expand=\False} 
573 
returns a \Data object of \Shape \var{(d,d,d)} in the \FunctionSpace \var{what} 
returns a \Data object of \Shape \var{(d,d,d)} in the \FunctionSpace \var{what} 
574 
where \var{d} is the spatial dimension of the \Domain of \var{what}. 
where \var{d} is the spatial dimension of the \Domain of \var{what}. 
575 
Values are initialed with the double \var{value}. If \var{expanded} is \True 
Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True 
576 
the \Data object is re\var{arg}presented in expanded from. 
the \Data object is re\var{arg}presented in expanded from. 
577 
\end{funcdesc} 
\end{funcdesc} 
578 


579 
\begin{funcdesc}{Tensor4}{value=0.,what=escript::FunctionSpace(),expand=\False} 
\begin{funcdesc}{Tensor4}{value=0.,what=escript::FunctionSpace(),expand=\False} 
580 
returns a \Data object of \Shape \var{(d,d,d,d)} in the \FunctionSpace \var{what} 
returns a \Data object of \Shape \var{(d,d,d,d)} in the \FunctionSpace \var{what} 
581 
where \var{d} is the spatial dimension of the \Domain of \var{what}. 
where \var{d} is the spatial dimension of the \Domain of \var{what}. 
582 
Values are initialed with the double \var{value}. If \var{expanded} is \True 
Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True 
583 
the \Data object is represented in expanded from. 
the \Data object is represented in expanded from. 
584 
\end{funcdesc} 
\end{funcdesc} 
585 


586 
\begin{funcdesc}{load}{filename,domain} 
\begin{funcdesc}{load}{filename,domain} 
587 
recovers a \Data object on \Domain \var{domain} from the dump file \var{filename}. 
recovers a \Data object on \Domain \var{domain} from the file \var{filename}, which was created by \var{dump}. 
588 
\end{funcdesc} 
\end{funcdesc} 
589 


590 
\subsection{\Data class methods} 
\subsection{\Data class methods} 
591 
This is a list of frequently used methods of the 
These are the most frequentlyused methods of the 
592 
\Data class. A complete list can be fond on \ReferenceGuide. 
\Data class. A complete list of methods can be found on \ReferenceGuide. 
593 
\begin{methoddesc}[Data]{getFunctionSpace}{} 
\begin{methoddesc}[Data]{getFunctionSpace}{} 
594 
returns the \FunctionSpace of the object. 
returns the \FunctionSpace of the object. 
595 
\end{methoddesc} 
\end{methoddesc} 
642 
writes \Data defined by keywords in the file with \var{filename} using the 
writes \Data defined by keywords in the file with \var{filename} using the 
643 
vtk file format \VTK file format. The key word is used as an identifier. The statement 
vtk file format \VTK file format. The key word is used as an identifier. The statement 
644 
\begin{python} 
\begin{python} 
645 
saveVTK("out.xml",temperature=T,velocity=v) 
saveVTK("out.xml",temperature=T,velocity=v) 
646 
\end{python} 
\end{python} 
647 
will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the 
will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the 
648 
file \file{out.xml}. Restrictions on the allowed combinations of \FunctionSpace apply. 
file \file{out.xml}. Restrictions on the allowed combinations of \FunctionSpace apply. 
651 
writes \Data defined by keywords in the file with \var{filename} using the 
writes \Data defined by keywords in the file with \var{filename} using the 
652 
vtk file format \OpenDX file format. The key word is used as an identifier. The statement 
vtk file format \OpenDX file format. The key word is used as an identifier. The statement 
653 
\begin{python} 
\begin{python} 
654 
saveDX("out.dx",temperature=T,velocity=v) 
saveDX("out.dx",temperature=T,velocity=v) 
655 
\end{python} 
\end{python} 
656 
will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the 
will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the 
657 
file \file{out.dx}. Restrictions on the allowed combinations of \FunctionSpace apply. 
file \file{out.dx}. Restrictions on the allowed combinations of \FunctionSpace apply. 