001/* Interface for actors that control integration step sizes.
002
003 Copyright (c) 1998-2013 The Regents of the University of California.
004 All rights reserved.
005 Permission is hereby granted, without written agreement and without
006 license or royalty fees, to use, copy, modify, and distribute this
007 software and its documentation for any purpose, provided that the above
008 copyright notice and the following two paragraphs appear in all copies
009 of this software.
010
011 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
012 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024 PT_COPYRIGHT_VERSION_2
025 COPYRIGHTENDKEY
026
027 */
028package ptolemy.actor.continuous;
029
030import ptolemy.actor.util.Time;
031import ptolemy.kernel.util.IllegalActionException;
032
033///////////////////////////////////////////////////////////////////
034//// Advanceable
035
036/**
037 Interface for actors and directors that, unlike native Ptolemy II actors, do not
038 proactively notify their director (using fireAt()) of events in the
039 future that they might produce, but which may, nevertheless, require
040 execution at some future time. An example of such actors are
041 functional mockup units (FMUs) conforming with the functional mockup
042 interface (FMI) standard version 2.0 or earlier.
043 <p>
044 A director that advances time and supports such actors should advance
045 time for actors that implement this interface before deciding on the
046 time advance for other actors.  That is, as part of choosing the step
047 size by which to advance time, it should invoke the {@link #advance(Time, int)}
048 method of this interface with its proposed time advance. If any such actor
049 returns false, then it should query the actor using the methods of the
050 base interface to refine the time step.
051 <p>
052 Note that this mechanism is much weaker than the native Ptolemy II
053 method using fireAt().  In particular, this method is advancing time
054 into the future <i>without providing inputs into the future</i>. That is,
055 the actor is expected to advance time without any knowledge of its inputs
056 during the proposed time interval. The actor has to make some assumptions
057 about the inputs during that interval, and those assumptions may be later
058 contradicted by the actual inputs provided by the environment.
059 If such a contradiction occurs, then the actor may need to roll back
060 to a previously stored state and redo some portion of the time step.
061 As of version 2.0, the FMI standard does not require actors to implement
062 such rollback.
063 <p>
064 Of the existing Ptolemy II directors, the only one that requires rollback in time
065 is the ContinuousDirector. Moreover, in Ptolemy II, rollback is implementable
066 by every actor that realizes the strict actor semantics, where the fire()
067 method does not change the state of the actor (state changes in postfire()).
068 However, actors that implement this interface may require rollback under
069 <i>any director that advances time</i>.
070 <p>
071 As a consequence, there is no Ptolemy II director that can guarantee correct
072 execution of arbitrary combinations of FMUs, unless the FMUs implement rollback.
073 In particular, consider a model contains more than one actor that implements
074 this interface. Suppose it has two. Then it has to advance time of one
075 before the other.  Suppose it advances time of the first by 1.0 time unit,
076 and the advance succeeds.  Then, suppose it tries to advance the other by
077 1.0 time unit, and the advance fails. Suppose that second actor suggests
078 a time advance of 0.5 time units, and at time <i>t</i> + 0.5, where <i>t</i>
079 is current time, it produces an output that is an input to the other
080 actor.  The other actor will now have an input that it could not possibly
081 have assumed when it advanced its time to <i>t</i> + 1.0, so it will have
082 to roll back to time <i>t</i> + 0.5.  If it is not capable of rollback,
083 then there is no assurance that its execution is correct.
084
085 @author Edward A. Lee
086 @version $Id$
087 @since Ptolemy II 10.0
088 @Pt.ProposedRating Green (hyzheng)
089 @Pt.AcceptedRating Green (eal)
090 */
091public interface Advanceable extends ContinuousStepSizeController {
092
093    ///////////////////////////////////////////////////////////////////
094    ////                         public methods                    ////
095
096    /** Advance to the specified time.
097     *  @param time The time to advance.
098     *  @param microstep The microstep to advance.
099     *  @return True if advancement to the specified time succeeds.
100     *  @exception IllegalActionException If an error occurs advancing time.
101     */
102    public boolean advance(Time time, int microstep)
103            throws IllegalActionException;
104}