ptolemy.domains.ct.kernel
Class CTBaseIntegrator

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.InstantiableNamedObj
          extended byptolemy.kernel.Entity
              extended byptolemy.kernel.ComponentEntity
                  extended byptolemy.actor.AtomicActor
                      extended byptolemy.actor.TypedAtomicActor
                          extended byptolemy.domains.ct.kernel.CTBaseIntegrator
All Implemented Interfaces:
Actor, Changeable, java.lang.Cloneable, CTDynamicActor, CTStatefulActor, CTStepSizeControlActor, Debuggable, DebugListener, Derivable, Executable, Instantiable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable, TimedActor, TypedActor
Direct Known Subclasses:
Integrator

public class CTBaseIntegrator
extends TypedAtomicActor
implements TimedActor, CTStepSizeControlActor, CTDynamicActor, CTStatefulActor

Base class for integrators in the continuous time (CT) domain. An integrator has one input port and one output port. Conceptually, the input is the derivative of the output w.r.t. time. So an ordinary differential equation dx/dt = f(x, t) can be built by:

   
               +---------------+
   
        dx/dt  |               |   x
   
    +--------->|   Integrator  |---------+----->
   
    |          |               |         |
   
    |          +---------------+         |
   
    |                                    |
   
    |             |---------|            |
   
    +-------------| f(x, t) |<-----------+
   
                  |---------|
   

An integrator is a dynamic actor that can emit a token (the state) without knowing the input. An integrator is a step size control actor that can control the accuracy of the ODE solution by adjusting step sizes. An integrator has memory, which is its state.

To help solving the ODE, a set of variables are used:
state: This is the value of the state variable at a time point, which has beed confirmed by all the step size control actors. tentative state: This is the value of the state variable which has not been confirmed. It is a starting point for other actors to estimate the accuracy of this integration step. history: The previous states and their derivatives. History may be used by multistep methods.

For different ODE solving methods, the functionality of an integrator may be different. The delegation and strategy design patterns are used in this class, ODESolver class, and the concrete ODE solver classes. Some solver-dependent methods of integrators are delegated to the ODE solvers.

An integrator has one parameter: the initialState. At the initialization stage of the simulation, the state of the integrator is set to the initial state. Changes of the initialState parameter are ignored after the execution starts, unless the initialize() method is called again. The default value of the parameter is 0.0 of type DoubleToken.

An integrator can possibly have several auxiliary variables for the the ODE solvers to use. The number of the auxiliary variables is checked before each iteration. The ODE solver class provides the number of variables needed for that particular solver. The auxiliary variables can be set and get by setAuxVariables() and getAuxVariables() methods.

Since:
Ptolemy II 0.2
Version:
$Id: CTBaseIntegrator.java,v 1.83.2.1 2004/06/20 03:10:43 cxh Exp $
Author:
Jie Liu
See Also:
ODESolver, CTDirector, Serialized Form
Accepted Rating:
Green (yuhong)
Proposed Rating:
Green (liuj)

Nested Class Summary
protected  class CTBaseIntegrator.History
          The history information, state and derivatives, at equidistance past time points.
 
Nested classes inherited from class ptolemy.kernel.Entity
Entity.ContainedObjectsIterator
 
Field Summary
protected  CTBaseIntegrator.History _history
          The history states and their derivative.
 Parameter initialState
          The initial state of type DoubleToken.
 TypedIOPort input
          The input port.
 TypedIOPort output
          The output port.
 
Fields inherited from class ptolemy.actor.AtomicActor
_stopRequested
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
 
Fields inherited from interface ptolemy.actor.Executable
COMPLETED, NOT_READY, STOP_ITERATING
 
Constructor Summary
CTBaseIntegrator(CompositeEntity container, java.lang.String name)
          Construct an integrator, with a name and a container.
 
Method Summary
 void clearHistory()
          Clear the history information.
 void emitTentativeOutputs()
          Emit the tentative output, which is the tentative state of the integrator.
 void fire()
          Delegate to the integratorFire() of the current ODE solver.
 double[] getAuxVariables()
          Return the auxiliary variables in a double array.
 double getDerivative()
          Return the latest updated derivative of the state variable.
 double[] getHistory(int index)
          Return the history information of the last index-th step.
 int getHistoryCapacity()
          Return the history capacity.
 double getState()
          Return the state of the integrator.
 double getTentativeState()
          Return the tentative state.
 int getValidHistoryCount()
          Return the number of valid history entries.
 void goToMarkedState()
          Go to the marked state.
 void initialize()
          Initialize the integrator.
 boolean isThisStepAccurate()
          Return true if this integration step is accurate from this integrator's point of view.
 void markState()
          Mark and remember the current state.
 boolean postfire()
          Update the state and its derivative, and push them into history.
 double predictedStepSize()
          Return the predicted next step size.
 boolean prefire()
          Setup the integrator to operate with the current ODE solver.
 void pruneDependencies()
          Override the base class to declare that the output does not depend on the input in a firing.
 double refinedStepSize()
          Return the estimation of the refined next step size.
 void setAuxVariables(int index, double value)
          Set the value of an auxiliary variable.
 void setHistoryCapacity(int cap)
          Set history capacity.
 void setTentativeDerivative(double value)
          Set the tentative derivative, dx/dt.
 void setTentativeState(double value)
          Set the tentative state.
 
