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

revision 97 by jgs, Tue Dec 14 05:39:33 2004 UTC revision 107 by jgs, Thu Jan 27 06:21:48 2005 UTC
# Line 1  Line 1
1
2  % $Id$  % $Id$
3
4  \chapter{The module \escript}  \chapter{The module \escript}
# Line 12  function space at the starting point can Line 13  function space at the starting point can
13  \end{figure}  \end{figure}
14
15  \escript is an extension of Python to handle functions represented by their values on  \escript is an extension of Python to handle functions represented by their values on
16  \DataSamplePoints. The \DataSamplePoints for the geometrical region on which  \DataSamplePoints for the geometrical region on which
17  the function is defined. The region as well as the method which is used  the function is defined. The region as well as the method which is used
18  to interpolate value on the \DataSamplePoints is defined by      to interpolate value on the \DataSamplePoints is defined by
19  \Domain class objects. For instance when using  \Domain class objects. For instance when using
# Line 38  PDE solutions on the \Domain \var{mydoma Line 39  PDE solutions on the \Domain \var{mydoma
39  \begin{python}  \begin{python}
40  solution_space=Solution(mydomain)  solution_space=Solution(mydomain)
41  \end{python}  \end{python}
42  The following generators for function spaces on a \Domain \var{mydomin} are available:  The following generators for function spaces on a \Domain \var{mydomain} are available:
43  \begin{itemize}  \begin{itemize}
44  \item \var{Solution(mydomain)}: solutions of a PDE.    \item \var{Solution(mydomain)}: solutions of a PDE.
45  \item \var{ContinuousFunction(mydomain)}: continuous functions, eg. a temperature distribution.  \item \var{ContinuousFunction(mydomain)}: continuous functions, eg. a temperature distribution.
# Line 77  will typically lead to a change of its r Line 78  will typically lead to a change of its r
78  So, when seen as a general function,  So, when seen as a general function,
79  a continuous function which is typically represented by its values  a continuous function which is typically represented by its values
80  on the node of the FEM mesh or finite difference grid  on the node of the FEM mesh or finite difference grid
81  has to be interpolated to the element centers or the cell edges,  must be interpolated to the element centers or the cell edges,
82  respectively.  respectively.
83
84  \Data class objects store functions of the location in a domain.  \Data class objects store functions of the location in a domain.
# Line 89  of the PDEs to be solved by a PDE solver Line 90  of the PDEs to be solved by a PDE solver
90  and to store the returned solutions.  and to store the returned solutions.
91
92  The values of the function have a rank which gives the  The values of the function have a rank which gives the
93  number of indexes, and a \Shape defining the range of each index.  number of indices, and a \Shape defining the range of each index.
94  The rank in \escript is limited to the range $0$ through $4$ and  The rank in \escript is limited to the range $0$ through $4$ and
95  it is assumed that the rank and \Shape is the same for all \DataSamplePoints.  it is assumed that the rank and \Shape is the same for all \DataSamplePoints.
96  The \Shape of a \Data object is a tuple \var{s} of integers. The length  The \Shape of a \Data object is a tuple \var{s} of integers. The length
# Line 121  which generates a $2 \times 3$ matrix as Line 122  which generates a $2 \times 3$ matrix as
122  filled with ones. The \Shape of the created \Data object  filled with ones. The \Shape of the created \Data object
123  it taken from the \Shape of the array. In the second  it taken from the \Shape of the array. In the second
124  case, the creator converts the initial value, which is a list of lists,  case, the creator converts the initial value, which is a list of lists,
125  and converts it into a \numarray array before creating the actuall  and converts it into a \numarray array before creating the actual
126  \Data object.        \Data object.
127
128  For convenience \escript provides creators for the most common types  For convenience \escript provides creators for the most common types
# Line 141  Here the initial value is $0$ but any ob Line 142  Here the initial value is $0$ but any ob
142  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.
143
144  \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)
145  and be combined by applying binary operations (eg. +, - ,* , /).  and can be combined by applying binary operations (eg. +, - ,* , /).
146  It is to be emphasized that \escript itself does not handle any spatial dependencies itself as  It is to be emphasized that \escript itself does not handle any spatial dependencies as
147  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.
148  However \escript invokes interpolation if this is needed during data manipulations.  However \escript invokes interpolation if this is needed during data manipulations.
149  Typically, this occurs in binary operation when both arguments belong to different  Typically, this occurs in binary operation when both arguments belong to different
# Line 252  processing the value for each individual Line 253  processing the value for each individual
253  \section{\Domain class}  \section{\Domain class}
254
255  \begin{classdesc}{Domain}{}  \begin{classdesc}{Domain}{}
256  A \Domain objects is used to describe a geometrical region together with  A \Domain object is used to describe a geometrical region together with
257  a way of representing functions over this region.  a way of representing functions over this region.
258  The \Domain class provides an abstract access to the domain of \FunctionSpace and \Data objects.  The \Domain class provides an abstract access to the domain of \FunctionSpace and \Data objects.
259  \Domain itself has no initialization but implementations of \Domain are  \Domain itself has no initialization but implementations of \Domain are
# Line 379  for the solution approximation. Line 380  for the solution approximation.
380  \end{funcdesc}  \end{funcdesc}
381
382  \section{\Data Class}  \section{\Data Class}
383    \label{SEC ESCRIPT DATA}
384
385  The following table shows binary and unitary operations that can be applied to  The following table shows binary and unitary operations that can be applied to
386  \Data objects:  \Data objects:
# Line 392  The following table shows binary and uni Line 393  The following table shows binary and uni
393  \lineii{\var{arg1}/\var{arg2}} {ratio \var{arg1} by \var{arg2} \index{/}}  \lineii{\var{arg1}/\var{arg2}} {ratio \var{arg1} by \var{arg2} \index{/}}
394  \lineii{\var{arg1}**\var{arg2}} {raises \var{arg1} to the power of \var{arg2} \index{**}}  \lineii{\var{arg1}**\var{arg2}} {raises \var{arg1} to the power of \var{arg2} \index{**}}
395  \end{tableii}  \end{tableii}
396  At least on of the arguments \var{arg1} or \var{arg2} must be a  At least one of the arguments \var{arg1} or \var{arg2} must be a
397  \Data object. One of the arguments may be an object that can be  \Data object. One of the arguments may be an object that can be
398  converted into a \Data object. If \var{arg1} or \var{arg2} are  converted into a \Data object. If \var{arg1} or \var{arg2} are
399  defined on different \FunctionSpace it is tried to embed \var{arg1}  defined on different \FunctionSpace an attempt is made to embed \var{arg1}
400  into the \FunctionSpace of \var{arg2} or to embed \var{arg2} into  into the \FunctionSpace of \var{arg2} or to embed \var{arg2} into
401  the \FunctionSpace of \var{arg1}. Boths arguments must have the same  the \FunctionSpace of \var{arg1}. Boths arguments must have the same
402  \Shape or one of the arguments my be of rank 0 or \Shape (1,). In the  \Shape or one of the arguments my be of rank 0 or \Shape (1,). In the
403  latter case it is assumed that the particular argument is of the same  latter case it is assumed that the particular argument is of the same
404  \Shape like the other argument but constant over all components.  \Shape as the other argument but constant over all components.
405
406  The returned \Data object has the same \Shape and is defined on  The returned \Data object has the same \Shape and is defined on
407  the \DataSamplePoints like \var{arg1} or \var{arg2}.  the \DataSamplePoints as \var{arg1} or \var{arg2}.
408
409  The following table shows the update operations that can be applied to  The following table shows the update operations that can be applied to
410  \Data objects:  \Data objects:
# Line 418  The following table shows the update ope Line 419  The following table shows the update ope
419  \Data object. \var{arg1} must have the same \Shape like  \Data object. \var{arg1} must have the same \Shape like
420  \var{arg1} or has rank 0 or \Shape (1,).  In the latter case it is  \var{arg1} or has rank 0 or \Shape (1,).  In the latter case it is
421  assumed that the values of \var{arg1} are constant for all  assumed that the values of \var{arg1} are constant for all
422  components. \var{arg2} must be defined on the same \DataSamplePoints like  components. \var{arg2} must be defined on the same \DataSamplePoints as
423  \var{arg1} or it must be possible to interpolate \var{arg2} onto the  \var{arg1} or it must be possible to interpolate \var{arg2} onto the
424  \DataSamplePoints where \var{arg1} is hold.  \DataSamplePoints where \var{arg1} is held.
425
426  The \Data class supports getting slices as well as assigning new values to components in an existing  The \Data class supports getting slices as well as assigning new values to components in an existing
427  \Data object \index{slicing}.  \Data object. \index{slicing}
428  The following expression for getting (expression on the right hand side of the  The following expression for getting (expression on the right hand side of the
429  equal sign) and setting slices (expression on the left hand side of the  equal sign) and setting slices (expression on the left hand side of the
430  equal sign) are valid:  equal sign) are valid:
# Line 445  Any of the upper indexes \var{u0}, \var{ Line 446  Any of the upper indexes \var{u0}, \var{
446  \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
447  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,
448  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}.
449  The follwing examples showing the usage of slicing:    The following examples show slicing usage:
450  \begin{python}  \begin{python}
451  t[1,1,1,0]=9.  t[1,1,1,0]=9.
452  s=t[:2,:,2:6,5] # s has rank 3  s=t[:2,:,2:6,5] # s has rank 3

Legend:
 Removed from v.97 changed lines Added in v.107