# Diff of /trunk/esys2/doc/user/escript.tex

revision 100 by jgs, Wed Dec 15 03:48:48 2004 UTC revision 107 by jgs, Thu Jan 27 06:21:48 2005 UTC
# Line 1  Line 1
1
2  % $Id$  % $Id$
3
4  \chapter{The module \escript}  \chapter{The module \escript}
5
6  \declaremodule{extension}{escript} \modulesynopsis{Handling data on  \declaremodule{extension}{escript}
7  data points like \class{Nodes}, \class{Elements}}  \modulesynopsis{Data manipulation}
8
9  The class \Data of the module \escript allows handling  \begin{figure}
10  data which are hold on data points \index{data points}. Examples for  \includegraphics[width=\textwidth]{EscriptDiagram1.eps}
11  data points are nodes or the quadrature points in elements of a finite  \caption{\label{ESCRIPT DEP}Dependency of Function Spaces. An arrow indicates that a function in the
12  element mesh. Another examples a particles or the connection between  function space at the starting point can be interpreted as a function in the function space of the arrow target.}
13  particles in the case of discrete element methods.  Handlers to data  \end{figure}
14  points are issued by the structure which contains the data points,
15  e.g. a \finley mesh.  \escript is an extension of Python to handle functions represented by their values on
16    \DataSamplePoints for the geometrical region on which
17  The simplest form of data attached to a data point is a single scalar  the function is defined. The region as well as the method which is used
18  $a$ value which for instance represent the temperature or pressure at  to interpolate value on the \DataSamplePoints is defined by
19  this particular data point. Another example is a velocity field. in  \Domain class objects. For instance when using
20  this case each data point holds a vector $a(0),a(1),a(2)$ representing  the finite element method (FEM) \index{finite element method}
21  the velocity at the particular data point. For the case that the  \Domain object holds the information about the FEM mesh, eg.
22  values are representing a stress tensor the value is a matrix of the  a table of nodes and a table of elements. Although \Domain contains
23  form  the discretization method to be used \escript does not use this information directly.
24  $a(0,0),a(0,1),a(0,2),a(1,0),a(1,1),a(1,2),a(2,0),a(2,1),a(2,2)$. In  \Domain objects are created from a module which want to make use
25  general, values hald by data points can have up to four indices. The  \escript, e.g. \finley.
26  number of indices is called rank \index{rank}. The tuple of length
27  rank which defines the upper-bound for each index component is called  The solution of a PDE is a function of its location in the domain of interest $\Omega$.
28  the shape. A stress has rank 2 and the shape is (3,3). For a vector we  When solving a partial differential equation \index{partial differential equation} (PDE) using FEM
29  have rank 1 and shape (3,). A scalar can have rank 0 or rank 1 with  the solution is (piecewise) differentiable but, in general, its gradient
30  shape (1,).  is discontinuous. To reflect these different degrees of smoothness different
31    representations of the functions are used. For instance; in FEM
32  In general, the data are stored for each data point. This status of  the displacement field is represented by its values at the nodes of the mesh, while the
33  the data is called expanded \index{expanded}. But in some cases, all  strain, which is the symmetric part of the gradient of the displacement field, is stored on the
34  data points hold the same value. In this case only a single value is  element centers. To be able to classify functions with respect to their smoothness, \escript has the
35  stored, which is refered by each data point if needed. This saves  concept of the "function space". A function space is described by a \FunctionSpace object.
36  memory as well as compute time. In some cases, it is very usefull to  The following statement generates the object \var{solution_space} which is
37  have slightly more general way which allows to define piecewise  a \FunctionSpace object and provides access to the function space of
38  constant data. For this, each data point has to wear a tag which is an  PDE solutions on the \Domain \var{mydomain}:
39  integer \index{tag}. The tag is used to distingish between various  \begin{python}
40  types of data points. Typical example of the usage of tags is to  solution_space=Solution(mydomain)
41  assign different material parameters to various subdomains. Then one  \end{python}
42  assigns the same tag to all elements in a finite element mesh which  The following generators for function spaces on a \Domain \var{mydomain} are available:
43  lay in the same subdomain.  Later each tag can be assigns individual  \begin{itemize}
44  material parameters.  \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 linear--elastic 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()
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  The following table shows unitary operations that can be applied to an  \section{\Data Class}
383  \Data object \var{arg}:  \label{SEC ESCRIPT DATA}
\begin{tableii}{l|l}{textrm}{expression}{Description}
\lineii{+\var{arg}} {just \var{arg} \index{+}}
\lineii{-\var{arg}} {swapping the sign\index{-}}
\lineii{\function{abs}(\var{arg})} {absolute value}
\lineii{\function{sin}(\var{arg})} {sine function}
\lineii{\function{cos}(\var{arg})} {cosine function}
\lineii{\function{exp}(\var{arg})} {exponential function}
\lineii{\function{sqrt}(\var{arg})} {square root}
\end{tableii}
An unitary operation returns a \Data objects of the same shape
and defined on the data points like \var{arg}.
384
385  The following table shows binary operations that can be applied to  The following table shows binary and unitary operations that can be applied to
386  \Data objects:  \Data objects:
387  \begin{tableii}{l|l}{textrm}{expression}{Description}  \begin{tableii}{l|l}{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{+}}  \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{*}}  \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{-}}  \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{/}}  \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{**}}  \lineii{\var{arg1}**\var{arg2}} {raises \var{arg1} to the power of \var{arg2} \index{**}}
395  \end{tableii}  \end{tableii}
396  At least on of the arguments \var{arg1} or \var{arg2} must be a  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  \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  converted into a \Data object. If \var{arg1} or \var{arg2} are
399  defined on different data points it is tried to interpolate \var{arg1}  defined on different \FunctionSpace an attempt is made to embed \var{arg1}
400  onto the data points of \var{arg2} or to interpolate \var{arg2} onto  into the \FunctionSpace of \var{arg2} or to embed \var{arg2} into
401  the data points of \var{arg1}. Boths arguments must have the same  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  \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  latter case it is assumed that the particular argument is of the same
404  shape like the other argument but constant over all components.  \Shape as the other argument but constant over all components.
405
406  The returned \Data object has the same shape and is defined on  The returned \Data object has the same \Shape and is defined on
407  the data points like \var{arg1} or \var{arg2}.  the \DataSamplePoints as \var{arg1} or \var{arg2}.
408
409  The following table shows the update operations that can be applied to  The following table shows the update operations that can be applied to
410  \Data objects:  \Data objects:
# Line 88  The following table shows the update ope Line 416  The following table shows the update ope
416  \end{tableii}  \end{tableii}
417  \var{arg1} must be a \Data object. \var{arg1} must be a  \var{arg1} must be a \Data object. \var{arg1} must be a
418  \Data object or an object that can be converted into a  \Data object or an object that can be converted into a
419  \Data object. \var{arg1} must have the same shape like  \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  \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  assumed that the values of \var{arg1} are constant for all
422  components. \var{arg2} must be defined on the same data points like  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  \var{arg1} or it must be possible to interpolate \var{arg2} onto the
424  data points where \var{arg1} is hold.  \DataSamplePoints where \var{arg1} is held.

