Package ptolemy.domains.continuous.kernel

Class ContinuousIntegrator

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, ContinuousStatefulComponent, ContinuousStepSizeController, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    Integrator
    public class ContinuousIntegrator
extends TypedAtomicActor
implements ContinuousStatefulComponent, ContinuousStepSizeController
    The integrator in the continuous domain.

    The derivative port receives the derivative of the state of the integrator with respect to time. The state output port shows the state of the integrator. So an ordinary differential equation (ODE), dx/dt = f(x, t), can be built as follows:

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

    An integrator also has a port-parameter called initialState. The parameter provides the initial state for integration during the initialization stage of execution. If during execution an input token is provided on the port, then the state of the integrator will be reset at that time to the value of the token. The default value of the parameter is 0.0.

    An integrator also has an input port named impulse. When present, a token at the impulse input port is interpreted as the weight of a Dirac delta function. It causes an increment or decrement to the state at the time of the arrival of the value. If both impulse and initialState have data on the same microstep, then initialState dominates.

    Note that both impulse and reset expect to receive discrete inputs. To preserve continuity, this means that those inputs should be present only when the solver step size is zero. If this assumption is violated, then this actor will throw an exception.

    An integrator can generate an output (its current state) before the derivative input is known, and hence can be used in feedback loops like that above without creating a causality loop. Since impulse and initialState inputs affect the output immediately, using them in feedback loops may require inclusion of a TimeDelay actor.

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

    An integrator can possibly have several auxiliary variables for the ODE solvers to use. 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.

    This class is based on the CTBaseIntegrator by Jie Liu and Haiyang Zheng, but it has more ports and provides more functionality.

    Since:
    Ptolemy II 6.0
    Version:
    $Id$
    Author:
    Haiyang Zheng and Edward A. Lee
    Pt.AcceptedRating:
    Red (yuhong)
    Pt.ProposedRating:
    Yellow (hyzheng)

    • Field Detail

      • impulse

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

      • derivative

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

      • state

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

      • initialState

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

    • Method Detail

      • clone

        public java.lang.Object clone​(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
        Clone this actor into the specified workspace. The new actor is not added to the directory of that workspace (you must do this yourself if you want it there). The result is a new actor with the same ports as the original, but no connections and no container. A container must be set before much can be done with this actor.
        Overrides:
        clone in class TypedAtomicActor
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        A new ComponentEntity.
        Throws:
        java.lang.CloneNotSupportedException - If cloned ports cannot have as their container the cloned entity (this should not occur), or if one of the attributes cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • fire

        public void fire()
          throws IllegalActionException
        If the value at the derivative port is known, and the current step size is bigger than 0, perform an integration. If the impulse port is known and has data, then add the value provided to the state; if the initialState port is known and has data, then reset the state to the provided value. If both impulse and initialState have data, then initialState dominates. If either is unknown, then simply return, leaving the output unknown. Note that the signals provided at these two ports are required to be purely discrete. This is enforced by throwing an exception if the current microstep is zero when they have input data.
        Specified by:
        fire in interface Executable
        Overrides:
        fire in class AtomicActor<TypedIOPort>
        Throws:
        IllegalActionException - If the input is infinite or not a number, or if thrown by the solver, or if data is present at either impulse or initialState and the step size is greater than zero.

      • 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.
        See Also:
        setAuxVariables(int, double)

      • getCausalityInterface

        public CausalityInterface getCausalityInterface()
        Return a causality interface for this actor. This causality interface expresses dependencies that are instances of BooleanDependency that declare that the state output port does not depend on any of the input ports at this microstep. Moreover, the initialState and impulse ports are equivalent (to process inputs at either, you need to know about inputs at the other). You do not need to know about inputs at derivative.
        Specified by:
        getCausalityInterface in interface Actor
        Overrides:
        getCausalityInterface in class AtomicActor<TypedIOPort>
        Returns:
        A representation of the dependencies between input ports and output ports.

      • getState

        public final double getState()
        Return the state of the integrator. The returned state is the latest confirmed state.
        Returns:
        The state of the integrator.

      • getTentativeState

        public double getTentativeState()
        Return the tentative state.
        Returns:
        The tentative state.
        See Also:
        setTentativeState(double)

      • initialize

        public void initialize()
                throws IllegalActionException
        Initialize the integrator. Check for the existence of a director and an ODE solver. Set the state to the value given by initialState.
        Specified by:
        initialize in interface Initializable
        Overrides:
        initialize in class AtomicActor<TypedIOPort>
        Throws:
        IllegalActionException - If there is no director, or the director has no ODE solver, or the initialState parameter does not contain a valid token, or the superclass throws it.

      • isStepSizeAccurate

        public boolean isStepSizeAccurate()
        Return true if the state is resolved successfully. If the input is not available, or the input is a result of divide by zero, a NumericalNonconvergeException is thrown.
        Specified by:
        isStepSizeAccurate in interface ContinuousStepSizeController
        Returns:
        True if the state is resolved successfully.

      • isStrict

        public boolean isStrict()
        Return false. This actor can produce some outputs even the derivative input is unknown. This actor is crucial at breaking feedback loops during simulation. The impulse and initialState ports, have to be known for prefire to return true (if they are connected).
        Specified by:
        isStrict in interface Executable
        Overrides:
        isStrict in class AtomicActor<TypedIOPort>
        Returns:
        False.

      • suggestedStepSize

        public double suggestedStepSize()
        Return the suggested next step size. This method delegates to the integratorPredictedStepSize() method of the current ODESolver.
        Specified by:
        suggestedStepSize in interface ContinuousStepSizeController
        Returns:
        The suggested next step size.

      • 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 ContinuousStepSizeController
        Returns:
        The refined step size.

      • setAuxVariables

        public void setAuxVariables​(int index,
                            double value)
                     throws InvalidStateException
        Set the value of an auxiliary variable. The index indicates which auxiliary variable in the auxVariables array. 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.
        See Also:
        getAuxVariables()

      • setTentativeState

        public final void setTentativeState​(double value)
        Set the tentative state. Tentative state is the state that the ODE solver resolved in one step. This may not be the final state due to error control or event detection.
        Parameters:
        value - The value to be set.
        See Also:
        getTentativeState()