/[escript]/trunk/doc/user/escript.tex
ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 82 by jgs, Tue Oct 26 06:53:54 2004 UTC revision 97 by jgs, Tue Dec 14 05:39:33 2004 UTC
# Line 2  Line 2 
2    
3  \chapter{The module \escript}  \chapter{The module \escript}
4    
5  \declaremodule{extension}{escript} \modulesynopsis{Handling data on  \declaremodule{extension}{escript}
6  data points like \class{Nodes}, \class{Elements}}  \modulesynopsis{Data manipulation}
7    
8  The class \Data of the module \escript allows handling  \begin{figure}
9  data which are hold on data points \index{data points}. Examples for  \includegraphics[width=\textwidth]{EscriptDiagram1.eps}
10  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
11  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.}
12  particles in the case of discrete element methods.  Handlers to data  \end{figure}
13  points are issued by the structure which contains the data points,  
14  e.g. a \finley mesh.  \escript is an extension of Python to handle functions represented by their values on
15    \DataSamplePoints. The \DataSamplePoints for the geometrical region on which
16  The 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
17  $a$ value which for instance represent the temperature or pressure at  to interpolate value on the \DataSamplePoints is defined by    
18  this particular data point. Another example is a velocity field. in  \Domain class objects. For instance when using
19  this case each data point holds a vector $a(0),a(1),a(2)$ representing  the finite element method (FEM) \index{finite element method}
20  the velocity at the particular data point. For the case that the  \Domain object holds the information about the FEM mesh, eg.
21  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
22  form  the discretization method to be used \escript does not use this information directly.
23  $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
24  general, values hald by data points can have up to four indices. The  \escript, e.g. \finley.
25  number of indices is called rank \index{rank}. The tuple of length  
26  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$.
27  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
28  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
29  shape (1,).  is discontinuous. To reflect these different degrees of smoothness different
30    representations of the functions are used. For instance; in FEM
31  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
32  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
33  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
34  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.
35  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
36  have slightly more general way which allows to define piecewise  a \FunctionSpace object and provides access to the function space of
37  constant data. For this, each data point has to wear a tag which is an  PDE solutions on the \Domain \var{mydomain}:
38  integer \index{tag}. The tag is used to distingish between various  \begin{python}
39  types of data points. Typical example of the usage of tags is to  solution_space=Solution(mydomain)
40  assign different material parameters to various subdomains. Then one  \end{python}
41  assigns the same tag to all elements in a finite element mesh which  The following generators for function spaces on a \Domain \var{mydomin} are available:
42  lay in the same subdomain.  Later each tag can be assigns individual  \begin{itemize}
43  material parameters.  \item \var{Solution(mydomain)}: solutions of a PDE.  
44    \item \var{ContinuousFunction(mydomain)}: continuous functions, eg. a temperature distribution.
45    \item \var{Function(mydomain)}: general functions which are not necessarily continuous, eg. a stress field.
46    \item \var{FunctionOnBoundary(mydomain)}: functions on the boundary of the domain, eg. a surface pressure.
47    \item \var{FunctionOnContact0(mydomain)}: functions on side $0$ of the discontinuity.
48    \item \var{FunctionOnContact1(mydomain)}: functions on side $1$ of the discontinuity.
49    \end{itemize}
50    A discontinuity \index{discontinuity} is a region within the domain across which functions may be discontinuous.  
51    The location of discontinuity is defined in the \Domain object.
52    \fig{ESCRIPT DEP} shows the dependency between the types of function spaces.
53    The solution of a PDE is a continuous function. Any continuous function can be seen as a general function
54    on the domain and can be restricted to the boundary as well as to any side of the
55    discontinuity (the result will be different depending on
56    which side is chosen). Functions on any side of the  
57    discontinuity can be seen as a function on the corresponding other side.
58    A function on the boundary or on one side of
59    the discontinuity cannot be seen as a general function on the domain as there are no values
60    defined for the interior. For most PDE solver libraries
61    the space of the solution and continuous functions is identical, however in some cases, eg.
62    when periodic boundary conditions are used in \finley, a solution
63    fulfils periodic boundary conditions while a continuous function does not have to be periodic.
64      
65    The concept of function spaces describes the properties of
66    functions and allows abstraction from the actual representation
67    of the function in the context of a particular application. For instance,
68    in the FEM context a
69    function in the \Function function space
70    is typically represented by its values at the element center,
71    but in a finite difference scheme the edge midpoint of cells is preferred.
72    Using the concept of function spaces
73    allows the user to run the same script on different
74    PDE solver libraries by just changing the creator of the \Domain object.    
75    Changing the function space of a particular function
76    will typically lead to a change of its representation.
77    So, when seen as a general function,
78    a continuous function which is typically represented by its values
79    on the node of the FEM mesh or finite difference grid
80    has to be interpolated to the element centers or the cell edges,
81    respectively.
82    
83    \Data class objects store functions of the location in a domain.
84    The function is represented through its values on \DataSamplePoints where
85    the \DataSamplePoints are chosen according to the function space
86    of the function.  
87    \Data class objects are used to define the coefficients
88    of the PDEs to be solved by a PDE solver library
89    and to store the returned solutions.
90    
91    The values of the function have a rank which gives the
92    number of indexes, and a \Shape defining the range of each index.
93    The rank in \escript is limited to the range $0$ through $4$ and
94    it is assumed that the rank and \Shape is the same for all \DataSamplePoints.
95    The \Shape of a \Data object is a tuple \var{s} of integers. The length
96    of \var{s} is the rank of the \Data object and \var{s[i]} is the maximum
97    value for the \var{i}-th index.
98    For instance, a stress field has rank $2$ and
99    \Shape $(d,d)$ where $d$ is the spatial dimension.
100    The following statement creates the \Data object
101    \var{mydat} representing a
102    continuous function with values
103    of \Shape $(2,3)$ and rank $2$:
104    \begin{python}
105    mydat=Data(value=1,what=ContinuousFunction(myDomain),shape=(2,3))
106    \end{python}
107    The initial value is the constant $1$ for all \DataSamplePoints and
108    all components.
109    
110    \Data objects can also be created from any \numarray
111    array or any object, such as a list of floating point numbers,
112    that can be converted into a \numarray array \Ref{NUMARRAY}.
113    The following two statements
114    create objects which are equivalent to \var{mydat}:
115    \begin{python}
116    mydat1=Data(value=numarray.ones((2,3)),what=ContinuousFunction(myDomain))
117    mydat2=Data(value=[[1,1],[1,1],[1,1]],what=ContinuousFunction(myDomain))
118    \end{python}
119    In the first case the initial value is \var{numarray.ones((2,3))}
120    which generates a $2 \times 3$ matrix as a \numarray array
121    filled with ones. The \Shape of the created \Data object
122    it taken from the \Shape of the array. In the second
123    case, the creator converts the initial value, which is a list of lists,
124    and converts it into a \numarray array before creating the actuall
125    \Data object.      
126    
127    For convenience \escript provides creators for the most common types
128    of \Data objects in the following forms (\var{d} defines the
129    spatial dimension):
130    \begin{itemize}
131    \item \var{Scalar(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(,))},
132    e.g a temperature field.
133    \item \var{Vector(0,Function(mydomain))}is the same as \var{Data(0,Function(myDomain),(d))}, e.g
134    a velocity field.  
135    \item \var{Tensor(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d,d))},
136    eg. a stress field.  
137    \item \var{Tensor4(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d,d,d,d))}
138    eg. a Hook tensor field.  
139    \end{itemize}
140    Here the initial value is $0$ but any object that can be converted into a \numarray array and whose \Shape
141    is consistent with \Shape of the \Data object to be created can be used as the initial value.
142    
143    \Data objects can be manipulated by applying unitary operations (eg. cos, sin, log)
144    and be combined by applying binary operations (eg. +, - ,* , /).
145    It is to be emphasized that \escript itself does not handle any spatial dependencies itself as
146    it does not know how values are interpreted by the processing PDE solver library.
147    However \escript invokes interpolation if this is needed during data manipulations.
148    Typically, this occurs in binary operation when both arguments belong to different
149    function spaces or when data are handed over to a PDE solver library
150    which requires functions to be represented in a particular way.
151    
152    The following example shows the usage of {\tt Data} objects: Assume we have a
153    displacement field $u$ and we want to calculate the corresponding stress field
154    $\sigma$ using the linear--elastic isotropic material model
155    \begin{eqnarray}\label{eq: linear elastic stress}
156    \sigma\hackscore {ij}=\lambda u\hackscore {k,k} \delta\hackscore {ij} + \mu ( u\hackscore {i,j} + u\hackscore {j,i})
157    \end{eqnarray}
158    where $\delta\hackscore {ij}$ is the Kronecker symbol and
159    $\lambda$ and $\mu$ are the Lame coefficients. The following function
160    takes the displacement {\tt u} and the Lame coefficients
161    \var{lam} and \var{mu} as arguments and returns the corresponding stress:
162    \begin{python}
163    import numarray
164    def getStress(u,lam,mu):
165      d=u.getDomain().getDim()
166      g=grad(u)
167      stress=lam*trace(g)*numarray.identity(d)+ \
168                                     mu*(g+transpose(g))
169      return stress    
170    \end{python}
171    The variable
172    \var{d} gives the spatial dimension of the
173    domain on which the displacements are defined.
174    \var{identity} is a \numarray function which returns the Kronecker symbol with indexes
175    $i$ and $j$ running from $0$ to \var{d}-1. The call \var{grad(u)} requires
176    the displacement field \var{u} to be in the \var{Solution} or \ContinuousFunction
177    function space. The result \var{g} as well as the returned stress will be in the \Function function space.
178    If \var{u} is available, eg. by solving a PDE, \var{getStress} might be called
179    in the following way:
180    \begin{python}
181    s=getStress(u,1.,2.)
182    \end{python}
183    However \var{getStress} can also be called with \Data objects as values for
184    \var{lam} and \var{mu} which,
185    for instance in the case of a temperature dependency, are calculated by an expression.
186    The following call is equivalent to the previous example:
187    \begin{python}
188    lam=Scalar(1.,ContinuousFunction(mydomain))
189    mu=Scalar(2.,Function(mydomain))
190    s=getStress(u,lam,mu)
191    \end{python}
192    The function \var{lam} belongs to the \ContinuousFunction function space
193    but with \var{g} the function \var{trace(g)} is in the \Function function space.
194    Therefore the evaluation of the product \var{lam*trace(g)} in the stress calculation
195    produces a problem, as both functions are represented differently, eg. in FEM
196    \var{lam} by its values on the node, and in \var{trace(g)} by its values at the element centers.
197    In the case of inconsistent function spaces of arguments in a binary operation, \escript
198    interprets the arguments in the appropriate function space according to the inclusion
199    defined in Table~\ref{ESCRIPT DEP}. In this example that means
200     \escript sees \var{lam} as a function of the \Function function space.
201    In the context of FEM this means the nodal values of
202    \var{lam} are interpolated to the element centers. Behind the scenes
203    \escript calls the appropriate function from the PDE solver library.
204    
205    \begin{figure}
206    \includegraphics[width=\textwidth]{EscriptDiagram2.eps}
207    \caption{\label{Figure: tag}Element Tagging. A rectangular mesh over a region with two rock types {\it white} and {\it gray}.
208    The number in each cell refers to the major rock type present in the cell ($1$ for {\it white} and $2$ for {\it gray}).
209    }
210    \end{figure}
211    
212    Material parameters such as the Lame coefficients are typically dependent on rock types present in the
213    area of interest. A common technique to handle these kinds of material parameters is "tagging". \fig{Figure: tag}
214    shows an example. In this case two rock types {\it white} and {\it gray} can be found in the domain. The domain
215    is subdivided into rectangular shaped cells (which is not necessarily the best subdivision for this case). Each
216    cell has a tag indicating the rock type predominately found in this cell. Here $1$ is used to indicate
217    rock type {\it white} and $2$ for rock type {\it gray}. The tags are assigned at the time when the cells are generated
218    (\escript provides tools to manipulate tags at a later stage)
219    and stored in the \Domain class object. The following statements show how for the
220    example of \fig{Figure: tag} and the stress calculation discussed before tagged values are used for
221    \var{lam}:
222    \begin{python}
223    lam=Scalar(value=2.,what=Function(mydomain))
224    lam.setTaggedValue(1,30.)
225    lam.setTaggedValue(2,5000.)
226    s=getStress(u,lam,2.)
227    \end{python}
228    In this example \var{lam} is set to $30$ for those cells with tag $1$ and to $5000.$ for those cells
229    with tag $2$. The initial value $2$ of \var{lam} is used as a default value for the case when a tag
230    is encountered which has not been linked with a value. Note that the \var{getStress} method
231    is called without modification. \escript resolves the tags when \var{lam*trace(g)} is calculated.
232    
233    The \Data class provides a transparent interface to various data representations and the
234    translations between them. As shown in the example of stress calculation, this allows the user to
235    develop and test algorithms for a simple case (for instance with the Lame coefficients as constants)
236    and then without further modifications of the program code to apply the algorithm in a
237    more complex application (for instance a definition of the Lame coefficients using tags).
238    As described here, there are three ways in which \Data objects are represented internally, constant, tagged, and expanded (other representions will become available in later versions of \escript):
239    In the constant case, if the same value is used at each sample point a single value is stored to save memory and compute time.
240    Any operation on this constant data will only be performed on the single value.
241    In the expanded case, each sample point has an individual value, eg. the solution of a PDE,
242    and the values are stored as a complete array. The tagged case has already been discussed above.
243    
244    Values are accessed through a sample reference number. Operations on expanded \Data
245    objects have to be performed for each sample point individually. If tagged values are used values are
246    held in a dictionary. Operations on tagged data require processing the set of tagged values only, rather than
247    processing the value for each individual sample point.
248    \escript allows use of constant, tagged and expanded data in a single expression.
249    
250    
251    
252    \section{\Domain class}
253    
254    \begin{classdesc}{Domain}{}
255    A \Domain objects is used to describe a geometrical region together with
256    a way of representing functions over this region.
257    The \Domain class provides an abstract access to the domain of \FunctionSpace and \Data objects.
258    \Domain itself has no initialization but implementations of \Domain are
259    instantiated by numerical libraries making use of \Data objects.
260    \end{classdesc}
261    
262    \begin{methoddesc}[Domain]{getDim}{}
263    returns the spatial dimension of the \Domain.
264    \end{methoddesc}
265    
266    \begin{methoddesc}[Domain]{getX}{}
267    returns the locations in the \Domain. The \FunctionSpace of the returned
268    \Data object is chosen by the \Domain implementation. Typically it will be
269    in the \Function.
270    \end{methoddesc}
271    
272    \begin{methoddesc}[Domain]{setX}{newX}
273    assigns a new location to the \Domain. \var{newX} has to have \Shape $(d,)$
274    where $d$ is the spatial dimension of the domain. Typically \var{newX} must be
275    in the \ContinuousFunction but the space actually to be used depends on the \Domain implementation.
276    \end{methoddesc}
277    
278    \begin{methoddesc}[Domain]{getNormal}{}
279    returns the surface normals on the boundary of the \Domain as \Data object.
280    \end{methoddesc}
281    
282    \begin{methoddesc}[Domain]{getSize}{}
283    returns the local sample size, e.g. the element diameter, as \Data object.
284    \end{methoddesc}
285    
286    \begin{methoddesc}[Domain]{__eq__}{arg}
287    returns \True of the \Domain \var{arg} describes the same domain. Otherwise
288    \False is returned.
289    \end{methoddesc}
290    
291    \begin{methoddesc}[Domain]{__ne__}{arg}
292    returns \True of the \Domain \var{arg} does not describe the same domain.
293    Otherwise \False is returned.
294    \end{methoddesc}
295    
296    \section{\Domain class}
297    \begin{classdesc}{FunctionSpace}{}
298    \FunctionSpace objects are used to define properties of \Data objects, such as continuity. \FunctionSpace objects
299    are instantiated by generator functions. \Data objects in particular \FunctionSpace are
300    represented by their values at \DataSamplePoints which are defined by the type and the \Domain of the
301    \FunctionSpace.
302    \end{classdesc}
303    
304    \begin{methoddesc}[FunctionSpace]{getDim}{}
305    returns the spatial dimension of the \Domain of the \FunctionSpace.
306    \end{methoddesc}
307    
308    \begin{methoddesc}[FunctionSpace]{getX}{}
309    returns the location of the \DataSamplePoints.
310    \end{methoddesc}
311    
312    \begin{methoddesc}[FunctionSpace]{getNormal}{}
313    If the domain of functions in the \FunctionSpace
314    is a hypermanifold (e.g. the boundary of a domain)
315    the method returns the outer normal at each of the
316    \DataSamplePoints. Otherwise an exception is raised.
317    \end{methoddesc}
318    
319    \begin{methoddesc}[FunctionSpace]{getSize}{}
320    returns a \Data objects measuring the spacing of the \DataSamplePoints.  
321    The size may be zero.
322    \end{methoddesc}
323    
324    \begin{methoddesc}[FunctionSpace]{getDomain}{}
325    returns the \Domain of the \FunctionSpace.
326    \end{methoddesc}
327    
328    \begin{methoddesc}[FunctionSpace]{__eq__}{arg}
329    returns \True of the \Domain \var{arg} describes the same domain. Otherwise
330    \False is returned.
331    \end{methoddesc}
332    
333    \begin{methoddesc}[FunctionSpace]{__ne__}{arg}
334    returns \True of the \Domain \var{arg} describes the note same domain.
335    Otherwise \False is returned.
336    \end{methoddesc}
337    
338    The following function provide generators for \FunctionSpace objects:
339    \begin{funcdesc}{Function}{domain}
340    returns the \Function on the \Domain \var{domain}. \Data objects in this type of \Function
341    are defined over the whole geometrical region defined by \var{domain}.
342    \end{funcdesc}
343    
344    \begin{funcdesc}{ContinuousFunction}{domain}
345    returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function
346    are defined over the whole geometrical region defined by \var{domain} and assumed to represent
347    a continuous function.
348    \end{funcdesc}
349    
350    \begin{funcdesc}{FunctionOnBoundary}{domain}
351    returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function
352    are defined on the boundary of the geometrical region defined by \var{domain}.
353    \end{funcdesc}
354    
355    \begin{funcdesc}{FunctionOnContactZero}{domain}
356    returns the \FunctionOnContactZero the \Domain domain. \Data objects in this type of \Function
357    are defined on side 0 of a discontinutiy  within the geometrical region defined by \var{domain}.
358    The discontinutiy is defined when \var{domain} is instantiated.
359    \end{funcdesc}
360    
361    \begin{funcdesc}{FunctionOnContactOne}{domain}
362    returns the \FunctionOnContactOne on the \Domain domain.
363    \Data objects in this type of \Function
364    are defined on side 1 of a discontinutiy  within the geometrical region defined by \var{domain}.
365    The discontinutiy is defined when \var{domain} is instantiated.
366    \end{funcdesc}
367    
368    \begin{funcdesc}{Solution}{domain}
369    returns the \SolutionFS on the \Domain domain. \Data objects in this type of \Function
370    are defined on geometrical region defined by \var{domain} and are solutions of
371    partial differential equations \index{partial differential equation}.
372    \end{funcdesc}
373    
374    \begin{funcdesc}{ReducedSolution}{domain}
375    returns the \ReducedSolutionFS on the \Domain domain. \Data objects in this type of \Function
376    are defined on geometrical region defined by \var{domain} and are solutions of
377    partial differential equations \index{partial differential equation} with a reduced smoothness
378    for the solution approximation.
379    \end{funcdesc}
380    
381  The following table shows unitary operations that can be applied to an  \section{\Data Class}
 \Data object \var{arg}:  
 \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}.  
