escript/py_src/util.py

# $Id$
#
#      COPYRIGHT ACcESS 2004 -  All Rights Reserved
#
#   This software is the property of ACcESS.  No part of this code
#   may be copied in any form or by any means without the expressed written
#   consent of ACcESS.  Copying, use or modification of this software
#   by any unauthorised person is illegal unless that
#   person has a software license agreement with ACcESS.
#

"""
Utility functions for escript

@remark:  This module is under construction and is still tested!!!

@var __author__: name of author
@var __licence__: licence agreement
@var __url__: url entry point on documentation
@var __version__: version
@var __date__: date of the version
"""
                                                                                                                                                                                                     
__author__="Lutz Gross, l.gross@uq.edu.au"
__licence__="contact: esys@access.uq.edu.au"
__url__="http://www.iservo.edu.au/esys/escript"
__version__="$Revision$"
__date__="$Date$"


import math
import numarray
import escript
import os

# missing tests:

# def pokeShape(arg):
# def pokeDim(arg):
# def commonShape(arg0,arg1):
# def commonDim(*args):
# def testForZero(arg):
# def matchType(arg0=0.,arg1=0.):
# def matchShape(arg0,arg1):

# def transpose(arg,axis=None):
# def trace(arg,axis0=0,axis1=1):
# def reorderComponents(arg,index):

# def integrate(arg,where=None):
# def interpolate(arg,where):
# def div(arg,where=None):
# def grad(arg,where=None):

#
# slicing: get
#          set
#
# and derivatives

#=========================================================
#   some helpers:
#=========================================================
def saveVTK(filename,domain=None,**data):
    """
    writes a L{Data} objects into a files using the the VTK XML file format.

    Example:

       tmp=Scalar(..)
       v=Vector(..)
       saveVTK("solution.xml",temperature=tmp,velovity=v)

    tmp and v are written into "solution.xml" where tmp is named "temperature" and v is named "velovity"

    @param filename: file name of the output file
    @type filename: C{str}
    @param domain: domain of the L{Data} object. If not specified, the domain of the given L{Data} objects is used.
    @type domain: L{escript.Domain}
    @keyword <name>: writes the assigned value to the VTK file using <name> as identifier.
    @type <name>: L{Data} object.
    @note: The data objects have to be defined on the same domain. They may not be in the same L{FunctionSpace} but one cannot expect that all L{FunctionSpace} can be mixed. Typically, data on the boundary and data on the interior cannot be mixed.
    """
    if domain==None:
       for i in data.keys():
          if not data[i].isEmpty(): domain=data[i].getFunctionSpace().getDomain()
    if domain==None:
        raise ValueError,"no domain detected."
    else:
        domain.saveVTK(filename,data)

def saveDX(filename,domain=None,**data):
    """
    writes a L{Data} objects into a files using the the DX file format.

    Example:

       tmp=Scalar(..)
       v=Vector(..)
       saveDX("solution.dx",temperature=tmp,velovity=v)

    tmp and v are written into "solution.dx" where tmp is named "temperature" and v is named "velovity".

    @param filename: file name of the output file
    @type filename: C{str}
    @param domain: domain of the L{Data} object. If not specified, the domain of the given L{Data} objects is used.
    @type domain: L{escript.Domain}
    @keyword <name>: writes the assigned value to the DX file using <name> as identifier. The identifier can be used to select the data set when data are imported into DX.
    @type <name>: L{Data} object.
    @note: The data objects have to be defined on the same domain. They may not be in the same L{FunctionSpace} but one cannot expect that all L{FunctionSpace} can be mixed. Typically, data on the boundary and data on the interior cannot be mixed.
    """
    if domain==None:
       for i in data.keys():
          if not data[i].isEmpty(): domain=data[i].getFunctionSpace().getDomain()
    if domain==None:
        raise ValueError,"no domain detected."
    else:
        domain.saveDX(filename,data)

def kronecker(d=3):
   """
   return the kronecker S{delta}-symbol

   @param d: dimension or an object that has the C{getDim} method defining the dimension
   @type d: C{int} or any object with a C{getDim} method
   @return: the object u of rank 2 with M{u[i,j]=1} for M{i=j} and M{u[i,j]=0} otherwise
   @rtype d: L{numarray.NumArray} of rank 2.
   @remark: the function is identical L{identity}
   """
   return identityTensor(d)

def identity(shape=()):
   """
   return the shape x shape identity tensor

   @param shape: input shape for the identity tensor
   @type shape: C{tuple} of C{int}
   @return: array of shape shape x shape with M{u[i,k]=1} for M{i=k} and M{u[i,k]=0} otherwise for len(shape)=1 and, for len(shape)=2: M{u[i,j,k,l]=1} for M{i=k and j=l} and M{u[i,j,k,l]=0} otherwise.
   @rtype: L{numarray.NumArray} of rank 1, rankk 2 or rank 4.
   @raise ValueError: if len(shape)>2.
   """
   if len(shape)>0:
      out=numarray.zeros(shape+shape,numarray.Float)
      if len(shape)==1:
          for i0 in range(shape[0]):
             out[i0,i0]=1.

      elif len(shape)==2:
          for i0 in range(shape[0]):
             for i1 in range(shape[1]):
                out[i0,i1,i0,i1]=1.
      else:
          raise ValueError,"identity: length of shape is restricted to 2."
   else:
      out=1.
   return out

def identityTensor(d=3):
   """
   return the dxd identity matrix

   @param d: dimension or an object that has the C{getDim} method defining the dimension
   @type d: C{int} or any object with a C{getDim} method
   @return: the object u of rank 2 with M{u[i,j]=1} for M{i=j} and M{u[i,j]=0} otherwise
   @rtype: L{numarray.NumArray} of rank 2.
   """
   if hasattr(d,"getDim"):
      d=d.getDim()
   return identity(shape=(d,))

