escript/py_src/util.py


########################################################
#
# Copyright (c) 2003-2008 by University of Queensland
# Earth Systems Science Computational Center (ESSCC)
# http://www.uq.edu.au/esscc
#
# Primary Business: Queensland, Australia
# Licensed under the Open Software License version 3.0
# http://www.opensource.org/licenses/osl-3.0.php
#
########################################################

__copyright__="""Copyright (c) 2003-2008 by University of Queensland
Earth Systems Science Computational Center (ESSCC)
http://www.uq.edu.au/esscc
Primary Business: Queensland, Australia"""
__license__="""Licensed under the Open Software License version 3.0
http://www.opensource.org/licenses/osl-3.0.php"""
__url__="http://www.uq.edu.au/esscc/escript-finley"

"""
Utility functions for escript

@var __author__: name of author
@var __copyright__: copyrights
@var __license__: licence agreement
@var __url__: url entry point on documentation
@var __version__: version
@var __date__: date of the version
@var EPSILON: smallest positive value with 1.<1.+EPSILON
@var DBLE_MAX: largest positive float
"""

__author__="Lutz Gross, l.gross@uq.edu.au"


import math
import numarray
import escript
import os
from esys.escript import C_GeneralTensorProduct
from esys.escript import getVersion
from esys.escript import printParallelThreadCounts
from esys.escript import listEscriptParams

#=========================================================
#   some helpers:
#=========================================================
def getEpsilon():
     return escript.getMachinePrecision()
EPSILON=getEpsilon()

def getMaxFloat():
     return escript.getMaxFloat()
DBLE_MAX=getMaxFloat()

def getTagNames(domain):
    """
    Returns a list of tag names used by the domain.

    @param domain: a domain object
    @type domain: L{escript.Domain}
    @return: a list of tag names used by the domain
    @rtype: C{list} of C{str}
    """
    return [n.strip() for n in domain.showTagNames().split(",") ]

def insertTagNames(domain,**kwargs):
    """
    Inserts tag names into the domain.

    @param domain: a domain object
    @type domain: C{escript.Domain}
    @keyword <tag_name>: tag key assigned to <tag_name>
    @type <tag_name>: C{int}
    """
    for  k in kwargs:
         domain.setTagMap(k,kwargs[k])

def insertTaggedValues(target,**kwargs):
    """
    Inserts tagged values into the target using tag names.

    @param target: data to be filled by tagged values
    @type target: L{escript.Data}
    @keyword <tag_name>: value to be used for <tag_name>
    @type <tag_name>: C{float} or C{numarray.NumArray}
    @return: C{target}
    @rtype: L{escript.Data}
    """
    for k in kwargs:
        target.setTaggedValue(k,kwargs[k])
    return target

