escript/py_src/modelframe.py

# $Id$

from types import StringType,IntType,FloatType,BooleanType,ListType,DictType
from sys import stdout
import itertools
# import modellib  temporarily removed!!!

# import the 'set' module if it's not defined (python2.3/2.4 difference)
try:
    set
except NameError:
    from sets import Set as set

from xml.dom import minidom

def dataNode(document, tagName, data):
    """
    dataNodes are the building blocks of the xml documents constructed in
    this module. document is the current xml document, tagName is the
    associated xml tag, and data is the values in the tag.
    """
    t = document.createTextNode(str(data))
    n = document.createElement(tagName)
    n.appendChild(t)
    return n

def esysDoc():
    """
    Global method for creating an instance of an EsysXML document.
    """
    doc = minidom.Document()
    esys = doc.createElement('ESys')
    doc.appendChild(esys)
    return doc, esys

def all(seq):
    for x in seq:
        if not x:
            return False
    return True

def any(seq):
    for x in seq:
        if x:
            return True
    return False

LinkableObjectRegistry = {}

def registerLinkableObject(obj_id, o):
    LinkableObjectRegistry[obj_id] = o

LinkRegistry = []

def registerLink(obj_id, l):
    LinkRegistry.append((obj_id,l))

def parse(xml):
    """
    Generic parse method for EsysXML. Without this, Links don't work.
    """
    global LinkRegistry, LinkableObjectRegistry
    LinkRegistry = []
    LinkableObjectRegistry = {}

    doc = minidom.parseString(xml)
    sim = getComponent(doc.firstChild)
    for obj_id, link in LinkRegistry:
        link.target = LinkableObjectRegistry[obj_id]

    return sim

def getComponent(doc):
    """ 
    Used to get components of Simualtions, Models.
    """
    for node in doc.childNodes:
        
        if isinstance(node, minidom.Element):
            if node.tagName == 'Simulation':
                if node.getAttribute("type") == 'Simulation':
                    return Simulation.fromDom(node)
            if node.tagName == 'Model':
                model_type = node.getAttribute("type")
                model_subclasses = Model.__subclasses__()
                for model in model_subclasses:
                    if model_type == model.__name__:
                        return Model.fromDom(node)
            if node.tagName == 'ParameterSet':
                parameter_type = node.getAttribute("type")
                return ParameterSet.fromDom(node)
            raise "Invalid simulation type, %r" % node.getAttribute("type")
        

    raise ValueError("No Simulation Found")
            

