escript/py_src/util.py


########################################################
#
# Copyright (c) 2003-2009 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-2009 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__="https://launchpad.net/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 numpy
import escript
import os
from esys.escript import C_GeneralTensorProduct
from esys.escript import getVersion, getMPIRankWorld, getMPIWorldMax
from esys.escript import printParallelThreadCounts
from esys.escript import listEscriptParams
from esys.escript.escriptcpp import Data, _saveDataCSV

#=========================================================
#   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: `escript.Domain`
    :return: a list of tag names used by the domain
    :rtype: ``list`` of ``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: ``escript.Domain``
    :keyword <tag_name>: tag key assigned to <tag_name>
    :type <tag_name>: ``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: `escript.Data`
    :keyword <tag_name>: value to be used for <tag_name>
    :type <tag_name>: ``float`` or ``numpy.ndarray``
    :return: ``target``
    :rtype: `escript.Data`
    """
    for k in kwargs:
        target.setTaggedValue(k,kwargs[k])
    return target

def saveDataCSV(filename, append=False, sep=", ", csep="_", **data):
    """
    Writes `Data` objects to a csv file.
    These objects must have compatible FunctionSpaces. ie it must be possible to
    interpolate all data to one `FunctionSpace`. 
    Example::
    s=Scalar(..)
    v=Vector(..)
    t=Tensor(..)
    saveDataCSV("f.csv",a=s, b=v, c=t)
    
    Will result in a file
    
    a, b0, b1, c0_0, c0_1, .., c1_0
    1.0, 1.5, 2.7, 3.1, 3.4, .., 0.89
    0.9, 8.7, 1.9, 3.4, 7.8, .., 1.21
    
    The first line is a header, the remaining lines give the values.
    
    :param filename: file to save data to.
    :type filename: ``string``
    :param append: If ``True``, then open file at end rather than beginning
    :type append: ``bool``
    :param sep: separator between fields
    :type sep: ``string``
    :param csep: separator for components of rank2 and above eg ('_' -> c0_1)
    
    The keyword args are Data objects to save.
    If a scalar `Data` object is passed with the name ``mask``, then only
    samples which correspond to positive values in ``mask`` will be output.
    """
    new_data={}
    for n,d in data.items():
    if not isinstance(d, Data):
        raise ValueError, "saveDataCSV: unknown non-data argument %s"%(str(n))
    new_data[n]=d
    _saveDataCSV(filename, new_data,sep, csep, append)

def saveVTK(filename,domain=None, metadata=None, metadata_schema=None, **data):
    """
    Writes `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)

    ``tmp`` and ``v`` are written into "solution.vtu" where ``tmp`` is named
    "temperature" and ``v`` is named "velocity".

    Meta tags, e.g. a timeStamp, can be added to the file, for instance::

        tmp=Scalar(..)
        v=Vector(..)
        saveVTK("solution.vtu", temperature=tmp, velocity=v,
                metadata="<timeStamp>1.234</timeStamp>",
                metadata_schema={ "gml" : "http://www.opengis.net/gml"})

    The argument ``metadata_schema`` allows the definition of name spaces with a schema used in the definition of meta tags.

    :param filename: file name of the output file
    :type filename: ``str``
    :param domain: domain of the `Data` objects. If not specified, the domain
                   of the given `Data` objects is used.
    :type domain: `escript.Domain`
    :keyword <name>: writes the assigned value to the VTK file using <name> as
                     identifier
    :param metadata: additional XML meta data which are inserted into the VTK file. The meta data are marked by the tag ``<MetaData>``.
    :type metadata: ``str``
    :param metadata_schema: assignes schema to namespaces which have been used to define  meta data.
    :type metadata_schema: ``dict`` with ``metadata_schema[<namespace>]=<URI>`` to assign the scheme ``<URI>`` to the name space ``<namespace>``.
    :note: The data objects have to be defined on the same domain. They may not
           be in the same `FunctionSpace` but one cannot expect that all
           `FunctionSpace` s can be mixed. Typically, data on the boundary and
           data on the interior cannot be mixed.
    """
    # create the string if meta data:
    if not metadata==None:
        metadata2="<MetaData>"+metadata+"</MetaData>"
    else:
        metadata2=""
    metadata_shema2=""
    if not metadata_schema==None:
         for i,p in metadata_schema.items():
             metadata_shema2="%s xmlns:%s=\"%s\""%(metadata_shema2,i,p)
    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,metadata2.strip(),metadata_shema2.strip())

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

    Example::

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

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

    :param filename: file name of the output file
    :type filename: ``str``
    :param domain: domain of the `Data` objects. If not specified, the domain
                   of the given `Data` objects is used.
    :type domain: `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>: `Data` object
    :note: The data objects have to be defined on the same domain. They may not
           be in the same `FunctionSpace` but one cannot expect that all
           `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, timeStep=0, deltaT=1, dynamicMesh=0, **data):
    """
    Saves `Data` objects to files and creates an I{escript dataset} (ESD) file
    for convenient processing/visualisation.

    Single timestep example::

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

    Time series example::

        while t < t_end:
            tmp = Scalar(..)
            v = Vector(..)
            # save every 10 timesteps
            if t % 10 == 0:
                saveESD("solution", "data", timeStep=t, deltaT=10, temperature=tmp, velocity=v)
            t = t + 1

    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: ``str``
    :param dataDir: optional directory where the data files should be saved
    :type dataDir: ``str``
    :param domain: domain of the `Data` object(s). If not specified, the
                   domain of the given `Data` objects is used.
    :type domain: `escript.Domain`
    :param timeStep: current timestep or sequence number - first one must be 0
    :type timeStep: `int`
    :param deltaT: timestep or sequence increment, see example above
    :type deltaT: `int`
    :param dynamicMesh: by default the mesh is assumed to be static and thus
                        only saved once at timestep 0 to save disk space.
                        Setting this to 1 changes the behaviour and the mesh
                        is saved at each timestep.
    :type dynamicMesh: `int`
    :keyword <name>: writes the assigned value to the file using <name> as
                     identifier
    :type <name>: `Data` object
    :note: The data objects have to be defined on the same domain. They may not
           be in the same `FunctionSpace` but one cannot expect that all
           `FunctionSpace` s can be mixed. Typically, data on the boundary and
           data on the interior cannot be mixed.
    :note: When saving a time series the first timestep must be 0 and it is
           assumed that data from all timesteps share the domain. The dataset
           file is updated in each iteration.
    """
    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")
    fileNumber = timeStep / deltaT

    if dynamicMesh == 0:
        # later timesteps reuse mesh from t=0
        if timeStep == 0:
            domain.dump(meshFile + ".nc")
    else:
        meshFile += ".%04d"
        domain.dump((meshFile + ".nc") % fileNumber)

    outputString = ""

    if domain.onMasterProcessor():
        outputString += "#escript datafile V1.0\n"
        # number of timesteps (currently only 1 is supported)
        outputString += "T=%d\n" % (fileNumber+1)
        # timestep increment
        outputString += "DT=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+".%04d")
        d.dump((varFile + ".nc") % fileNumber)
        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 delta-symbol.

   :param d: dimension or an object that has the ``getDim`` method defining the
             dimension
   :type d: ``int``, `escript.Domain` or `escript.FunctionSpace`
   :return: the object u of rank 2 with *u[i,j]=1* for *i=j* and *u[i,j]=0*
            otherwise
   :rtype: ``numpy.ndarray`` or `escript.Data` of rank 2
   """
   return identityTensor(d)

def identity(shape=()):
   """
   Returns the ``shape`` x ``shape`` identity tensor.

   :param shape: input shape for the identity tensor
   :type shape: ``tuple`` of ``int``
   :return: array whose shape is shape x shape where *u[i,k]=1* for *i=k* and
            *u[i,k]=0* otherwise for len(shape)=1. If len(shape)=2:
            *u[i,j,k,l]=1* for *i=k and j=l* and *u[i,j,k,l]=0* otherwise.
   :rtype: ``numpy.ndarray`` of rank 1, rank 2 or rank 4
   :raise ValueError: if len(shape)>2
   """
   if len(shape)>0:
      out=numpy.zeros(shape+shape,numpy.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 ``d`` x ``d`` identity matrix.

   :param d: dimension or an object that has the ``getDim`` method defining the
             dimension
   :type d: ``int``, `escript.Domain` or `escript.FunctionSpace`
   :return: the object u of rank 2 with *u[i,j]=1* for *i=j* and *u[i,j]=0*
            otherwise
   :rtype: ``numpy.ndarray`` or `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 ``d`` x ``d`` x ``d`` x ``d`` identity tensor.

   :param d: dimension or an object that has the ``getDim`` method defining the
             dimension
   :type d: ``int`` or any object with a ``getDim`` method
   :return: the object u of rank 4 with *u[i,j,k,l]=1* for *i=k and j=l* and
            *u[i,j,k,l]=0* otherwise
   :rtype: ``numpy.ndarray`` or `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: ``int``
   :param d: dimension or an object that has the ``getDim`` method defining the
             dimension
   :type d: ``int``, `escript.Domain` or `escript.FunctionSpace`
   :return: the object u of rank 1 with *u[j]=1* for *j=index* and *u[j]=0*
            otherwise
   :rtype: ``numpy.ndarray`` or `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 ``arg``. This is the maximum absolute value
    over all data points. This function is equivalent to ``sup(abs(arg))``.

    :param arg: argument
    :type arg: ``float``, ``int``, `escript.Data`, ``numpy.ndarray``
    :return: maximum value of the absolute value of ``arg`` over all components
             and all data points
    :rtype: ``float``
    :raise TypeError: if type of ``arg`` cannot be processed
    """
    if isinstance(arg,numpy.ndarray):
        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: ``float``, ``int``, `escript.Data`, ``numpy.ndarray``
    :return: maximum value of ``arg`` over all components and all data points
    :rtype: ``float``
    :raise TypeError: if type of ``arg`` cannot be processed
    """
    if isinstance(arg,numpy.ndarray):
        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: ``float``, ``int``, `escript.Data`, ``numpy.ndarray``
    :return: minimum value of ``arg`` over all components and all data points
    :rtype: ``float``
    :raise TypeError: if type of ``arg`` cannot be processed
    """
    if isinstance(arg,numpy.ndarray):
        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: ``numpy.ndarray``, `escript.Data`, ``float``, ``int``,
               ``Symbol``
    :return: the rank of the argument
    :rtype: ``int``
    :raise TypeError: if type of ``arg`` cannot be processed
    """

    if isinstance(arg,numpy.ndarray):
        return arg.ndim
    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: ``numpy.ndarray``, `escript.Data`, ``float``, ``int``,
               ``Symbol``
    :return: the shape of the argument
    :rtype: ``tuple`` of ``int``
    :raise TypeError: if type of ``arg`` cannot be processed
    """

    if isinstance(arg,numpy.ndarray):
        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 ``None``
    :rtype: ``int`` or ``None``
    """

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

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

    :param arg0: an object with a shape (see `getShape`)
    :param arg1: an object with a shape (see `getShape`)
    :return: the shape of ``arg0`` or ``arg1`` such that the left part equals the
             shape of ``arg0`` and the right end equals the shape of ``arg1``
    :rtype: ``tuple`` of ``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 `pokeDim`). If none of the objects has a spatial dimension
             ``None`` is returned.
    :rtype: ``int`` or ``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 ``numpy.ndarray``, `escript.Data`, ``float``, ``int``
    :return: True if the argument is identical to zero, False otherwise
    :rtype: ``bool``
    """
    if isinstance(arg,numpy.ndarray):
       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 ``arg0`` and ``arg1`` both to the same type ``numpy.ndarray`` or
    `escript.Data` or, if one of ``arg0`` or ``arg1`` is of type `Symbol`, the
    other one to be of type ``numpy.ndarray`` or `escript.Data`.

    :param arg0: first argument
    :type arg0: ``numpy.ndarray``,`escript.Data`,``float``, ``int``, ``Symbol``
    :param arg1: second argument
    :type arg1: ``numpy.ndarray``,`escript.Data`,``float``, ``int``, ``Symbol``
    :return: a tuple representing ``arg0`` and ``arg1`` with the same type or
             with one of them being a `Symbol`
    :rtype: ``tuple`` of two ``numpy.ndarray``, two `escript.Data`,
            a ``Symbol`` and one of the types ``numpy.ndarray`` or
            `escript.Data`
    :raise TypeError: if type of ``arg0`` or ``arg1`` cannot be processed
    """
    if isinstance(arg0,numpy.ndarray):
       if isinstance(arg1,numpy.ndarray):
          pass
       elif isinstance(arg1,escript.Data):
          arg0=escript.Data(arg0,arg1.getFunctionSpace())
       elif isinstance(arg1,float):
          arg1=numpy.array(arg1,dtype=numpy.float64)
       elif isinstance(arg1,int):
          arg1=numpy.array(float(arg1),dtype=numpy.float64)
       elif isinstance(arg1,Symbol):
          pass
       else:
          raise TypeError,"function: Unknown type of second argument."
    elif isinstance(arg0,escript.Data):
       if isinstance(arg1,numpy.ndarray):
          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,numpy.ndarray):
          pass
       elif isinstance(arg1,escript.Data):
          pass
       elif isinstance(arg1,float):
          arg1=numpy.array(arg1,dtype=numpy.float64)
       elif isinstance(arg1,int):
          arg1=numpy.array(float(arg1),dtype=numpy.float64)
       elif isinstance(arg1,Symbol):
          pass
       else:
          raise TypeError,"function: Unknown type of second argument."
    elif isinstance(arg0,float):
       if isinstance(arg1,numpy.ndarray):
          arg0=numpy.array(arg0,dtype=numpy.float64)
       elif isinstance(arg1,escript.Data):
          arg0=escript.Data(arg0,arg1.getFunctionSpace())
       elif isinstance(arg1,float):
          arg0=numpy.array(arg0,dtype=numpy.float64)
          arg1=numpy.array(arg1,dtype=numpy.float64)
       elif isinstance(arg1,int):
          arg0=numpy.array(arg0,dtype=numpy.float64)
          arg1=numpy.array(float(arg1),dtype=numpy.float64)
       elif isinstance(arg1,Symbol):
          arg0=numpy.array(arg0,dtype=numpy.float64)
       else:
          raise TypeError,"function: Unknown type of second argument."
    elif isinstance(arg0,int):
       if isinstance(arg1,numpy.ndarray):
          arg0=numpy.array(float(arg0),dtype=numpy.float64)
       elif isinstance(arg1,escript.Data):
          arg0=escript.Data(float(arg0),arg1.getFunctionSpace())
       elif isinstance(arg1,float):
          arg0=numpy.array(float(arg0),dtype=numpy.float64)
          arg1=numpy.array(arg1,dtype=numpy.float64)
       elif isinstance(arg1,int):
          arg0=numpy.array(float(arg0),dtype=numpy.float64)
          arg1=numpy.array(float(arg1),dtype=numpy.float64)
       elif isinstance(arg1,Symbol):
          arg0=numpy.array(float(arg0),dtype=numpy.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 ``arg0`` and ``arg1`` which have the same shape.

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

#=========================================================
#   symbolic tool box starts here:
#=========================================================
class Symbol(object):
   """
   Symbol class objects provide the same functionality as ``numpy.ndarray``
   and `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 ``args`` which may be symbols or any other object.

       :param args: the arguments of the symbol
       :type args: ``list``
       :param shape: the shape of the symbol
       :type shape: ``tuple`` of ``int``
       :param dim: spatial dimension of the symbol. If dim=``None`` the spatial
                   dimension is undefined.
       :type dim: ``None`` or ``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: ``int`` or ``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: ``int``
       """
       return len(self.getShape())

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

       :return: the shape of the symbol
       :rtype: ``tuple`` of ``int``
       """
       return self.__shape

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

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

   def __str__(self):
       """
       Returns a string representation of the symbol.

       :return: a string representation of the object
       :rtype: ``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: `Symbol` and their substitutes. The `Symbol` u in the
                       expression defining this object is replaced by
                       argvals[u].
       :type argvals: ``dict`` with keywords of type `Symbol`
       :rtype: ``list`` of objects
       :return: list of the object assigned to the arguments through
                substitution or for the arguments which are not `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 ``arg``
       :type arg: typically `escript.Symbol` but can also be ``float``,
                  `escript.Data`, ``numpy.ndarray`` depending on the
                  involved functions and data
       :rtype: ``list`` of objects
       :return: list of object obtained by calculating the derivatives of the
                arguments with respect to ``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(numpy.zeros(s),numpy.float64)
              else:
                 out.append(a)
       return out

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

      :param arg: object to be checked
      :type arg: ``numpy.ndarray``, `escript.Data`, ``float``, ``int``,
                 ``Symbol``
      :return: True if ``arg`` is a suitable object to be used for substitution,
               False otherwise
      :rtype: ``bool``
      """
      if isinstance(arg,numpy.ndarray):
          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: ``list`` of ``str``
       :param format: specifies the format to be used. At the moment only
                      "escript", "str" and "text" are supported.
       :type format: ``str``
       :return: a piece of program code which can be used to evaluate the
                expression assuming the values for the arguments are available
       :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

      :param argvals: new values assigned to symbols
      :type argvals: ``dict`` with keywords of type `Symbol`
      :return: result of the substitution process. Operations are executed as
               much as possible.
      :rtype: `escript.Symbol`, ``float``, `escript.Data`, ``numpy.ndarray``
              depending on the degree of substitution
      :note: this method has to be overwritten by a particular `Symbol`
      :raise NotImplementedError: if no implementation for the given format is
                                  available
      :raise TypeError: if a value for a `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 `Symbol` ``arg``.

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

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

       :return: a `Symbol` representing the negative of the object
       :rtype: `DependendSymbol`
       """
       return self*(-1.)

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

       :return: a `Symbol` representing the positive of the object
       :rtype: `DependendSymbol`
       """
       return self*(1.)

   def __abs__(self):
       """
       Returns a `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: `escript.Symbol`, ``float``, `escript.Data`,
                    ``numpy.ndarray``.
       :return: a `Symbol` representing the sum of this object and ``other``
       :rtype: `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: `escript.Symbol`, ``float``, `escript.Data`,
                    ``numpy.ndarray``
       :return: a `Symbol` representing the sum of ``other`` and this object
       :rtype: `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: `escript.Symbol`, ``float``, `escript.Data`,
                    ``numpy.ndarray``
       :return: a `Symbol` representing the difference of ``other`` and this
                object
       :rtype: `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: `escript.Symbol`, ``float``, `escript.Data`,
                    ``numpy.ndarray``
       :return: a `Symbol` representing the difference of this object and
                ``other``.
       :rtype: `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: `escript.Symbol`, ``float``, `escript.Data`,
                    ``numpy.ndarray``
       :return: a `Symbol` representing the product of the object and ``other``
       :rtype: `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: `escript.Symbol`, ``float``, `escript.Data`,
                    ``numpy.ndarray``
       :return: a `Symbol` representing the product of ``other`` and the object
       :rtype: `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: `escript.Symbol`, ``float``, `escript.Data`,
                    ``numpy.ndarray``
       :return: a `Symbol` representing the quotient of this object and
                ``other``
       :rtype: `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: `escript.Symbol`, ``float``, `escript.Data`,
                    ``numpy.ndarray``
       :return: a `Symbol` representing the quotient of ``other`` and this
                object
       :rtype: `DependendSymbol` or 0 if ``other`` is identical to zero
       """
       return quotient(other,self)

   def __pow__(self,other):
       """
       Raises this object to the power of ``other``.

       :param other: exponent
       :type other: `escript.Symbol`, ``float``, `escript.Data`,
                    ``numpy.ndarray``
       :return: a `Symbol` representing the power of this object to ``other``
       :rtype: `DependendSymbol` or 1 if ``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: `escript.Symbol`, ``float``, `escript.Data`,
                    ``numpy.ndarray``
       :return: a `Symbol` representing the power of ``other`` to this object
       :rtype: `DependendSymbol` or 0 if ``other`` is identical to zero
       """
       return power(other,self)

   def __getitem__(self,index):
       """
       Returns the slice defined by ``index``.

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

class DependendSymbol(Symbol):
   """
   DependendSymbol extents `Symbol` by modifying the == operator to allow two
   instances to be equal. Two ``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
          `Symbol` arguments. This will allow the optimizer to remove
          redundant function calls.
   """
   def __eq__(self,other):
      """
      Checks if ``other`` equals self.

      :param other: any object
      :return: True if other has the same class as self and the shape, the
               spatial dimension and the arguments are equal, False otherwise
      :rtype: ``bool``
      """
      if isinstance(other,DependendSymbol):
         if self.__class__==other.__class__:
            if self.getShape()==other.getShape():
               if self.getArgument()==other.getArgument():
                  if self.getDim()==None or other.getDim()==None or self.getDim()==other.getDim():
                     return True
      return False

   def __ne__(self,other):
      """
      Checks if ``other`` 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: ``bool``
      """
      return not self==other
#=========================================================
#  Unary operations preserving the shape
#========================================================
class GetSlice_Symbol(DependendSymbol):
   """
   `Symbol` representing getting a slice for a `Symbol`.
   """
   def __init__(self,arg,index):
      """
      Initialization of the `Symbol` with argument ``arg``.

      :param arg: argument
      :type arg: `Symbol`
      :param index: defines index
      :type index: ``slice`` or ``int`` or a ``tuple`` of them
      :raise IndexError: if length of index is larger than rank of arg or
                          index start or stop is out of range
      :raise 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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

      :param argvals: new values assigned to symbols
      :type argvals: ``dict`` with keywords of type `Symbol`
      :return: result of the substitution process. Operations are executed as
               much as possible.
      :rtype: `escript.Symbol`, ``float``, `escript.Data`, ``numpy.ndarray``
              depending on the degree of substitution
      :raise TypeError: if a value for a `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 ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.log10(arg)
   elif isinstance(arg,escript.Data):
      return arg._log10()
   elif isinstance(arg,float):
      return math.log10(arg)
   elif isinstance(arg,int):
      return math.log10(float(arg))
   elif isinstance(arg,Symbol):
      return log(arg)/log(10.)
   else:
      raise TypeError,"log10: Unknown argument type."

def wherePositive(arg):
   """
   Returns mask of positive values of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``.
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      out=numpy.greater(arg,numpy.zeros(arg.shape,numpy.float64))*1.
      if isinstance(out,float): out=numpy.array(out,dtype=numpy.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):
   """
   `Symbol` representing the result of the mask of positive values function.
   """
   def __init__(self,arg):
      """
      Initialization of wherePositive `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

      :param argvals: new values assigned to symbols
      :type argvals: ``dict`` with keywords of type `Symbol`
      :return: result of the substitution process. Operations are executed as
               much as possible.
      :rtype: `escript.Symbol`, ``float``, `escript.Data`, ``numpy.ndarray``
              depending on the degree of substitution
      :raise TypeError: if a value for a `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 ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      out=numpy.less(arg,numpy.zeros(arg.shape,numpy.float64))*1.
      if isinstance(out,float): out=numpy.array(out,dtype=numpy.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):
   """
   `Symbol` representing the result of the mask of negative values function.
   """
   def __init__(self,arg):
      """
      Initialization of whereNegative `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

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

def whereNonNegative(arg):
   """
   Returns mask of non-negative values of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      out=numpy.greater_equal(arg,numpy.zeros(arg.shape,numpy.float64))*1.
      if isinstance(out,float): out=numpy.array(out,dtype=numpy.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 ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      out=numpy.less_equal(arg,numpy.zeros(arg.shape,numpy.float64))*1.
      if isinstance(out,float): out=numpy.array(out,dtype=numpy.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 ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data` , `Symbol` , ``numpy.ndarray``
   :param tol: absolute tolerance. Values with absolute value less than tol are accepted
               as zero. If ``tol`` is not present ``rtol``*```Lsup` (arg)`` is used. 
   :type tol: ``float``
   :param rtol: relative tolerance used to define the absolute tolerance if ``tol`` is not present.
   :type rtol: non-negative ``float``
   :rtype: ``float``, `escript.Data` , `Symbol` , ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise ValueError: if ``rtol`` is non-negative.
   :raise 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,numpy.ndarray):
      out=numpy.less_equal(abs(arg)-tol,numpy.zeros(arg.shape,numpy.float64))*1.
      if isinstance(out,float): out=numpy.array(out,dtype=numpy.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):
   """
   `Symbol` representing the result of the mask of zero entries function.
   """
   def __init__(self,arg,tol=0.):
      """
      Initialization of whereZero `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

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

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

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :param tol: absolute tolerance. Values with absolute value less than tol are accepted
               as zero. If ``tol`` is not present ``rtol``*```Lsup` (arg)`` is used. 
   :type tol: ``float``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise ValueError: if ``rtol`` is non-negative.
   :raise 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,numpy.ndarray):
      out=numpy.greater(abs(arg)-tol,numpy.zeros(arg.shape,numpy.float64))*1.
      if isinstance(out,float): out=numpy.array(out,dtype=numpy.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 *erf* of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``.
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``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 ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``.
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.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):
   """
   `Symbol` representing the result of the sine function.
   """
   def __init__(self,arg):
      """
      Initialization of sin `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

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

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

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

def cos(arg):
   """
   Returns cosine of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.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):
   """
   `Symbol` representing the result of the cosine function.
   """
   def __init__(self,arg):
      """
      Initialization of cos `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

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

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

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

def tan(arg):
   """
   Returns tangent of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.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):
   """
   `Symbol` representing the result of the tangent function.
   """
   def __init__(self,arg):
      """
      Initialization of tan `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

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

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

      :param arg: the derivative is calculated with respect to ``arg``
      :type arg: `escript.Symbol`
      :return: derivative with respect to ``arg``
      :rtype: typically `Symbol` but other types such as ``float``,
              `escript.Data`, ``numpy.ndarray`` 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 ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.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):
   """
   `Symbol` representing the result of the inverse sine function.
   """
   def __init__(self,arg):
      """
      Initialization of asin `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

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

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

      :param arg: the derivative is calculated with respect to ``arg``
      :type arg: `escript.Symbol`
      :return: derivative with respect to ``arg``
      :rtype: typically `Symbol` but other types such as ``float``,
              `escript.Data`, ``numpy.ndarray`` 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 ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.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):
   """
   `Symbol` representing the result of the inverse cosine function.
   """
   def __init__(self,arg):
      """
      Initialization of acos `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

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

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

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

def atan(arg):
   """
   Returns inverse tangent of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.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):
   """
   `Symbol` representing the result of the inverse tangent function.
   """
   def __init__(self,arg):
      """
      Initialization of atan `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

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

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

      :param arg: the derivative is calculated with respect to ``arg``
      :type arg: `escript.Symbol`
      :return: derivative with respect to ``arg``
      :rtype: typically `Symbol` but other types such as ``float``,
              `escript.Data`, ``numpy.ndarray`` 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 ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.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):
   """
   `Symbol` representing the result of the hyperbolic sine function.
   """
   def __init__(self,arg):
      """
      Initialization of sinh `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

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

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

      :param arg: the derivative is calculated with respect to ``arg``
      :type arg: `escript.Symbol`
      :return: derivative with respect to ``arg``
      :rtype: typically `Symbol` but other types such as ``float``,
              `escript.Data`, ``numpy.ndarray`` 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 ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.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):
   """
   `Symbol` representing the result of the hyperbolic cosine function.
   """
   def __init__(self,arg):
      """
      Initialization of cosh `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

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

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

      :param arg: the derivative is calculated with respect to ``arg``
      :type arg: `escript.Symbol`
      :return: derivative with respect to ``arg``
      :rtype: typically `Symbol` but other types such as ``float``,
              `escript.Data`, ``numpy.ndarray`` 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 ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.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):
   """
   `Symbol` representing the result of the hyperbolic tangent function.
   """
   def __init__(self,arg):
      """
      Initialization of tanh `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 `Symbol` u by argvals[u] in the expression
      defining this object.

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

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

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

