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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26