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

revision 97 by jgs, Tue Dec 14 05:39:33 2004 UTC revision 100 by jgs, Wed Dec 15 03:48:48 2004 UTC
# Line 2  Line 2
2
3  \chapter{The module \escript}  \chapter{The module \escript}
4
5  \declaremodule{extension}{escript}  \declaremodule{extension}{escript} \modulesynopsis{Handling data on
6  \modulesynopsis{Data manipulation}  data points like \class{Nodes}, \class{Elements}}
7
8  \begin{figure}  The class \Data of the module \escript allows handling
9  \includegraphics[width=\textwidth]{EscriptDiagram1.eps}  data which are hold on data points \index{data points}. Examples for
10  \caption{\label{ESCRIPT DEP}Dependency of Function Spaces. An arrow indicates that a function in the  data points are nodes or the quadrature points in elements of a finite
11  function space at the starting point can be interpreted as a function in the function space of the arrow target.}  element mesh. Another examples a particles or the connection between
12  \end{figure}  particles in the case of discrete element methods.  Handlers to data
13    points are issued by the structure which contains the data points,
14  \escript is an extension of Python to handle functions represented by their values on  e.g. a \finley mesh.
15  \DataSamplePoints. The \DataSamplePoints for the geometrical region on which
16  the function is defined. The region as well as the method which is used  The simplest form of data attached to a data point is a single scalar
17  to interpolate value on the \DataSamplePoints is defined by      $a$ value which for instance represent the temperature or pressure at
18  \Domain class objects. For instance when using  this particular data point. Another example is a velocity field. in
19  the finite element method (FEM) \index{finite element method}  this case each data point holds a vector $a(0),a(1),a(2)$ representing
20  \Domain object holds the information about the FEM mesh, eg.  the velocity at the particular data point. For the case that the
21  a table of nodes and a table of elements. Although \Domain contains  values are representing a stress tensor the value is a matrix of the
22  the discretization method to be used \escript does not use this information directly.  form
23  \Domain objects are created from a module which want to make use  $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
24  \escript, e.g. \finley.  general, values hald by data points can have up to four indices. The
25    number of indices is called rank \index{rank}. The tuple of length
26  The solution of a PDE is a function of its location in the domain of interest $\Omega$.  rank which defines the upper-bound for each index component is called
27  When solving a partial differential equation \index{partial differential equation} (PDE) using FEM  the shape. A stress has rank 2 and the shape is (3,3). For a vector we
28  the solution is (piecewise) differentiable but, in general, its gradient  have rank 1 and shape (3,). A scalar can have rank 0 or rank 1 with
29  is discontinuous. To reflect these different degrees of smoothness different  shape (1,).
30  representations of the functions are used. For instance; in FEM
31  the displacement field is represented by its values at the nodes of the mesh, while the  In general, the data are stored for each data point. This status of
32  strain, which is the symmetric part of the gradient of the displacement field, is stored on the  the data is called expanded \index{expanded}. But in some cases, all
33  element centers. To be able to classify functions with respect to their smoothness, \escript has the  data points hold the same value. In this case only a single value is
34  concept of the "function space". A function space is described by a \FunctionSpace object.  stored, which is refered by each data point if needed. This saves
35  The following statement generates the object \var{solution_space} which is  memory as well as compute time. In some cases, it is very usefull to
36  a \FunctionSpace object and provides access to the function space of  have slightly more general way which allows to define piecewise
37  PDE solutions on the \Domain \var{mydomain}:  constant data. For this, each data point has to wear a tag which is an
38  \begin{python}  integer \index{tag}. The tag is used to distingish between various
39  solution_space=Solution(mydomain)  types of data points. Typical example of the usage of tags is to
40  \end{python}  assign different material parameters to various subdomains. Then one
41  The following generators for function spaces on a \Domain \var{mydomin} are available:  assigns the same tag to all elements in a finite element mesh which
42  \begin{itemize}  lay in the same subdomain.  Later each tag can be assigns individual
43  \item \var{Solution(mydomain)}: solutions of a PDE.    material parameters.
\item \var{ContinuousFunction(mydomain)}: continuous functions, eg. a temperature distribution.
\item \var{Function(mydomain)}: general functions which are not necessarily continuous, eg. a stress field.
\item \var{FunctionOnBoundary(mydomain)}: functions on the boundary of the domain, eg. a surface pressure.
\item \var{FunctionOnContact0(mydomain)}: functions on side $0$ of the discontinuity.
\item \var{FunctionOnContact1(mydomain)}: functions on side $1$ of the discontinuity.
\end{itemize}
A discontinuity \index{discontinuity} is a region within the domain across which functions may be discontinuous.
The location of discontinuity is defined in the \Domain object.
\fig{ESCRIPT DEP} shows the dependency between the types of function spaces.
The solution of a PDE is a continuous function. Any continuous function can be seen as a general function
on the domain and can be restricted to the boundary as well as to any side of the
discontinuity (the result will be different depending on
which side is chosen). Functions on any side of the
discontinuity can be seen as a function on the corresponding other side.
A function on the boundary or on one side of
the discontinuity cannot be seen as a general function on the domain as there are no values
defined for the interior. For most PDE solver libraries
the space of the solution and continuous functions is identical, however in some cases, eg.
when periodic boundary conditions are used in \finley, a solution
fulfils periodic boundary conditions while a continuous function does not have to be periodic.

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

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

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

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

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

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