def identityTensor4(d=3):
   """
   return the dxdxdxd identity tensor

   @param d: dimension or an object that has the C{getDim} method defining the dimension
   @type d: C{int} or any object with a C{getDim} method
   @return: the object u of rank 4 with M{u[i,j,k,l]=1} for M{i=k and j=l} and M{u[i,j,k,l]=0} otherwise
   @rtype: L{numarray.NumArray} of rank 4.
   """
   if hasattr(d,"getDim"):
      d=d.getDim()
   return identity((d,d))

def unitVector(i=0,d=3):
   """
   return a unit vector u of dimension d with nonzero index i:

   @param i: index 
   @type i: C{int} 
   @param d: dimension or an object that has the C{getDim} method defining the dimension
   @type d: C{int} or any object with a C{getDim} method
   @return: the object u of rank 1 with M{u[j]=1} for M{j=i} and M{u[i]=0} otherwise
   @rtype: L{numarray.NumArray} of rank 1.
   """
   return kronecker(d)[i]

#=========================================================================
#   global reduction operations (these functions have no symbolic version)
#=========================================================================
def Lsup(arg):
    """
    returns the Lsup-norm of argument arg. This is the maximum absolute value over all data points. 
    This function is equivalent to sup(abs(arg)).

    @param arg: argument
    @type arg: C{float}, C{int}, L{escript.Data}, L{numarray.NumArray}.
    @return: maximum value of the absolute value of arg over all components and all data points
    @rtype: C{float}
    @raise TypeError: if type of arg cannot be processed
    """
    if isinstance(arg,numarray.NumArray):
        return sup(abs(arg))
    elif isinstance(arg,escript.Data):
        return arg._Lsup()
    elif isinstance(arg,float):
        return abs(arg)
    elif isinstance(arg,int):
        return abs(float(arg))
    else:
      raise TypeError,"Lsup: Unknown argument type."

def sup(arg):
    """
    returns the maximum value over all data points. 

    @param arg: argument
    @type arg: C{float}, C{int}, L{escript.Data}, L{numarray.NumArray}.
    @return: maximum value of arg over all components and all data points
    @rtype: C{float}
    @raise TypeError: if type of arg cannot be processed
    """
    if isinstance(arg,numarray.NumArray):
        return arg.max()
    elif isinstance(arg,escript.Data):
        return arg._sup()
    elif isinstance(arg,float):
        return arg
    elif isinstance(arg,int):
        return float(arg)
    else:
      raise TypeError,"sup: Unknown argument type."

def inf(arg):
    """
    returns the maximum value over all data points. 

    @param arg: argument
    @type arg: C{float}, C{int}, L{escript.Data}, L{numarray.NumArray}.
    @return : minimum value of arg over all components and all data points
    @rtype: C{float}
    @raise TypeError: if type of arg cannot be processed
    """
    if isinstance(arg,numarray.NumArray):
        return arg.min()
    elif isinstance(arg,escript.Data):
        return arg._inf()
    elif isinstance(arg,float):
        return arg
    elif isinstance(arg,int):
        return float(arg)
    else:
      raise TypeError,"inf: Unknown argument type."


#=========================================================================
#   some little helpers
#=========================================================================
def pokeShape(arg):
    """
    identifies the shape of its argument

    @param arg: a given object 
    @type arg: L{numarray.NumArray},L{escript.Data},C{float}, C{int}, C{Symbol}
    @return: the shape of the argument
    @rtype: C{tuple} of C{int}
    @raise TypeError: if type of arg cannot be processed
    """

    if isinstance(arg,numarray.NumArray):
        return arg.shape
    elif isinstance(arg,escript.Data):
        return arg.getShape()
    elif isinstance(arg,float):
        return ()
    elif isinstance(arg,int):
        return ()
    elif isinstance(arg,Symbol):
        return arg.getShape()
    else:
      raise TypeError,"pokeShape: cannot identify shape"

def pokeDim(arg):
    """
    identifies the spatial dimension of its argument

    @param arg: a given object 
    @type arg: any
    @return: the spatial dimension of the argument, if available, or C{None}
    @rtype: C{int} or C{None}
    """

    if isinstance(arg,escript.Data):
        return arg.getFunctionSpace().getDim()
    elif isinstance(arg,Symbol):
        return arg.getDim()
    else:
        return None

def commonShape(arg0,arg1):
    """
    returns a shape to which arg0 can be extendent from the right and arg1 can be extended from the left.

    @param arg0: an object with a shape (see L{pokeShape})
    @param arg1: an object with a shape (see L{pokeShape})
    @return: the shape of arg0 or arg1 such that the left port equals the shape of arg0 and the right end equals the shape of arg1.
    @rtype: C{tuple} of C{int}
    @raise ValueError: if no shape can be found.
    """
    sh0=pokeShape(arg0)
    sh1=pokeShape(arg1)
    if len(sh0)<len(sh1):
       if not sh0==sh1[:len(sh0)]:
             raise ValueError,"argument 0 cannot be extended to the shape of argument 1"
       return sh1
    elif len(sh0)>len(sh1):
       if not sh1==sh0[:len(sh1)]:
             raise ValueError,"argument 1 cannot be extended to the shape of argument 0"
       return sh0
    else:
       if not sh0==sh1:
             raise ValueError,"argument 1 and argument 0 have not the same shape."
       return sh0

def commonDim(*args):
    """
    identifies, if possible, the spatial dimension across a set of objects which may or my not have a spatial dimension.

    @param *args: given objects
    @return: the spatial dimension of the objects with identifiable dimension (see L{pokeDim}). If none the objects has 
             a spatial dimension C{None} is returned.
    @rtype: C{int} or C{None}
    @raise ValueError: if the objects with identifiable dimension don't have the same spatial dimension.
    """
    out=None
    for a in args:
       d=pokeDim(a)
       if not out==None:
          if not (d==None or out==d):
             raise ValueError,"dimension of arguments don't match"
       else:
          out=d
    return out