def asinh(arg):
   """
   Returns the inverse hyperbolic sine of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.arcsinh(arg)
   elif isinstance(arg,escript.Data):
      return arg._asinh()
   elif isinstance(arg,float):
      return numpy.arcsinh(arg)
   elif isinstance(arg,int):
      return numpy.arcsinh(float(arg))
   elif isinstance(arg,Symbol):
      return Asinh_Symbol(arg)
   else:
      raise TypeError,"asinh: Unknown argument type."

class Asinh_Symbol(DependendSymbol):
   """
   `Symbol` representing the result of the inverse hyperbolic sine function.
   """
   def __init__(self,arg):
      """
      Initialization of asinh `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 "asinh(%s)"%argstrs
      else:
         raise NotImplementedError,"Asinh_Symbol does not provide program code for format %s."%format

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

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

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

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

def acosh(arg):
   """
   Returns the inverse hyperbolic cosine of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.arccosh(arg)
   elif isinstance(arg,escript.Data):
      return arg._acosh()
   elif isinstance(arg,float):
      return numpy.arccosh(arg)
   elif isinstance(arg,int):
      return numpy.arccosh(float(arg))
   elif isinstance(arg,Symbol):
      return Acosh_Symbol(arg)
   else:
      raise TypeError,"acosh: Unknown argument type."

class Acosh_Symbol(DependendSymbol):
   """
   `Symbol` representing the result of the inverse hyperbolic cosine function.
   """
   def __init__(self,arg):
      """
      Initialization of acosh `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 "acosh(%s)"%argstrs
      else:
         raise NotImplementedError,"Acosh_Symbol does not provide program code for format %s."%format

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

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

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

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

