# 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')

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

  __init__(uri='file.ext', fileformat='unknown')
  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

  Creates an XML Dom representation.

  __init__()
  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)

  Parser for an ESysXML file.

  __init__(xml, debug=False)
  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

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

  __init__(*args, **kwargs)

class esys.escript.modelframe.IterationDivergenceError

  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__(*args, **kwargs)

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

  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)

  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

  Exception which is thrown when a link is missing.

  __init__(*args, **kwargs)

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

  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
  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.

  getSafeTimeStepSize(dt)

    Returns a time step size which can be safely used.

    `dt` gives the previously used step size.

    This function may be overwritten.

  setUp()

    Sets up the model.

    This function may be overwritten.

  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.

class esys.escript.modelframe.NonPositiveStepSizeError

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

  __init__(*args, **kwargs)

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

  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)
  releaseParameters(name)

    Removes parameter name from the parameters.

  showParameters()

    Returns a description of the parameters.

  toDom(esysxml, node)

    `toDom` method of Model class.

  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)

  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)

  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
  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.

  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.

  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.

  iterModels()

    Returns an iterator over the models.

  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.

  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.

class esys.escript.modelframe.SimulationBreakDownError

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

  __init__(*args, **kwargs)

## 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