382    
383  The following table shows binary operations that can be applied to  
384    The following table shows binary and unitary operations that can be applied to
385  \Data objects:  \Data objects:
386  \begin{tableii}{l|l}{textrm}{expression}{Description}  \begin{tableii}{l|l}{textrm}{expression}{Description}
387    \lineii{+\var{arg1}} {just \var{arg} \index{+}}
388    \lineii{-\var{arg1}} {swapping the sign\index{-}}
389  \lineii{\var{arg1}+\var{arg2}} {adds \var{arg1} and \var{arg2} \index{+}}  \lineii{\var{arg1}+\var{arg2}} {adds \var{arg1} and \var{arg2} \index{+}}
390  \lineii{\var{arg1}*\var{arg2}} {multiplies \var{arg1} and \var{arg2} \index{*}}  \lineii{\var{arg1}*\var{arg2}} {multiplies \var{arg1} and \var{arg2} \index{*}}
391  \lineii{\var{arg1}-\var{arg2}} {difference \var{arg2} from\var{arg2} \index{-}}  \lineii{\var{arg1}-\var{arg2}} {difference \var{arg2} from\var{arg2} \index{-}}
# Line 68  The following table shows binary operati Line 395  The following table shows binary operati
395  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
396  \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
397  converted into a \Data object. If \var{arg1} or \var{arg2} are  converted into a \Data object. If \var{arg1} or \var{arg2} are
398  defined on different data points it is tried to interpolate \var{arg1}  defined on different \FunctionSpace it is tried to embed \var{arg1}
399  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
400  the data points of \var{arg1}. Boths arguments must have the same  the \FunctionSpace of \var{arg1}. Boths arguments must have the same
401  shape or one of the arguments my be of rank 0 or shape (1,). In the  \Shape or one of the arguments my be of rank 0 or \Shape (1,). In the
402  latter case it is assumed that the particular argument is of the same  latter case it is assumed that the particular argument is of the same
403  shape like the other argument but constant over all components.  \Shape like the other argument but constant over all components.
404    
405  The returned \Data object has the same shape and is defined on  The returned \Data object has the same \Shape and is defined on
406  the data points like \var{arg1} or \var{arg2}.  the \DataSamplePoints like \var{arg1} or \var{arg2}.
407    
408  The following table shows the update operations that can be applied to  The following table shows the update operations that can be applied to
409  \Data objects:  \Data objects:
# Line 88  The following table shows the update ope Line 415  The following table shows the update ope
415  \end{tableii}  \end{tableii}
416  \var{arg1} must be a \Data object. \var{arg1} must be a  \var{arg1} must be a \Data object. \var{arg1} must be a
417  \Data object or an object that can be converted into a  \Data object or an object that can be converted into a
418  \Data object. \var{arg1} must have the same shape like  \Data object. \var{arg1} must have the same \Shape like
419  \var{arg1} or has rank 0 or shape (1,).  In the latter case it is  \var{arg1} or has rank 0 or \Shape (1,).  In the latter case it is
420  assumed that the values of \var{arg1} are constant for all  assumed that the values of \var{arg1} are constant for all
421  components. \var{arg2} must be defined on the same data points like  components. \var{arg2} must be defined on the same \DataSamplePoints like
422  \var{arg1} or it must be possible to interpolate \var{arg2} onto the  \var{arg1} or it must be possible to interpolate \var{arg2} onto the
423  data points where \var{arg1} is hold.  \DataSamplePoints where \var{arg1} is hold.
   
   
 %TODO:  
 Slicing \index{slicing}.  
