ptolemy.domains.ct.kernel
Class ODESolver

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.domains.ct.kernel.ODESolver
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable
Direct Known Subclasses:
DerivativeResolver, ExplicitRK23Solver, FixedStepSolver, TrapezoidalRuleSolver

public abstract class ODESolver
extends NamedObj

Abstract base class for ODE solvers. The key method for the class is resolveState(), which executes the integration method for one step. This method does not consider any breakpoints. In general, resolveState() will resolve the integrators' new states. Step size control (including error control) is performed by the director, but solvers may provide support for it. How the states are resolved and how the errors are controlled are solver dependent. Derived classes may implement these methods according to individual ODE solving algorithms.

The behavior of integrators also changes when changing the ODE solver, so this class provides some methods for the integrators too, including the fire() method and the step size control related methods. Here we use the strategy and delegation design patterns. CTBaseIntegrator delegated its corresponding methods to this class. And subclasses of this class provide concrete implementations of these methods.

An integer called "round" is used to indicate the number of firing rounds within one iteration. For some integration methods, (i.e. the so called explicit methods) the round of firings are fixed. For some others (i.e. implicit methods), the round could be an arbitrary positive integer.

A round counter is a counter for the number of fire() rounds in one iteration to help the actors that may behave differently under different rounds. The round can be got by the getRound() method. The incrementRound() method will increase the counter by one, and resetRound() will always reset the counter to 0.

Conceptually, ODE solvers do not maintain simulation parameters, like step sizes and error tolerance. They get these parameters from the director. So the same set of parameters are shared by all the solvers in a simulation.

Since:
Ptolemy II 0.2
Version:
$Id: ODESolver.java,v 1.55 2004/04/13 03:26:48 cxh Exp $
Author:
Jie Liu
See Also:
Serialized Form
Accepted Rating:
Green (yuhong)
Proposed Rating:
Green (liuj)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Field Summary
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
 
Constructor Summary
ODESolver()
          Construct a solver in the default workspace with an empty string as name.
ODESolver(Workspace workspace)
          Construct a solver in the given workspace with a null string name.
ODESolver(Workspace workspace, java.lang.String name)
          Construct a solver in the given workspace with the given name.
 
Method Summary
protected  void _makeSolverOf(Director dir)
          Make this solver to be the solver of the given Director.
protected  void _prefireIfNecessary(Actor actor)
          If the specified actor has not be prefired() in the current iteration, then prefire() it.
 NamedObj getContainer()
          Return the director that contains this solver.
abstract  int getHistoryCapacityRequirement()
          Return the number of history information needed by this solver.
abstract  int getIntegratorAuxVariableCount()
          Return the number of auxiliary variables that an integrator should provide when solving the ODE.
 int getRound()
          Return the round counter record.
 void incrementRound()
          Increase the round counter by one.
abstract  void integratorFire(CTBaseIntegrator integrator)
          The fire() method of integrators is delegated to this method.
abstract  boolean integratorIsAccurate(CTBaseIntegrator integrator)
          The isThisStepAccurate() method of integrators is delegated to this method.
abstract  double integratorPredictedStepSize(CTBaseIntegrator integrator)
          The predictedStepSize() method of the integrator is delegated to this method.
 void resetRound()
          Reset the round counter to 0.
abstract  boolean resolveStates()
          Return true if the state of the system is resolved successfully.
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _description, _exportMoMLContents, _getContainedObject, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateExistence, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setName, setPersistent, setSource, toplevel, toString, uniqueName, validateSettables, workspace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ODESolver

public ODESolver()
Construct a solver in the default workspace with an empty string as name. The solver is added to the list of objects in the workspace. Increment the version number of the workspace.


ODESolver

public ODESolver(Workspace workspace)
Construct a solver in the given workspace with a null string name. If the workspace argument is null, use the default workspace. The director is added to the list of objects in the workspace. Increment the version number of the workspace.

Parameters:
workspace - Object for synchronization and version tracking

ODESolver

public ODESolver(Workspace workspace,
                 java.lang.String name)
          throws IllegalActionException
Construct a solver in the given workspace with the given name. If the workspace argument is null, use the default workspace. The solver is added to the list of objects in the workspace. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace.

Parameters:
workspace - Object for synchronization and version tracking
name - Name of this solver.
Throws:
IllegalActionException - If the name has a period.
Method Detail

getContainer

public final NamedObj getContainer()
Return the director that contains this solver.

Specified by:
getContainer in interface Nameable
Overrides:
getContainer in class NamedObj
Returns:
the director that contains this solver.

getHistoryCapacityRequirement

public abstract int getHistoryCapacityRequirement()
Return the number of history information needed by this solver. Some solvers need history information from each integrator. The derived class should implement this method to return the number of history information needed so that the integrator can prepare for that in advance.

Returns:
The number of history information needed.

getIntegratorAuxVariableCount

public abstract int getIntegratorAuxVariableCount()
Return the number of auxiliary variables that an integrator should provide when solving the ODE. Auxiliary variables are variables in integrators to store integrator-dependent intermediate results when solving an ODE.

Returns:
The number of auxiliary variables.

getRound

public int getRound()
Return the round counter record.

Returns:
The round of firing the state transition schedule.

incrementRound

public void incrementRound()
Increase the round counter by one. In general, the round counter will be increased for each round the state transition schedule is fired.


integratorFire

public abstract void integratorFire(CTBaseIntegrator integrator)
                             throws IllegalActionException
The fire() method of integrators is delegated to this method.

Parameters:
integrator - The integrator of that calls this method.
Throws:
IllegalActionException - Not thrown in this base class. May be needed by the derived class.

integratorIsAccurate

public abstract boolean integratorIsAccurate(CTBaseIntegrator integrator)
The isThisStepAccurate() method of integrators is delegated to this method. It returns true if the current integration step is accurate from the argument integrator's point of view.

Parameters:
integrator - The integrator of that calls this method.
Returns:
True if the integrator finds the step accurate.

integratorPredictedStepSize

public abstract double integratorPredictedStepSize(CTBaseIntegrator integrator)
The predictedStepSize() method of the integrator is delegated to this method.

Parameters:
integrator - The integrator of that calls this method.
Returns:
The suggested next step by the given integrator.

resetRound

public void resetRound()
Reset the round counter to 0.


resolveStates

public abstract boolean resolveStates()
                               throws IllegalActionException
Return true if the state of the system is resolved successfully. Different solvers may implement it differently. Implementations of this method will fire STATE_TRANSITION_ACTORS and DYNAMIC actors.

Throws:
IllegalActionException - Thrown in derived classes if the exception is thrown by * one of the execution methods of some actors.

_makeSolverOf

protected void _makeSolverOf(Director dir)
Make this solver to be the solver of the given Director. This method should not be called directly. The solvers will be instantiated by the director according to the parameters.

Parameters:
dir - The CT director

_prefireIfNecessary

protected void _prefireIfNecessary(Actor actor)
                            throws IllegalActionException
If the specified actor has not be prefired() in the current iteration, then prefire() it.

Parameters:
actor - The actor to prefire().
Throws:
IllegalActionException - If the actor returns false.