def saveVTK(filename,domain=None,**data):
    """
    Writes L{Data} objects and their mesh into a file using the VTK XML file
    format.

    Example::

        tmp=Scalar(..)
        v=Vector(..)
        saveVTK("solution.vtu", temperature=tmp, velocity=v)

    C{tmp} and C{v} are written into "solution.vtu" where C{tmp} is named
    "temperature" and C{v} is named "velocity".

    @param filename: file name of the output file
    @type filename: C{str}
    @param domain: domain of the L{Data} objects. 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}s can be mixed. Typically, data on the boundary and
           data on the interior cannot be mixed.
    """
    new_data={}
    for n,d in data.items():
          if not d.isEmpty():
            fs=d.getFunctionSpace()
            domain2=fs.getDomain()
            if fs == escript.Solution(domain2):
               new_data[n]=interpolate(d,escript.ContinuousFunction(domain2))
            elif fs == escript.ReducedSolution(domain2):
               new_data[n]=interpolate(d,escript.ReducedContinuousFunction(domain2))
            else:
               new_data[n]=d
            if domain==None: domain=domain2
    if domain==None:
        raise ValueError,"saveVTK: no domain detected."
    domain.saveVTK(filename,new_data)

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

    Example::

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

    C{tmp} and C{v} are written into "solution.dx" where C{tmp} is named
    "temperature" and C{v} is named "velocity".

    @param filename: file name of the output file
    @type filename: C{str}
    @param domain: domain of the L{Data} objects. 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}s can be mixed. Typically, data on the boundary and
           data on the interior cannot be mixed.
    """
    new_data={}
    for n,d in data.items():
          if not d.isEmpty():
            fs=d.getFunctionSpace()
            domain2=fs.getDomain()
            if fs == escript.Solution(domain2):
               new_data[n]=interpolate(d,escript.ReducedContinuousFunction(domain2))
            elif fs == escript.ReducedSolution(domain2):
               new_data[n]=interpolate(d,escript.ReducedContinuousFunction(domain2))
            elif fs == escript.ContinuousFunction(domain2):
               new_data[n]=interpolate(d,escript.ReducedContinuousFunction(domain2))
            else:
               new_data[n]=d
            if domain==None: domain=domain2
    if domain==None:
        raise ValueError,"saveDX: no domain detected."
    domain.saveDX(filename,new_data)

def saveESD(datasetName, dataDir=".", domain=None, **data):
    """
    Saves L{Data} objects to files and creates an I{escript dataset} (ESD) file
    for convenient processing/visualisation.

    Example::

        tmp = Scalar(..)
        v = Vector(..)
        saveESD("solution", "data", temperature=tmp, velocity=v)

    tmp, v and the domain are saved in native format in the "data"
    directory and the file "solution.esd" is created that refers to tmp by
    the name "temperature" and to v by the name "velocity".

    @param datasetName: name of the dataset, used to name the ESD file
    @type datasetName: C{str}
    @param dataDir: optional directory where the data files should be saved
    @type dataDir: C{str}
    @param domain: domain of the L{Data} object(s). 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 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}s can be mixed. Typically, data on the boundary and
           data on the interior cannot be mixed.
    """
    new_data = {}
    for n,d in data.items():
          if not d.isEmpty(): 
            fs = d.getFunctionSpace() 
            domain2 = fs.getDomain()
            if fs == escript.Solution(domain2):
               new_data[n]=interpolate(d,escript.ContinuousFunction(domain2))
            elif fs == escript.ReducedSolution(domain2):
               new_data[n]=interpolate(d,escript.ReducedContinuousFunction(domain2))
            else:
               new_data[n]=d
            if domain==None: domain=domain2
    if domain==None:
        raise ValueError, "saveESD: no domain detected."

    if domain.onMasterProcessor() and not os.path.isdir(dataDir):
        os.mkdir(dataDir)

    meshFile = os.path.join(dataDir, datasetName+"_mesh")
    domain.dump(meshFile + ".nc")
    outputString = ""
    if domain.onMasterProcessor():
        outputString += "#escript datafile V1.0\n"
        # number of timesteps (currently only 1 is supported)
        outputString += "T=1\n"
        # name of the mesh file
        outputString += "M=%s\n" % meshFile
        # number of blocks (MPI size)
        outputString += "N=%d\n" % domain.getMPISize()

    # now add the variables
    for varName, d in new_data.items():
        varFile = os.path.join(dataDir, datasetName+"_"+varName)
        d.dump(varFile + ".nc")
        if domain.onMasterProcessor():
            outputString += "V=%s:%s\n" % (varFile, varName)

    if domain.onMasterProcessor():
        esdfile = open(datasetName+".esd", "w")
        esdfile.write(outputString)
        esdfile.close()

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

   @param d: dimension or an object that has the C{getDim} method defining the
             dimension
   @type d: C{int}, L{escript.Domain} or L{escript.FunctionSpace}
   @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: C{numarray.NumArray} or L{escript.Data} of rank 2
   """
   return identityTensor(d)