class Link:
    """
    a Link makes an attribute of an object callable: 
          o.object()
          o.a=8
          l=Link(o,"a")
          assert l()==8
     """
    
    def __init__(self,target,attribute=None):
        """
        creates a link to the object target. If attribute is given, the link is
        establised to this attribute of the target.  Otherwise the attribute is
        undefined.
        """
        self.target = target
        self.attribute = None
        self.setAttributeName(attribute)
    
    def setAttributeName(self,attribute):
        """
        set a new attribute name to be collected from the target object. The
        target object must have the attribute with name attribute.
        """
        if attribute and self.target:
            if isinstance(self.target,LinkableObject):
               if not self.target.hasAttribute(attribute):
                  raise AttributeError("%s: target %s has no attribute %s."%(self, self.target, attribute))
            else:
               if not hasattr(self.target,attribute):
                  raise AttributeError("%s: target %s has no attribute %s."%(self, self.target, attribute))
        self.attribute = attribute
    
    def hasDefinedAttributeName(self):
        """
        returns true if an attribute name is set
        """
        return self.attribute != None
    
    def __repr__(self):
        """
        returns a string representation of the link
        """
        if self.hasDefinedAttributeName():
            return "<Link to attribute %s of %s>" % (self.attribute, self.target)
        else:
            return "<Link to target %s>" % self.target
    
    def __call__(self,name=None):
        """
        returns the value of the attribute of the target object. If the
        atrribute is callable then the return value of the call is returned.
        """
        if name:
            out=getattr(self.target, name)
        else:
            out=getattr(self.target, self.attribute)

        if callable(out):
            return out()
        else:
            return out

    def toDom(self, document, node):
        """
        toDom method of Link. Creates a Link node and appends it to the current XML 
        document 
        """
        link = document.createElement('Link')
        assert (self.target != None), ("Target was none, name was %r" % self.attribute)
        link.appendChild(dataNode(document, 'Target', self.target.id))
        # this use of id will not work for purposes of being able to retrieve the intended
        # target from the xml later. I need a better unique identifier.
        assert self.attribute, "You can't xmlify a Link without a target attribute"
        link.appendChild(dataNode(document, 'Attribute', self.attribute))
        node.appendChild(link)

    def fromDom(cls, doc):
        targetid = doc.getElementsByTagName("Target")[0].firstChild.nodeValue.strip()
        attribute = doc.getElementsByTagName("Attribute")[0].firstChild.nodeValue.strip()
        l = cls(None, attribute)
        registerLink(targetid, l)
        return l

    fromDom = classmethod(fromDom)
    
    def writeXML(self,ostream=stdout):
        """
        writes an XML representation of self to the output stream ostream.
        If ostream is nor present the standart output stream is used.  If
        esysheader==True the esys XML header is written
        """
        print 'I got to the Link writeXML method'
        document, rootnode = esysDoc()
        self.toDom(document, rootnode)

        ostream.write(document.toprettyxml())

class LinkableObject(object):
    """
    An object that allows to link its attributes to attributes of other objects
    via a Link object. For instance
           
           p = LinkableObject()
           p.x = Link(o,"name")
           print p.x
    
    links attribute x of p to the attribute name of object o. 

    p.x will contain the current value of attribute name of object o.  

    If the value of getattr(o, "name") is callable, p.x will rturn the return
    value of the call. 
    """
   
    number_sequence = itertools.count(100)
    
    def __init__(self, debug=False):
        """ initializes LinkableObject so that we can operate on Links """
        self.debug = debug
        self.__linked_attributes={}
        self.id = self.number_sequence.next()

    def trace(self, msg):
        """ If debugging is on, print the message, otherwise do nothing
        """
        if self.debug:
            print "%s: %s"%(str(self),msg)
    
    def __getattr__(self,name):
        """returns the value of attribute name. If the value is a Link object the
        object is called and the return value is returned."""
        out = self.getAttributeObject(name)
        if isinstance(out,Link):
            return out()
        else:
            return out
    
    def getAttributeObject(self,name):
        """return the object stored for attribute name."""

        if self.__dict__.has_key(name):
            return self.__dict__[name]

        if self.__linked_attributes.has_key(name):
            return self.__linked_attributes[name]

        if self.__class__.__dict__.has_key(name):
            return self.__class.__dict__[name]

        raise AttributeError,"No attribute %s."%name
    
    def hasAttribute(self,name):
        """returns True if self as attribute name"""
        return self.__dict__.has_key(name) or self.__linked_attributes.has_key(name) or  self.__class__.__dict__.has_key(name)

    def __setattr__(self,name,value):
        """sets the value for attribute name. If value is a Link the target
        attribute is set to name if no attribute has been specified."""


        if self.__dict__.has_key(name): 
            del self.__dict__[name]

        if isinstance(value,Link):
            if not value.hasDefinedAttributeName(): 
                value.setAttributeName(name)
            self.__linked_attributes[name] = value

            self.trace("attribute %s is now linked by %s."%(name,value))
        else:
            self.__dict__[name] = value
    
    def __delattr__(self,name):
        """removes the attribute name."""

        if self.__linked_attributes.has_key[name]:
            del self.__linked_attributes[name]
        elif self.__dict__.has_key(name):
            del self.__dict__[name]
        else:
            raise AttributeError,"No attribute %s."%name

