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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 809 - (hide annotations)
Sun Aug 13 22:10:03 2006 UTC (12 years, 8 months ago) by gross
File MIME type: application/x-tex
File size: 46549 byte(s)
update of user guide'

1 jgs 82 % $Id$
2 gross 625 %
3     % Copyright © 2006 by ACcESS MNRF
4     % http://www.access.edu.au
5     % Primary Business: Queensland, Australia.
6     % Licensed under the Open Software License version 3.0
7     % http://www.opensource.org/licenses/osl-3.0.php
8     %
9 jgs 82
10 gross 625
11 jgs 82 \chapter{The module \escript}
12 gross 660 \label{ESCRIPT CHAP}
13 jgs 82
14 jgs 102 \declaremodule{extension}{escript}
15     \modulesynopsis{Data manipulation}
16 jgs 82
17 jgs 102 \begin{figure}
18 gross 599 \includegraphics[width=\textwidth]{figures/EscriptDiagram1.eps}
19 jgs 102 \caption{\label{ESCRIPT DEP}Dependency of Function Spaces. An arrow indicates that a function in the
20     function space at the starting point can be interpreted as a function in the function space of the arrow target.}
21     \end{figure}
22 jgs 82
23 jgs 102 \escript is an extension of Python to handle functions represented by their values on
24 jgs 107 \DataSamplePoints for the geometrical region on which
25 jgs 102 the function is defined. The region as well as the method which is used
26     to interpolate value on the \DataSamplePoints is defined by
27     \Domain class objects. For instance when using
28     the finite element method (FEM) \index{finite element method}
29     \Domain object holds the information about the FEM mesh, eg.
30     a table of nodes and a table of elements. Although \Domain contains
31     the discretization method to be used \escript does not use this information directly.
32     \Domain objects are created from a module which want to make use
33     \escript, e.g. \finley.
34 jgs 82
35 jgs 102 The solution of a PDE is a function of its location in the domain of interest $\Omega$.
36     When solving a partial differential equation \index{partial differential equation} (PDE) using FEM
37     the solution is (piecewise) differentiable but, in general, its gradient
38     is discontinuous. To reflect these different degrees of smoothness different
39     representations of the functions are used. For instance; in FEM
40     the displacement field is represented by its values at the nodes of the mesh, while the
41     strain, which is the symmetric part of the gradient of the displacement field, is stored on the
42     element centers. To be able to classify functions with respect to their smoothness, \escript has the
43     concept of the "function space". A function space is described by a \FunctionSpace object.
44     The following statement generates the object \var{solution_space} which is
45     a \FunctionSpace object and provides access to the function space of
46     PDE solutions on the \Domain \var{mydomain}:
47     \begin{python}
48     solution_space=Solution(mydomain)
49     \end{python}
50 jgs 107 The following generators for function spaces on a \Domain \var{mydomain} are available:
51 jgs 102 \begin{itemize}
52 gross 599 \item \var{Solution(mydomain)}: solutions of a PDE.
53     \item \var{ReducedSolution(mydomain)}: solutions of a PDE with a reduced smoothness requirement.
54 jgs 102 \item \var{ContinuousFunction(mydomain)}: continuous functions, eg. a temperature distribution.
55     \item \var{Function(mydomain)}: general functions which are not necessarily continuous, eg. a stress field.
56     \item \var{FunctionOnBoundary(mydomain)}: functions on the boundary of the domain, eg. a surface pressure.
57     \item \var{FunctionOnContact0(mydomain)}: functions on side $0$ of the discontinuity.
58     \item \var{FunctionOnContact1(mydomain)}: functions on side $1$ of the discontinuity.
59     \end{itemize}
60 gross 599 The reduced smoothness for PDE solution is often used to fulfill the Ladyzhenskaya–-Babuska–-Brezzi condition \cite{LBB} when
61     solving saddle point problems \index{saddle point problems}, eg. the Stokes equation.
62 jgs 102 A discontinuity \index{discontinuity} is a region within the domain across which functions may be discontinuous.
63     The location of discontinuity is defined in the \Domain object.
64     \fig{ESCRIPT DEP} shows the dependency between the types of function spaces.
65     The solution of a PDE is a continuous function. Any continuous function can be seen as a general function
66     on the domain and can be restricted to the boundary as well as to any side of the
67     discontinuity (the result will be different depending on
68     which side is chosen). Functions on any side of the
69     discontinuity can be seen as a function on the corresponding other side.
70     A function on the boundary or on one side of
71     the discontinuity cannot be seen as a general function on the domain as there are no values
72     defined for the interior. For most PDE solver libraries
73     the space of the solution and continuous functions is identical, however in some cases, eg.
74     when periodic boundary conditions are used in \finley, a solution
75     fulfils periodic boundary conditions while a continuous function does not have to be periodic.
76    
77     The concept of function spaces describes the properties of
78     functions and allows abstraction from the actual representation
79     of the function in the context of a particular application. For instance,
80     in the FEM context a
81     function in the \Function function space
82     is typically represented by its values at the element center,
83     but in a finite difference scheme the edge midpoint of cells is preferred.
84     Using the concept of function spaces
85     allows the user to run the same script on different
86     PDE solver libraries by just changing the creator of the \Domain object.
87     Changing the function space of a particular function
88     will typically lead to a change of its representation.
89     So, when seen as a general function,
90     a continuous function which is typically represented by its values
91     on the node of the FEM mesh or finite difference grid
92 jgs 107 must be interpolated to the element centers or the cell edges,
93 jgs 102 respectively.
94 jgs 82
95 jgs 102 \Data class objects store functions of the location in a domain.
96     The function is represented through its values on \DataSamplePoints where
97     the \DataSamplePoints are chosen according to the function space
98     of the function.
99     \Data class objects are used to define the coefficients
100     of the PDEs to be solved by a PDE solver library
101     and to store the returned solutions.
102 jgs 82
103 jgs 102 The values of the function have a rank which gives the
104 jgs 107 number of indices, and a \Shape defining the range of each index.
105 jgs 102 The rank in \escript is limited to the range $0$ through $4$ and
106     it is assumed that the rank and \Shape is the same for all \DataSamplePoints.
107     The \Shape of a \Data object is a tuple \var{s} of integers. The length
108     of \var{s} is the rank of the \Data object and \var{s[i]} is the maximum
109     value for the \var{i}-th index.
110     For instance, a stress field has rank $2$ and
111     \Shape $(d,d)$ where $d$ is the spatial dimension.
112     The following statement creates the \Data object
113     \var{mydat} representing a
114     continuous function with values
115     of \Shape $(2,3)$ and rank $2$:
116     \begin{python}
117     mydat=Data(value=1,what=ContinuousFunction(myDomain),shape=(2,3))
118     \end{python}
119     The initial value is the constant $1$ for all \DataSamplePoints and
120     all components.
121 jgs 82
122 jgs 102 \Data objects can also be created from any \numarray
123     array or any object, such as a list of floating point numbers,
124 gross 593 that can be converted into a \numarray.NumArray \Ref{NUMARRAY}.
125 jgs 102 The following two statements
126     create objects which are equivalent to \var{mydat}:
127     \begin{python}
128     mydat1=Data(value=numarray.ones((2,3)),what=ContinuousFunction(myDomain))
129     mydat2=Data(value=[[1,1],[1,1],[1,1]],what=ContinuousFunction(myDomain))
130     \end{python}
131     In the first case the initial value is \var{numarray.ones((2,3))}
132 gross 593 which generates a $2 \times 3$ matrix as a \numarray.NumArray
133 jgs 102 filled with ones. The \Shape of the created \Data object
134     it taken from the \Shape of the array. In the second
135     case, the creator converts the initial value, which is a list of lists,
136 gross 593 and converts it into a \numarray.NumArray before creating the actual
137 jgs 102 \Data object.
138 jgs 82
139 jgs 102 For convenience \escript provides creators for the most common types
140     of \Data objects in the following forms (\var{d} defines the
141     spatial dimension):
142     \begin{itemize}
143     \item \var{Scalar(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(,))},
144     e.g a temperature field.
145     \item \var{Vector(0,Function(mydomain))}is the same as \var{Data(0,Function(myDomain),(d))}, e.g
146     a velocity field.
147     \item \var{Tensor(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d,d))},
148     eg. a stress field.
149     \item \var{Tensor4(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d,d,d,d))}
150     eg. a Hook tensor field.
151     \end{itemize}
152 gross 593 Here the initial value is $0$ but any object that can be converted into a \numarray.NumArray and whose \Shape
153 jgs 102 is consistent with \Shape of the \Data object to be created can be used as the initial value.
154 jgs 82
155 jgs 102 \Data objects can be manipulated by applying unitary operations (eg. cos, sin, log)
156 jgs 107 and can be combined by applying binary operations (eg. +, - ,* , /).
157     It is to be emphasized that \escript itself does not handle any spatial dependencies as
158 jgs 102 it does not know how values are interpreted by the processing PDE solver library.
159     However \escript invokes interpolation if this is needed during data manipulations.
160     Typically, this occurs in binary operation when both arguments belong to different
161     function spaces or when data are handed over to a PDE solver library
162     which requires functions to be represented in a particular way.
163 jgs 82
164 jgs 102 The following example shows the usage of {\tt Data} objects: Assume we have a
165     displacement field $u$ and we want to calculate the corresponding stress field
166     $\sigma$ using the linear--elastic isotropic material model
167     \begin{eqnarray}\label{eq: linear elastic stress}
168     \sigma\hackscore {ij}=\lambda u\hackscore {k,k} \delta\hackscore {ij} + \mu ( u\hackscore {i,j} + u\hackscore {j,i})
169     \end{eqnarray}
170     where $\delta\hackscore {ij}$ is the Kronecker symbol and
171     $\lambda$ and $\mu$ are the Lame coefficients. The following function
172     takes the displacement {\tt u} and the Lame coefficients
173     \var{lam} and \var{mu} as arguments and returns the corresponding stress:
174     \begin{python}
175 gross 599 from esys.escript import *
176 jgs 102 def getStress(u,lam,mu):
177     d=u.getDomain().getDim()
178     g=grad(u)
179 gross 599 stress=lam*trace(g)*kronecker(d)+mu*(g+transpose(g))
180 jgs 102 return stress
181     \end{python}
182     The variable
183     \var{d} gives the spatial dimension of the
184     domain on which the displacements are defined.
185 gross 599 \var{kronecker} returns the Kronecker symbol with indexes
186 jgs 102 $i$ and $j$ running from $0$ to \var{d}-1. The call \var{grad(u)} requires
187     the displacement field \var{u} to be in the \var{Solution} or \ContinuousFunction
188     function space. The result \var{g} as well as the returned stress will be in the \Function function space.
189     If \var{u} is available, eg. by solving a PDE, \var{getStress} might be called
190     in the following way:
191     \begin{python}
192     s=getStress(u,1.,2.)
193     \end{python}
194     However \var{getStress} can also be called with \Data objects as values for
195     \var{lam} and \var{mu} which,
196     for instance in the case of a temperature dependency, are calculated by an expression.
197     The following call is equivalent to the previous example:
198     \begin{python}
199     lam=Scalar(1.,ContinuousFunction(mydomain))
200     mu=Scalar(2.,Function(mydomain))
201     s=getStress(u,lam,mu)
202     \end{python}
203     The function \var{lam} belongs to the \ContinuousFunction function space
204     but with \var{g} the function \var{trace(g)} is in the \Function function space.
205     Therefore the evaluation of the product \var{lam*trace(g)} in the stress calculation
206     produces a problem, as both functions are represented differently, eg. in FEM
207     \var{lam} by its values on the node, and in \var{trace(g)} by its values at the element centers.
208     In the case of inconsistent function spaces of arguments in a binary operation, \escript
209     interprets the arguments in the appropriate function space according to the inclusion
210     defined in Table~\ref{ESCRIPT DEP}. In this example that means
211     \escript sees \var{lam} as a function of the \Function function space.
212     In the context of FEM this means the nodal values of
213     \var{lam} are interpolated to the element centers. Behind the scenes
214     \escript calls the appropriate function from the PDE solver library.
215 jgs 82
216 jgs 102 \begin{figure}
217 gross 599 \includegraphics[width=\textwidth]{figures/EscriptDiagram2.eps}
218 jgs 102 \caption{\label{Figure: tag}Element Tagging. A rectangular mesh over a region with two rock types {\it white} and {\it gray}.
219     The number in each cell refers to the major rock type present in the cell ($1$ for {\it white} and $2$ for {\it gray}).
220     }
221     \end{figure}
222 jgs 82
223 jgs 102 Material parameters such as the Lame coefficients are typically dependent on rock types present in the
224     area of interest. A common technique to handle these kinds of material parameters is "tagging". \fig{Figure: tag}
225     shows an example. In this case two rock types {\it white} and {\it gray} can be found in the domain. The domain
226 gross 599 is subdivided into triangular shaped cells. Each
227 jgs 102 cell has a tag indicating the rock type predominately found in this cell. Here $1$ is used to indicate
228     rock type {\it white} and $2$ for rock type {\it gray}. The tags are assigned at the time when the cells are generated
229     and stored in the \Domain class object. The following statements show how for the
230     example of \fig{Figure: tag} and the stress calculation discussed before tagged values are used for
231     \var{lam}:
232     \begin{python}
233     lam=Scalar(value=2.,what=Function(mydomain))
234     lam.setTaggedValue(1,30.)
235     lam.setTaggedValue(2,5000.)
236     s=getStress(u,lam,2.)
237     \end{python}
238     In this example \var{lam} is set to $30$ for those cells with tag $1$ and to $5000.$ for those cells
239     with tag $2$. The initial value $2$ of \var{lam} is used as a default value for the case when a tag
240     is encountered which has not been linked with a value. Note that the \var{getStress} method
241     is called without modification. \escript resolves the tags when \var{lam*trace(g)} is calculated.
242 jgs 82
243 jgs 102 The \Data class provides a transparent interface to various data representations and the
244     translations between them. As shown in the example of stress calculation, this allows the user to
245     develop and test algorithms for a simple case (for instance with the Lame coefficients as constants)
246     and then without further modifications of the program code to apply the algorithm in a
247     more complex application (for instance a definition of the Lame coefficients using tags).
248 gross 599 As described here, there are three ways in which \Data objects are represented internally, constant,
249     tagged, and expanded (other representations will become available in later versions of \escript):
250 jgs 102 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.
251     Any operation on this constant data will only be performed on the single value.
252     In the expanded case, each sample point has an individual value, eg. the solution of a PDE,
253     and the values are stored as a complete array. The tagged case has already been discussed above.
254    
255     Values are accessed through a sample reference number. Operations on expanded \Data
256     objects have to be performed for each sample point individually. If tagged values are used values are
257     held in a dictionary. Operations on tagged data require processing the set of tagged values only, rather than
258     processing the value for each individual sample point.
259     \escript allows use of constant, tagged and expanded data in a single expression.
260 jgs 82
261 jgs 102 \section{\Domain class}
262     \begin{classdesc}{Domain}{}
263 jgs 107 A \Domain object is used to describe a geometrical region together with
264 jgs 102 a way of representing functions over this region.
265     The \Domain class provides an abstract access to the domain of \FunctionSpace and \Data objects.
266     \Domain itself has no initialization but implementations of \Domain are
267     instantiated by numerical libraries making use of \Data objects.
268 jgs 82 \end{classdesc}
269 gross 593 The following methds are available:
270 jgs 102 \begin{methoddesc}[Domain]{getDim}{}
271     returns the spatial dimension of the \Domain.
272     \end{methoddesc}
273    
274     \begin{methoddesc}[Domain]{getX}{}
275     returns the locations in the \Domain. The \FunctionSpace of the returned
276     \Data object is chosen by the \Domain implementation. Typically it will be
277     in the \Function.
278     \end{methoddesc}
279    
280     \begin{methoddesc}[Domain]{setX}{newX}
281     assigns a new location to the \Domain. \var{newX} has to have \Shape $(d,)$
282     where $d$ is the spatial dimension of the domain. Typically \var{newX} must be
283     in the \ContinuousFunction but the space actually to be used depends on the \Domain implementation.
284     \end{methoddesc}
285    
286     \begin{methoddesc}[Domain]{getNormal}{}
287     returns the surface normals on the boundary of the \Domain as \Data object.
288     \end{methoddesc}
289    
290     \begin{methoddesc}[Domain]{getSize}{}
291     returns the local sample size, e.g. the element diameter, as \Data object.
292     \end{methoddesc}
293    
294     \begin{methoddesc}[Domain]{__eq__}{arg}
295     returns \True of the \Domain \var{arg} describes the same domain. Otherwise
296     \False is returned.
297     \end{methoddesc}
298    
299     \begin{methoddesc}[Domain]{__ne__}{arg}
300     returns \True of the \Domain \var{arg} does not describe the same domain.
301     Otherwise \False is returned.
302     \end{methoddesc}
303    
304 gross 593 \begin{methoddesc}[Domain]{__str__}{g}
305     returns string represention of the \Domain.
306     \end{methoddesc}
307    
308 gross 625 \section{\FunctionSpace class}
309 jgs 102 \begin{classdesc}{FunctionSpace}{}
310     \FunctionSpace objects are used to define properties of \Data objects, such as continuity. \FunctionSpace objects
311     are instantiated by generator functions. \Data objects in particular \FunctionSpace are
312     represented by their values at \DataSamplePoints which are defined by the type and the \Domain of the
313     \FunctionSpace.
314 jgs 82 \end{classdesc}
315 gross 593 The following methds are available:
316 jgs 102 \begin{methoddesc}[FunctionSpace]{getDim}{}
317     returns the spatial dimension of the \Domain of the \FunctionSpace.
318     \end{methoddesc}
319 jgs 82
320 jgs 102 \begin{methoddesc}[FunctionSpace]{getX}{}
321     returns the location of the \DataSamplePoints.
322     \end{methoddesc}
323 jgs 82
324 jgs 102 \begin{methoddesc}[FunctionSpace]{getNormal}{}
325     If the domain of functions in the \FunctionSpace
326     is a hypermanifold (e.g. the boundary of a domain)
327     the method returns the outer normal at each of the
328     \DataSamplePoints. Otherwise an exception is raised.
329     \end{methoddesc}
330 jgs 82
331 jgs 102 \begin{methoddesc}[FunctionSpace]{getSize}{}
332     returns a \Data objects measuring the spacing of the \DataSamplePoints.
333     The size may be zero.
334     \end{methoddesc}
335 jgs 82
336 jgs 102 \begin{methoddesc}[FunctionSpace]{getDomain}{}
337     returns the \Domain of the \FunctionSpace.
338     \end{methoddesc}
339 jgs 82
340 jgs 102 \begin{methoddesc}[FunctionSpace]{__eq__}{arg}
341     returns \True of the \Domain \var{arg} describes the same domain. Otherwise
342     \False is returned.
343     \end{methoddesc}
344 jgs 82
345 jgs 102 \begin{methoddesc}[FunctionSpace]{__ne__}{arg}
346     returns \True of the \Domain \var{arg} describes the note same domain.
347     Otherwise \False is returned.
348     \end{methoddesc}
349 jgs 82
350 gross 593 \begin{methoddesc}[Domain]{__str__}{g}
351     returns string represention of the \Domain.
352     \end{methoddesc}
353    
354 jgs 102 The following function provide generators for \FunctionSpace objects:
355     \begin{funcdesc}{Function}{domain}
356     returns the \Function on the \Domain \var{domain}. \Data objects in this type of \Function
357     are defined over the whole geometrical region defined by \var{domain}.
358 jgs 82 \end{funcdesc}
359    
360 jgs 102 \begin{funcdesc}{ContinuousFunction}{domain}
361     returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function
362     are defined over the whole geometrical region defined by \var{domain} and assumed to represent
363     a continuous function.
364 jgs 82 \end{funcdesc}
365    
366 jgs 102 \begin{funcdesc}{FunctionOnBoundary}{domain}
367     returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function
368     are defined on the boundary of the geometrical region defined by \var{domain}.
369 jgs 82 \end{funcdesc}
370    
371 jgs 102 \begin{funcdesc}{FunctionOnContactZero}{domain}
372     returns the \FunctionOnContactZero the \Domain domain. \Data objects in this type of \Function
373     are defined on side 0 of a discontinutiy within the geometrical region defined by \var{domain}.
374     The discontinutiy is defined when \var{domain} is instantiated.
375 jgs 82 \end{funcdesc}
376    
377 jgs 102 \begin{funcdesc}{FunctionOnContactOne}{domain}
378     returns the \FunctionOnContactOne on the \Domain domain.
379     \Data objects in this type of \Function
380     are defined on side 1 of a discontinutiy within the geometrical region defined by \var{domain}.
381     The discontinutiy is defined when \var{domain} is instantiated.
382 jgs 82 \end{funcdesc}
383    
384 jgs 102 \begin{funcdesc}{Solution}{domain}
385     returns the \SolutionFS on the \Domain domain. \Data objects in this type of \Function
386     are defined on geometrical region defined by \var{domain} and are solutions of
387     partial differential equations \index{partial differential equation}.
388 jgs 82 \end{funcdesc}
389    
390 jgs 102 \begin{funcdesc}{ReducedSolution}{domain}
391     returns the \ReducedSolutionFS on the \Domain domain. \Data objects in this type of \Function
392     are defined on geometrical region defined by \var{domain} and are solutions of
393     partial differential equations \index{partial differential equation} with a reduced smoothness
394     for the solution approximation.
395 jgs 82 \end{funcdesc}
396    
397 jgs 102 \section{\Data Class}
398 jgs 107 \label{SEC ESCRIPT DATA}
399 jgs 82
400 jgs 102 The following table shows binary and unitary operations that can be applied to
401     \Data objects:
402     \begin{tableii}{l|l}{textrm}{expression}{Description}
403 gross 625 \lineii{+\var{arg0}} {just \var{arg} \index{+}}
404     \lineii{-\var{arg0}} {swapping the sign\index{-}}
405     \lineii{\var{arg0}+\var{arg1}} {adds \var{arg0} and \var{arg1} \index{+}}
406     \lineii{\var{arg0}*\var{arg1}} {multiplies \var{arg0} and \var{arg1} \index{*}}
407     \lineii{\var{arg0}-\var{arg1}} {difference \var{arg1} from\var{arg1} \index{-}}
408     \lineii{\var{arg0}/\var{arg1}} {ratio \var{arg0} by \var{arg1} \index{/}}
409     \lineii{\var{arg0}**\var{arg1}} {raises \var{arg0} to the power of \var{arg1} \index{**}}
410 jgs 102 \end{tableii}
411 gross 625 At least one of the arguments \var{arg0} or \var{arg1} must be a
412 jgs 102 \Data object. One of the arguments may be an object that can be
413 gross 625 converted into a \Data object. If \var{arg0} or \var{arg1} are
414     defined on different \FunctionSpace an attempt is made to embed \var{arg0}
415     into the \FunctionSpace of \var{arg1} or to embed \var{arg1} into
416     the \FunctionSpace of \var{arg0}. Boths arguments must have the same
417     \Shape or one of the arguments my be of rank 0. In the
418 jgs 102 latter case it is assumed that the particular argument is of the same
419 jgs 107 \Shape as the other argument but constant over all components.
420 jgs 82
421 jgs 102 The returned \Data object has the same \Shape and is defined on
422 gross 625 the \DataSamplePoints as \var{arg0} or \var{arg1}.
423 jgs 82
424 jgs 102 The following table shows the update operations that can be applied to
425     \Data objects:
426     \begin{tableii}{l|l}{textrm}{expression}{Description}
427 gross 625 \lineii{\var{arg0}+=\var{arg2}} {adds \var{arg0} to \var{arg2} \index{+}}
428     \lineii{\var{arg0}*=\var{arg2}} {multiplies \var{arg0} with \var{arg2} \index{*}}
429     \lineii{\var{arg0}-=\var{arg2}} {subtracts \var{arg2} from\var{arg2} \index{-}}
430     \lineii{\var{arg0}/=\var{arg2}} {divides \var{arg0} by \var{arg2} \index{/}}
431     \lineii{\var{arg0}**=\var{arg2}} {raises \var{arg0} by \var{arg2} \index{**}}
432 jgs 102 \end{tableii}
433 gross 625 \var{arg0} must be a \Data object. \var{arg1} must be a
434 jgs 102 \Data object or an object that can be converted into a
435     \Data object. \var{arg1} must have the same \Shape like
436 gross 625 \var{arg1} or has rank 0. In the latter case it is
437 jgs 102 assumed that the values of \var{arg1} are constant for all
438 gross 625 components. \var{arg1} must be defined in the same \FunctionSpace as
439     \var{arg0} or it must be possible to interpolate \var{arg1} onto the
440     \FunctionSpace of \var{arg1}.
441 jgs 82
442 jgs 102 The \Data class supports getting slices as well as assigning new values to components in an existing
443 jgs 107 \Data object. \index{slicing}
444 jgs 102 The following expression for getting (expression on the right hand side of the
445     equal sign) and setting slices (expression on the left hand side of the
446     equal sign) are valid:
447     \begin{tableiii}{l|ll}{textrm}{rank of \var{arg}}{slicing expression}{\Shape of returned and assigned object}
448     \lineiii{0}{ no slicing } {-}
449     \lineiii{1}{\var{arg[l0:u0]}} {(\var{u0}-\var{l0},)}
450     \lineiii{2}{\var{arg[l0:u0,l1:u1]}} {(\var{u0}-\var{l0},\var{u1}-\var{l1})}
451     \lineiii{3}{\var{arg[l0:u0,l1:u1,l2:u2]} } {(\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2})}
452     \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})}
453     \end{tableiii}
454     where
455     $0 \le \var{l0} \le \var{u0} \le \var{s[0]}$,
456     $0 \le \var{l1} \le \var{u1} \le \var{s[1]}$,
457     $0 \le \var{l2} \le \var{u2} \le \var{s[2]}$,
458     $0 \le \var{l3} \le \var{u3} \le \var{s[3]}$ and \var{s} the \Shape if \var{arg}.
459     Any of the lower indexes \var{l0}, \var{l1}, \var{l2} and \var{l3} may not be present in which case
460     $0$ is assumed.
461     Any of the upper indexes \var{u0}, \var{u1}, \var{u2} and \var{u3} may not be present in which case
462     \var{s} is assumed. The lower and upper index may be identical, in which case the column and the lower or upper
463     index may be dropped. In the returned or in the object assigned to a slice the corresponding component is dropped,
464     i.e. the rank is reduced by one in comparison to \var{arg}.
465 jgs 107 The following examples show slicing usage:
466 jgs 102 \begin{python}
467 gross 593 t=Data(1.,(4,4,6,6),Function(mydomain))
468 jgs 102 t[1,1,1,0]=9.
469     s=t[:2,:,2:6,5] # s has rank 3
470     s[:,:,1]=1.
471     t[:2,:2,5,5]=s[2:4,1,:2]
472     \end{python}
473    
474 gross 593 \subsection{Generation of \Data class objects}
475     \begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expand=\False}
476 jgs 102 creates a \Data object with \Shape \var{shape} in the \FunctionSpace \var{what}.
477     The values at all \DataSamplePoints are set to the double value \var{value}. If \var{expanded} is \True
478     the \Data object is represented in expanded from.
479 jgs 82 \end{classdesc}
480    
481 gross 593 \begin{classdesc}{Data}{value,what=FunctionSpace(),expand=\False}
482 jgs 102 creates a \Data object in the \FunctionSpace \var{what}.
483 gross 593 The value for each \DataSamplePoints is set to \numarray, \Data object \var{value} or a dictionary of
484     \numarray or floating point numbers. In the latter case the keys muts be integers and are used
485     as tags.
486 jgs 102 The \Shape of the returned object is equal to the \Shape of \var{value}. If \var{expanded} is \True
487     the \Data object is represented in expanded from.
488     \end{classdesc}
489    
490     \begin{classdesc}{Data}{}
491     creates an \EmptyData object. The \EmptyData object is used to indicate that an argument is not present
492     where a \Data object is required.
493     \end{classdesc}
494    
495 gross 593 \begin{funcdesc}{Scalar}{value=0.,what=escript::FunctionSpace(),expand=\False}
496     returns a \Data object of rank 0 in the \FunctionSpace \var{what}.
497     Values are initialed with the double \var{value}. If \var{expanded} is \True
498     the \Data object is represented in expanded from.
499     \end{funcdesc}
500    
501     \begin{funcdesc}{Vector}{value=0.,what=escript::FunctionSpace(),expand=\False}
502     returns a \Data object of \Shape \var{(d,)} in the \FunctionSpace \var{what}
503     where \var{d} is the spatial dimension of the \Domain of \var{what}.
504     Values are initialed with the double \var{value}. If \var{expanded} is \True
505     the \Data object is represented in expanded from.
506     \end{funcdesc}
507    
508     \begin{funcdesc}{Tensor}{value=0.,what=escript::FunctionSpace(),expand=\False}
509     returns a \Data object of \Shape \var{(d,d)} in the \FunctionSpace \var{what}
510     where \var{d} is the spatial dimension of the \Domain of \var{what}.
511     Values are initialed with the double \var{value}. If \var{expanded} is \True
512     the \Data object is represented in expanded from.
513     \end{funcdesc}
514    
515     \begin{funcdesc}{Tensor3}{value=0.,what=escript::FunctionSpace(),expand=\False}
516     returns a \Data object of \Shape \var{(d,d,d)} in the \FunctionSpace \var{what}
517     where \var{d} is the spatial dimension of the \Domain of \var{what}.
518     Values are initialed with the double \var{value}. If \var{expanded} is \True
519     the \Data object is re\var{arg}presented in expanded from.
520     \end{funcdesc}
521    
522     \begin{funcdesc}{Tensor4}{value=0.,what=escript::FunctionSpace(),expand=\False}
523     returns a \Data object of \Shape \var{(d,d,d,d)} in the \FunctionSpace \var{what}
524     where \var{d} is the spatial dimension of the \Domain of \var{what}.
525     Values are initialed with the double \var{value}. If \var{expanded} is \True
526     the \Data object is represented in expanded from.
527     \end{funcdesc}
528    
529     \subsection{\Data class methods}
530     This is a list of frequently used methods of the
531     \Data class. A complete list can be fond on \ReferenceGuide.
532 jgs 102 \begin{methoddesc}[Data]{getFunctionSpace}{}
533     returns the \FunctionSpace of the object.
534 jgs 82 \end{methoddesc}
535    
536 gross 593 \begin{methoddesc}[Data]{getDomain}{}
537 jgs 102 returns the \Domain of the object.
538     \end{methoddesc}
539    
540 jgs 82 \begin{methoddesc}[Data]{getShape}{}
541 jgs 102 returns the \Shape of the object as a \class{tuple} of
542     integers.
543 jgs 82 \end{methoddesc}
544    
545     \begin{methoddesc}[Data]{getRank}{}
546     returns the rank of the data on each data point. \index{rank}
547     \end{methoddesc}
548    
549 jgs 102 \begin{methoddesc}[Data]{isEmpty}{}
550     returns \True id the \Data object is the \EmptyData object.
551     Otherwise \False is returned.
552 jgs 82 \end{methoddesc}
553    
554 jgs 102 \begin{methoddesc}[Data]{setTaggedValue}{tag,value}
555     assigns the \var{value} to all \DataSamplePoints which have the tag
556     \var{tag}. \var{value} must be an object of class
557 gross 593 \class{numarray.NumArray} or must be convertible into a
558     \class{numarray.NumArray} object. \var{value} (or the corresponding
559     \class{numarray.NumArray} object) must be of rank $0$ or must have the
560 jgs 102 same rank like the object.
561     If a value has already be defined for tag \var{tag} within the object
562     it is overwritten by the new \var{value}. If the object is expanded,
563     the value assigned to \DataSamplePoints with tag \var{tag} is replaced by
564     \var{value}.
565 jgs 82 \end{methoddesc}
566    
567 gross 593 \begin{methoddesc}[Data]{__str__}{}
568     returns a string representation of the object.
569     \end{methoddesc}
570    
571     \section{Functions of \Data class objects}
572     This section lists the most important functions for \Data class objects \var{a}.
573     A complete list and a more detailed description of the functionality can be fond on \ReferenceGuide.
574 gross 599 \begin{funcdesc}{saveVTK}{filename,**kwdata}
575     writes \Data defined by keywords in the file with \var{filename} using the
576     vtk file format \VTK file format. The key word is used as an identifier. The statement
577     \begin{python}
578     saveVTK("out.xml",temperature=T,velocity=v)
579     \end{python}
580     will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the
581     file \file{out.xml}. Restrictions on the allowed combinations of \FunctionSpace apply.
582 gross 593 \end{funcdesc}
583 gross 599 \begin{funcdesc}{saveDX}{filename,**kwdata}
584     writes \Data defined by keywords in the file with \var{filename} using the
585     vtk file format \OpenDX file format. The key word is used as an identifier. The statement
586     \begin{python}
587     saveDX("out.dx",temperature=T,velocity=v)
588     \end{python}
589     will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the
590     file \file{out.dx}. Restrictions on the allowed combinations of \FunctionSpace apply.
591 gross 593 \end{funcdesc}
592     \begin{funcdesc}{kronecker}{d}
593 gross 599 returns a \RankTwo \Data object in \FunctionSpace \var{d} such that
594 gross 593 \begin{equation}
595 gross 599 \code{kronecker(d)}\left[ i,j\right] = \left\{
596 gross 593 \begin{array}{cc}
597     1 & \mbox{ if } i=j \\
598     0 & \mbox{ otherwise }
599     \end{array}
600     \right.
601     \end{equation}
602 gross 599 If \var{d} is an integer a $(d,d)$ \numarray array is returned.
603 gross 593 \end{funcdesc}
604     \begin{funcdesc}{identityTensor}{d}
605 gross 599 returns a \RankTwo \Data object in \FunctionSpace \var{d} such that
606     \begin{equation}
607     \code{identityTensor(d)}\left[ i,j\right] = \left\{
608     \begin{array}{cc}
609     1 & \mbox{ if } i=j \\
610     0 & \mbox{ otherwise }
611     \end{array}
612     \right.
613     \end{equation}
614     If \var{d} is an integer a $(d,d)$ \numarray array is returned.
615 gross 593 \end{funcdesc}
616     \begin{funcdesc}{identityTensor4}{d}
617 gross 599 returns a \RankFour \Data object in \FunctionSpace \var{d} such that
618     \begin{equation}
619     \code{identityTensor(d)}\left[ i,j,k,l\right] = \left\{
620     \begin{array}{cc}
621     1 & \mbox{ if } i=k \mbox{ and } j=l\\
622     0 & \mbox{ otherwise }
623     \end{array}
624     \right.
625     \end{equation}
626     If \var{d} is an integer a $(d,d,d,d)$ \numarray array is returned.
627 gross 593 \end{funcdesc}
628     \begin{funcdesc}{unitVector}{i,d}
629 gross 599 returns a \RankOne \Data object in \FunctionSpace \var{d} such that
630     \begin{equation}
631     \code{identityTensor(d)}\left[ j \right] = \left\{
632     \begin{array}{cc}
633     1 & \mbox{ if } j=i\\
634     0 & \mbox{ otherwise }
635     \end{array}
636     \right.
637     \end{equation}
638     If \var{d} is an integer a $(d,)$ \numarray array is returned.
639    
640 gross 593 \end{funcdesc}
641    
642     \begin{funcdesc}{Lsup}{a}
643     returns the $L^{sup}$ norm of \var{arg}. This is the maximum of the absolute values
644     over all components and all \DataSamplePoints of \var{a}.
645     \end{funcdesc}
646    
647     \begin{funcdesc}{sup}{a}
648     returns the maximum value over all components and all \DataSamplePoints of \var{a}.
649     \end{funcdesc}
650    
651     \begin{funcdesc}{inf}{a}
652     returns the minimum value over all components and all \DataSamplePoints of \var{a}
653     \end{funcdesc}
654    
655     \begin{funcdesc}{sin}{a}
656     applies sine function to \var{a}.
657     \end{funcdesc}
658    
659     \begin{funcdesc}{cos}{a}
660     applies cosine function to \var{a}.
661     \end{funcdesc}
662    
663     \begin{funcdesc}{tan}{a}
664     applies tangent function to \var{a}.
665     \end{funcdesc}
666    
667     \begin{funcdesc}{asin}{a}
668     applies arc (inverse) sine function to \var{a}.
669     \end{funcdesc}
670    
671     \begin{funcdesc}{acos}{a}
672     applies arc (inverse) cosine function to \var{a}.
673     \end{funcdesc}
674    
675     \begin{funcdesc}{atan}{a}
676     applies arc (inverse) tangent function to \var{a}.
677     \end{funcdesc}
678    
679     \begin{funcdesc}{sinh}{a}
680     applies hyperbolic sine function to \var{a}.
681     \end{funcdesc}
682    
683     \begin{funcdesc}{cosh}{a}
684     applies hyperbolic cosine function to \var{a}.
685     \end{funcdesc}
686    
687     \begin{funcdesc}{tanh}{a}
688     applies hyperbolic tangent function to \var{a}.
689     \end{funcdesc}
690    
691     \begin{funcdesc}{asinh}{a}
692     applies arc (inverse) hyperbolic sine function to \var{a}.
693     \end{funcdesc}
694    
695     \begin{funcdesc}{acosh}{a}
696     applies arc (inverse) hyperbolic cosine function to \var{a}.
697     \end{funcdesc}
698    
699     \begin{funcdesc}{atanh}{a}
700     applies arc (inverse) hyperbolic tangent function to \var{a}.
701     \end{funcdesc}
702    
703     \begin{funcdesc}{exp}{a}
704     applies exponential function to \var{a}.
705     \end{funcdesc}
706    
707     \begin{funcdesc}{sqrt}{a}
708     applies square root function to \var{a}.
709     \end{funcdesc}
710    
711     \begin{funcdesc}{log}{a}
712 gross 599 applies the natural logarithm to \var{a}.
713 gross 593 \end{funcdesc}
714    
715     \begin{funcdesc}{log10}{a}
716 gross 599 applies the base-$10$ logarithm to \var{a}.
717 gross 593 \end{funcdesc}
718    
719     \begin{funcdesc}{sign}{a}
720 gross 599 applies the sign function to \var{a}, that is $1$ where \var{a} is positive,
721     $-1$ where \var{a} is negative and $0$ otherwise.
722 gross 593 \end{funcdesc}
723    
724     \begin{funcdesc}{wherePositive}{a}
725 gross 599 returns a function which is $1$ where \var{a} is positive and $0$ otherwise.
726 gross 593 \end{funcdesc}
727 gross 599
728 gross 593 \begin{funcdesc}{whereNegative}{a}
729 gross 599 returns a function which is $1$ where \var{a} is negative and $0$ otherwise.
730 gross 593 \end{funcdesc}
731 gross 599
732 gross 593 \begin{funcdesc}{whereNonNegative}{a}
733 gross 599 returns a function which is $1$ where \var{a} is non--negative and $0$ otherwise.
734 gross 593 \end{funcdesc}
735 gross 599
736 gross 593 \begin{funcdesc}{whereNonPositive}{a}
737 gross 599 returns a function which is $1$ where \var{a} is non--positive and $0$ otherwise.
738 gross 593 \end{funcdesc}
739 gross 599
740     \begin{funcdesc}{whereZero}{a\optional{, tol=0.}}
741     returns a function which is $1$ where \var{a} equals zero with tolerance \var{tol} and $0$ otherwise.
742 gross 593 \end{funcdesc}
743 gross 599
744     \begin{funcdesc}{whereNonZero}{a\optional{, tol=0.}}
745     returns a function which is $1$ where \var{a} different from zero with tolerance \var{tol} and $0$ otherwise.
746 gross 593 \end{funcdesc}
747 gross 599
748 gross 593 \begin{funcdesc}{minval}{a}
749 gross 599 returns at each \DataSamplePoints the minumum value over all components.
750 gross 593 \end{funcdesc}
751 gross 599
752 gross 593 \begin{funcdesc}{maxval}{a}
753 gross 599 returns at each \DataSamplePoints the maximum value over all components.
754 gross 593 \end{funcdesc}
755 gross 599
756 gross 593 \begin{funcdesc}{length}{a}
757 gross 599 returns at Euclidean norm at each \DataSamplePoints. For a \RankFour function \var{a} this is
758     \begin{equation}
759     \code{length(a)}=\sqrt{\sum\hackscore{ijkl} \var{a} \left[i,j,k,l\right]^2}
760     \end{equation}
761 gross 593 \end{funcdesc}
762 gross 599 \begin{funcdesc}{trace}{a\optional{,axis_offset=0}}
763     returns the trace of \var{a}. This is the sum over components \var{axis_offset} and \var{axis_offset+1} with the same index. For instance in the
764     case of a \RankTwo function and this is
765     \begin{equation}
766     \code{trace(a)}=\sum\hackscore{i} \var{a} \left[i,i\right]
767     \end{equation}
768     and for a \RankFour function and \code{axis_offset=1} this is
769     \begin{equation}
770     \code{trace(a,1)}\left[i,j\right]=\sum\hackscore{k} \var{a} \left[i,k,k,j\right]
771     \end{equation}
772 gross 593 \end{funcdesc}
773 gross 804
774 gross 599 \begin{funcdesc}{transpose}{a\optional{, axis_offset=None}}
775     returns the transpose of \var{a}. This swaps the first \var{axis_offset} components of \var{a} with the rest. If \var{axis_offset} is not
776     present \code{int(r/2)} is used where \var{r} is the rank of \var{a}.
777     the sum over components \var{axis_offset} and \var{axis_offset+1} with the same index. For instance in the
778     case of a \RankTwo function and this is
779     \begin{equation}
780     \code{transpose(a)}\left[i,j\right]=\var{a} \left[j,i\right]
781     \end{equation}
782     and for a \RankFour function and \code{axis_offset=1} this is
783     \begin{equation}
784     \code{transpose(a,1)}\left[i,j,k,l\right]=\var{a} \left[j,k,l,i\right]
785     \end{equation}
786 gross 593 \end{funcdesc}
787 gross 804
788     \begin{funcdesc}{swap_axes}{a\optional{, axis0=0 \optional{, axis1=1 }}}
789     returns \var{a} but with swapped componets \var{axis0} and \var{axis1}. The argument \var{a} must be
790     at least of \RankTwo. For instance in the
791     for a \RankFour argument, \code{axis0=1} and \code{axis1=2} this is
792     \begin{equation}
793     \code{swap_axes(a,1,2)}\left[i,j,k,l\right]=\var{a} \left[i,k,j,l\right]
794     \end{equation}
795     \end{funcdesc}
796    
797 gross 593 \begin{funcdesc}{symmetric}{a}
798 gross 599 returns the symmetric part of \var{a}. This is \code{(a+transpose(a))/2}.
799 gross 593 \end{funcdesc}
800     \begin{funcdesc}{nonsymmetric}{a}
801 gross 599 returns the non--symmetric part of \var{a}. This is \code{(a-transpose(a))/2}.
802 gross 593 \end{funcdesc}
803     \begin{funcdesc}{inverse}{a}
804 gross 599 return the inverse of \var{a}. This is
805     \begin{equation}
806 gross 809 \code{matrix_mult(inverse(a),a)=kronecker(d)}
807 gross 599 \end{equation}
808     if \var{a} has shape \code{(d,d)}. The current implementation is restricted to arguments of shape
809     \code{(2,2)} and \code{(3,3)}.
810 gross 593 \end{funcdesc}
811     \begin{funcdesc}{eigenvalues}{a}
812 gross 599 return the eigenvalues of \var{a}. This is
813     \begin{equation}
814 gross 809 \code{matrix_mult(a,V)=e[i]*V}
815 gross 599 \end{equation}
816     where \code{e=eigenvalues(a)} and \var{V} is suitable non--zero vector \var{V}.
817     The eigenvalues are ordered in increasing size.
818     The argument \var{a} has to be the symmetric, ie. \code{a=symmetric(a)}.
819     The current implementation is restricted to arguments of shape
820     \code{(2,2)} and \code{(3,3)}.
821 gross 593 \end{funcdesc}
822     \begin{funcdesc}{eigenvalues_and_eigenvectors}{a}
823 gross 599 return the eigenvalues and eigenvectors of \var{a}. This is
824     \begin{equation}
825 gross 809 \code{matrix_mult(a,V[:,i])=e[i]*V[:,i]}
826 gross 599 \end{equation}
827     where \code{e,V=eigenvalues_and_eigenvectors(a)}. The eigenvectors \var{V} are orthogonal and normalized, ie.
828     \begin{equation}
829 gross 809 \code{matrix_mult(transpose(V),V)=kronecker(d)}
830 gross 599 \end{equation}
831     if \var{a} has shape \code{(d,d)}. The eigenvalues are ordered in increasing size.
832     The argument \var{a} has to be the symmetric, ie. \code{a=symmetric(a)}.
833     The current implementation is restricted to arguments of shape
834     \code{(2,2)} and \code{(3,3)}.
835 gross 593 \end{funcdesc}
836 gross 599 \begin{funcdesc}{maximum}{*a}
837     returns the maximum value over all arguments at all \DataSamplePoints and for each component.
838     For instance
839     \begin{equation}
840     \code{maximum(a0,a1)}\left[i,j\right]=max(\var{a0} \left[i,j\right],\var{a1} \left[i,j\right])
841     \end{equation}
842     at all \DataSamplePoints.
843 gross 593 \end{funcdesc}
844 gross 599 \begin{funcdesc}{minimum}{*a}
845     returns the minimum value over all arguments at all \DataSamplePoints and for each component.
846     For instance
847     \begin{equation}
848     \code{minimum(a0,a1)}\left[i,j\right]=min(\var{a0} \left[i,j\right],\var{a1} \left[i,j\right])
849     \end{equation}
850     at all \DataSamplePoints.
851 gross 593 \end{funcdesc}
852 gross 599
853     \begin{funcdesc}{clip}{a\optional{, minval=0.}\optional{, maxval=1.}}
854     cuts back \var{a} into the range between \var{minval} and \var{maxval}. A value in the returned object equals
855     \var{minval} if the corresponding value of \var{a} is less than \var{minval}, equals \var{maxval} if the
856     corresponding value of \var{a} is greater than \var{maxval}
857     or corresponding value of \var{a} otherwise.
858 gross 593 \end{funcdesc}
859     \begin{funcdesc}{inner}{a0,a1}
860 gross 599 returns the inner product of \var{a0} and \var{a1}. For instance in the
861     case of \RankTwo arguments and this is
862     \begin{equation}
863     \code{inner(a)}=\sum\hackscore{ij}\var{a0} \left[j,i\right] \cdot \var{a1} \left[j,i\right]
864     \end{equation}
865     and for a \RankFour arguments this is
866     \begin{equation}
867     \code{inner(a)}=\sum\hackscore{ijkl}\var{a0} \left[i,j,k,l\right] \cdot \var{a1} \left[j,i,k,l\right]
868     \end{equation}
869 gross 593 \end{funcdesc}
870 gross 809
871     \begin{funcdesc}{matrix_mult}{a0,a1}
872 gross 599 returns the matrix product of \var{a0} and \var{a1}. If \var{a1} is \RankOne this is
873     \begin{equation}
874 gross 809 \code{matrix_mult(a)}\left[i\right]=\sum\hackscore{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[k\right]
875 gross 599 \end{equation}
876     and if \var{a1} is \RankTwo this is
877     \begin{equation}
878 gross 809 \code{matrix_mult(a)}\left[i,j\right]=\sum\hackscore{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[k,j\right]
879 gross 599 \end{equation}
880 gross 593 \end{funcdesc}
881 gross 809
882     \begin{funcdesc}{transposed_matrix_mult}{a0,a1}
883     returns the matrix product of the transposed of \var{a0} and \var{a1}. The function is equivalent to
884     \code{matrix_mult(transpose(a0),a1)}.
885     If \var{a1} is \RankOne this is
886     \begin{equation}
887     \code{transposed_matrix_mult(a)}\left[i\right]=\sum\hackscore{k}\var{a0} \cdot \left[k,i\right]\var{a1} \left[k\right]
888     \end{equation}
889     and if \var{a1} is \RankTwo this is
890     \begin{equation}
891     \code{transposed_matrix_mult(a)}\left[i,j\right]=\sum\hackscore{k}\var{a0} \cdot \left[k,i\right]\var{a1} \left[k,j\right]
892     \end{equation}
893     \end{funcdesc}
894    
895     \begin{funcdesc}{matrix_transposed_mult}{a0,a1}
896     returns the matrix product of \var{a0} and the transposed of \var{a1}.
897     The function is equivalent to
898     \code{matrix_mult(a0,transpose(a1))}.
899     If \var{a1} is \RankTwo this is
900     \begin{equation}
901     \code{matrix_transposed_mult(a)}\left[i,j\right]=\sum\hackscore{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[j,k\right]
902     \end{equation}
903     \end{funcdesc}
904    
905 gross 593 \begin{funcdesc}{outer}{a0,a1}
906 gross 599 returns the outer product of \var{a0} and \var{a1}. For instance if \var{a0} and \var{a1} both are \RankOne then
907     \begin{equation}
908     \code{outer(a)}\left[i,j\right]=\var{a0} \left[i\right] \cdot \var{a1}\left[j\right]
909     \end{equation}
910     and if \var{a0} is \RankOne and \var{a1} is \RankThree
911     \begin{equation}
912     \code{outer(a)}\left[i,j,k\right]=\var{a0} \left[i\right] \cdot \var{a1}\left[j,k\right]
913     \end{equation}
914 gross 593 \end{funcdesc}
915 gross 809
916     \begin{funcdesc}{tensor_mult}{a0,a1}
917 gross 599 returns the tensor product of \var{a0} and \var{a1}. If \var{a1} is \RankTwo this is
918     \begin{equation}
919 gross 809 \code{tensor_mult(a)}\left[i,j\right]=\sum\hackscore{kl}\var{a0}\left[i,j,k,l\right] \cdot \var{a1} \left[k,l\right]
920 gross 599 \end{equation}
921     and if \var{a1} is \RankFour this is
922     \begin{equation}
923 gross 809 \code{tensor_mult(a)}\left[i,j,k,l\right]=\sum\hackscore{mn}\var{a0} \left[i,j,m,n\right] \cdot \var{a1} \left[m,n,k,l\right]
924 gross 599 \end{equation}
925 gross 593 \end{funcdesc}
926 gross 809
927     \begin{funcdesc}{transposed_tensor_mult}{a0,a1}
928     returns the tensor product of the transposed of \var{a0} and \var{a1}. The function is equivalent to
929     \code{tensor_mult(transpose(a0),a1)}.
930     If \var{a1} is \RankTwo this is
931     \begin{equation}
932     \code{transposed_tensor_mult(a)}\left[i,j\right]=\sum\hackscore{kl}\var{a0}\left[k,l,i,j\right] \cdot \var{a1} \left[k,l\right]
933     \end{equation}
934     and if \var{a1} is \RankFour this is
935     \begin{equation}
936     \code{transposed_tensor_mult(a)}\left[i,j,k,l\right]=\sum\hackscore{mn}\var{a0} \left[m,n,i,j\right] \cdot \var{a1} \left[m,n,k,l\right]
937     \end{equation}
938     \end{funcdesc}
939    
940     \begin{funcdesc}{tensor_transposed_mult}{a0,a1}
941     returns the tensor product of \var{a0} and the transposed of \var{a1}.
942     The function is equivalent to
943     \code{tensor_mult(a0,transpose(a1))}.
944     If \var{a1} is \RankTwo this is
945     \begin{equation}
946     \code{tensor_transposed_mult(a)}\left[i,j\right]=\sum\hackscore{kl}\var{a0}\left[i,j,k,l\right] \cdot \var{a1} \left[l,k\right]
947     \end{equation}
948     and if \var{a1} is \RankFour this is
949     \begin{equation}
950     \code{tensor_transposed_mult(a)}\left[i,j,k,l\right]=\sum\hackscore{mn}\var{a0} \left[i,j,m,n\right] \cdot \var{a1} \left[k,l,m,n\right]
951     \end{equation}
952     \end{funcdesc}
953    
954 gross 599 \begin{funcdesc}{grad}{a\optional{, where=None}}
955     returns the gradient of \var{a}. If \var{where} is present the gradient will be calculated in \FunctionSpace \var{where} otherwise a
956     default \FunctionSpace is used. In case that \var{a} has \RankTwo one has
957     \begin{equation}
958     \code{grad(a)}\left[i,j,k\right]=\frac{\partial \var{a} \left[i,j\right]}{\partial x\hackscore{k}}
959     \end{equation}
960 gross 593 \end{funcdesc}
961 gross 599 \begin{funcdesc}{integrate}{a\optional{ ,where=None}}
962     returns the integral of \var{a} where the domain of integration is defined by the \FunctionSpace of \var{a}. If \var{where} is
963     present the argument is interpolated into \FunctionSpace \var{where} before integration. For instance in the case of
964     a \RankTwo argument in \ContinuousFunction it is
965     \begin{equation}
966     \code{integrate(a)}\left[i,j\right]=\int\hackscore{\Omega}\var{a} \left[i,j\right] \; d\Omega
967     \end{equation}
968     where $\Omega$ is the spatial domain and $d\Omega$ volume integration. To integrate over the boundary of the domain one uses
969     \begin{equation}
970     \code{integrate(a,where=FunctionOnBoundary(a.getDomain))}\left[i,j\right]=\int\hackscore{\partial \Omega} a\left[i,j\right] \; ds
971     \end{equation}
972     where $\partial \Omega$ is the surface of the spatial domain and $ds$ area or line integration.
973 gross 593 \end{funcdesc}
974     \begin{funcdesc}{interpolate}{a,where}
975 gross 599 interpolates argument \var{a} into the \FunctionSpace \var{where}.
976 gross 593 \end{funcdesc}
977 gross 599 \begin{funcdesc}{div}{a\optional{ ,where=None}}
978     returns the divergence of \var{a}. This
979     \begin{equation}
980     \code{div(a)}=trace(grad(a),where)
981     \end{equation}
982 gross 593 \end{funcdesc}
983 gross 599 \begin{funcdesc}{jump}{a\optional{ ,domain=None}}
984     returns the jump of \var{a} over the discontinuity in its domain or if \Domain \var{domain} is present
985     in \var{domain}.
986     \begin{equation}
987 gross 809 \begin{array}{rcl}
988     \code{jump(a)}& = &\code{interpolate(a,FunctionOnContactOne(domain))} \\
989     & & \hfill - \code{interpolate(a,FunctionOnContactZero(domain))}
990     \end{array}
991 gross 599 \end{equation}
992 gross 593 \end{funcdesc}
993     \begin{funcdesc}{L2}{a}
994 gross 599 returns the $L^2$-norm of \var{a} in its function space. This is
995     \begin{equation}
996 gross 809 \code{L2(a)=integrate(length(a)}^2\code{)} \; .
997 gross 599 \end{equation}
998 gross 593 \end{funcdesc}
999    
1000 jgs 102 \section{\Operator Class}
1001     The \Operator class provides an abstract access to operators build
1002     within the \LinearPDE class. \Operator objects are created
1003     when a PDE is handed over to a PDE solver library and handled
1004     by the \LinearPDE class defining the PDE. The user can gain access
1005     to the \Operator of a \LinearPDE object through the \var{getOperator}
1006     method.
1007    
1008     \begin{classdesc}{Operator}{}
1009     creates an empty \Operator object.
1010     \end{classdesc}
1011    
1012     \begin{methoddesc}[Operator]{isEmpty}{fileName}
1013     returns \True is the object is empty. Otherwise \True is returned.
1014 jgs 82 \end{methoddesc}
1015    
1016 jgs 102 \begin{methoddesc}[Operator]{setValue}{value}
1017     resets all entires in the obeject representation to \var{value}
1018 jgs 82 \end{methoddesc}
1019    
1020 jgs 102 \begin{methoddesc}[Operator]{solves}{rhs}
1021     solves the operator equation with right hand side \var{rhs}
1022 jgs 82 \end{methoddesc}
1023    
1024 jgs 102 \begin{methoddesc}[Operator]{of}{u}
1025     applies the operator to the \Data object \var{u}
1026 jgs 82 \end{methoddesc}
1027    
1028 jgs 102 \begin{methoddesc}[Operator]{saveMM}{fileName}
1029 jgs 82 saves the object to a matrix market format file of name
1030     \var{fileName}, see
1031     \ulink{maths.nist.gov/MatrixMarket}{\url{http://maths.nist.gov/MatrixMarket}}.
1032     \index{Matrix Market}
1033     \end{methoddesc}
1034    

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26