%TODO:
Slicing \index{slicing}.
425
426  \begin{classdesc}{Data}{}  The \Data class supports getting slices as well as assigning new values to components in an existing
427  A class that holds values assigned to data points.  \Data object. \index{slicing}
428  \end{classdesc}  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  \begin{classdesc}{Scalar}{value=None,where=None,expand=None}  equal sign) are valid:
431  A class that holds a single value per data point.  \begin{tableiii}{l|ll}{textrm}{rank of \var{arg}}{slicing expression}{\Shape of returned and assigned object}
432  \end{classdesc}  \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
\begin{classdesc}{Vector}{value=None,dim=None,where=None,expand=None}
A class that holds a vector per data point.
\end{classdesc}
457
\begin{classdesc}{Tensor}{value=None,dim=None,where=None,expand=None}
A class that holds a tensor order 2 (matrix) per data point.
\end{classdesc}
458
459  \begin{classdesc}{Tensor3}{value=None,dim=None,where=None,expand=None}  \begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expanded=\False}
460  A class that holds a tensor order 3 per data point.  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}  \end{classdesc}
479
480  \begin{classdesc}{Tensor4}{value=None,dim=None,where=None,expand=None}  \begin{classdesc}{Data}{}
481  A class that holds a tensor order 4 per data point.  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}  \end{classdesc}
484
485  \begin{funcdesc}{abs}{arg}  \begin{methoddesc}[Data]{getFunctionSpace}{}
486  returns the absulute value of \Data \var{arg}. The returned  returns the \FunctionSpace of the object.
487  \Data object has the same rank, shape and is defined on the  \end{methoddesc}
same \class{_Atom} like \var{arg}. An entries in the returned object
is the absolute value of the corresponding entry in \var{arg}.
\index{absolute value}
\end{funcdesc}

