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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2318 - (show annotations)
Thu Mar 19 03:18:11 2009 UTC (13 years, 4 months ago) by gross
File MIME type: application/x-tex
File size: 51683 byte(s)
more on MPI in the users guide.
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 the processor is the master processor within
357 the \MPI processor group used by the \Domain. This is the processor with rank 0.
358 If \MPI support is not enabled the return value is always \True.
359 \end{methoddesc}
360
361 \begin{methoddesc}[Domain]{getMPISize}{}
362 returns the number of \MPI processors used for this \Domain. If \MPI support is not enabled
363 1 is returned.
364 \end{methoddesc}
365
366 \begin{methoddesc}[Domain]{getMPIRank}{}
367 returns the rank of the processor executing the statement
368 within the \MPI processor group used by the \Domain.
369 If \MPI support is not enabled 0 is returned.
370 \end{methoddesc}
371
372 \begin{methoddesc}[Domain]{MPIBarrier}{}
373 executes barrier synchronization within
374 the \MPI processor group used by the \Domain.
375 If \MPI support is not enabled, this command does nothing.
376 \end{methoddesc}
377
378 \subsection{\FunctionSpace class}
379 \begin{classdesc}{FunctionSpace}{}
380 \FunctionSpace objects are used to define properties of \Data objects, such as continuity. \FunctionSpace objects
381 are instantiated by generator functions. A \Data object in a particular \FunctionSpace is
382 represented by its values at \DataSamplePoints which are defined by the type and the \Domain of the
383 \FunctionSpace.
384 \end{classdesc}
385 The following methods are available:
386 \begin{methoddesc}[FunctionSpace]{getDim}{}
387 returns the spatial dimension of the \Domain of the \FunctionSpace.
388 \end{methoddesc}
389
390
391
392 \begin{methoddesc}[FunctionSpace]{getX}{}
393 returns the location of the \DataSamplePoints.
394 \end{methoddesc}
395
396 \begin{methoddesc}[FunctionSpace]{getNormal}{}
397 If the domain of functions in the \FunctionSpace
398 is a hypermanifold (e.g. the boundary of a domain)
399 the method returns the outer normal at each of the
400 \DataSamplePoints. Otherwise an exception is raised.
401 \end{methoddesc}
402
403 \begin{methoddesc}[FunctionSpace]{getSize}{}
404 returns a \Data objects measuring the spacing of the \DataSamplePoints.
405 The size may be zero.
406 \end{methoddesc}
407
408 \begin{methoddesc}[FunctionSpace]{getDomain}{}
409 returns the \Domain of the \FunctionSpace.
410 \end{methoddesc}
411
412 \begin{methoddesc}[FunctionSpace]{setTags}{new_tag, mask}
413 assigns a new tag \var{new_tag} to all data sample
414 where \var{mask} is positive for a least one data point.
415 \var{mask} must be defined on the this \FunctionSpace.
416 Use the \var{setTagMap} to assign a tag name to \var{new_tag}.
417 \end{methoddesc}
418
419 \begin{methoddesc}[FunctionSpace]{__eq__}{arg}
420 (python == operator) returns \True if the \Domain \var{arg} describes the same domain. Otherwise
421 \False is returned.
422 \end{methoddesc}
423
424 \begin{methoddesc}[FunctionSpace]{__ne__}{arg}
425 (python != operator) returns \True if the \Domain \var{arg} do not describe the same domain.
426 Otherwise \False is returned.
427 \end{methoddesc}
428
429 \begin{methoddesc}[Domain]{__str__}{g}
430 (python str() function) returns string representation of the \Domain.
431 \end{methoddesc}
432
433 The following function provide generators for \FunctionSpace objects:
434 \begin{funcdesc}{Function}{domain}
435 returns the \Function on the \Domain \var{domain}. \Data objects in this type of \Function
436 are defined over the whole geometric region defined by \var{domain}.
437 \end{funcdesc}
438
439 \begin{funcdesc}{ContinuousFunction}{domain}
440 returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function
441 are defined over the whole geometric region defined by \var{domain} and assumed to represent
442 a continuous function.
443 \end{funcdesc}
444
445 \begin{funcdesc}{FunctionOnBoundary}{domain}
446 returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function
447 are defined on the boundary of the geometric region defined by \var{domain}.
448 \end{funcdesc}
449
450 \begin{funcdesc}{FunctionOnContactZero}{domain}
451 returns the \FunctionOnContactZero the \Domain domain. \Data objects in this type of \Function
452 are defined on side 0 of a discontinuity within the geometric region defined by \var{domain}.
453 The discontinuity is defined when \var{domain} is instantiated.
454 \end{funcdesc}
455
456 \begin{funcdesc}{FunctionOnContactOne}{domain}
457 returns the \FunctionOnContactOne on the \Domain domain.
458 \Data objects in this type of \Function
459 are defined on side 1 of a discontinuity within the geometric region defined by \var{domain}.
460 The discontinuity is defined when \var{domain} is instantiated.
461 \end{funcdesc}
462
463 \begin{funcdesc}{Solution}{domain}
464 returns the \SolutionFS on the \Domain domain. \Data objects in this type of \Function
465 are defined on geometric region defined by \var{domain} and are solutions of
466 partial differential equations \index{partial differential equation}.
467 \end{funcdesc}
468
469 \begin{funcdesc}{ReducedSolution}{domain}
470 returns the \ReducedSolutionFS on the \Domain domain. \Data objects in this type of \Function
471 are defined on geometric region defined by \var{domain} and are solutions of
472 partial differential equations \index{partial differential equation} with a reduced smoothness
473 for the solution approximation.
474 \end{funcdesc}
475
476 \subsection{\Data Class}
477 \label{SEC ESCRIPT DATA}
478
479 The following table shows arithmetic operations that can be performed point-wise on
480 \Data objects.
481 \begin{tableii}{l|l}{textrm}{expression}{Description}
482 \lineii{+\var{arg0}} {identical to \var{arg} \index{+}}
483 \lineii{-\var{arg0}} {negation\index{-}}
484 \lineii{\var{arg0}+\var{arg1}} {adds \var{arg0} and \var{arg1} \index{+}}
485 \lineii{\var{arg0}*\var{arg1}} {multiplies \var{arg0} and \var{arg1} \index{*}}
486 \lineii{\var{arg0}-\var{arg1}} {difference \var{arg1} from\var{arg1} \index{-}}
487 \lineii{\var{arg0}/\var{arg1}} {divide \var{arg0} by \var{arg1} \index{/}}
488 \lineii{\var{arg0}**\var{arg1}} {raises \var{arg0} to the power of \var{arg1} \index{**}}
489 \end{tableii}
490 At least one of the arguments \var{arg0} or \var{arg1} must be a
491 \Data object.
492 Either of the arguments may be a \Data object, a python number or a numarray object.
493
494 If \var{arg0} or \var{arg1} are
495 not defined on the same \FunctionSpace, then an attempt is made to convert \var{arg0}
496 to the \FunctionSpace of \var{arg1} or to convert \var{arg1} to
497 the \FunctionSpace of \var{arg0}. Both arguments must have the same
498 \Shape or one of the arguments may be of rank 0 (a constant).
499
500 The returned \Data object has the same \Shape and is defined on
501 the \DataSamplePoints as \var{arg0} or \var{arg1}.
502
503 The following table shows the update operations that can be applied to
504 \Data objects:
505 \begin{tableii}{l|l}{textrm}{expression}{Description}
506 \lineii{\var{arg0}+=\var{arg2}} {adds \var{arg0} to \var{arg2} \index{+}}
507 \lineii{\var{arg0}*=\var{arg2}} {multiplies \var{arg0} with \var{arg2} \index{*}}
508 \lineii{\var{arg0}-=\var{arg2}} {subtracts \var{arg2} from\var{arg2} \index{-}}
509 \lineii{\var{arg0}/=\var{arg2}} {divides \var{arg0} by \var{arg2} \index{/}}
510 \lineii{\var{arg0}**=\var{arg2}} {raises \var{arg0} by \var{arg2} \index{**}}
511 \end{tableii}
512 \var{arg0} must be a \Data object. \var{arg1} must be a
513 \Data object or an object that can be converted into a
514 \Data object. \var{arg1} must have the same \Shape as
515 \var{arg0} or have rank 0. In the latter case it is
516 assumed that the values of \var{arg1} are constant for all
517 components. \var{arg1} must be defined in the same \FunctionSpace as
518 \var{arg0} or it must be possible to interpolate \var{arg1} onto the
519 \FunctionSpace of \var{arg0}.
520
521 The \Data class supports taking slices from a \Data object as well as assigning new values to a slice of an existing
522 \Data object. \index{slicing}
523 The following expressions for taking and setting slices are valid:
524 \begin{tableiii}{l|ll}{textrm}{rank of \var{arg}}{slicing expression}{\Shape of returned and assigned object}
525 \lineiii{0}{ no slicing } {-}
526 \lineiii{1}{\var{arg[l0:u0]}} {(\var{u0}-\var{l0},)}
527 \lineiii{2}{\var{arg[l0:u0,l1:u1]}} {(\var{u0}-\var{l0},\var{u1}-\var{l1})}
528 \lineiii{3}{\var{arg[l0:u0,l1:u1,l2:u2]} } {(\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2})}
529 \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})}
530 \end{tableiii}
531 where \var{s} is the \Shape of \var{arg} and
532 \[0 \le \var{l0} \le \var{u0} \le \var{s[0]},\]
533 \[0 \le \var{l1} \le \var{u1} \le \var{s[1]},\]
534 \[0 \le \var{l2} \le \var{u2} \le \var{s[2]},\]
535 \[0 \le \var{l3} \le \var{u3} \le \var{s[3]}.\]
536 Any of the lower indexes \var{l0}, \var{l1}, \var{l2} and \var{l3} may not be present in which case
537 $0$ is assumed.
538 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.
539 The lower and upper index may be identical, in which case the column and the lower or upper
540 index may be dropped. In the returned or in the object assigned to a slice, the corresponding component is dropped,
541 i.e. the rank is reduced by one in comparison to \var{arg}.
542 The following examples show slicing in action:
543 \begin{python}
544 t=Data(1.,(4,4,6,6),Function(mydomain))
545 t[1,1,1,0]=9.
546 s=t[:2,:,2:6,5] # s has rank 3
547 s[:,:,1]=1.
548 t[:2,:2,5,5]=s[2:4,1,:2]
549 \end{python}
550
551 \subsection{Generation of \Data objects}
552 \begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expand=\False}
553 creates a \Data object with \Shape \var{shape} in the \FunctionSpace \var{what}.
554 The values at all \DataSamplePoints are set to the double value \var{value}. If \var{expanded} is \True
555 the \Data object is represented in expanded from.
556 \end{classdesc}
557
558 \begin{classdesc}{Data}{value,what=FunctionSpace(),expand=\False}
559 creates a \Data object in the \FunctionSpace \var{what}.
560 The value for each \DataSamplePoints is set to \var{value}, which could be a \numarray, \Data object \var{value} or a dictionary of
561 \numarray or floating point numbers. In the latter case the keys must be integers and are used
562 as tags.
563 The \Shape of the returned object is equal to the \Shape of \var{value}. If \var{expanded} is \True
564 the \Data object is represented in expanded form.
565 \end{classdesc}
566
567 \begin{classdesc}{Data}{}
568 creates an \EmptyData object. The \EmptyData object is used to indicate that an argument is not present
569 where a \Data object is required.
570 \end{classdesc}
571
572 \begin{funcdesc}{Scalar}{value=0.,what=FunctionSpace(),expand=\False}
573 returns a \Data object of rank 0 (a constant) in the \FunctionSpace \var{what}.
574 Values are initialised with \var{value}, a double precision quantity. If \var{expanded} is \True
575 the \Data object is represented in expanded from.
576 \end{funcdesc}
577
578 \begin{funcdesc}{Vector}{value=0.,what=FunctionSpace(),expand=\False}
579 returns a \Data object of \Shape \var{(d,)} in the \FunctionSpace \var{what},
580 where \var{d} is the spatial dimension of the \Domain of \var{what}.
581 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
582 the \Data object is represented in expanded from.
583 \end{funcdesc}
584
585 \begin{funcdesc}{Tensor}{value=0.,what=FunctionSpace(),expand=\False}
586 returns a \Data object of \Shape \var{(d,d)} in the \FunctionSpace \var{what},
587 where \var{d} is the spatial dimension of the \Domain of \var{what}.
588 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
589 the \Data object is represented in expanded from.
590 \end{funcdesc}
591
592 \begin{funcdesc}{Tensor3}{value=0.,what=FunctionSpace(),expand=\False}
593 returns a \Data object of \Shape \var{(d,d,d)} in the \FunctionSpace \var{what},
594 where \var{d} is the spatial dimension of the \Domain of \var{what}.
595 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
596 the \Data object is re\var{arg}presented in expanded from.
597 \end{funcdesc}
598
599 \begin{funcdesc}{Tensor4}{value=0.,what=FunctionSpace(),expand=\False}
600 returns a \Data object of \Shape \var{(d,d,d,d)} in the \FunctionSpace \var{what},
601 where \var{d} is the spatial dimension of the \Domain of \var{what}.
602 Values are initialised with \var{value}, a double precision quantity. If \var{expanded} is \True
603 the \Data object is represented in expanded from.
604 \end{funcdesc}
605
606 \begin{funcdesc}{load}{filename,domain}
607 recovers a \Data object on \Domain \var{domain} from the file \var{filename}, which was created by \function{dump}.
608 \end{funcdesc}
609
610 \subsection{\Data methods}
611 These are the most frequently-used methods of the
612 \Data class. A complete list of methods can be found on \ReferenceGuide.
613 \begin{methoddesc}[Data]{getFunctionSpace}{}
614 returns the \FunctionSpace of the object.
615 \end{methoddesc}
616
617 \begin{methoddesc}[Data]{getDomain}{}
618 returns the \Domain of the object.
619 \end{methoddesc}
620
621 \begin{methoddesc}[Data]{getShape}{}
622 returns the \Shape of the object as a \class{tuple} of
623 integers.
624 \end{methoddesc}
625
626 \begin{methoddesc}[Data]{getRank}{}
627 returns the rank of the data on each data point. \index{rank}
628 \end{methoddesc}
629
630 \begin{methoddesc}[Data]{isEmpty}{}
631 returns \True id the \Data object is the \EmptyData object.
632 Otherwise \False is returned.
633 Note that this is not the same as asking if the object contains no \DataSamplePoints.
634 \end{methoddesc}
635
636 \begin{methoddesc}[Data]{setTaggedValue}{tag_name,value}
637 assigns the \var{value} to all \DataSamplePoints which have the tag
638 assigned to \var{tag_name}. \var{value} must be an object of class
639 \class{numarray.NumArray} or must be convertible into a
640 \class{numarray.NumArray} object. \var{value} (or the corresponding
641 \class{numarray.NumArray} object) must be of rank $0$ or must have the
642 same rank like the object.
643 If a value has already be defined for tag \var{tag_name} within the object
644 it is overwritten by the new \var{value}. If the object is expanded,
645 the value assigned to \DataSamplePoints with tag \var{tag_name} is replaced by
646 \var{value}. If no tag is assigned tag name \var{tag_name}, no value is set.
647 \end{methoddesc}
648
649 \begin{methoddesc}[Data]{dump}{filename}
650 dumps the \Data object to the file \var{filename}. The file stores the
651 function space but not the \Domain. It is in the responsibility of the user to
652 save the \Domain.
653 \end{methoddesc}
654
655 \begin{methoddesc}[Data]{__str__}{}
656 returns a string representation of the object.
657 \end{methoddesc}
658
659 \subsection{Functions of \Data objects}
660 This section lists the most important functions for \Data class objects \var{a}.
661 A complete list and a more detailed description of the functionality can be found on \ReferenceGuide.
662 \begin{funcdesc}{saveVTK}{filename,**kwdata}
663 writes \Data defined by keywords in the file with \var{filename} using the
664 vtk file format \VTK file format. The key word is used as an identifier. The statement
665 \begin{python}
666 saveVTK("out.xml",temperature=T,velocity=v)
667 \end{python}
668 will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the
669 file \file{out.xml}. Restrictions on the allowed combinations of \FunctionSpace apply.
670 \end{funcdesc}
671 \begin{funcdesc}{saveDX}{filename,**kwdata}
672 writes \Data defined by keywords in the file with \var{filename} using the
673 vtk file format \OpenDX file format. The key word is used as an identifier. The statement
674 \begin{python}
675 saveDX("out.dx",temperature=T,velocity=v)
676 \end{python}
677 will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the
678 file \file{out.dx}. Restrictions on the allowed combinations of \FunctionSpace apply.
679 \end{funcdesc}
680 \begin{funcdesc}{kronecker}{d}
681 returns a \RankTwo \Data object in \FunctionSpace \var{d} such that
682 \begin{equation}
683 \code{kronecker(d)}\left[ i,j\right] = \left\{
684 \begin{array}{cc}
685 1 & \mbox{ if } i=j \\
686 0 & \mbox{ otherwise }
687 \end{array}
688 \right.
689 \end{equation}
690 If \var{d} is an integer a $(d,d)$ \numarray array is returned.
691 \end{funcdesc}
692 \begin{funcdesc}{identityTensor}{d}
693 is a synonym for \code{kronecker} (see above).
694 % returns a \RankTwo \Data object in \FunctionSpace \var{d} such that
695 % \begin{equation}
696 % \code{identityTensor(d)}\left[ i,j\right] = \left\{
697 % \begin{array}{cc}
698 % 1 & \mbox{ if } i=j \\
699 % 0 & \mbox{ otherwise }
700 % \end{array}
701 % \right.
702 % \end{equation}
703 % If \var{d} is an integer a $(d,d)$ \numarray array is returned.
704 \end{funcdesc}
705 \begin{funcdesc}{identityTensor4}{d}
706 returns a \RankFour \Data object in \FunctionSpace \var{d} such that
707 \begin{equation}
708 \code{identityTensor(d)}\left[ i,j,k,l\right] = \left\{
709 \begin{array}{cc}
710 1 & \mbox{ if } i=k \mbox{ and } j=l\\
711 0 & \mbox{ otherwise }
712 \end{array}
713 \right.
714 \end{equation}
715 If \var{d} is an integer a $(d,d,d,d)$ \numarray array is returned.
716 \end{funcdesc}
717 \begin{funcdesc}{unitVector}{i,d}
718 returns a \RankOne \Data object in \FunctionSpace \var{d} such that
719 \begin{equation}
720 \code{identityTensor(d)}\left[ j \right] = \left\{
721 \begin{array}{cc}
722 1 & \mbox{ if } j=i\\
723 0 & \mbox{ otherwise }
724 \end{array}
725 \right.
726 \end{equation}
727 If \var{d} is an integer a $(d,)$ \numarray array is returned.
728
729 \end{funcdesc}
730
731 \begin{funcdesc}{Lsup}{a}
732 returns the $L^{sup}$ norm of \var{arg}. This is the maximum of the absolute values
733 over all components and all \DataSamplePoints of \var{a}.
734 \end{funcdesc}
735
736 \begin{funcdesc}{sup}{a}
737 returns the maximum value over all components and all \DataSamplePoints of \var{a}.
738 \end{funcdesc}
739
740 \begin{funcdesc}{inf}{a}
741 returns the minimum value over all components and all \DataSamplePoints of \var{a}
742 \end{funcdesc}
743
744
745
746 \begin{funcdesc}{minval}{a}
747 returns at each \DataSamplePoints the minimum value over all components.
748 \end{funcdesc}
749
750 \begin{funcdesc}{maxval}{a}
751 returns at each \DataSamplePoints the maximum value over all components.
752 \end{funcdesc}
753
754 \begin{funcdesc}{length}{a}
755 returns at Euclidean norm at each \DataSamplePoints. For a \RankFour \var{a} this is
756 \begin{equation}
757 \code{length(a)}=\sqrt{\sum\hackscore{ijkl} \var{a} \left[i,j,k,l\right]^2}
758 \end{equation}
759 \end{funcdesc}
760 \begin{funcdesc}{trace}{a\optional{,axis_offset=0}}
761 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
762 case of a \RankTwo function and this is
763 \begin{equation}
764 \code{trace(a)}=\sum\hackscore{i} \var{a} \left[i,i\right]
765 \end{equation}
766 and for a \RankFour function and \code{axis_offset=1} this is
767 \begin{equation}
768 \code{trace(a,1)}\left[i,j\right]=\sum\hackscore{k} \var{a} \left[i,k,k,j\right]
769 \end{equation}
770 \end{funcdesc}
771
772 \begin{funcdesc}{transpose}{a\optional{, axis_offset=None}}
773 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
774 present \code{int(r/2)} is used where \var{r} is the rank of \var{a}.
775 the sum over components \var{axis_offset} and \var{axis_offset+1} with the same index. For instance in the
776 case of a \RankTwo function and this is
777 \begin{equation}
778 \code{transpose(a)}\left[i,j\right]=\var{a} \left[j,i\right]
779 \end{equation}
780 and for a \RankFour function and \code{axis_offset=1} this is
781 \begin{equation}
782 \code{transpose(a,1)}\left[i,j,k,l\right]=\var{a} \left[j,k,l,i\right]
783 \end{equation}
784 \end{funcdesc}
785
786 \begin{funcdesc}{swap_axes}{a\optional{, axis0=0 \optional{, axis1=1 }}}
787 returns \var{a} but with swapped components \var{axis0} and \var{axis1}. The argument \var{a} must be
788 at least of \RankTwo. For instance in the
789 for a \RankFour argument, \code{axis0=1} and \code{axis1=2} this is
790 \begin{equation}
791 \code{swap_axes(a,1,2)}\left[i,j,k,l\right]=\var{a} \left[i,k,j,l\right]
792 \end{equation}
793 \end{funcdesc}
794
795 \begin{funcdesc}{symmetric}{a}
796 returns the symmetric part of \var{a}. This is \code{(a+transpose(a))/2}.
797 \end{funcdesc}
798 \begin{funcdesc}{nonsymmetric}{a}
799 returns the non--symmetric part of \var{a}. This is \code{(a-transpose(a))/2}.
800 \end{funcdesc}
801 \begin{funcdesc}{inverse}{a}
802 return the inverse of \var{a}. This is
803 \begin{equation}
804 \code{matrix_mult(inverse(a),a)=kronecker(d)}
805 \end{equation}
806 if \var{a} has shape \code{(d,d)}. The current implementation is restricted to arguments of shape
807 \code{(2,2)} and \code{(3,3)}.
808 \end{funcdesc}
809 \begin{funcdesc}{eigenvalues}{a}
810 return the eigenvalues of \var{a}. This is
811 \begin{equation}
812 \code{matrix_mult(a,V)=e[i]*V}
813 \end{equation}
814 where \code{e=eigenvalues(a)} and \var{V} is suitable non--zero vector \var{V}.
815 The eigenvalues are ordered in increasing size.
816 The argument \var{a} has to be the symmetric, ie. \code{a=symmetric(a)}.
817 The current implementation is restricted to arguments of shape
818 \code{(2,2)} and \code{(3,3)}.
819 \end{funcdesc}
820 \begin{funcdesc}{eigenvalues_and_eigenvectors}{a}
821 return the eigenvalues and eigenvectors of \var{a}. This is
822 \begin{equation}
823 \code{matrix_mult(a,V[:,i])=e[i]*V[:,i]}
824 \end{equation}
825 where \code{e,V=eigenvalues_and_eigenvectors(a)}. The eigenvectors \var{V} are orthogonal and normalized, ie.
826 \begin{equation}
827 \code{matrix_mult(transpose(V),V)=kronecker(d)}
828 \end{equation}
829 if \var{a} has shape \code{(d,d)}. The eigenvalues are ordered in increasing size.
830 The argument \var{a} has to be the symmetric, ie. \code{a=symmetric(a)}.
831 The current implementation is restricted to arguments of shape
832 \code{(2,2)} and \code{(3,3)}.
833 \end{funcdesc}
834 \begin{funcdesc}{maximum}{*a}
835 returns the maximum value over all arguments at all \DataSamplePoints and for each component.
836 For instance
837 \begin{equation}
838 \code{maximum(a0,a1)}\left[i,j\right]=max(\var{a0} \left[i,j\right],\var{a1} \left[i,j\right])
839 \end{equation}
840 at all \DataSamplePoints.
841 \end{funcdesc}
842 \begin{funcdesc}{minimum}{*a}
843 returns the minimum value over all arguments at all \DataSamplePoints and for each component.
844 For instance
845 \begin{equation}
846 \code{minimum(a0,a1)}\left[i,j\right]=min(\var{a0} \left[i,j\right],\var{a1} \left[i,j\right])
847 \end{equation}
848 at all \DataSamplePoints.
849 \end{funcdesc}
850
851 \begin{funcdesc}{clip}{a\optional{, minval=0.}\optional{, maxval=1.}}
852 cuts back \var{a} into the range between \var{minval} and \var{maxval}. A value in the returned object equals
853 \var{minval} if the corresponding value of \var{a} is less than \var{minval}, equals \var{maxval} if the
854 corresponding value of \var{a} is greater than \var{maxval}
855 or corresponding value of \var{a} otherwise.
856 \end{funcdesc}
857 \begin{funcdesc}{inner}{a0,a1}
858 returns the inner product of \var{a0} and \var{a1}. For instance in the
859 case of \RankTwo arguments and this is
860 \begin{equation}
861 \code{inner(a)}=\sum\hackscore{ij}\var{a0} \left[j,i\right] \cdot \var{a1} \left[j,i\right]
862 \end{equation}
863 and for a \RankFour arguments this is
864 \begin{equation}
865 \code{inner(a)}=\sum\hackscore{ijkl}\var{a0} \left[i,j,k,l\right] \cdot \var{a1} \left[j,i,k,l\right]
866 \end{equation}
867 \end{funcdesc}
868
869 \begin{funcdesc}{matrix_mult}{a0,a1}
870 returns the matrix product of \var{a0} and \var{a1}. If \var{a1} is \RankOne this is
871 \begin{equation}
872 \code{matrix_mult(a)}\left[i\right]=\sum\hackscore{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[k\right]
873 \end{equation}
874 and if \var{a1} is \RankTwo this is
875 \begin{equation}
876 \code{matrix_mult(a)}\left[i,j\right]=\sum\hackscore{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[k,j\right]
877 \end{equation}
878 \end{funcdesc}
879
880 \begin{funcdesc}{transposed_matrix_mult}{a0,a1}
881 returns the matrix product of the transposed of \var{a0} and \var{a1}. The function is equivalent to
882 \code{matrix_mult(transpose(a0),a1)}.
883 If \var{a1} is \RankOne this is
884 \begin{equation}
885 \code{transposed_matrix_mult(a)}\left[i\right]=\sum\hackscore{k}\var{a0} \cdot \left[k,i\right]\var{a1} \left[k\right]
886 \end{equation}
887 and if \var{a1} is \RankTwo this is
888 \begin{equation}
889 \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]
890 \end{equation}
891 \end{funcdesc}
892
893 \begin{funcdesc}{matrix_transposed_mult}{a0,a1}
894 returns the matrix product of \var{a0} and the transposed of \var{a1}.
895 The function is equivalent to
896 \code{matrix_mult(a0,transpose(a1))}.
897 If \var{a1} is \RankTwo this is
898 \begin{equation}
899 \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]
900 \end{equation}
901 \end{funcdesc}
902
903 \begin{funcdesc}{outer}{a0,a1}
904 returns the outer product of \var{a0} and \var{a1}. For instance if \var{a0} and \var{a1} both are \RankOne then
905 \begin{equation}
906 \code{outer(a)}\left[i,j\right]=\var{a0} \left[i\right] \cdot \var{a1}\left[j\right]
907 \end{equation}
908 and if \var{a0} is \RankOne and \var{a1} is \RankThree
909 \begin{equation}
910 \code{outer(a)}\left[i,j,k\right]=\var{a0} \left[i\right] \cdot \var{a1}\left[j,k\right]
911 \end{equation}
912 \end{funcdesc}
913
914 \begin{funcdesc}{tensor_mult}{a0,a1}
915 returns the tensor product of \var{a0} and \var{a1}. If \var{a1} is \RankTwo this is
916 \begin{equation}
917 \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]
918 \end{equation}
919 and if \var{a1} is \RankFour this is
920 \begin{equation}
921 \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]
922 \end{equation}
923 \end{funcdesc}
924
925 \begin{funcdesc}{transposed_tensor_mult}{a0,a1}
926 returns the tensor product of the transposed of \var{a0} and \var{a1}. The function is equivalent to
927 \code{tensor_mult(transpose(a0),a1)}.
928 If \var{a1} is \RankTwo this is
929 \begin{equation}
930 \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]
931 \end{equation}
932 and if \var{a1} is \RankFour this is
933 \begin{equation}
934 \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]
935 \end{equation}
936 \end{funcdesc}
937
938 \begin{funcdesc}{tensor_transposed_mult}{a0,a1}
939 returns the tensor product of \var{a0} and the transposed of \var{a1}.
940 The function is equivalent to
941 \code{tensor_mult(a0,transpose(a1))}.
942 If \var{a1} is \RankTwo this is
943 \begin{equation}
944 \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]
945 \end{equation}
946 and if \var{a1} is \RankFour this is
947 \begin{equation}
948 \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]
949 \end{equation}
950 \end{funcdesc}
951
952 \begin{funcdesc}{grad}{a\optional{, where=None}}
953 returns the gradient of \var{a}. If \var{where} is present the gradient will be calculated in \FunctionSpace \var{where} otherwise a
954 default \FunctionSpace is used. In case that \var{a} has \RankTwo one has
955 \begin{equation}
956 \code{grad(a)}\left[i,j,k\right]=\frac{\partial \var{a} \left[i,j\right]}{\partial x\hackscore{k}}
957 \end{equation}
958 \end{funcdesc}
959 \begin{funcdesc}{integrate}{a\optional{ ,where=None}}
960 returns the integral of \var{a} where the domain of integration is defined by the \FunctionSpace of \var{a}. If \var{where} is
961 present the argument is interpolated into \FunctionSpace \var{where} before integration. For instance in the case of
962 a \RankTwo argument in \ContinuousFunction it is
963 \begin{equation}
964 \code{integrate(a)}\left[i,j\right]=\int\hackscore{\Omega}\var{a} \left[i,j\right] \; d\Omega
965 \end{equation}
966 where $\Omega$ is the spatial domain and $d\Omega$ volume integration. To integrate over the boundary of the domain one uses
967 \begin{equation}
968 \code{integrate(a,where=FunctionOnBoundary(a.getDomain))}\left[i,j\right]=\int\hackscore{\partial \Omega} a\left[i,j\right] \; ds
969 \end{equation}
970 where $\partial \Omega$ is the surface of the spatial domain and $ds$ area or line integration.
971 \end{funcdesc}
972 \begin{funcdesc}{interpolate}{a,where}
973 interpolates argument \var{a} into the \FunctionSpace \var{where}.
974 \end{funcdesc}
975 \begin{funcdesc}{div}{a\optional{ ,where=None}}
976 returns the divergence of \var{a}. This
977 \begin{equation}
978 \code{div(a)}=trace(grad(a),where)
979 \end{equation}
980 \end{funcdesc}
981 \begin{funcdesc}{jump}{a\optional{ ,domain=None}}
982 returns the jump of \var{a} over the discontinuity in its domain or if \Domain \var{domain} is present
983 in \var{domain}.
984 \begin{equation}
985 \begin{array}{rcl}
986 \code{jump(a)}& = &\code{interpolate(a,FunctionOnContactOne(domain))} \\
987 & & \hfill - \code{interpolate(a,FunctionOnContactZero(domain))}
988 \end{array}
989 \end{equation}
990 \end{funcdesc}
991 \begin{funcdesc}{L2}{a}
992 returns the $L^2$-norm of \var{a} in its function space. This is
993 \begin{equation}
994 \code{L2(a)=integrate(length(a)}^2\code{)} \; .
995 \end{equation}
996 \end{funcdesc}
997
998 The following functions operate ``point-wise''. That is, the operation is applied to each component of each point
999 individually.
1000
1001 \begin{funcdesc}{sin}{a}
1002 applies sine function to \var{a}.
1003 \end{funcdesc}
1004
1005 \begin{funcdesc}{cos}{a}
1006 applies cosine function to \var{a}.
1007 \end{funcdesc}
1008
1009 \begin{funcdesc}{tan}{a}
1010 applies tangent function to \var{a}.
1011 \end{funcdesc}
1012
1013 \begin{funcdesc}{asin}{a}
1014 applies arc (inverse) sine function to \var{a}.
1015 \end{funcdesc}
1016
1017 \begin{funcdesc}{acos}{a}
1018 applies arc (inverse) cosine function to \var{a}.
1019 \end{funcdesc}
1020
1021 \begin{funcdesc}{atan}{a}
1022 applies arc (inverse) tangent function to \var{a}.
1023 \end{funcdesc}
1024
1025 \begin{funcdesc}{sinh}{a}
1026 applies hyperbolic sine function to \var{a}.
1027 \end{funcdesc}
1028
1029 \begin{funcdesc}{cosh}{a}
1030 applies hyperbolic cosine function to \var{a}.
1031 \end{funcdesc}
1032
1033 \begin{funcdesc}{tanh}{a}
1034 applies hyperbolic tangent function to \var{a}.
1035 \end{funcdesc}
1036
1037 \begin{funcdesc}{asinh}{a}
1038 applies arc (inverse) hyperbolic sine function to \var{a}.
1039 \end{funcdesc}
1040
1041 \begin{funcdesc}{acosh}{a}
1042 applies arc (inverse) hyperbolic cosine function to \var{a}.
1043 \end{funcdesc}
1044
1045 \begin{funcdesc}{atanh}{a}
1046 applies arc (inverse) hyperbolic tangent function to \var{a}.
1047 \end{funcdesc}
1048
1049 \begin{funcdesc}{exp}{a}
1050 applies exponential function to \var{a}.
1051 \end{funcdesc}
1052
1053 \begin{funcdesc}{sqrt}{a}
1054 applies square root function to \var{a}.
1055 \end{funcdesc}
1056
1057 \begin{funcdesc}{log}{a}
1058 applies the natural logarithm to \var{a}.
1059 \end{funcdesc}
1060
1061 \begin{funcdesc}{log10}{a}
1062 applies the base-$10$ logarithm to \var{a}.
1063 \end{funcdesc}
1064
1065 \begin{funcdesc}{sign}{a}
1066 applies the sign function to \var{a}, that is $1$ where \var{a} is positive,
1067 $-1$ where \var{a} is negative and $0$ otherwise.
1068 \end{funcdesc}
1069
1070 \begin{funcdesc}{wherePositive}{a}
1071 returns a function which is $1$ where \var{a} is positive and $0$ otherwise.
1072 \end{funcdesc}
1073
1074 \begin{funcdesc}{whereNegative}{a}
1075 returns a function which is $1$ where \var{a} is negative and $0$ otherwise.
1076 \end{funcdesc}
1077
1078 \begin{funcdesc}{whereNonNegative}{a}
1079 returns a function which is $1$ where \var{a} is non--negative and $0$ otherwise.
1080 \end{funcdesc}
1081
1082 \begin{funcdesc}{whereNonPositive}{a}
1083 returns a function which is $1$ where \var{a} is non--positive and $0$ otherwise.
1084 \end{funcdesc}
1085
1086 \begin{funcdesc}{whereZero}{a\optional{, tol=None, \optional{, rtol=1.e-8}}}
1087 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.
1088 \end{funcdesc}
1089
1090 \begin{funcdesc}{whereNonZero}{a, \optional{, tol=None, \optional{, rtol=1.e-8}}}
1091 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.
1092 \end{funcdesc}
1093
1094 \subsection{\Operator Class}
1095 The \Operator class provides an abstract access to operators build
1096 within the \LinearPDE class. \Operator objects are created
1097 when a PDE is handed over to a PDE solver library and handled
1098 by the \LinearPDE object defining the PDE. The user can gain access
1099 to the \Operator of a \LinearPDE object through the \var{getOperator}
1100 method.
1101
1102 \begin{classdesc}{Operator}{}
1103 creates an empty \Operator object.
1104 \end{classdesc}
1105
1106 \begin{methoddesc}[Operator]{isEmpty}{fileName}
1107 returns \True is the object is empty. Otherwise \True is returned.
1108 \end{methoddesc}
1109
1110 \begin{methoddesc}[Operator]{setValue}{value}
1111 resets all entries in the object representation to \var{value}
1112 \end{methoddesc}
1113
1114 \begin{methoddesc}[Operator]{solves}{rhs}
1115 solves the operator equation with right hand side \var{rhs}
1116 \end{methoddesc}
1117
1118 \begin{methoddesc}[Operator]{of}{u}
1119 applies the operator to the \Data object \var{u}
1120 \end{methoddesc}
1121
1122 \begin{methoddesc}[Operator]{saveMM}{fileName}
1123 saves the object to a matrix market format file of name
1124 \var{fileName}, see
1125 \ulink{maths.nist.gov/MatrixMarket}{\url{http://maths.nist.gov/MatrixMarket}}.
1126 \index{Matrix Market}
1127 \end{methoddesc}
1128
1129 \section{Utilities}
1130 \begin{funcdesc}{setEscriptParamInt}{name,value}
1131 assignes the ineger value \var{value} to the parameter \var{name}.
1132 If \var{name}="TOO_MANY_LINES" convertion of any \Data object to a string is switching to a
1133 condensed format if more than \var{value} lines would be created.
1134 \end{funcdesc}
1135
1136 \begin{funcdesc}{getEscriptParamInt}{name}
1137 returns the current value of integer parameter \var{name}.
1138 \end{funcdesc}
1139
1140 \begin{funcdesc}{listEscriptParams}{a}
1141 returns a list of valid parameters and their description.
1142 \end{funcdesc}
1143
1144 \begin{funcdesc}{getMPISizeWorld}{}
1145 returns the number of \MPI processors in use in the \env{MPI_COMM_WORLD} processor group.
1146 If \MPI is not used 1 is returend.
1147 \end{funcdesc}
1148 \begin{funcdesc}{getMPIRankWorld}{}
1149 returns the rank of the process within the \env{MPI_COMM_WORLD} processor group.
1150 If \MPI is not used 0 is returend.
1151 \end{funcdesc}
1152 \begin{funcdesc}{MPIBarrierWorld}{}
1153 performs a barrier synchronization across all processors within \env{MPI_COMM_WORLD}
1154 processor group.
1155 \end{funcdesc}
1156 \begin{funcdesc}{getMPIWorldMax}{a}
1157 returns the maximum value of the interger \var{a} across all
1158 processors within \env{MPI_COMM_WORLD}.
1159 \end{funcdesc}

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26