def identity(shape=()):
   """
   Returns the C{shape} x C{shape} identity tensor.

   @param shape: input shape for the identity tensor
   @type shape: C{tuple} of C{int}
   @return: array whose shape is shape x shape where M{u[i,k]=1} for M{i=k} and
            M{u[i,k]=0} otherwise for len(shape)=1. If 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: C{numarray.NumArray} of rank 1, rank 2 or rank 4
   @raise ValueError: if len(shape)>2
   """
   if len(shape)>0:
      out=numarray.zeros(shape+shape,numarray.Float64)
      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):
   """
   Returns the C{d} x C{d} identity matrix.

   @param d: dimension or an object that has the C{getDim} method defining the
             dimension
   @type d: C{int}, L{escript.Domain} or L{escript.FunctionSpace}
   @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: C{numarray.NumArray} or L{escript.Data} of rank 2
   """
   if isinstance(d,escript.FunctionSpace):
       return escript.Data(identity((d.getDim(),)),d)
   elif isinstance(d,escript.Domain):
       return identity((d.getDim(),))
   else:
       return identity((d,))

def identityTensor4(d=3):
   """
   Returns the C{d} x C{d} x C{d} x C{d} 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: C{numarray.NumArray} or L{escript.Data} of rank 4
   """
   if isinstance(d,escript.FunctionSpace):
       return escript.Data(identity((d.getDim(),d.getDim())),d)
   elif isinstance(d,escript.Domain):
       return identity((d.getDim(),d.getDim()))
   else:
       return identity((d,d))