class _ParameterIterator:
    def __init__(self,parameterset):

        self.__set=parameterset
        self.__iter=iter(parameterset.parameters)

    def next(self):
        o=self.__iter.next()
        return (o,self.__set.getAttributeObject(o))

    def __iter__(self):
        return self

class ParameterSet(LinkableObject):
    """a class which allows to emphazise attributes to be written and read to XML
       
       Leaves of  an ESySParameters objects can be 
    
            a real number
            a integer number
            a string
            a boolean value
            a ParameterSet object 
            a Simulation object
            a Model object 
            any other object (not considered by writeESySXML and writeXML)
    
           Example how to create an ESySParameters object:
    
                 p11=ParameterSet(gamma1=1.,gamma2=2.,gamma3=3.)
                 p1=ParameterSet(dim=2,tol_v=0.001,output_file="/tmp/u.%3.3d.dx",runFlag=True,parm11=p11) 
                 parm=ParameterSet(parm1=p1,parm2=ParameterSet(alpha=Link(p11,"gamma1")))
    
           This can be accessed as 
    
                 parm.parm1.gamma=0.
                 parm.parm1.dim=2
                 parm.parm1.tol_v=0.001
                 parm.parm1.output_file="/tmp/u.%3.3d.dx"
                 parm.parm1.runFlag=True
                 parm.parm1.parm11.gamma1=1.
                 parm.parm1.parm11.gamma2=2.
                 parm.parm1.parm11.gamma3=3.
                 parm.parm2.alpha=1. (value of parm.parm1.parm11.gamma1)
             
    """
    def __init__(self, parameters=[], **kwargs):
        """creates a ParameterSet with parameters parameters"""
        LinkableObject.__init__(self, **kwargs)
        self.parameters = set()
        self.declareParameters(parameters)

    def __repr__(self):
        return "<%s %r>" % (self.__class__.__name__, 
                            [(p, getattr(self, p, None)) for p in self.parameters])
    
    def declareParameter(self,**parameters):
        """declares a new parameter(s) and its (their) inital value."""
        self.declareParameters(parameters)
    
    def declareParameters(self,parameters):
        """declares a set of parameters. parameters can be a list, a dictonary or a ParameterSet."""
        if isinstance(parameters,ListType):
            parameters = zip(parameters, itertools.repeat(None))
        if isinstance(parameters,DictType):
            parameters = parameters.iteritems()

        for prm, value in parameters:
            setattr(self,prm,value)
            self.parameters.add(prm)

            self.trace("parameter %s has been declared."%prm)

    def releaseParameters(self,name):
        """removes parameter name from the paramameters"""
        if self.isParameter(name): 
            self.parameters.remove(name)
            self.trace("parameter %s has been removed."%name)
    
    def __iter__(self):
        """creates an iterator over the parameter and their values"""
        return _ParameterIterator(self)
    
    def showParameters(self):
        """returns a descrition of the parameters"""        
        out="{"
        notfirst=False
        for i,v in self:
            if notfirst: out=out+","
            notfirst=True
            if isinstance(v,ParameterSet):
                out="%s\"%s\" : %s"%(out,i,v.showParameters())
            else:
                out="%s\"%s\" : %s"%(out,i,v)
        return out+"}"
    
    def __delattr__(self,name):
        """removes the attribute name."""
        LinkableObject.__delattr__(self,name)
        try:
            self.releaseParameter(name) 
        except:
            pass

    def toDom(self, document, node):
        """ toDom method of ParameterSet class """
        pset = document.createElement('ParameterSet')
        node.appendChild(pset)
        self._parametersToDom(document, pset)

    def _parametersToDom(self, document, node):
        node.setAttribute ('id', str(self.id))
        for name,value in self:
            param = document.createElement('Parameter')
            param.setAttribute('type', value.__class__.__name__)

            param.appendChild(dataNode(document, 'Name', name))

            val = document.createElement('Value')

            if isinstance(value,ParameterSet):
                value.toDom(document, val)
                param.appendChild(val)
            elif isinstance(value, Link):
                value.toDom(document, val)
                param.appendChild(val)
            elif isinstance(value,StringType):
                param.appendChild(dataNode(document, 'Value', value))
            else:
                param.appendChild(dataNode(document, 'Value', str(value)))

            node.appendChild(param)

    def fromDom(cls, doc):

        # Define a host of helper functions to assist us.
        def _children(node):
            """
            Remove the empty nodes from the children of this node
            """
            return [x for x in node.childNodes 
                    if not isinstance(x, minidom.Text) or x.nodeValue.strip()]

        def _floatfromValue(doc):
            return float(doc.nodeValue.strip())

        def _stringfromValue(doc):
            return str(doc.nodeValue.strip())
       
        def _intfromValue(doc):
            return int(doc.nodeValue.strip())

        def _boolfromValue(doc):
            return bool(doc.nodeValue.strip())
       
        # Mapping from text types in the xml to methods used to process trees of that type
        ptypemap = {"Simulation": Simulation.fromDom,
                    "Model":Model.fromDom,
                    "ParameterSet":ParameterSet.fromDom,
                    "Link":Link.fromDom,
                    "float":_floatfromValue,
                    "int":_intfromValue,
                    "str":_stringfromValue,
                    "bool":_boolfromValue
                    }

