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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1317 by ksteube, Tue Sep 25 03:18:30 2007 UTC revision 1318 by ksteube, Wed Sep 26 04:39:14 2007 UTC
# Line 14  Line 14 
14  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15  %  %
16    
17  \chapter{The module \escript}  \chapter{The Module \escript}
18  \label{ESCRIPT CHAP}  \label{ESCRIPT CHAP}
19    
20    
# Line 24  Line 24 
24  function space at the starting point can be interpreted as a function in the function space of the arrow target.}  function space at the starting point can be interpreted as a function in the function space of the arrow target.}
25  \end{figure}  \end{figure}
26    
27  \escript is an extension of Python to handle functions represented by their values on  \escript is a Python module that allows you to represent the values of
28  \DataSamplePoints for the geometrical region on which  a function at points in a \Domain in such a way that the function will
29  the function is defined. The region as well as the method which is used  be useful for the Finite Element Method (FEM) simulation.  It also
30  to interpolate value on the \DataSamplePoints is defined by      provides what we call a function space that describes how the data is
31  \Domain class objects. For instance when using  used in the simulation.  Stored along with the data is information
32  the finite element method (FEM) \index{finite element method}  about the elements and nodes which will be used by \finley.
33  \Domain object holds the information about the FEM mesh, eg.  
34  a table of nodes and a table of elements. Although \Domain contains  In order to understand what we mean by the term 'function space'
35  the discretization method to be used \escript does not use this information directly.  consider that the solution of a partial differential equation
36  \Domain objects are created from a module which want to make use  \index{partial differential equation} (PDE) is a function on a domain
37  \escript, e.g. \finley.  $\Omega$.  When solving a PDE using FEM the solution is
38    piecewise-differentiable but, in general, its gradient is
39  The solution of a PDE is a function of its location in the domain of interest $\Omega$.  discontinuous.  To reflect these different degrees of smoothness
40  When solving a partial differential equation \index{partial differential equation} (PDE) using FEM  different function spaces are used.  For instance, in FEM the
41  the solution is (piecewise) differentiable but, in general, its gradient  displacement field is represented by its values at the nodes of the
42  is discontinuous. To reflect these different degrees of smoothness different  mesh, and is then continuous.  The strain, which is the symmetric
43  representations of the functions are used. For instance; in FEM  part of the gradient of the displacement field, is stored on the
44  the displacement field is represented by its values at the nodes of the mesh, while the  element centers, and so is considered to be discontinuous.
45  strain, which is the symmetric part of the gradient of the displacement field, is stored on the  
46  element centers. To be able to classify functions with respect to their smoothness, \escript has the  A function space is described by a \FunctionSpace object.  The
47  concept of the "function space". A function space is described by a \FunctionSpace object.  following statement generates the object \var{solution_space} which is
48  The following statement generates the object \var{solution_space} which is  a \FunctionSpace object and provides access to the function space of
 a \FunctionSpace object and provides access to the function space of  