def testForZero(arg):
    """
    test the argument for being identical to Zero

    @param arg: a given object 
    @type arg: typically L{numarray.NumArray},L{escript.Data},C{float}, C{int}
    @return : True if the argument is identical to zero.
    @rtype : C{bool}
    """
    if isinstance(arg,numarray.NumArray):
       return not Lsup(arg)>0.
    elif isinstance(arg,escript.Data):
       return False
    elif isinstance(arg,float):
       return not Lsup(arg)>0.
    elif isinstance(arg,int):
       return not Lsup(arg)>0.
    elif isinstance(arg,Symbol):
       return False
    else:
       return False

def matchType(arg0=0.,arg1=0.):
    """
    converting arg0 and arg1 both to the same type L{numarray.NumArray} or L{escript.Data} or, if one of arg0 or arg1 is of type L{Symbol}, the other one to be of type L{numarray.NumArray} or L{escript.Data}.

    @param arg0: first argument 
    @type arg0: L{numarray.NumArray},L{escript.Data},C{float}, C{int}, C{Symbol}
    @param arg1: second argument 
    @type arg1: L{numarray.NumArray},L{escript.Data},C{float}, C{int}, C{Symbol}
    @return: a tuple representing arg0 and arg1 with the same type or with one of them being a L{Symbol} 
    @rtype: C{tuple} of two L{numarray.NumArray}, two L{escript.Data}, a C{Symbol} and one of the types L{numarray.NumArray} or L{escript.Data}.  
    @raise TypeError: if type of arg0 or arg1 cannot be processed
    """
    if isinstance(arg0,numarray.NumArray):
       if isinstance(arg1,numarray.NumArray):
          pass
       elif isinstance(arg1,escript.Data):
          arg0=escript.Data(arg0,arg1.getFunctionSpace())
       elif isinstance(arg1,float):
          arg1=numarray.array(arg1)
       elif isinstance(arg1,int):
          arg1=numarray.array(float(arg1))
       elif isinstance(arg1,Symbol):
          pass
       else:
          raise TypeError,"function: Unknown type of second argument."    
    elif isinstance(arg0,escript.Data):
       if isinstance(arg1,numarray.NumArray):
          arg1=escript.Data(arg1,arg0.getFunctionSpace())
       elif isinstance(arg1,escript.Data):
          pass
       elif isinstance(arg1,float):
          arg1=escript.Data(arg1,(),arg0.getFunctionSpace())
       elif isinstance(arg1,int):
          arg1=escript.Data(float(arg1),(),arg0.getFunctionSpace())
       elif isinstance(arg1,Symbol):
          pass
       else:
          raise TypeError,"function: Unknown type of second argument."    
    elif isinstance(arg0,Symbol):
       if isinstance(arg1,numarray.NumArray):
          pass
       elif isinstance(arg1,escript.Data):
          pass
       elif isinstance(arg1,float):
          arg1=numarray.array(arg1)
       elif isinstance(arg1,int):
          arg1=numarray.array(float(arg1))
       elif isinstance(arg1,Symbol):
          pass
       else:
          raise TypeError,"function: Unknown type of second argument."    
    elif isinstance(arg0,float):
       if isinstance(arg1,numarray.NumArray):
          arg0=numarray.array(arg0)
       elif isinstance(arg1,escript.Data):
          arg0=escript.Data(arg0,arg1.getFunctionSpace())
       elif isinstance(arg1,float):
          arg0=numarray.array(arg0)
          arg1=numarray.array(arg1)
       elif isinstance(arg1,int):
          arg0=numarray.array(arg0)
          arg1=numarray.array(float(arg1))
       elif isinstance(arg1,Symbol):
          arg0=numarray.array(arg0)
       else:
          raise TypeError,"function: Unknown type of second argument."    
    elif isinstance(arg0,int):
       if isinstance(arg1,numarray.NumArray):
          arg0=numarray.array(float(arg0))
       elif isinstance(arg1,escript.Data):
          arg0=escript.Data(float(arg0),arg1.getFunctionSpace())
       elif isinstance(arg1,float):
          arg0=numarray.array(float(arg0))
          arg1=numarray.array(arg1)
       elif isinstance(arg1,int):
          arg0=numarray.array(float(arg0))
          arg1=numarray.array(float(arg1))
       elif isinstance(arg1,Symbol):
          arg0=numarray.array(float(arg0))
       else:
          raise TypeError,"function: Unknown type of second argument."    
    else:
      raise TypeError,"function: Unknown type of first argument."    

    return arg0,arg1

def matchShape(arg0,arg1):
    """
    

    If shape is not given the shape "largest" shape of args is used.

    @param args: a given ob
    @type arg: typically L{numarray.NumArray},L{escript.Data},C{float}, C{int}
    @return: True if the argument is identical to zero.
    @rtype: C{list} of C{int}
    """
    sh=commonShape(arg0,arg1)
    sh0=pokeShape(arg0)
    sh1=pokeShape(arg1)
    if len(sh0)<len(sh):
       return outer(arg0,numarray.ones(sh[len(sh0):],numarray.Float)),arg1
    elif len(sh1)<len(sh):
       return arg0,outer(arg1,numarray.ones(sh[len(sh1):],numarray.Float))
    else: 
       return arg0,arg1