\begin{funcdesc}{L2}{arg}
returns the $L^2$-norm of the \Data \var{arg} by using method
\method{arg.L2()}.  \index{$L^2$-norm}
\end{funcdesc}

returns the gradient of the interpolation function of \Data
\end{funcdesc}

\begin{funcdesc}{integrate}{arg}
returns the integral of the interpolation function of \Data
\var{arg} by using \method{arg.integrate}. \index{integral}
\end{funcdesc}

\begin{funcdesc}{interpolate}{arg,where}
interpolates the \Data \var{arg} onto \class{_Atom} where by
using \method{arg.interpolate}. \index{interpolation}
\end{funcdesc}

\begin{funcdesc}{transpose}{arg}
returns the transpose of \var{arg} where \var{arg} has to be
\Data or \class{numarray.array}. If \var{arg} is of
\Data the method \method{arg.transpose} is used otherwise
\function{numarray.transpose} is called. \index{transpose}
\end{funcdesc}

\begin{funcdesc}{trace}{arg}
returns the trace of \var{arg} where \var{arg} has to be \Data
or \class{numarray.array} of rank 2. If \var{arg} is of \Data
the method \method{arg.trace} is used otherwise
\function{numarray.trace} is called. \index{trace}
\end{funcdesc}

\begin{funcdesc}{exp}{arg}
applies the exponential function to \var{arg} where \var{arg} has to
be \Data or \class{numarray.array}. If \var{arg} is of
\Data the method \method{arg.exp} is used otherwise
\function{numarray.exp} is called. \index{exponential function}
\end{funcdesc}

\begin{funcdesc}{sqrt}{arg}
applies the square root function to \var{arg} where \var{arg} has to
be \Data or \class{numarray.array}. If \var{arg} is of
\Data the method \method{arg.sqrt} is used otherwise
\function{numarray.sqrt} is called. \index{square root}
\end{funcdesc}

\begin{funcdesc}{sin}{arg}
applies the sine function to \var{arg} where \var{arg} has to be
\Data or \class{numarray.array}. If \var{arg} is of
\Data the method \method{arg.sin} is used otherwise
\function{numarray.sin} is called. \index{sine function}
\end{funcdesc}

\begin{funcdesc}{cos}{arg}
applies the cosine function to \var{arg} where \var{arg} has to be
\Data or \class{numarray.array}. If \var{arg} is of
\Data the method \method{arg.cos} is used otherwise
\function{numarray.cos} is called. \index{cosine function}
\end{funcdesc}

