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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1316 - (show annotations)
Tue Sep 25 03:18:30 2007 UTC (11 years, 6 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 %
2 % $Id$
3 %
4 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
5 %
6 % 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
17 \chapter{The module \escript}
18 \label{ESCRIPT CHAP}
19
20
21 \begin{figure}
22 \includegraphics[width=\textwidth]{figures/EscriptDiagram1.eps}
23 \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
27 \escript is an extension of Python to handle functions represented by their values on
28 \DataSamplePoints for the geometrical region on which
29 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
39 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 The following generators for function spaces on a \Domain \var{mydomain} are available:
55 \begin{itemize}
56 \item \var{Solution(mydomain)}: solutions of a PDE.
57 \item \var{ReducedSolution(mydomain)}: solutions of a PDE with a reduced smoothness requirement.
58 \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 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 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 fulfills periodic boundary conditions while a continuous function does not have to be periodic.
80
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 must be interpolated to the element centers or the cell edges,
97 respectively.
98
99 \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
107 The values of the function have a rank which gives the
108 number of indices, and a \Shape defining the range of each index.
109 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 The \Shape of a \Data object is a tuple (list) \var{s} of integers. The length
112 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
126 \Data objects can also be created from any \numarray
127 array or any object, such as a list of floating point numbers,
128 that can be converted into a \numarray.NumArray \Ref{NUMARRAY}.
129 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 which generates a $2 \times 3$ matrix as a \numarray.NumArray
137 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 and converts it into a \numarray.NumArray before creating the actual
141 \Data object.
142
143 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 Here the initial value is $0$ but any object that can be converted into a \numarray.NumArray and whose \Shape
157 is consistent with \Shape of the \Data object to be created can be used as the initial value.
158
159 \Data objects can be manipulated by applying unitary operations (eg. cos, sin, log)
160 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 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
168 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 from esys.escript import *
180 def getStress(u,lam,mu):
181 d=u.getDomain().getDim()
182 g=grad(u)
183 stress=lam*trace(g)*kronecker(d)+mu*(g+transpose(g))
184 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 \var{kronecker} returns the Kronecker symbol with indexes
190 $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
220 \begin{figure}
221 \includegraphics[width=\textwidth]{figures/EscriptDiagram2.eps}
222 \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
227 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 is subdivided into triangular shaped cells. Each
231 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 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 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 insertTaggedValue(lam,white=30.,gray=5000.)
242 s=getStress(u,lam,2.)
243 \end{python}
244 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 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
249 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 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 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
267 The \var{dump} method provides a possibility to save \Data objects to a file, for instance to restart a simulation
268 or to save data for visualization. The file format uses \netCDF which commonly is using the file extension
269 {\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 appropriate methods of \var{mydomain} to be loaded before \var{x}. Alternatively, the \Domain can be reconstructed.
277 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 \section{\escript Classes}
289 \declaremodule{extension}{esys.escript}
290 \modulesynopsis{Data manipulation}
291
292 \subsection{\Domain class}
293 \begin{classdesc}{Domain}{}
294 A \Domain object is used to describe a geometrical region together with
295 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 \end{classdesc}
300 The following methods are available:
301 \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 \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 \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 \begin{methoddesc}[Domain]{__str__}{g}
346 returns string representation of the \Domain.
347 \end{methoddesc}
348
349 \subsection{\FunctionSpace class}
350 \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 \end{classdesc}
356 The following methods are available:
357 \begin{methoddesc}[FunctionSpace]{getDim}{}
358 returns the spatial dimension of the \Domain of the \FunctionSpace.
359 \end{methoddesc}
360
361
362
363 \begin{methoddesc}[FunctionSpace]{getX}{}
364 returns the location of the \DataSamplePoints.
365 \end{methoddesc}
366
367 \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
374 \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
379 \begin{methoddesc}[FunctionSpace]{getDomain}{}
380 returns the \Domain of the \FunctionSpace.
381 \end{methoddesc}
382
383 \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 Use the \var{setTagMap} to assign a tag name to \var{new_tag}.
388 \end{methoddesc}
389
390 \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
395 \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
400 \begin{methoddesc}[Domain]{__str__}{g}
401 returns string representation of the \Domain.
402 \end{methoddesc}
403
404 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 \end{funcdesc}
409
410 \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 \end{funcdesc}
415
416 \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 \end{funcdesc}
420
421 \begin{funcdesc}{FunctionOnContactZero}{domain}
422 returns the \FunctionOnContactZero the \Domain domain. \Data objects in this type of \Function
423 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 \end{funcdesc}
426
427 \begin{funcdesc}{FunctionOnContactOne}{domain}
428 returns the \FunctionOnContactOne on the \Domain domain.
429 \Data objects in this type of \Function
430 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 \end{funcdesc}
433
434 \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 \end{funcdesc}
439
440 \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 \end{funcdesc}
446
447 \subsection{\Data Class}
448 \label{SEC ESCRIPT DATA}
449
450 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 \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 \end{tableii}
461 At least one of the arguments \var{arg0} or \var{arg1} must be a
462 \Data object. One of the arguments may be an object that can be
463 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 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 latter case it is assumed that the particular argument is of the same
469 \Shape as the other argument but constant over all components.
470
471 The returned \Data object has the same \Shape and is defined on
472 the \DataSamplePoints as \var{arg0} or \var{arg1}.
473
474 The following table shows the update operations that can be applied to
475 \Data objects:
476 \begin{tableii}{l|l}{textrm}{expression}{Description}
477 \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 \end{tableii}
483 \var{arg0} must be a \Data object. \var{arg1} must be a
484 \Data object or an object that can be converted into a
485 \Data object. \var{arg1} must have the same \Shape like
486 \var{arg1} or has rank 0. In the latter case it is
487 assumed that the values of \var{arg1} are constant for all
488 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
492 The \Data class supports getting slices as well as assigning new values to components in an existing
493 \Data object. \index{slicing}
494 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 The following examples show slicing usage:
516 \begin{python}
517 t=Data(1.,(4,4,6,6),Function(mydomain))
518 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 \subsection{Generation of \Data class objects}
525 \begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expand=\False}
526 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 \end{classdesc}
530
531 \begin{classdesc}{Data}{value,what=FunctionSpace(),expand=\False}
532 creates a \Data object in the \FunctionSpace \var{what}.
533 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 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 \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 \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 \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 \begin{methoddesc}[Data]{getFunctionSpace}{}
587 returns the \FunctionSpace of the object.
588 \end{methoddesc}
589
590 \begin{methoddesc}[Data]{getDomain}{}
591 returns the \Domain of the object.
592 \end{methoddesc}
593
594 \begin{methoddesc}[Data]{getShape}{}
595 returns the \Shape of the object as a \class{tuple} of
596 integers.
597 \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 \begin{methoddesc}[Data]{isEmpty}{}
604 returns \True id the \Data object is the \EmptyData object.
605 Otherwise \False is returned.
606 \end{methoddesc}
607
608 \begin{methoddesc}[Data]{setTaggedValue}{tag_name,value}
609 assigns the \var{value} to all \DataSamplePoints which have the tag
610 assigned to \var{tag_name}. \var{value} must be an object of class
611 \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 same rank like the object.
615 If a value has already be defined for tag \var{tag_name} within the object
616 it is overwritten by the new \var{value}. If the object is expanded,
617 the value assigned to \DataSamplePoints with tag \var{tag_name} is replaced by
618 \var{value}. If no tag is assigned tag name \var{tag_name}, no value is set.
619 \end{methoddesc}
620
621 \begin{methoddesc}[Data]{dump}{filename}
622 dumps the \Data object to the file \var{filename}. The file stores the
623 function space but not the \Domain. It is in the responsibility of the user to
624 save the \Domain.
625 \end{methoddesc}
626
627 \begin{methoddesc}[Data]{__str__}{}
628 returns a string representation of the object.
629 \end{methoddesc}
630
631 \subsection{Functions of \Data class objects}
632 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 \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 \end{funcdesc}
643 \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 \end{funcdesc}
652 \begin{funcdesc}{kronecker}{d}
653 returns a \RankTwo \Data object in \FunctionSpace \var{d} such that
654 \begin{equation}
655 \code{kronecker(d)}\left[ i,j\right] = \left\{
656 \begin{array}{cc}
657 1 & \mbox{ if } i=j \\
658 0 & \mbox{ otherwise }
659 \end{array}
660 \right.
661 \end{equation}
662 If \var{d} is an integer a $(d,d)$ \numarray array is returned.
663 \end{funcdesc}
664 \begin{funcdesc}{identityTensor}{d}
665 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 \end{funcdesc}
676 \begin{funcdesc}{identityTensor4}{d}
677 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 \end{funcdesc}
688 \begin{funcdesc}{unitVector}{i,d}
689 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 \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 applies the natural logarithm to \var{a}.
773 \end{funcdesc}
774
775 \begin{funcdesc}{log10}{a}
776 applies the base-$10$ logarithm to \var{a}.
777 \end{funcdesc}
778
779 \begin{funcdesc}{sign}{a}
780 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 \end{funcdesc}
783
784 \begin{funcdesc}{wherePositive}{a}
785 returns a function which is $1$ where \var{a} is positive and $0$ otherwise.
786 \end{funcdesc}
787
788 \begin{funcdesc}{whereNegative}{a}
789 returns a function which is $1$ where \var{a} is negative and $0$ otherwise.
790 \end{funcdesc}
791
792 \begin{funcdesc}{whereNonNegative}{a}
793 returns a function which is $1$ where \var{a} is non--negative and $0$ otherwise.
794 \end{funcdesc}
795
796 \begin{funcdesc}{whereNonPositive}{a}
797 returns a function which is $1$ where \var{a} is non--positive and $0$ otherwise.
798 \end{funcdesc}
799
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 \end{funcdesc}
803
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 \end{funcdesc}
807
808 \begin{funcdesc}{minval}{a}
809 returns at each \DataSamplePoints the minimum value over all components.
810 \end{funcdesc}
811
812 \begin{funcdesc}{maxval}{a}
813 returns at each \DataSamplePoints the maximum value over all components.
814 \end{funcdesc}
815
816 \begin{funcdesc}{length}{a}
817 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 \end{funcdesc}
822 \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 \end{funcdesc}
833
834 \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 \end{funcdesc}
847
848 \begin{funcdesc}{swap_axes}{a\optional{, axis0=0 \optional{, axis1=1 }}}
849 returns \var{a} but with swapped components \var{axis0} and \var{axis1}. The argument \var{a} must be
850 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 \begin{funcdesc}{symmetric}{a}
858 returns the symmetric part of \var{a}. This is \code{(a+transpose(a))/2}.
859 \end{funcdesc}
860 \begin{funcdesc}{nonsymmetric}{a}
861 returns the non--symmetric part of \var{a}. This is \code{(a-transpose(a))/2}.
862 \end{funcdesc}
863 \begin{funcdesc}{inverse}{a}
864 return the inverse of \var{a}. This is
865 \begin{equation}
866 \code{matrix_mult(inverse(a),a)=kronecker(d)}
867 \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 \end{funcdesc}
871 \begin{funcdesc}{eigenvalues}{a}
872 return the eigenvalues of \var{a}. This is
873 \begin{equation}
874 \code{matrix_mult(a,V)=e[i]*V}
875 \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 \end{funcdesc}
882 \begin{funcdesc}{eigenvalues_and_eigenvectors}{a}
883 return the eigenvalues and eigenvectors of \var{a}. This is
884 \begin{equation}
885 \code{matrix_mult(a,V[:,i])=e[i]*V[:,i]}
886 \end{equation}
887 where \code{e,V=eigenvalues_and_eigenvectors(a)}. The eigenvectors \var{V} are orthogonal and normalized, ie.
888 \begin{equation}
889 \code{matrix_mult(transpose(V),V)=kronecker(d)}
890 \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 \end{funcdesc}
896 \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 \end{funcdesc}
904 \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 \end{funcdesc}
912
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 \end{funcdesc}
919 \begin{funcdesc}{inner}{a0,a1}
920 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 \end{funcdesc}
930
931 \begin{funcdesc}{matrix_mult}{a0,a1}
932 returns the matrix product of \var{a0} and \var{a1}. If \var{a1} is \RankOne this is
933 \begin{equation}
934 \code{matrix_mult(a)}\left[i\right]=\sum\hackscore{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[k\right]
935 \end{equation}
936 and if \var{a1} is \RankTwo this is
937 \begin{equation}
938 \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 \end{equation}
940 \end{funcdesc}
941
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 \begin{funcdesc}{outer}{a0,a1}
966 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 \end{funcdesc}
975
976 \begin{funcdesc}{tensor_mult}{a0,a1}
977 returns the tensor product of \var{a0} and \var{a1}. If \var{a1} is \RankTwo this is
978 \begin{equation}
979 \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 \end{equation}
981 and if \var{a1} is \RankFour this is
982 \begin{equation}
983 \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 \end{equation}
985 \end{funcdesc}
986
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 \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 \end{funcdesc}
1021 \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 \end{funcdesc}
1034 \begin{funcdesc}{interpolate}{a,where}
1035 interpolates argument \var{a} into the \FunctionSpace \var{where}.
1036 \end{funcdesc}
1037 \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 \end{funcdesc}
1043 \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 \begin{array}{rcl}
1048 \code{jump(a)}& = &\code{interpolate(a,FunctionOnContactOne(domain))} \\
1049 & & \hfill - \code{interpolate(a,FunctionOnContactZero(domain))}
1050 \end{array}
1051 \end{equation}
1052 \end{funcdesc}
1053 \begin{funcdesc}{L2}{a}
1054 returns the $L^2$-norm of \var{a} in its function space. This is
1055 \begin{equation}
1056 \code{L2(a)=integrate(length(a)}^2\code{)} \; .
1057 \end{equation}
1058 \end{funcdesc}
1059
1060 \subsection{\Operator Class}
1061 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 \end{methoddesc}
1075
1076 \begin{methoddesc}[Operator]{setValue}{value}
1077 resets all entries in the object representation to \var{value}
1078 \end{methoddesc}
1079
1080 \begin{methoddesc}[Operator]{solves}{rhs}
1081 solves the operator equation with right hand side \var{rhs}
1082 \end{methoddesc}
1083
1084 \begin{methoddesc}[Operator]{of}{u}
1085 applies the operator to the \Data object \var{u}
1086 \end{methoddesc}
1087
1088 \begin{methoddesc}[Operator]{saveMM}{fileName}
1089 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