The following example shows the usage of {\tt Data} objects: Assume we have a
displacement field $u$ and we want to calculate the corresponding stress field
$\sigma$ using the linear--elastic isotropic material model
\begin{eqnarray}\label{eq: linear elastic stress}
\sigma\hackscore {ij}=\lambda u\hackscore {k,k} \delta\hackscore {ij} + \mu ( u\hackscore {i,j} + u\hackscore {j,i})
\end{eqnarray}
where $\delta\hackscore {ij}$ is the Kronecker symbol and
$\lambda$ and $\mu$ are the Lame coefficients. The following function
takes the displacement {\tt u} and the Lame coefficients
\var{lam} and \var{mu} as arguments and returns the corresponding stress:
\begin{python}
import numarray
def getStress(u,lam,mu):
d=u.getDomain().getDim()
stress=lam*trace(g)*numarray.identity(d)+ \
mu*(g+transpose(g))
return stress
\end{python}
The variable
\var{d} gives the spatial dimension of the
domain on which the displacements are defined.
\var{identity} is a \numarray function which returns the Kronecker symbol with indexes
$i$ and $j$ running from $0$ to \var{d}-1. The call \var{grad(u)} requires
the displacement field \var{u} to be in the \var{Solution} or \ContinuousFunction
function space. The result \var{g} as well as the returned stress will be in the \Function function space.
If \var{u} is available, eg. by solving a PDE, \var{getStress} might be called
in the following way:
\begin{python}
s=getStress(u,1.,2.)
\end{python}
However \var{getStress} can also be called with \Data objects as values for
\var{lam} and \var{mu} which,
for instance in the case of a temperature dependency, are calculated by an expression.
The following call is equivalent to the previous example:
\begin{python}
lam=Scalar(1.,ContinuousFunction(mydomain))
mu=Scalar(2.,Function(mydomain))
s=getStress(u,lam,mu)
\end{python}
The function \var{lam} belongs to the \ContinuousFunction function space
but with \var{g} the function \var{trace(g)} is in the \Function function space.
Therefore the evaluation of the product \var{lam*trace(g)} in the stress calculation
produces a problem, as both functions are represented differently, eg. in FEM
\var{lam} by its values on the node, and in \var{trace(g)} by its values at the element centers.
In the case of inconsistent function spaces of arguments in a binary operation, \escript
interprets the arguments in the appropriate function space according to the inclusion
defined in Table~\ref{ESCRIPT DEP}. In this example that means
\escript sees \var{lam} as a function of the \Function function space.
In the context of FEM this means the nodal values of
\var{lam} are interpolated to the element centers. Behind the scenes
\escript calls the appropriate function from the PDE solver library.

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

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

The \Data class provides a transparent interface to various data representations and the
translations between them. As shown in the example of stress calculation, this allows the user to
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 representions 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.

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

\section{\Domain class}

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

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

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

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

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

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

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

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

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

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

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

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

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

\begin{methoddesc}[FunctionSpace]{getDomain}{}
returns the \Domain of the \FunctionSpace.
\end{methoddesc}

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

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

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

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

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

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

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

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

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