424    
425  \begin{classdesc}{Data}{}  The \Data class supports getting slices as well as assigning new values to components in an existing
426  A class that holds values assigned to data points.  \Data object \index{slicing}.
427  \end{classdesc}  The following expression for getting (expression on the right hand side of the
428    equal sign) and setting slices (expression on the left hand side of the
429  \begin{classdesc}{Scalar}{value=None,where=None,expand=None}  equal sign) are valid:
430  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}
431  \end{classdesc}  \lineiii{0}{ no slicing }                      {-}
432    \lineiii{1}{\var{arg[l0:u0]}}                   {(\var{u0}-\var{l0},)}
433    \lineiii{2}{\var{arg[l0:u0,l1:u1]}}             {(\var{u0}-\var{l0},\var{u1}-\var{l1})}
434    \lineiii{3}{\var{arg[l0:u0,l1:u1,l2:u2]} }      {(\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2})}
435    \lineiii{4}{\var{arg[l0:u0,l1:u1,l2:u2,l3:u3]}} {(\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2},\var{u3}-\var{l3})}
436    \end{tableiii}
437    where
438    $0 \le \var{l0} \le \var{u0} \le \var{s[0]}$,
439    $0 \le \var{l1} \le \var{u1} \le \var{s[1]}$,
440    $0 \le \var{l2} \le \var{u2} \le \var{s[2]}$,
441    $0 \le \var{l3} \le \var{u3} \le \var{s[3]}$ and \var{s} the \Shape if \var{arg}.
442    Any of the lower indexes \var{l0}, \var{l1}, \var{l2} and \var{l3} may not be present in which case
443    $0$ is assumed.
444    Any of the upper indexes \var{u0}, \var{u1}, \var{u2} and \var{u3} may not be present in which case
445    \var{s} is assumed. The lower and upper index may be identical, in which case the column and the lower or upper
446    index may be dropped. In the returned or in the object assigned to a slice the corresponding component is dropped,
447    i.e. the rank is reduced by one in comparison to \var{arg}.
448    The follwing examples showing the usage of slicing:  
449    \begin{python}
450    t[1,1,1,0]=9.
451    s=t[:2,:,2:6,5] # s has rank 3
452    s[:,:,1]=1.
453    t[:2,:2,5,5]=s[2:4,1,:2]
454    \end{python}
455    
 \begin{classdesc}{Vector}{value=None,dim=None,where=None,expand=None}  
 A class that holds a vector per data point.  
 \end{classdesc}  
