ptolemy.domains.ct.kernel
Class ODESolver

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.domains.ct.kernel.ODESolver

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

DerivativeResolver, ExplicitRK23Solver, ExplicitRK45Solver, FixedStepSolver, TrapezoidalRuleSolver

public abstract class ODESolver
extends NamedObj

Abstract base class for ODE solvers. The key methods for the class are fireDynamicActors() and fireStateTransitionActors(). CT directors call these methods to resolve the initial states in a future time in the continuous phase of execution of a complete iteration. See CTMultiSolverDirector for explanation of initial states and phases of executions. The process of resolving the initial states in a future time is also known as an integration. A complete integration is composed of one or more rounds of executions. One round of execution consists of calling fireDynamicActors() once followed by calling fireStateTransitionActors() once. How the states are resolved are solver dependent. Derived classes need to implement these methods according to their 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 delegates its corresponding methods to this class. And subclasses of this class provide concrete implementations of these methods.

How many rounds are needed in one integration is solver dependent. For some solving algorithms, (i.e. the so called explicit methods) the number of rounds is fixed. For some others (i.e. implicit methods), the number of rounds can not be decided beforehand.

A round counter is a counter for the number of rounds in one integration. It helps the solvers to decide how to behave under different rounds. The round counter can be retrieved by the _getRoundCount() method. The _incrementRoundCount() method will increase the counter by one, and _resetRoundCount() will always reset the counter to 0. These methods are protected because they are only used by solvers and CT directors.

In this class, two methods _isConverged and _voteForConverged(boolean) are defined to let CT directors know the status of resolved states. If multiple integrators exist, only when all of them vote true for converged, will the _isConverged() return true. Another related method is resolveStates(), which always returns true in this base class. However, in the solvers that implement the implicit solving methods, this method may return false if the maximum number of iterations is reached but states have not been resolved.

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 57040 2010-01-27 20:52:32Z cxh $

Author:

Jie Liu, Haiyang Zheng

See Also:

Serialized Form

Accepted Rating:

Green (hyzheng)

Proposed Rating:

Green (hyzheng)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

private CTDirector	_director
private boolean	_isConverged
private int	_roundCount

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Constructor Summary

ODESolver(Workspace workspace)
Construct a solver in the given workspace with a null string name.

Method Summary

protected void	_advanceModelTime() Advance the current model time.
protected int	_getRoundCount() Return the number of the round counter.
protected CTSchedule	_getSchedule() Get the current schedule.
protected void	_incrementRoundCount() Increase the round counter by one.
protected boolean	_isConverged() Return true if all integrators agree that the current states have converged to a fixed point.
protected void	_makeSolverOf(CTDirector director) Make this solver the solver of the given Director.
protected void	_resetRoundCount() Reset the round counter to 0.
protected void	_setConverged(boolean converged) Set a flag to indicate whether the fixed point of states has been reached.
protected void	_voteForConverged(boolean converged) An integrator calls this method to vote whether a fixed point has been reached.
void	fireDynamicActors() Fire dynamic actors.
void	fireStateTransitionActors() Fire state transition actors.
abstract int	getAmountOfHistoryInformation() Return the amount of history information needed by this solver.
NamedObj	getContainer() Return the director that contains this solver.
abstract int	getIntegratorAuxVariableCount() Return the number of auxiliary variables that an integrator should provide when solving the ODE.
abstract void	integratorFire(CTBaseIntegrator integrator) Perform one integration step.
abstract boolean	integratorIsAccurate(CTBaseIntegrator integrator) Return true if the current integration step is accurate from the argument integrator's point of view.
abstract double	integratorPredictedStepSize(CTBaseIntegrator integrator) The predictedStepSize() method of the integrator delegates to this method.
boolean	resolveStates() Return true if the states of the system have been resolved successfully.

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _description, _exportMoMLContents, _getContainedObject, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateExistence, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setName, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_director

private CTDirector _director

_isConverged

private boolean _isConverged

_roundCount

private int _roundCount

Constructor Detail

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

Method Detail

fireDynamicActors

public void fireDynamicActors()
                       throws IllegalActionException