\section{\Data Class}
44
45    The following table shows unitary operations that can be applied to an
46    \Data object \var{arg}:
47    \begin{tableii}{l|l}{textrm}{expression}{Description}
48    \lineii{+\var{arg}} {just \var{arg} \index{+}}
49    \lineii{-\var{arg}} {swapping the sign\index{-}}
50    \lineii{\function{abs}(\var{arg})} {absolute value}
51    \lineii{\function{sin}(\var{arg})} {sine function}
52    \lineii{\function{cos}(\var{arg})} {cosine function}
53    \lineii{\function{exp}(\var{arg})} {exponential function}
54    \lineii{\function{sqrt}(\var{arg})} {square root}
55    \end{tableii}
56    An unitary operation returns a \Data objects of the same shape
57    and defined on the data points like \var{arg}.
58
59  The following table shows binary and unitary operations that can be applied to  The following table shows binary operations that can be applied to
60  \Data objects:  \Data objects:
61  \begin{tableii}{l|l}{textrm}{expression}{Description}  \begin{tableii}{l|l}{textrm}{expression}{Description}
\lineii{+\var{arg1}} {just \var{arg} \index{+}}
\lineii{-\var{arg1}} {swapping the sign\index{-}}
62  \lineii{\var{arg1}+\var{arg2}} {adds \var{arg1} and \var{arg2} \index{+}}  \lineii{\var{arg1}+\var{arg2}} {adds \var{arg1} and \var{arg2} \index{+}}
63  \lineii{\var{arg1}*\var{arg2}} {multiplies \var{arg1} and \var{arg2} \index{*}}  \lineii{\var{arg1}*\var{arg2}} {multiplies \var{arg1} and \var{arg2} \index{*}}
64  \lineii{\var{arg1}-\var{arg2}} {difference \var{arg2} from\var{arg2} \index{-}}  \lineii{\var{arg1}-\var{arg2}} {difference \var{arg2} from\var{arg2} \index{-}}
# Line 395  The following table shows binary and uni Line 68  The following table shows binary and uni
68  At least on of the arguments \var{arg1} or \var{arg2} must be a  At least on of the arguments \var{arg1} or \var{arg2} must be a
69  \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
70  converted into a \Data object. If \var{arg1} or \var{arg2} are  converted into a \Data object. If \var{arg1} or \var{arg2} are
71  defined on different \FunctionSpace it is tried to embed \var{arg1}  defined on different data points it is tried to interpolate \var{arg1}
72  into the \FunctionSpace of \var{arg2} or to embed \var{arg2} into  onto the data points of \var{arg2} or to interpolate \var{arg2} onto
73  the \FunctionSpace of \var{arg1}. Boths arguments must have the same  the data points of \var{arg1}. Boths arguments must have the same
74  \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
75  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
76  \Shape like the other argument but constant over all components.  shape like the other argument but constant over all components.
77
78  The returned \Data object has the same \Shape and is defined on  The returned \Data object has the same shape and is defined on
79  the \DataSamplePoints like \var{arg1} or \var{arg2}.  the data points like \var{arg1} or \var{arg2}.
80
81  The following table shows the update operations that can be applied to  The following table shows the update operations that can be applied to
82  \Data objects:  \Data objects:
# Line 415  The following table shows the update ope Line 88  The following table shows the update ope
88  \end{tableii}  \end{tableii}
89  \var{arg1} must be a \Data object. \var{arg1} must be a  \var{arg1} must be a \Data object. \var{arg1} must be a
90  \Data object or an object that can be converted into a  \Data object or an object that can be converted into a
91  \Data object. \var{arg1} must have the same \Shape like  \Data object. \var{arg1} must have the same shape like
92  \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
93  assumed that the values of \var{arg1} are constant for all  assumed that the values of \var{arg1} are constant for all
94  components. \var{arg2} must be defined on the same \DataSamplePoints like  components. \var{arg2} must be defined on the same data points like
95  \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
96  \DataSamplePoints where \var{arg1} is hold.  data points where \var{arg1} is hold.
97
The \Data class supports getting slices as well as assigning new values to components in an existing
\Data object \index{slicing}.
The following expression for getting (expression on the right hand side of the
equal sign) and setting slices (expression on the left hand side of the
equal sign) are valid:
\begin{tableiii}{l|ll}{textrm}{rank of \var{arg}}{slicing expression}{\Shape of returned and assigned object}
\lineiii{0}{ no slicing }                      {-}
\lineiii{1}{\var{arg[l0:u0]}}                   {(\var{u0}-\var{l0},)}
\lineiii{2}{\var{arg[l0:u0,l1:u1]}}             {(\var{u0}-\var{l0},\var{u1}-\var{l1})}
\lineiii{3}{\var{arg[l0:u0,l1:u1,l2:u2]} }      {(\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2})}
\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})}
\end{tableiii}
where
$0 \le \var{l0} \le \var{u0} \le \var{s[0]}$,
$0 \le \var{l1} \le \var{u1} \le \var{s[1]}$,
$0 \le \var{l2} \le \var{u2} \le \var{s[2]}$,
$0 \le \var{l3} \le \var{u3} \le \var{s[3]}$ and \var{s} the \Shape if \var{arg}.
Any of the lower indexes \var{l0}, \var{l1}, \var{l2} and \var{l3} may not be present in which case
$0$ is assumed.
Any of the upper indexes \var{u0}, \var{u1}, \var{u2} and \var{u3} may not be present in which case
\var{s} is assumed. The lower and upper index may be identical, in which case the column and the lower or upper
index may be dropped. In the returned or in the object assigned to a slice the corresponding component is dropped,
i.e. the rank is reduced by one in comparison to \var{arg}.
The follwing examples showing the usage of slicing:
\begin{python}
t[1,1,1,0]=9.
s=t[:2,:,2:6,5] # s has rank 3
s[:,:,1]=1.
t[:2,:2,5,5]=s[2:4,1,:2]
\end{python}
98
99    %TODO:
100    Slicing \index{slicing}.
101
102    \begin{classdesc}{Data}{}
103    A class that holds values assigned to data points.
104    \end{classdesc}
105
106  \begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expanded=\False}  \begin{classdesc}{Scalar}{value=None,where=None,expand=None}
107  creates a \Data object with \Shape \var{shape} in the \FunctionSpace \var{what}.  A class that holds a single value per data point.
The values at all \DataSamplePoints are set to the double value \var{value}. If \var{expanded} is \True
the \Data object is represented in expanded from.
\end{classdesc}

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