def atanh(arg):
   """
   Returns the inverse hyperbolic tangent of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.arctanh(arg)
   elif isinstance(arg,escript.Data):
      return arg._atanh()
   elif isinstance(arg,float):
      return numpy.arctanh(arg)
   elif isinstance(arg,int):
      return numpy.arctanh(float(arg))
   elif isinstance(arg,Symbol):
      return Atanh_Symbol(arg)
   else:
      raise TypeError,"atanh: Unknown argument type."

class Atanh_Symbol(DependendSymbol):
   """
   `Symbol` representing the result of the inverse hyperbolic tangent function.
   """
   def __init__(self,arg):
      """
      Initialization of atanh `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 "atanh(%s)"%argstrs
      else:
         raise NotImplementedError,"Atanh_Symbol does not provide program code for format %s."%format

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

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

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

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

def exp(arg):
   """
   Returns *e* to the power of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``.
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of arg
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.exp(arg)
   elif isinstance(arg,escript.Data):
      return arg._exp()
   elif isinstance(arg,float):
      return math.exp(arg)
   elif isinstance(arg,int):
      return math.exp(arg)
   elif isinstance(arg,Symbol):
      return Exp_Symbol(arg)
   else:
      raise TypeError,"exp: Unknown argument type."

class Exp_Symbol(DependendSymbol):
   """
   `Symbol` representing the result of the exponential function.
   """
   def __init__(self,arg):
      """
      Initialization of exp `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 "exp(%s)"%argstrs
      else:
         raise NotImplementedError,"Exp_Symbol does not provide program code for format %s."%format

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

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

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

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