#=========================================================
#   symbolic tool box starts here:
#=========================================================
class Symbol(object):
   """
   Symbol class. 

   Symbol class objects provide the same functionality as L{numarray.NumArray} and L{escript.Data} objects 
   but they do not have a value and therefore cannot be plotted or visualize. The main purpose is the possibilty 
   calculate derivatives with respect to other Symbols used to define a Symbol.
 
   """
   def __init__(self,shape=(),args=[],dim=None):
       """
       Creates an instance of a symbol of a given shape. The symbol may depending on a list of arguments args which may be
       symbols or any other object.

       @param arg: the arguments of the symbol.
       @type arg: C{list}
       @param shape: the shape 
       @type shape: C{tuple} of C{int}
       @param dim: spatial dimension of the symbol. If dim=C{None} the spatial dimension is undefined.  
       @type dim: C{None} or C{int}  

       """
       if len(shape)>4:
           raise ValueError,"Symbol supports only tensors up to order 4"
       self.__args=args
       self.__shape=shape
       self.__dim=dim

   def getArgument(self,i=None):
       """
       returns the i-th argument of the symbol

       @param i: index of the argument requested. 
       @type i: C{int} or C{None}
       @raise IndexError: if the requested index does not exist
       @return: the vlaue of the i-th argument or i is not specified the list of all arguments.
       @rtype: a single object or a list of objects 
       """
       if i==None:
          return self.__args
       else:
          if i<0 or i>=len(self.__args):
             raise IndexError,"there are only %s arguments"%len(self.__args)
          return self.__args[i]

   def getRank(self):
       """
       the rank of the symbol 

       @return: the rank of the symbol. This is length of the shape
       @rtype: C{int}
       """
       return len(self.getShape())

   def getShape(self):
       """
       the shape of the symbol.

       @return : the shape of the symbol. 
       @rtype: C{tuple} of C{int}
       """
       return self.__shape

   def getDim(self):
       """
       the spatial dimension

       @return : the spatial dimension
       @rtype: C{int} if the dimension is defined. Otherwise C{None} is returned.
       """
       return self.__dim
   
   def __str__(self):
       """
       a string representation of the symbol.
       @return: a string representation of the object
       @rtype: C{str}
       """
       args=[]
       for arg in self.getArgument():
          args.append(str(arg))
       try:
           out=self.getMyCode(args,format="str")
       except NotImplementedError:
           out="<Symbol %s>"%id(self)
       return out
       
   def getSubstitutedArguments(self,argvals):
       """
       substitutes symbols in the arguments of this object and returns the result as a list.

       @param argvals: L{Symbols} and their substitutes. The L{Symbol} u in the expression defining this object is replaced by argvals[u]. 
       @type argvals: C{dict} with keywords of type L{Symbol}.
       @rtype: C{list} of objects
       @return: list of the object assigned to the arguments through substitution or for the arguments which are not L{Symbols} the value assigned to the argument at instantiation.
       """
       out=[]
       for a in self.getArgument():
          if isinstance(a,Symbol):
             out.append(a.substitute(argvals))
          else:
             out.append(a)
       return out

   def getDifferentiatedArguments(self,arg):
       """
       applifies differentials to the arguments of this object and returns the result as a list.

       @param arg: the derivative is calculated with respect to arg
       @type arg: typically L{escript.Symbol} but can also be C{float}, L{escript.Data}, L{numarray.NumArray} depending the involved functions and data.
       @rtype: C{list} of objects
       @return: list of object obtained by calculating the derivatives of the argumenst with respct to arg
       """
       out=[]
       for a in self.getArgument():
          if isinstance(a,Symbol):
             out.append(a.substitute(argvals))
          else:
              s=pokeShape(s)+arg.getShape()
              if len(s)>0:
                 out.append(numarray.zeros(s),numarray.Float)
              else:
                 out.append(a)
       return out

   def isAppropriateValue(self,arg):
      """
      checks if the given argument arg can be used as a substitution of this object. The method checks 
      the shape of arg and, if the spatial dimension is defined, the spatial dimension of arg.    

      @param arg: a given object 
      @type arg: L{numarray.NumArray},L{escript.Data},C{float}, C{int}, C{Symbol}
      @return: True if arg is a suitbale object to be used for substitution. Otherwise False is returned.
      @rtype: C{bool}
      """
      if isinstance(arg,numarray.NumArray):
          return arg.shape==self.getShape()
      elif isinstance(arg,escript.Data):
          if self.getDim()==None:
              return arg.getShape()==self.getShape()
          elif self.getDim()==arg.getFunctionSpace().getDim():
              return arg.getShape()==self.getShape()
          else:
              return False
      elif isinstance(arg,Symbol):
          if self.getDim()==None:
              return arg.getShape()==self.getShape()
          elif self.getDim()==arg.getDim():
              return arg.getShape()==self.getShape()
          else:
              return False
      elif isinstance(arg,float):
          return ()==self.getShape()
      elif isinstance(arg,int):
          return ()==self.getShape()
      else:
         return False

   def getMyCode(self,argstrs,format="escript"):
       """
       returns a program code that can be used to evaluate the symbol.

       @param argstrs: gives for each argument a string representing the argument for the evaluation. 
       @type argstrs: C{list} of C{str}.
       @param format: specifies the format to be used. At the moment only "escript", "str" and "text" are supported.
       @type format: C{str}
       @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
       @rtype: C{str}
       @raise NotImplementedError: if no implementation for the given format is available
       @note: This method has to be overwritten by subclasses.
       """
       raise NotImplementedError,"no code for %s representation available"%format

   def substitute(self,argvals):
      """  
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object. 

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @note: this method has to be overwritten by a particular L{Symbol}
      @raise NotImplementedError: if no implementation for the given format is available
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"Symbol: new value is not appropriate."
      else:
         raise NotImplementedError,"no substitution in %s avialable"%str(self)

   def diff(self,arg):
       """
       returns the derivative of the symbol with respect to L{Symbol} arg

       @param arg: the derivative is calculated with respect to arg
       @type arg: typically L{escript.Symbol} but can also be C{float}, L{escript.Data}, L{numarray.NumArray} depending the involved functions and data.
       @return: derivative with respect to C{arg}
       @rtype: typically L{escript.Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
       @note: this method is overwritten by a particular L{Symbol}
       """
       if arg==self:
          return identity(self.getShape())
       else:
          s=self.getShape()+arg.getShape()
          if len(s)>0:
             return numarray.zeros(s,numarray.Float)
          else:
             return 0.

   def __neg__(self):
       """
       returns -self.

       @return:  a S{Symbol} representing the negative of the object
       @rtype: L{DependendSymbol}
       """
       return self*(-1.)

   def __pos__(self):
       """
       returns +self.

       @return:  a S{Symbol} representing the positive of the object
       @rtype: L{DependendSymbol}
       """
       return self*(1.)

   def __abs__(self):
       """
       returns a S{Symbol} representing the absolute value of the object.
       """
       return Abs_Symbol(self)

   def __add__(self,other):
       """
       add another object to this object

       @param other: object to be added to this object
       @type other: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray}.
       @return:  a S{Symbol} representing the sum of this object and C{other}
       @rtype: L{DependendSymbol}
       """
       return add(self,other)

   def __radd__(self,other):
       """
       add this object to another object

       @param other: object this object is added to
       @type other: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray}.
       @return: a S{Symbol} representing the sum of C{other} and this object object
       @rtype: L{DependendSymbol}
       """
       return add(other,self)

   def __sub__(self,other):
       """
       subtracts another object from this object

       @param other: object to be subtracted from this object
       @type other: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray}.
       @return: a S{Symbol} representing the difference of C{other} and this object 
       @rtype: L{DependendSymbol}
       """
       return add(self,-other)

   def __rsub__(self,other):
       """
       subtracts this object from another object

       @param other: object this object is been subtracted from
       @type other: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray}.
       @return: a S{Symbol} representing the difference of this object and C{other}.
       @rtype: L{DependendSymbol}
       """
       return add(-self,other)

   def __mul__(self,other):
       """
       multiplies this object with other object

       @param other: object to be mutiplied by this object
       @type other: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray}.
       @return: a S{Symbol} representing the product of the object and C{other}.
       @rtype: L{DependendSymbol} or 0 if other is identical to zero.
       """
       return mult(self,other)

   def __rmul__(self,other):
       """
       multiplies this object with other object

       @param other: object this object is multiplied with
       @type other: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray}.
       @return: a S{Symbol} representing the product of C{other} and the object.
       @rtype: L{DependendSymbol} or 0 if other is identical to zero.
       """
       return mult(other,self)

   def __div__(self,other):
       """
       divides this object by other object

       @param other: object dividing this object
       @type other: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray}.
       @return: a S{Symbol} representing the quotient of this object and C{other}
       @rtype: L{DependendSymbol} 
       """
       return quotient(self,other)

   def __rdiv__(self,other):
       """
       divides this object by other object

       @param other: object dividing this object
       @type other: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray}.
       @return: a S{Symbol} representing the quotient of C{other} and this object
       @rtype: L{DependendSymbol} or 0 if C{other} is identical to zero.
       """
       return quotient(other,self)

   def __pow__(self,other):
       """
       raises this object to the power of other

       @param other: exponent
       @type other: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray}.
       @return: a S{Symbol} representing the power of this object to C{other}
       @rtype: L{DependendSymbol} or 1 if C{other} is identical to zero.
       """
       return power(self,other)

   def __rpow__(self,other):
       """
       raises an object to the power of this object

       @param other: basis 
       @type other: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray}.
       @return: a S{Symbol} representing the power of C{other} to this object
       @rtype: L{DependendSymbol} or 0 if C{other} is identical to zero.
       """
       return power(other,self)

class DependendSymbol(Symbol):
   """
   DependendSymbol extents L{Symbol} by modifying the == operator to allow two instances to be equal. 
   Two DependendSymbol are equal if they have the same shape, the same arguments and one of them has an unspecified spatial dimension or the spatial dimension is identical  
   
   Example: 
   
   u1=Symbol(shape=(3,4),dim=2,args=[4.])
   u2=Symbol(shape=(3,4),dim=2,args=[4.])
   print u1==u2
   False
   
      but   

   u1=DependendSymbol(shape=(3,4),dim=2,args=[4.])
   u2=DependendSymbol(shape=(3,4),dim=2,args=[4.])
   u3=DependendSymbol(shape=(2,),dim=2,args=[4.])   
   print u1==u2, u1==u3
   True False

   @note: DependendSymbol should be used as return value of functions with L{Symbol} arguments. This will allow the optimizer to remove redundant function calls. 
   """
   def __eq__(self,other):
      """
      checks if other equals self

      @param other: any object
      @return: True if other has the same class like self, and the shape, the spatial diemsnion and the arguments are equal.
      @rtype: C{bool}
      """
      if isinstance(other,DependendSymbol):
         if self.__class__==other.__class__:  
            if self.getShape()==other.getShape():
              if self.getArgument()==other.getArgument():
                 if self.getDim()==None or other.getDim()==None or self.getDim()==other.getDim():
                    return True
      return False

   def __ne__(self,other):
      """
      checks if other equals self

      @param other: any object
      @return: Flase if other has the same class like self, and the shape, the spatial diemsnion and the arguments are equal.
      @rtype: C{bool}
      """
      return not self==other
#=========================================================
#  Unary operations prserving the shape
#========================================================
def log10(arg):
   """
   returns base-10 logarithm of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.log10(arg)
   elif isinstance(arg,escript.Data):
      return arg._log10()
   elif isinstance(arg,float):
      return math.log10(arg)
   elif isinstance(arg,int):
      return math.log10(float(arg))
   elif isinstance(arg,Symbol):
      return log(arg)/log(10.)
   else:
      raise TypeError,"log10: Unknown argument type."