\begin{classdesc}{Data}{value,what=FunctionSpace()}
creates a \Data object in the \FunctionSpace \var{what} from the \Data object \var{value}.
The \Shape of the created \Data object is equal to the \Shape of \var{value}.
If the \FunctionSpace of \var{value} is equal to the \var{what}, a shallow copy, i.e.
a reference to the representation of \var{value} is greated. Otherwise,
\var{value} is interpolated into the \var{what}.
108  \end{classdesc}  \end{classdesc}
109
110  \begin{classdesc}{Data}{}  \begin{classdesc}{Vector}{value=None,dim=None,where=None,expand=None}
111  creates an \EmptyData object. The \EmptyData object is used to indicate that an argument is not present  A class that holds a vector per data point.
where a \Data object is required.
112  \end{classdesc}  \end{classdesc}
113
114  \begin{methoddesc}[Data]{getFunctionSpace}{}  \begin{classdesc}{Tensor}{value=None,dim=None,where=None,expand=None}
115  returns the \FunctionSpace of the object.  A class that holds a tensor order 2 (matrix) per data point.
116  \end{methoddesc}  \end{classdesc}
117
118  \begin{methoddesc}[Data]{getFunctionSpace}{}  \begin{classdesc}{Tensor3}{value=None,dim=None,where=None,expand=None}
119  returns the \Domain  of the object.  A class that holds a tensor order 3 per data point.
120  \end{methoddesc}  \end{classdesc}
121
122  \begin{methoddesc}[Data]{getShape}{}  \begin{classdesc}{Tensor4}{value=None,dim=None,where=None,expand=None}
123  returns the \Shape  of the object as a \class{tuple} of  A class that holds a tensor order 4 per data point.
124  integers.  \end{classdesc}
\end{methoddesc}
125
126  \begin{methoddesc}[Data]{getRank}{}  \begin{funcdesc}{abs}{arg}
127  returns the rank of the data on each data point. \index{rank}  returns the absulute value of \Data \var{arg}. The returned
128  \end{methoddesc}  \Data object has the same rank, shape and is defined on the
129    same \class{_Atom} like \var{arg}. An entries in the returned object
130    is the absolute value of the corresponding entry in \var{arg}.
131    \index{absolute value}
132    \end{funcdesc}
133
134  \begin{methoddesc}[Data]{isEmpty}{}  \begin{funcdesc}{L2}{arg}
135  returns \True id the \Data object is the \EmptyData object.    returns the $L^2$-norm of the \Data \var{arg} by using method
136  Otherwise \False is returned.  \method{arg.L2()}.  \index{$L^2$-norm}
137  \end{methoddesc}  \end{funcdesc}
138
140  assigns the \var{value} to all \DataSamplePoints which have the tag  returns the gradient of the interpolation function of \Data
141  \var{tag}. \var{value} must be an object of class  \var{arg} by using \method{arg.grad}. \index{gradient}
142  \class{numarray.array} or must be convertable into a  \end{funcdesc}
\class{numarray.array} object. \var{value} (or the cooresponding
\class{numarray.array} object) must be of rank $0$ or must have the
same rank like the object.
If a value has already be defined for tag \var{tag} within the object
it is overwritten by the new \var{value}.  If the object is expanded,
the value assigned to \DataSamplePoints with tag \var{tag} is replaced by
\var{value}.
\end{methoddesc}
143
144  \begin{methoddesc}[Data]{wherePositive}{}  \begin{funcdesc}{integrate}{arg}
145  returns \Data object which has the same \Shape and is defined on  returns the integral of the interpolation function of \Data
146  the same \FunctionSpace like the object. The returned values are $1$  \var{arg} by using \method{arg.integrate}. \index{integral}
147  where the object is positive and $0$ elsewhere.  \end{funcdesc}
\end{methoddesc}
148
149  \begin{methoddesc}[Data]{wherePositive}{}  \begin{funcdesc}{interpolate}{arg,where}
150  returns \Data object which has the same \Shape and is defined on  interpolates the \Data \var{arg} onto \class{_Atom} where by
151  the same \FunctionSpace like the object. The returned values are $1$  using \method{arg.interpolate}. \index{interpolation}
152  where the object is non-positive and $0$ elsewhere.  \end{funcdesc}
153
154    \begin{funcdesc}{transpose}{arg}
155    returns the transpose of \var{arg} where \var{arg} has to be
156    \Data or \class{numarray.array}. If \var{arg} is of
157    \Data the method \method{arg.transpose} is used otherwise
158    \function{numarray.transpose} is called. \index{transpose}
159    \end{funcdesc}
160
161    \begin{funcdesc}{trace}{arg}
162    returns the trace of \var{arg} where \var{arg} has to be \Data
163    or \class{numarray.array} of rank 2. If \var{arg} is of \Data
164    the method \method{arg.trace} is used otherwise
165    \function{numarray.trace} is called. \index{trace}
166    \end{funcdesc}
167
168    \begin{funcdesc}{exp}{arg}
169    applies the exponential function to \var{arg} where \var{arg} has to
170    be \Data or \class{numarray.array}. If \var{arg} is of
171    \Data the method \method{arg.exp} is used otherwise
172    \function{numarray.exp} is called. \index{exponential function}
173    \end{funcdesc}
174
175    \begin{funcdesc}{sqrt}{arg}
176    applies the square root function to \var{arg} where \var{arg} has to
177    be \Data or \class{numarray.array}. If \var{arg} is of
178    \Data the method \method{arg.sqrt} is used otherwise
179    \function{numarray.sqrt} is called. \index{square root}
180    \end{funcdesc}
181
182    \begin{funcdesc}{sin}{arg}
183    applies the sine function to \var{arg} where \var{arg} has to be
184    \Data or \class{numarray.array}. If \var{arg} is of
185    \Data the method \method{arg.sin} is used otherwise
186    \function{numarray.sin} is called. \index{sine function}
187    \end{funcdesc}
188
189    \begin{funcdesc}{cos}{arg}
190    applies the cosine function to \var{arg} where \var{arg} has to be
191    \Data or \class{numarray.array}. If \var{arg} is of
192    \Data the method \method{arg.cos} is used otherwise
193    \function{numarray.cos} is called. \index{cosine function}
194    \end{funcdesc}
195
196    \begin{funcdesc}{maxval}{arg}
197    returns for each data point the maximum value over all components of
198    \Data \var{arg} by using \method{arg.maxval}.  \index{maximum
199    value}
200    \end{funcdesc}
201
202    \begin{funcdesc}{minval}{arg}
203    returns for each data point the minimum value over all components of
204    \Data \var{arg} by using \method{arg.minval}.  \index{minimum
205    value}
206    \end{funcdesc}
207
208    \begin{funcdesc}{inf}{arg}
209    returns the minimum value (infimum) over all components and all data
210    points of \Data \var{arg} by using \method{arg.inf}.
211    \index{infimum}
212    \end{funcdesc}
213
214    \begin{funcdesc}{sup}{arg}
215    returns the maximum value (supremum) over all components and all data
216    points of \Data \var{arg} by using \method{arg.sup}.
217    \index{supremum}
218    \end{funcdesc}
219
220    \begin{funcdesc}{Lsup}{arg}
221    returns the maximum absulute value ($L^{sup}$-norm) over all
222    components and all data points of \Data \var{arg} by using
223    \method{arg.sup}.  The returned value equals
224    \function{sup}(\function(arg)).  \index{$L^{sup}$-norm}
225    \end{funcdesc}
226
227    \begin{funcdesc}{matmult}{arg1,arg2}
228    returns for each data point the matrix-matrix product of \var{arg1}
229    and \var{arg2} \index{matrix-matrix product}. At least of the
230    arguments \var{arg1} and \var{arg2} has to be a \Data
231    object. If the other argument is not a \Data object it must be
232    convertable into a \Data object. The returned \Data
233    object has rank \var{arg1.getRank()}+\var{arg2.getRank()}-2 and shape
234    (\var{arg1.getShape()}[r-1],\var{arg2.getShape()}[1:]), where
235    \var{r}=\var{arg1.getRank()}. The last dimension of \var{arg1} and the
236    first dimension of \var{arg2} have to match,
237    i.e. \var{arg1.getShape()[r-1]}=\var{arg2.getShape()[0]}
238
239    For the case that \var{arg1} and \var{arg2} are both of rank $2$ the
240    result \var{res} is calculated as
241
242    res(i,j;s)=
243    arg1(i,0;s) \cdot arg2(0,j;s)+
244    \ldots
245    arg1(i,n-1;s) \cdot arg2(n-1,j;s)
246
247    for all $0\le i <$ \var{arg1.getShape()[0]}, $0\le j <$
248    \var{arg2.getShape()[1]} and all data points $s$, where
249    $n$=\var{arg2.getShape()[0]},
250
251    If the arguments are not defined on the same data points, \var{arg1}
252    is tried to be interpolated on the data points of \var{arg2} or
253    \var{arg2} is tried to be interpolated on the data points of
254    \var{arg1}. What ever case works defines the data points of the
255    result.
256    \end{funcdesc}
257
258    %==================================================================
259    \section{\Data class}
260    \begin{classdesc}{Data}{value=None,shape=None,where=None,expand=None}
261    \end{classdesc}
262
263    \begin{methoddesc}[Data]{getAtoms}{}
264    returns a handel to the data points on which the object is definded
265    \index{data points}.  The returned object is of \class{_Atoms}.
266  \end{methoddesc}  \end{methoddesc}
267
268  \begin{methoddesc}[Data]{whereNonnegative}{}  \begin{methoddesc}[Data]{getShape}{}
269  returns \Data object which has the same \Shape and is defined on  returns the shape of the data on each data point as a \class{tuple} of
270  the same \FunctionSpace like the object. The returned values are $1$  integers. \index{shape}
where the object is non-negative and $0$ elsewhere.
271  \end{methoddesc}  \end{methoddesc}
272
273  \begin{methoddesc}[Data]{whereNegative}{}  \begin{methoddesc}[Data]{getRank}{}
274  returns \Data object which has the same \Shape and is defined on  returns the rank of the data on each data point. \index{rank}
the same \FunctionSpace like the object. The returned values are $1$
where the object is negative and $0$ elsewhere.
275  \end{methoddesc}  \end{methoddesc}
276
277  \begin{methoddesc}[Data]{whereZero}{tolerance=1.e-8}  \begin{methoddesc}[Data]{hasShape}{shape}
278  returns \Data object which has the same \Shape and is defined on  is true if the object has the shape \var{shape}.
the same \FunctionSpace 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.
279  \end{methoddesc}  \end{methoddesc}
280
281  \begin{methoddesc}[Data]{whereNonzero}{tolerance=1.e-8}  \begin{methoddesc}[Data]{expand}{}
282  returns \Data object which has the same \Shape and is defined on  returns an expanded version of the object if the object is not
283  the same \FunctionSpace like the object. The returned values are $1$  expanded. Otherwise it returns itself. \index{expanded}
where the object is nearly non-zero, i.e. where the absolute value is
greater or equal than \var{tolerance}, and $0$ elsewhere.
284  \end{methoddesc}  \end{methoddesc}
285
286  \begin{methoddesc}[Data]{sign}{}  \begin{methoddesc}[Data]{makeExpanded}{}
287  returns \Data object which has the same \Shape and is defined on  turns the object into an expanded \Data
288  the same \FunctionSpace like the object. The returned values are $1$  object. \index{expanded}
where the object is positive, $-1$ where the value is negative and $0$ elsewhere.
289  \end{methoddesc}  \end{methoddesc}
290
292  copies the \Data object \var{arg} into the object  is true if the object is expanded. \index{expanded}
where the \Data object \var{mask} is positive. \var{arg}
and \var{mask} must have the same \Shape
and must belong to same \FunctionSpace as
the object.
293  \end{methoddesc}  \end{methoddesc}
294
295  \begin{methoddesc}[Data]{Lsup}{}  \begin{methoddesc}[Data]{isTagged}{}
296  returns the $L^{sup}$-norm of the object. This is maximum absolute values over all components and all \DataSamplePoints. \index{$L^{sup}$-norm}.  is true if the object is defined using tags. \index{tagged}
297  \end{methoddesc}  \end{methoddesc}
298  \begin{methoddesc}[Data]{inf}{}
299  returns the minimum value (infimum) of the object. The minimum is  \begin{methoddesc}[Data]{asArray}{}
300  taken over all components and all \DataSamplePoints .  \index{infimum}  returns the object as a \class{numarray.array} array. The array is one
301    rank higher than the rank of the object. The extra dimension is the
302    number of data points.
303    % TODO: be more accurate on the shape
304  \end{methoddesc}  \end{methoddesc}
305
307  returns the maximum value (supremum) of the object. The maximum is  assigns the \var{value} to all data points which have the tag
308  taken over all components and all \DataSamplePoints .  \index{supremum}  \var{tag} which has to be an integer or a list of
309    integers. \var{value} must be an object of class
310    \class{numarray.array} or must be convertable into a
311    \class{numarray.array} object. \var{value} (or the cooresponding
312    \class{numarray.array} object) must be of rank $0$ or must have the
313    same rank like the object. \index{tagged}
314
315    If a value has allready be defined for tag \var{tag} within the object
316    it is overwritten by the new \var{value}.  If the object is expanded,
317    the value assigned to data points with tag \var{tag} is replaced by
318    \var{value}.
319  \end{methoddesc}  \end{methoddesc}
320
322  returns the gradient of the function represented by the object.  returns the value assigned to \var{tag}. An exception is raised if the
323  \Data object is in \FunctionSpace \var{on} and has rank r+1 where r is the rank of the object.  object is not defined by tagged data, e.g. if the object is
324  If \var{on} is not present, a suitbale \FunctionSpace is used.  expanded.\index{tagged}
325    \end{methoddesc}
326
327    \begin{methoddesc}[Data]{L2}{}
328    returns the $L^2$-norm of the object. This is square root of sum of
329    the squares of all values over all components and all data points.
330    \index{$L^2$-norm}
331    \end{methoddesc}
332
334    returns the gradient of the interpolation function. The returned
335    \Data object is of rank r+1 where r is the rank of the object.
336    Typically the object of to be defined on nodes and the returned
339  \end{methoddesc}  \end{methoddesc}
340
341  \begin{methoddesc}[Data]{integrate}{}  \begin{methoddesc}[Data]{integrate}{}
342  returns the integral of the function represented by the object. The method returns  returns the integral of the interpolation function. The method returns
343  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
344  component of the returned object is the integral of the corresponding  component of the returned object is the integral of the corresponding
345  component of the object. \index{integral}  component of the object.  \index{integral}
346  \end{methoddesc}  \end{methoddesc}
347
348  \begin{methoddesc}[Data]{interpolate}{on}  \begin{methoddesc}[Data]{interpolate}{where}
349  interpolates  interpolates onto the data points of the \class{_Atom}
350  the function represented by the object  \var{where}. The returned \Data object is of the same shape
351  into the \FunctionSpace\var{on}.  like the object and is defined on the data points \var{where}.
352  \index{interpolation}  \index{interpolation}
353  \end{methoddesc}  \end{methoddesc}
354
355  \begin{methoddesc}[Data]{abs}{}  \begin{methoddesc}[Data]{transpose}{}
356  applies the absolute value function to the object. The  returns the transpose of the object. The return value is an object has
357  return \Data object has the same \Shape and is in the same  the same shape and is defined on the same data points like the object.
358  \FunctionSpace like the object. For all \DataSamplePoints and all  For each data point the value is set to transposed of the
359  components the value is calculated by applying the exponential  corresponding value of the object by reversing the index of the data.
360  function. \index{function!absolute value}
361    For the case that object \var{self} is of rank 3 the result \var{res} is
362
363    res(i,j,k;s)=self(k,j,i;s)
364
365    for all
366    $0\le i <$ \var{self.getShape()[2]},
367    $0\le j <$ \var{self.getShape()[1]},
368    $0\le k <$ \var{self.getShape()[0]}
369    and all data points $s$.
370    \index{transpose}
371  \end{methoddesc}  \end{methoddesc}
372
373  \begin{methoddesc}[Data]{exp}{}  \begin{methoddesc}[Data]{trace}{}
374  applies the exponential function to the object. The  returns the trace of the object of rank 2. The return value is an
375  return \Data object has the same \Shape and is in the same  object has rank 0 or shape (1,) and is defined on the same data points
376  \FunctionSpace like the object. For all \DataSamplePoints and all  like the object. For each data point the value is set to sum of the
377  components the value is calculated by applying the exponential  main diagonal entries.
378  function. \index{function!exponential}
379    For the case that object \var{self} is of rank 2 the result \var{res}
380    is
381
382    res(0;s)=
383    self(0,0;s)+
384    self(1,1;s)+
385    \ldots +
386    self(n,n;s)
387
388    for all data points $s$ where
389    $n=min($\var{self.getShape()[0]},\var{self.getShape()[1]}$)$.
390    \index{trace}
391    \end{methoddesc}
392
393    \begin{methoddesc}[Data]{exp}{}
394    applies the exponential function to the values of the object. The
395    return value is an object has the same shape and is defined on the
396    same data points like the object.  For each data point and all
397    components the value is calculated by applying the exponention
398    function to the corresponding value of the object.  \index{exponential
399    function}
400  \end{methoddesc}  \end{methoddesc}
401
402  \begin{methoddesc}[Data]{sqrt}{}  \begin{methoddesc}[Data]{sqrt}{}
403  applies the square root function to the object. The  applies the square root function to the values of the object. The
404  return \Data object has the same \Shape and is in the same  return value is an object has the same shape and is defined on the
405  \FunctionSpace like the object. For all \DataSamplePoints and all  same data points like the object.  For each data point and all
406  components the value is calculated by applying the square root function.  components the value is calculated by applying the square root
407  An exception is  function to the corresponding value of the object. An exception is
408  raised if the value is negative.  \index{function!square root}  raised if the value is negative.  \index{square root}
409  \end{methoddesc}  \end{methoddesc}
410
411  \begin{methoddesc}[Data]{sin}{}  \begin{methoddesc}[Data]{sin}{}
412  applies the sine function to the object. The  applies the sine function to the values of the object. The return
413  return \Data object has the same \Shape and is in the same  value is an object has the same shape and is defined on the same data
414  \FunctionSpace like the object. For all \DataSamplePoints and all  points like the object.  For each data point and all components the
415  components the value is calculated by applying the sine function. \index{function!sine}  value is calculated by applying the sine function to the
416    corresponding value of the object.  \index{sine function}
417  \end{methoddesc}  \end{methoddesc}
418
419  \begin{methoddesc}[Data]{cos}{}  \begin{methoddesc}[Data]{cos}{}
420  applies the cosine function to the object. The  applies the cosine function to the values of the object. The return
421  return \Data object has the same \Shape and is in the same  value is an object has the same shape and is defined on the same data
422  \FunctionSpace like the object. For all \DataSamplePoints and all  points like the object.  For each data point and all components the
423  components the value is calculated by applying the cosine function. \index{function!cosine}  value is calculated by applying the cosine function to the
424  \end{methoddesc}  corresponding value of the object.  \index{cosine function}

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