\begin{funcdesc}{maxval}{arg}
returns for each data point the maximum value over all components of
\Data \var{arg} by using \method{arg.maxval}.  \index{maximum
value}
\end{funcdesc}
488
489  \begin{funcdesc}{minval}{arg}  \begin{methoddesc}[Data]{getFunctionSpace}{}
490  returns for each data point the minimum value over all components of  returns the \Domain  of the object.
491  \Data \var{arg} by using \method{arg.minval}.  \index{minimum  \end{methoddesc}
value}
\end{funcdesc}
492
493  \begin{funcdesc}{inf}{arg}  \begin{methoddesc}[Data]{getShape}{}
494  returns the minimum value (infimum) over all components and all data  returns the \Shape  of the object as a \class{tuple} of
495  points of \Data \var{arg} by using \method{arg.inf}.  integers.
496  \index{infimum}  \end{methoddesc}
\end{funcdesc}
497
498  \begin{funcdesc}{sup}{arg}  \begin{methoddesc}[Data]{getRank}{}
499  returns the maximum value (supremum) over all components and all data  returns the rank of the data on each data point. \index{rank}
500  points of \Data \var{arg} by using \method{arg.sup}.  \end{methoddesc}
\index{supremum}
\end{funcdesc}
501
502  \begin{funcdesc}{Lsup}{arg}  \begin{methoddesc}[Data]{isEmpty}{}
503  returns the maximum absulute value ($L^{sup}$-norm) over all  returns \True id the \Data object is the \EmptyData object.
504  components and all data points of \Data \var{arg} by using  Otherwise \False is returned.
505  \method{arg.sup}.  The returned value equals  \end{methoddesc}
\function{sup}(\function(arg)).  \index{$L^{sup}$-norm}
\end{funcdesc}

\begin{funcdesc}{matmult}{arg1,arg2}
returns for each data point the matrix-matrix product of \var{arg1}
and \var{arg2} \index{matrix-matrix product}. At least of the
arguments \var{arg1} and \var{arg2} has to be a \Data
object. If the other argument is not a \Data object it must be
convertable into a \Data object. The returned \Data
object has rank \var{arg1.getRank()}+\var{arg2.getRank()}-2 and shape
(\var{arg1.getShape()}[r-1],\var{arg2.getShape()}[1:]), where
\var{r}=\var{arg1.getRank()}. The last dimension of \var{arg1} and the
first dimension of \var{arg2} have to match,
i.e. \var{arg1.getShape()[r-1]}=\var{arg2.getShape()[0]}

For the case that \var{arg1} and \var{arg2} are both of rank $2$ the
result \var{res} is calculated as

res(i,j;s)=
arg1(i,0;s) \cdot arg2(0,j;s)+
\ldots
arg1(i,n-1;s) \cdot arg2(n-1,j;s)

for all $0\le i <$ \var{arg1.getShape()[0]}, $0\le j <$
\var{arg2.getShape()[1]} and all data points $s$, where
$n$=\var{arg2.getShape()[0]},

If the arguments are not defined on the same data points, \var{arg1}
is tried to be interpolated on the data points of \var{arg2} or
\var{arg2} is tried to be interpolated on the data points of
\var{arg1}. What ever case works defines the data points of the
result.
\end{funcdesc}