456    
 \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}  
457    
458  \begin{classdesc}{Tensor3}{value=None,dim=None,where=None,expand=None}  \begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expanded=\False}
459  A class that holds a tensor order 3 per data point.  creates a \Data object with \Shape \var{shape} in the \FunctionSpace \var{what}.
460    The values at all \DataSamplePoints are set to the double value \var{value}. If \var{expanded} is \True
461    the \Data object is represented in expanded from.
462    \end{classdesc}
463    
464    \begin{classdesc}{Data}{value,what=FunctionSpace(),expanded=\False}
465    creates a \Data object in the \FunctionSpace \var{what}.
466    The value for each \DataSamplePoints is set to \numarray object \var{value}.
467    The \Shape of the returned object is equal to the \Shape of \var{value}. If \var{expanded} is \True
468    the \Data object is represented in expanded from.
469    \end{classdesc}
470    
471    \begin{classdesc}{Data}{value,what=FunctionSpace()}
472    creates a \Data object in the \FunctionSpace \var{what} from the \Data object \var{value}.
473    The \Shape of the created \Data object is equal to the \Shape of \var{value}.
474    If the \FunctionSpace of \var{value} is equal to the \var{what}, a shallow copy, i.e.
475    a reference to the representation of \var{value} is greated. Otherwise,
476    \var{value} is interpolated into the \var{what}.
477  \end{classdesc}  \end{classdesc}
478    
479  \begin{classdesc}{Tensor4}{value=None,dim=None,where=None,expand=None}  \begin{classdesc}{Data}{}
480  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
481    where a \Data object is required.
482  \end{classdesc}  \end{classdesc}
483    
484  \begin{funcdesc}{abs}{arg}  \begin{methoddesc}[Data]{getFunctionSpace}{}
485  returns the absulute value of \Data \var{arg}. The returned  returns the \FunctionSpace of the object.
486  \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}  
   
 \begin{funcdesc}{grad}{arg}  
 returns the gradient of the interpolation function of \Data  
 \var{arg} by using \method{arg.grad}. \index{gradient}  
 \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}  