def wherePositive(arg):
   """
   returns mask of positive values of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      out=numarray.greater(arg,numarray.zeros(arg.shape,numarray.Float))*1.
      if isinstance(out,float): out=numarray.array(out)
      return out
   elif isinstance(arg,escript.Data):
      return arg._wherePositive()
   elif isinstance(arg,float):
      if arg>0:
        return 1.
      else:
        return 0.
   elif isinstance(arg,int):
      if arg>0:
        return 1.
      else:
        return 0.
   elif isinstance(arg,Symbol):
      return WherePositive_Symbol(arg)
   else:
      raise TypeError,"wherePositive: Unknown argument type."

class WherePositive_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the mask of positive values function
   """
   def __init__(self,arg):
      """
      initialization of wherePositive L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "wherePositive(%s)"%argstrs
      else:
         raise NotImplementedError,"WherePositive_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return wherePositive(arg)

def whereNegative(arg):
   """
   returns mask of positive values of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      out=numarray.less(arg,numarray.zeros(arg.shape,numarray.Float))*1.
      if isinstance(out,float): out=numarray.array(out)
      return out
   elif isinstance(arg,escript.Data):
      return arg._whereNegative()
   elif isinstance(arg,float):
      if arg<0:
        return 1.
      else:
        return 0.
   elif isinstance(arg,int):
      if arg<0:
        return 1.
      else:
        return 0.
   elif isinstance(arg,Symbol):
      return WhereNegative_Symbol(arg)
   else:
      raise TypeError,"whereNegative: Unknown argument type."