Fire dynamic actors. Derived classes may advance the model time. The amount of time increment depends on the solving algorithms.

Throws:

IllegalActionException - If schedule can not be found or dynamic actors throw it from their fire() methods.

fireStateTransitionActors

public void fireStateTransitionActors()
                               throws IllegalActionException

Fire state transition actors. See CTScheduler for explanation of state transition actors. Derived classes may increase the round count.

Throws:

IllegalActionException - If schedule can not be found or state transition actors throw it from their fire() methods.

getAmountOfHistoryInformation

public abstract int getAmountOfHistoryInformation()

Return the amount 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. In particular, if a solver needs no history information, this method returns 0.

Returns:

The amount of history information needed.

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.

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.
For example, the fixed-step solvers need 0 auxiliary variable, but the RK23 solver needs 4 auxiliary variables to store the temporary derivatives at different time points during an integration.

Returns:

The number of auxiliary variables.

integratorFire

public abstract void integratorFire(CTBaseIntegrator integrator)
                             throws IllegalActionException

Perform one integration step. The fire() method of integrators delegates to this method. Derived classes need to implement the details.

Parameters:

integrator - The integrator that calls this method.

Throws:

IllegalActionException - Not thrown in this base class.

integratorIsAccurate

public abstract boolean integratorIsAccurate(CTBaseIntegrator integrator)

Return true if the current integration step is accurate from the argument integrator's point of view. The integratorIsAccurate() method of integrators delegates to this method. Derived classes need to implement the details.

Parameters:

integrator - The integrator 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 delegates to this method. Derived classes need to implement the details.

Parameters:

integrator - The integrator that calls this method.

Returns:

The suggested next step size by the given integrator.

resolveStates

public boolean resolveStates()
                      throws IllegalActionException

Return true if the states of the system have been resolved successfully. In this base class, always return true. Derived classes may change the returned value.

Returns:

True If states of the system have been resolved successfully.

Throws:

IllegalActionException - Not thrown in this base class.

_advanceModelTime

protected void _advanceModelTime()
                          throws IllegalActionException

Advance the current model time. In this abstract base class, nothing is done. The derived classes specify the detailed implementations.

Throws:

IllegalActionException - Not thrown in this abstract base class.

_getRoundCount

protected int _getRoundCount()

Return the number of the round counter.

Returns:

The number of the round counter.

_getSchedule

protected CTSchedule _getSchedule()
                           throws IllegalActionException

Get the current schedule.

Returns:

The current schedule.

Throws:

IllegalActionException - If this solver is not contained by a CT director, or the director does not have a scheduler.

_incrementRoundCount

protected void _incrementRoundCount()

Increase the round counter by one. In general, the round counter will be increased for each time the state transition actors are fired.

_isConverged

protected boolean _isConverged()

Return true if all integrators agree that the current states have converged to a fixed point.

Returns:

Return true if all integrators agree that the current states have converged to a fixed point.

_makeSolverOf

protected void _makeSolverOf(CTDirector director)

Make this solver the solver of the given Director. This method should only be called by CT directors, when they instantiate solvers according to the ODESolver parameters.

Parameters:

director - The CT director that contains this solver.

_resetRoundCount

protected void _resetRoundCount()

Reset the round counter to 0. This method is called when either the fixed-point solution of states has been found or the current integration fails to find the fixed-point solution within the maximum number of rounds.

_setConverged

protected void _setConverged(boolean converged)

Set a flag to indicate whether the fixed point of states has been reached. Solvers and CT directors may call this method to change the convergence.

This method should not be called by individual integrators. If an integrator thinks the states have not converged, it should call the _voteForConverged() method, which influences the convergence of the solver.

Parameters:

converged - The flag setting.

See Also:

_voteForConverged(boolean)

_voteForConverged

protected void _voteForConverged(boolean converged)

An integrator calls this method to vote whether a fixed point has been reached. The final result is the logic and of votes from all integrators. This method is particularly designed for integrators and it should be called from the integratorFire() method. Solvers and CT directors should use _setConverged() instead.

Parameters:

converged - True if vote for convergence.

See Also:

integratorFire(ptolemy.domains.ct.kernel.CTBaseIntegrator), _setConverged(boolean)