487    
488  \begin{funcdesc}{minval}{arg}  \begin{methoddesc}[Data]{getFunctionSpace}{}
489  returns for each data point the minimum value over all components of  returns the \Domain  of the object.
490  \Data \var{arg} by using \method{arg.minval}.  \index{minimum  \end{methoddesc}
 value}  
 \end{funcdesc}  
491    
492  \begin{funcdesc}{inf}{arg}  \begin{methoddesc}[Data]{getShape}{}
493  returns the minimum value (infimum) over all components and all data  returns the \Shape  of the object as a \class{tuple} of
494  points of \Data \var{arg} by using \method{arg.inf}.  integers.
495  \index{infimum}  \end{methoddesc}
 \end{funcdesc}  
496    
497  \begin{funcdesc}{sup}{arg}  \begin{methoddesc}[Data]{getRank}{}
498  returns the maximum value (supremum) over all components and all data  returns the rank of the data on each data point. \index{rank}
499  points of \Data \var{arg} by using \method{arg.sup}.  \end{methoddesc}
 \index{supremum}  
 \end{funcdesc}  
500    
501  \begin{funcdesc}{Lsup}{arg}  \begin{methoddesc}[Data]{isEmpty}{}
502  returns the maximum absulute value ($L^{sup}$-norm) over all  returns \True id the \Data object is the \EmptyData object.
503  components and all data points of \Data \var{arg} by using  Otherwise \False is returned.
504  \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  
 \begin{equation}  
 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)  
 \end{equation}  
 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}  
505    
506  \begin{methoddesc}[Data]{getAtoms}{}  \begin{methoddesc}[Data]{setTaggedValue}{tag,value}
507  returns a handel to the data points on which the object is definded  assigns the \var{value} to all \DataSamplePoints which have the tag
508  \index{data points}.  The returned object is of \class{_Atoms}.  \var{tag}. \var{value} must be an object of class
509    \class{numarray.array} or must be convertable into a
510    \class{numarray.array} object. \var{value} (or the cooresponding
511    \class{numarray.array} object) must be of rank $0$ or must have the
512    same rank like the object.
513    If a value has already be defined for tag \var{tag} within the object
514    it is overwritten by the new \var{value}.  If the object is expanded,
515    the value assigned to \DataSamplePoints with tag \var{tag} is replaced by
516    \var{value}.
517  \end{methoddesc}  \end{methoddesc}
518    
519  \begin{methoddesc}[Data]{getShape}{}  \begin{methoddesc}[Data]{wherePositive}{}
520  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
521  integers. \index{shape}  the same \FunctionSpace like the object. The returned values are $1$
522    where the object is positive and $0$ elsewhere.
523  \end{methoddesc}  \end{methoddesc}
524    
525  \begin{methoddesc}[Data]{getRank}{}  \begin{methoddesc}[Data]{wherePositive}{}
526  returns the rank of the data on each data point. \index{rank}  returns \Data object which has the same \Shape and is defined on
527    the same \FunctionSpace like the object. The returned values are $1$
528    where the object is non-positive and $0$ elsewhere.
529  \end{methoddesc}  \end{methoddesc}
530    
531  \begin{methoddesc}[Data]{hasShape}{shape}  \begin{methoddesc}[Data]{whereNonnegative}{}
532  is true if the object has the shape \var{shape}.  returns \Data object which has the same \Shape and is defined on
533    the same \FunctionSpace like the object. The returned values are $1$
534    where the object is non-negative and $0$ elsewhere.
535  \end{methoddesc}  \end{methoddesc}
536    
537  \begin{methoddesc}[Data]{expand}{}  \begin{methoddesc}[Data]{whereNegative}{}
538  returns an expanded version of the object if the object is not  returns \Data object which has the same \Shape and is defined on
539  expanded. Otherwise it returns itself. \index{expanded}  the same \FunctionSpace like the object. The returned values are $1$
540    where the object is negative and $0$ elsewhere.
541  \end{methoddesc}  \end{methoddesc}
542    
543  \begin{methoddesc}[Data]{makeExpanded}{}  \begin{methoddesc}[Data]{whereZero}{tolerance=1.e-8}
544  turns the object into an expanded \Data  returns \Data object which has the same \Shape and is defined on
545  object. \index{expanded}  the same \FunctionSpace like the object. The returned values are $1$
546    where the object is nearly zero, i.e. where the absolute value is less
547    than \var{tolerance}, and $0$ elsewhere.
548  \end{methoddesc}  \end{methoddesc}
549    
550  \begin{methoddesc}[Data]{isExpanded}{}  \begin{methoddesc}[Data]{whereNonzero}{tolerance=1.e-8}
551  is true if the object is expanded. \index{expanded}  returns \Data object which has the same \Shape and is defined on
552    the same \FunctionSpace like the object. The returned values are $1$
553    where the object is nearly non-zero, i.e. where the absolute value is
554    greater or equal than \var{tolerance}, and $0$ elsewhere.
555  \end{methoddesc}  \end{methoddesc}
556    
557  \begin{methoddesc}[Data]{isTagged}{}  \begin{methoddesc}[Data]{sign}{}
558  is true if the object is defined using tags. \index{tagged}  returns \Data object which has the same \Shape and is defined on
559    the same \FunctionSpace like the object. The returned values are $1$
560    where the object is positive, $-1$ where the value is negative and $0$ elsewhere.
561  \end{methoddesc}  \end{methoddesc}
562    
563  \begin{methoddesc}[Data]{asArray}{}  \begin{methoddesc}[Data]{copyWithMask}{arg,mask}
564  returns the object as a \class{numarray.array} array. The array is one  copies the \Data object \var{arg} into the object
565  rank higher than the rank of the object. The extra dimension is the  where the \Data object \var{mask} is positive. \var{arg}
566  number of data points.  and \var{mask} must have the same \Shape
567  % TODO: be more accurate on the shape  and must belong to same \FunctionSpace as
568    the object.
569  \end{methoddesc}  \end{methoddesc}
570    
571  \begin{methoddesc}[Data]{addTaggedValue}{tag,value=0}  \begin{methoddesc}[Data]{Lsup}{}
572  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}.
573  \var{tag} which has to be an integer or a list of  \end{methoddesc}
574  integers. \var{value} must be an object of class  \begin{methoddesc}[Data]{inf}{}
575  \class{numarray.array} or must be convertable into a  returns the minimum value (infimum) of the object. The minimum is
576  \class{numarray.array} object. \var{value} (or the cooresponding  taken over all components and all \DataSamplePoints .  \index{infimum}
577  \class{numarray.array} object) must be of rank $0$ or must have the  \end{methoddesc}
 same rank like the object. \index{tagged}  