def sqrt(arg):
   """
   Returns the square root of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
           depending on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.sqrt(arg)
   elif isinstance(arg,escript.Data):
      return arg._sqrt()
   elif isinstance(arg,float):
      return math.sqrt(arg)
   elif isinstance(arg,int):
      return math.sqrt(arg)
   elif isinstance(arg,Symbol):
      return Sqrt_Symbol(arg)
   else:
      raise TypeError,"sqrt: Unknown argument type."

class Sqrt_Symbol(DependendSymbol):
   """
   `Symbol` representing the result of the square root function.
   """
   def __init__(self,arg):
      """
      Initialization of sqrt `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 "sqrt(%s)"%argstrs
      else:
         raise NotImplementedError,"Sqrt_Symbol does not provide program code for format %s."%format

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

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

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

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

def log(arg):
   """
   Returns the natural logarithm of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``.
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return numpy.log(arg)
   elif isinstance(arg,escript.Data):
      return arg._log()
   elif isinstance(arg,float):
      return math.log(arg)
   elif isinstance(arg,int):
      return math.log(arg)
   elif isinstance(arg,Symbol):
      return Log_Symbol(arg)
   else:
      raise TypeError,"log: Unknown argument type."

class Log_Symbol(DependendSymbol):
   """
   `Symbol` representing the result of the natural logarithm function.
   """
   def __init__(self,arg):
      """
      Initialization of log `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 "log(%s)"%argstrs
      else:
         raise NotImplementedError,"Log_Symbol does not provide program code for format %s."%format

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

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

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

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

