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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2484 - (show annotations)
Mon Jun 22 04:22:19 2009 UTC (9 years, 6 months ago) by gross
File MIME type: application/x-tex
File size: 57821 byte(s)
numarray removed from docu; Locator revised.
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 \numpy
128 array or any object, such as a list of floating point numbers,
129 that can be converted into a \numpyNDA \cite{NUMPY}.
130 The following two statements
131 create objects which are equivalent to \var{mydat}:
132 \begin{python}
133 mydat1=Data(value=numpy.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{numpy.ones((2,3))}
137 which generates a $2 \times 3$ matrix as a \numpyNDA
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 \numpyNDA 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 \numpyNDA 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\cite{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 mydomain.dump(`dom.nc`)
280 \end{python}
281 To recover the object \var{x} and \var{mydomain} was a \finley mesh use
282 \begin{python}
283 from esys.finley import LoadMesh
284 mydomain=LoadMesh('dom.nc')
285 x=load("x.nc", mydomain)
286 \end{python}
287 It possible to rerun the mechanism that was originally used to generates
288 \var{mydomain} to recreate \var{mydomain}. However in most cases using \var{dump} and
289 load is faster in particular if optimization has been applied. In case that
290 \escript is running on more than one \MPI processor the \var{dump} will create an individual file for each processor containing the local data. In order to avoid conflicts the file name is extended by the \MPI processor rank.
291
292 The function space of the \Data is stored in {\tt x.nc}, though.
293 If the \Data object
294 is expanded, the number of data points in the file and of the \Domain for the particular \FunctionSpace must match.
295 Moreover, the ordering of the values is checked using the reference identifiers provided by
296 \FunctionSpace on the \Domain. In some cases, data points will be re-ordered. Take care to be sure you get what you want!
297
298
299 \section{\escript Classes}
300 \declaremodule{extension}{esys.escript}
301 \modulesynopsis{Data manipulation}
302
303 \subsection{\Domain class}
304 \begin{classdesc}{Domain}{}
305 A \Domain object is used to describe a geometric region together with
306 a way of representing functions over this region.
307 The \Domain class provides an abstract interface to the domain of \FunctionSpace and \Data objects.
308 \Domain needs to be subclassed in order to provide a complete implementation.
309 \end{classdesc}
310 The following methods are available:
311 \begin{methoddesc}[Domain]{getDim}{}
312 returns the spatial dimension of the \Domain.
313 \end{methoddesc}
314 \begin{methoddesc}[Domain]{dump}{filename}
315 dumps the \Domain into the file \var{filename}.
316 \end{methoddesc}
317 \begin{methoddesc}[Domain]{getX}{}
318 returns the locations in the \Domain. The \FunctionSpace of the returned
319 \Data object is chosen by the \Domain implementation. Typically it will be
320 in the \Function.
321 \end{methoddesc}
322
323 \begin{methoddesc}[Domain]{setX}{newX}
324 assigns a new location to the \Domain. \var{newX} has to have \Shape $(d,)$
325 where $d$ is the spatial dimension of the domain. Typically \var{newX} must be
326 in the \ContinuousFunction but the space actually to be used depends on the \Domain implementation.
327 \end{methoddesc}
328
329 \begin{methoddesc}[Domain]{getNormal}{}
330 returns the surface normals on the boundary of the \Domain as \Data object.
331 \end{methoddesc}
332
333 \begin{methoddesc}[Domain]{getSize}{}
334 returns the local sample size, e.g. the element diameter, as \Data object.
335 \end{methoddesc}
336
337 \begin{methoddesc}[Domain]{setTagMap}{tag_name, tag}
338 defines a mapping of the tag name \var{tag_name} to the \var{tag}.
339 \end{methoddesc}
340 \begin{methoddesc}[Domain]{getTag}{tag_name}
341 returns the tag associated with the tag name \var{tag_name}.
342 \end{methoddesc}
343 \begin{methoddesc}[Domain]{isValidTagName}{tag_name}
344 return \True if \var{tag_name} is a valid tag name.
345 \end{methoddesc}
346
347 \begin{methoddesc}[Domain]{__eq__}{arg}
348 (python == operator) returns \True if the \Domain \var{arg} describes the same domain. Otherwise
349 \False is returned.
350 \end{methoddesc}
351
352 \begin{methoddesc}[Domain]{__ne__}{arg}
353 (python != operator) returns \True if the \Domain \var{arg} does not describe the same domain.
354 Otherwise \False is returned.
355 \end{methoddesc}
356
357 \begin{methoddesc}[Domain]{__str__}{arg}
358 (python str() function) returns string representation of the \Domain.
359 \end{methoddesc}
360
361 \begin{methoddesc}[Domain]{onMasterProcessor)}{}
362 returns \True if the processor is the master processor within
363 the \MPI processor group used by the \Domain. This is the processor with rank 0.
364 If \MPI support is not enabled the return value is always \True.
365 \end{methoddesc}
366
367 \begin{methoddesc}[Domain]{getMPISize}{}
368 returns the number of \MPI processors used for this \Domain. If \MPI support is not enabled
369 1 is returned.
370 \end{methoddesc}
371
372 \begin{methoddesc}[Domain]{getMPIRank}{}
373 returns the rank of the processor executing the statement
374 within the \MPI processor group used by the \Domain.
375 If \MPI support is not enabled 0 is returned.
376 \end{methoddesc}
377
378 \begin{methoddesc}[Domain]{MPIBarrier}{}
379 executes barrier synchronization within
380 the \MPI processor group used by the \Domain.
381 If \MPI support is not enabled, this command does nothing.
382 \end{methoddesc}
383
384 \subsection{\FunctionSpace class}
385 \begin{classdesc}{FunctionSpace}{}
386 \FunctionSpace objects are used to define properties of \Data objects, such as continuity. \FunctionSpace objects
387 are instantiated by generator functions. A \Data object in a particular \FunctionSpace is
388 represented by its values at \DataSamplePoints which are defined by the type and the \Domain of the
389 \FunctionSpace.
390 \end{classdesc}
391 The following methods are available:
392 \begin{methoddesc}[FunctionSpace]{getDim}{}
393 returns the spatial dimension of the \Domain of the \FunctionSpace.
394 \end{methoddesc}
395
396
397
398 \begin{methoddesc}[FunctionSpace]{getX}{}
399 returns the location of the \DataSamplePoints.
400 \end{methoddesc}
401
402 \begin{methoddesc}[FunctionSpace]{getNormal}{}
403 If the domain of functions in the \FunctionSpace
404 is a hyper-manifold (e.g. the boundary of a domain)
405 the method returns the outer normal at each of the
406 \DataSamplePoints. Otherwise an exception is raised.
407 \end{methoddesc}
408
409 \begin{methoddesc}[FunctionSpace]{getSize}{}
410 returns a \Data objects measuring the spacing of the \DataSamplePoints.
411 The size may be zero.
412 \end{methoddesc}
413
414 \begin{methoddesc}[FunctionSpace]{getDomain}{}
415 returns the \Domain of the \FunctionSpace.
416 \end{methoddesc}
417
418 \begin{methoddesc}[FunctionSpace]{setTags}{new_tag, mask}
419 assigns a new tag \var{new_tag} to all data sample
420 where \var{mask} is positive for a least one data point.
421 \var{mask} must be defined on the this \FunctionSpace.
422 Use the \var{setTagMap} to assign a tag name to \var{new_tag}.
423 \end{methoddesc}
424
425 \begin{methoddesc}[FunctionSpace]{__eq__}{arg}
426 (python == operator) returns \True if the \Domain \var{arg} describes the same domain. Otherwise
427 \False is returned.
428 \end{methoddesc}
429
430 \begin{methoddesc}[FunctionSpace]{__ne__}{arg}
431 (python != operator) returns \True if the \Domain \var{arg} do not describe the same domain.
432 Otherwise \False is returned.
433 \end{methoddesc}
434
435 \begin{methoddesc}[Domain]{__str__}{g}
436 (python str() function) returns string representation of the \Domain.
437 \end{methoddesc}
438
439 The following function provide generators for \FunctionSpace objects:
440 \begin{funcdesc}{Function}{domain}
441 returns the \Function on the \Domain \var{domain}. \Data objects in this type of \Function
442 are defined over the whole geometric region defined by \var{domain}.
443 \end{funcdesc}
444
445 \begin{funcdesc}{ContinuousFunction}{domain}
446 returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function
447 are defined over the whole geometric region defined by \var{domain} and assumed to represent
448 a continuous function.
449 \end{funcdesc}
450
451 \begin{funcdesc}{FunctionOnBoundary}{domain}
452 returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function
453 are defined on the boundary of the geometric region defined by \var{domain}.
454 \end{funcdesc}
455
456 \begin{funcdesc}{FunctionOnContactZero}{domain}
457 returns the \FunctionOnContactZero the \Domain domain. \Data objects in this type of \Function
458 are defined on side 0 of a discontinuity within the geometric region defined by \var{domain}.
459 The discontinuity is defined when \var{domain} is instantiated.
460 \end{funcdesc}
461
462 \begin{funcdesc}{FunctionOnContactOne}{domain}
463 returns the \FunctionOnContactOne on the \Domain domain.
464 \Data objects in this type of \Function
465 are defined on side 1 of a discontinuity within the geometric region defined by \var{domain}.
466 The discontinuity is defined when \var{domain} is instantiated.
467 \end{funcdesc}
468
469 \begin{funcdesc}{Solution}{domain}
470 returns the \SolutionFS 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}.
473 \end{funcdesc}
474
475 \begin{funcdesc}{ReducedSolution}{domain}
476 returns the \ReducedSolutionFS on the \Domain domain. \Data objects in this type of \Function
477 are defined on geometric region defined by \var{domain} and are solutions of
478 partial differential equations \index{partial differential equation} with a reduced smoothness
479 for the solution approximation.
480 \end{funcdesc}
481
482 \subsection{\Data Class}
483 \label{SEC ESCRIPT DATA}
484
485 The following table shows arithmetic operations that can be performed point-wise on
486 \Data objects.
487 \begin{tableii}{l|l}{textrm}{expression}{Description}
488 \lineii{+\var{arg0}} {identical to \var{arg} \index{+}}
489 \lineii{-\var{arg0}} {negation\index{-}}
490 \lineii{\var{arg0}+\var{arg1}} {adds \var{arg0} and \var{arg1} \index{+}}
491 \lineii{\var{arg0}*\var{arg1}} {multiplies \var{arg0} and \var{arg1} \index{*}}
492 \lineii{\var{arg0}-\var{arg1}} {difference \var{arg1} from\var{arg1} \index{-}}
493 \lineii{\var{arg0}/\var{arg1}} {divide \var{arg0} by \var{arg1} \index{/}}
494 \lineii{\var{arg0}**\var{arg1}} {raises \var{arg0} to the power of \var{arg1} \index{**}}
495 \end{tableii}
496 At least one of the arguments \var{arg0} or \var{arg1} must be a
497 \Data object.
498 Either of the arguments may be a \Data object, a python number or a \numpy object.
499
500 If \var{arg0} or \var{arg1} are
501 not defined on the same \FunctionSpace, then an attempt is made to convert \var{arg0}
502 to the \FunctionSpace of \var{arg1} or to convert \var{arg1} to
503 the \FunctionSpace of \var{arg0}. Both arguments must have the same
504 \Shape or one of the arguments may be of rank 0 (a constant).
505
506 The returned \Data object has the same \Shape and is defined on
507 the \DataSamplePoints as \var{arg0} or \var{arg1}.
508
509 The following table shows the update operations that can be applied to
510 \Data objects:
511 \begin{tableii}{l|l}{textrm}{expression}{Description}
512 \lineii{\var{arg0}+=\var{arg2}} {adds \var{arg0} to \var{arg2} \index{+}}
513 \lineii{\var{arg0}*=\var{arg2}} {multiplies \var{arg0} with \var{arg2} \index{*}}
514 \lineii{\var{arg0}-=\var{arg2}} {subtracts \var{arg2} from\var{arg2} \index{-}}
515 \lineii{\var{arg0}/=\var{arg2}} {divides \var{arg0} by \var{arg2} \index{/}}
516 \lineii{\var{arg0}**=\var{arg2}} {raises \var{arg0} by \var{arg2} \index{**}}
517 \end{tableii}
518 \var{arg0} must be a \Data object. \var{arg1} must be a
519 \Data object or an object that can be converted into a
520 \Data object. \var{arg1} must have the same \Shape as
521 \var{arg0} or have rank 0. In the latter case it is
522 assumed that the values of \var{arg1} are constant for all
523 components. \var{arg1} must be defined in the same \FunctionSpace as
524 \var{arg0} or it must be possible to interpolate \var{arg1} onto the
525 \FunctionSpace of \var{arg0}.
526
527 The \Data class supports taking slices from a \Data object as well as assigning new values to a slice of an existing
528 \Data object. \index{slicing}
529 The following expressions for taking and setting slices are valid:
530 \begin{tableiii}{l|ll}{textrm}{rank of \var{arg}}{slicing expression}{\Shape of returned and assigned object}
531 \lineiii{0}{ no slicing } {-}
532 \lineiii{1}{\var{arg[l0:u0]}} {(\var{u0}-\var{l0},)}
533 \lineiii{2}{\var{arg[l0:u0,l1:u1]}} {(\var{u0}-\var{l0},\var{u1}-\var{l1})}
534 \lineiii{3}{\var{arg[l0:u0,l1:u1,l2:u2]} } {(\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2})}
535 \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})}
536 \end{tableiii}
537 where \var{s} is the \Shape of \var{arg} and
538 \[0 \le \var{l0} \le \var{u0} \le \var{s[0]},\]
539 \[0 \le \var{l1} \le \var{u1} \le \var{s[1]},\]
540 \[0 \le \var{l2} \le \var{u2} \le \var{s[2]},\]
541 \[0 \le \var{l3} \le \var{u3} \le \var{s[3]}.\]
542 Any of the lower indexes \var{l0}, \var{l1}, \var{l2} and \var{l3} may not be present in which case
543 $0$ is assumed.
544 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.
545 The lower and upper index may be identical, in which case the column and the lower or upper
546 index may be dropped. In the returned or in the object assigned to a slice, the corresponding component is dropped,
547 i.e. the rank is reduced by one in comparison to \var{arg}.
548 The following examples show slicing in action:
549 \begin{python}
550 t=Data(1.,(4,4,6,6),Function(mydomain))
551 t[1,1,1,0]=9.
552 s=t[:2,:,2:6,5] # s has rank 3
553 s[:,:,1]=1.
554 t[:2,:2,5,5]=s[2:4,1,:2]
555 \end{python}
556
557 \subsection{Generation of \Data objects}
558 \begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expand=\False}
559 creates a \Data object with \Shape \var{shape} in the \FunctionSpace \var{what}.
560 The values at all \DataSamplePoints are set to the double value \var{value}. If \var{expanded} is \True
561 the \Data object is represented in expanded from.
562 \end{classdesc}
563
564 \begin{classdesc}{Data}{value,what=FunctionSpace(),expand=\False}
565 creates a \Data object in the \FunctionSpace \var{what}.
566 The value for each \DataSamplePoints is set to \var{value}, which could be a \numpy, \Data object \var{value} or a dictionary of
567 \numpy or floating point numbers. In the latter case the keys must be integers and are used
568 as tags.
569 The \Shape of the returned object is equal to the \Shape of \var{value}. If \var{expanded} is \True
570 the \Data object is represented in expanded form.
571 \end{classdesc}
572
573 \begin{classdesc}{Data}{}
574 creates an \EmptyData object. The \EmptyData object is used to indicate that an argument is not present
575 where a \Data object is required.
576 \end{classdesc}
577
578 \begin{funcdesc}{Scalar}{value=0.,what=FunctionSpace(),expand=\False}
579 returns a \Data object of rank 0 (a constant) in the \FunctionSpace \var{what}.
580 Values are initialized with \var{value}, a double precision quantity. If \var{expanded} is \True
581 the \Data object is represented in expanded from.
582 \end{funcdesc}
583
584 \begin{funcdesc}{Vector}{value=0.,what=FunctionSpace(),expand=\False}
585 returns a \Data object of \Shape \var{(d,)} in the \FunctionSpace \var{what},
586 where \var{d} is the spatial dimension of the \Domain of \var{what}.
587 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
588 the \Data object is represented in expanded from.
589 \end{funcdesc}
590
591 \begin{funcdesc}{Tensor}{value=0.,what=FunctionSpace(),expand=\False}
592 returns a \Data object of \Shape \var{(d,d)} in the \FunctionSpace \var{what},
593 where \var{d} is the spatial dimension of the \Domain of \var{what}.
594 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
595 the \Data object is represented in expanded from.
596 \end{funcdesc}
597
598 \begin{funcdesc}{Tensor3}{value=0.,what=FunctionSpace(),expand=\False}
599 returns a \Data object of \Shape \var{(d,d,d)} in the \FunctionSpace \var{what},
600 where \var{d} is the spatial dimension of the \Domain of \var{what}.
601 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
602 the \Data object is re\var{arg}presented in expanded from.
603 \end{funcdesc}
604
605 \begin{funcdesc}{Tensor4}{value=0.,what=FunctionSpace(),expand=\False}
606 returns a \Data object of \Shape \var{(d,d,d,d)} in the \FunctionSpace \var{what},
607 where \var{d} is the spatial dimension of the \Domain of \var{what}.
608 Values are initialized with \var{value}, a double precision quantity. If \var{expanded} is \True
609 the \Data object is represented in expanded from.
610 \end{funcdesc}
611
612 \begin{funcdesc}{load}{filename,domain}
613 recovers a \Data object on \Domain \var{domain} from the file \var{filename}, which was created by \function{dump}.
614 \end{funcdesc}
615
616 \subsection{\Data methods}
617 These are the most frequently-used methods of the
618 \Data class. A complete list of methods can be found on \ReferenceGuide.
619 \begin{methoddesc}[Data]{getFunctionSpace}{}
620 returns the \FunctionSpace of the object.
621 \end{methoddesc}
622
623 \begin{methoddesc}[Data]{getDomain}{}
624 returns the \Domain of the object.
625 \end{methoddesc}
626
627 \begin{methoddesc}[Data]{getShape}{}
628 returns the \Shape of the object as a \class{tuple} of
629 integers.
630 \end{methoddesc}
631
632 \begin{methoddesc}[Data]{getRank}{}
633 returns the rank of the data on each data point. \index{rank}
634 \end{methoddesc}
635
636 \begin{methoddesc}[Data]{isEmpty}{}
637 returns \True id the \Data object is the \EmptyData object.
638 Otherwise \False is returned.
639 Note that this is not the same as asking if the object contains no \DataSamplePoints.
640 \end{methoddesc}
641
642 \begin{methoddesc}[Data]{setTaggedValue}{tag_name,value}
643 assigns the \var{value} to all \DataSamplePoints which have the tag
644 assigned to \var{tag_name}. \var{value} must be an object of class
645 \class{numpy.ndarray} or must be convertible into a
646 \class{numpy.ndarray} object. \var{value} (or the corresponding
647 \class{numpy.ndarray} object) must be of rank $0$ or must have the
648 same rank like the object.
649 If a value has already be defined for tag \var{tag_name} within the object
650 it is overwritten by the new \var{value}. If the object is expanded,
651 the value assigned to \DataSamplePoints with tag \var{tag_name} is replaced by
652 \var{value}. If no tag is assigned tag name \var{tag_name}, no value is set.
653 \end{methoddesc}
654
655 \begin{methoddesc}[Data]{dump}{filename}
656 dumps the \Data object to the file \var{filename}. The file stores the
657 function space but not the \Domain. It is in the responsibility of the user to
658 save the \Domain.
659 \end{methoddesc}
660
661 \begin{methoddesc}[Data]{__str__}{}
662 returns a string representation of the object.
663 \end{methoddesc}
664
665 \subsection{Functions of \Data objects}
666 This section lists the most important functions for \Data class objects \var{a}.
667 A complete list and a more detailed description of the functionality can be found on \ReferenceGuide.
668 \begin{funcdesc}{saveVTK}{filename,**kwdata}
669 writes \Data defined by keywords in the file with \var{filename} using the
670 vtk file format \VTK file format. The key word is used as an identifier. The statement
671 \begin{python}
672 saveVTK("out.xml",temperature=T,velocity=v)
673 \end{python}
674 will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the
675 file \file{out.xml}. Restrictions on the allowed combinations of \FunctionSpace apply.
676 \end{funcdesc}
677 \begin{funcdesc}{saveDX}{filename,**kwdata}
678 writes \Data defined by keywords in the file with \var{filename} using the
679 vtk file format \OpenDX file format. The key word is used as an identifier. The statement
680 \begin{python}
681 saveDX("out.dx",temperature=T,velocity=v)
682 \end{python}
683 will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the
684 file \file{out.dx}. Restrictions on the allowed combinations of \FunctionSpace apply.
685 \end{funcdesc}
686 \begin{funcdesc}{kronecker}{d}
687 returns a \RankTwo \Data object in \FunctionSpace \var{d} such that
688 \begin{equation}
689 \code{kronecker(d)}\left[ i,j\right] = \left\{
690 \begin{array}{cc}
691 1 & \mbox{ if } i=j \\
692 0 & \mbox{ otherwise }
693 \end{array}
694 \right.
695 \end{equation}
696 If \var{d} is an integer a $(d,d)$ \numpy array is returned.
697 \end{funcdesc}
698 \begin{funcdesc}{identityTensor}{d}
699 is a synonym for \code{kronecker} (see above).
700 % returns a \RankTwo \Data object in \FunctionSpace \var{d} such that
701 % \begin{equation}
702 % \code{identityTensor(d)}\left[ i,j\right] = \left\{
703 % \begin{array}{cc}
704 % 1 & \mbox{ if } i=j \\
705 % 0 & \mbox{ otherwise }
706 % \end{array}
707 % \right.
708 % \end{equation}
709 % If \var{d} is an integer a $(d,d)$ \numpy array is returned.
710 \end{funcdesc}
711 \begin{funcdesc}{identityTensor4}{d}
712 returns a \RankFour \Data object in \FunctionSpace \var{d} such that
713 \begin{equation}
714 \code{identityTensor(d)}\left[ i,j,k,l\right] = \left\{
715 \begin{array}{cc}
716 1 & \mbox{ if } i=k \mbox{ and } j=l\\
717 0 & \mbox{ otherwise }
718 \end{array}
719 \right.
720 \end{equation}
721 If \var{d} is an integer a $(d,d,d,d)$ \numpy array is returned.
722 \end{funcdesc}
723 \begin{funcdesc}{unitVector}{i,d}
724 returns a \RankOne \Data object in \FunctionSpace \var{d} such that
725 \begin{equation}
726 \code{identityTensor(d)}\left[ j \right] = \left\{
727 \begin{array}{cc}
728 1 & \mbox{ if } j=i\\
729 0 & \mbox{ otherwise }
730 \end{array}
731 \right.
732 \end{equation}
733 If \var{d} is an integer a $(d,)$ \numpy array is returned.
734
735 \end{funcdesc}
736
737 \begin{funcdesc}{Lsup}{a}
738 returns the $L^{sup}$ norm of \var{arg}. This is the maximum of the absolute values
739 over all components and all \DataSamplePoints of \var{a}.
740 \end{funcdesc}
741
742 \begin{funcdesc}{sup}{a}
743 returns the maximum value over all components and all \DataSamplePoints of \var{a}.
744 \end{funcdesc}
745
746 \begin{funcdesc}{inf}{a}
747 returns the minimum value over all components and all \DataSamplePoints of \var{a}
748 \end{funcdesc}
749
750
751
752 \begin{funcdesc}{minval}{a}
753 returns at each \DataSamplePoints the minimum value over all components.
754 \end{funcdesc}
755
756 \begin{funcdesc}{maxval}{a}
757 returns at each \DataSamplePoints the maximum value over all components.
758 \end{funcdesc}
759
760 \begin{funcdesc}{length}{a}
761 returns at Euclidean norm at each \DataSamplePoints. For a \RankFour \var{a} this is
762 \begin{equation}
763 \code{length(a)}=\sqrt{\sum\hackscore{ijkl} \var{a} \left[i,j,k,l\right]^2}
764 \end{equation}
765 \end{funcdesc}
766 \begin{funcdesc}{trace}{a\optional{,axis_offset=0}}
767 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
768 case of a \RankTwo function and this is
769 \begin{equation}
770 \code{trace(a)}=\sum\hackscore{i} \var{a} \left[i,i\right]
771 \end{equation}
772 and for a \RankFour function and \code{axis_offset=1} this is
773 \begin{equation}
774 \code{trace(a,1)}\left[i,j\right]=\sum\hackscore{k} \var{a} \left[i,k,k,j\right]
775 \end{equation}
776 \end{funcdesc}
777
778 \begin{funcdesc}{transpose}{a\optional{, axis_offset=None}}
779 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
780 present \code{int(r/2)} is used where \var{r} is the rank of \var{a}.
781 the sum over components \var{axis_offset} and \var{axis_offset+1} with the same index. For instance in the
782 case of a \RankTwo function and this is
783 \begin{equation}
784 \code{transpose(a)}\left[i,j\right]=\var{a} \left[j,i\right]
785 \end{equation}
786 and for a \RankFour function and \code{axis_offset=1} this is
787 \begin{equation}
788 \code{transpose(a,1)}\left[i,j,k,l\right]=\var{a} \left[j,k,l,i\right]
789 \end{equation}
790 \end{funcdesc}
791
792 \begin{funcdesc}{swap_axes}{a\optional{, axis0=0 \optional{, axis1=1 }}}
793 returns \var{a} but with swapped components \var{axis0} and \var{axis1}. The argument \var{a} must be
794 at least of \RankTwo. For instance in the
795 for a \RankFour argument, \code{axis0=1} and \code{axis1=2} this is
796 \begin{equation}
797 \code{swap_axes(a,1,2)}\left[i,j,k,l\right]=\var{a} \left[i,k,j,l\right]
798 \end{equation}
799 \end{funcdesc}
800
801 \begin{funcdesc}{symmetric}{a}
802 returns the symmetric part of \var{a}. This is \code{(a+transpose(a))/2}.
803 \end{funcdesc}
804 \begin{funcdesc}{nonsymmetric}{a}
805 returns the non--symmetric part of \var{a}. This is \code{(a-transpose(a))/2}.
806 \end{funcdesc}
807 \begin{funcdesc}{inverse}{a}
808 return the inverse of \var{a}. This is
809 \begin{equation}
810 \code{matrix_mult(inverse(a),a)=kronecker(d)}
811 \end{equation}
812 if \var{a} has shape \code{(d,d)}. The current implementation is restricted to arguments of shape
813 \code{(2,2)} and \code{(3,3)}.
814 \end{funcdesc}
815 \begin{funcdesc}{eigenvalues}{a}
816 return the eigenvalues of \var{a}. This is
817 \begin{equation}
818 \code{matrix_mult(a,V)=e[i]*V}
819 \end{equation}
820 where \code{e=eigenvalues(a)} and \var{V} is suitable non--zero vector \var{V}.
821 The eigenvalues are ordered in increasing size.
822 The argument \var{a} has to be the symmetric, ie. \code{a=symmetric(a)}.
823 The current implementation is restricted to arguments of shape
824 \code{(2,2)} and \code{(3,3)}.
825 \end{funcdesc}
826 \begin{funcdesc}{eigenvalues_and_eigenvectors}{a}
827 return the eigenvalues and eigenvectors of \var{a}. This is
828 \begin{equation}
829 \code{matrix_mult(a,V[:,i])=e[i]*V[:,i]}
830 \end{equation}
831 where \code{e,V=eigenvalues_and_eigenvectors(a)}. The eigenvectors \var{V} are orthogonal and normalized, ie.
832 \begin{equation}
833 \code{matrix_mult(transpose(V),V)=kronecker(d)}
834 \end{equation}
835 if \var{a} has shape \code{(d,d)}. The eigenvalues are ordered in increasing size.
836 The argument \var{a} has to be the symmetric, ie. \code{a=symmetric(a)}.
837 The current implementation is restricted to arguments of shape
838 \code{(2,2)} and \code{(3,3)}.
839 \end{funcdesc}
840 \begin{funcdesc}{maximum}{*a}
841 returns the maximum value over all arguments at all \DataSamplePoints and for each component.
842 For instance
843 \begin{equation}
844 \code{maximum(a0,a1)}\left[i,j\right]=max(\var{a0} \left[i,j\right],\var{a1} \left[i,j\right])
845 \end{equation}
846 at all \DataSamplePoints.
847 \end{funcdesc}
848 \begin{funcdesc}{minimum}{*a}
849 returns the minimum value over all arguments at all \DataSamplePoints and for each component.
850 For instance
851 \begin{equation}
852 \code{minimum(a0,a1)}\left[i,j\right]=min(\var{a0} \left[i,j\right],\var{a1} \left[i,j\right])
853 \end{equation}
854 at all \DataSamplePoints.
855 \end{funcdesc}
856
857 \begin{funcdesc}{clip}{a\optional{, minval=0.}\optional{, maxval=1.}}
858 cuts back \var{a} into the range between \var{minval} and \var{maxval}. A value in the returned object equals
859 \var{minval} if the corresponding value of \var{a} is less than \var{minval}, equals \var{maxval} if the
860 corresponding value of \var{a} is greater than \var{maxval}
861 or corresponding value of \var{a} otherwise.
862 \end{funcdesc}
863 \begin{funcdesc}{inner}{a0,a1}
864 returns the inner product of \var{a0} and \var{a1}. For instance in the
865 case of \RankTwo arguments and this is
866 \begin{equation}
867 \code{inner(a)}=\sum\hackscore{ij}\var{a0} \left[j,i\right] \cdot \var{a1} \left[j,i\right]
868 \end{equation}
869 and for a \RankFour arguments this is
870 \begin{equation}
871 \code{inner(a)}=\sum\hackscore{ijkl}\var{a0} \left[i,j,k,l\right] \cdot \var{a1} \left[j,i,k,l\right]
872 \end{equation}
873 \end{funcdesc}
874
875 \begin{funcdesc}{matrix_mult}{a0,a1}
876 returns the matrix product of \var{a0} and \var{a1}. If \var{a1} is \RankOne this is
877 \begin{equation}
878 \code{matrix_mult(a)}\left[i\right]=\sum\hackscore{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[k\right]
879 \end{equation}
880 and if \var{a1} is \RankTwo this is
881 \begin{equation}
882 \code{matrix_mult(a)}\left[i,j\right]=\sum\hackscore{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[k,j\right]
883 \end{equation}
884 \end{funcdesc}
885
886 \begin{funcdesc}{transposed_matrix_mult}{a0,a1}
887 returns the matrix product of the transposed of \var{a0} and \var{a1}. The function is equivalent to
888 \code{matrix_mult(transpose(a0),a1)}.
889 If \var{a1} is \RankOne this is
890 \begin{equation}
891 \code{transposed_matrix_mult(a)}\left[i\right]=\sum\hackscore{k}\var{a0} \cdot \left[k,i\right]\var{a1} \left[k\right]
892 \end{equation}
893 and if \var{a1} is \RankTwo this is
894 \begin{equation}
895 \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]
896 \end{equation}
897 \end{funcdesc}
898
899 \begin{funcdesc}{matrix_transposed_mult}{a0,a1}
900 returns the matrix product of \var{a0} and the transposed of \var{a1}.
901 The function is equivalent to
902 \code{matrix_mult(a0,transpose(a1))}.
903 If \var{a1} is \RankTwo this is
904 \begin{equation}
905 \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]
906 \end{equation}
907 \end{funcdesc}
908
909 \begin{funcdesc}{outer}{a0,a1}
910 returns the outer product of \var{a0} and \var{a1}. For instance if \var{a0} and \var{a1} both are \RankOne then
911 \begin{equation}
912 \code{outer(a)}\left[i,j\right]=\var{a0} \left[i\right] \cdot \var{a1}\left[j\right]
913 \end{equation}
914 and if \var{a0} is \RankOne and \var{a1} is \RankThree
915 \begin{equation}
916 \code{outer(a)}\left[i,j,k\right]=\var{a0} \left[i\right] \cdot \var{a1}\left[j,k\right]
917 \end{equation}
918 \end{funcdesc}
919
920 \begin{funcdesc}{tensor_mult}{a0,a1}
921 returns the tensor product of \var{a0} and \var{a1}. If \var{a1} is \RankTwo this is
922 \begin{equation}
923 \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]
924 \end{equation}
925 and if \var{a1} is \RankFour this is
926 \begin{equation}
927 \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]
928 \end{equation}
929 \end{funcdesc}
930
931 \begin{funcdesc}{transposed_tensor_mult}{a0,a1}
932 returns the tensor product of the transposed of \var{a0} and \var{a1}. The function is equivalent to
933 \code{tensor_mult(transpose(a0),a1)}.
934 If \var{a1} is \RankTwo this is
935 \begin{equation}
936 \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]
937 \end{equation}
938 and if \var{a1} is \RankFour this is
939 \begin{equation}
940 \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]
941 \end{equation}
942 \end{funcdesc}
943
944 \begin{funcdesc}{tensor_transposed_mult}{a0,a1}
945 returns the tensor product of \var{a0} and the transposed of \var{a1}.
946 The function is equivalent to
947 \code{tensor_mult(a0,transpose(a1))}.
948 If \var{a1} is \RankTwo this is
949 \begin{equation}
950 \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]
951 \end{equation}
952 and if \var{a1} is \RankFour this is
953 \begin{equation}
954 \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]
955 \end{equation}
956 \end{funcdesc}
957
958 \begin{funcdesc}{grad}{a\optional{, where=None}}
959 returns the gradient of \var{a}. If \var{where} is present the gradient will be calculated in \FunctionSpace \var{where} otherwise a
960 default \FunctionSpace is used. In case that \var{a} has \RankTwo one has
961 \begin{equation}
962 \code{grad(a)}\left[i,j,k\right]=\frac{\partial \var{a} \left[i,j\right]}{\partial x\hackscore{k}}
963 \end{equation}
964 \end{funcdesc}
965 \begin{funcdesc}{integrate}{a\optional{ ,where=None}}
966 returns the integral of \var{a} where the domain of integration is defined by the \FunctionSpace of \var{a}. If \var{where} is
967 present the argument is interpolated into \FunctionSpace \var{where} before integration. For instance in the case of
968 a \RankTwo argument in \ContinuousFunction it is
969 \begin{equation}
970 \code{integrate(a)}\left[i,j\right]=\int\hackscore{\Omega}\var{a} \left[i,j\right] \; d\Omega
971 \end{equation}
972 where $\Omega$ is the spatial domain and $d\Omega$ volume integration. To integrate over the boundary of the domain one uses
973 \begin{equation}
974 \code{integrate(a,where=FunctionOnBoundary(a.getDomain))}\left[i,j\right]=\int\hackscore{\partial \Omega} a\left[i,j\right] \; ds
975 \end{equation}
976 where $\partial \Omega$ is the surface of the spatial domain and $ds$ area or line integration.
977 \end{funcdesc}
978 \begin{funcdesc}{interpolate}{a,where}
979 interpolates argument \var{a} into the \FunctionSpace \var{where}.
980 \end{funcdesc}
981 \begin{funcdesc}{div}{a\optional{ ,where=None}}
982 returns the divergence of \var{a}. This
983 \begin{equation}
984 \code{div(a)}=trace(grad(a),where)
985 \end{equation}
986 \end{funcdesc}
987 \begin{funcdesc}{jump}{a\optional{ ,domain=None}}
988 returns the jump of \var{a} over the discontinuity in its domain or if \Domain \var{domain} is present
989 in \var{domain}.
990 \begin{equation}
991 \begin{array}{rcl}
992 \code{jump(a)}& = &\code{interpolate(a,FunctionOnContactOne(domain))} \\
993 & & \hfill - \code{interpolate(a,FunctionOnContactZero(domain))}
994 \end{array}
995 \end{equation}
996 \end{funcdesc}
997 \begin{funcdesc}{L2}{a}
998 returns the $L^2$-norm of \var{a} in its function space. This is
999 \begin{equation}
1000 \code{L2(a)=integrate(length(a)}^2\code{)} \; .
1001 \end{equation}
1002 \end{funcdesc}
1003
1004 The following functions operate ``point-wise''. That is, the operation is applied to each component of each point
1005 individually.
1006
1007 \begin{funcdesc}{sin}{a}
1008 applies sine function to \var{a}.
1009 \end{funcdesc}
1010
1011 \begin{funcdesc}{cos}{a}
1012 applies cosine function to \var{a}.
1013 \end{funcdesc}
1014
1015 \begin{funcdesc}{tan}{a}
1016 applies tangent function to \var{a}.
1017 \end{funcdesc}
1018
1019 \begin{funcdesc}{asin}{a}
1020 applies arc (inverse) sine function to \var{a}.
1021 \end{funcdesc}
1022
1023 \begin{funcdesc}{acos}{a}
1024 applies arc (inverse) cosine function to \var{a}.
1025 \end{funcdesc}
1026
1027 \begin{funcdesc}{atan}{a}
1028 applies arc (inverse) tangent function to \var{a}.
1029 \end{funcdesc}
1030
1031 \begin{funcdesc}{sinh}{a}
1032 applies hyperbolic sine function to \var{a}.
1033 \end{funcdesc}
1034
1035 \begin{funcdesc}{cosh}{a}
1036 applies hyperbolic cosine function to \var{a}.
1037 \end{funcdesc}
1038
1039 \begin{funcdesc}{tanh}{a}
1040 applies hyperbolic tangent function to \var{a}.
1041 \end{funcdesc}
1042
1043 \begin{funcdesc}{asinh}{a}
1044 applies arc (inverse) hyperbolic sine function to \var{a}.
1045 \end{funcdesc}
1046
1047 \begin{funcdesc}{acosh}{a}
1048 applies arc (inverse) hyperbolic cosine function to \var{a}.
1049 \end{funcdesc}
1050
1051 \begin{funcdesc}{atanh}{a}
1052 applies arc (inverse) hyperbolic tangent function to \var{a}.
1053 \end{funcdesc}
1054
1055 \begin{funcdesc}{exp}{a}
1056 applies exponential function to \var{a}.
1057 \end{funcdesc}
1058
1059 \begin{funcdesc}{sqrt}{a}
1060 applies square root function to \var{a}.
1061 \end{funcdesc}
1062
1063 \begin{funcdesc}{log}{a}
1064 applies the natural logarithm to \var{a}.
1065 \end{funcdesc}
1066
1067 \begin{funcdesc}{log10}{a}
1068 applies the base-$10$ logarithm to \var{a}.
1069 \end{funcdesc}
1070
1071 \begin{funcdesc}{sign}{a}
1072 applies the sign function to \var{a}, that is $1$ where \var{a} is positive,
1073 $-1$ where \var{a} is negative and $0$ otherwise.
1074 \end{funcdesc}
1075
1076 \begin{funcdesc}{wherePositive}{a}
1077 returns a function which is $1$ where \var{a} is positive and $0$ otherwise.
1078 \end{funcdesc}
1079
1080 \begin{funcdesc}{whereNegative}{a}
1081 returns a function which is $1$ where \var{a} is negative and $0$ otherwise.
1082 \end{funcdesc}
1083
1084 \begin{funcdesc}{whereNonNegative}{a}
1085 returns a function which is $1$ where \var{a} is non--negative and $0$ otherwise.
1086 \end{funcdesc}
1087
1088 \begin{funcdesc}{whereNonPositive}{a}
1089 returns a function which is $1$ where \var{a} is non--positive and $0$ otherwise.
1090 \end{funcdesc}
1091
1092 \begin{funcdesc}{whereZero}{a\optional{, tol=None, \optional{, rtol=1.e-8}}}
1093 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.
1094 \end{funcdesc}
1095
1096 \begin{funcdesc}{whereNonZero}{a, \optional{, tol=None, \optional{, rtol=1.e-8}}}
1097 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.
1098 \end{funcdesc}
1099
1100 \subsection{\Operator Class}
1101 The \Operator class provides an abstract access to operators build
1102 within the \LinearPDE class. \Operator objects are created
1103 when a PDE is handed over to a PDE solver library and handled
1104 by the \LinearPDE object defining the PDE. The user can gain access
1105 to the \Operator of a \LinearPDE object through the \var{getOperator}
1106 method.
1107
1108 \begin{classdesc}{Operator}{}
1109 creates an empty \Operator object.
1110 \end{classdesc}
1111
1112 \begin{methoddesc}[Operator]{isEmpty}{fileName}
1113 returns \True is the object is empty. Otherwise \True is returned.
1114 \end{methoddesc}
1115
1116 \begin{methoddesc}[Operator]{setValue}{value}
1117 resets all entries in the object representation to \var{value}
1118 \end{methoddesc}
1119
1120 \begin{methoddesc}[Operator]{solves}{rhs}
1121 solves the operator equation with right hand side \var{rhs}
1122 \end{methoddesc}
1123
1124 \begin{methoddesc}[Operator]{of}{u}
1125 applies the operator to the \Data object \var{u}
1126 \end{methoddesc}
1127
1128 \begin{methoddesc}[Operator]{saveMM}{fileName}
1129 saves the object to a matrix market format file of name
1130 \var{fileName}, see
1131 \url{http://maths.nist.gov/MatrixMarket}
1132 % \ulink{maths.nist.gov/MatrixMarket}{\url{http://maths.nist.gov/MatrixMarket}}.
1133 \index{Matrix Market}
1134 \end{methoddesc}
1135
1136 \section{Physical Units}
1137 \escript provides support for physical units in the SI system \index{SI units} including unit conversion. So the
1138 user can define variables in the form
1139 \begin{python}
1140 from esys.escript.unitsSI import *
1141 l=20*m
1142 w=30*kg
1143 w2=40*lb
1144 T=100*Celsius
1145 \end{python}
1146 In the two latter cases an conversion from pounds\index{pounds} and degree Celsius\index{Celsius} is performed into the appropriate SI units kg and Kelvin is performed. In addition
1147 composed units can be used, for instance
1148 \begin{python}
1149 from esys.escript.unitsSI import *
1150 rho=40*lb/cm**3
1151 \end{python}
1152 to define the density in the units of pounds per cubic centimeter. The value $40$ will be converted
1153 into SI units, in this case kg per cubic meter.
1154 Moreover unit prefixes are supported:
1155 \begin{python}
1156 from esys.escript.unitsSI import *
1157 p=40*Mega*Pa
1158 \end{python}
1159 to the the pressure to 40 Mega Pascal. Units can also be converted back from the SI system into
1160 a desired unit, e.g
1161 \begin{python}
1162 from esys.escript.unitsSI import *
1163 print p/atm
1164 \end{python}
1165 can be used print the pressure in units of atmosphere\index{atmosphere}.
1166
1167 This is an incomplete list of supported physical units:
1168
1169 \begin{datadesc}{km}
1170 unit of kilo meter
1171 \end{datadesc}
1172
1173 \begin{datadesc}{m}
1174 unit of meter
1175 \end{datadesc}
1176
1177 \begin{datadesc}{cm}
1178 unit of centi meter
1179 \end{datadesc}
1180
1181 \begin{datadesc}{mm}
1182 unit of milli meter
1183 \end{datadesc}
1184
1185 \begin{datadesc}{sec}
1186 unit of second
1187 \end{datadesc}
1188
1189 \begin{datadesc}{minute}
1190 unit of minute
1191 \end{datadesc}
1192
1193 \begin{datadesc}{h}
1194 unit of hour
1195 \end{datadesc}
1196 \begin{datadesc}{day}
1197 unit of day
1198 \end{datadesc}
1199 \begin{datadesc}{yr}
1200 unit of year
1201 \end{datadesc}
1202
1203 \begin{datadesc}{gram}
1204 unit of gram
1205 \end{datadesc}
1206 \begin{datadesc}{kg}
1207 unit of kilo gram
1208 \end{datadesc}
1209 \begin{datadesc}{lb}
1210 unit of pound
1211 \end{datadesc}
1212 \begin{datadesc}{ton}
1213 metric ton
1214 \end{datadesc}
1215
1216 \begin{datadesc}{A}
1217 unit of Ampere
1218 \end{datadesc}
1219
1220 \begin{datadesc}{Hz}
1221 unit of Hertz
1222 \end{datadesc}
1223
1224 \begin{datadesc}{N}
1225 unit of Newton
1226 \end{datadesc}
1227 \begin{datadesc}{Pa}
1228 unit of Pascal
1229 \end{datadesc}
1230 \begin{datadesc}{atm}
1231 unit of atmosphere
1232 \end{datadesc}
1233 \begin{datadesc}{J}
1234 unit of Joule
1235 \end{datadesc}
1236
1237 \begin{datadesc}{W}
1238 unit of Watt
1239 \end{datadesc}
1240
1241 \begin{datadesc}{C}
1242 unit of Coulomb
1243 \end{datadesc}
1244 \begin{datadesc}{V}
1245 unit of Volt
1246 \end{datadesc}
1247 \begin{datadesc}{F}
1248 unit of Farad
1249 \end{datadesc}
1250
1251 \begin{datadesc}{Ohm}
1252 unit of Ohm
1253 \end{datadesc}
1254 \begin{datadesc}{K}
1255 unit of Kelvin
1256 \end{datadesc}
1257 \begin{datadesc}{Celsius}
1258 unit of Celsius
1259 \end{datadesc}
1260
1261 \begin{datadesc}{Fahrenheit}
1262 unit of Fahrenheit
1263 \end{datadesc}
1264
1265 Moreover unit prefixes are supported:
1266
1267 \begin{datadesc}{Yotta}
1268 prefix yotta = $10^{24}$.
1269
1270 \end{datadesc}
1271
1272 \begin{datadesc}{Zetta}
1273 prefix zetta= $10^{21}$.
1274 \end{datadesc}
1275
1276 \begin{datadesc}{Exa}
1277 prefix exa= $10^{18}$.
1278 \end{datadesc}
1279
1280 \begin{datadesc}{Peta}
1281 prefix peta= $10^{15}$.
1282 \end{datadesc}
1283
1284 \begin{datadesc}{Tera}
1285 prefix tera= $10^{12}$.
1286 \end{datadesc}
1287
1288 \begin{datadesc}{Giga}
1289 prefix giga= $10^9$.
1290 \end{datadesc}
1291
1292 \begin{datadesc}{Mega}
1293 prefix mega= $10^6$.
1294 \end{datadesc}
1295
1296 \begin{datadesc}{Kilo}
1297 prefix kilo= $10^3$.
1298 \end{datadesc}
1299
1300 \begin{datadesc}{Hecto}
1301 prefix hecto= $10^2$.
1302 \end{datadesc}
1303
1304 \begin{datadesc}{Deca}
1305 prefix deca= $10^1$.
1306 \end{datadesc}
1307
1308 \begin{datadesc}{Deci}
1309 prefix deci= $10^{-1}$.
1310 \end{datadesc}
1311
1312 \begin{datadesc}{Centi}
1313 prefix centi= $10^{-2}$.
1314 \end{datadesc}
1315
1316 \begin{datadesc}{Milli}
1317 prefix milli= $10^{-3}$.
1318 \end{datadesc}
1319
1320 \begin{datadesc}{Micro}
1321 prefix micro= $10^{-6}$.
1322 \end{datadesc}
1323
1324 \begin{datadesc}{Nano}
1325 prefix nano= $10^{-9}$.
1326 \end{datadesc}
1327
1328 \begin{datadesc}{Pico}
1329 prefix pico= $10^{-12}$.
1330 \end{datadesc}
1331
1332 \begin{datadesc}{Femto}
1333 prefix femto= $10^{-15}$.
1334 \end{datadesc}
1335
1336 \begin{datadesc}{Atto}
1337 prefix atto= $10^{-18}$.
1338 \end{datadesc}
1339
1340 \begin{datadesc}{Zepto}
1341 prefix zepto= $10^{-21}$.
1342 \end{datadesc}
1343
1344 \begin{datadesc}{Yocto}
1345 prefix yocto= $10^{-24}$.
1346 \end{datadesc}
1347
1348
1349 \section{Utilities}
1350
1351 The \class{FileWriter} provides a mechanism to write data to a file.
1352 In essence, this class wraps the standard \class{file} class to write data
1353 that are global in MPI to a file. In fact, data are written on the processor
1354 with \MPI rank 0 only. It is recommended to use \class{FileWriter}
1355 rather than \class{open} in order to write code that is running
1356 with and without \MPI. It is save to use \class{open} under MPI to read data which are global under \MPI.
1357
1358 \begin{classdesc}{FileWriter}{fn\optional{,append=\False, \optional{createLocalFiles=\False}})}
1359 Opens a file of name \var{fn} for writing. If \var{append} is set to \True
1360 written data are append at the end of the file.
1361 If running under \MPI only the first processor with rank==0
1362 will open the file and write to it.
1363 If \var{createLocalFiles} is set each individual processor will create a file
1364 where for any processor with rank>0 the file name is extended by its rank. This option is normally used for debug purposes only.
1365 \end{classdesc}
1366
1367 The following methods are available:
1368 \begin{methoddesc}[FileWriter]{close}{}
1369 closes the file.
1370 \end{methoddesc}
1371 \begin{methoddesc}[FileWriter]{flush}{}
1372 flushes the internal buffer to disk.
1373 \end{methoddesc}
1374 \begin{methoddesc}[FileWriter]{write}{txt}
1375 Write string \var{txt} to file.
1376 Note that newline is not added.
1377 \end{methoddesc}
1378 \begin{methoddesc}[FileWriter]{writelines}{txts}
1379 Write the list \var{txts} of strings to the file..
1380 Note that newlines are not added.
1381 This method is equivalent to call write() for each string.
1382 \end{methoddesc}
1383 \begin{memberdesc}[FileWriter]{closed}
1384 \True if file is closed.
1385 \end{memberdesc}
1386 \begin{memberdesc}[FileWriter]{mode}
1387 access mode.
1388 \end{memberdesc}
1389 \begin{memberdesc}[FileWriter]{name}
1390 file name.
1391 \end{memberdesc}
1392 \begin{memberdesc}[FileWriter]{newlines}
1393 line separator
1394 \end{memberdesc}
1395
1396
1397 \begin{funcdesc}{setEscriptParamInt}{name,value}
1398 assigns the integer value \var{value} to the parameter \var{name}.
1399 If \var{name}="TOO_MANY_LINES" conversion of any \Data object to a string switches to a
1400 condensed format if more than \var{value} lines would be created.
1401 \end{funcdesc}
1402
1403 \begin{funcdesc}{getEscriptParamInt}{name}
1404 returns the current value of integer parameter \var{name}.
1405 \end{funcdesc}
1406
1407 \begin{funcdesc}{listEscriptParams}{a}
1408 returns a list of valid parameters and their description.
1409 \end{funcdesc}
1410
1411 \begin{funcdesc}{getMPISizeWorld}{}
1412 returns the number of \MPI processors in use in the \env{MPI_COMM_WORLD} processor group.
1413 If \MPI is not used 1 is returned.
1414 \end{funcdesc}
1415 \begin{funcdesc}{getMPIRankWorld}{}
1416 returns the rank of the process within the \env{MPI_COMM_WORLD} processor group.
1417 If \MPI is not used 0 is returned.
1418 \end{funcdesc}
1419 \begin{funcdesc}{MPIBarrierWorld}{}
1420 performs a barrier synchronization across all processors within \env{MPI_COMM_WORLD}
1421 processor group.
1422 \end{funcdesc}
1423 \begin{funcdesc}{getMPIWorldMax}{a}
1424 returns the maximum value of the integer \var{a} across all
1425 processors within \env{MPI_COMM_WORLD}.
1426 \end{funcdesc}
1427

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26