#        print doc.toxml()

        parameters = {}
        for node in _children(doc):
            ptype = node.getAttribute("type")

            pname = pvalue = None
            for childnode in _children(node):

                if childnode.tagName == "Name":
                    pname = childnode.firstChild.nodeValue.strip()

                if childnode.tagName == "Value":
                    nodes = _children(childnode)
                    pvalue = ptypemap[ptype](nodes[0])

            parameters[pname] = pvalue

        # Create the instance of ParameterSet
        o = cls()
        o.declareParameters(parameters)
        registerLinkableObject(doc.getAttribute("id"), o)
        return o
    
    fromDom = classmethod(fromDom)
    
    def writeXML(self,ostream=stdout):
        """writes the object as an XML object into an output stream"""
        # ParameterSet(d) with d[Name]=Value
        document, node = esysDoc()
        self.toDom(document, node)
        ostream.write(document.toprettyxml())

class Model(ParameterSet):
    """

    A Model object represents a processess marching over time
    until a finalizing condition is fullfilled. At each time step an iterative
    process can be performed and the time step size can be controlled. A Model has
    the following work flow:

          doInitialization()
          while not finalize():
               dt=getSafeTimeStepSize(dt)
               doStepPreprocessing(dt)
               while not terminateIteration(): doStep(dt)
               doStepPostprocessing(dt)
          doFinalization()

          where doInitialization,finalize, getSafeTimeStepSize, doStepPreprocessing, terminateIteration, doStepPostprocessing, doFinalization
          are methods of the particular instance of a Model. The default implementations of these methods have to be overwritten by 
          the subclass implementinf a Model.

    """

    UNDEF_DT=1.e300

    def __init__(self,parameters=[],**kwarg):
        """creates a model

            Just calls the parent constructor.
        """
        ParameterSet.__init__(self, parameters=parameters,**kwarg)

    def __str__(self):
       return "<%s %d>"%(self.__class__,id(self))

    def toDom(self, document, node):
        """ toDom method of Model class """
        pset = document.createElement('Model')
        pset.setAttribute('type', self.__class__.__name__)
        node.appendChild(pset)
        self._parametersToDom(document, pset)

    def doInitialization(self):
        """initializes the time stepping scheme. This function may be overwritten."""
        pass
    
    def getSafeTimeStepSize(self,dt):
        """returns a time step size which can safely be used. 
           dt gives the previously used step size.
           This function may be overwritten."""
        return self.UNDEF_DT
    
    def finalize(self):
        """returns False if the time stepping is finalized. This function may be
        overwritten."""
        return False
       
    def doFinalization(self):
        """finalizes the time stepping. This function may be overwritten."""
        pass
    
    def doStepPreprocessing(self,dt):
        """sets up a time step of step size dt. This function may be overwritten."""
        pass
    
    def doStep(self,dt):
        """executes an iteration step at a time step. 
           dt is the currently used time step size.
           This function may be overwritten."""
        pass
    
    def terminateIteration(self):
        """returns True if iteration on a time step is terminated."""
        return True
       
    def doStepPostprocessing(self,dt):
        """finalalizes the time step.
           dt is the currently used time step size.
           This function may be overwritten."""
        pass
    
    def writeXML(self, ostream=stdout):
        document, node = esysDoc()
        self.toDom(document, node)
        ostream.write(document.toprettyxml())
    
    