%==================================================================
\section{\Data class}
\begin{classdesc}{Data}{value=None,shape=None,where=None,expand=None}
\end{classdesc}
506
507  \begin{methoddesc}[Data]{getAtoms}{}  \begin{methoddesc}[Data]{setTaggedValue}{tag,value}
508  returns a handel to the data points on which the object is definded  assigns the \var{value} to all \DataSamplePoints which have the tag
509  \index{data points}.  The returned object is of \class{_Atoms}.  \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}  \end{methoddesc}
519
520  \begin{methoddesc}[Data]{getShape}{}  \begin{methoddesc}[Data]{wherePositive}{}
521  returns the shape of the data on each data point as a \class{tuple} of  returns \Data object which has the same \Shape and is defined on
522  integers. \index{shape}  the same \FunctionSpace like the object. The returned values are $1$
523    where the object is positive and $0$ elsewhere.
524  \end{methoddesc}  \end{methoddesc}
525
526  \begin{methoddesc}[Data]{getRank}{}  \begin{methoddesc}[Data]{wherePositive}{}
527  returns the rank of the data on each data point. \index{rank}  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 non-positive and $0$ elsewhere.
530  \end{methoddesc}  \end{methoddesc}
531
532  \begin{methoddesc}[Data]{hasShape}{shape}  \begin{methoddesc}[Data]{whereNonnegative}{}
533  is true if the object has the shape \var{shape}.  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 non-negative and $0$ elsewhere.
536  \end{methoddesc}  \end{methoddesc}
537
538  \begin{methoddesc}[Data]{expand}{}  \begin{methoddesc}[Data]{whereNegative}{}
539  returns an expanded version of the object if the object is not  returns \Data object which has the same \Shape and is defined on
540  expanded. Otherwise it returns itself. \index{expanded}  the same \FunctionSpace like the object. The returned values are $1$
541    where the object is negative and $0$ elsewhere.
542  \end{methoddesc}  \end{methoddesc}
543
544  \begin{methoddesc}[Data]{makeExpanded}{}  \begin{methoddesc}[Data]{whereZero}{tolerance=1.e-8}
545  turns the object into an expanded \Data  returns \Data object which has the same \Shape and is defined on
546  object. \index{expanded}  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}  \end{methoddesc}
550
551  \begin{methoddesc}[Data]{isExpanded}{}  \begin{methoddesc}[Data]{whereNonzero}{tolerance=1.e-8}
552  is true if the object is expanded. \index{expanded}  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 non-zero, i.e. where the absolute value is
555    greater or equal than \var{tolerance}, and $0$ elsewhere.
556  \end{methoddesc}  \end{methoddesc}
557
558  \begin{methoddesc}[Data]{isTagged}{}  \begin{methoddesc}[Data]{sign}{}
559  is true if the object is defined using tags. \index{tagged}  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}  \end{methoddesc}
563
565  returns the object as a \class{numarray.array} array. The array is one  copies the \Data object \var{arg} into the object
566  rank higher than the rank of the object. The extra dimension is the  where the \Data object \var{mask} is positive. \var{arg}
567  number of data points.  and \var{mask} must have the same \Shape
568  % TODO: be more accurate on the shape  and must belong to same \FunctionSpace as
569    the object.
570  \end{methoddesc}  \end{methoddesc}
571
573  assigns the \var{value} to all data points which have the tag  returns the $L^{sup}$-norm of the object. This is maximum absolute values over all components and all \DataSamplePoints. \index{$L^{sup}$-norm}.
574  \var{tag} which has to be an integer or a list of  \end{methoddesc}
575  integers. \var{value} must be an object of class  \begin{methoddesc}[Data]{inf}{}
576  \class{numarray.array} or must be convertable into a  returns the minimum value (infimum) of the object. The minimum is
577  \class{numarray.array} object. \var{value} (or the cooresponding  taken over all components and all \DataSamplePoints .  \index{infimum}
578  \class{numarray.array} object) must be of rank $0$ or must have the  \end{methoddesc}
same rank like the object. \index{tagged}
579
580  If a value has allready be defined for tag \var{tag} within the object  \begin{methoddesc}[Data]{sup}{}
581  it is overwritten by the new \var{value}.  If the object is expanded,  returns the maximum value (supremum) of the object. The maximum is
582  the value assigned to data points with tag \var{tag} is replaced by  taken over all components and all \DataSamplePoints .  \index{supremum}
\var{value}.
583  \end{methoddesc}  \end{methoddesc}
584
586  returns the value assigned to \var{tag}. An exception is raised if the  returns the gradient of the function represented by the object.
587  object is not defined by tagged data, e.g. if the object is  \Data object is in \FunctionSpace \var{on} and has rank r+1 where r is the rank of the object.
588  expanded.\index{tagged}  If \var{on} is not present, a suitbale \FunctionSpace is used.
\end{methoddesc}

\begin{methoddesc}[Data]{L2}{}
returns the $L^2$-norm of the object. This is square root of sum of
the squares of all values over all components and all data points.
\index{$L^2$-norm}
\end{methoddesc}

