# esys.escript.modelframe Package

## Classes

- `DataSource`
- `ESySXMLCreator`
- `ESySXMLParser`
- `FailedTimeStepError`
- `IterationDivergenceError`
- `Link`
- `LinkableObject`
- `MissingLink`
- `Model`
- `NonPositiveStepSizeError`
- `ParameterSet`
- `RestartManager`
- `Simulation`
- `SimulationBreakDownError`

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.

  `registerLink`(obj_id, link)
  `registerLinkableObject`(obj, node)
  `setLinks`()

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.

class `esys.escript.modelframe.``Link`(target, attribute=None)

  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.

class `esys.escript.modelframe.``MissingLink`

  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