/[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 1958 by jfenwick, Mon Nov 3 06:14:18 2008 UTC revision 1959 by jfenwick, Tue Nov 4 01:49:19 2008 UTC
# Line 285  It is common to simply recreate the \Dom Line 285  It is common to simply recreate the \Dom
285  \var{domain=ReadMesh(fileName)} and \var{domain.write(fileName)}.  \var{domain=ReadMesh(fileName)} and \var{domain.write(fileName)}.
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 (provided that the domains use the same \FunctionSpace types).  That means that \Data objects that are constant or tagged can be recovered with a different \Domain\footnote{This is provided that the domains use the same \FunctionSpace types.}.
289  If the \Data object  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
# Line 300  Moreover, the ordering of the values is Line 300  Moreover, the ordering of the values is
300  \begin{classdesc}{Domain}{}  \begin{classdesc}{Domain}{}
301  A \Domain object is used to describe a geometric 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 representation of the domain of \FunctionSpace and \Data objects.  The \Domain class provides an abstract interface to the domain of \FunctionSpace and \Data objects.
304  \Domain itself has no initialization but implementations of \Domain are  \Domain needs to be subclassed in order to provide a complete implementation.
 instantiated by numerical libraries making use of \Data objects.  
305  \end{classdesc}  \end{classdesc}
306  The following methods are available:  The following methods are available:
307  \begin{methoddesc}[Domain]{getDim}{}  \begin{methoddesc}[Domain]{getDim}{}
# Line 340  return \True if \var{tag_name} is a vali Line 339  return \True if \var{tag_name} is a vali
339  \end{methoddesc}  \end{methoddesc}
340    
341  \begin{methoddesc}[Domain]{__eq__}{arg}  \begin{methoddesc}[Domain]{__eq__}{arg}
342  returns \True of the \Domain \var{arg} describes the same domain. Otherwise  (python == operator) returns \True if the \Domain \var{arg} describes the same domain. Otherwise
343  \False is returned.  \False is returned.
344  \end{methoddesc}  \end{methoddesc}
345    
346  \begin{methoddesc}[Domain]{__ne__}{arg}  \begin{methoddesc}[Domain]{__ne__}{arg}
347  returns \True of the \Domain \var{arg} does not describe the same domain.  (python != operator) returns \True if the \Domain \var{arg} does not describe the same domain.
348  Otherwise \False is returned.  Otherwise \False is returned.
349  \end{methoddesc}  \end{methoddesc}
350    
351  \begin{methoddesc}[Domain]{__str__}{g}  \begin{methoddesc}[Domain]{__str__}{g}
352  returns string representation of the \Domain.  (python str() function) returns string representation of the \Domain.
353  \end{methoddesc}  \end{methoddesc}
354    
355  \subsection{\FunctionSpace class}  \subsection{\FunctionSpace class}
# Line 395  Use the \var{setTagMap} to assign a tag Line 394  Use the \var{setTagMap} to assign a tag
394  \end{methoddesc}  \end{methoddesc}
395    
396  \begin{methoddesc}[FunctionSpace]{__eq__}{arg}  \begin{methoddesc}[FunctionSpace]{__eq__}{arg}
397  returns \True of the \Domain \var{arg} describes the same domain. Otherwise  (python == operator) returns \True if the \Domain \var{arg} describes the same domain. Otherwise
398  \False is returned.  \False is returned.
399  \end{methoddesc}  \end{methoddesc}
400    
401  \begin{methoddesc}[FunctionSpace]{__ne__}{arg}  \begin{methoddesc}[FunctionSpace]{__ne__}{arg}
402  returns \True of the \Domain \var{arg} describes the note same domain.  (python != operator) returns \True if the \Domain \var{arg} do not describe the same domain.
403  Otherwise \False is returned.  Otherwise \False is returned.
404  \end{methoddesc}  \end{methoddesc}
405    
406  \begin{methoddesc}[Domain]{__str__}{g}  \begin{methoddesc}[Domain]{__str__}{g}
407  returns string representation of the \Domain.  (python str() function) returns string representation of the \Domain.
408  \end{methoddesc}  \end{methoddesc}
409    
410  The following function provide generators for \FunctionSpace objects:  The following function provide generators for \FunctionSpace objects:
# Line 470  At least one of the arguments \var{arg0} Line 469  At least one of the arguments \var{arg0}
469  Either of the arguments may be a \Data object, a python number or a numarray object.  Either of the arguments may be a \Data object, a python number or a numarray object.
470    
471  If \var{arg0} or \var{arg1} are  If \var{arg0} or \var{arg1} are
472  defined on different \FunctionSpace an attempt is made to convert \var{arg0}  not defined on the same \FunctionSpace, then an attempt is made to convert \var{arg0}
473  to the \FunctionSpace of \var{arg1} or to convert \var{arg1} to  to the \FunctionSpace of \var{arg1} or to convert \var{arg1} to
474  the \FunctionSpace of \var{arg0}. Both arguments must have the same  the \FunctionSpace of \var{arg0}. Both arguments must have the same
475  \Shape or one of the arguments may be of rank 0 (a constant).  \Shape or one of the arguments may be of rank 0 (a constant).
# Line 489  The following table shows the update ope Line 488  The following table shows the update ope
488  \end{tableii}  \end{tableii}
489  \var{arg0} must be a \Data object. \var{arg1} must be a  \var{arg0} must be a \Data object. \var{arg1} must be a
490  \Data object or an object that can be converted into a  \Data object or an object that can be converted into a
491  \Data object. \var{arg1} must have the same \Shape like  \Data object. \var{arg1} must have the same \Shape as
492  \var{arg1} or has rank 0.  In the latter case it is  \var{arg0} or have rank 0.  In the latter case it is
493  assumed that the values of \var{arg1} are constant for all  assumed that the values of \var{arg1} are constant for all
494  components. \var{arg1} must be defined in the same \FunctionSpace as  components. \var{arg1} must be defined in the same \FunctionSpace as
495  \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
496  \FunctionSpace of \var{arg1}.  \FunctionSpace of \var{arg0}.
497    
498  The \Data class supports taking slices from a \Data object as well as assigning new values to a slice of an existing  The \Data class supports taking slices from a \Data object as well as assigning new values to a slice of an existing
499  \Data object. \index{slicing}  \Data object. \index{slicing}
# Line 506  The following expressions for taking and Line 505  The following expressions for taking and
505  \lineiii{3}{\var{arg[l0:u0,l1:u1,l2:u2]} }      {(\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2})}  \lineiii{3}{\var{arg[l0:u0,l1:u1,l2:u2]} }      {(\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2})}
506  \lineiii{4}{\var{arg[l0:u0,l1:u1,l2:u2,l3:u3]}} {(\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2},\var{u3}-\var{l3})}  \lineiii{4}{\var{arg[l0:u0,l1:u1,l2:u2,l3:u3]}} {(\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2},\var{u3}-\var{l3})}
507  \end{tableiii}  \end{tableiii}
508  where  where \var{s} is the \Shape of \var{arg} and
509  $0 \le \var{l0} \le \var{u0} \le \var{s[0]}$,  \[0 \le \var{l0} \le \var{u0} \le \var{s[0]},\]
510  $0 \le \var{l1} \le \var{u1} \le \var{s[1]}$,  \[0 \le \var{l1} \le \var{u1} \le \var{s[1]},\]
511  $0 \le \var{l2} \le \var{u2} \le \var{s[2]}$,  \[0 \le \var{l2} \le \var{u2} \le \var{s[2]},\]
512  $0 \le \var{l3} \le \var{u3} \le \var{s[3]}$ and \var{s} the \Shape if \var{arg}.  \[0 \le \var{l3} \le \var{u3} \le \var{s[3]}.\]
513  Any of the lower indexes \var{l0}, \var{l1}, \var{l2} and \var{l3} may not be present in which case  Any of the lower indexes \var{l0}, \var{l1}, \var{l2} and \var{l3} may not be present in which case
514  $0$ is assumed.  $0$ is assumed.
515  Any of the upper indexes \var{u0}, \var{u1}, \var{u2} and \var{u3} may not be present in which case  Any of the upper indexes \var{u0}, \var{u1}, \var{u2} and \var{u3} may be ommitted, in which case, the upper limit for that dimension is assumed.
516  \var{s} is assumed. The lower and upper index may be identical, in which case the column and the lower or upper  The lower and upper index may be identical, in which case the column and the lower or upper
517  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,
518  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}.
519  The following examples show slicing in action:  The following examples show slicing in action:
520  \begin{python}  \begin{python}
# Line 526  The following examples show slicing in a Line 525  The following examples show slicing in a
525    t[:2,:2,5,5]=s[2:4,1,:2]    t[:2,:2,5,5]=s[2:4,1,:2]
526  \end{python}  \end{python}
527    
528  \subsection{Generation of \Data class objects}  \subsection{Generation of \Data objects}
529  \begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expand=\False}  \begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expand=\False}
530  creates a \Data object with \Shape \var{shape} in the \FunctionSpace \var{what}.  creates a \Data object with \Shape \var{shape} in the \FunctionSpace \var{what}.
531  The values at all \DataSamplePoints are set to the double value \var{value}. If \var{expanded} is \True  The values at all \DataSamplePoints are set to the double value \var{value}. If \var{expanded} is \True
# Line 535  the \Data object is represented in expan Line 534  the \Data object is represented in expan
534    
535  \begin{classdesc}{Data}{value,what=FunctionSpace(),expand=\False}  \begin{classdesc}{Data}{value,what=FunctionSpace(),expand=\False}
536  creates a \Data object in the \FunctionSpace \var{what}.  creates a \Data object in the \FunctionSpace \var{what}.
537  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 \var{value}, which could be a \numarray, \Data object \var{value} or a dictionary of
538  \numarray or floating point numbers. In the latter case the keys must be integers and are used  \numarray or floating point numbers. In the latter case the keys must be integers and are used
539  as tags.  as tags.
540  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
# Line 547  creates an \EmptyData object. The \Empty Line 546  creates an \EmptyData object. The \Empty
546  where a \Data object is required.  where a \Data object is required.
547  \end{classdesc}  \end{classdesc}
548    
549  \begin{funcdesc}{Scalar}{value=0.,what=escript::FunctionSpace(),expand=\False}  \begin{funcdesc}{Scalar}{value=0.,what=FunctionSpace(),expand=\False}
550  returns a \Data object of rank 0 (a constant) in the \FunctionSpace \var{what}.  returns a \Data object of rank 0 (a constant) in the \FunctionSpace \var{what}.
551  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True  Values are initialised with \var{value}, a double precision quantity. If \var{expanded} is \True
552  the \Data object is represented in expanded from.  the \Data object is represented in expanded from.
553  \end{funcdesc}  \end{funcdesc}
554    
555  \begin{funcdesc}{Vector}{value=0.,what=escript::FunctionSpace(),expand=\False}  \begin{funcdesc}{Vector}{value=0.,what=FunctionSpace(),expand=\False}
556  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},
557  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}.
558  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
559  the \Data object is represented in expanded from.  the \Data object is represented in expanded from.
560  \end{funcdesc}  \end{funcdesc}
561    
562  \begin{funcdesc}{Tensor}{value=0.,what=escript::FunctionSpace(),expand=\False}  \begin{funcdesc}{Tensor}{value=0.,what=FunctionSpace(),expand=\False}
563  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},
564  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}.
565  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
566  the \Data object is represented in expanded from.  the \Data object is represented in expanded from.
567  \end{funcdesc}  \end{funcdesc}
568    
569  \begin{funcdesc}{Tensor3}{value=0.,what=escript::FunctionSpace(),expand=\False}  \begin{funcdesc}{Tensor3}{value=0.,what=FunctionSpace(),expand=\False}
570  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},
571  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}.
572  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True
573  the \Data object is re\var{arg}presented in expanded from.  the \Data object is re\var{arg}presented in expanded from.
574  \end{funcdesc}  \end{funcdesc}
575    
576  \begin{funcdesc}{Tensor4}{value=0.,what=escript::FunctionSpace(),expand=\False}  \begin{funcdesc}{Tensor4}{value=0.,what=FunctionSpace(),expand=\False}
577  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},
578  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}.
579  Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True  Values are initialised with \var{value}, a double precision quantity. If \var{expanded} is \True
580  the \Data object is represented in expanded from.  the \Data object is represented in expanded from.
581  \end{funcdesc}  \end{funcdesc}
582    
# Line 585  the \Data object is represented in expan Line 584  the \Data object is represented in expan
584  recovers a \Data object on \Domain \var{domain} from the file \var{filename}, which was created by \var{dump}.  recovers a \Data object on \Domain \var{domain} from the file \var{filename}, which was created by \var{dump}.
585  \end{funcdesc}  \end{funcdesc}
586    
587  \subsection{\Data class methods}  \subsection{\Data methods}
588  These are the most frequently-used methods of the  These are the most frequently-used methods of the
589  \Data class. A complete list of methods can be found on \ReferenceGuide.  \Data class. A complete list of methods can be found on \ReferenceGuide.
590  \begin{methoddesc}[Data]{getFunctionSpace}{}  \begin{methoddesc}[Data]{getFunctionSpace}{}
# Line 608  returns the rank of the data on each dat Line 607  returns the rank of the data on each dat
607  \begin{methoddesc}[Data]{isEmpty}{}  \begin{methoddesc}[Data]{isEmpty}{}
608  returns \True id the \Data object is the \EmptyData object.  returns \True id the \Data object is the \EmptyData object.
609  Otherwise \False is returned.  Otherwise \False is returned.
610    Note that this is not the same as asking if the object contains no \DataSamplePoints.
611  \end{methoddesc}  \end{methoddesc}
612    
613  \begin{methoddesc}[Data]{setTaggedValue}{tag_name,value}  \begin{methoddesc}[Data]{setTaggedValue}{tag_name,value}
# Line 633  save the \Domain. Line 633  save the \Domain.
633  returns a string representation of the object.  returns a string representation of the object.
634  \end{methoddesc}  \end{methoddesc}
635    
636  \subsection{Functions of \Data class objects}  \subsection{Functions of \Data objects}
637  This section lists the most important functions for \Data class objects \var{a}.  This section lists the most important functions for \Data class objects \var{a}.
638  A complete list and a more detailed description of the functionality can be fond on \ReferenceGuide.  A complete list and a more detailed description of the functionality can be found on \ReferenceGuide.
639  \begin{funcdesc}{saveVTK}{filename,**kwdata}  \begin{funcdesc}{saveVTK}{filename,**kwdata}
640  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
641  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
# Line 667  returns a \RankTwo \Data object in \Func Line 667  returns a \RankTwo \Data object in \Func
667  If \var{d} is an integer a $(d,d)$ \numarray array is returned.  If \var{d} is an integer a $(d,d)$ \numarray array is returned.
668  \end{funcdesc}  \end{funcdesc}
669  \begin{funcdesc}{identityTensor}{d}  \begin{funcdesc}{identityTensor}{d}
670  returns a \RankTwo \Data object in \FunctionSpace \var{d} such that  is a synonym for \code{kronecker} (see above).
671  \begin{equation}  % returns a \RankTwo \Data object in \FunctionSpace \var{d} such that
672  \code{identityTensor(d)}\left[ i,j\right] = \left\{  % \begin{equation}
673  \begin{array}{cc}  % \code{identityTensor(d)}\left[ i,j\right] = \left\{
674  1 & \mbox{ if } i=j \\  % \begin{array}{cc}
675  0 & \mbox{ otherwise }  % 1 & \mbox{ if } i=j \\
676  \end{array}  % 0 & \mbox{ otherwise }
677  \right.  % \end{array}
678  \end{equation}  % \right.
679  If \var{d} is an integer a $(d,d)$ \numarray array is returned.  % \end{equation}
680    % If \var{d} is an integer a $(d,d)$ \numarray array is returned.
681  \end{funcdesc}  \end{funcdesc}
682  \begin{funcdesc}{identityTensor4}{d}  \begin{funcdesc}{identityTensor4}{d}
683  returns a \RankFour \Data object in \FunctionSpace \var{d} such that  returns a \RankFour \Data object in \FunctionSpace \var{d} such that
# Line 819  returns at each \DataSamplePoints the ma Line 820  returns at each \DataSamplePoints the ma
820  \end{funcdesc}  \end{funcdesc}
821    
822  \begin{funcdesc}{length}{a}  \begin{funcdesc}{length}{a}
823  returns at Euclidean norm at each \DataSamplePoints. For a \RankFour function \var{a} this is  returns at Euclidean norm at each \DataSamplePoints. For a \RankFour \var{a} this is
824  \begin{equation}  \begin{equation}
825  \code{length(a)}=\sqrt{\sum\hackscore{ijkl} \var{a} \left[i,j,k,l\right]^2}  \code{length(a)}=\sqrt{\sum\hackscore{ijkl} \var{a} \left[i,j,k,l\right]^2}
826  \end{equation}  \end{equation}
# Line 1066  returns the $L^2$-norm of \var{a} in its Line 1067  returns the $L^2$-norm of \var{a} in its
1067  The \Operator class provides an abstract access to operators build  The \Operator class provides an abstract access to operators build
1068  within the \LinearPDE class. \Operator objects are created  within the \LinearPDE class. \Operator objects are created
1069  when a PDE is handed over to a PDE solver library and handled  when a PDE is handed over to a PDE solver library and handled
1070  by the \LinearPDE class defining the PDE. The user can gain access  by the \LinearPDE object defining the PDE. The user can gain access
1071  to the \Operator of a \LinearPDE object through the \var{getOperator}  to the \Operator of a \LinearPDE object through the \var{getOperator}
1072  method.  method.
1073    

Legend:
Removed from v.1958  
changed lines
  Added in v.1959

  ViewVC Help
Powered by ViewVC 1.1.26