returns the gradient of the interpolation function. The returned
\Data object is of rank r+1 where r is the rank of the object.
Typically the object of to be defined on nodes and the returned
590  \end{methoddesc}  \end{methoddesc}
591
592  \begin{methoddesc}[Data]{integrate}{}  \begin{methoddesc}[Data]{integrate}{}
593  returns the integral of the interpolation function. The method returns  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  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  component of the returned object is the integral of the corresponding
596  component of the object.  \index{integral}  component of the object. \index{integral}
597  \end{methoddesc}  \end{methoddesc}
598
599  \begin{methoddesc}[Data]{interpolate}{where}  \begin{methoddesc}[Data]{interpolate}{on}
600  interpolates onto the data points of the \class{_Atom}  interpolates
601  \var{where}. The returned \Data object is of the same shape  the function represented by the object
602  like the object and is defined on the data points \var{where}.  into the \FunctionSpace\var{on}.
603  \index{interpolation}  \index{interpolation}
604  \end{methoddesc}  \end{methoddesc}
605
606  \begin{methoddesc}[Data]{transpose}{}  \begin{methoddesc}[Data]{abs}{}
607  returns the transpose of the object. The return value is an object has  applies the absolute value function to the object. The
608  the same shape and is defined on the same data points like the object.  return \Data object has the same \Shape and is in the same
609  For each data point the value is set to transposed of the  \FunctionSpace like the object. For all \DataSamplePoints and all
610  corresponding value of the object by reversing the index of the data.  components the value is calculated by applying the exponential
611    function. \index{function!absolute value}
For the case that object \var{self} is of rank 3 the result \var{res} is

res(i,j,k;s)=self(k,j,i;s)

for all
$0\le i <$ \var{self.getShape()[2]},
$0\le j <$ \var{self.getShape()[1]},
$0\le k <$ \var{self.getShape()[0]}
and all data points $s$.
\index{transpose}
612  \end{methoddesc}  \end{methoddesc}
613
614  \begin{methoddesc}[Data]{trace}{}  \begin{methoddesc}[Data]{exp}{}
615  returns the trace of the object of rank 2. The return value is an  applies the exponential function to the object. The
616  object has rank 0 or shape (1,) and is defined on the same data points  return \Data object has the same \Shape and is in the same
617  like the object. For each data point the value is set to sum of the  \FunctionSpace like the object. For all \DataSamplePoints and all
618  main diagonal entries.  components the value is calculated by applying the exponential
619    function. \index{function!exponential}
For the case that object \var{self} is of rank 2 the result \var{res}
is

res(0;s)=
self(0,0;s)+
self(1,1;s)+
\ldots +
self(n,n;s)

for all data points $s$ where
$n=min($\var{self.getShape()[0]},\var{self.getShape()[1]}$)$.
\index{trace}
\end{methoddesc}