578    
579  If a value has allready be defined for tag \var{tag} within the object  \begin{methoddesc}[Data]{sup}{}
580  it is overwritten by the new \var{value}.  If the object is expanded,  returns the maximum value (supremum) of the object. The maximum is
581  the value assigned to data points with tag \var{tag} is replaced by  taken over all components and all \DataSamplePoints .  \index{supremum}
 \var{value}.  
582  \end{methoddesc}  \end{methoddesc}
583    
584  \begin{methoddesc}[Data]{getTaggedValue}{tag}  \begin{methoddesc}[Data]{grad}{\optional{on}}
585  returns the value assigned to \var{tag}. An exception is raised if the  returns the gradient of the function represented by the object.
586  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.
587  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}  
   
 \begin{methoddesc}[Data]{grad}{}  
 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  
 gradient is defined on the quadrature points of elements.  
588  \index{gradient}  \index{gradient}
589  \end{methoddesc}  \end{methoddesc}
590    
591  \begin{methoddesc}[Data]{integrate}{}  \begin{methoddesc}[Data]{integrate}{}
592  returns the integral of the interpolation function. The method returns  returns the integral of the function represented by the object. The method returns
593  a \class{numarray.array} object of the same shape like the object.  A  a \class{numarray.array} object of the same \Shape like the object.  A
594  component of the returned object is the integral of the corresponding  component of the returned object is the integral of the corresponding
595  component of the object.  \index{integral}  component of the object. \index{integral}
596  \end{methoddesc}  \end{methoddesc}
597    
598  \begin{methoddesc}[Data]{interpolate}{where}  \begin{methoddesc}[Data]{interpolate}{on}
599  interpolates onto the data points of the \class{_Atom}  interpolates
600  \var{where}. The returned \Data object is of the same shape  the function represented by the object
601  like the object and is defined on the data points \var{where}.  into the \FunctionSpace\var{on}.
602  \index{interpolation}  \index{interpolation}
603  \end{methoddesc}  \end{methoddesc}
604    
605  \begin{methoddesc}[Data]{transpose}{}  \begin{methoddesc}[Data]{abs}{}
606  returns the transpose of the object. The return value is an object has  applies the absolute value function to the object. The
607  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
608  For each data point the value is set to transposed of the  \FunctionSpace like the object. For all \DataSamplePoints and all
609  corresponding value of the object by reversing the index of the data.  components the value is calculated by applying the exponential
610    function. \index{function!absolute value}
 For the case that object \var{self} is of rank 3 the result \var{res} is  
 \begin{equation}  
 res(i,j,k;s)=self(k,j,i;s)  
 \end{equation}  
 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}  
611  \end{methoddesc}  \end{methoddesc}
612    
613  \begin{methoddesc}[Data]{trace}{}  \begin{methoddesc}[Data]{exp}{}
614  returns the trace of the object of rank 2. The return value is an  applies the exponential function to the object. The
615  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
616  like the object. For each data point the value is set to sum of the  \FunctionSpace like the object. For all \DataSamplePoints and all
617  main diagonal entries.  components the value is calculated by applying the exponential
618    function. \index{function!exponential}
 For the case that object \var{self} is of rank 2 the result \var{res}  
 is  
 \begin{equation}  
 res(0;s)=  
 self(0,0;s)+  
 self(1,1;s)+  
 \ldots +  
 self(n,n;s)  
 \end{equation}  
 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}  
