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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 97 - (hide annotations)
Tue Dec 14 05:39:33 2004 UTC (14 years, 4 months ago) by jgs
Original Path: trunk/esys2/doc/user/escript.tex
File MIME type: application/x-tex
File size: 41166 byte(s)
*** empty log message ***

1 jgs 82 % $Id$
2    
3     \chapter{The module \escript}
4    
5 jgs 97 \declaremodule{extension}{escript}
6     \modulesynopsis{Data manipulation}
7 jgs 82
8 jgs 97 \begin{figure}
9     \includegraphics[width=\textwidth]{EscriptDiagram1.eps}
10     \caption{\label{ESCRIPT DEP}Dependency of Function Spaces. An arrow indicates that a function in the
11     function space at the starting point can be interpreted as a function in the function space of the arrow target.}
12     \end{figure}
13 jgs 82
14 jgs 97 \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 function is defined. The region as well as the method which is used
17     to interpolate value on the \DataSamplePoints is defined by
18     \Domain class objects. For instance when using
19     the finite element method (FEM) \index{finite element method}
20     \Domain object holds the information about the FEM mesh, eg.
21     a table of nodes and a table of elements. Although \Domain contains
22     the discretization method to be used \escript does not use this information directly.
23     \Domain objects are created from a module which want to make use
24     \escript, e.g. \finley.
25 jgs 82
26 jgs 97 The solution of a PDE is a function of its location in the domain of interest $\Omega$.
27     When solving a partial differential equation \index{partial differential equation} (PDE) using FEM
28     the solution is (piecewise) differentiable but, in general, its gradient
29     is discontinuous. To reflect these different degrees of smoothness different
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
32     strain, which is the symmetric part of the gradient of the displacement field, is stored on the
33     element centers. To be able to classify functions with respect to their smoothness, \escript has the
34     concept of the "function space". A function space is described by a \FunctionSpace object.
35     The following statement generates the object \var{solution_space} which is
36     a \FunctionSpace object and provides access to the function space of
37     PDE solutions on the \Domain \var{mydomain}:
38     \begin{python}
39     solution_space=Solution(mydomain)
40     \end{python}
41     The following generators for function spaces on a \Domain \var{mydomin} are available:
42     \begin{itemize}
43     \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 jgs 82
83 jgs 97 \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 jgs 82
91 jgs 97 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 jgs 82
110 jgs 97 \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 jgs 82
127 jgs 97 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 jgs 82
143 jgs 97 \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 jgs 82
152 jgs 97 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 jgs 82
205 jgs 97 \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 jgs 82
212 jgs 97 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 jgs 82
233 jgs 97 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 jgs 82
250    
251 jgs 97
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 jgs 82 \end{classdesc}
261    
262 jgs 97 \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 jgs 82 \end{classdesc}
303    
304 jgs 97 \begin{methoddesc}[FunctionSpace]{getDim}{}
305     returns the spatial dimension of the \Domain of the \FunctionSpace.
306     \end{methoddesc}
307 jgs 82
308 jgs 97 \begin{methoddesc}[FunctionSpace]{getX}{}
309     returns the location of the \DataSamplePoints.
310     \end{methoddesc}
311 jgs 82
312 jgs 97 \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 jgs 82
319 jgs 97 \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 jgs 82
324 jgs 97 \begin{methoddesc}[FunctionSpace]{getDomain}{}
325     returns the \Domain of the \FunctionSpace.
326     \end{methoddesc}
327 jgs 82
328 jgs 97 \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 jgs 82
333 jgs 97 \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 jgs 82
338 jgs 97 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 jgs 82 \end{funcdesc}
343    
344 jgs 97 \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 jgs 82 \end{funcdesc}
349    
350 jgs 97 \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 jgs 82 \end{funcdesc}
354    
355 jgs 97 \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 jgs 82 \end{funcdesc}
360    
361 jgs 97 \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 jgs 82 \end{funcdesc}
367    
368 jgs 97 \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 jgs 82 \end{funcdesc}
373    
374 jgs 97 \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 jgs 82 \end{funcdesc}
380    
381 jgs 97 \section{\Data Class}
382 jgs 82
383    
384 jgs 97 The following table shows binary and unitary operations that can be applied to
385     \Data objects:
386     \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{+}}
390     \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{-}}
392     \lineii{\var{arg1}/\var{arg2}} {ratio \var{arg1} by \var{arg2} \index{/}}
393     \lineii{\var{arg1}**\var{arg2}} {raises \var{arg1} to the power of \var{arg2} \index{**}}
394     \end{tableii}
395     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
397     converted into a \Data object. If \var{arg1} or \var{arg2} are
398     defined on different \FunctionSpace it is tried to embed \var{arg1}
399     into the \FunctionSpace of \var{arg2} or to embed \var{arg2} into
400     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
402     latter case it is assumed that the particular argument is of the same
403     \Shape like the other argument but constant over all components.
404 jgs 82
405 jgs 97 The returned \Data object has the same \Shape and is defined on
406     the \DataSamplePoints like \var{arg1} or \var{arg2}.
407 jgs 82
408 jgs 97 The following table shows the update operations that can be applied to
409     \Data objects:
410     \begin{tableii}{l|l}{textrm}{expression}{Description}
411     \lineii{\var{arg1}+=\var{arg2}} {adds \var{arg1} to \var{arg2} \index{+}}
412     \lineii{\var{arg1}*=\var{arg2}} {multiplies \var{arg1} with \var{arg2} \index{*}}
413     \lineii{\var{arg1}-=\var{arg2}} {subtracts \var{arg2} from\var{arg2} \index{-}}
414     \lineii{\var{arg1}/=\var{arg2}} {divides \var{arg1} by \var{arg2} \index{/}}
415     \end{tableii}
416     \var{arg1} must be a \Data object. \var{arg1} must be a
417     \Data object or an object that can be converted into a
418     \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
420     assumed that the values of \var{arg1} are constant for all
421     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
423     \DataSamplePoints where \var{arg1} is hold.
424 jgs 82
425 jgs 97 The \Data class supports getting slices as well as assigning new values to components in an existing
426     \Data object \index{slicing}.
427     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     equal sign) are valid:
430     \begin{tableiii}{l|ll}{textrm}{rank of \var{arg}}{slicing expression}{\Shape of returned and assigned object}
431     \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    
456    
457    
458     \begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expanded=\False}
459     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 jgs 82 \end{classdesc}
463    
464 jgs 97 \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}
478    
479     \begin{classdesc}{Data}{}
480     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}
483    
484     \begin{methoddesc}[Data]{getFunctionSpace}{}
485     returns the \FunctionSpace of the object.
486 jgs 82 \end{methoddesc}
487    
488 jgs 97 \begin{methoddesc}[Data]{getFunctionSpace}{}
489     returns the \Domain of the object.
490     \end{methoddesc}
491    
492 jgs 82 \begin{methoddesc}[Data]{getShape}{}
493 jgs 97 returns the \Shape of the object as a \class{tuple} of
494     integers.
495 jgs 82 \end{methoddesc}
496    
497     \begin{methoddesc}[Data]{getRank}{}
498     returns the rank of the data on each data point. \index{rank}
499     \end{methoddesc}
500    
501 jgs 97 \begin{methoddesc}[Data]{isEmpty}{}
502     returns \True id the \Data object is the \EmptyData object.
503     Otherwise \False is returned.
504 jgs 82 \end{methoddesc}
505    
506 jgs 97 \begin{methoddesc}[Data]{setTaggedValue}{tag,value}
507     assigns the \var{value} to all \DataSamplePoints which have the tag
508     \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 jgs 82 \end{methoddesc}
518    
519 jgs 97 \begin{methoddesc}[Data]{wherePositive}{}
520     returns \Data object which has the same \Shape and is defined on
521     the same \FunctionSpace like the object. The returned values are $1$
522     where the object is positive and $0$ elsewhere.
523 jgs 82 \end{methoddesc}
524    
525 jgs 97 \begin{methoddesc}[Data]{wherePositive}{}
526     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 jgs 82 \end{methoddesc}
530    
531 jgs 97 \begin{methoddesc}[Data]{whereNonnegative}{}
532     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 jgs 82 \end{methoddesc}
536    
537 jgs 97 \begin{methoddesc}[Data]{whereNegative}{}
538     returns \Data object which has the same \Shape and is defined on
539     the same \FunctionSpace like the object. The returned values are $1$
540     where the object is negative and $0$ elsewhere.
541 jgs 82 \end{methoddesc}
542    
543 jgs 97 \begin{methoddesc}[Data]{whereZero}{tolerance=1.e-8}
544     returns \Data object which has the same \Shape and is defined on
545     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}
549 jgs 82
550 jgs 97 \begin{methoddesc}[Data]{whereNonzero}{tolerance=1.e-8}
551     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 jgs 82 \end{methoddesc}
556    
557 jgs 97 \begin{methoddesc}[Data]{sign}{}
558     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 jgs 82 \end{methoddesc}
562    
563 jgs 97 \begin{methoddesc}[Data]{copyWithMask}{arg,mask}
564     copies the \Data object \var{arg} into the object
565     where the \Data object \var{mask} is positive. \var{arg}
566     and \var{mask} must have the same \Shape
567     and must belong to same \FunctionSpace as
568     the object.
569 jgs 82 \end{methoddesc}
570    
571 jgs 97 \begin{methoddesc}[Data]{Lsup}{}
572     returns the $L^{sup}$-norm of the object. This is maximum absolute values over all components and all \DataSamplePoints. \index{$L^{sup}$-norm}.
573     \end{methoddesc}
574     \begin{methoddesc}[Data]{inf}{}
575     returns the minimum value (infimum) of the object. The minimum is
576     taken over all components and all \DataSamplePoints . \index{infimum}
577     \end{methoddesc}
578    
579     \begin{methoddesc}[Data]{sup}{}
580     returns the maximum value (supremum) of the object. The maximum is
581     taken over all components and all \DataSamplePoints . \index{supremum}
582     \end{methoddesc}
583    
584     \begin{methoddesc}[Data]{grad}{\optional{on}}
585     returns the gradient of the function represented by the object.
586     \Data object is in \FunctionSpace \var{on} and has rank r+1 where r is the rank of the object.
587     If \var{on} is not present, a suitbale \FunctionSpace is used.
588 jgs 82 \index{gradient}
589     \end{methoddesc}
590    
591     \begin{methoddesc}[Data]{integrate}{}
592 jgs 97 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
594 jgs 82 component of the returned object is the integral of the corresponding
595 jgs 97 component of the object. \index{integral}
596 jgs 82 \end{methoddesc}
597    
598 jgs 97 \begin{methoddesc}[Data]{interpolate}{on}
599     interpolates
600     the function represented by the object
601     into the \FunctionSpace\var{on}.
602 jgs 82 \index{interpolation}
603     \end{methoddesc}
604    
605 jgs 97 \begin{methoddesc}[Data]{abs}{}
606     applies the absolute value function to the object. The
607     return \Data object has the same \Shape and is in the same
608     \FunctionSpace like the object. For all \DataSamplePoints and all
609     components the value is calculated by applying the exponential
610     function. \index{function!absolute value}
611 jgs 82 \end{methoddesc}
612    
613 jgs 97 \begin{methoddesc}[Data]{exp}{}
614     applies the exponential function to the object. The
615     return \Data object has the same \Shape and is in the same
616     \FunctionSpace like the object. For all \DataSamplePoints and all
617     components the value is calculated by applying the exponential
618     function. \index{function!exponential}
619 jgs 82 \end{methoddesc}
620    
621     \begin{methoddesc}[Data]{sqrt}{}
622 jgs 97 applies the square root function to the object. The
623     return \Data object has the same \Shape and is in the same
624     \FunctionSpace like the object. For all \DataSamplePoints and all
625     components the value is calculated by applying the square root function.
626     An exception is
627     raised if the value is negative. \index{function!square root}
628 jgs 82 \end{methoddesc}
629    
630     \begin{methoddesc}[Data]{sin}{}
631 jgs 97 applies the sine function to the object. The
632     return \Data object has the same \Shape and is in the same
633     \FunctionSpace like the object. For all \DataSamplePoints and all
634     components the value is calculated by applying the sine function. \index{function!sine}
635 jgs 82 \end{methoddesc}
636    
637     \begin{methoddesc}[Data]{cos}{}
638 jgs 97 applies the cosine function to the object. The
639     return \Data object has the same \Shape and is in the same
640     \FunctionSpace like the object. For all \DataSamplePoints and all
641     components the value is calculated by applying the cosine function. \index{function!cosine}
642 jgs 82 \end{methoddesc}
643    
644 jgs 97 \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 jgs 82 \end{methoddesc}
650    
651 jgs 97 \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 jgs 82 \end{methoddesc}
658    
659 jgs 97 \begin{methoddesc}[Data]{maxval}{}
660     returns the maximum value over all components. The
661     return value is a \Data object of rank 0
662     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 jgs 82 \end{methoddesc}
666    
667 jgs 97 \begin{methoddesc}[Data]{minval}{}
668     returns the minimum value over all components. The
669     return value is a \Data object of rank 0
670     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 jgs 82 \end{methoddesc}
674    
675 jgs 97 \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 jgs 82 \end{methoddesc}
682 jgs 97 \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 jgs 82 \end{methoddesc}
694    
695 jgs 97 \begin{methoddesc}[Data]{trace}{}
696     returns sum of the components with identical indexes.
697     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 jgs 82 \end{methoddesc}
703 jgs 97 \begin{methoddesc}[Data]{saveDX}{fileName}
704     saves the object to an openDX format file of name \var{fileName}, see
705     \ulink{www.opendx.org}{\url{www.opendx.org}}. \index{openDX}
706     \end{methoddesc}
707 jgs 82
708 jgs 97
709     For convenience the following factories are provided to created \Data object:
710    
711     \begin{funcdesc}{Scalar}{value=0.,what=escript::FunctionSpace(),expand=\False}
712     returns a \Data object of rank 0 in the \FunctionSpace \var{what}.
713     Values are initialed with the double \var{value}. If \var{expanded} is \True
714     the \Data object is represented in expanded from.
715     \end{funcdesc}
716    
717     \begin{funcdesc}{Vector}{value=0.,what=escript::FunctionSpace(),expand=\False}
718     returns a \Data object of \Shape \var{(d,)} in the \FunctionSpace \var{what}
719     where \var{d} is the spatial dimension of the \Domain of \var{what}.
720     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 jgs 82 \end{methoddesc}
882    
883 jgs 97 \begin{methoddesc}[Operator]{setValue}{value}
884     resets all entires in the obeject representation to \var{value}
885 jgs 82 \end{methoddesc}
886    
887 jgs 97 \begin{methoddesc}[Operator]{solves}{rhs}
888     solves the operator equation with right hand side \var{rhs}
889 jgs 82 \end{methoddesc}
890    
891 jgs 97 \begin{methoddesc}[Operator]{of}{u}
892     applies the operator to the \Data object \var{u}
893 jgs 82 \end{methoddesc}
894    
895 jgs 97 \begin{methoddesc}[Operator]{saveMM}{fileName}
896 jgs 82 saves the object to a matrix market format file of name
897     \var{fileName}, see
898     \ulink{maths.nist.gov/MatrixMarket}{\url{http://maths.nist.gov/MatrixMarket}}.
899     \index{Matrix Market}
900     \end{methoddesc}
901    

Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision

  ViewVC Help
Powered by ViewVC 1.1.26