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.kernel.util.IllegalActionException;
031
032///////////////////////////////////////////////////////////////////
033//// ContinuousStepSizeController
034
035/**
036 Interface for actors and directors that control integration step sizes.
037 This interface should be implemented by components that discover
038 breakpoints during an integration step (such as level-crossing
039 detectors) and by integrators.
040 <P>
041 Actors can affect the integration step size in two ways. The first one
042 is by introducing predictable breakpoints. To request a breakpoint
043 at time <i>t</i>, an actor can call the fireAt()
044 method of ContinuousDirector with a time argument <i>t</i>,
045 the director will treat <i>t</i> as a breakpoint. Actors that only
046 introduce predictable breakpoints need not implement this interface.
047 The director guarantees that no step size will be use that is large
048 enough to step over <i>t</i>.
049 <P>
050 The second way of controlling step size is through checking the accuracy
051 after each integration step. We treat an integration step as accurate if
052 the numerical integration error is less than the error tolerance and
053 there are no (unpredicted) breakpoints within this step.
054 Actors that use this mechanism need to implement this interface.
055 At the end of each integration step, each actor that implements this
056 interface will be asked whether this step is accurate by calling its
057 isStepSizeAccurate() method. If this method returns false, then all
058 actors that implement this interface will be asked to suggest a
059 refined step size (by calling refinedStepSize()). The integration step
060 will be repeated with the smallest of these suggestions.
061 <p>
062 If all actors that implement this interface find the integration
063 step accurate, then they will be asked for a suggested next step size
064 (by calling suggestedStepSize()).
065 The smallest of these suggested step sizes will be used for the next
066 integration step.
067 <P>
068 If there are no step size control actors in a model, the step size
069 is controlled by the director.  Most (or possibly all) CT directors
070 will leave the default step size at its initial value and only deviate
071 from these steps when there is a predictable breakpoint that does not
072 coincide with one of these steps.
073
074 @author  Jie Liu, Haiyang Zheng, Edward A. Lee
075 @version $Id$
076 @since Ptolemy II 10.0
077 @Pt.ProposedRating Green (hyzheng)
078 @Pt.AcceptedRating Green (eal)
079 */
080public interface ContinuousStepSizeController {
081
082    ///////////////////////////////////////////////////////////////////
083    ////                         public methods                    ////
084
085    /** Implementations of this method should return
086     *  true if the current integration step size
087     *  is sufficiently small for this actor to give accurate
088     *  results.
089     *  @return True if the current step is accurate.
090     */
091    public boolean isStepSizeAccurate();
092
093    /** Implementations of this method should return
094     *  the suggested next step size. If the current integration
095     *  step is accurate, each actor will be asked for its suggestion
096     *  for the next step size. If the actor that implements this interface
097     *  does not care what the next step size is, it should
098     *  return java.lang.Double.MAX_VALUE.
099     *  @return The suggested next step size.
100     *  @exception IllegalActionException If an actor suggests an illegal step size.
101     */
102    public double suggestedStepSize() throws IllegalActionException;
103
104    /** Implementations of this method should return
105     *  the suggested refined step size for restarting the current integration.
106     *  If any actor returns false when isStepSizeAccurate() is called,
107     *  then this method will be called on all actors that implement this
108     *  interface. The minimum of their returned value will be the new step size.
109     *  If the actor does not need a smaller step size, then
110     *  this method should return the current step size.
111     *  @return The suggested refined step size.
112     *  @exception IllegalActionException If the step size cannot be further refined.
113     */
114    public double refinedStepSize() throws IllegalActionException;
115}