619  \end{methoddesc}  \end{methoddesc}
620    
621  \begin{methoddesc}[Data]{sqrt}{}  \begin{methoddesc}[Data]{sqrt}{}
622  applies the square root function to the values of the object. The  applies the square root function to the object. The
623  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
624  same data points like the object.  For each data point and all  \FunctionSpace like the object. For all \DataSamplePoints and all
625  components the value is calculated by applying the square root  components the value is calculated by applying the square root function.
626  function to the corresponding value of the object. An exception is  An exception is
627  raised if the value is negative.  \index{square root}  raised if the value is negative.  \index{function!square root}
628  \end{methoddesc}  \end{methoddesc}
629    
630  \begin{methoddesc}[Data]{sin}{}  \begin{methoddesc}[Data]{sin}{}
631  applies the sine function to the values of the object. The return  applies the sine function to the object. The
632  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
633  points like the object.  For each data point and all components the  \FunctionSpace like the object. For all \DataSamplePoints and all
634  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}  
635  \end{methoddesc}  \end{methoddesc}
636    
637  \begin{methoddesc}[Data]{cos}{}  \begin{methoddesc}[Data]{cos}{}
638  applies the cosine function to the values of the object. The return  applies the cosine function to the object. The
639  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
640  points like the object.  For each data point and all components the  \FunctionSpace like the object. For all \DataSamplePoints and all
641  value is calculated by applying the cosine function to the  components the value is calculated by applying the cosine function. \index{function!cosine}
642  corresponding value of the object.  \index{cosine function}  \end{methoddesc}
643    
644    \begin{methoddesc}[Data]{tan}{}
645    applies the tangent function to the object. The
646    return \Data object has the same \Shape and is in the same
647    \FunctionSpace like the object. For all \DataSamplePoints and all
648    components the value is calculated by applying the tangent function. \index{function!tangent}
649    \end{methoddesc}
650    
651    \begin{methoddesc}[Data]{log}{}
652    applies the logarithmic function to the object. The
653    return \Data object has the same \Shape and is in the same
654    \FunctionSpace like the object. For all \DataSamplePoints and all
655    components the value is calculated by applying the logarithmic function. An exception is
656    raised if the value is negative.\index{function!logarithmic}
657  \end{methoddesc}  \end{methoddesc}
658    
659  \begin{methoddesc}[Data]{maxval}{}  \begin{methoddesc}[Data]{maxval}{}
660  returns for each data point the maximum value over all components. The  returns the maximum value over all components. The
661  return value is an object of rank 0 or shape (1,) and is defined on  return value is a \Data object of rank 0
662  the same data points like the object.  \index{maximum value}  and is in the same
663    \FunctionSpace like the object. For all \DataSamplePoints
664    the value is calculated as the maximum value over all components. \index{function!maximum}
665  \end{methoddesc}  \end{methoddesc}
666    
667  \begin{methoddesc}[Data]{minval}{}  \begin{methoddesc}[Data]{minval}{}
668  returns for each data point the minimum value over all components. The  returns the minimum value over all components. The
669  return value is an object of rank 0 or shape (1,) and is defined on  return value is a \Data object of rank 0
670  the same data points like the object.  \index{minimum value}  and is in the same
671    \FunctionSpace like the object. For all \DataSamplePoints
672    the value is calculated as the minimum value over all components. \index{function!minimum}
673    \end{methoddesc}
674    
675    \begin{methoddesc}[Data]{length}{}
676    returns the Euclidean length at all \DataSamplePoints. The
677    return value is a \Data object of rank 0
678    and is in the same
679    \FunctionSpace like the object. For all \DataSamplePoints
680    the value is calculated as the square root of the sum of the square over all over all components. \index{function!length}
681    \end{methoddesc}
682    \begin{methoddesc}[Data]{transpose}{axis}
683    returns the transpose of the object around \var{axis}. \var{axis} is a non-negative integer
684    which is less the rank $r$ of the object. Transpose swaps the indexes $0$ to \var{axis}
685    with the indexes \var{axis}+1 to $r$. If the \var{d} is \RankFour one has
686    \begin{python}
687    d[i,j,k,l]=d.transpose(0)[i,j,k,l]
688    d[i,j,k,l]=d.transpose(1)[j,k,l,i]
689    d[i,j,k,l]=d.transpose(2)[k,l,i,j]
690    d[i,j,k,l]=d.transpose(3)[l,i,j,k]
691    \end{python}
692    \index{function!transpose}
693  \end{methoddesc}  \end{methoddesc}
694    
695  \begin{methoddesc}[Data]{inf}{}  \begin{methoddesc}[Data]{trace}{}
696  returns the minimum value (infimum) of the object. The minimum is  returns sum of the components with identical indexes.
697  taken over all components and all data points.  \index{infimum}  The
698    return value is a \Data object of rank 0
699    and is in the same
700    \FunctionSpace like the object.
701    \index{function!trace}
702  \end{methoddesc}  \end{methoddesc}
703    \begin{methoddesc}[Data]{saveDX}{fileName}
704  \begin{methoddesc}[Data]{sup}{}  saves the object to an openDX format file of name \var{fileName}, see
705  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}  
706  \end{methoddesc}  \end{methoddesc}
707    
 \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}  
