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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26