def unitVector(i=0,d=3):
   """
   Returns a unit vector u of dimension d whose non-zero element is at index i.

   @param i: index for non-zero element
   @type i: C{int}
   @param d: dimension or an object that has the C{getDim} method defining the
             dimension
   @type d: C{int}, L{escript.Domain} or L{escript.FunctionSpace}
   @return: the object u of rank 1 with M{u[j]=1} for M{j=index} and M{u[j]=0}
            otherwise
   @rtype: C{numarray.NumArray} or L{escript.Data} 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 C{arg}. This is the maximum absolute value
    over all data points. This function is equivalent to C{sup(abs(arg))}.

    @param arg: argument
    @type arg: C{float}, C{int}, L{escript.Data}, C{numarray.NumArray}
    @return: maximum value of the absolute value of C{arg}over all components
             and all data points
    @rtype: C{float}
    @raise TypeError: if type of C{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}, C{numarray.NumArray}
    @return: maximum value of C{arg}over all components and all data points
    @rtype: C{float}
    @raise TypeError: if type of C{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 minimum value over all data points.

    @param arg: argument
    @type arg: C{float}, C{int}, L{escript.Data}, C{numarray.NumArray}
    @return: minimum value of C{arg}over all components and all data points
    @rtype: C{float}
    @raise TypeError: if type of C{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 getRank(arg):
    """
    Identifies the rank of the argument.

    @param arg: an object whose rank is to be returned
    @type arg: C{numarray.NumArray}, L{escript.Data}, C{float}, C{int},
               C{Symbol}
    @return: the rank of the argument
    @rtype: C{int}
    @raise TypeError: if type of C{arg}cannot be processed
    """

    if isinstance(arg,numarray.NumArray):
        return arg.rank
    elif isinstance(arg,escript.Data):
        return arg.getRank()
    elif isinstance(arg,float):
        return 0
    elif isinstance(arg,int):
        return 0
    elif isinstance(arg,Symbol):
        return arg.getRank()
    else:
      raise TypeError,"getRank: Unknown argument type."

def getShape(arg):
    """
    Identifies the shape of the argument.

    @param arg: an object whose shape is to be returned
    @type arg: C{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 C{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,"getShape: Cannot identify shape"

def pokeDim(arg):
    """
    Identifies the spatial dimension of the argument.

    @param arg: an object whose spatial dimension is to be returned
    @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 C{arg0} can be extended from the right and C{arg1}
    can be extended from the left.

    @param arg0: an object with a shape (see L{getShape})
    @param arg1: an object with a shape (see L{getShape})
    @return: the shape of C{arg0} or C{arg1} such that the left part equals the
             shape of C{arg0} and the right end equals the shape of C{arg1}
    @rtype: C{tuple} of C{int}
    @raise ValueError: if no shape can be found
    """
    sh0=getShape(arg0)
    sh1=getShape(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 may not have a spatial dimension.

    @param args: given objects
    @return: the spatial dimension of the objects with identifiable dimension
             (see L{pokeDim}). If none of 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):
    """
    Tests if the argument is identical to zero.

    @param arg: the object to test for zero
    @type arg: typically C{numarray.NumArray}, L{escript.Data}, C{float}, C{int}
    @return: True if the argument is identical to zero, False otherwise
    @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.):
    """
    Converts C{arg0} and C{arg1} both to the same type C{numarray.NumArray} or
    L{escript.Data} or, if one of C{arg0} or C{arg1} is of type L{Symbol}, the
    other one to be of type C{numarray.NumArray} or L{escript.Data}.

    @param arg0: first argument
    @type arg0: C{numarray.NumArray},L{escript.Data},C{float}, C{int}, C{Symbol}
    @param arg1: second argument
    @type arg1: C{numarray.NumArray},L{escript.Data},C{float}, C{int}, C{Symbol}
    @return: a tuple representing C{arg0} and C{arg1} with the same type or
             with one of them being a L{Symbol}
    @rtype: C{tuple} of two C{numarray.NumArray}, two L{escript.Data},
            a C{Symbol} and one of the types C{numarray.NumArray} or
            L{escript.Data}
    @raise TypeError: if type of C{arg0} or C{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,type=numarray.Float64)
       elif isinstance(arg1,int):
          arg1=numarray.array(float(arg1),type=numarray.Float64)
       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,type=numarray.Float64)
       elif isinstance(arg1,int):
          arg1=numarray.array(float(arg1),type=numarray.Float64)
       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,type=numarray.Float64)
       elif isinstance(arg1,escript.Data):
          arg0=escript.Data(arg0,arg1.getFunctionSpace())
       elif isinstance(arg1,float):
          arg0=numarray.array(arg0,type=numarray.Float64)
          arg1=numarray.array(arg1,type=numarray.Float64)
       elif isinstance(arg1,int):
          arg0=numarray.array(arg0,type=numarray.Float64)
          arg1=numarray.array(float(arg1),type=numarray.Float64)
       elif isinstance(arg1,Symbol):
          arg0=numarray.array(arg0,type=numarray.Float64)
       else:
          raise TypeError,"function: Unknown type of second argument."
    elif isinstance(arg0,int):
       if isinstance(arg1,numarray.NumArray):
          arg0=numarray.array(float(arg0),type=numarray.Float64)
       elif isinstance(arg1,escript.Data):
          arg0=escript.Data(float(arg0),arg1.getFunctionSpace())
       elif isinstance(arg1,float):
          arg0=numarray.array(float(arg0),type=numarray.Float64)
          arg1=numarray.array(arg1,type=numarray.Float64)
       elif isinstance(arg1,int):
          arg0=numarray.array(float(arg0),type=numarray.Float64)
          arg1=numarray.array(float(arg1),type=numarray.Float64)
       elif isinstance(arg1,Symbol):
          arg0=numarray.array(float(arg0),type=numarray.Float64)
       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):
    """
    Returns a representation of C{arg0} and C{arg1} which have the same shape.

    @param arg0: first argument
    @type arg0: C{numarray.NumArray},L{escript.Data},C{float}, C{int}, L{Symbol}
    @param arg1: second argument
    @type arg1: C{numarray.NumArray},L{escript.Data},C{float}, C{int}, L{Symbol}
    @return: C{arg0} and C{arg1} where copies are returned when the shape has
             to be changed
    @rtype: C{tuple}
    """
    sh=commonShape(arg0,arg1)
    sh0=getShape(arg0)
    sh1=getShape(arg1)
    if len(sh0)<len(sh):
       return outer(arg0,numarray.ones(sh[len(sh0):],numarray.Float64)),arg1
    elif len(sh1)<len(sh):
       return arg0,outer(arg1,numarray.ones(sh[len(sh1):],numarray.Float64))
    else:
       return arg0,arg1