\begin{methoddesc}[Data]{exp}{}
applies the exponential function to the values of the object. The
return value is an object has the same shape and is defined on the
same data points like the object.  For each data point and all
components the value is calculated by applying the exponention
function to the corresponding value of the object.  \index{exponential
function}
620  \end{methoddesc}  \end{methoddesc}
621
622  \begin{methoddesc}[Data]{sqrt}{}  \begin{methoddesc}[Data]{sqrt}{}
623  applies the square root function to the values of the object. The  applies the square root function to the object. The
624  return value is an object has the same shape and is defined on the  return \Data object has the same \Shape and is in the same
625  same data points like the object.  For each data point and all  \FunctionSpace like the object. For all \DataSamplePoints and all
626  components the value is calculated by applying the square root  components the value is calculated by applying the square root function.
627  function to the corresponding value of the object. An exception is  An exception is
628  raised if the value is negative.  \index{square root}  raised if the value is negative.  \index{function!square root}
629  \end{methoddesc}  \end{methoddesc}
630
631  \begin{methoddesc}[Data]{sin}{}  \begin{methoddesc}[Data]{sin}{}
632  applies the sine function to the values of the object. The return  applies the sine function to the object. The
633  value is an object has the same shape and is defined on the same data  return \Data object has the same \Shape and is in the same
634  points like the object.  For each data point and all components the  \FunctionSpace like the object. For all \DataSamplePoints and all
635  value is calculated by applying the sine function to the  components the value is calculated by applying the sine function. \index{function!sine}
corresponding value of the object.  \index{sine function}
636  \end{methoddesc}  \end{methoddesc}
637
638  \begin{methoddesc}[Data]{cos}{}  \begin{methoddesc}[Data]{cos}{}
639  applies the cosine function to the values of the object. The return  applies the cosine function to the object. The
640  value is an object has the same shape and is defined on the same data  return \Data object has the same \Shape and is in the same
641  points like the object.  For each data point and all components the  \FunctionSpace like the object. For all \DataSamplePoints and all
642  value is calculated by applying the cosine function to the  components the value is calculated by applying the cosine function. \index{function!cosine}
643  corresponding value of the object.  \index{cosine function}  \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}  \end{methoddesc}
659
660  \begin{methoddesc}[Data]{maxval}{}  \begin{methoddesc}[Data]{maxval}{}
661  returns for each data point the maximum value over all components. The  returns the maximum value over all components. The
662  return value is an object of rank 0 or shape (1,) and is defined on  return value is a \Data object of rank 0
663  the same data points like the object.  \index{maximum value}  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}  \end{methoddesc}
667
668  \begin{methoddesc}[Data]{minval}{}  \begin{methoddesc}[Data]{minval}{}
669  returns for each data point the minimum value over all components. The  returns the minimum value over all components. The
670  return value is an object of rank 0 or shape (1,) and is defined on  return value is a \Data object of rank 0
671  the same data points like the object.  \index{minimum value}  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 non-negative 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}  \end{methoddesc}
695
696  \begin{methoddesc}[Data]{inf}{}  \begin{methoddesc}[Data]{trace}{}
697  returns the minimum value (infimum) of the object. The minimum is  returns sum of the components with identical indexes.
698  taken over all components and all data points.  \index{infimum}  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}  \end{methoddesc}
704    \begin{methoddesc}[Data]{saveDX}{fileName}
705  \begin{methoddesc}[Data]{sup}{}  saves the object to an openDX format file of name \var{fileName}, see
706  returns the maximum value (supremum) of the object. The maximum is  \ulink{www.opendx.org}{\url{www.opendx.org}}.  \index{openDX}
taken over all components and all data points.  \index{supremum}
707  \end{methoddesc}  \end{methoddesc}
708
\begin{methoddesc}[Data]{Lsup}{}
returns the $L^{sup}$-norm of the object. This is maximum value of the
absolut values of the object over all data points and all components.
\index{$L^{sup}$-norm}
\end{methoddesc}
709
710  \begin{methoddesc}[Data]{wherePositive}{}  For convenience the following factories are provided to created \Data object:
returns \Data object which has the same shape and is defined on
the same data points like the object. The returned values are $1$
where the object is positive and $0$ elsewhere.
\end{methoddesc}
711
712  \begin{methoddesc}[Data]{whereNonnegative}{}  \begin{funcdesc}{Scalar}{value=0.,what=escript::FunctionSpace(),expand=\False}
713  returns \Data object which has the same shape and is defined on  returns a \Data object of rank 0 in the \FunctionSpace \var{what}.
714  the same data points like the object. The returned values are $1$  Values are initialed with the double \var{value}. If \var{expanded} is \True
715  where the object is non-negative and $0$ elsewhere.  the \Data object is represented in expanded from.
716  \end{methoddesc}  \end{funcdesc}
717
718  \begin{methoddesc}[Data]{whereNegative}{}  \begin{funcdesc}{Vector}{value=0.,what=escript::FunctionSpace(),expand=\False}
719  returns \Data object which has the same shape and is defined on  returns a \Data object of \Shape \var{(d,)} in the \FunctionSpace \var{what}
720  the same data points like the object. The returned values are $1$  where \var{d} is the spatial dimension of the \Domain of \var{what}.
721  where the object is negative and $0$ elsewhere.  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 non-negative 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
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
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}  \end{methoddesc}
883
884  \begin{methoddesc}[Data]{whereZero}{tolerance=Constants.EPSILON}  \begin{methoddesc}[Operator]{setValue}{value}
885  returns \Data object which has the same shape and is defined on  resets all entires in the obeject representation to \var{value}
the same data points like the object. The returned values are $1$
where the object is nearly zero, i.e. where the absolute value is less
than \var{tolerance}, and $0$ elsewhere.
886  \end{methoddesc}  \end{methoddesc}
887
888  \begin{methoddesc}[Data]{whereNonzero}{tolerance=Constants.EPSILON}  \begin{methoddesc}[Operator]{solves}{rhs}
889  returns \Data object which has the same shape and is defined on  solves the operator equation with right hand side \var{rhs}
the same data points like the object. The returned values are $1$
where the object is nearly non-zero, i.e. where the absolute value is
greater or equal than \var{tolerance}, and $0$ elsewhere.
890  \end{methoddesc}  \end{methoddesc}
891
892  \begin{methoddesc}[Data]{saveDX}{fileName}  \begin{methoddesc}[Operator]{of}{u}
893  saves the object to an openDX format file of name \var{fileName}, see  applies the operator to the \Data object \var{u}
894  \end{methoddesc}  \end{methoddesc}
895
896  \begin{methoddesc}[Data]{saveMM}{fileName}  \begin{methoddesc}[Operator]{saveMM}{fileName}
897  saves the object to a matrix market format file of name  saves the object to a matrix market format file of name
898  \var{fileName}, see  \var{fileName}, see
900  \index{Matrix Market}  \index{Matrix Market}
901  \end{methoddesc}  \end{methoddesc}
902
%=====================================================
\section{Subclasses of \var{class}}
\begin{classdesc}{Scalar}{value=None,where=None,expand=None}
\Data object with a single value (scalar) per data
point. \var{value} must be a float number.  If \var{expand} is true,
the \var{value} is copied to each data point.
\end{classdesc}