Methods inherited from class ptolemy.actor.TypedAtomicActor
_addPort, attributeTypeChanged, clone, newPort, typeConstraintList
 
Methods inherited from class ptolemy.actor.AtomicActor
_createReceivers, clone, connectionsChanged, getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, iterate, newReceiver, outputPortList, preinitialize, removeDependency, setContainer, stop, stopFire, terminate, wrapup
 
Methods inherited from class ptolemy.kernel.ComponentEntity
_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, propagateExistence, setName
 
Methods inherited from class ptolemy.kernel.Entity
_description, _exportMoMLContents, _removePort, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName, validateSettables
 
Methods inherited from class ptolemy.kernel.InstantiableNamedObj
_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, workspace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface ptolemy.actor.Actor
getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, newReceiver, outputPortList
 
Methods inherited from interface ptolemy.actor.Executable
iterate, preinitialize, stop, stopFire, terminate, wrapup
 
Methods inherited from interface ptolemy.kernel.util.Derivable
getDerivedLevel, getDerivedList, propagateValue
 
Methods inherited from interface ptolemy.kernel.util.Nameable
description, getFullName, getName, getName
 

Field Detail

input

public TypedIOPort input
The input port. This is a single port of type double.


output

public TypedIOPort output
The output port. This is a single port of type double.


initialState

public Parameter initialState
The initial state of type DoubleToken. The default value is 0.0


_history

protected CTBaseIntegrator.History _history
The history states and their derivative. This variable is needed by Linear Multistep (LMS) methods, like Trapezoidal rule and backward differential formula. This variable is protected so that derived classes may access it directly.

Constructor Detail

CTBaseIntegrator

public CTBaseIntegrator(CompositeEntity container,
                        java.lang.String name)
                 throws NameDuplicationException,
                        IllegalActionException
Construct an integrator, with a name and a container. The integrator is in the same workspace as the container.

Parameters:
container - The container.
name - The name
Throws:
NameDuplicationException - If the name is used by another actor in the container.
IllegalActionException - Not thrown in this base class.
Method Detail

clearHistory

public void clearHistory()
Clear the history information.


emitTentativeOutputs

public void emitTentativeOutputs()
                          throws IllegalActionException
Emit the tentative output, which is the tentative state of the integrator.

Specified by:
emitTentativeOutputs in interface CTDynamicActor
Throws:
IllegalActionException - If the data transfer is not completed.

fire

public void fire()
          throws IllegalActionException
Delegate to the integratorFire() of the current ODE solver. The existence of a director and an ODE solver is not checked here. If there's no director and ODE solver, a NullPointerException will be thrown.

Specified by:
fire in interface Executable
Overrides:
fire in class AtomicActor
Throws:
IllegalActionException - If thrown by integratorFire() of the solver.

getAuxVariables

public double[] getAuxVariables()
Return the auxiliary variables in a double array. The auxiliary variables are created in the prefire() method and may be set during each firing of the actor. Return null if the auxiliary variables have never been created.

Returns:
The auxiliary variables in a double array.

getDerivative

public final double getDerivative()
Return the latest updated derivative of the state variable.

Returns:
The derivative of the most recently resolved state.

getHistory

public double[] getHistory(int index)
Return the history information of the last index-th step. The index starts from 0. If the current time is t(n), then getHistory(0) gives the state and derivative of time t(n-1), and getHistory(1) corresponds to time t(n-2). The returned history array has length 2, where the first element is the history state, and the second element is the corresponding derivative. The history information is equidistant in time, and the distance is the current step size. If the step sizes are changed during the execution, the history information will be self-adjusted. If the index is less than 0 or grater than the history capacity, a runtime IndexOutOfBoundsException will be thrown.

Parameters:
index - The index.
Returns:
The history array at the index point.

getHistoryCapacity

public final int getHistoryCapacity()
Return the history capacity.

Returns:
The maximum capacity of the history information.

