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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3296 - (hide annotations)
Fri Oct 22 02:53:24 2010 UTC (11 years, 11 months ago) by caltinay
File MIME type: application/x-tex
File size: 65984 byte(s)
hackscore removal.

1 ksteube 1811
2     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 ksteube 1316 %
4 jfenwick 2881 % Copyright (c) 2003-2010 by University of Queensland
5 ksteube 1811 % Earth Systems Science Computational Center (ESSCC)
6     % http://www.uq.edu.au/esscc
7 gross 625 %
8 ksteube 1811 % 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 gross 625 %
12 ksteube 1811 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13 jgs 82
14 caltinay 3293 \chapter{The \escript Module}\label{ESCRIPT CHAP}
15 ksteube 1811
16 caltinay 3291 \section{Concepts}
17     \escript is a \PYTHON module that allows you to represent the values of
18 ksteube 1318 a function at points in a \Domain in such a way that the function will
19 caltinay 3291 be useful for the Finite Element Method (FEM) simulation. It also
20 ksteube 1318 provides what we call a function space that describes how the data is
21 caltinay 3291 used in the simulation. Stored along with the data is information
22 ksteube 1318 about the elements and nodes which will be used by \finley.
23 jgs 82
24 caltinay 3291 \subsection{Function spaces}
25 jfenwick 1957 In order to understand what we mean by the term 'function space',
26 caltinay 3291 consider that the solution of a partial differential
27     equation\index{partial differential equation} (PDE) is a function on a domain
28 jfenwick 1957 $\Omega$. When solving a PDE using FEM, the solution is
29 caltinay 3291 piecewise-differentiable but, in general, its gradient is discontinuous.
30     To reflect these different degrees of smoothness, different function spaces
31     are used.
32     For instance, in FEM, the displacement field is represented by its values at
33     the nodes of the mesh, and so is continuous.
34     The strain, which is the symmetric part of the gradient of the displacement
35     field, is stored on the element centers, and so is considered to be
36     discontinuous.
37 ksteube 1318
38 caltinay 3291 A function space is described by a \FunctionSpace object.
39     The following statement generates the object \var{solution_space} which is
40 ksteube 1318 a \FunctionSpace object and provides access to the function space of
41 jgs 102 PDE solutions on the \Domain \var{mydomain}:
42 ksteube 1318
43 jgs 102 \begin{python}
44 ksteube 1318 solution_space=Solution(mydomain)
45 jgs 102 \end{python}
46 caltinay 3296 The following generators for function spaces on a \Domain \var{mydomain} are commonly used:
47 jgs 102 \begin{itemize}
48 caltinay 3291 \item \var{Solution(mydomain)}: solutions of a PDE
49     \item \var{ReducedSolution(mydomain)}: solutions of a PDE with a reduced
50     smoothness requirement, e.g. using a lower order approximation on the same
51     element or using macro elements\index{macro elements}
52     \item \var{ContinuousFunction(mydomain)}: continuous functions, e.g. a temperature distribution
53     \item \var{Function(mydomain)}: general functions which are not necessarily continuous, e.g. a stress field
54     \item \var{FunctionOnBoundary(mydomain)}: functions on the boundary of the domain, e.g. a surface pressure
55     \item \var{FunctionOnContact0(mydomain)}: functions on side $0$ of the discontinuity
56     \item \var{FunctionOnContact1(mydomain)}: functions on side $1$ of the discontinuity
57 jgs 102 \end{itemize}
58 gross 2647 In some cases under-integration is used. For these cases the user may use a
59 gross 2864 \FunctionSpace from the following list:
60 gross 2647 \begin{itemize}
61     \item \var{ReducedFunction(mydomain)}
62     \item \var{ReducedFunctionOnBoundary(mydomain)}
63 caltinay 3296 \item \var{ReducedFunctionOnContact0(mydomain)}
64 gross 2647 \item \var{ReducedFunctionOnContact1(mydomain)}
65     \end{itemize}
66 caltinay 3291 In comparison to the corresponding full version they use a reduced number of
67     integration nodes (typically one only) to represent values.
68 ksteube 1318
69 caltinay 3291 \begin{figure}
70     \centering
71     \includegraphics{EscriptDiagram1}
72     \caption{\label{ESCRIPT DEP}Dependency of function spaces in \finley.
73     An arrow indicates that a function in the \FunctionSpace at the starting point
74     can be interpolated to the \FunctionSpace of the arrow target.
75     All function spaces above the dotted line can be interpolated to any of
76     the function spaces below the line. See also \Sec{SEC Projection}.}
77     \end{figure}
78 gross 2647
79 caltinay 3291 The reduced smoothness for a PDE solution is often used to fulfill the
80     Ladyzhenskaya-Babuska-Brezzi condition\cite{LBB} when solving saddle point
81     problems\index{saddle point problems}, e.g. the Stokes equation.
82     A discontinuity\index{discontinuity} is a region within the domain across
83     which functions may be discontinuous.
84     The location of a discontinuity is defined in the \Domain object.
85     \fig{ESCRIPT DEP} shows the dependency between the types of function spaces
86 caltinay 3296 in \finley (other libraries may have different relationships).
87 ksteube 1318
88 caltinay 3291 The solution of a PDE is a continuous function. Any continuous function can
89     be seen as a general function on the domain and can be restricted to the
90     boundary as well as to one side of a discontinuity (the result will be
91     different depending on which side is chosen). Functions on any side of the
92     discontinuity can be seen as a function on the corresponding other side.
93 ksteube 1318
94 caltinay 3291 A function on the boundary or on one side of the discontinuity cannot be seen
95     as a general function on the domain as there are no values defined for the
96     interior. For most PDE solver libraries the space of the solution and
97     continuous functions is identical, however in some cases, for example when
98     periodic boundary conditions are used in \finley, a solution fulfills periodic
99     boundary conditions while a continuous function does not have to be periodic.
100 ksteube 1318
101 caltinay 3291 The concept of function spaces describes the properties of functions and
102     allows abstraction from the actual representation of the function in the
103     context of a particular application. For instance, in the FEM context a
104     function of the \Function type (written as \emph{Function()} in \fig{ESCRIPT DEP})
105     is usually represented by its values at the element center,
106     but in a finite difference scheme the edge midpoint of cells is preferred.
107     By changing its function space you can use the same function in a Finite
108     Difference scheme instead of Finite Element scheme.
109     Changing the function space of a particular function will typically lead to
110 caltinay 3296 a change of its representation.
111 caltinay 3291 So, when seen as a general function, a continuous function which is typically
112     represented by its values on the nodes of the FEM mesh or finite difference
113     grid must be interpolated to the element centers or the cell edges,
114     respectively. Interpolation happens automatically in \escript whenever it is
115     required\index{interpolation}. The user needs to be aware that an
116     interpolation is not always possible, see \fig{ESCRIPT DEP} for \finley.
117 caltinay 3296 An alternative approach to change the representation (=\FunctionSpace) is
118 caltinay 3291 projection\index{projection}, see \Sec{SEC Projection}.
119 jgs 82
120 caltinay 3291 \subsection{\Data objects}
121 ksteube 1318 In \escript the class that stores these functions is called \Data.
122 jgs 102 The function is represented through its values on \DataSamplePoints where
123 caltinay 3291 the \DataSamplePoints are chosen according to the function space of the
124 caltinay 3296 function.
125 caltinay 3291 \Data class objects are used to define the coefficients of the PDEs to be
126     solved by a PDE solver library and also to store the solutions of the PDE.
127 jgs 82
128 caltinay 3291 The values of the function have a rank which gives the number of indices,
129     and a \Shape defining the range of each index.
130     The rank in \escript is limited to the range 0 through 4 and it is assumed
131     that the rank and \Shape is the same for all \DataSamplePoints.
132     The \Shape of a \Data object is a tuple (list) \var{s} of integers.
133     The length of \var{s} is the rank of the \Data object and the \var{i}-th
134     index ranges between 0 and $\var{s[i]}-1$.
135     For instance, a stress field has rank 2 and \Shape $(d,d)$ where $d$ is the
136     spatial dimension.
137     The following statement creates the \Data object \var{mydat} representing a
138     continuous function with values of \Shape $(2,3)$ and rank $2$:
139 jgs 102 \begin{python}
140 caltinay 3291 mydat=Data(value=1, what=ContinuousFunction(myDomain), shape=(2,3))
141 jgs 102 \end{python}
142 caltinay 3291 The initial value is the constant 1 for all \DataSamplePoints and all
143     components.
144 jgs 82
145 caltinay 3291 \Data objects can also be created from any \numpy array or any object, such
146     as a list of floating point numbers, that can be converted into
147 caltinay 3296 a \numpyNDA\cite{NUMPY}.
148 caltinay 3291 The following two statements create objects which are equivalent
149     to \var{mydat}:
150 jgs 102 \begin{python}
151 caltinay 3291 mydat1=Data(value=numpy.ones((2,3)), what=ContinuousFunction(myDomain))
152     mydat2=Data(value=[[1,1], [1,1], [1,1]], what=ContinuousFunction(myDomain))
153 jgs 102 \end{python}
154 caltinay 3291 In the first case the initial value is \var{numpy.ones((2,3))} which generates
155     a $2 \times 3$ matrix as a \numpyNDA filled with ones.
156     The \Shape of the created \Data object is taken from the \Shape of the array.
157     In the second case, the creator converts the initial value, which is a list of
158 caltinay 3296 lists, into a \numpyNDA before creating the actual \Data object.
159 jgs 82
160 jgs 102 For convenience \escript provides creators for the most common types
161 caltinay 3291 of \Data objects in the following forms (\var{d} defines the spatial dimension):
162 jgs 102 \begin{itemize}
163 caltinay 3291 \item \code{Scalar(0, Function(mydomain))} is the same as \code{Data(0, Function(myDomain),(,))}
164     (each value is a scalar), e.g. a temperature field
165     \item \code{Vector(0, Function(mydomain))} is the same as \code{Data(0, Function(myDomain),(d))}
166     (each value is a vector), e.g. a velocity field
167     \item \code{Tensor(0, Function(mydomain))} is the same as \code{Data(0, Function(myDomain), (d,d))},
168     e.g. a stress field
169     \item \code{Tensor4(0,Function(mydomain))} is the same as \code{Data(0,Function(myDomain), (d,d,d,d))}
170     e.g. a Hook tensor field
171 jgs 102 \end{itemize}
172 caltinay 3291 Here the initial value is 0 but any object that can be converted into
173     a \numpyNDA and whose \Shape is consistent with \Shape of the \Data object to
174     be created can be used as the initial value.
175 jgs 82
176 caltinay 3291 \Data objects can be manipulated by applying unary operations (e.g. cos, sin,
177     log), and they can be combined point-wise by applying arithmetic operations
178     (e.g. +, - ,* , /).
179     We emphasize that \escript itself does not handle any spatial dependencies as
180     it does not know how values are interpreted by the processing PDE solver library.
181     However \escript invokes interpolation if this is needed during data manipulations.
182     Typically, this occurs in binary operations when both arguments belong to
183     different function spaces or when data are handed over to a PDE solver library
184     which requires functions to be represented in a particular way.
185 jgs 82
186 caltinay 3291 The following example shows the usage of \Data objects. Assume we have a
187 jgs 102 displacement field $u$ and we want to calculate the corresponding stress field
188 caltinay 3291 $\sigma$ using the linear-elastic isotropic material model
189 jgs 102 \begin{eqnarray}\label{eq: linear elastic stress}
190 caltinay 3296 \sigma_{ij}=\lambda u_{k,k} \delta_{ij} + \mu ( u_{i,j} + u_{j,i})
191 jgs 102 \end{eqnarray}
192 caltinay 3296 where $\delta_{ij}$ is the Kronecker symbol and
193 jgs 102 $\lambda$ and $\mu$ are the Lame coefficients. The following function
194 caltinay 3291 takes the displacement \var{u} and the Lame coefficients \var{lam} and \var{mu}
195     as arguments and returns the corresponding stress:
196 jgs 102 \begin{python}
197 ksteube 1318 from esys.escript import *
198 caltinay 3291 def getStress(u, lam, mu):
199 ksteube 1318 d=u.getDomain().getDim()
200     g=grad(u)
201     stress=lam*trace(g)*kronecker(d)+mu*(g+transpose(g))
202 caltinay 3291 return stress
203 jgs 102 \end{python}
204 caltinay 3291 The variable \var{d} gives the spatial dimension of the domain on which the
205     displacements are defined.
206     \var{kronecker} returns the Kronecker symbol with indexes $i$ and $j$ running
207     from 0 to \var{d}-1.
208     The call \var{grad(u)} requires the displacement field \var{u} to be in
209     the \var{Solution} or \ContinuousFunction.
210 caltinay 3296 The result \var{g} as well as the returned stress will be in the \Function.
211 caltinay 3291 If, for example, \var{u} is the solution of a PDE then \code{getStress} might
212     be called in the following way:
213 jgs 102 \begin{python}
214 caltinay 3291 s=getStress(u, 1., 2.)
215 jgs 102 \end{python}
216 caltinay 3291 However \code{getStress} can also be called with \Data objects as values for
217     \var{lam} and \var{mu} which, for instance in the case of a temperature
218     dependency, are calculated by an expression.
219 jgs 102 The following call is equivalent to the previous example:
220     \begin{python}
221 caltinay 3291 lam=Scalar(1., ContinuousFunction(mydomain))
222     mu=Scalar(2., Function(mydomain))
223     s=getStress(u, lam, mu)
224 jgs 102 \end{python}
225 ksteube 1318
226 caltinay 3291 The function \var{lam} belongs to the \ContinuousFunction but with \var{g} the
227     function \var{trace(g)} is in the \Function.
228 ksteube 1318 In the evaluation of the product \var{lam*trace(g)} we have different function
229     spaces (on the nodes versus in the centers) and at first glance we have incompatible data.
230 caltinay 3291 \escript converts the arguments into an appropriate function space according
231     to \fig{ESCRIPT DEP}.
232     In this example that means \escript sees \var{lam} as a function of the \Function.
233     In the context of FEM this means the nodal values of \var{lam} are
234     interpolated to the element centers.
235 ksteube 1318 The interpolation is automatic and requires no special handling.
236 jgs 82
237 jgs 102 \begin{figure}
238 caltinay 3291 \centering
239     \includegraphics{EscriptDiagram2}
240     \caption{\label{Figure: tag}Element Tagging. A rectangular mesh over a region
241     with two rock types {\it white} and {\it gray} is shown.
242     The number in each cell refers to the major rock type present in the cell
243     ($1$ for {\it white} and $2$ for {\it gray}).}
244 jgs 102 \end{figure}
245 jgs 82
246 caltinay 3291 \subsection{Tagged, Expanded and Constant Data}
247     Material parameters such as the Lame coefficients are typically dependent on
248     rock types present in the area of interest.
249     A common technique to handle these kinds of material parameters is
250     \emph{tagging}\index{tagging}, which uses storage efficiently.
251     \fig{Figure: tag} shows an example. In this case two rock types {\it white}
252     and {\it gray} can be found in the domain.
253     The domain is subdivided into triangular shaped cells.
254     Each cell has a tag indicating the rock type predominantly found in this cell.
255     Here $1$ is used to indicate rock type {\it white} and $2$ for rock type {\it gray}.
256     The tags are assigned at the time when the cells are generated and stored in
257     the \Domain class object. To allow easier usage of tags, names can be used
258     instead of numbers. These names are typically defined at the time when the
259     geometry is generated.
260 gross 1044
261 caltinay 3291 The following statements show how to use tagged values for \var{lam} as shown
262     in \fig{Figure: tag} for the stress calculation discussed above:
263 jgs 102 \begin{python}
264 caltinay 3291 lam=Scalar(value=2., what=Function(mydomain))
265     insertTaggedValue(lam, white=30., gray=5000.)
266     s=getStress(u, lam, 2.)
267 jgs 102 \end{python}
268 caltinay 3291 In this example \var{lam} is set to $30$ for those cells with tag {\it white}
269     (=$1$) and to $5000$ for cells with tag {\it gray} (=$2$).
270     The initial value $2$ of \var{lam} is used as a default value for the case
271     when a tag is encountered which has not been linked with a value.
272     The \code{getStress} method does not need to be changed now that we are using tags.
273 ksteube 1318 \escript resolves the tags when \var{lam*trace(g)} is calculated.
274 jgs 82
275 ksteube 1318 This brings us to a very important point about \escript.
276 caltinay 3291 You can develop a simulation with constant Lame coefficients, and then later
277     switch to tagged Lame coefficients without otherwise changing your python script.
278     In short, you can use the same script for models with different domains and
279     different types of input data.
280 ksteube 1318
281 caltinay 3291 There are three main ways in which \Data objects are represented internally --
282     constant, tagged, and expanded.
283     In the constant case, the same value is used at each sample point while only a
284     single value is stored to save memory.
285 ksteube 1318 In the expanded case, each sample point has an individual value (such as for the solution of a PDE).
286 caltinay 3291 This is where your largest data sets will be created because the values are
287     stored as a complete array.
288 ksteube 1318 The tagged case has already been discussed above.
289    
290 caltinay 3291 Expanded data is created when you create a \Data object with \code{expanded=True}.
291     Tagged data sets are created when you use the \member{insertTaggedValue}
292     method as shown above.
293 caltinay 3296
294 caltinay 3291 Values are accessed through a sample reference number.
295     Operations on expanded \Data objects have to be performed for each sample
296     point individually.
297     When tagged values are used, the values are held in a dictionary.
298     Operations on tagged data require processing the set of tagged values only,
299     rather than processing the value for each individual sample point.
300 ksteube 1318 \escript allows any mixture of constant, tagged and expanded data in a single expression.
301 jgs 82
302 caltinay 3291 \subsection{Saving and Restoring Simulation Data}
303     \Data objects can be written to disk files with the \member{dump} method and
304     read back using the \member{load} method, both of which use the
305     \netCDF\cite{NETCDF} file format.
306     Use these to save data for checkpoint/restart or simply to save and reuse data
307     that was expensive to compute.
308 ksteube 1318
309 caltinay 3291 For instance, to save the coordinates of the data points of a
310     \ContinuousFunction to the file \file{x.nc} use
311 gross 983 \begin{python}
312 ksteube 1318 x=ContinuousFunction(mydomain).getX()
313     x.dump("x.nc")
314 caltinay 3291 mydomain.dump("dom.nc")
315 gross 983 \end{python}
316 caltinay 3291 To recover the object \var{x}, and \var{mydomain} was a \finley mesh use
317 gross 983 \begin{python}
318 gross 2417 from esys.finley import LoadMesh
319 caltinay 3291 mydomain=LoadMesh("dom.nc")
320 ksteube 1318 x=load("x.nc", mydomain)
321 gross 983 \end{python}
322 caltinay 3291 Obviously, it is possible to execute the same steps that were originally used
323     to generate \var{mydomain} to recreate it. However, in most cases using
324     \member{dump} and \member{load} is faster, particularly if optimization has
325     been applied.
326     If \escript is running on more than one \MPI process \member{dump} will create
327     an individual file for each process containing the local data.
328     In order to avoid conflicts the file names are extended by the \MPI processor
329     rank, that is instead of one file \file{dom.nc} you would get
330     \file{dom.nc.0000}, \file{dom.nc.0001}, etc. You still call
331     \code{LoadMesh('dom.nc')} to load the domain but you have to make sure that
332     the appropriate file is accessible from the corresponding rank, and loading
333     will only succeed if you run with as many processes as were used when calling
334     \member{dump}.
335 ksteube 1318
336 caltinay 3291 The function space of the \Data is stored in \file{x.nc}.
337     If the \Data object is expanded, the number of data points in the file and of
338     the \Domain for the particular \FunctionSpace must match.
339     Moreover, the ordering of the values is checked using the reference
340     identifiers provided by \FunctionSpace on the \Domain.
341     In some cases, data points will be reordered so be aware and confirm that you
342     get what you wanted.
343 gross 983
344 caltinay 3291 A newer, more flexible way of saving and restoring \escript simulation data
345     is through a \class{DataManager} class object.
346     It has the advantage of allowing to save and load not only a \Domain and
347     \Data objects but also other values\footnote{The \PYTHON \emph{pickle} module
348     is used for other types.} you compute in your simulation script.
349     Further, \class{DataManager} objects can simultaneously create files for
350     visualization so no extra calls to, e.g. \code{saveVTK} are needed.
351 gross 983
352 caltinay 3291 The following example shows how the \class{DataManager} class can be used.
353     For an explanation of all member functions and options see the relevant
354     reference section.
355     \begin{python}
356     from esys.escript import DataManager, Scalar, Function
357     from esys.finley import Rectangle
358    
359     dm = DataManager(formats=[DataManager.RESTART, DataManager.VTK])
360     if dm.hasData():
361     mydomain=dm.getDomain()
362     val=dm.getValue("val")
363     t=dm.getValue("t")
364     t_max=dm.getValue("t_max")
365     else:
366     mydomain=Rectangle()
367     val=Function(mydomain).getX()
368     t=0.
369     t_max=2.5
370    
371     while t<t_max:
372     t+=.01
373     val=val+t/2
374     dm.addData(val=val, t=t, t_max=t_max)
375     dm.export()
376     \end{python}
377     In the constructor we specify that we want \code{RESTART} (i.e. dump) files
378     and \code{VTK} files to be saved.
379     By default, the constructor will look for previously saved \code{RESTART}
380     files under the current directory and load them.
381     We can then enquire if such files were found by calling the \member{hasData}
382     method. If it returns \True we retrieve the domain and values into local
383     variables. Otherwise the same variables are initialized with appropriate
384     values to start a new simulation.
385     Note, that \var{t} and \var{t_max} are regular floating point values and not
386     \Data objects but are treated the same way by the \class{DataManager}.
387    
388     After this initialization step the script enters the main simulation loop
389     where calculations are performed.
390     When these are finalized for a time step we call the \member{addData} method
391     to let the manager know which variables to store on disk.
392     Note, that this does not actually save the data yet and it is allowed to call
393     \member{addData} more than once to add information incrementally, e.g. from
394     separate functions that have access to the \class{DataManager} instance.
395     Once all variables have been added the \member{export} method has to be called
396     to flush all data to disk and clear the manager.
397     In this example, this call dumps \var{mydomain} and \var{val} to files
398     in a restart directory and also stores \var{t} and \var{t_max} on disk.
399     Additionally, it generates a \VTK file for visualization of the data.
400    
401 gross 999 \section{\escript Classes}
402    
403 caltinay 3296 \subsection{The \Domain class}
404 jgs 102 \begin{classdesc}{Domain}{}
405 caltinay 3291 A \Domain object is used to describe a geometric region together with
406 jgs 102 a way of representing functions over this region.
407 jfenwick 1959 The \Domain class provides an abstract interface to the domain of \FunctionSpace and \Data objects.
408     \Domain needs to be subclassed in order to provide a complete implementation.
409 jgs 82 \end{classdesc}
410 ksteube 1316 The following methods are available:
411 jgs 102 \begin{methoddesc}[Domain]{getDim}{}
412     returns the spatial dimension of the \Domain.
413     \end{methoddesc}
414 gross 2417 \begin{methoddesc}[Domain]{dump}{filename}
415     dumps the \Domain into the file \var{filename}.
416     \end{methoddesc}
417 jgs 102 \begin{methoddesc}[Domain]{getX}{}
418     returns the locations in the \Domain. The \FunctionSpace of the returned
419     \Data object is chosen by the \Domain implementation. Typically it will be
420     in the \Function.
421     \end{methoddesc}
422    
423     \begin{methoddesc}[Domain]{setX}{newX}
424     assigns a new location to the \Domain. \var{newX} has to have \Shape $(d,)$
425     where $d$ is the spatial dimension of the domain. Typically \var{newX} must be
426     in the \ContinuousFunction but the space actually to be used depends on the \Domain implementation.
427     \end{methoddesc}
428    
429     \begin{methoddesc}[Domain]{getNormal}{}
430     returns the surface normals on the boundary of the \Domain as \Data object.
431     \end{methoddesc}
432    
433     \begin{methoddesc}[Domain]{getSize}{}
434     returns the local sample size, e.g. the element diameter, as \Data object.
435     \end{methoddesc}
436    
437 gross 1044 \begin{methoddesc}[Domain]{setTagMap}{tag_name, tag}
438 caltinay 3296 defines a mapping of the tag name \var{tag_name} to the \var{tag}.
439 gross 1044 \end{methoddesc}
440     \begin{methoddesc}[Domain]{getTag}{tag_name}
441     returns the tag associated with the tag name \var{tag_name}.
442     \end{methoddesc}
443     \begin{methoddesc}[Domain]{isValidTagName}{tag_name}
444     return \True if \var{tag_name} is a valid tag name.
445     \end{methoddesc}
446    
447 jgs 102 \begin{methoddesc}[Domain]{__eq__}{arg}
448 jfenwick 1959 (python == operator) returns \True if the \Domain \var{arg} describes the same domain. Otherwise
449 jgs 102 \False is returned.
450     \end{methoddesc}
451    
452     \begin{methoddesc}[Domain]{__ne__}{arg}
453 caltinay 3296 (python != operator) returns \True if the \Domain \var{arg} does not describe the same domain.
454 jgs 102 Otherwise \False is returned.
455     \end{methoddesc}
456    
457 jfenwick 1966 \begin{methoddesc}[Domain]{__str__}{arg}
458 jfenwick 1959 (python str() function) returns string representation of the \Domain.
459 gross 593 \end{methoddesc}
460    
461 gross 2318 \begin{methoddesc}[Domain]{onMasterProcessor)}{}
462 caltinay 3296 returns \True if the processor is the master processor within
463 gross 2318 the \MPI processor group used by the \Domain. This is the processor with rank 0.
464     If \MPI support is not enabled the return value is always \True.
465 jfenwick 1966 \end{methoddesc}
466    
467 gross 2318 \begin{methoddesc}[Domain]{getMPISize}{}
468     returns the number of \MPI processors used for this \Domain. If \MPI support is not enabled
469     1 is returned.
470 jfenwick 1966 \end{methoddesc}
471    
472 gross 2318 \begin{methoddesc}[Domain]{getMPIRank}{}
473 caltinay 3296 returns the rank of the processor executing the statement
474     within the \MPI processor group used by the \Domain.
475 gross 2318 If \MPI support is not enabled 0 is returned.
476 jfenwick 1966 \end{methoddesc}
477    
478 gross 2318 \begin{methoddesc}[Domain]{MPIBarrier}{}
479 caltinay 3296 executes barrier synchronization within
480 gross 2318 the \MPI processor group used by the \Domain.
481 caltinay 3296 If \MPI support is not enabled, this command does nothing.
482 jfenwick 1966 \end{methoddesc}
483    
484 caltinay 3296 \subsection{The \FunctionSpace class}
485 jgs 102 \begin{classdesc}{FunctionSpace}{}
486     \FunctionSpace objects are used to define properties of \Data objects, such as continuity. \FunctionSpace objects
487 caltinay 3296 are instantiated by generator functions. A \Data object in a particular \FunctionSpace is
488 jfenwick 1966 represented by its values at \DataSamplePoints which are defined by the type and the \Domain of the
489 jgs 102 \FunctionSpace.
490 jgs 82 \end{classdesc}
491 gross 1044 The following methods are available:
492 jgs 102 \begin{methoddesc}[FunctionSpace]{getDim}{}
493     returns the spatial dimension of the \Domain of the \FunctionSpace.
494     \end{methoddesc}
495 jgs 82
496 gross 1044
497    
498 jgs 102 \begin{methoddesc}[FunctionSpace]{getX}{}
499     returns the location of the \DataSamplePoints.
500     \end{methoddesc}
501 jgs 82
502 jgs 102 \begin{methoddesc}[FunctionSpace]{getNormal}{}
503 caltinay 3296 If the domain of functions in the \FunctionSpace
504 gross 2404 is a hyper-manifold (e.g. the boundary of a domain)
505 caltinay 3296 the method returns the outer normal at each of the
506 jgs 102 \DataSamplePoints. Otherwise an exception is raised.
507     \end{methoddesc}
508 jgs 82
509 jgs 102 \begin{methoddesc}[FunctionSpace]{getSize}{}
510 caltinay 3296 returns a \Data objects measuring the spacing of the \DataSamplePoints.
511 jgs 102 The size may be zero.
512     \end{methoddesc}
513 jgs 82
514 jgs 102 \begin{methoddesc}[FunctionSpace]{getDomain}{}
515     returns the \Domain of the \FunctionSpace.
516     \end{methoddesc}
517 jgs 82
518 gross 1044 \begin{methoddesc}[FunctionSpace]{setTags}{new_tag, mask}
519 caltinay 3296 assigns a new tag \var{new_tag} to all data sample
520     where \var{mask} is positive for a least one data point.
521 gross 1044 \var{mask} must be defined on the this \FunctionSpace.
522 ksteube 1316 Use the \var{setTagMap} to assign a tag name to \var{new_tag}.
523 gross 1044 \end{methoddesc}
524    
525 jgs 102 \begin{methoddesc}[FunctionSpace]{__eq__}{arg}
526 jfenwick 1959 (python == operator) returns \True if the \Domain \var{arg} describes the same domain. Otherwise
527 jgs 102 \False is returned.
528     \end{methoddesc}
529 jgs 82
530 jgs 102 \begin{methoddesc}[FunctionSpace]{__ne__}{arg}
531 caltinay 3296 (python != operator) returns \True if the \Domain \var{arg} do not describe the same domain.
532 jgs 102 Otherwise \False is returned.
533     \end{methoddesc}
534 jgs 82
535 gross 593 \begin{methoddesc}[Domain]{__str__}{g}
536 jfenwick 1959 (python str() function) returns string representation of the \Domain.
537 gross 593 \end{methoddesc}
538    
539 jgs 102 The following function provide generators for \FunctionSpace objects:
540     \begin{funcdesc}{Function}{domain}
541     returns the \Function on the \Domain \var{domain}. \Data objects in this type of \Function
542 caltinay 3296 are defined over the whole geometric region defined by \var{domain}.
543 jgs 82 \end{funcdesc}
544    
545 jgs 102 \begin{funcdesc}{ContinuousFunction}{domain}
546     returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function
547 jfenwick 1957 are defined over the whole geometric region defined by \var{domain} and assumed to represent
548 jgs 102 a continuous function.
549 jgs 82 \end{funcdesc}
550    
551 jgs 102 \begin{funcdesc}{FunctionOnBoundary}{domain}
552     returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function
553 caltinay 3296 are defined on the boundary of the geometric region defined by \var{domain}.
554 jgs 82 \end{funcdesc}
555    
556 jgs 102 \begin{funcdesc}{FunctionOnContactZero}{domain}
557     returns the \FunctionOnContactZero the \Domain domain. \Data objects in this type of \Function
558 jfenwick 1957 are defined on side 0 of a discontinuity within the geometric region defined by \var{domain}.
559 ksteube 1316 The discontinuity is defined when \var{domain} is instantiated.
560 jgs 82 \end{funcdesc}
561    
562 jgs 102 \begin{funcdesc}{FunctionOnContactOne}{domain}
563 caltinay 3296 returns the \FunctionOnContactOne on the \Domain domain.
564 jgs 102 \Data objects in this type of \Function
565 jfenwick 1957 are defined on side 1 of a discontinuity within the geometric region defined by \var{domain}.
566 ksteube 1316 The discontinuity is defined when \var{domain} is instantiated.
567 jgs 82 \end{funcdesc}
568    
569 jgs 102 \begin{funcdesc}{Solution}{domain}
570     returns the \SolutionFS on the \Domain domain. \Data objects in this type of \Function
571 jfenwick 1957 are defined on geometric region defined by \var{domain} and are solutions of
572 caltinay 3296 partial differential equations \index{partial differential equation}.
573 jgs 82 \end{funcdesc}
574    
575 jgs 102 \begin{funcdesc}{ReducedSolution}{domain}
576     returns the \ReducedSolutionFS on the \Domain domain. \Data objects in this type of \Function
577 jfenwick 1957 are defined on geometric region defined by \var{domain} and are solutions of
578 caltinay 3296 partial differential equations \index{partial differential equation} with a reduced smoothness
579 jgs 102 for the solution approximation.
580 jgs 82 \end{funcdesc}
581    
582 caltinay 3296 \subsection{The \Data Class}
583 jgs 107 \label{SEC ESCRIPT DATA}
584 jgs 82
585 ksteube 1318 The following table shows arithmetic operations that can be performed point-wise on
586     \Data objects.
587 caltinay 3293 \begin{table}
588     \centering
589     \begin{tabular}{l|l}
590     \bfseries expression & Description\\
591     \hline
592     +\var{arg0} & identical to \var{arg} \index{+}\\
593     -\var{arg0} & negation\index{-}\\
594     \var{arg0}+\var{arg1} & adds \var{arg0} and \var{arg1} \index{+}\\
595     \var{arg0}*\var{arg1} & multiplies \var{arg0} and \var{arg1} \index{*}\\
596     \var{arg0}-\var{arg1} & difference \var{arg1} from\var{arg1} \index{-}\\
597     \var{arg0}/\var{arg1} & divide \var{arg0} by \var{arg1} \index{/}\\
598     \var{arg0}**\var{arg1} & raises \var{arg0} to the power of \var{arg1} \index{**}\\
599     \end{tabular}
600     \end{table}
601 gross 625 At least one of the arguments \var{arg0} or \var{arg1} must be a
602 ksteube 1318 \Data object.
603 gross 2484 Either of the arguments may be a \Data object, a python number or a \numpy object.
604 ksteube 1318
605     If \var{arg0} or \var{arg1} are
606 jfenwick 1959 not defined on the same \FunctionSpace, then an attempt is made to convert \var{arg0}
607 ksteube 1318 to the \FunctionSpace of \var{arg1} or to convert \var{arg1} to
608 ksteube 1316 the \FunctionSpace of \var{arg0}. Both arguments must have the same
609 ksteube 1318 \Shape or one of the arguments may be of rank 0 (a constant).
610 jgs 82
611 jgs 102 The returned \Data object has the same \Shape and is defined on
612 gross 625 the \DataSamplePoints as \var{arg0} or \var{arg1}.
613 jgs 82
614 jgs 102 The following table shows the update operations that can be applied to
615     \Data objects:
616 caltinay 3293 \begin{table}
617     \centering
618     \begin{tabular}{l|l}
619     \bfseries Expression & Description\\
620     \hline
621     \var{arg0}+=\var{arg2} & adds \var{arg0} to \var{arg2}\index{+}\\
622     \var{arg0}*=\var{arg2} & multiplies \var{arg0} with \var{arg2}\index{*}\\
623     \var{arg0}-=\var{arg2} & subtracts \var{arg2} from\var{arg2}\index{-}\\
624     \var{arg0}/=\var{arg2} & divides \var{arg0} by \var{arg2}\index{/}\\
625     \var{arg0}**=\var{arg2} & raises \var{arg0} by \var{arg2}\index{**}\\
626     \end{tabular}
627     \end{table}
628 gross 625 \var{arg0} must be a \Data object. \var{arg1} must be a
629 jgs 102 \Data object or an object that can be converted into a
630 jfenwick 1959 \Data object. \var{arg1} must have the same \Shape as
631     \var{arg0} or have rank 0. In the latter case it is
632 jgs 102 assumed that the values of \var{arg1} are constant for all
633 gross 625 components. \var{arg1} must be defined in the same \FunctionSpace as
634     \var{arg0} or it must be possible to interpolate \var{arg1} onto the
635 jfenwick 1959 \FunctionSpace of \var{arg0}.
636 jgs 82
637 ksteube 1318 The \Data class supports taking slices from a \Data object as well as assigning new values to a slice of an existing
638 jgs 107 \Data object. \index{slicing}
639 ksteube 1318 The following expressions for taking and setting slices are valid:
640 caltinay 3293 \begin{table}
641     \centering
642     \begin{tabular}{l|ll}
643     \bfseries rank of \var{arg} & slicing expression & \Shape of returned and assigned object\\
644     \hline
645     0 & no slicing & -\\
646     1 & \var{arg[l0:u0]} & (\var{u0}-\var{l0},)\\
647     2 & \var{arg[l0:u0,l1:u1]} & (\var{u0}-\var{l0},\var{u1}-\var{l1})\\
648     3 & \var{arg[l0:u0,l1:u1,l2:u2]} & (\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2})\\
649     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})\\
650     \end{tabular}
651     \end{table}
652 caltinay 3296 where \var{s} is the \Shape of \var{arg} and
653 jfenwick 1959 \[0 \le \var{l0} \le \var{u0} \le \var{s[0]},\]
654 caltinay 3296 \[0 \le \var{l1} \le \var{u1} \le \var{s[1]},\]
655     \[0 \le \var{l2} \le \var{u2} \le \var{s[2]},\]
656 jfenwick 1959 \[0 \le \var{l3} \le \var{u3} \le \var{s[3]}.\]
657 caltinay 3296 Any of the lower indexes \var{l0}, \var{l1}, \var{l2} and \var{l3} may not be present in which case
658     $0$ is assumed.
659     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.
660 jfenwick 1959 The lower and upper index may be identical, in which case the column and the lower or upper
661     index may be dropped. In the returned or in the object assigned to a slice, the corresponding component is dropped,
662 jgs 102 i.e. the rank is reduced by one in comparison to \var{arg}.
663 ksteube 1318 The following examples show slicing in action:
664 jgs 102 \begin{python}
665 ksteube 1318 t=Data(1.,(4,4,6,6),Function(mydomain))
666     t[1,1,1,0]=9.
667     s=t[:2,:,2:6,5] # s has rank 3
668     s[:,:,1]=1.
669     t[:2,:2,5,5]=s[2:4,1,:2]
670 jgs 102 \end{python}
671    
672 jfenwick 1959 \subsection{Generation of \Data objects}
673 gross 593 \begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expand=\False}
674 jgs 102 creates a \Data object with \Shape \var{shape} in the \FunctionSpace \var{what}.
675     The values at all \DataSamplePoints are set to the double value \var{value}. If \var{expanded} is \True
676     the \Data object is represented in expanded from.
677 jgs 82 \end{classdesc}
678    
679 gross 593 \begin{classdesc}{Data}{value,what=FunctionSpace(),expand=\False}
680 caltinay 3296 creates a \Data object in the \FunctionSpace \var{what}.
681     The value for each \DataSamplePoints is set to \var{value}, which could be a \numpy, \Data object \var{value} or a dictionary of
682 gross 2484 \numpy or floating point numbers. In the latter case the keys must be integers and are used
683 gross 593 as tags.
684 jgs 102 The \Shape of the returned object is equal to the \Shape of \var{value}. If \var{expanded} is \True
685 ksteube 1318 the \Data object is represented in expanded form.
686 jgs 102 \end{classdesc}
687    
688     \begin{classdesc}{Data}{}
689     creates an \EmptyData object. The \EmptyData object is used to indicate that an argument is not present
690     where a \Data object is required.
691     \end{classdesc}
692    
693 jfenwick 1959 \begin{funcdesc}{Scalar}{value=0.,what=FunctionSpace(),expand=\False}
694 ksteube 1318 returns a \Data object of rank 0 (a constant) in the \FunctionSpace \var{what}.
695 gross 2404 Values are initialized with \var{value}, a double precision quantity. If \var{expanded} is \True
696 gross 593 the \Data object is represented in expanded from.
697     \end{funcdesc}
698    
699 jfenwick 1959 \begin{funcdesc}{Vector}{value=0.,what=FunctionSpace(),expand=\False}
700     returns a \Data object of \Shape \var{(d,)} in the \FunctionSpace \var{what},
701 gross 593 where \var{d} is the spatial dimension of the \Domain of \var{what}.
702 ksteube 1318 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
703 gross 593 the \Data object is represented in expanded from.
704     \end{funcdesc}
705    
706 jfenwick 1959 \begin{funcdesc}{Tensor}{value=0.,what=FunctionSpace(),expand=\False}
707     returns a \Data object of \Shape \var{(d,d)} in the \FunctionSpace \var{what},
708 gross 593 where \var{d} is the spatial dimension of the \Domain of \var{what}.
709 ksteube 1318 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
710 gross 593 the \Data object is represented in expanded from.
711     \end{funcdesc}
712    
713 jfenwick 1959 \begin{funcdesc}{Tensor3}{value=0.,what=FunctionSpace(),expand=\False}
714     returns a \Data object of \Shape \var{(d,d,d)} in the \FunctionSpace \var{what},
715 gross 593 where \var{d} is the spatial dimension of the \Domain of \var{what}.
716 ksteube 1318 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
717 gross 593 the \Data object is re\var{arg}presented in expanded from.
718     \end{funcdesc}
719    
720 jfenwick 1959 \begin{funcdesc}{Tensor4}{value=0.,what=FunctionSpace(),expand=\False}
721     returns a \Data object of \Shape \var{(d,d,d,d)} in the \FunctionSpace \var{what},
722 gross 593 where \var{d} is the spatial dimension of the \Domain of \var{what}.
723 gross 2404 Values are initialized with \var{value}, a double precision quantity. If \var{expanded} is \True
724 gross 593 the \Data object is represented in expanded from.
725     \end{funcdesc}
726    
727 gross 983 \begin{funcdesc}{load}{filename,domain}
728 gross 2316 recovers a \Data object on \Domain \var{domain} from the file \var{filename}, which was created by \function{dump}.
729 gross 983 \end{funcdesc}
730    
731 jfenwick 1959 \subsection{\Data methods}
732 caltinay 3296 These are the most frequently-used methods of the
733 ksteube 1318 \Data class. A complete list of methods can be found on \ReferenceGuide.
734 jgs 102 \begin{methoddesc}[Data]{getFunctionSpace}{}
735     returns the \FunctionSpace of the object.
736 jgs 82 \end{methoddesc}
737    
738 gross 593 \begin{methoddesc}[Data]{getDomain}{}
739 jgs 102 returns the \Domain of the object.
740     \end{methoddesc}
741    
742 jgs 82 \begin{methoddesc}[Data]{getShape}{}
743 jgs 102 returns the \Shape of the object as a \class{tuple} of
744     integers.
745 jgs 82 \end{methoddesc}
746    
747     \begin{methoddesc}[Data]{getRank}{}
748     returns the rank of the data on each data point. \index{rank}
749     \end{methoddesc}
750    
751 jgs 102 \begin{methoddesc}[Data]{isEmpty}{}
752     returns \True id the \Data object is the \EmptyData object.
753     Otherwise \False is returned.
754 jfenwick 1959 Note that this is not the same as asking if the object contains no \DataSamplePoints.
755 jgs 82 \end{methoddesc}
756    
757 gross 1044 \begin{methoddesc}[Data]{setTaggedValue}{tag_name,value}
758 jgs 102 assigns the \var{value} to all \DataSamplePoints which have the tag
759 gross 1044 assigned to \var{tag_name}. \var{value} must be an object of class
760 gross 2484 \class{numpy.ndarray} or must be convertible into a
761     \class{numpy.ndarray} object. \var{value} (or the corresponding
762     \class{numpy.ndarray} object) must be of rank $0$ or must have the
763 jgs 102 same rank like the object.
764 gross 1044 If a value has already be defined for tag \var{tag_name} within the object
765 jgs 102 it is overwritten by the new \var{value}. If the object is expanded,
766 gross 1044 the value assigned to \DataSamplePoints with tag \var{tag_name} is replaced by
767 gross 1045 \var{value}. If no tag is assigned tag name \var{tag_name}, no value is set.
768 jgs 82 \end{methoddesc}
769    
770 gross 983 \begin{methoddesc}[Data]{dump}{filename}
771     dumps the \Data object to the file \var{filename}. The file stores the
772 ksteube 1316 function space but not the \Domain. It is in the responsibility of the user to
773 caltinay 3296 save the \Domain.
774 gross 983 \end{methoddesc}
775    
776 gross 593 \begin{methoddesc}[Data]{__str__}{}
777     returns a string representation of the object.
778     \end{methoddesc}
779    
780 jfenwick 1959 \subsection{Functions of \Data objects}
781 gross 593 This section lists the most important functions for \Data class objects \var{a}.
782 jfenwick 1959 A complete list and a more detailed description of the functionality can be found on \ReferenceGuide.
783 gross 599 \begin{funcdesc}{saveVTK}{filename,**kwdata}
784 caltinay 3296 writes \Data defined by keywords in the file with \var{filename} using the
785 gross 599 vtk file format \VTK file format. The key word is used as an identifier. The statement
786     \begin{python}
787 ksteube 1318 saveVTK("out.xml",temperature=T,velocity=v)
788 caltinay 3296 \end{python}
789     will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the
790 gross 599 file \file{out.xml}. Restrictions on the allowed combinations of \FunctionSpace apply.
791 gross 593 \end{funcdesc}
792 gross 599 \begin{funcdesc}{saveDX}{filename,**kwdata}
793 caltinay 3296 writes \Data defined by keywords in the file with \var{filename} using the
794 gross 599 vtk file format \OpenDX file format. The key word is used as an identifier. The statement
795     \begin{python}
796 ksteube 1318 saveDX("out.dx",temperature=T,velocity=v)
797 caltinay 3296 \end{python}
798     will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the
799 gross 599 file \file{out.dx}. Restrictions on the allowed combinations of \FunctionSpace apply.
800 gross 593 \end{funcdesc}
801     \begin{funcdesc}{kronecker}{d}
802 gross 599 returns a \RankTwo \Data object in \FunctionSpace \var{d} such that
803 gross 593 \begin{equation}
804 caltinay 3296 \code{kronecker(d)}\left[ i,j\right] = \left\{
805 gross 593 \begin{array}{cc}
806     1 & \mbox{ if } i=j \\
807     0 & \mbox{ otherwise }
808     \end{array}
809     \right.
810     \end{equation}
811 gross 2484 If \var{d} is an integer a $(d,d)$ \numpy array is returned.
812 gross 593 \end{funcdesc}
813     \begin{funcdesc}{identityTensor}{d}
814 jfenwick 1959 is a synonym for \code{kronecker} (see above).
815     % returns a \RankTwo \Data object in \FunctionSpace \var{d} such that
816     % \begin{equation}
817 caltinay 3296 % \code{identityTensor(d)}\left[ i,j\right] = \left\{
818 jfenwick 1959 % \begin{array}{cc}
819     % 1 & \mbox{ if } i=j \\
820     % 0 & \mbox{ otherwise }
821     % \end{array}
822     % \right.
823     % \end{equation}
824 gross 2484 % If \var{d} is an integer a $(d,d)$ \numpy array is returned.
825 gross 593 \end{funcdesc}
826     \begin{funcdesc}{identityTensor4}{d}
827 gross 599 returns a \RankFour \Data object in \FunctionSpace \var{d} such that
828     \begin{equation}
829 caltinay 3296 \code{identityTensor(d)}\left[ i,j,k,l\right] = \left\{
830 gross 599 \begin{array}{cc}
831     1 & \mbox{ if } i=k \mbox{ and } j=l\\
832     0 & \mbox{ otherwise }
833     \end{array}
834     \right.
835     \end{equation}
836 gross 2484 If \var{d} is an integer a $(d,d,d,d)$ \numpy array is returned.
837 gross 593 \end{funcdesc}
838     \begin{funcdesc}{unitVector}{i,d}
839 gross 599 returns a \RankOne \Data object in \FunctionSpace \var{d} such that
840     \begin{equation}
841 caltinay 3296 \code{identityTensor(d)}\left[ j \right] = \left\{
842 gross 599 \begin{array}{cc}
843     1 & \mbox{ if } j=i\\
844     0 & \mbox{ otherwise }
845     \end{array}
846     \right.
847     \end{equation}
848 gross 2484 If \var{d} is an integer a $(d,)$ \numpy array is returned.
849 gross 599
850 gross 593 \end{funcdesc}
851    
852     \begin{funcdesc}{Lsup}{a}
853     returns the $L^{sup}$ norm of \var{arg}. This is the maximum of the absolute values
854 caltinay 3296 over all components and all \DataSamplePoints of \var{a}.
855 gross 593 \end{funcdesc}
856    
857     \begin{funcdesc}{sup}{a}
858     returns the maximum value over all components and all \DataSamplePoints of \var{a}.
859     \end{funcdesc}
860    
861     \begin{funcdesc}{inf}{a}
862     returns the minimum value over all components and all \DataSamplePoints of \var{a}
863     \end{funcdesc}
864    
865    
866    
867     \begin{funcdesc}{minval}{a}
868 ksteube 1316 returns at each \DataSamplePoints the minimum value over all components.
869 gross 593 \end{funcdesc}
870 gross 599
871 gross 593 \begin{funcdesc}{maxval}{a}
872 gross 599 returns at each \DataSamplePoints the maximum value over all components.
873 gross 593 \end{funcdesc}
874 gross 599
875 gross 593 \begin{funcdesc}{length}{a}
876 jfenwick 1959 returns at Euclidean norm at each \DataSamplePoints. For a \RankFour \var{a} this is
877 gross 599 \begin{equation}
878 caltinay 3296 \code{length(a)}=\sqrt{\sum_{ijkl} \var{a} \left[i,j,k,l\right]^2}
879     \end{equation}
880 gross 593 \end{funcdesc}
881 gross 599 \begin{funcdesc}{trace}{a\optional{,axis_offset=0}}
882     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
883 caltinay 3296 case of a \RankTwo function and this is
884 gross 599 \begin{equation}
885 caltinay 3296 \code{trace(a)}=\sum_{i} \var{a} \left[i,i\right]
886     \end{equation}
887 gross 599 and for a \RankFour function and \code{axis_offset=1} this is
888     \begin{equation}
889 caltinay 3296 \code{trace(a,1)}\left[i,j\right]=\sum_{k} \var{a} \left[i,k,k,j\right]
890     \end{equation}
891 gross 593 \end{funcdesc}
892 gross 804
893 gross 599 \begin{funcdesc}{transpose}{a\optional{, axis_offset=None}}
894     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
895 caltinay 3296 present \code{int(r/2)} is used where \var{r} is the rank of \var{a}.
896 gross 599 the sum over components \var{axis_offset} and \var{axis_offset+1} with the same index. For instance in the
897 caltinay 3296 case of a \RankTwo function and this is
898 gross 599 \begin{equation}
899     \code{transpose(a)}\left[i,j\right]=\var{a} \left[j,i\right]
900 caltinay 3296 \end{equation}
901 gross 599 and for a \RankFour function and \code{axis_offset=1} this is
902     \begin{equation}
903     \code{transpose(a,1)}\left[i,j,k,l\right]=\var{a} \left[j,k,l,i\right]
904 caltinay 3296 \end{equation}
905 gross 593 \end{funcdesc}
906 gross 804
907     \begin{funcdesc}{swap_axes}{a\optional{, axis0=0 \optional{, axis1=1 }}}
908 ksteube 1316 returns \var{a} but with swapped components \var{axis0} and \var{axis1}. The argument \var{a} must be
909 caltinay 3296 at least of \RankTwo. For instance in the
910 gross 804 for a \RankFour argument, \code{axis0=1} and \code{axis1=2} this is
911     \begin{equation}
912     \code{swap_axes(a,1,2)}\left[i,j,k,l\right]=\var{a} \left[i,k,j,l\right]
913 caltinay 3296 \end{equation}
914 gross 804 \end{funcdesc}
915    
916 gross 593 \begin{funcdesc}{symmetric}{a}
917 gross 599 returns the symmetric part of \var{a}. This is \code{(a+transpose(a))/2}.
918 gross 593 \end{funcdesc}
919     \begin{funcdesc}{nonsymmetric}{a}
920 gross 599 returns the non--symmetric part of \var{a}. This is \code{(a-transpose(a))/2}.
921 gross 593 \end{funcdesc}
922     \begin{funcdesc}{inverse}{a}
923 caltinay 3296 return the inverse of \var{a}. This is
924 gross 599 \begin{equation}
925 gross 809 \code{matrix_mult(inverse(a),a)=kronecker(d)}
926 caltinay 3296 \end{equation}
927     if \var{a} has shape \code{(d,d)}. The current implementation is restricted to arguments of shape
928 gross 599 \code{(2,2)} and \code{(3,3)}.
929 gross 593 \end{funcdesc}
930     \begin{funcdesc}{eigenvalues}{a}
931 caltinay 3296 return the eigenvalues of \var{a}. This is
932 gross 599 \begin{equation}
933 gross 809 \code{matrix_mult(a,V)=e[i]*V}
934 caltinay 3296 \end{equation}
935     where \code{e=eigenvalues(a)} and \var{V} is suitable non--zero vector \var{V}.
936 gross 599 The eigenvalues are ordered in increasing size.
937 caltinay 3296 The argument \var{a} has to be the symmetric, ie. \code{a=symmetric(a)}.
938     The current implementation is restricted to arguments of shape
939 gross 599 \code{(2,2)} and \code{(3,3)}.
940 gross 593 \end{funcdesc}
941     \begin{funcdesc}{eigenvalues_and_eigenvectors}{a}
942 caltinay 3296 return the eigenvalues and eigenvectors of \var{a}. This is
943 gross 599 \begin{equation}
944 gross 809 \code{matrix_mult(a,V[:,i])=e[i]*V[:,i]}
945 caltinay 3296 \end{equation}
946 gross 599 where \code{e,V=eigenvalues_and_eigenvectors(a)}. The eigenvectors \var{V} are orthogonal and normalized, ie.
947     \begin{equation}
948 gross 809 \code{matrix_mult(transpose(V),V)=kronecker(d)}
949 caltinay 3296 \end{equation}
950 gross 599 if \var{a} has shape \code{(d,d)}. The eigenvalues are ordered in increasing size.
951 caltinay 3296 The argument \var{a} has to be the symmetric, ie. \code{a=symmetric(a)}.
952     The current implementation is restricted to arguments of shape
953 gross 599 \code{(2,2)} and \code{(3,3)}.
954 gross 593 \end{funcdesc}
955 gross 599 \begin{funcdesc}{maximum}{*a}
956     returns the maximum value over all arguments at all \DataSamplePoints and for each component.
957 caltinay 3296 For instance
958 gross 599 \begin{equation}
959     \code{maximum(a0,a1)}\left[i,j\right]=max(\var{a0} \left[i,j\right],\var{a1} \left[i,j\right])
960     \end{equation}
961     at all \DataSamplePoints.
962 gross 593 \end{funcdesc}
963 gross 599 \begin{funcdesc}{minimum}{*a}
964     returns the minimum value over all arguments at all \DataSamplePoints and for each component.
965 caltinay 3296 For instance
966 gross 599 \begin{equation}
967     \code{minimum(a0,a1)}\left[i,j\right]=min(\var{a0} \left[i,j\right],\var{a1} \left[i,j\right])
968     \end{equation}
969     at all \DataSamplePoints.
970 gross 593 \end{funcdesc}
971 gross 599
972     \begin{funcdesc}{clip}{a\optional{, minval=0.}\optional{, maxval=1.}}
973 caltinay 3296 cuts back \var{a} into the range between \var{minval} and \var{maxval}. A value in the returned object equals
974     \var{minval} if the corresponding value of \var{a} is less than \var{minval}, equals \var{maxval} if the
975 gross 599 corresponding value of \var{a} is greater than \var{maxval}
976     or corresponding value of \var{a} otherwise.
977 gross 593 \end{funcdesc}
978     \begin{funcdesc}{inner}{a0,a1}
979 gross 599 returns the inner product of \var{a0} and \var{a1}. For instance in the
980 caltinay 3296 case of \RankTwo arguments and this is
981 gross 599 \begin{equation}
982 caltinay 3296 \code{inner(a)}=\sum_{ij}\var{a0} \left[j,i\right] \cdot \var{a1} \left[j,i\right]
983     \end{equation}
984 gross 599 and for a \RankFour arguments this is
985     \begin{equation}
986 caltinay 3296 \code{inner(a)}=\sum_{ijkl}\var{a0} \left[i,j,k,l\right] \cdot \var{a1} \left[j,i,k,l\right]
987     \end{equation}
988 gross 593 \end{funcdesc}
989 gross 809
990     \begin{funcdesc}{matrix_mult}{a0,a1}
991 gross 599 returns the matrix product of \var{a0} and \var{a1}. If \var{a1} is \RankOne this is
992     \begin{equation}
993 caltinay 3296 \code{matrix_mult(a)}\left[i\right]=\sum_{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[k\right]
994     \end{equation}
995 gross 599 and if \var{a1} is \RankTwo this is
996     \begin{equation}
997 caltinay 3296 \code{matrix_mult(a)}\left[i,j\right]=\sum_{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[k,j\right]
998     \end{equation}
999 gross 593 \end{funcdesc}
1000 gross 809
1001     \begin{funcdesc}{transposed_matrix_mult}{a0,a1}
1002 caltinay 3296 returns the matrix product of the transposed of \var{a0} and \var{a1}. The function is equivalent to
1003 gross 809 \code{matrix_mult(transpose(a0),a1)}.
1004     If \var{a1} is \RankOne this is
1005     \begin{equation}
1006 caltinay 3296 \code{transposed_matrix_mult(a)}\left[i\right]=\sum_{k}\var{a0} \cdot \left[k,i\right]\var{a1} \left[k\right]
1007     \end{equation}
1008 gross 809 and if \var{a1} is \RankTwo this is
1009     \begin{equation}
1010 caltinay 3296 \code{transposed_matrix_mult(a)}\left[i,j\right]=\sum_{k}\var{a0} \cdot \left[k,i\right]\var{a1} \left[k,j\right]
1011     \end{equation}
1012 gross 809 \end{funcdesc}
1013    
1014     \begin{funcdesc}{matrix_transposed_mult}{a0,a1}
1015     returns the matrix product of \var{a0} and the transposed of \var{a1}.
1016     The function is equivalent to
1017 caltinay 3296 \code{matrix_mult(a0,transpose(a1))}.
1018 gross 809 If \var{a1} is \RankTwo this is
1019     \begin{equation}
1020 caltinay 3296 \code{matrix_transposed_mult(a)}\left[i,j\right]=\sum_{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[j,k\right]
1021     \end{equation}
1022 gross 809 \end{funcdesc}
1023    
1024 gross 593 \begin{funcdesc}{outer}{a0,a1}
1025 gross 599 returns the outer product of \var{a0} and \var{a1}. For instance if \var{a0} and \var{a1} both are \RankOne then
1026     \begin{equation}
1027     \code{outer(a)}\left[i,j\right]=\var{a0} \left[i\right] \cdot \var{a1}\left[j\right]
1028 caltinay 3296 \end{equation}
1029 gross 599 and if \var{a0} is \RankOne and \var{a1} is \RankThree
1030     \begin{equation}
1031     \code{outer(a)}\left[i,j,k\right]=\var{a0} \left[i\right] \cdot \var{a1}\left[j,k\right]
1032 caltinay 3296 \end{equation}
1033 gross 593 \end{funcdesc}
1034 gross 809
1035     \begin{funcdesc}{tensor_mult}{a0,a1}
1036 gross 599 returns the tensor product of \var{a0} and \var{a1}. If \var{a1} is \RankTwo this is
1037     \begin{equation}
1038 caltinay 3296 \code{tensor_mult(a)}\left[i,j\right]=\sum_{kl}\var{a0}\left[i,j,k,l\right] \cdot \var{a1} \left[k,l\right]
1039     \end{equation}
1040 gross 599 and if \var{a1} is \RankFour this is
1041     \begin{equation}
1042 caltinay 3296 \code{tensor_mult(a)}\left[i,j,k,l\right]=\sum_{mn}\var{a0} \left[i,j,m,n\right] \cdot \var{a1} \left[m,n,k,l\right]
1043     \end{equation}
1044 gross 593 \end{funcdesc}
1045 gross 809
1046     \begin{funcdesc}{transposed_tensor_mult}{a0,a1}
1047     returns the tensor product of the transposed of \var{a0} and \var{a1}. The function is equivalent to
1048     \code{tensor_mult(transpose(a0),a1)}.
1049     If \var{a1} is \RankTwo this is
1050     \begin{equation}
1051 caltinay 3296 \code{transposed_tensor_mult(a)}\left[i,j\right]=\sum_{kl}\var{a0}\left[k,l,i,j\right] \cdot \var{a1} \left[k,l\right]
1052     \end{equation}
1053 gross 809 and if \var{a1} is \RankFour this is
1054     \begin{equation}
1055 caltinay 3296 \code{transposed_tensor_mult(a)}\left[i,j,k,l\right]=\sum_{mn}\var{a0} \left[m,n,i,j\right] \cdot \var{a1} \left[m,n,k,l\right]
1056     \end{equation}
1057 gross 809 \end{funcdesc}
1058    
1059     \begin{funcdesc}{tensor_transposed_mult}{a0,a1}
1060 caltinay 3296 returns the tensor product of \var{a0} and the transposed of \var{a1}.
1061 gross 809 The function is equivalent to
1062     \code{tensor_mult(a0,transpose(a1))}.
1063     If \var{a1} is \RankTwo this is
1064     \begin{equation}
1065 caltinay 3296 \code{tensor_transposed_mult(a)}\left[i,j\right]=\sum_{kl}\var{a0}\left[i,j,k,l\right] \cdot \var{a1} \left[l,k\right]
1066     \end{equation}
1067 gross 809 and if \var{a1} is \RankFour this is
1068     \begin{equation}
1069 caltinay 3296 \code{tensor_transposed_mult(a)}\left[i,j,k,l\right]=\sum_{mn}\var{a0} \left[i,j,m,n\right] \cdot \var{a1} \left[k,l,m,n\right]
1070     \end{equation}
1071 gross 809 \end{funcdesc}
1072    
1073 gross 599 \begin{funcdesc}{grad}{a\optional{, where=None}}
1074 caltinay 3296 returns the gradient of \var{a}. If \var{where} is present the gradient will be calculated in \FunctionSpace \var{where} otherwise a
1075 gross 599 default \FunctionSpace is used. In case that \var{a} has \RankTwo one has
1076     \begin{equation}
1077 caltinay 3296 \code{grad(a)}\left[i,j,k\right]=\frac{\partial \var{a} \left[i,j\right]}{\partial x_{k}}
1078     \end{equation}
1079 gross 593 \end{funcdesc}
1080 gross 599 \begin{funcdesc}{integrate}{a\optional{ ,where=None}}
1081 caltinay 3296 returns the integral of \var{a} where the domain of integration is defined by the \FunctionSpace of \var{a}. If \var{where} is
1082     present the argument is interpolated into \FunctionSpace \var{where} before integration. For instance in the case of
1083 gross 599 a \RankTwo argument in \ContinuousFunction it is
1084     \begin{equation}
1085 caltinay 3296 \code{integrate(a)}\left[i,j\right]=\int_{\Omega}\var{a} \left[i,j\right] \; d\Omega
1086     \end{equation}
1087     where $\Omega$ is the spatial domain and $d\Omega$ volume integration. To integrate over the boundary of the domain one uses
1088 gross 599 \begin{equation}
1089 caltinay 3296 \code{integrate(a,where=FunctionOnBoundary(a.getDomain))}\left[i,j\right]=\int_{\partial \Omega} a\left[i,j\right] \; ds
1090     \end{equation}
1091 gross 599 where $\partial \Omega$ is the surface of the spatial domain and $ds$ area or line integration.
1092 gross 593 \end{funcdesc}
1093     \begin{funcdesc}{interpolate}{a,where}
1094 caltinay 3296 interpolates argument \var{a} into the \FunctionSpace \var{where}.
1095 gross 593 \end{funcdesc}
1096 gross 599 \begin{funcdesc}{div}{a\optional{ ,where=None}}
1097 caltinay 3296 returns the divergence of \var{a}. This
1098 gross 599 \begin{equation}
1099     \code{div(a)}=trace(grad(a),where)
1100     \end{equation}
1101 gross 593 \end{funcdesc}
1102 gross 599 \begin{funcdesc}{jump}{a\optional{ ,domain=None}}
1103     returns the jump of \var{a} over the discontinuity in its domain or if \Domain \var{domain} is present
1104     in \var{domain}.
1105     \begin{equation}
1106 gross 809 \begin{array}{rcl}
1107     \code{jump(a)}& = &\code{interpolate(a,FunctionOnContactOne(domain))} \\
1108     & & \hfill - \code{interpolate(a,FunctionOnContactZero(domain))}
1109     \end{array}
1110 gross 599 \end{equation}
1111 gross 593 \end{funcdesc}
1112     \begin{funcdesc}{L2}{a}
1113 caltinay 3296 returns the $L^2$-norm of \var{a} in its function space. This is
1114 gross 599 \begin{equation}
1115 gross 809 \code{L2(a)=integrate(length(a)}^2\code{)} \; .
1116 caltinay 3296 \end{equation}
1117 gross 593 \end{funcdesc}
1118    
1119 jfenwick 1966 The following functions operate ``point-wise''. That is, the operation is applied to each component of each point
1120     individually.
1121    
1122     \begin{funcdesc}{sin}{a}
1123     applies sine function to \var{a}.
1124     \end{funcdesc}
1125    
1126     \begin{funcdesc}{cos}{a}
1127     applies cosine function to \var{a}.
1128     \end{funcdesc}
1129    
1130     \begin{funcdesc}{tan}{a}
1131     applies tangent function to \var{a}.
1132     \end{funcdesc}
1133    
1134     \begin{funcdesc}{asin}{a}
1135     applies arc (inverse) sine function to \var{a}.
1136     \end{funcdesc}
1137    
1138     \begin{funcdesc}{acos}{a}
1139     applies arc (inverse) cosine function to \var{a}.
1140     \end{funcdesc}
1141    
1142     \begin{funcdesc}{atan}{a}
1143     applies arc (inverse) tangent function to \var{a}.
1144     \end{funcdesc}
1145    
1146     \begin{funcdesc}{sinh}{a}
1147     applies hyperbolic sine function to \var{a}.
1148     \end{funcdesc}
1149    
1150     \begin{funcdesc}{cosh}{a}
1151     applies hyperbolic cosine function to \var{a}.
1152     \end{funcdesc}
1153    
1154     \begin{funcdesc}{tanh}{a}
1155     applies hyperbolic tangent function to \var{a}.
1156     \end{funcdesc}
1157    
1158     \begin{funcdesc}{asinh}{a}
1159     applies arc (inverse) hyperbolic sine function to \var{a}.
1160     \end{funcdesc}
1161    
1162     \begin{funcdesc}{acosh}{a}
1163     applies arc (inverse) hyperbolic cosine function to \var{a}.
1164     \end{funcdesc}
1165    
1166     \begin{funcdesc}{atanh}{a}
1167     applies arc (inverse) hyperbolic tangent function to \var{a}.
1168     \end{funcdesc}
1169    
1170     \begin{funcdesc}{exp}{a}
1171     applies exponential function to \var{a}.
1172     \end{funcdesc}
1173    
1174     \begin{funcdesc}{sqrt}{a}
1175     applies square root function to \var{a}.
1176     \end{funcdesc}
1177    
1178     \begin{funcdesc}{log}{a}
1179     applies the natural logarithm to \var{a}.
1180     \end{funcdesc}
1181    
1182     \begin{funcdesc}{log10}{a}
1183     applies the base-$10$ logarithm to \var{a}.
1184     \end{funcdesc}
1185    
1186     \begin{funcdesc}{sign}{a}
1187     applies the sign function to \var{a}, that is $1$ where \var{a} is positive,
1188     $-1$ where \var{a} is negative and $0$ otherwise.
1189     \end{funcdesc}
1190    
1191     \begin{funcdesc}{wherePositive}{a}
1192     returns a function which is $1$ where \var{a} is positive and $0$ otherwise.
1193     \end{funcdesc}
1194    
1195     \begin{funcdesc}{whereNegative}{a}
1196     returns a function which is $1$ where \var{a} is negative and $0$ otherwise.
1197     \end{funcdesc}
1198    
1199     \begin{funcdesc}{whereNonNegative}{a}
1200     returns a function which is $1$ where \var{a} is non--negative and $0$ otherwise.
1201     \end{funcdesc}
1202    
1203     \begin{funcdesc}{whereNonPositive}{a}
1204     returns a function which is $1$ where \var{a} is non--positive and $0$ otherwise.
1205     \end{funcdesc}
1206    
1207 gross 2304 \begin{funcdesc}{whereZero}{a\optional{, tol=None, \optional{, rtol=1.e-8}}}
1208     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.
1209 jfenwick 1966 \end{funcdesc}
1210    
1211 gross 2304 \begin{funcdesc}{whereNonZero}{a, \optional{, tol=None, \optional{, rtol=1.e-8}}}
1212     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.
1213 jfenwick 1966 \end{funcdesc}
1214    
1215 jfenwick 2646 \subsection{Interpolating Data}
1216     \index{interpolateTable}
1217     In some cases, it may be useful to produce Data objects which fit some user defined function.
1218 caltinay 3296 Manually modifying each value in the Data object is not a good idea since it depends on
1219 jfenwick 2646 knowing the location and order of each datapoint in the domain.
1220     Instead \escript can use an interpolation table to produce a Data object.
1221    
1222 gross 2668 The following example is available as \file{int_save.py} in the examples directory.
1223 jfenwick 2646 We will produce a \Data object which aproximates a sine curve.
1224    
1225     \begin{python}
1226     from esys.escript import saveDataCSV, sup
1227     import numpy
1228     from esys.finley import Rectangle
1229    
1230 gross 2668 n=4
1231 jfenwick 2646 r=Rectangle(n,n)
1232     x=r.getX()
1233     x0=x[0]
1234     x1=x[1] #we'll use this later
1235     toobig=100
1236     \end{python}
1237    
1238     First we produce an interpolation table.
1239     \begin{python}
1240 caltinay 3296 sine_table=[0, 0.70710678118654746, 1, 0.70710678118654746, 0,
1241 jfenwick 2677 -0.70710678118654746, -1, -0.70710678118654746, 0]
1242 jfenwick 2646 \end{python}
1243    
1244     We wish to identify $0$ and $1$ with the ends of the curve.
1245 caltinay 3296 That is, with the first and eighth values in the table.
1246 jfenwick 2646
1247     \begin{python}
1248     numslices=len(sine_table)-1
1249    
1250     minval=0
1251 jfenwick 2677 maxval=1
1252 jfenwick 2646
1253     step=sup(maxval-minval)/numslices
1254     \end{python}
1255    
1256     So the values $v$ from the input lie in the interval minval$\leq v < $maxval.
1257     \var{step} represents the gap (in the input range) between entries in the table.
1258 gross 2668 By default values of $v$ outside the table argument range (minval, maxval) will
1259     be pushed back into the range, ie. if $v <$ minval the value minval will be used to
1260 gross 2864 evaluate the table. Similarly, for values $v>$ maxval the value maxval is used.
1261 gross 2668
1262 jfenwick 2646 Now we produce our new \Data object.
1263    
1264     \begin{python}
1265     result=x0.interpolateTable(sine_table, minval, step, toobig)
1266     \end{python}
1267 caltinay 3296 Any values which interpolate to larger than \var{toobig} will raise an exception. You can
1268 gross 2668 switch on boundary checking by adding ''check_boundaries=True`` the argument list.
1269 jfenwick 2646
1270 gross 2668
1271 jfenwick 2646 Now for a 2D example.
1272     We will interpolate a surface such that the bottom edge is the sine curve described above.
1273     The amplitude of the curve decreases as we move towards the top edge.
1274    
1275     Our interpolation table will have three rows.
1276     \begin{python}
1277     st=numpy.array(sine_table)
1278    
1279     table=[st, 0.5*st, 0*st ]
1280     \end{python}
1281    
1282     The use of numpy and multiplication here is just to save typing.
1283    
1284     \begin{python}
1285     result2=x1.interpolateTable(table, 0, 0.55, x0, minval, step, toobig)
1286     \end{python}
1287    
1288 caltinay 3296 In the 2D case, the parameters for the x1 direction (min=0, step=0.55) come first followed by the x0 data object and
1289 gross 2864 its parameters.
1290 jfenwick 2677 By default, if a point is specified which is outside the boundary, then \var{interpolateTable} will operate
1291     as if the point was on the boundary.
1292     Passing \var{check_boundaries}=\var{True} will \var{interpolateTable} to reject any points outside the boundaries.
1293 jfenwick 2646
1294     \subsection{Saving Data as CSV}
1295     \index{saveDataCSV}
1296     \index{CSV}
1297     For simple post-processing, \Data objects can be saved in comma separated value format.
1298    
1299     If \var{mydata1} and \var{mydata2} are scalar data, the following command:
1300     \begin{python}
1301     saveDataCSV('output.csv',U=mydata1, V=mydata2)
1302     \end{python}
1303     will record the values of mydata in \texttt{output.csv} in the following format:
1304     \begin{verbatim}
1305     U, V
1306     1.0000000e+0, 2.0000000e-1
1307     5.0000000e-0, 1.0000000e+1
1308     ...
1309     \end{verbatim}
1310    
1311 gross 2864 The names of the keyword parameters form the names of columns in the output.
1312 jfenwick 2646 If the data objects are over different function spaces, then saveDataCSV will attempt to
1313     interpolate to a common function space.
1314     If this is not possible, then an exception will be raised.
1315    
1316     Output can be restricted using a scalar mask.
1317     \begin{python}
1318     saveDataCSV('outfile.csv', U=mydata1, V=mydata2, mask=myscalar)
1319     \end{python}
1320     Will only output those rows which correspond to to positive values of \var{myscalar}.
1321 gross 2864 Some aspects of the output can be tuned using additional parameters.
1322 jfenwick 2646 \begin{python}
1323     saveDataCSV('data.csv', append=True, sep=' ', csep='/', mask=mymask, e=mat1)
1324     \end{python}
1325    
1326     \begin{itemize}
1327     \item \var{append} - specifies that the output should be written to the end of an existing file.
1328     \item \var{sep} - defines the separator between fields.
1329 caltinay 3296 \item \var{csep} - defines the separator between components in the header line. For example between the components of a matrix.
1330 jfenwick 2646 \end{itemize}
1331    
1332     The above command would produce output like this:
1333     \begin{verbatim}
1334     e/0/0 e/1/0 e/0/1 e/1/1
1335     1.0000000000e+00 2.0000000000e+00 3.0000000000e+00 4.0000000000e+00
1336 caltinay 3296 ...
1337 jfenwick 2646 \end{verbatim}
1338    
1339 jfenwick 2766 Note that while the order in which rows are output can vary, all the elements in a given row
1340     always correspond to the same input.
1341 jfenwick 2646
1342    
1343 caltinay 3296 \subsection{The \Operator Class}
1344 jgs 102 The \Operator class provides an abstract access to operators build
1345 caltinay 3296 within the \LinearPDE class. \Operator objects are created
1346 jgs 102 when a PDE is handed over to a PDE solver library and handled
1347 jfenwick 1959 by the \LinearPDE object defining the PDE. The user can gain access
1348 jgs 102 to the \Operator of a \LinearPDE object through the \var{getOperator}
1349     method.
1350    
1351     \begin{classdesc}{Operator}{}
1352     creates an empty \Operator object.
1353     \end{classdesc}
1354    
1355     \begin{methoddesc}[Operator]{isEmpty}{fileName}
1356     returns \True is the object is empty. Otherwise \True is returned.
1357 jgs 82 \end{methoddesc}
1358    
1359 jgs 102 \begin{methoddesc}[Operator]{setValue}{value}
1360 ksteube 1316 resets all entries in the object representation to \var{value}
1361 jgs 82 \end{methoddesc}
1362    
1363 jgs 102 \begin{methoddesc}[Operator]{solves}{rhs}
1364     solves the operator equation with right hand side \var{rhs}
1365 jgs 82 \end{methoddesc}
1366    
1367 jgs 102 \begin{methoddesc}[Operator]{of}{u}
1368     applies the operator to the \Data object \var{u}
1369 jgs 82 \end{methoddesc}
1370    
1371 jgs 102 \begin{methoddesc}[Operator]{saveMM}{fileName}
1372 jgs 82 saves the object to a matrix market format file of name
1373     \var{fileName}, see
1374 jfenwick 2335 \url{http://maths.nist.gov/MatrixMarket}
1375     % \ulink{maths.nist.gov/MatrixMarket}{\url{http://maths.nist.gov/MatrixMarket}}.
1376 jgs 82 \index{Matrix Market}
1377     \end{methoddesc}
1378    
1379 gross 2404 \section{Physical Units}
1380     \escript provides support for physical units in the SI system \index{SI units} including unit conversion. So the
1381     user can define variables in the form
1382     \begin{python}
1383     from esys.escript.unitsSI import *
1384     l=20*m
1385     w=30*kg
1386     w2=40*lb
1387     T=100*Celsius
1388     \end{python}
1389 caltinay 3296 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
1390 gross 2404 composed units can be used, for instance
1391     \begin{python}
1392     from esys.escript.unitsSI import *
1393     rho=40*lb/cm**3
1394     \end{python}
1395 caltinay 3296 to define the density in the units of pounds per cubic centimeter. The value $40$ will be converted
1396 gross 2404 into SI units, in this case kg per cubic meter.
1397     Moreover unit prefixes are supported:
1398     \begin{python}
1399     from esys.escript.unitsSI import *
1400     p=40*Mega*Pa
1401     \end{python}
1402     to the the pressure to 40 Mega Pascal. Units can also be converted back from the SI system into
1403     a desired unit, e.g
1404     \begin{python}
1405     from esys.escript.unitsSI import *
1406     print p/atm
1407     \end{python}
1408 caltinay 3296 can be used print the pressure in units of atmosphere\index{atmosphere}.
1409 gross 2404
1410     This is an incomplete list of supported physical units:
1411    
1412     \begin{datadesc}{km}
1413     unit of kilo meter
1414     \end{datadesc}
1415    
1416     \begin{datadesc}{m}
1417     unit of meter
1418     \end{datadesc}
1419    
1420     \begin{datadesc}{cm}
1421     unit of centi meter
1422     \end{datadesc}
1423    
1424     \begin{datadesc}{mm}
1425     unit of milli meter
1426     \end{datadesc}
1427    
1428     \begin{datadesc}{sec}
1429     unit of second
1430     \end{datadesc}
1431    
1432     \begin{datadesc}{minute}
1433     unit of minute
1434     \end{datadesc}
1435    
1436     \begin{datadesc}{h}
1437 caltinay 3296 unit of hour
1438 gross 2404 \end{datadesc}
1439     \begin{datadesc}{day}
1440 caltinay 3296 unit of day
1441 gross 2404 \end{datadesc}
1442     \begin{datadesc}{yr}
1443     unit of year
1444     \end{datadesc}
1445    
1446     \begin{datadesc}{gram}
1447     unit of gram
1448     \end{datadesc}
1449     \begin{datadesc}{kg}
1450     unit of kilo gram
1451     \end{datadesc}
1452     \begin{datadesc}{lb}
1453 caltinay 3296 unit of pound
1454 gross 2404 \end{datadesc}
1455     \begin{datadesc}{ton}
1456     metric ton
1457     \end{datadesc}
1458    
1459     \begin{datadesc}{A}
1460     unit of Ampere
1461     \end{datadesc}
1462    
1463     \begin{datadesc}{Hz}
1464     unit of Hertz
1465     \end{datadesc}
1466    
1467     \begin{datadesc}{N}
1468     unit of Newton
1469     \end{datadesc}
1470     \begin{datadesc}{Pa}
1471 caltinay 3296 unit of Pascal
1472 gross 2404 \end{datadesc}
1473     \begin{datadesc}{atm}
1474 caltinay 3296 unit of atmosphere
1475 gross 2404 \end{datadesc}
1476     \begin{datadesc}{J}
1477 caltinay 3296 unit of Joule
1478 gross 2404 \end{datadesc}
1479    
1480     \begin{datadesc}{W}
1481 caltinay 3296 unit of Watt
1482 gross 2404 \end{datadesc}
1483    
1484     \begin{datadesc}{C}
1485 caltinay 3296 unit of Coulomb
1486 gross 2404 \end{datadesc}
1487     \begin{datadesc}{V}
1488 caltinay 3296 unit of Volt
1489 gross 2404 \end{datadesc}
1490     \begin{datadesc}{F}
1491 caltinay 3296 unit of Farad
1492 gross 2404 \end{datadesc}
1493    
1494     \begin{datadesc}{Ohm}
1495     unit of Ohm
1496     \end{datadesc}
1497     \begin{datadesc}{K}
1498 caltinay 3296 unit of Kelvin
1499 gross 2404 \end{datadesc}
1500     \begin{datadesc}{Celsius}
1501     unit of Celsius
1502     \end{datadesc}
1503    
1504     \begin{datadesc}{Fahrenheit}
1505 caltinay 3296 unit of Fahrenheit
1506 gross 2404 \end{datadesc}
1507    
1508     Moreover unit prefixes are supported:
1509    
1510     \begin{datadesc}{Yotta}
1511     prefix yotta = $10^{24}$.
1512 caltinay 3296
1513 gross 2404 \end{datadesc}
1514    
1515     \begin{datadesc}{Zetta}
1516     prefix zetta= $10^{21}$.
1517     \end{datadesc}
1518    
1519     \begin{datadesc}{Exa}
1520     prefix exa= $10^{18}$.
1521     \end{datadesc}
1522    
1523     \begin{datadesc}{Peta}
1524     prefix peta= $10^{15}$.
1525     \end{datadesc}
1526    
1527     \begin{datadesc}{Tera}
1528     prefix tera= $10^{12}$.
1529     \end{datadesc}
1530    
1531     \begin{datadesc}{Giga}
1532     prefix giga= $10^9$.
1533     \end{datadesc}
1534    
1535     \begin{datadesc}{Mega}
1536     prefix mega= $10^6$.
1537     \end{datadesc}
1538    
1539     \begin{datadesc}{Kilo}
1540     prefix kilo= $10^3$.
1541     \end{datadesc}
1542    
1543     \begin{datadesc}{Hecto}
1544     prefix hecto= $10^2$.
1545     \end{datadesc}
1546    
1547     \begin{datadesc}{Deca}
1548     prefix deca= $10^1$.
1549     \end{datadesc}
1550    
1551     \begin{datadesc}{Deci}
1552     prefix deci= $10^{-1}$.
1553     \end{datadesc}
1554    
1555     \begin{datadesc}{Centi}
1556 caltinay 3296 prefix centi= $10^{-2}$.
1557 gross 2404 \end{datadesc}
1558    
1559     \begin{datadesc}{Milli}
1560     prefix milli= $10^{-3}$.
1561     \end{datadesc}
1562    
1563     \begin{datadesc}{Micro}
1564     prefix micro= $10^{-6}$.
1565     \end{datadesc}
1566    
1567     \begin{datadesc}{Nano}
1568     prefix nano= $10^{-9}$.
1569     \end{datadesc}
1570    
1571     \begin{datadesc}{Pico}
1572     prefix pico= $10^{-12}$.
1573     \end{datadesc}
1574    
1575     \begin{datadesc}{Femto}
1576     prefix femto= $10^{-15}$.
1577     \end{datadesc}
1578    
1579     \begin{datadesc}{Atto}
1580     prefix atto= $10^{-18}$.
1581     \end{datadesc}
1582    
1583     \begin{datadesc}{Zepto}
1584     prefix zepto= $10^{-21}$.
1585     \end{datadesc}
1586    
1587     \begin{datadesc}{Yocto}
1588     prefix yocto= $10^{-24}$.
1589     \end{datadesc}
1590    
1591    
1592 gross 2318 \section{Utilities}
1593 gross 2420
1594 caltinay 3296 The \class{FileWriter} provides a mechanism to write data to a file.
1595     In essence, this class wraps the standard \class{file} class to write data
1596     that are global in MPI to a file. In fact, data are written on the processor
1597     with \MPI rank 0 only. It is recommended to use \class{FileWriter}
1598     rather than \class{open} in order to write code that is running
1599 gross 2420 with and without \MPI. It is save to use \class{open} under MPI to read data which are global under \MPI.
1600    
1601     \begin{classdesc}{FileWriter}{fn\optional{,append=\False, \optional{createLocalFiles=\False}})}
1602     Opens a file of name \var{fn} for writing. If \var{append} is set to \True
1603     written data are append at the end of the file.
1604     If running under \MPI only the first processor with rank==0
1605 caltinay 3296 will open the file and write to it.
1606 gross 2420 If \var{createLocalFiles} is set each individual processor will create a file
1607     where for any processor with rank>0 the file name is extended by its rank. This option is normally used for debug purposes only.
1608     \end{classdesc}
1609    
1610     The following methods are available:
1611     \begin{methoddesc}[FileWriter]{close}{}
1612     closes the file.
1613     \end{methoddesc}
1614     \begin{methoddesc}[FileWriter]{flush}{}
1615     flushes the internal buffer to disk.
1616     \end{methoddesc}
1617     \begin{methoddesc}[FileWriter]{write}{txt}
1618     Write string \var{txt} to file.
1619     Note that newline is not added.
1620     \end{methoddesc}
1621     \begin{methoddesc}[FileWriter]{writelines}{txts}
1622     Write the list \var{txts} of strings to the file..
1623 caltinay 3296 Note that newlines are not added.
1624 gross 2420 This method is equivalent to call write() for each string.
1625     \end{methoddesc}
1626     \begin{memberdesc}[FileWriter]{closed}
1627     \True if file is closed.
1628     \end{memberdesc}
1629     \begin{memberdesc}[FileWriter]{mode}
1630 caltinay 3296 access mode.
1631 gross 2420 \end{memberdesc}
1632     \begin{memberdesc}[FileWriter]{name}
1633     file name.
1634     \end{memberdesc}
1635     \begin{memberdesc}[FileWriter]{newlines}
1636     line separator
1637     \end{memberdesc}
1638    
1639    
1640 gross 2318 \begin{funcdesc}{setEscriptParamInt}{name,value}
1641 jfenwick 2335 assigns the integer value \var{value} to the parameter \var{name}.
1642 caltinay 3296 If \var{name}="TOO_MANY_LINES" conversion of any \Data object to a string switches to a
1643 gross 2318 condensed format if more than \var{value} lines would be created.
1644     \end{funcdesc}
1645    
1646     \begin{funcdesc}{getEscriptParamInt}{name}
1647 caltinay 3296 returns the current value of integer parameter \var{name}.
1648 gross 2318 \end{funcdesc}
1649    
1650     \begin{funcdesc}{listEscriptParams}{a}
1651     returns a list of valid parameters and their description.
1652     \end{funcdesc}
1653    
1654     \begin{funcdesc}{getMPISizeWorld}{}
1655     returns the number of \MPI processors in use in the \env{MPI_COMM_WORLD} processor group.
1656 gross 2420 If \MPI is not used 1 is returned.
1657 gross 2318 \end{funcdesc}
1658     \begin{funcdesc}{getMPIRankWorld}{}
1659     returns the rank of the process within the \env{MPI_COMM_WORLD} processor group.
1660 gross 2420 If \MPI is not used 0 is returned.
1661 gross 2318 \end{funcdesc}
1662     \begin{funcdesc}{MPIBarrierWorld}{}
1663     performs a barrier synchronization across all processors within \env{MPI_COMM_WORLD}
1664     processor group.
1665     \end{funcdesc}
1666     \begin{funcdesc}{getMPIWorldMax}{a}
1667 caltinay 3296 returns the maximum value of the integer \var{a} across all
1668 gross 2318 processors within \env{MPI_COMM_WORLD}.
1669     \end{funcdesc}
1670 gross 2420

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26