class Simulation(Model): 
    """
          A Simulation object is special Model which runs a sequence of Models. 

          The methods doInitialization,finalize, getSafeTimeStepSize, doStepPreprocessing,
          terminateIteration, doStepPostprocessing, doFinalization
          are executing the corresponding methods of the models in the simulation.
           
    """
    
    FAILED_TIME_STEPS_MAX=20
    MAX_ITER_STEPS=50
    
    def __init__(self, models=[], **kwargs):
        """initiates a simulation from a list of models. """
        Model.__init__(self, **kwargs)
        self.__models=[]

        for i in range(len(models)): 
            self[i] = models[i]

    def __repr__(self):
        """
        returns a string representation of the Simulation
        """
        return "<Simulation %r>" % self.__models

    def __str__(self):
        """
        returning Simulation as a string
        """
        return "<Simulation %d>"%id(self)
    
    def iterModels(self):
        """returns an iterator over the models"""
        return self.__models
    
    def __getitem__(self,i):
        """returns the i-th model"""
        return self.__models[i]
    
    def __setitem__(self,i,value):
        """sets the i-th model"""
        if not isinstance(value,Model):
            raise ValueError("assigned value is not a Model")
        for j in range(max(i-len(self.__models)+1,0)): self.__models.append(None)
        self.__models[i]=value
    
    def __len__(self):
        """returns the number of models"""
        return len(self.__models)

    def toDom(self, document, node):
        """ toDom method of Simulation class """
        simulation = document.createElement('Simulation')
        simulation.setAttribute('type', self.__class__.__name__)

        for rank, sim in enumerate(self.iterModels()):
            component = document.createElement('Component')
            component.setAttribute('rank', str(rank))

            sim.toDom(document, component)

            simulation.appendChild(component)

        node.appendChild(simulation)

    def writeXML(self,ostream=stdout):
        """writes the object as an XML object into an output stream"""
        document, rootnode = esysDoc()
        self.toDom(document, rootnode)
        ostream.write(document.toprettyxml())
    
    def getSafeTimeStepSize(self,dt):
        """returns a time step size which can safely be used by all models.
           This is the minimum over the time step sizes of all models."""
        out=min([o.getSafeTimeStepSize(dt) for o in self.iterModels()])
        print "%s: safe step size is %e."%(str(self),out)
        return out
    
    def doInitialization(self):
        """initializes all models """
        self.n=0
        self.tn=0.
        for o in self.iterModels(): 
            o.doInitialization()
    
    def finalize(self):
        """returns True if any of the models is to be finalized"""
        return any([o.finalize() for o in self.iterModels()])
       
    def doFinalization(self):
        """finalalizes the time stepping for all models."""
        for i in self.iterModels(): i.doFinalization()
        self.trace("end of time integation.")
    
    def doStepPreprocessing(self,dt):
        """initializes the time step for all models."""
        for o in self.iterModels(): 
            o.doStepPreprocessing(dt)
    
    def terminateIteration(self):
        """returns True if all iterations for all models are terminated."""
        out=all([o.terminateIteration() for o in self.iterModels()])
        return out
       
    def doStepPostprocessing(self,dt):
        """finalalizes the iteration process for all models."""
        for o in self.iterModels(): 
            o.doStepPostprocessing(dt)
        self.n+=1
        self.tn+=dt
    
    def doStep(self,dt):
        """
             executes the iteration step at a time step for all model:
 
                  self.doStepPreprocessing(dt)
                  while not self.terminateIteration(): for all models: self.doStep(dt)
                  self.doStepPostprocessing(dt)

        """
        self.iter=0
        while not self.terminateIteration(): 
            if self.iter==0: self.trace("iteration at %d-th time step %e starts"%(self.n+1,self.tn+dt))
            self.iter+=1
            self.trace("iteration step %d"%(self.iter))
            for o in self.iterModels(): 
                  o.doStep(dt)
        if self.iter>0: self.trace("iteration at %d-th time step %e finalized."%(self.n+1,self.tn+dt))

    def run(self,check_point=None):
        """

           run the simulation by performing essentially 
    
               self.doInitialization()
               while not self.finalize():
                  dt=self.getSafeTimeStepSize()
                  self.doStep(dt)
                  if n%check_point==0: self.writeXML() 
               self.doFinalization()

           If one of the models in throws a FailedTimeStepError exception a new time step size is 
           computed through getSafeTimeStepSize() and the time step is repeated.
   
           If one of the models in throws a IterationDivergenceError exception the time step size 
           is halved and the time step is repeated.

           In both cases the time integration is given up after Simulation.FAILED_TIME_STEPS_MAX
           attempts.

    
        """
        dt=self.UNDEF_DT
        self.doInitialization()
        while not self.finalize():
            step_fail_counter=0
            iteration_fail_counter=0
            dt_new=self.getSafeTimeStepSize(dt)
            self.trace("%d. time step %e (step size %e.)" % (self.n+1,self.tn+dt_new,dt_new))
            end_of_step=False
            while not end_of_step:
               end_of_step=True
               if not dt_new>0:
                  raise NonPositiveStepSizeError("non-positive step size in step %d",self.n+1)
               try:
                  self.doStepPreprocessing(dt_new)
                  self.doStep(dt_new)
                  self.doStepPostprocessing(dt_new)
               except IterationDivergenceError:
                  dt_new*=0.5
                  end_of_step=False
                  iteration_fail_counter+=1
                  if iteration_fail_counter>self.FAILED_TIME_STEPS_MAX:
                           raise SimulationBreakDownError("reduction of time step to achieve convergence failed.")
                  self.trace("iteration fails. time step is repeated with new step size.")
               except FailedTimeStepError:
                  dt_new=self.getSafeTimeStepSize(dt)
                  end_of_step=False
                  step_fail_counter+=1
                  self.trace("time step is repeated.")
                  if step_fail_counter>self.FAILED_TIME_STEPS_MAX:
                        raise SimulationBreakDownError("time integration is given up after %d attempts."%step_fail_counter)
            dt=dt_new
            if not check_point==None:
                if n%check_point==0: 
                    self.trace("check point is created.")
                    self.writeXML()
        self.doFinalization()

    def fromDom(cls, doc):
        sims = []
        for node in doc.childNodes:
            if isinstance(node, minidom.Text):
                continue

            sims.append(getComponent(node))

        return cls(sims)

    fromDom = classmethod(fromDom)


class IterationDivergenceError(Exception):
    """
       excpetion which is thrown if there is no convergence of the iteration process at a time step 
       but there is a chance taht a smaller step could help to reach convergence.

    """
    pass

class FailedTimeStepError(Exception):
    """excpetion which is thrown if the time step fails because of a step size that have been choosen to be too large"""
    pass

class SimulationBreakDownError(Exception):
    """excpetion which is thrown if the simulation does not manage to progress in time."""
    pass

class NonPositiveStepSizeError(Exception):
    """excpetion which is thrown if the step size is not positive"""
    pass
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision