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

revision 1956 by ksteube, Thu Sep 25 23:11:13 2008 UTC revision 1957 by jfenwick, Mon Nov 3 06:14:18 2008 UTC
# Line 17  Line 17
17
18
19  \begin{figure}  \begin{figure}
20  \includegraphics[width=\textwidth]{figures/EscriptDiagram1.eps}  \includegraphics[width=\textwidth]{figures/EscriptDiagram1}
21  \caption{\label{ESCRIPT DEP}Dependency of Function Spaces. An arrow indicates that a function in the  \caption{\label{ESCRIPT DEP}Dependency of Function Spaces. An arrow indicates that a function in the
22  function space at the starting point can be interpreted as a function in the function space of the arrow target.}  function space at the starting point can be interpreted as a function in the function space of the arrow target.}
23  \end{figure}  \end{figure}
# Line 29  provides what we call a function space t Line 29  provides what we call a function space t
29  used in the simulation.  Stored along with the data is information  used in the simulation.  Stored along with the data is information
30  about the elements and nodes which will be used by \finley.  about the elements and nodes which will be used by \finley.
31
32  In order to understand what we mean by the term 'function space'  In order to understand what we mean by the term 'function space',
33  consider that the solution of a partial differential equation  consider that the solution of a partial differential equation
34  \index{partial differential equation} (PDE) is a function on a domain  \index{partial differential equation} (PDE) is a function on a domain
35  $\Omega$.  When solving a PDE using FEM the solution is  $\Omega$.  When solving a PDE using FEM, the solution is
36  piecewise-differentiable but, in general, its gradient is  piecewise-differentiable but, in general, its gradient is
37  discontinuous.  To reflect these different degrees of smoothness  discontinuous.  To reflect these different degrees of smoothness,
38  different function spaces are used.  For instance, in FEM the  different function spaces are used.  For instance, in FEM, the
39  displacement field is represented by its values at the nodes of the  displacement field is represented by its values at the nodes of the
40  mesh, and is then continuous.  The strain, which is the symmetric  mesh, and so is continuous.  The strain, which is the symmetric
41  part of the gradient of the displacement field, is stored on the  part of the gradient of the displacement field, is stored on the
42  element centers, and so is considered to be discontinuous.  element centers, and so is considered to be discontinuous.
43
# Line 67  The location of discontinuity is defined Line 67  The location of discontinuity is defined
67  \fig{ESCRIPT DEP} shows the dependency between the types of function spaces.  \fig{ESCRIPT DEP} shows the dependency between the types of function spaces.
68
69  The solution of a PDE is a continuous function. Any continuous function can be seen as a general function  The solution of a PDE is a continuous function. Any continuous function can be seen as a general function
70  on the domain and can be restricted to the boundary as well as to any side of the  on the domain and can be restricted to the boundary as well as to one side of
71  discontinuity (the result will be different depending on  discontinuity (the result will be different depending on
72  which side is chosen). Functions on any side of the    which side is chosen). Functions on any side of the
73  discontinuity can be seen as a function on the corresponding other side.  discontinuity can be seen as a function on the corresponding other side.
# Line 110  number of indices, and a \Shape defining Line 110  number of indices, and a \Shape defining
110  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
111  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.
112  The \Shape of a \Data object is a tuple (list) \var{s} of integers. The length  The \Shape of a \Data object is a tuple (list) \var{s} of integers. The length
113  of \var{s} is the rank of the \Data object and \var{s[i]} is the maximum  of \var{s} is the rank of the \Data object and the \var{i}-th index ranges between $0$ and $\var{s[i]}-1$.
value for the \var{i}-th index.
114  For instance, a stress field has rank $2$ and  For instance, a stress field has rank $2$ and
115  \Shape $(d,d)$ where $d$ is the spatial dimension.  \Shape $(d,d)$ where $d$ is the spatial dimension.
116  The following statement creates the \Data object  The following statement creates the \Data object
# Line 126  all components. Line 125  all components.
125
126  \Data objects can also be created from any \numarray  \Data objects can also be created from any \numarray
127  array or any object, such as a list of floating point numbers,  array or any object, such as a list of floating point numbers,
128  that can be converted into a \numarray.NumArray \Ref{NUMARRAY}.  that can be converted into a \numarrayNA \cite{NUMARRAY}.
129  The following two statements  The following two statements
130  create objects which are equivalent to \var{mydat}:  create objects which are equivalent to \var{mydat}:
131  \begin{python}  \begin{python}
# Line 134  create objects which are equivalent to \ Line 133  create objects which are equivalent to \
133    mydat2=Data(value=[[1,1],[1,1],[1,1]],what=ContinuousFunction(myDomain))    mydat2=Data(value=[[1,1],[1,1],[1,1]],what=ContinuousFunction(myDomain))
134  \end{python}  \end{python}
135  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))}
136  which generates a $2 \times 3$ matrix as a \numarray.NumArray  which generates a $2 \times 3$ matrix as a \numarrayNA
137  filled with ones. The \Shape of the created \Data object  filled with ones. The \Shape of the created \Data object
138  it taken from the \Shape of the array. In the second  it taken from the \Shape of the array. In the second
139  case, the creator converts the initial value, which is a list of lists,  case, the creator converts the initial value, which is a list of lists,
140  and converts it into a \numarray.NumArray before creating the actual  and converts it into a \numarrayNA before creating the actual
141  \Data object.        \Data object.
142
143  For convenience \escript provides creators for the most common types  For convenience \escript provides creators for the most common types
144  of \Data objects in the following forms (\var{d} defines the  of \Data objects in the following forms (\var{d} defines the
145  spatial dimension):  spatial dimension):
146  \begin{itemize}  \begin{itemize}
147  \item \var{Scalar(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(,))},  \item \var{Scalar(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(,))} (each value is a scalar),
148  e.g a temperature field.  e.g a temperature field.
149  \item \var{Vector(0,Function(mydomain))}is the same as \var{Data(0,Function(myDomain),(d))}, e.g  \item \var{Vector(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d))} (each value is a vector), e.g
150  a velocity field.    a velocity field.
151  \item \var{Tensor(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d,d))},  \item \var{Tensor(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d,d))},
152  eg. a stress field.    eg. a stress field.
153  \item \var{Tensor4(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d,d,d,d))}  \item \var{Tensor4(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d,d,d,d))}
154  eg. a Hook tensor field.    eg. a Hook tensor field.
155  \end{itemize}  \end{itemize}
156  Here the initial value is $0$ but any object that can be converted into a \numarray.NumArray and whose \Shape  Here the initial value is $0$ but any object that can be converted into a \numarrayNA and whose \Shape
157  is consistent with \Shape of the \Data object to be created can be used as the initial value.  is consistent with \Shape of the \Data object to be created can be used as the initial value.
158
159  \Data objects can be manipulated by applying unitary operations (eg. cos, sin, log)  \Data objects can be manipulated by applying unary operations (eg. cos, sin, log) point
160  and can be combined point-wise by applying arithmetic operations (eg. +, - ,* , /).  and can be combined point-wise by applying arithmetic operations (eg. +, - ,* , /).
161  It is to be emphasized that \escript itself does not handle any spatial dependencies as  It is to be emphasized that \escript itself does not handle any spatial dependencies as
162  it does not know how values are interpreted by the processing PDE solver library.  it does not know how values are interpreted by the processing PDE solver library.
# Line 218  In the context of FEM this means the nod Line 217  In the context of FEM this means the nod
217  The interpolation is automatic and requires no special handling.  The interpolation is automatic and requires no special handling.
218
219  \begin{figure}  \begin{figure}
220  \includegraphics[width=\textwidth]{figures/EscriptDiagram2.eps}  \includegraphics[width=\textwidth]{figures/EscriptDiagram2}
221  \caption{\label{Figure: tag}Element Tagging. A rectangular mesh over a region with two rock types {\it white} and {\it gray}.  \caption{\label{Figure: tag}Element Tagging. A rectangular mesh over a region with two rock types {\it white} and {\it gray}.
222  The number in each cell refers to the major rock type present in the cell ($1$ for {\it white} and $2$ for {\it gray}).  The number in each cell refers to the major rock type present in the cell ($1$ for {\it white} and $2$ for {\it gray}).
223  }  }
# Line 231  shows an example. In this case two rock Line 230  shows an example. In this case two rock
230  is subdivided into triangular shaped cells. Each  is subdivided into triangular shaped cells. Each
231  cell has a tag indicating the rock type predominately found in this cell. Here $1$ is used to indicate  cell has a tag indicating the rock type predominately found in this cell. Here $1$ is used to indicate
232  rock type {\it white} and $2$ for rock type {\it gray}. The tags are assigned at the time when the cells are generated  rock type {\it white} and $2$ for rock type {\it gray}. The tags are assigned at the time when the cells are generated
233  and stored in the \Domain class object. To allow easier usage of tags names can be used. These names are typically defined  and stored in the \Domain class object. To allow easier usage of tags, names can be used instead of numbers. These names are typically defined
234  at the time when the geometry is generated.  at the time when the geometry is generated.
235
236  The following statements show how for the  The following statements show how, for the
237  example of \fig{Figure: tag} and the stress calculation discussed before tagged values are used for  example of \fig{Figure: tag}, the stress calculation discussed above and tagged values are used for
238  \var{lam}:  \var{lam}:
239  \begin{python}  \begin{python}
240    lam=Scalar(value=2.,what=Function(mydomain))    lam=Scalar(value=2.,what=Function(mydomain))
# Line 253  You can develop a simulation with consta Line 252  You can develop a simulation with consta
252  Lame coefficients without otherwise changing your python script.  Lame coefficients without otherwise changing your python script.
253  In short, you can use the same script to model with different domains and different types of input data.  In short, you can use the same script to model with different domains and different types of input data.
254
255  There are three ways in which \Data objects are represented internally: constant, tagged, and expanded.  There are three main ways in which \Data objects are represented internally: constant, tagged, and expanded.
256  In the constant case, the same value is used at each sample point and only a single value is stored to save memory.  In the constant case, the same value is used at each sample point and only a single value is stored to save memory.
257  In the expanded case, each sample point has an individual value (such as for the solution of a PDE).  In the expanded case, each sample point has an individual value (such as for the solution of a PDE).
258  This is where your largest data sets will be created because the values are stored as a complete array.  This is where your largest data sets will be created because the values are stored as a complete array.
# Line 263  Expanded data is created when you create Line 262  Expanded data is created when you create
262  Tagged data sets are created when you use the insertTaggedValue() method as shown above.  Tagged data sets are created when you use the insertTaggedValue() method as shown above.
263
264  Values are accessed through a sample reference number. Operations on expanded \Data  Values are accessed through a sample reference number. Operations on expanded \Data
265  objects have to be performed for each sample point individually. When tagged values are used the values are  objects have to be performed for each sample point individually. When tagged values are used, the values are
266  held in a dictionary. Operations on tagged data require processing the set of tagged values only, rather than  held in a dictionary. Operations on tagged data require processing the set of tagged values only, rather than
267  processing the value for each individual sample point.  processing the value for each individual sample point.
268  \escript allows any mixture of constant, tagged and expanded data in a single expression.  \escript allows any mixture of constant, tagged and expanded data in a single expression.
# Line 282  To recover the object \var{x} use Line 281  To recover the object \var{x} use
282  \end{python}  \end{python}
283  The dump file {\tt x.nc} does not contain a representation of the \Domain, even though it is required to recreate \var{x}.  The dump file {\tt x.nc} does not contain a representation of the \Domain, even though it is required to recreate \var{x}.
284  It's common to simply recreate the \Domain before reading a \Data, or you may read and write your \Domain in a separate file with  It is common to simply recreate the \Domain before reading a \Data, or you may read and write your \Domain in a separate file with
286
287  The function space of the \Data is stored in {\tt x.nc}, though.  The function space of the \Data is stored in {\tt x.nc}, though.
288  That means that \Data objects that are constant or tagged can be recovered with a different \Domain. If the \Data object  That means that \Data objects that are constant or tagged can be recovered with a different \Domain (provided that the domains use the same \FunctionSpace types).
289    If the \Data object
290  is expanded, the number of data points in the file and of the \Domain for the particular \FunctionSpace must match.  is expanded, the number of data points in the file and of the \Domain for the particular \FunctionSpace must match.
291  Moreover, the ordering of the values is checked using the reference identifiers provided by  Moreover, the ordering of the values is checked using the reference identifiers provided by
292  \FunctionSpace on the \Domain. In some cases, data points will be re-ordered. Take care to be sure you get what you want!  \FunctionSpace on the \Domain. In some cases, data points will be re-ordered. Take care to be sure you get what you want!
# Line 298  Moreover, the ordering of the values is Line 298  Moreover, the ordering of the values is
298
299  \subsection{\Domain class}  \subsection{\Domain class}
300  \begin{classdesc}{Domain}{}  \begin{classdesc}{Domain}{}
301  A \Domain object is used to describe a geometrical region together with  A \Domain object is used to describe a geometric region together with
302  a way of representing functions over this region.  a way of representing functions over this region.
303  The \Domain class provides an abstract access to the domain of \FunctionSpace and \Data objects.  The \Domain class provides an abstract representation of the domain of \FunctionSpace and \Data objects.
304  \Domain itself has no initialization but implementations of \Domain are  \Domain itself has no initialization but implementations of \Domain are
305  instantiated by numerical libraries making use of \Data objects.  instantiated by numerical libraries making use of \Data objects.
306  \end{classdesc}  \end{classdesc}
# Line 411  returns string representation of the \Do Line 411  returns string representation of the \Do
411  The following function provide generators for \FunctionSpace objects:  The following function provide generators for \FunctionSpace objects:
412  \begin{funcdesc}{Function}{domain}  \begin{funcdesc}{Function}{domain}
413  returns the \Function on the \Domain \var{domain}. \Data objects in this type of \Function  returns the \Function on the \Domain \var{domain}. \Data objects in this type of \Function
414  are defined over the whole geometrical region defined by \var{domain}.  are defined over the whole geometric region defined by \var{domain}.
415  \end{funcdesc}  \end{funcdesc}
416
417  \begin{funcdesc}{ContinuousFunction}{domain}  \begin{funcdesc}{ContinuousFunction}{domain}
418  returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function  returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function
419  are defined over the whole geometrical region defined by \var{domain} and assumed to represent  are defined over the whole geometric region defined by \var{domain} and assumed to represent
420  a continuous function.  a continuous function.
421  \end{funcdesc}  \end{funcdesc}
422
423  \begin{funcdesc}{FunctionOnBoundary}{domain}  \begin{funcdesc}{FunctionOnBoundary}{domain}
424  returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function  returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function
425  are defined on the boundary of the geometrical region defined by \var{domain}.  are defined on the boundary of the geometric region defined by \var{domain}.
426  \end{funcdesc}  \end{funcdesc}
427
428  \begin{funcdesc}{FunctionOnContactZero}{domain}  \begin{funcdesc}{FunctionOnContactZero}{domain}
429  returns the \FunctionOnContactZero the \Domain domain. \Data objects in this type of \Function  returns the \FunctionOnContactZero the \Domain domain. \Data objects in this type of \Function
430  are defined on side 0 of a discontinuity  within the geometrical region defined by \var{domain}.  are defined on side 0 of a discontinuity  within the geometric region defined by \var{domain}.
431  The discontinuity is defined when \var{domain} is instantiated.  The discontinuity is defined when \var{domain} is instantiated.
432  \end{funcdesc}  \end{funcdesc}
433
434  \begin{funcdesc}{FunctionOnContactOne}{domain}  \begin{funcdesc}{FunctionOnContactOne}{domain}
435  returns the \FunctionOnContactOne on the \Domain domain.  returns the \FunctionOnContactOne on the \Domain domain.
436  \Data objects in this type of \Function  \Data objects in this type of \Function
437  are defined on side 1 of a discontinuity  within the geometrical region defined by \var{domain}.  are defined on side 1 of a discontinuity  within the geometric region defined by \var{domain}.
438  The discontinuity is defined when \var{domain} is instantiated.  The discontinuity is defined when \var{domain} is instantiated.
439  \end{funcdesc}  \end{funcdesc}
440
441  \begin{funcdesc}{Solution}{domain}  \begin{funcdesc}{Solution}{domain}
442  returns the \SolutionFS on the \Domain domain. \Data objects in this type of \Function  returns the \SolutionFS on the \Domain domain. \Data objects in this type of \Function
443  are defined on geometrical region defined by \var{domain} and are solutions of  are defined on geometric region defined by \var{domain} and are solutions of
444  partial differential equations \index{partial differential equation}.  partial differential equations \index{partial differential equation}.
445  \end{funcdesc}  \end{funcdesc}
446
447  \begin{funcdesc}{ReducedSolution}{domain}  \begin{funcdesc}{ReducedSolution}{domain}
448  returns the \ReducedSolutionFS on the \Domain domain. \Data objects in this type of \Function  returns the \ReducedSolutionFS on the \Domain domain. \Data objects in this type of \Function
449  are defined on geometrical region defined by \var{domain} and are solutions of  are defined on geometric region defined by \var{domain} and are solutions of
450  partial differential equations \index{partial differential equation} with a reduced smoothness  partial differential equations \index{partial differential equation} with a reduced smoothness
451  for the solution approximation.  for the solution approximation.
452  \end{funcdesc}  \end{funcdesc}

Legend:
 Removed from v.1956 changed lines Added in v.1957