708    
709  \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}  
710    
711  \begin{methoddesc}[Data]{whereNonnegative}{}  \begin{funcdesc}{Scalar}{value=0.,what=escript::FunctionSpace(),expand=\False}
712  returns \Data object which has the same shape and is defined on  returns a \Data object of rank 0 in the \FunctionSpace \var{what}.
713  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
714  where the object is non-negative and $0$ elsewhere.  the \Data object is represented in expanded from.
715  \end{methoddesc}  \end{funcdesc}
716    
717  \begin{methoddesc}[Data]{whereNegative}{}  \begin{funcdesc}{Vector}{value=0.,what=escript::FunctionSpace(),expand=\False}
718  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}
719  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}.
720  where the object is negative and $0$ elsewhere.  Values are initialed with the double \var{value}. If \var{expanded} is \True
721    the \Data object is represented in expanded from.
722    \end{funcdesc}
723    
724    \begin{funcdesc}{Tensor}{value=0.,what=escript::FunctionSpace(),expand=\False}
725    returns a \Data object of \Shape \var{(d,d)} in the \FunctionSpace \var{what}
726    where \var{d} is the spatial dimension of the \Domain of \var{what}.
727    Values are initialed with the double \var{value}. If \var{expanded} is \True
728    the \Data object is represented in expanded from.
729    \end{funcdesc}
730    
731    \begin{funcdesc}{Tensor3}{value=0.,what=escript::FunctionSpace(),expand=\False}
732    returns a \Data object of \Shape \var{(d,d,d)} in the \FunctionSpace \var{what}
733    where \var{d} is the spatial dimension of the \Domain of \var{what}.
734    Values are initialed with the double \var{value}. If \var{expanded} is \True
735    the \Data object is re\var{arg}presented in expanded from.
736    \end{funcdesc}
737    
738    \begin{funcdesc}{Tensor4}{value=0.,what=escript::FunctionSpace(),expand=\False}
739    returns a \Data object of \Shape \var{(d,d,d,d)} in the \FunctionSpace \var{what}
740    where \var{d} is the spatial dimension of the \Domain of \var{what}.
741    Values are initialed with the double \var{value}. If \var{expanded} is \True
742    the \Data object is represented in expanded from.
743    \end{funcdesc}
744    
745    \begin{funcdesc}{abs}{arg}
746    returns the absolute value of \var{arg} where \var{arg}
747    can be double, a \Data object or an \numarray object.
748    \end{funcdesc}
749    
750    \begin{funcdesc}{sin}{arg}
751    returns the sine of \var{arg} where \var{arg}
752    can be double, a \Data object or an \numarray object.
753    \end{funcdesc}
754    
755    \begin{funcdesc}{cos}{arg}
756    returns the cosine of \var{arg} where \var{arg}
757    can be double, a \Data object or an \numarray object.
758    \end{funcdesc}
759    
760    \begin{funcdesc}{exp}{arg}
761    returns the value of the exponential function for \var{arg} where \var{arg}
762    can be double, a \Data object or an \numarray object.
763    \end{funcdesc}
764    
765    \begin{funcdesc}{sqrt}{arg}
766    returns the square root of \var{arg} where \var{arg}
767    can be double, a \Data object or an \numarray object.
768    \end{funcdesc}
769    
770    \begin{funcdesc}{maxval}{arg}
771    returns the maximum value over all component of \var{arg} where \var{arg}
772    can be double, a \Data object or an \numarray object.
773    \end{funcdesc}
774    
775    \begin{funcdesc}{minval}{arg}
776    returns the minumum value over all component of \var{arg} where \var{arg}
777    can be double, a \Data object or an \numarray object.
778    \end{funcdesc}
779    
780    \begin{funcdesc}{length}{arg}
781    returns the length of \var{arg} which is the
782    square root of the sum of the squares of all component of \var{arg}. \var{arg}
783    can be double, a \Data object or an \numarray object.
784    \end{funcdesc}
785    
786    \begin{funcdesc}{sign}{arg}
787    return the sign of \var{arg} where \var{arg}
788    can be double, a \Data object or an \numarray object.
789    \end{funcdesc}
790    
791    \begin{funcdesc}{transpose}{arg,\optional{axis}}
792    returns the transpose of \var{arg} around \var{axis}. \var{axis} is a non-negative integer
793    which is less the rank $r$ of the object. Transpose swaps the indexes $0$ to \var{axis}
794    with the indexes \var{axis}+1 to $r$. If \var{axis} is not present, \var{axis}=$r/2$ is assumed.
795    \var{arg}
796    may be a \Data object or an \numarray object.
797    \end{funcdesc}
798    
799    \begin{funcdesc}{transpose}{arg,\optional{axis}}
800    returns the trace the object of \var{arg}. The trace is the sum over those components
801    with identical indexed.
802    \var{arg}
803    may be a \Data object or a \numarray object.
804    \end{funcdesc}
805    
806    \begin{funcdesc}{sum}{arg}
807    returns the sum over all components and all
808    \DataSamplePoints of \var{arg}, where \var{arg}
809    is a \Data object.
810    \end{funcdesc}
811    
812    \begin{funcdesc}{sup}{arg}
813    returns the maximum over all components and all
814    \DataSamplePoints of \var{arg}, where \var{arg}
815    is a \Data object.
816    \end{funcdesc}
817    
818    \begin{funcdesc}{inf}{arg}
819    returns the mimumum over all components and all
820    \DataSamplePoints of \var{arg}, where \var{arg}
821    is a \Data object.
822    \end{funcdesc}
823    
824    
825    \begin{funcdesc}{L2}{arg}
826    returns the $L^2$ norm of \var{arg}. This is the square root
827    of the sum of the squared value over all components and all
828    \DataSamplePoints of \var{arg}, where \var{arg}
829    is a \Data object.
830    \end{funcdesc}
831    
832    \begin{funcdesc}{Lsup}{arg}
833    returns the $L^{sup}$ norm of \var{arg}. This is the maximum of the absolute values
834     over all components and all
835    \DataSamplePoints of \var{arg}, where \var{arg}
836    is a \Data object.
837    \end{funcdesc}
838    
839    \begin{funcdesc}{dot}{arg1,arg2}
840    returns the dot product of of \var{arg1} and \var{arg2}. This is sum
841    of the product of corresponding entries in \var{arg1} and \var{arg2} over all
842    components and and all
843    \DataSamplePoints. \var{arg1} and \var{arg2} are \Data objects of the
844    same \Shape and in the same \FunctionSpace.
845    \end{funcdesc}
846    
847    \begin{funcdesc}{grad}{arg,\optional{where}}
848    returns the gradient of \var{arg} as a function in the \FunctionSpace \var{where}.
849    If \var{where} is not present a reasonable \FunctionSpace is chosen.
850    \var{arg}
851    is a \Data object.
852    \end{funcdesc}
853    
854    \begin{funcdesc}{integrate}{arg}
855    returns the integral of \var{arg} as a \numarray object.
856    If \var{where} is not present a reasonable \FunctionSpace is chosen.
857    \var{arg}
858    is a \Data object.
859    \end{funcdesc}
860    
861    \begin{funcdesc}{interpolate}{arg,where}
862    interpolate \Data object \var{arg} into the \FunctionSpace \var{where}
863    \end{funcdesc}
864    
865    
866    \section{\Operator Class}
867    
868    The \Operator class provides an abstract access to operators build
869    within the \LinearPDE class. \Operator objects are created
870    when a PDE is handed over to a PDE solver library and handled
871    by the \LinearPDE class defining the PDE. The user can gain access
872    to the \Operator of a \LinearPDE object through the \var{getOperator}
873    method.
874    
875    \begin{classdesc}{Operator}{}
876    creates an empty \Operator object.
877    \end{classdesc}
878    
879    \begin{methoddesc}[Operator]{isEmpty}{fileName}
880    returns \True is the object is empty. Otherwise \True is returned.
881  \end{methoddesc}  \end{methoddesc}
882    
883  \begin{methoddesc}[Data]{whereZero}{tolerance=Constants.EPSILON}  \begin{methoddesc}[Operator]{setValue}{value}
884  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.  
885  \end{methoddesc}  \end{methoddesc}
886    
887  \begin{methoddesc}[Data]{whereNonzero}{tolerance=Constants.EPSILON}  \begin{methoddesc}[Operator]{solves}{rhs}
888  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.  
889  \end{methoddesc}  \end{methoddesc}
890    
891  \begin{methoddesc}[Data]{saveDX}{fileName}  \begin{methoddesc}[Operator]{of}{u}
892  saves the object to an openDX format file of name \var{fileName}, see  applies the operator to the \Data object \var{u}
 \ulink{www.opendx.org}{\url{www.opendx.org}}.  \index{openDX}  
893  \end{methoddesc}  \end{methoddesc}
894    
895  \begin{methoddesc}[Data]{saveMM}{fileName}  \begin{methoddesc}[Operator]{saveMM}{fileName}
896  saves the object to a matrix market format file of name  saves the object to a matrix market format file of name
897  \var{fileName}, see  \var{fileName}, see
898  \ulink{maths.nist.gov/MatrixMarket}{\url{http://maths.nist.gov/MatrixMarket}}.  \ulink{maths.nist.gov/MatrixMarket}{\url{http://maths.nist.gov/MatrixMarket}}.
899  \index{Matrix Market}  \index{Matrix Market}
900  \end{methoddesc}  \end{methoddesc}
901    
 %=====================================================  
 \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.82  
changed lines
  Added in v.97

  ViewVC Help
Powered by ViewVC 1.1.26