\begin{classdesc}{Vector}{value=None,dim=None,where=None,expand=None}
\Data object with a vector of length \var{dim} value (scalar)
per data point.  If \var{dim} is not present or equals \var{None},
\var{dim} is assumed to be the spatial dimension of the data points
defined by \var{where}. \var{value} may be a float number or a
\class{numarray.array} object with shape (\var{dim},).  If
\var{expand} is true, the \var{value} is copied to each data point.
\end{classdesc}

\begin{classdesc}{Tensor}{value=None,dim=None,where=None,expand=None}
\Data object with a \var{dim} $\times$ \var{dim} - tensor of
order 2 per data point.  If \var{dim} is not present or equals
\var{None}, \var{dim} is assumed to be the spatial dimension of the
data points defined by \var{where}. \var{value} may be a float number
or a \class{numarray.array} object with shape (\var{dim},\var{dim}).
If \var{expand} is true, the \var{value} is copied to each data point.
\end{classdesc}

\begin{classdesc}{Tensor3}{value=None,dim=None,where=None,expand=None}
\Data object with a \var{dim} $\times$ \var{dim} $\times$
\var{dim} - tensor of order 3 per data point.  If \var{dim} is not
present or equals \var{None}, \var{dim} is assumed to be the spatial
dimension of the data points defined by \var{where}. \var{value} may
be a float number or a \class{numarray.array} object with shape
(\var{dim},\var{dim},var{dim}).  If \var{expand} is true, the
\var{value} is copied to each data point.
\end{classdesc}

\begin{classdesc}{Tensor4}{value=None,dim=None,where=None,expand=None}
\Data object with a \var{dim} $\times$ \var{dim} $\times$
\var{dim} $\times$ \var{dim} - tensor of order 4 per data point.  If
\var{dim} is not present or equals \var{None}, \var{dim} is assumed to
be the spatial dimension of the data points defined by
\var{where}. \var{value} may be a float number or a
\class{numarray.array} object with shape
(\var{dim},\var{dim},var{dim},var{dim}).  If \var{expand} is true, the
\var{value} is copied to each data point.
\end{classdesc}

Legend:
 Removed from v.100 changed lines Added in v.107