49  PDE solutions on the \Domain \var{mydomain}:  PDE solutions on the \Domain \var{mydomain}:
50    
51  \begin{python}  \begin{python}
52  solution_space=Solution(mydomain)    solution_space=Solution(mydomain)
53  \end{python}  \end{python}
54  The following generators for function spaces on a \Domain \var{mydomain} are available:  The following generators for function spaces on a \Domain \var{mydomain} are available:
55  \begin{itemize}  \begin{itemize}
# Line 61  The following generators for function sp Line 61  The following generators for function sp
61  \item \var{FunctionOnContact0(mydomain)}: functions on side $0$ of the discontinuity.  \item \var{FunctionOnContact0(mydomain)}: functions on side $0$ of the discontinuity.
62  \item \var{FunctionOnContact1(mydomain)}: functions on side $1$ of the discontinuity.  \item \var{FunctionOnContact1(mydomain)}: functions on side $1$ of the discontinuity.
63  \end{itemize}  \end{itemize}
64    
65  The reduced smoothness for PDE solution is often used to fulfill the Ladyzhenskaya–-Babuska–-Brezzi condition \cite{LBB} when  The reduced smoothness for PDE solution is often used to fulfill the Ladyzhenskaya–-Babuska–-Brezzi condition \cite{LBB} when
66  solving saddle point problems \index{saddle point problems}, eg. the Stokes equation.  solving saddle point problems \index{saddle point problems}, eg. the Stokes equation.
67  A discontinuity \index{discontinuity} is a region within the domain across which functions may be discontinuous.    A discontinuity \index{discontinuity} is a region within the domain across which functions may be discontinuous.  
68  The location of discontinuity is defined in the \Domain object.  The location of discontinuity is defined in the \Domain object.
69  \fig{ESCRIPT DEP} shows the dependency between the types of function spaces.  \fig{ESCRIPT DEP} shows the dependency between the types of function spaces.
70    
71  The solution of a PDE is a continuous function. Any continuous function can be seen as a general function  The solution of a PDE is a continuous function. Any continuous function can be seen as a general function
72  on the domain and can be restricted to the boundary as well as to any side of the  on the domain and can be restricted to the boundary as well as to any side of the
73  discontinuity (the result will be different depending on  discontinuity (the result will be different depending on
74  which side is chosen). Functions on any side of the    which side is chosen). Functions on any side of the  
75  discontinuity can be seen as a function on the corresponding other side.  discontinuity can be seen as a function on the corresponding other side.
76    
77  A function on the boundary or on one side of  A function on the boundary or on one side of
78  the discontinuity cannot be seen as a general function on the domain as there are no values  the discontinuity cannot be seen as a general function on the domain as there are no values
79  defined for the interior. For most PDE solver libraries  defined for the interior. For most PDE solver libraries
80  the space of the solution and continuous functions is identical, however in some cases, eg.  the space of the solution and continuous functions is identical, however in some cases, eg.
81  when periodic boundary conditions are used in \finley, a solution  when periodic boundary conditions are used in \finley, a solution
82  fulfills periodic boundary conditions while a continuous function does not have to be periodic.  fulfills periodic boundary conditions while a continuous function does not have to be periodic.
83      
84  The concept of function spaces describes the properties of  The concept of function spaces describes the properties of
85  functions and allows abstraction from the actual representation  functions and allows abstraction from the actual representation
86  of the function in the context of a particular application. For instance,  of the function in the context of a particular application. For instance,
87  in the FEM context a  in the FEM context a
88  function in the \Function function space  function of the \Function type
89  is typically represented by its values at the element center,  is usually represented by its values at the element center,
90  but in a finite difference scheme the edge midpoint of cells is preferred.  but in a finite difference scheme the edge midpoint of cells is preferred.
91  Using the concept of function spaces  By changing its function space you can use the same function in a Finite Difference
92  allows the user to run the same script on different  scheme instead of Finite Element scheme.
 PDE solver libraries by just changing the creator of the \Domain object.      