\begin{methoddesc}[Data]{log}{}
applies the logarithmic function to the object. The
return \Data object has the same \Shape and is in the same
\FunctionSpace like the object. For all \DataSamplePoints and all
components the value is calculated by applying the logarithmic function. An exception is
raised if the value is negative.\index{function!logarithmic}
425  \end{methoddesc}  \end{methoddesc}
426
427  \begin{methoddesc}[Data]{maxval}{}  \begin{methoddesc}[Data]{maxval}{}
428  returns the maximum value over all components. The  returns for each data point the maximum value over all components. The
429  return value is a \Data object of rank 0  return value is an object of rank 0 or shape (1,) and is defined on
430  and is in the same  the same data points like the object.  \index{maximum value}
\FunctionSpace like the object. For all \DataSamplePoints
the value is calculated as the maximum value over all components. \index{function!maximum}
431  \end{methoddesc}  \end{methoddesc}
432
433  \begin{methoddesc}[Data]{minval}{}  \begin{methoddesc}[Data]{minval}{}
434  returns the minimum value over all components. The  returns for each data point the minimum value over all components. The
435  return value is a \Data object of rank 0  return value is an object of rank 0 or shape (1,) and is defined on
436  and is in the same  the same data points like the object.  \index{minimum value}
\FunctionSpace like the object. For all \DataSamplePoints
the value is calculated as the minimum value over all components. \index{function!minimum}
\end{methoddesc}

