esys.escript.modelframe Package

Classes

class esys.escript.modelframe.DataSource(uri='file.ext', fileformat='unknown')

Bases: object

Class for handling data sources, including local and remote files. This class is under development.

__init__(uri='file.ext', fileformat='unknown')

Initialize self. See help(type(self)) for accurate signature.

classmethod fromDom(esysxml, node)
getLocalFileName()
toDom(esysxml, node)

toDom method of DataSource. Creates a DataSource node and appends it to the current XML esysxml.

class esys.escript.modelframe.ESySXMLCreator

Bases: object

Creates an XML Dom representation.

__init__()

Initialize self. See help(type(self)) for accurate signature.

createDataNode(tagName, data)

createDataNode s are the building blocks of the XML documents constructed in this module.

Parameters:
  • tagName – the associated XML tag
  • data – the values in the tag
createElement(name)
createTextNode(name)
getElementById(name)
getLinkableObjectId(obj)
getRoot()
includeTargets()
registerLinkableObject(obj, node)

Returns a unique object id for object obj.

toprettyxml()
class esys.escript.modelframe.ESySXMLParser(xml, debug=False)

Bases: object

Parser for an ESysXML file.

__init__(xml, debug=False)

Initialize self. See help(type(self)) for accurate signature.

getClassPath(node)
getComponent(node)

Returns a single component + rank from a simulation.

parse()

Parses EsysXML and returns the list of generating ParameterSets.

registerLinkableObject(obj, node)
class esys.escript.modelframe.FailedTimeStepError

Bases: Exception

Exception which is thrown if the time step fails because of a step size that has been chosen to be too large.

__init__()

Initialize self. See help(type(self)) for accurate signature.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class esys.escript.modelframe.IterationDivergenceError

Bases: Exception

Exception which is thrown if there is no convergence of the iteration process at a time step.

But there is a chance that a smaller step could help to reach convergence.

__init__()

Initialize self. See help(type(self)) for accurate signature.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Bases: object

A Link makes an attribute of an object callable:

o.object()
o.a=8
l=Link(o,"a")
assert l()==8
__init__(target, attribute=None)

Creates a link to the object target. If attribute is given, the link is established to this attribute of the target. Otherwise the attribute is undefined.

classmethod fromDom(esysxml, node)
getAttributeName()

Returns the name of the attribute the link is pointing to.

getTarget()

Returns the target.

hasDefinedAttributeName()

Returns true if an attribute name is set.

setAttributeName(attribute)

Sets a new attribute name to be collected from the target object. The target object must have the attribute with name attribute.

toDom(esysxml, node)

toDom method of Link. Creates a Link node and appends it to the current XML esysxml.

class esys.escript.modelframe.LinkableObject(id=None, debug=False)

Bases: 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 return the return value of the call.

__init__(id=None, debug=False)

Initializes LinkableObject so that we can operate on Links.

getAttributeObject(name)

Returns the object stored for attribute name.

hasAttribute(name)

Returns True if self has attribute name.

trace(msg)

If debugging is on, prints the message, otherwise does nothing.

Bases: Exception

Exception which is thrown when a link is missing.

__init__()

Initialize self. See help(type(self)) for accurate signature.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class esys.escript.modelframe.Model(parameters=[], **kwargs)

Bases: esys.escriptcore.modelframe.ParameterSet

A Model object represents a process marching over time until a finalizing condition is fulfilled. 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 terminateInitialIteration(): doInitialStep()
doInitialPostprocessing()
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 implementing a Model.

__init__(parameters=[], **kwargs)

Creates a model.

Just calls the parent constructor.

UNDEF_DT = 1e+300
checkLinkTargets(models, hash)

Returns a set of tuples (“<self>(<name>)”, <target model>) if the parameter <name> is linked to model <target model> but <target model> is not in the list of models. If a parameter is linked to another parameter set which is not in the hash list the parameter set is checked for its models. hash gives the call history.

declareParameter(**parameters)

Declares one or more new parameters and their initial value.

declareParameters(parameters)

Declares a set of parameters. parameters can be a list, a dictionary or a ParameterSet.

doFinalization()

Finalizes the time stepping.

This function may be overwritten.

doInitialPostprocessing()

Finalises the initialization iteration process. This method is not called in case of a restart.

This function may be overwritten.