def sign(arg):
   """
   Returns the sign of argument ``arg``.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray`` depending
           on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      return wherePositive(arg)-whereNegative(arg)
   elif isinstance(arg,escript.Data):
      return arg._sign()
   elif isinstance(arg,float):
      if arg>0:
        return 1.
      elif arg<0:
        return -1.
      else:
        return 0.
   elif isinstance(arg,int):
      if float(arg)>0:
        return 1.
      elif float(arg)<0:
        return -1.
      else:
        return 0.
   elif isinstance(arg,Symbol):
      return wherePositive(arg)-whereNegative(arg)
   else:
      raise TypeError,"sign: Unknown argument type."

class Abs_Symbol(DependendSymbol):
   """
   `Symbol` representing the result of the absolute value function.
   """
   def __init__(self,arg):
      """
      Initialization of abs `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 "abs(%s)"%argstrs
      else:
         raise NotImplementedError,"Abs_Symbol does not provide program code for format %s."%format

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

      :param argvals: new values assigned to symbols
      :type argvals: ``dict`` with keywords of type `Symbol`
      :return: result of the substitution process. Operations are executed as
               much as possible.
      :rtype: `escript.Symbol`, ``float``, `escript.Data`, ``numpy.ndarray``
              depending on the degree of substitution
      :raise TypeError: if a value for a `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 abs(arg)

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

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

def minval(arg):
   """
   Returns the minimum value over all components of ``arg`` at each data point.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol` depending on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      if arg.ndim==0:
         return float(arg)
      else:
         return arg.min()
   elif isinstance(arg,escript.Data):
      return arg._minval()
   elif isinstance(arg,float):
      return arg
   elif isinstance(arg,int):
      return float(arg)
   elif isinstance(arg,Symbol):
      return Minval_Symbol(arg)
   else:
      raise TypeError,"minval: Unknown argument type."

class Minval_Symbol(DependendSymbol):
   """
   `Symbol` representing the result of the minimum value function.
   """
   def __init__(self,arg):
      """
      Initialization of minimum value `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `Symbol`
      """
      DependendSymbol.__init__(self,args=[arg],shape=(),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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 "minval(%s)"%argstrs
      else:
         raise NotImplementedError,"Minval_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 `Symbol` u by argvals[u] in the expression
      defining this object.

      :param argvals: new values assigned to symbols
      :type argvals: ``dict`` with keywords of type `Symbol`
      :return: result of the substitution process. Operations are executed as
               much as possible.
      :rtype: `escript.Symbol`, ``float``, `escript.Data`, ``numpy.ndarray``
              depending on the degree of substitution
      :raise TypeError: if a value for a `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 minval(arg)