\begin{methoddesc}[Data]{length}{}
returns the Euclidean length at all \DataSamplePoints. The
return value is a \Data object of rank 0
and is in the same
\FunctionSpace like the object. For all \DataSamplePoints
the value is calculated as the square root of the sum of the square over all over all components. \index{function!length}
\end{methoddesc}
\begin{methoddesc}[Data]{transpose}{axis}
returns the transpose of the object around \var{axis}. \var{axis} is a non-negative integer
which is less the rank $r$ of the object. Transpose swaps the indexes $0$ to \var{axis}
with the indexes \var{axis}+1 to $r$. If the \var{d} is \RankFour one has
\begin{python}
d[i,j,k,l]=d.transpose(0)[i,j,k,l]
d[i,j,k,l]=d.transpose(1)[j,k,l,i]
d[i,j,k,l]=d.transpose(2)[k,l,i,j]
d[i,j,k,l]=d.transpose(3)[l,i,j,k]
\end{python}
\index{function!transpose}
437  \end{methoddesc}  \end{methoddesc}
438
439  \begin{methoddesc}[Data]{trace}{}  \begin{methoddesc}[Data]{inf}{}
440  returns sum of the components with identical indexes.  returns the minimum value (infimum) of the object. The minimum is
441  The  taken over all components and all data points.  \index{infimum}
return value is a \Data object of rank 0
and is in the same
\FunctionSpace like the object.
\index{function!trace}
\end{methoddesc}
\begin{methoddesc}[Data]{saveDX}{fileName}
saves the object to an openDX format file of name \var{fileName}, see
442  \end{methoddesc}  \end{methoddesc}
443
444    \begin{methoddesc}[Data]{sup}{}
445    returns the maximum value (supremum) of the object. The maximum is
446    taken over all components and all data points.  \index{supremum}
447    \end{methoddesc}
448
449  For convenience the following factories are provided to created \Data object:  \begin{methoddesc}[Data]{Lsup}{}
450    returns the $L^{sup}$-norm of the object. This is maximum value of the
451  \begin{funcdesc}{Scalar}{value=0.,what=escript::FunctionSpace(),expand=\False}  absolut values of the object over all data points and all components.
452  returns a \Data object of rank 0 in the \FunctionSpace \var{what}.  \index{$L^{sup}$-norm}
453  Values are initialed with the double \var{value}. If \var{expanded} is \True  \end{methoddesc}
the \Data object is represented in expanded from.
\end{funcdesc}

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

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

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

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

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

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

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

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

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

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

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

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

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