getState

public final double getState()
Return the state of the integrator. The returned state is the latest confirmed state. This is the same value as getHistory(0)[0], but more efficient.

Returns:
A double number as the state of the integrator.

getTentativeState

public double getTentativeState()
Return the tentative state.

Returns:
the tentative state.

getValidHistoryCount

public final int getValidHistoryCount()
Return the number of valid history entries. This number is always less than or equal to the history capacity.

Returns:
The number of valid history entries.

goToMarkedState

public void goToMarkedState()
Go to the marked state. After calling the markState() method, calling this method will bring the integrator back to the marked state. This method is used for rollbacking the execution to a previous time point.

Specified by:
goToMarkedState in interface CTStatefulActor

initialize

public void initialize()
                throws IllegalActionException
Initialize the integrator. Check for director and ODE solver. Update initial state parameter. Set the initial state to the tentative state and the state. Set tentative derivative to 0.0.

Specified by:
initialize in interface Executable
Overrides:
initialize in class AtomicActor
Throws:
IllegalActionException - If there's no director or the director has no ODE solver, or thrown by the integratorInitialize() of the solver.

isThisStepAccurate

public boolean isThisStepAccurate()
Return true if this integration step is accurate from this integrator's point of view. This method delegates to the integratorIsAccurate() method of the current ODE solver. Throw a NullPointerException, if there's no ODE solver. If the input is not available, or the input is a result of divide by zero, an InternalErrorException is thrown.

Specified by:
isThisStepAccurate in interface CTStepSizeControlActor
Returns:
True if the last integration step is accurate.

markState

public void markState()
Mark and remember the current state. This remembered state can be retrieved by the goToMarkedState() method. The marked state may be used for rolling back the execution to a previous time point.

Specified by:
markState in interface CTStatefulActor

postfire

public boolean postfire()
                 throws IllegalActionException
Update the state and its derivative, and push them into history.

Specified by:
postfire in interface Executable
Overrides:
postfire in class AtomicActor
Returns:
True always.
Throws:
IllegalActionException - Not thrown in this base class.

predictedStepSize

public double predictedStepSize()
Return the predicted next step size. This method delegates to the integratorPredictedStepSize() method of the current ODESolver. Throw a NullPointerException, if there's no ODE solver.

Specified by:
predictedStepSize in interface CTStepSizeControlActor
Returns:
The predicteded next step size.

prefire

public boolean prefire()
                throws IllegalActionException
Setup the integrator to operate with the current ODE solver. This method checks whether there are enough auxiliary variables in the integrator for the current ODE solver. If not, create more auxiliary variables. This method also adjusts the history information w.r.t. the current ODE solver and the current step size. The existence of director and ODE solver is not checked, since they are checked in the initialize() method.

Specified by:
prefire in interface Executable
Overrides:
prefire in class AtomicActor
Returns:
True always.
Throws:
IllegalActionException - If there's no director or the director has no ODE solver.

refinedStepSize

public double refinedStepSize()
Return the estimation of the refined next step size. If this integrator considers the current step to be accurate, then return the current step size, otherwise return half of the current step size.

Specified by:
refinedStepSize in interface CTStepSizeControlActor
Returns:
The refined step size.

setAuxVariables

public void setAuxVariables(int index,
                            double value)
                     throws InvalidStateException
Set the value of an auxiliary variable. If the index is out of the bound of the auxiliary variable array, an InvalidStateException is thrown to indicate an inconsistency in the ODE solver.

Parameters:
index - The index in the auxVariables array.
value - The value to be set.
Throws:
InvalidStateException - If the index is out of the range of the auxiliary variable array.

pruneDependencies

public void pruneDependencies()
Override the base class to declare that the output does not depend on the input in a firing.

Overrides:
pruneDependencies in class AtomicActor
See Also:
TimedDelay, AtomicActor.removeDependency(IOPort, IOPort), FunctionDependencyOfAtomicActor

setHistoryCapacity

public final void setHistoryCapacity(int cap)
Set history capacity. This will typically be set by the ODE solvers that uses the history. If the argument is less than 0, the capacity is set to 0.

Parameters:
cap - The capacity.

setTentativeDerivative

public final void setTentativeDerivative(double value)
Set the tentative derivative, dx/dt. Tentative derivative is the derivative of the state that the ODE solver resolved in one step. This may not be the final derivative due to error control or event detection.

Parameters:
value - The value to be set.

setTentativeState

public final void setTentativeState(double value)
Set the tentative state. Tentative state is the state that the ODE solver resolved in one step. It may not be the final state due to error control or event detection.

Parameters:
value - The value to be set.