class WhereNegative_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the mask of positive values function
   """
   def __init__(self,arg):
      """
      initialization of whereNegative L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "whereNegative(%s)"%argstrs
      else:
         raise NotImplementedError,"WhereNegative_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return whereNegative(arg)

def whereNonNegative(arg):
   """
   returns mask of non-negative values of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      out=numarray.greater_equal(arg,numarray.zeros(arg.shape,numarray.Float))*1.
      if isinstance(out,float): out=numarray.array(out)
      return out
   elif isinstance(arg,escript.Data):
      return arg._whereNonNegative()
   elif isinstance(arg,float):
      if arg<0:
        return 0.
      else:
        return 1.
   elif isinstance(arg,int):
      if arg<0:
        return 0.
      else:
        return 1.
   elif isinstance(arg,Symbol):
      return 1.-whereNegative(arg)
   else:
      raise TypeError,"whereNonNegative: Unknown argument type."

def whereNonPositive(arg):
   """
   returns mask of non-positive values of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      out=numarray.less_equal(arg,numarray.zeros(arg.shape,numarray.Float))*1.
      if isinstance(out,float): out=numarray.array(out)
      return out
   elif isinstance(arg,escript.Data):
      return arg._whereNonPositive()
   elif isinstance(arg,float):
      if arg>0:
        return 0.
      else:
        return 1.
   elif isinstance(arg,int):
      if arg>0:
        return 0.
      else:
        return 1.
   elif isinstance(arg,Symbol):
      return 1.-wherePositive(arg)
   else:
      raise TypeError,"whereNonPositive: Unknown argument type."

def whereZero(arg,tol=0.):
   """
   returns mask of zero entries of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @param tol: tolerance. values with absolute value less then tol are accepted as zero.
   @type tol: C{float}
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      out=numarray.less_equal(abs(arg)-tol,numarray.zeros(arg.shape,numarray.Float))*1.
      if isinstance(out,float): out=numarray.array(out)
      return out
   elif isinstance(arg,escript.Data):
      if tol>0.:
         return whereNegative(abs(arg)-tol)
      else:
         return arg._whereZero()
   elif isinstance(arg,float):
      if abs(arg)<=tol:
        return 1.
      else:
        return 0.
   elif isinstance(arg,int):
      if abs(float(arg))<=tol:
        return 1.
      else:
        return 0.
   elif isinstance(arg,Symbol):
      return WhereZero_Symbol(arg,tol)
   else:
      raise TypeError,"whereZero: Unknown argument type."

class WhereZero_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the mask of zero entries function
   """
   def __init__(self,arg,tol=0.):
      """
      initialization of whereZero L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg,tol],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if format=="escript" or format=="str"  or format=="text":
         return "whereZero(%s,tol=%s)"%(argstrs[0],argstrs[1])
      else:
         raise NotImplementedError,"WhereZero_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)
         return whereZero(arg[0],arg[1])

def whereNonZero(arg,tol=0.):
   """
   returns mask of values different from zero of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      out=numarray.greater(abs(arg)-tol,numarray.zeros(arg.shape,numarray.Float))*1.
      if isinstance(out,float): out=numarray.array(out)
      return out
   elif isinstance(arg,escript.Data):
      if tol>0.:
         return 1.-whereZero(arg,tol)
      else:
         return arg._whereNonZero()
   elif isinstance(arg,float):
      if abs(arg)>tol:
        return 1.
      else:
        return 0.
   elif isinstance(arg,int):
      if abs(float(arg))>tol:
        return 1.
      else:
        return 0.
   elif isinstance(arg,Symbol):
      return 1.-whereZero(arg,tol)
   else:
      raise TypeError,"whereNonZero: Unknown argument type."

def sin(arg):
   """
   returns sine of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.sin(arg)
   elif isinstance(arg,escript.Data):
      return arg._sin()
   elif isinstance(arg,float):
      return math.sin(arg)
   elif isinstance(arg,int):
      return math.sin(arg)
   elif isinstance(arg,Symbol):
      return Sin_Symbol(arg)
   else:
      raise TypeError,"sin: Unknown argument type."

class Sin_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the sine function
   """
   def __init__(self,arg):
      """
      initialization of sin L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "sin(%s)"%argstrs
      else:
         raise NotImplementedError,"Sin_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return sin(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(cos(myarg),self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def cos(arg):
   """
   returns cosine of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.cos(arg)
   elif isinstance(arg,escript.Data):
      return arg._cos()
   elif isinstance(arg,float):
      return math.cos(arg)
   elif isinstance(arg,int):
      return math.cos(arg)
   elif isinstance(arg,Symbol):
      return Cos_Symbol(arg)
   else:
      raise TypeError,"cos: Unknown argument type."