doInitialStep()

Performs an iteration step in the initialization phase. This method is not called in case of a restart.

This function may be overwritten.

doInitialization()

Initializes the time stepping scheme. This method is not called in case of a restart.

This function may be overwritten.

doStep(dt)

Executes an iteration step at a time step.

dt is the currently used time step size.

This function may be overwritten.

doStepPostprocessing(dt)

Finalises the time step.

dt is the currently used time step size.

This function may be overwritten.

doStepPreprocessing(dt)

Sets up a time step of step size dt.

This function may be overwritten.

finalize()

Returns False if the time stepping is finalized.

This function may be overwritten.

classmethod fromDom(esysxml, node)
getAttributeObject(name)

Returns the object stored for attribute name.

getSafeTimeStepSize(dt)

Returns a time step size which can be safely used.

dt gives the previously used step size.

This function may be overwritten.

hasAttribute(name)

Returns True if self has attribute name.

releaseParameters(name)

Removes parameter name from the parameters.

setUp()

Sets up the model.

This function may be overwritten.

showParameters()

Returns a description of the parameters.

terminateInitialIteration()

Returns True if iteration at the inital phase is terminated.

terminateIteration()

Returns True if iteration on a time step is terminated.

toDom(esysxml, node)

toDom method of Model class.

trace(msg)

If debugging is on, prints the message, otherwise does nothing.

writeXML(ostream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Writes the object as an XML object into an output stream.

class esys.escript.modelframe.NonPositiveStepSizeError

Bases: Exception

Exception which is thrown if the step size is not positive.

__init__()

Initialize self. See help(type(self)) for accurate signature.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class esys.escript.modelframe.ParameterSet(parameters=[], **kwargs)

Bases: esys.escriptcore.modelframe.LinkableObject

A class which allows to emphasize attributes to be written and read to XML.

Leaves of an ESySParameters object can be:

  • a real number
  • an integer number
  • a string
  • a boolean value
  • a ParameterSet object
  • a Simulation object
  • a Model object
  • a numpy object
  • a list of booleans
  • any other object (not considered by writeESySXML and writeXML)

Example for 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)
__init__(parameters=[], **kwargs)

Creates a ParameterSet with given parameters.

checkLinkTargets(models, hash)

Returns a set of tuples (“<self>(<name>)”, <target model>) if the parameter <name> is linked to model <target model> but <target model> is not in the list of models. If a parameter is linked to another parameter set which is not in the hash list the parameter set is checked for its models. hash gives the call history.

declareParameter(**parameters)

Declares one or more new parameters and their initial value.

declareParameters(parameters)

Declares a set of parameters. parameters can be a list, a dictionary or a ParameterSet.

classmethod fromDom(esysxml, node)
getAttributeObject(name)

Returns the object stored for attribute name.

hasAttribute(name)

Returns True if self has attribute name.

releaseParameters(name)

Removes parameter name from the parameters.

showParameters()

Returns a description of the parameters.

toDom(esysxml, node)

toDom method of Model class.

trace(msg)

If debugging is on, prints the message, otherwise does nothing.