\begin{funcdesc}{transpose}{arg,\optional{axis}}
returns the transpose of \var{arg} around \var{axis}. \var{axis} is a non-negative integer
which is less the rank $r$ of the object. Transpose swaps the indexes $0$ to \var{axis}
with the indexes \var{axis}+1 to $r$. If \var{axis} is not present, \var{axis}=$r/2$ is assumed.
\var{arg}
may be a \Data object or an \numarray object.
\end{funcdesc}

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

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

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

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

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

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

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

returns the gradient of \var{arg} as a function in the \FunctionSpace \var{where}.
If \var{where} is not present a reasonable \FunctionSpace is chosen.
\var{arg}
is a \Data object.
\end{funcdesc}

\begin{funcdesc}{integrate}{arg}
returns the integral of \var{arg} as a \numarray object.
If \var{where} is not present a reasonable \FunctionSpace is chosen.
\var{arg}
is a \Data object.
\end{funcdesc}

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

\section{\Operator Class}
454
455  The \Operator class provides an abstract access to operators build  \begin{methoddesc}[Data]{wherePositive}{}
456  within the \LinearPDE class. \Operator objects are created  returns \Data object which has the same shape and is defined on
457  when a PDE is handed over to a PDE solver library and handled  the same data points like the object. The returned values are $1$
458  by the \LinearPDE class defining the PDE. The user can gain access  where the object is positive and $0$ elsewhere.
459  to the \Operator of a \LinearPDE object through the \var{getOperator}  \end{methoddesc}
method.
460
461  \begin{classdesc}{Operator}{}  \begin{methoddesc}[Data]{whereNonnegative}{}
462  creates an empty \Operator object.  returns \Data object which has the same shape and is defined on
463  \end{classdesc}  the same data points like the object. The returned values are $1$
464    where the object is non-negative and $0$ elsewhere.
465    \end{methoddesc}
466
467  \begin{methoddesc}[Operator]{isEmpty}{fileName}  \begin{methoddesc}[Data]{whereNegative}{}
468  returns \True is the object is empty. Otherwise \True is returned.  returns \Data object which has the same shape and is defined on
469    the same data points like the object. The returned values are $1$
470    where the object is negative and $0$ elsewhere.
471  \end{methoddesc}  \end{methoddesc}
472
473  \begin{methoddesc}[Operator]{setValue}{value}  \begin{methoddesc}[Data]{whereZero}{tolerance=Constants.EPSILON}
474  resets all entires in the obeject representation to \var{value}  returns \Data object which has the same shape and is defined on
475    the same data points like the object. The returned values are $1$
476    where the object is nearly zero, i.e. where the absolute value is less
477    than \var{tolerance}, and $0$ elsewhere.
478  \end{methoddesc}  \end{methoddesc}
479
480  \begin{methoddesc}[Operator]{solves}{rhs}  \begin{methoddesc}[Data]{whereNonzero}{tolerance=Constants.EPSILON}
481  solves the operator equation with right hand side \var{rhs}  returns \Data object which has the same shape and is defined on
482    the same data points like the object. The returned values are $1$
483    where the object is nearly non-zero, i.e. where the absolute value is
484    greater or equal than \var{tolerance}, and $0$ elsewhere.
485  \end{methoddesc}  \end{methoddesc}
486
487  \begin{methoddesc}[Operator]{of}{u}  \begin{methoddesc}[Data]{saveDX}{fileName}
488  applies the operator to the \Data object \var{u}  saves the object to an openDX format file of name \var{fileName}, see
490  \end{methoddesc}  \end{methoddesc}
491
492  \begin{methoddesc}[Operator]{saveMM}{fileName}  \begin{methoddesc}[Data]{saveMM}{fileName}
493  saves the object to a matrix market format file of name  saves the object to a matrix market format file of name
494  \var{fileName}, see  \var{fileName}, see
496  \index{Matrix Market}  \index{Matrix Market}
497  \end{methoddesc}  \end{methoddesc}
498
499    %=====================================================
500    \section{Subclasses of \var{class}}
501    \begin{classdesc}{Scalar}{value=None,where=None,expand=None}
502    \Data object with a single value (scalar) per data
503    point. \var{value} must be a float number.  If \var{expand} is true,
504    the \var{value} is copied to each data point.
505    \end{classdesc}
506
507    \begin{classdesc}{Vector}{value=None,dim=None,where=None,expand=None}
508    \Data object with a vector of length \var{dim} value (scalar)
509    per data point.  If \var{dim} is not present or equals \var{None},
510    \var{dim} is assumed to be the spatial dimension of the data points
511    defined by \var{where}. \var{value} may be a float number or a
512    \class{numarray.array} object with shape (\var{dim},).  If
513    \var{expand} is true, the \var{value} is copied to each data point.
514    \end{classdesc}
515
516    \begin{classdesc}{Tensor}{value=None,dim=None,where=None,expand=None}
517    \Data object with a \var{dim} $\times$ \var{dim} - tensor of
518    order 2 per data point.  If \var{dim} is not present or equals
519    \var{None}, \var{dim} is assumed to be the spatial dimension of the
520    data points defined by \var{where}. \var{value} may be a float number
521    or a \class{numarray.array} object with shape (\var{dim},\var{dim}).
522    If \var{expand} is true, the \var{value} is copied to each data point.
523    \end{classdesc}
524
525    \begin{classdesc}{Tensor3}{value=None,dim=None,where=None,expand=None}
526    \Data object with a \var{dim} $\times$ \var{dim} $\times$
527    \var{dim} - tensor of order 3 per data point.  If \var{dim} is not
528    present or equals \var{None}, \var{dim} is assumed to be the spatial
529    dimension of the data points defined by \var{where}. \var{value} may
530    be a float number or a \class{numarray.array} object with shape
531    (\var{dim},\var{dim},var{dim}).  If \var{expand} is true, the
532    \var{value} is copied to each data point.
533    \end{classdesc}
534
535    \begin{classdesc}{Tensor4}{value=None,dim=None,where=None,expand=None}
536    \Data object with a \var{dim} $\times$ \var{dim} $\times$
537    \var{dim} $\times$ \var{dim} - tensor of order 4 per data point.  If
538    \var{dim} is not present or equals \var{None}, \var{dim} is assumed to
539    be the spatial dimension of the data points defined by
540    \var{where}. \var{value} may be a float number or a
541    \class{numarray.array} object with shape
542    (\var{dim},\var{dim},var{dim},var{dim}).  If \var{expand} is true, the
543    \var{value} is copied to each data point.
544    \end{classdesc}

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