class Cos_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the cosine function
   """
   def __init__(self,arg):
      """
      initialization of cos L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "cos(%s)"%argstrs
      else:
         raise NotImplementedError,"Cos_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return cos(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(-sin(myarg),self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def tan(arg):
   """
   returns tangent of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.tan(arg)
   elif isinstance(arg,escript.Data):
      return arg._tan()
   elif isinstance(arg,float):
      return math.tan(arg)
   elif isinstance(arg,int):
      return math.tan(arg)
   elif isinstance(arg,Symbol):
      return Tan_Symbol(arg)
   else:
      raise TypeError,"tan: Unknown argument type."

class Tan_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the tangent function
   """
   def __init__(self,arg):
      """
      initialization of tan L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "tan(%s)"%argstrs
      else:
         raise NotImplementedError,"Tan_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return tan(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(1./cos(myarg)**2,self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def asin(arg):
   """
   returns inverse sine of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.arcsin(arg)
   elif isinstance(arg,escript.Data):
      return arg._asin()
   elif isinstance(arg,float):
      return math.asin(arg)
   elif isinstance(arg,int):
      return math.asin(arg)
   elif isinstance(arg,Symbol):
      return Asin_Symbol(arg)
   else:
      raise TypeError,"asin: Unknown argument type."

class Asin_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the inverse sine function
   """
   def __init__(self,arg):
      """
      initialization of asin L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "asin(%s)"%argstrs
      else:
         raise NotImplementedError,"Asin_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return asin(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(1./sqrt(1.-myarg**2),self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def acos(arg):
   """
   returns inverse cosine of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.arccos(arg)
   elif isinstance(arg,escript.Data):
      return arg._acos()
   elif isinstance(arg,float):
      return math.acos(arg)
   elif isinstance(arg,int):
      return math.acos(arg)
   elif isinstance(arg,Symbol):
      return Acos_Symbol(arg)
   else:
      raise TypeError,"acos: Unknown argument type."

class Acos_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the inverse cosine function
   """
   def __init__(self,arg):
      """
      initialization of acos L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "acos(%s)"%argstrs
      else:
         raise NotImplementedError,"Acos_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return acos(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(-1./sqrt(1.-myarg**2),self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def atan(arg):
   """
   returns inverse tangent of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.arctan(arg)
   elif isinstance(arg,escript.Data):
      return arg._atan()
   elif isinstance(arg,float):
      return math.atan(arg)
   elif isinstance(arg,int):
      return math.atan(arg)
   elif isinstance(arg,Symbol):
      return Atan_Symbol(arg)
   else:
      raise TypeError,"atan: Unknown argument type."

class Atan_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the inverse tangent function
   """
   def __init__(self,arg):
      """
      initialization of atan L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "atan(%s)"%argstrs
      else:
         raise NotImplementedError,"Atan_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return atan(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(1./(1+myarg**2),self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def sinh(arg):
   """
   returns hyperbolic sine of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.sinh(arg)
   elif isinstance(arg,escript.Data):
      return arg._sinh()
   elif isinstance(arg,float):
      return math.sinh(arg)
   elif isinstance(arg,int):
      return math.sinh(arg)
   elif isinstance(arg,Symbol):
      return Sinh_Symbol(arg)
   else:
      raise TypeError,"sinh: Unknown argument type."

class Sinh_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the hyperbolic sine function
   """
   def __init__(self,arg):
      """
      initialization of sinh L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "sinh(%s)"%argstrs
      else:
         raise NotImplementedError,"Sinh_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return sinh(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(cosh(myarg),self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def cosh(arg):
   """
   returns hyperbolic cosine of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.cosh(arg)
   elif isinstance(arg,escript.Data):
      return arg._cosh()
   elif isinstance(arg,float):
      return math.cosh(arg)
   elif isinstance(arg,int):
      return math.cosh(arg)
   elif isinstance(arg,Symbol):
      return Cosh_Symbol(arg)
   else:
      raise TypeError,"cosh: Unknown argument type."

class Cosh_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the hyperbolic cosine function
   """
   def __init__(self,arg):
      """
      initialization of cosh L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "cosh(%s)"%argstrs
      else:
         raise NotImplementedError,"Cosh_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return cosh(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(sinh(myarg),self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def tanh(arg):
   """
   returns hyperbolic tangent of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.tanh(arg)
   elif isinstance(arg,escript.Data):
      return arg._tanh()
   elif isinstance(arg,float):
      return math.tanh(arg)
   elif isinstance(arg,int):
      return math.tanh(arg)
   elif isinstance(arg,Symbol):
      return Tanh_Symbol(arg)
   else:
      raise TypeError,"tanh: Unknown argument type."

class Tanh_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the hyperbolic tangent function
   """
   def __init__(self,arg):
      """
      initialization of tanh L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "tanh(%s)"%argstrs
      else:
         raise NotImplementedError,"Tanh_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return tanh(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(1./cosh(myarg)**2,self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def asinh(arg):
   """
   returns inverse hyperbolic sine of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.arcsinh(arg)
   elif isinstance(arg,escript.Data):
      return arg._asinh()
   elif isinstance(arg,float):
      return numarray.arcsinh(arg)
   elif isinstance(arg,int):
      return numarray.arcsinh(float(arg))
   elif isinstance(arg,Symbol):
      return Asinh_Symbol(arg)
   else:
      raise TypeError,"asinh: Unknown argument type."

class Asinh_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the inverse hyperbolic sine function
   """
   def __init__(self,arg):
      """
      initialization of asinh L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "asinh(%s)"%argstrs
      else:
         raise NotImplementedError,"Asinh_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return asinh(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(1./sqrt(myarg**2+1),self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def acosh(arg):
   """
   returns inverse hyperolic cosine of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.arccosh(arg)
   elif isinstance(arg,escript.Data):
      return arg._acosh()
   elif isinstance(arg,float):
      return numarray.arccosh(arg)
   elif isinstance(arg,int):
      return numarray.arccosh(float(arg))
   elif isinstance(arg,Symbol):
      return Acosh_Symbol(arg)
   else:
      raise TypeError,"acosh: Unknown argument type."

class Acosh_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the inverse hyperolic cosine function
   """
   def __init__(self,arg):
      """
      initialization of acosh L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "acosh(%s)"%argstrs
      else:
         raise NotImplementedError,"Acosh_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return acosh(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(1./sqrt(myarg**2-1),self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def atanh(arg):
   """
   returns inverse hyperbolic tangent of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.arctanh(arg)
   elif isinstance(arg,escript.Data):
      return arg._atanh()
   elif isinstance(arg,float):
      return numarray.arctanh(arg)
   elif isinstance(arg,int):
      return numarray.arctanh(float(arg))
   elif isinstance(arg,Symbol):
      return Atanh_Symbol(arg)
   else:
      raise TypeError,"atanh: Unknown argument type."