writeXML(ostream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Writes the object as an XML object into an output stream.

class esys.escript.modelframe.RestartManager(dump_time=1080.0, dump_step=None, dumper=None)

Bases: object

A restart manager which does two things: it decides when restart files were created (when doDump returns true) and manages directories for restart files. The method getNewDumper creates a new directory and returns its name.

This restart manager will decide to dump restart files every dump_step calls of doDump or if more than dump_time since the last dump has elapsed. The restart manager controls two directories for dumping restart data, namely for the current and previous dump. This way the previous dump can be used for restart in the case the current dump failed.

Variables:
  • SEC – unit of seconds, for instance 5*RestartManager.SEC defines 5 seconds
  • MIN – unit of minutes, for instance 5*RestartManager.MIN defines 5 minutes
  • H – unit of hours, for instance 5*RestartManager.H defines 5 hours
  • D – unit of days, for instance 5*RestartManager.D defines 5 days
__init__(dump_time=1080.0, dump_step=None, dumper=None)

Initializes the RestartManager.

Parameters:
  • dump_time – defines the minimum time interval in SEC between two dumps. If None, time is not used as criterion.
  • dump_step – defines the number of calls of doDump between two dump events. If None, the call counter is not used as criterion.
  • dumper – defines the directory for dumping restart files. Additionally, the directories dumper+”_bkp” and dumper+”_bkp2” are used. If the directory does not exist it is created. If dumper is not present a unique directory within the current working directory is used.
D = 8640.0
H = 360.0
MIN = 60.0
SEC = 1.0
doDump()

Returns true if the restart should be dumped. Use getNewDumper to retrieve the directory name to be used for dumping.

getCurrentDumper()

Returns the name of the currently used dumper.

getNewDumper()

Creates a new directory to be used for dumping and returns its name.

class esys.escript.modelframe.Simulation(models=[], **kwargs)

Bases: esys.escriptcore.modelframe.Model

A Simulation object is a special Model which runs a sequence of Models.

The methods doInitialization, finalize, getSafeTimeStepSize, doStepPreprocessing, terminateIteration, doStepPostprocessing, doFinalization execute the corresponding methods of the models in the simulation.

__init__(models=[], **kwargs)

Initiates a simulation from a list of models.

FAILED_TIME_STEPS_MAX = 20
MAX_CHANGE_OF_DT = 2.0
MAX_ITER_STEPS = 50
UNDEF_DT = 1e+300
checkLinkTargets(models, hash)

Returns a set of tuples (“<self>(<name>)”, <target model>) if the parameter <name> is linked to model <target model> but <target model> is not in the list of models. If a parameter is linked to another parameter set which is not in the hash list the parameter set is checked for its models. hash gives the call history.

checkModels(models, hash)

Returns a list of (model, parameter, target model) if the parameter of model is linking to the target_model which is not in the list of models.

declareParameter(**parameters)

Declares one or more new parameters and their initial value.

declareParameters(parameters)

Declares a set of parameters. parameters can be a list, a dictionary or a ParameterSet.

doFinalization()

Finalises the time stepping for all models.

doInitialPostprocessing()

Finalises the initialization iteration process for all models.

doInitialStep()

Performs an iteration step in the initialization step for all models.

doInitialization()

Initializes all models.

doStep(dt)

Executes the iteration step at a time step for all models

doStepPostprocessing(dt)

Finalises the iteration process for all models.

doStepPreprocessing(dt)

Initializes the time step for all models.

finalize()

Returns True if any of the models is to be finalized.

classmethod fromDom(esysxml, node)
getAllModels()

Returns a list of all models used in the Simulation including subsimulations.

getAttributeObject(name)

Returns the object stored for attribute name.

getSafeTimeStepSize(dt)

Returns a time step size which can be safely used by all models.

This is the minimum over the time step sizes of all models.

hasAttribute(name)

Returns True if self has attribute name.

iterModels()

Returns an iterator over the models.

releaseParameters(name)

Removes parameter name from the parameters.

run(check_pointing=None)

Runs the simulation by performing essentially:

self.setUp()
if not restart:
    self.doInitialization()
    while not self.terminateInitialIteration(): self.doInitialStep()
    self.doInitialPostprocessing()
while not self.finalize():
    dt=self.getSafeTimeStepSize()
    self.doStepPreprocessing(dt_new)
    self.doStep(dt_new)
    self.doStepPostprocessing(dt_new)
self.doFinalization()

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

If one of the models 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.

setUp()

Performs the setup for all models.

showParameters()

Returns a description of the parameters.

terminateInitialIteration()

Returns True if all initial iterations for all models are terminated.

terminateIteration()

Returns True if all iterations for all models are terminated.

toDom(esysxml, node)

toDom method of Simulation class.

trace(msg)

If debugging is on, prints the message, otherwise does nothing.

writeXML(ostream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Writes the object as an XML object into an output stream.

class esys.escript.modelframe.SimulationBreakDownError

Bases: Exception

Exception which is thrown if the simulation does not manage to progress in time.

__init__()

Initialize self. See help(type(self)) for accurate signature.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Functions

esys.escript.modelframe.all(seq)

Returns True if no element in seq is None, False otherwise.

esys.escript.modelframe.any(seq)

Returns True if not all elements in seq are None, False otherwise.

esys.escript.modelframe.importName(modulename, name)

Imports a named object from a module in the context of this function, which means you should use fully qualified module paths. Returns None on failure.

This function is from http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52241

Others

  • reduce

Packages