93  Changing the function space of a particular function  Changing the function space of a particular function
94  will typically lead to a change of its representation.  will typically lead to a change of its representation.
95  So, when seen as a general function,  So, when seen as a general function,
96  a continuous function which is typically represented by its values  a continuous function which is typically represented by its values
97  on the node of the FEM mesh or finite difference grid  on the node of the FEM mesh or finite difference grid
98  must be interpolated to the element centers or the cell edges,  must be interpolated to the element centers or the cell edges,
99  respectively.  respectively. Interpolation happens automatically in \escript
100    whenever it is required.
101    
102  \Data class objects store functions of the location in a domain.  In \escript the class that stores these functions is called \Data.
103  The function is represented through its values on \DataSamplePoints where  The function is represented through its values on \DataSamplePoints where
104  the \DataSamplePoints are chosen according to the function space  the \DataSamplePoints are chosen according to the function space
105  of the function.    of the function.  
106  \Data class objects are used to define the coefficients  \Data class objects are used to define the coefficients
107  of the PDEs to be solved by a PDE solver library  of the PDEs to be solved by a PDE solver library
108  and to store the returned solutions.  and also to store the solutions of the PDE.
109    
110  The values of the function have a rank which gives the  The values of the function have a rank which gives the
111  number of indices, and a \Shape defining the range of each index.  number of indices, and a \Shape defining the range of each index.
# Line 118  The following statement creates the \Dat Line 121  The following statement creates the \Dat
121  continuous function with values  continuous function with values
122  of \Shape $(2,3)$ and rank $2$:  of \Shape $(2,3)$ and rank $2$:
123  \begin{python}  \begin{python}
124  mydat=Data(value=1,what=ContinuousFunction(myDomain),shape=(2,3))    mydat=Data(value=1,what=ContinuousFunction(myDomain),shape=(2,3))
125  \end{python}  \end{python}
126  The initial value is the constant $1$ for all \DataSamplePoints and  The initial value is the constant $1$ for all \DataSamplePoints and
127  all components.  all components.
# Line 129  that can be converted into a \numarray.N Line 132  that can be converted into a \numarray.N
132  The following two statements  The following two statements
133  create objects which are equivalent to \var{mydat}:  create objects which are equivalent to \var{mydat}:
134  \begin{python}  \begin{python}
135  mydat1=Data(value=numarray.ones((2,3)),what=ContinuousFunction(myDomain))    mydat1=Data(value=numarray.ones((2,3)),what=ContinuousFunction(myDomain))
136  mydat2=Data(value=[[1,1],[1,1],[1,1]],what=ContinuousFunction(myDomain))    mydat2=Data(value=[[1,1],[1,1],[1,1]],what=ContinuousFunction(myDomain))
137  \end{python}  \end{python}
138  In the first case the initial value is \var{numarray.ones((2,3))}  In the first case the initial value is \var{numarray.ones((2,3))}
139  which generates a $2 \times 3$ matrix as a \numarray.NumArray  which generates a $2 \times 3$ matrix as a \numarray.NumArray
# Line 157  Here the initial value is $0$ but any ob Line 160  Here the initial value is $0$ but any ob
160  is consistent with \Shape of the \Data object to be created can be used as the initial value.  is consistent with \Shape of the \Data object to be created can be used as the initial value.
161    
162  \Data objects can be manipulated by applying unitary operations (eg. cos, sin, log)  \Data objects can be manipulated by applying unitary operations (eg. cos, sin, log)
163  and can be combined by applying binary operations (eg. +, - ,* , /).  and can be combined point-wise by applying arithmetic operations (eg. +, - ,* , /).
164  It is to be emphasized that \escript itself does not handle any spatial dependencies as  It is to be emphasized that \escript itself does not handle any spatial dependencies as
165  it does not know how values are interpreted by the processing PDE solver library.  it does not know how values are interpreted by the processing PDE solver library.
166  However \escript invokes interpolation if this is needed during data manipulations.  However \escript invokes interpolation if this is needed during data manipulations.
# Line 176  $\lambda$ and $\mu$ are the Lame coeffic Line 179  $\lambda$ and $\mu$ are the Lame coeffic
179  takes the displacement {\tt u} and the Lame coefficients  takes the displacement {\tt u} and the Lame coefficients
180  \var{lam} and \var{mu} as arguments and returns the corresponding stress:  \var{lam} and \var{mu} as arguments and returns the corresponding stress:
181  \begin{python}  \begin{python}
182  from esys.escript import *    from esys.escript import *
183  def getStress(u,lam,mu):    def getStress(u,lam,mu):
184    d=u.getDomain().getDim()      d=u.getDomain().getDim()
185    g=grad(u)      g=grad(u)
186    stress=lam*trace(g)*kronecker(d)+mu*(g+transpose(g))      stress=lam*trace(g)*kronecker(d)+mu*(g+transpose(g))
187    return stress          return stress    
188  \end{python}  \end{python}
189  The variable  The variable
190  \var{d} gives the spatial dimension of the  \var{d} gives the spatial dimension of the
# Line 190  domain on which the displacements are de Line 193  domain on which the displacements are de
193  $i$ and $j$ running from $0$ to \var{d}-1. The call \var{grad(u)} requires  $i$ and $j$ running from $0$ to \var{d}-1. The call \var{grad(u)} requires
194  the displacement field \var{u} to be in the \var{Solution} or \ContinuousFunction  the displacement field \var{u} to be in the \var{Solution} or \ContinuousFunction
195  function space. The result \var{g} as well as the returned stress will be in the \Function function space.  function space. The result \var{g} as well as the returned stress will be in the \Function function space.
196  If \var{u} is available, eg. by solving a PDE, \var{getStress} might be called  If, for example, \var{u} is the solution of a PDE then \var{getStress} might be called
197  in the following way:  in the following way:
198  \begin{python}  \begin{python}
199  s=getStress(u,1.,2.)    s=getStress(u,1.,2.)
200  \end{python}  \end{python}
201  However \var{getStress} can also be called with \Data objects as values for  However \var{getStress} can also be called with \Data objects as values for
202  \var{lam} and \var{mu} which,  \var{lam} and \var{mu} which,
203  for instance in the case of a temperature dependency, are calculated by an expression.  for instance in the case of a temperature dependency, are calculated by an expression.
204  The following call is equivalent to the previous example:  The following call is equivalent to the previous example:
205  \begin{python}  \begin{python}
206  lam=Scalar(1.,ContinuousFunction(mydomain))    lam=Scalar(1.,ContinuousFunction(mydomain))
207  mu=Scalar(2.,Function(mydomain))    mu=Scalar(2.,Function(mydomain))
208  s=getStress(u,lam,mu)    s=getStress(u,lam,mu)
209  \end{python}  \end{python}
210    
211  The function \var{lam} belongs to the \ContinuousFunction function space  The function \var{lam} belongs to the \ContinuousFunction function space
212  but with \var{g} the function \var{trace(g)} is in the \Function function space.  but with \var{g} the function \var{trace(g)} is in the \Function function space.
213  Therefore the evaluation of the product \var{lam*trace(g)} in the stress calculation  In the evaluation of the product \var{lam*trace(g)} we have different function
214  produces a problem, as both functions are represented differently, eg. in FEM  spaces (on the nodes versus in the centers) and at first glance we have incompatible data.
215  \var{lam} by its values on the node, and in \var{trace(g)} by its values at the element centers.  \escript converts the arguments in an appropriate function space according to
216  In the case of inconsistent function spaces of arguments in a binary operation, \escript  Table~\ref{ESCRIPT DEP}. In this example that means
217  interprets the arguments in the appropriate function space according to the inclusion  \escript sees \var{lam} as a function of the \Function function space.
 defined in Table~\ref{ESCRIPT DEP}. In this example that means  
  \escript sees \var{lam} as a function of the \Function function space.  
218  In the context of FEM this means the nodal values of  In the context of FEM this means the nodal values of
219  \var{lam} are interpolated to the element centers. Behind the scenes  \var{lam} are interpolated to the element centers.
220  \escript calls the appropriate function from the PDE solver library.  The interpolation is automatic and requires no special handling.
221    
222  \begin{figure}  \begin{figure}
223  \includegraphics[width=\textwidth]{figures/EscriptDiagram2.eps}  \includegraphics[width=\textwidth]{figures/EscriptDiagram2.eps}
# Line 225  The number in each cell refers to the ma Line 227  The number in each cell refers to the ma
227  \end{figure}  \end{figure}
228    
229  Material parameters such as the Lame coefficients are typically dependent on rock types present in the  Material parameters such as the Lame coefficients are typically dependent on rock types present in the
230  area of interest. A common technique to handle these kinds of material parameters is "tagging". \fig{Figure: tag}  area of interest. A common technique to handle these kinds of material parameters is "tagging", which
231    uses storage efficiently. \fig{Figure: tag}
232  shows an example. In this case two rock types {\it white} and {\it gray} can be found in the domain. The domain  shows an example. In this case two rock types {\it white} and {\it gray} can be found in the domain. The domain
233  is subdivided into triangular shaped cells. Each  is subdivided into triangular shaped cells. Each
234  cell has a tag indicating the rock type predominately found in this cell. Here $1$ is used to indicate  cell has a tag indicating the rock type predominately found in this cell. Here $1$ is used to indicate
# Line 237  The following statements show how for th Line 240  The following statements show how for th
240  example of \fig{Figure: tag} and the stress calculation discussed before tagged values are used for  example of \fig{Figure: tag} and the stress calculation discussed before tagged values are used for
241  \var{lam}:  \var{lam}:
242  \begin{python}  \begin{python}
243  lam=Scalar(value=2.,what=Function(mydomain))    lam=Scalar(value=2.,what=Function(mydomain))
244  insertTaggedValue(lam,white=30.,gray=5000.)    insertTaggedValue(lam,white=30.,gray=5000.)
245  s=getStress(u,lam,2.)    s=getStress(u,lam,2.)
246  \end{python}  \end{python}
247  In this example \var{lam} is set to $30$ for those cells with tag {\it white} (=$1$) and to $5000.$ for those cells  In this example \var{lam} is set to $30$ for those cells with tag {\it white} (=$1$) and to $5000.$ for those cells
248  with tag {\it gray} (=$2$_. The initial value $2$ of \var{lam} is used as a default value for the case when a tag  with tag {\it gray} (=$2$_. The initial value $2$ of \var{lam} is used as a default value for the case when a tag
249  is encountered which has not been linked with a value. Note that the \var{getStress} method  is encountered which has not been linked with a value. The \var{getStress} method
250  is called without modification. \escript resolves the tags when \var{lam*trace(g)} is calculated.  does not need to be changed now that we are using tags.
251    \escript resolves the tags when \var{lam*trace(g)} is calculated.
252    
253    This brings us to a very important point about \escript.
254    You can develop a simulation with constant Lame coefficients, and then later switch to tagged
255    Lame coefficients without otherwise changing your python script.
256    In short, you can use the same script to model with different domains and different types of input data.
257    
258    There are three ways in which \Data objects are represented internally: constant, tagged, and expanded.
259    In the constant case, the same value is used at each sample point and only a single value is stored to save memory.
260    In the expanded case, each sample point has an individual value (such as for the solution of a PDE).
261    This is where your largest data sets will be created because the values are stored as a complete array.
262    The tagged case has already been discussed above.
263    
264  The \Data class provides a transparent interface to various data representations and the  Expanded data is created when you create a \Data object with expanded=True.
265  translations between them. As shown in the example of stress calculation, this allows the user to  Tagged data sets are created when you use the insertTaggedValue() method as shown above.
 develop and test algorithms for a simple case (for instance with the Lame coefficients as constants)  
 and then without further modifications of the program code to apply the algorithm in a  
 more complex application (for instance a definition of the Lame coefficients using tags).  
 As described here, there are three ways in which \Data objects are represented internally, constant,  
 tagged, and expanded (other representations will become available in later versions of \escript):  
 In the constant case, if the same value is used at each sample point a single value is stored to save memory and compute time.  
 Any operation on this constant data will only be performed on the single value.  
 In the expanded case, each sample point has an individual value, eg. the solution of a PDE,  
 and the values are stored as a complete array. The tagged case has already been discussed above.  
266    
267  Values are accessed through a sample reference number. Operations on expanded \Data  Values are accessed through a sample reference number. Operations on expanded \Data
268  objects have to be performed for each sample point individually. If tagged values are used values are  objects have to be performed for each sample point individually. When tagged values are used the values are
269  held in a dictionary. Operations on tagged data require processing the set of tagged values only, rather than  held in a dictionary. Operations on tagged data require processing the set of tagged values only, rather than
270  processing the value for each individual sample point.  processing the value for each individual sample point.
271  \escript allows use of constant, tagged and expanded data in a single expression.  \escript allows any mixture of constant, tagged and expanded data in a single expression.
272    
273  The \var{dump} method provides a possibility to save \Data objects to a file, for instance to restart a simulation  \Data objects can be written to disk files and read with \var{dump} and \var{load}, both of which use \netCDF.
274  or to save data for visualization. The file format uses \netCDF which commonly is using the file extension  Use these to save data for visualization, checkpoint/restart or simply to save and reuse data that was expensive to compute.
275  {\tt nc}. For instance to save the coordinates of the data points of the \FunctionSpace  
276  \ContinuousFunction to the file {\tt x.nc} one uses:  For instance to save the coordinates of the data points of the \FunctionSpace
277    \ContinuousFunction to the file {\tt x.nc} use
278  \begin{python}  \begin{python}
279  x=ContinuousFunction(mydomain).getX()    x=ContinuousFunction(mydomain).getX()
280  x.dump("x.nc")    x.dump("x.nc")
281  \end{python}  \end{python}
282  In order to keep the dump files small {\tt x.nc} does not contain a representation of the \Domain. It has to be saved using  To recover the object \var{x} use
 appropriate methods of \var{mydomain} to be loaded before \var{x}. Alternatively, the \Domain can be reconstructed.  
 To recover the object \var{x} one uses  
283  \begin{python}  \begin{python}
284  x=load("x.nc", mydomain)    x=load("x.nc", mydomain)
285  \end{python}  \end{python}
286  The \Data object represented by {\tt x.nc} is tight to a \FunctionSpace - in this case \ContinuousFunction - but not  The dump file {\tt x.nc} does not contain a representation of the \Domain, even though it is required to recreate \var{x}.
287  o a \Domain. That means that \Data objects that are constant or tagged can be recovered with any \Domain. If the \Data object  It's common to simply recreate the \Domain before reading a \Data, or you may read and write your \Domain in a separate file with
288    \var{domain=ReadMesh(fileName)} and \var{domain.write(fileName)}.
289    
290    The function space of the \Data is stored in {\tt x.nc}, though.
291    That means that \Data objects that are constant or tagged can be recovered with a different \Domain. If the \Data object
292  is expanded, the number of data points in the file and of the \Domain for the particular \FunctionSpace must match.  is expanded, the number of data points in the file and of the \Domain for the particular \FunctionSpace must match.
293  Moreover, the ordering of the value is checked using the reference identifiers provided by  Moreover, the ordering of the values is checked using the reference identifiers provided by
294  \FunctionSpace on the \Domain. In some cases, data points will be reordered.  \FunctionSpace on the \Domain. In some cases, data points will be re-ordered. Take care to be sure you get what you want!
295    
296    
297  \section{\escript Classes}  \section{\escript Classes}
# Line 447  for the solution approximation. Line 456  for the solution approximation.
456  \subsection{\Data Class}  \subsection{\Data Class}
457  \label{SEC ESCRIPT DATA}  \label{SEC ESCRIPT DATA}
458    
459  The following table shows binary and unitary operations that can be applied to  The following table shows arithmetic operations that can be performed point-wise on
460  \Data objects:  \Data objects.
461  \begin{tableii}{l|l}{textrm}{expression}{Description}  \begin{tableii}{l|l}{textrm}{expression}{Description}
462  \lineii{+\var{arg0}} {just \var{arg} \index{+}}  \lineii{+\var{arg0}} {identical to \var{arg} \index{+}}
463  \lineii{-\var{arg0}} {swapping the sign\index{-}}  \lineii{-\var{arg0}} {negation\index{-}}
464  \lineii{\var{arg0}+\var{arg1}} {adds \var{arg0} and \var{arg1} \index{+}}  \lineii{\var{arg0}+\var{arg1}} {adds \var{arg0} and \var{arg1} \index{+}}
465  \lineii{\var{arg0}*\var{arg1}} {multiplies \var{arg0} and \var{arg1} \index{*}}  \lineii{\var{arg0}*\var{arg1}} {multiplies \var{arg0} and \var{arg1} \index{*}}
466  \lineii{\var{arg0}-\var{arg1}} {difference \var{arg1} from\var{arg1} \index{-}}  \lineii{\var{arg0}-\var{arg1}} {difference \var{arg1} from\var{arg1} \index{-}}
467  \lineii{\var{arg0}/\var{arg1}} {ratio \var{arg0} by \var{arg1} \index{/}}  \lineii{\var{arg0}/\var{arg1}} {divide \var{arg0} by \var{arg1} \index{/}}
468  \lineii{\var{arg0}**\var{arg1}} {raises \var{arg0} to the power of \var{arg1} \index{**}}  \lineii{\var{arg0}**\var{arg1}} {raises \var{arg0} to the power of \var{arg1} \index{**}}
469  \end{tableii}  \end{tableii}
470  At least one of the arguments \var{arg0} or \var{arg1} must be a  At least one of the arguments \var{arg0} or \var{arg1} must be a
471  \Data object. One of the arguments may be an object that can be  \Data object.
472  converted into a \Data object. If \var{arg0} or \var{arg1} are  Either of the arguments may be a \Data object, a python number or a numarray object.
473  defined on different \FunctionSpace an attempt is made to embed \var{arg0}  
474  into the \FunctionSpace of \var{arg1} or to embed \var{arg1} into  If \var{arg0} or \var{arg1} are
475    defined on different \FunctionSpace an attempt is made to convert \var{arg0}
476    to the \FunctionSpace of \var{arg1} or to convert \var{arg1} to
477  the \FunctionSpace of \var{arg0}. Both arguments must have the same  the \FunctionSpace of \var{arg0}. Both arguments must have the same
478  \Shape or one of the arguments may be of rank 0. In the  \Shape or one of the arguments may be of rank 0 (a constant).
 latter case it is assumed that the particular argument is of the same  
 \Shape as the other argument but constant over all components.  
479    
480  The returned \Data object has the same \Shape and is defined on  The returned \Data object has the same \Shape and is defined on
481  the \DataSamplePoints as \var{arg0} or \var{arg1}.  the \DataSamplePoints as \var{arg0} or \var{arg1}.
# Line 489  components. \var{arg1} must be defined i Line 498  components. \var{arg1} must be defined i
498  \var{arg0} or it must be possible to interpolate \var{arg1} onto the  \var{arg0} or it must be possible to interpolate \var{arg1} onto the
499  \FunctionSpace of \var{arg1}.  \FunctionSpace of \var{arg1}.
500    
501  The \Data class supports getting slices as well as assigning new values to components in an existing  The \Data class supports taking slices from a \Data object as well as assigning new values to a slice of an existing
502  \Data object. \index{slicing}  \Data object. \index{slicing}
503  The following expression for getting (expression on the right hand side of the  The following expressions for taking and setting slices are valid:
 equal sign) and setting slices (expression on the left hand side of the  
 equal sign) are valid:  
504  \begin{tableiii}{l|ll}{textrm}{rank of \var{arg}}{slicing expression}{\Shape of returned and assigned object}  \begin{tableiii}{l|ll}{textrm}{rank of \var{arg}}{slicing expression}{\Shape of returned and assigned object}
505  \lineiii{0}{ no slicing }                      {-}  \lineiii{0}{ no slicing }                      {-}
506  \lineiii{1}{\var{arg[l0:u0]}}                   {(\var{u0}-\var{l0},)}  \lineiii{1}{\var{arg[l0:u0]}}                   {(\var{u0}-\var{l0},)}
# Line 512  Any of the upper indexes \var{u0}, \var{ Line 519  Any of the upper indexes \var{u0}, \var{
519  \var{s} is assumed. The lower and upper index may be identical, in which case the column and the lower or upper  \var{s} is assumed. The lower and upper index may be identical, in which case the column and the lower or upper
520  index may be dropped. In the returned or in the object assigned to a slice the corresponding component is dropped,  index may be dropped. In the returned or in the object assigned to a slice the corresponding component is dropped,
521  i.e. the rank is reduced by one in comparison to \var{arg}.  i.e. the rank is reduced by one in comparison to \var{arg}.
522  The following examples show slicing usage:    The following examples show slicing in action:
523  \begin{python}  \begin{python}
524  t=Data(1.,(4,4,6,6),Function(mydomain))    t=Data(1.,(4,4,6,6),Function(mydomain))
525  t[1,1,1,0]=9.    t[1,1,1,0]=9.
526  s=t[:2,:,2:6,5] # s has rank 3    s=t[:2,:,2:6,5] # s has rank 3
527  s[:,:,1]=1.    s[:,:,1]=1.
528  t[:2,:2,5,5]=s[2:4,1,:2]    t[:2,:2,5,5]=s[2:4,1,:2]
529  \end{python}  \end{python}
530    
531  \subsection{Generation of \Data class objects}  \subsection{Generation of \Data class objects}
# Line 531  the \Data object is represented in expan Line 538  the \Data object is represented in expan
538  \begin{classdesc}{Data}{value,what=FunctionSpace(),expand=\False}  \begin{classdesc}{Data}{value,what=FunctionSpace(),expand=\False}
539  creates a \Data object in the \FunctionSpace \var{what}.  creates a \Data object in the \FunctionSpace \var{what}.
540  The value for each \DataSamplePoints is set to \numarray, \Data object \var{value} or a dictionary of  The value for each \DataSamplePoints is set to \numarray, \Data object \var{value} or a dictionary of
541  \numarray or floating point numbers. In the latter case the keys muts be integers and are used  \numarray or floating point numbers. In the latter case the keys must be integers and are used
542  as tags.  as tags.
543  The \Shape of the returned object is equal to the \Shape of \var{value}. If \var{expanded} is \True  The \Shape of the returned object is equal to the \Shape of \var{value}. If \var{expanded} is \True
544  the \Data object is represented in expanded from.  the \Data object is represented in expanded form.
545  \end{classdesc}  \end{classdesc}
546    
547  \begin{classdesc}{Data}{}  \begin{classdesc}{Data}{}
# Line 543  where a \Data object is required. Line 550  where a \Data object is required.
550  \end{classdesc}  \end{classdesc}
551    
552  \begin{funcdesc}{Scalar}{value=0.,what=escript::FunctionSpace(),expand=\False}  \begin{funcdesc}{Scalar}{value=0.,what=escript::FunctionSpace(),expand=\False}
553  returns a \Data object of rank 0 in the \FunctionSpace \var{what}.  returns a \Data object of rank 0 (a constant) in the \FunctionSpace \var{what}.
554  Values are initialed with the double \var{value}. If \var{expanded} is \True  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
555  the \Data object is represented in expanded from.  the \Data object is represented in expanded from.
556  \end{funcdesc}  \end{funcdesc}
557    
558  \begin{funcdesc}{Vector}{value=0.,what=escript::FunctionSpace(),expand=\False}  \begin{funcdesc}{Vector}{value=0.,what=escript::FunctionSpace(),expand=\False}
559  returns a \Data object of \Shape \var{(d,)} in the \FunctionSpace \var{what}  returns a \Data object of \Shape \var{(d,)} in the \FunctionSpace \var{what}
560  where \var{d} is the spatial dimension of the \Domain of \var{what}.  where \var{d} is the spatial dimension of the \Domain of \var{what}.
561  Values are initialed with the double \var{value}. If \var{expanded} is \True  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
562  the \Data object is represented in expanded from.  the \Data object is represented in expanded from.
563  \end{funcdesc}  \end{funcdesc}
564    
565  \begin{funcdesc}{Tensor}{value=0.,what=escript::FunctionSpace(),expand=\False}  \begin{funcdesc}{Tensor}{value=0.,what=escript::FunctionSpace(),expand=\False}
566  returns a \Data object of \Shape \var{(d,d)} in the \FunctionSpace \var{what}  returns a \Data object of \Shape \var{(d,d)} in the \FunctionSpace \var{what}
567  where \var{d} is the spatial dimension of the \Domain of \var{what}.  where \var{d} is the spatial dimension of the \Domain of \var{what}.
568  Values are initialed with the double \var{value}. If \var{expanded} is \True  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
569  the \Data object is represented in expanded from.  the \Data object is represented in expanded from.
570  \end{funcdesc}  \end{funcdesc}
571    
572  \begin{funcdesc}{Tensor3}{value=0.,what=escript::FunctionSpace(),expand=\False}  \begin{funcdesc}{Tensor3}{value=0.,what=escript::FunctionSpace(),expand=\False}
573  returns a \Data object of \Shape \var{(d,d,d)} in the \FunctionSpace \var{what}  returns a \Data object of \Shape \var{(d,d,d)} in the \FunctionSpace \var{what}
574  where \var{d} is the spatial dimension of the \Domain of \var{what}.  where \var{d} is the spatial dimension of the \Domain of \var{what}.
575  Values are initialed with the double \var{value}. If \var{expanded} is \True  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
576  the \Data object is re\var{arg}presented in expanded from.  the \Data object is re\var{arg}presented in expanded from.
577  \end{funcdesc}  \end{funcdesc}
578    
579  \begin{funcdesc}{Tensor4}{value=0.,what=escript::FunctionSpace(),expand=\False}  \begin{funcdesc}{Tensor4}{value=0.,what=escript::FunctionSpace(),expand=\False}
580  returns a \Data object of \Shape \var{(d,d,d,d)} in the \FunctionSpace \var{what}  returns a \Data object of \Shape \var{(d,d,d,d)} in the \FunctionSpace \var{what}
581  where \var{d} is the spatial dimension of the \Domain of \var{what}.  where \var{d} is the spatial dimension of the \Domain of \var{what}.
582  Values are initialed with the double \var{value}. If \var{expanded} is \True  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
583  the \Data object is represented in expanded from.  the \Data object is represented in expanded from.
584  \end{funcdesc}  \end{funcdesc}
585    
586  \begin{funcdesc}{load}{filename,domain}  \begin{funcdesc}{load}{filename,domain}
587  recovers a \Data object on \Domain \var{domain} from the dump file \var{filename}.  recovers a \Data object on \Domain \var{domain} from the file \var{filename}, which was created by \var{dump}.
588  \end{funcdesc}  \end{funcdesc}
589    
590  \subsection{\Data class methods}  \subsection{\Data class methods}
591  This is a list of frequently used methods of the  These are the most frequently-used methods of the
592  \Data class. A complete list can be fond on \ReferenceGuide.  \Data class. A complete list of methods can be found on \ReferenceGuide.
593  \begin{methoddesc}[Data]{getFunctionSpace}{}  \begin{methoddesc}[Data]{getFunctionSpace}{}
594  returns the \FunctionSpace of the object.  returns the \FunctionSpace of the object.
595  \end{methoddesc}  \end{methoddesc}
# Line 635  A complete list and a more detailed desc Line 642  A complete list and a more detailed desc
642  writes \Data defined by keywords in the file with \var{filename} using the  writes \Data defined by keywords in the file with \var{filename} using the
643  vtk file format \VTK file format. The key word is used as an identifier. The statement  vtk file format \VTK file format. The key word is used as an identifier. The statement
644  \begin{python}  \begin{python}
645  saveVTK("out.xml",temperature=T,velocity=v)    saveVTK("out.xml",temperature=T,velocity=v)
646  \end{python}  \end{python}
647  will write the scalar \var{T} as \var{temperature} and the vector \var{v} as  \var{velocity} into the  will write the scalar \var{T} as \var{temperature} and the vector \var{v} as  \var{velocity} into the
648  file \file{out.xml}. Restrictions on the allowed combinations of \FunctionSpace apply.  file \file{out.xml}. Restrictions on the allowed combinations of \FunctionSpace apply.
# Line 644  file \file{out.xml}. Restrictions on the Line 651  file \file{out.xml}. Restrictions on the
651  writes \Data defined by keywords in the file with \var{filename} using the  writes \Data defined by keywords in the file with \var{filename} using the
652  vtk file format \OpenDX file format. The key word is used as an identifier. The statement  vtk file format \OpenDX file format. The key word is used as an identifier. The statement
653  \begin{python}  \begin{python}
654  saveDX("out.dx",temperature=T,velocity=v)    saveDX("out.dx",temperature=T,velocity=v)
655  \end{python}  \end{python}
656  will write the scalar \var{T} as \var{temperature} and the vector \var{v} as  \var{velocity} into the  will write the scalar \var{T} as \var{temperature} and the vector \var{v} as  \var{velocity} into the
657  file \file{out.dx}. Restrictions on the allowed combinations of \FunctionSpace apply.  file \file{out.dx}. Restrictions on the allowed combinations of \FunctionSpace apply.
Legend:
Removed from v.1317  
changed lines
  Added in v.1318
  ViewVC Help
Powered by ViewVC 1.1.26