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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1316 - (hide annotations)
Tue Sep 25 03:18:30 2007 UTC (11 years, 7 months ago) by ksteube
File MIME type: application/x-tex
File size: 49391 byte(s)
Quickly edited chapters 1 and 2 of the User Guide, but it needs more work.
Ran entire document through spell checker.

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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26