def maxval(arg):
   """
   Returns the maximum value over all components of ``arg`` at each data point.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol` depending on the type of ``arg``
   :raise TypeError: if the type of the argument is not expected
   """
   if isinstance(arg,numpy.ndarray):
      if arg.ndim==0:
         return float(arg)
      else:
         return arg.max()
   elif isinstance(arg,escript.Data):
      return arg._maxval()
   elif isinstance(arg,float):
      return arg
   elif isinstance(arg,int):
      return float(arg)
   elif isinstance(arg,Symbol):
      return Maxval_Symbol(arg)
   else:
      raise TypeError,"maxval: Unknown argument type."

class Maxval_Symbol(DependendSymbol):
   """
   `Symbol` representing the result of the maximum value function.
   """
   def __init__(self,arg):
      """
      Initialization of maximum value `Symbol` with argument ``arg``.

      :param arg: argument of function
      :type arg: typically `Symbol`
      """
      DependendSymbol.__init__(self,args=[arg],shape=(),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: ``str`` or a ``list`` of length 1 of ``str``
      :param format: specifies the format to be used. At the moment only
                     "escript", "str" and "text" are supported.
      :type format: ``str``
      :return: a piece of program code which can be used to evaluate the
               expression assuming the values for the arguments are available
      :rtype: ``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 "maxval(%s)"%argstrs
      else:
         raise NotImplementedError,"Maxval_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 `Symbol` u by argvals[u] in the expression
      defining this object.

      :param argvals: new values assigned to symbols
      :type argvals: ``dict`` with keywords of type `Symbol`
      :return: result of the substitution process. Operations are executed as
               much as possible.
      :rtype: `escript.Symbol`, ``float``, `escript.Data`, ``numpy.ndarray``
              depending on the degree of substitution
      :raise TypeError: if a value for a `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 maxval(arg)

def length(arg):
   """
   Returns the length (Euclidean norm) of argument ``arg`` at each data point.

   :param arg: argument
   :type arg: ``float``, `escript.Data`, `Symbol`, ``numpy.ndarray``
   :rtype: ``float``, `escript.Data`, `Symbol` depending on the type of ``arg``
   """
   return sqrt(inner(arg,arg))

def trace(arg,axis_offset=0):
   """
   Returns the trace of ``arg`` which is the sum of ``arg[k,k]`` over k.

   :param arg: argument
   :type arg: `escript.Data`, `Symbol`, ``numpy.ndarray``
   :param axis_offset: ``axis_offset`` to components to sum over. ``axis_offset``
                       must be non-negative and less than the rank of ``arg`` +1.
                       The dimensions of component ``axis_offset`` and
                       axis_offset+1 must be equal.
   :type axis_offset: ``int``
   :return: trace of arg. The rank of the returned object is rank of ``arg``
            minus 2.
   :rtype: `escript.Data`, `Symbol`, ``numpy.ndarray`` depending on the
           type of ``arg``
   """
   if isinstance(arg,numpy.ndarray):
      sh=arg.shape
      if len(sh)<2:
        raise ValueError,"rank of argument must be greater than 1"
      if axis_offset<0 or axis_offset>len(sh)-2:
        raise ValueError,"axis_offset must be between 0 and %d"%(len(sh)-2)
      s1=1
      for i in range(axis_offset): s1*=sh[i]
      s2=1
      for i in range(axis_offset+2,len(sh)): s2*=sh[i]
      if not sh[axis_offset] == sh[axis_offset+1]:
        raise ValueError,"dimensions of component %d and %d must match."%(axis_offset,axis_offset+1)
      arg_reshaped=numpy.reshape(arg,(s1,sh[axis_offset],sh[axis_offset],s2))
      out=numpy.zeros([s1,s2],numpy.float64)
      for i1 in range(s1):
        for i2 in range(s2):
            for j in range(sh[axis_offset]): out[i1,i2]+=arg_reshaped[i1,j,j,i2]
      out.resize(sh[:axis_offset]+sh[axis_offset+2:])
      return out
   elif isinstance(arg,escript.Data):
      if arg.getRank()<2:
        raise ValueError,"rank of argument must be greater than 1"
      if axis_offset<0 or axis_offset>arg.getRank()-2:
        raise <