class Atanh_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the inverse hyperbolic tangent function
   """
   def __init__(self,arg):
      """
      initialization of atanh L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "atanh(%s)"%argstrs
      else:
         raise NotImplementedError,"Atanh_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return atanh(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(1./(1.-myarg**2),self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def exp(arg):
   """
   returns exponential of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.exp(arg)
   elif isinstance(arg,escript.Data):
      return arg._exp()
   elif isinstance(arg,float):
      return math.exp(arg)
   elif isinstance(arg,int):
      return math.exp(arg)
   elif isinstance(arg,Symbol):
      return Exp_Symbol(arg)
   else:
      raise TypeError,"exp: Unknown argument type."

class Exp_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the exponential function
   """
   def __init__(self,arg):
      """
      initialization of exp L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "exp(%s)"%argstrs
      else:
         raise NotImplementedError,"Exp_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return exp(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(self,self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def sqrt(arg):
   """
   returns square root of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.sqrt(arg)
   elif isinstance(arg,escript.Data):
      return arg._sqrt()
   elif isinstance(arg,float):
      return math.sqrt(arg)
   elif isinstance(arg,int):
      return math.sqrt(arg)
   elif isinstance(arg,Symbol):
      return Sqrt_Symbol(arg)
   else:
      raise TypeError,"sqrt: Unknown argument type."

class Sqrt_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the square root function
   """
   def __init__(self,arg):
      """
      initialization of sqrt L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "sqrt(%s)"%argstrs
      else:
         raise NotImplementedError,"Sqrt_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return sqrt(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(0.5/self,self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def log(arg):
   """
   returns natural logarithm of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return numarray.log(arg)
   elif isinstance(arg,escript.Data):
      return arg._log()
   elif isinstance(arg,float):
      return math.log(arg)
   elif isinstance(arg,int):
      return math.log(arg)
   elif isinstance(arg,Symbol):
      return Log_Symbol(arg)
   else:
      raise TypeError,"log: Unknown argument type."

class Log_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the natural logarithm function
   """
   def __init__(self,arg):
      """
      initialization of log L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "log(%s)"%argstrs
      else:
         raise NotImplementedError,"Log_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.

      @param argvals: new values assigned to symbols
      @type argvals: C{dict} with keywords of type L{Symbol}.
      @return: result of the substitution process. Operations are executed as much as possible.
      @rtype: L{escript.Symbol}, C{float}, L{escript.Data}, L{numarray.NumArray} depending on the degree of substitution
      @raise TypeError: if a value for a L{Symbol} cannot be substituted.
      """
      if argvals.has_key(self):
         arg=argvals[self]
         if self.isAppropriateValue(arg):
            return arg
         else:
            raise TypeError,"%s: new value is not appropriate."%str(self)
      else:
         arg=self.getSubstitutedArguments(argvals)[0]
         return log(arg)

   def diff(self,arg):
      """
      differential of this object

      @param arg: the derivative is calculated with respect to arg
      @type arg: L{escript.Symbol}
      @return: derivative with respect to C{arg}
      @rtype: typically L{Symbol} but other types such as C{float}, L{escript.Data}, L{numarray.NumArray}  are possible.
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=matchShape(1./arg,self.getDifferentiatedArguments(arg)[0])
         return val[0]*val[1]

def sign(arg):
   """
   returns sign of argument arg

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray}.
   @rtype:C{float}, L{escript.Data}, L{Symbol}, L{numarray.NumArray} depending on the type of arg.
   @raises TypeError: if the type of the argument is not expected.
   """
   if isinstance(arg,numarray.NumArray):
      return wherePositive(arg)-whereNegative(arg)
   elif isinstance(arg,escript.Data):
      return arg._sign()
   elif isinstance(arg,float):
      if arg>0:
        return 1.
      elif arg<0:
        return -1.
      else:
        return 0.
   elif isinstance(arg,int):
      if float(arg)>0:
        return 1.
      elif float(arg)<0:
        return -1.
      else:
        return 0.
   elif isinstance(arg,Symbol):
      return wherePositive(arg)-whereNegative(arg)
   else:
      raise TypeError,"sign: Unknown argument type."

class Abs_Symbol(DependendSymbol):
   """
   L{Symbol} representing the result of the absolute value function
   """
   def __init__(self,arg):
      """
      initialization of abs L{Symbol} with argument arg
      @param arg: argument of function
      @type arg: typically L{Symbol}.
      """
      DependendSymbol.__init__(self,args=[arg],shape=arg.getShape(),dim=arg.getDim())

   def getMyCode(self,argstrs,format="escript"):
      """
      returns a program code that can be used to evaluate the symbol.

      @param argstrs: gives for each argument a string representing the argument for the evaluation.
      @type argstrs: C{str} or a C{list} of length 1 of C{str}.
      @param format: specifies the format to be used. At the moment only "escript" ,"text" and "str" are supported.
      @type format: C{str}
      @return: a piece of program code which can be used to evaluate the expression assuming the values for the arguments are available.
      @rtype: C{str}
      @raise: NotImplementedError: if the requested format is not available
      """
      if isinstance(argstrs,list):
          argstrs=argstrs[0]
      if format=="escript" or format=="str"  or format=="text":
         return "abs(%s)"%argstrs
      else:
         raise NotImplementedError,"Abs_Symbol does not provide program code for format %s."%format

   def substitute(self,argvals):
      """
      assigns new values to symbols in the definition of the symbol.
      The method replaces the L{Symbol} u by argvals[u] in the expression defining this object.