#=========================================================
#   symbolic tool box starts here:
#=========================================================
class Symbol(object):
   """
   Symbol class objects provide the same functionality as C{numarray.NumArray}
   and L{escript.Data} objects but they do not have a value and therefore
   cannot be plotted or visualized. The main purpose is the possibility to
   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 depend
       on a list of arguments C{args} which may be symbols or any other object.

       @param args: the arguments of the symbol
       @type args: C{list}
       @param shape: the shape of the symbol
       @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 only supports 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 value of the i-th argument or if 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):
       """
       Returns 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):
       """
       Returns the shape of the symbol.

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

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

       @return: the symbol's spatial dimension
       @rtype: C{int} if the dimension is defined, C{None} otherwise
       """
       return self.__dim

   def __str__(self):
       """
       Returns 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{Symbol} 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{Symbol}s 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):
       """
       Applies differentials to the arguments of this object and returns the
       result as a list.

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

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

      @param arg: object to be checked
      @type arg: C{numarray.NumArray}, L{escript.Data}, C{float}, C{int},
                 C{Symbol}
      @return: True if C{arg} is a suitable object to be used for substitution,
               False otherwise
      @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 program code that can be used to evaluate the symbol.

       @param argstrs: a string for each argument 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}, C{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} C{arg}.

       @param arg: the derivative is calculated with respect to C{arg}
       @type arg: typically L{escript.Symbol} but can also be C{float},
                  L{escript.Data}, C{numarray.NumArray} depending on 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}, C{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.Float64)
          else:
             return 0.

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

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

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

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

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

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

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

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

       @param other: object to add this object to
       @type other: L{escript.Symbol}, C{float}, L{escript.Data},
                    C{numarray.NumArray}
       @return: a L{Symbol} representing the sum of C{other} and this 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},
                    C{numarray.NumArray}
       @return: a L{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 to be subtracted from
       @type other: L{escript.Symbol}, C{float}, L{escript.Data},
                    C{numarray.NumArray}
       @return: a L{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 another object.

       @param other: object to be mutiplied by this object
       @type other: L{escript.Symbol}, C{float}, L{escript.Data},
                    C{numarray.NumArray}
       @return: a L{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 another object by this object.

       @param other: object this object is multiplied with
       @type other: L{escript.Symbol}, C{float}, L{escript.Data},
                    C{numarray.NumArray}
       @return: a L{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 another object.

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

   def __rdiv__(self,other):
       """
       Divides another object by this object.

       @param other: object to be divided by this object
       @type other: L{escript.Symbol}, C{float}, L{escript.Data},
                    C{numarray.NumArray}
       @return: a L{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 C{other}.

       @param other: exponent
       @type other: L{escript.Symbol}, C{float}, L{escript.Data},
                    C{numarray.NumArray}
       @return: a L{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},
                    C{numarray.NumArray}
       @return: a L{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)

   def __getitem__(self,index):
       """
       Returns the slice defined by C{index}.

       @param index: the slice index
       @type index: C{slice} or C{int} or a C{tuple} of them
       @return: a L{Symbol} representing the slice defined by index
       @rtype: L{DependendSymbol}
       """
       return GetSlice_Symbol(self,index)

class DependendSymbol(Symbol):
   """
   DependendSymbol extents L{Symbol} by modifying the == operator to allow two
   instances to be equal. Two C{DependendSymbol}s 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 C{other} equals self.

      @param other: any object
      @return: True if other has the same class as self and the shape, the
               spatial dimension and the arguments are equal, False otherwise
      @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 C{other} is not equal to self.

      @param other: any object
      @return: False if other has the same class as self and the shape, the
               spatial dimension and the arguments are equal, True otherwise
      @rtype: C{bool}
      """
      return not self==other
#=========================================================
#  Unary operations preserving the shape
#========================================================
class GetSlice_Symbol(DependendSymbol):
   """
   L{Symbol} representing getting a slice for a L{Symbol}.
   """
   def __init__(self,arg,index):
      """
      Initialization of the L{Symbol} with argument C{arg}.

      @param arg: argument
      @type arg: L{Symbol}
      @param index: defines index
      @type index: C{slice} or C{int} or a C{tuple} of them
      @raises IndexError: if length of index is larger than rank of arg or
                          index start or stop is out of range
      @raises ValueError: if a step is given
      """
      if not isinstance(index,tuple): index=(index,)
      if len(index)>arg.getRank():
           raise IndexError,"GetSlice_Symbol: index out of range."
      sh=()
      index2=()
      for i in range(len(index)):
         ix=index[i]
         if isinstance(ix,int):
            if ix<0 or ix>=arg.getShape()[i]:
               raise IndexError,"GetSlice_Symbol: index out of range."
            index2=index2+(ix,)
         else:
           if not ix.step==None:
             raise ValueError,"GetSlice_Symbol: stepping is not supported."
           if ix.start==None:
              s=0
           else:
              s=ix.start
           if ix.stop==None:
              e=arg.getShape()[i]
           else:
              e=ix.stop
              if e>arg.getShape()[i]:
                 raise IndexError,"GetSlice_Symbol: index out of range."
           index2=index2+(slice(s,e),)
           if e>s:
               sh=sh+(e-s,)
           elif s>e:
               raise IndexError,"GetSlice_Symbol: slice start must be less or equal slice end"
      for i in range(len(index),arg.getRank()):
          index2=index2+(slice(0,arg.getShape()[i]),)
          sh=sh+(arg.getShape()[i],)
      super(GetSlice_Symbol, self).__init__(args=[arg,index2],shape=sh,dim=arg.getDim())

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

      @param argstrs: a string for each argument 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", "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
      """
      if format=="escript" or format=="str"  or format=="text":
         return "%s.__getitem__(%s)"%(argstrs[0],argstrs[1])
      else:
         raise NotImplementedError,"GetItem_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}, C{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:
         args=self.getSubstitutedArguments(argvals)
         arg=args[0]
         index=args[1]
         return arg.__getitem__(index)

def log10(arg):
   """
   Returns base-10 logarithm of argument C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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 C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}.
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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.Float64))*1.
      if isinstance(out,float): out=numarray.array(out,type=numarray.Float64)
      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 C{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 program code that can be used to evaluate the symbol.

      @param argstrs: a string for each argument 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", "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
      """
      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}, C{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 negative values of argument C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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.Float64))*1.
      if isinstance(out,float): out=numarray.array(out,type=numarray.Float64)
      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 negative values function.
   """
   def __init__(self,arg):
      """
      Initialization of whereNegative L{Symbol} with argument C{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 program code that can be used to evaluate the symbol.

      @param argstrs: a string for each argument 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", "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
      """
      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}, C{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 C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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.Float64))*1.
      if isinstance(out,float): out=numarray.array(out,type=numarray.Float64)
      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 C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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.Float64))*1.
      if isinstance(out,float): out=numarray.array(out,type=numarray.Float64)
      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=None,adaptTol=True,rtol=math.sqrt(EPSILON)):
   """
   Returns mask of zero entries of argument C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @param tol: absolute tolerance. Values with absolute value less than tol are accepted
               as zero. If C{tol} is not present C{rtol}*C{L{Lsup}(arg)} is used. 
   @type tol: C{float}
   @param rtol: relative tolerance used to define the absolute tolerance if C{tol} is not present.
   @type rtol: non-negative C{float}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{arg}
   @raises ValueError: if C{rtol} is non-negative.
   @raises TypeError: if the type of the argument is not expected
   """
   if tol == None:
      if not isinstance(arg,Symbol):
         if rtol<=0: raise ValueError,"rtol must be non-negative."
         tol = Lsup(arg)*rtol
      else:
         tol=0.
   if isinstance(arg,numarray.NumArray):
      out=numarray.less_equal(abs(arg)-tol,numarray.zeros(arg.shape,numarray.Float64))*1.
      if isinstance(out,float): out=numarray.array(out,type=numarray.Float64)
      return out
   elif isinstance(arg,escript.Data):
      return arg._whereZero(tol)
   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 C{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 program code that can be used to evaluate the symbol.

      @param argstrs: a string for each argument 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", "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
      """
      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}, C{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 C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @param tol: absolute tolerance. Values with absolute value less than tol are accepted
               as zero. If C{tol} is not present C{rtol}*C{L{Lsup}(arg)} is used. 
   @type tol: C{float}
   @param rtol: relative tolerance used to define the absolute tolerance if C{tol} is not present.
   @type rtol: non-negative C{float}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{arg}
   @raises ValueError: if C{rtol} is non-negative.
   @raises TypeError: if the type of the argument is not expected
   """
   if tol == None:
      if not isinstance(arg,Symbol):
         if rtol<=0: raise ValueError,"rtol must be non-negative."
         tol = Lsup(arg)*rtol
      else:
         tol=0.
   if isinstance(arg,numarray.NumArray):
      out=numarray.greater(abs(arg)-tol,numarray.zeros(arg.shape,numarray.Float64))*1.
      if isinstance(out,float): out=numarray.array(out,type=numarray.Float64)
      return out
   elif isinstance(arg,escript.Data):
      return arg._whereNonZero(tol)
   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 erf(arg):
   """
   Returns the error function M{erf} of argument C{arg}.

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

def sin(arg):
   """
   Returns sine of argument C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}.
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{arg}
   @raise 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 C{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 program code that can be used to evaluate the symbol.

      @param argstrs: a string for each argument 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", "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
      """
      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}, C{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 C{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}, C{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 C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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 C{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 program code that can be used to evaluate the symbol.

      @param argstrs: a string for each argument 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", "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
      """
      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}, C{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 C{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}, C{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 C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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 C{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 program code that can be used to evaluate the symbol.

      @param argstrs: a string for each argument 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", "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
      """
      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}, C{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 C{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}, C{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 the inverse sine of argument C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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 C{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 program code that can be used to evaluate the symbol.

      @param argstrs: a string for each argument 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", "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
      """
      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}, C{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 C{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}, C{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 the inverse cosine of argument C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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 C{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 program code that can be used to evaluate the symbol.

      @param argstrs: a string for each argument 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", "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
      """
      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}, C{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 C{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}, C{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 C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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 C{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 program code that can be used to evaluate the symbol.

      @param argstrs: a string for each argument 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", "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
      """
      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}, C{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 C{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}, C{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 the hyperbolic sine of argument C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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 C{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 program code that can be used to evaluate the symbol.

      @param argstrs: a string for each argument 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", "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
      """
      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}, C{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 C{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}, C{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 the hyperbolic cosine of argument C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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 C{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 program code that can be used to evaluate the symbol.

      @param argstrs: a string for each argument 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", "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
      """
      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}, C{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 C{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}, C{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 the hyperbolic tangent of argument C{arg}.

   @param arg: argument
   @type arg: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray}
   @rtype: C{float}, L{escript.Data}, L{Symbol}, C{numarray.NumArray} depending
           on the type of C{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 C{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 program code that can be used to evaluate the symbol.

      @param argstrs: a string for each argument 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", "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
      """
      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}, C{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 C{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}, C{numarray.NumArray} are possible
      """
      if arg==self:
         return identity(self.getShape())
      else:
         myarg=self.getArgument()[0]
         val=