Package ptolemy.actor.lib

Class NonStrictTest

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    Test
    public class NonStrictTest
extends Sink

    This actor compares the inputs against the value specified by the correctValues parameter. That parameter is an ArrayToken, where each element of the array is of the same type as the input. On each firing where the input is present, the value of the input is compared against the next token in the correctValues parameter. If it matches, the firing succeeds. If it doesn't match, then an exception is thrown. After matching each of the value in the correctValues parameter, subsequent iterations always succeed, so the actor can be used as a "power-up" test for a model, checking the first few iterations against some known results.

    Unlike the Test actor, NonStrictTest does not support a multiport input, only single port inputs are supported. This also differs from Test in that it ignores absent inputs, and it checks the inputs in the postfire() method rather than the fire() method.

    This actor accepts any type of data on its input port, therefore it doesn't declare a type, but lets the type resolution algorithm find the least fixed point. If backward type inference is enabled, and no input type has been declared, the input is constrained to be equal to BaseType.GENERAL. This will result in upstream ports resolving to the most general type rather than the most specific.

    If the input is a DoubleToken or ComplexToken, then the comparison passes if the value is close to what it should be, within the specified tolerance (which defaults to 10-9). During training, if a correct value is greater than 10 orders of magnitude than the tolerance, then the tolerance is changed to a value 9 orders of magnitude less than the correct value. This helps avoid comparisons beyond the precision of a Java double.

    If the parameter trainingMode is true, then instead of performing the test, this actor collects the inputs into the correctValues parameter. Thus, to use this actor, you can place it in a model, set trainingMode to true to collect the reference data, then set trainingMode to false. Any subsequent run of the actor will throw an exception if the input data does not match the training data. The value of the reference token is set in the wrapup() method. The trainingMode parameter is a shared parameter, meaning that if you change it for any one instance of this actor in the model, then it will be changed for all instances.

    Since:
    Ptolemy II 2.0
    Version:
    $Id$
    Author:
    Paul Whitaker, Christopher Hylands, Edward A. Lee
    See Also:
    Test
    Pt.AcceptedRating:
    Yellow (cxh)
    Pt.ProposedRating:
    Yellow (cxh)

    • Field Detail

      • correctValues

        public Parameter correctValues
        A matrix specifying what the input should be. This defaults to a one-by-one array containing a boolean true.

      • tolerance

        public Parameter tolerance
        A double specifying how close the input has to be to the value given by correctValues. This is a DoubleToken, with default value 10-9. During training, if a correct value is greater than 10 orders of magnitude than the tolerance, then the tolerance is changed to a value 9 orders of magnitude less than the correct value. This helps avoid comparisons beyond the precision of a Java double.

      • requireAllCorrectValues

        public Parameter requireAllCorrectValues
        If true, and the number of tokens seen in wrapup() is not equal to or greater than the number of elements in the correctValues array, then throw an exception. The default value is true. This parameter is a shared parameter, meaning that changing it for any one instance in a model will change it for all instances in the model.

      • requireOrderedValues

        public Parameter requireOrderedValues
        If true, then require that inputs appear in the order recorded in the correctValues parameter. If false, then the inputs can appear in any order. The default value is true.

      • trainingMode

        public SharedParameter trainingMode
        If true, then do not check inputs, but rather collect them into the correctValues array. This parameter is a boolean, and it defaults to false. It is a shared parameter, meaning that changing it for any one instance in a model will change it for all instances in the model.

      • TRAINING_MODE_ERROR_MESSAGE

        public static final java.lang.String TRAINING_MODE_ERROR_MESSAGE
        Exception message that is used if we are running under the nightly build and the trainingMode parameter is true.
        See Also:
        Constant Field Values

      • _firedOnce

        protected boolean _firedOnce
        Set to true if fire() is called once. If fire() is not called at least once, then throw an exception in wrapup().

      • _initialized

        protected boolean _initialized
        Set to true when initialized() is called.

      • _iteration

        protected int _iteration
        Count of iterations.

      • _numberOfInputTokensSeen

        protected int _numberOfInputTokensSeen
        Number of input tokens seen by this actor in the fire method.

      • _matchedValues

        protected boolean[] _matchedValues
        An array of booleans where if an element is true, then the corresponding element in correctValues has been seen. This field is only used if the requireCorrectOrder parameter is false.

      • _tolerance

        protected double _tolerance
        A double that is read from the tolerance parameter specifying how close the input has to be to the value given by correctValues. This is a double, with default value 10-9.

      • _trainingTokens

        protected java.util.List _trainingTokens
        List to store tokens for training mode.

    • Method Detail

      • attributeChanged

        public void attributeChanged​(Attribute attribute)
                      throws IllegalActionException
        If the attribute being changed is tolerance, then check that it is increasing and nonnegative.
        Overrides:
        attributeChanged in class NamedObj
        Parameters:
        attribute - The attribute that changed.
        Throws:
        IllegalActionException - If the indexes vector is not increasing and nonnegative, or the indexes is not a row vector.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        Read one token from each input channel and compare against the value specified in correctValues. If the token count is larger than the length of correctValues, then return immediately, indicating that the inputs correctly matched the values in correctValues and that the test succeeded.
        Specified by:
        postfire in interface Executable
        Overrides:
        postfire in class AtomicActor<TypedIOPort>
        Returns:
        True if execution can continue into the next iteration.
        Throws:
        IllegalActionException - If an input does not match the required value or if the width of the input is not 1.

      • wrapup

        public void wrapup()
            throws IllegalActionException
        If trainingMode is true, then take the collected training tokens and store them as an array in correctValues.
        Specified by:
        wrapup in interface Initializable
        Overrides:
        wrapup in class AtomicActor<TypedIOPort>
        Throws:
        IllegalActionException - If initialized() was called and fire() was not called or if the number of inputs tokens seen is not greater than or equal to the number of elements in the correctValues array.

      • _checkRangeOfTolerance

        protected void _checkRangeOfTolerance​(Token newValue)
                               throws IllegalActionException
        Check that the difference in exponents between the input and the tolerance is not greater than the precision of a Double. If the exponent of newValue parameter is different by from the exponent of the tolerance parameter by more than 10, then adjust the tolerance parameter. This is useful for training large modesl that have many PublisherTests.
        Parameters:
        newValue - The token to be tested. DoubleTokens are tested, other tokens are ignored.
        Throws:
        IllegalActionException - If thrown while reading the tolerance parameter.

      • _customTypeConstraints

        protected java.util.Set<Inequality> _customTypeConstraints()
        Set the input port to be greater than or equal to BaseType.GENERAL in case backward type inference is enabled and the input port has no type declared.
        Overrides:
        _customTypeConstraints in class TypedAtomicActor
        Returns:
        A set of inequalities.

      • _isClose

        protected static boolean _isClose​(Token token1,
                                  Token token2,
                                  double epsilon)
        Test whether the value of the first token is close to the the value of the second token. Arrays and Records are handled specially, see _isCloseToIfNilArrayElement(Token, Token, double) and _isCloseToIfNilRecordElement(Token, Token, double). If the tokens do not support this comparison, then return false.
        Parameters:
        token1 - The first array token to compare.
        token2 - The second array token to compare.
        epsilon - The value that we use to determine whether two tokens are close.
        Returns:
        True if the first argument is close to this token. False

      • _isCloseToIfNilArrayElement

        protected static boolean _isCloseToIfNilArrayElement​(Token token1,
                                                     Token token2,
                                                     double epsilon)
                                              throws IllegalActionException
        Test whether the value of this token is close to the first argument, where "close" means that the distance between them is less than or equal to the second argument. This method only makes sense for tokens where the distance between them is reasonably represented as a double. It is assumed that the argument is an ArrayToken, and the isCloseTo() method of the array elements is used. This method differs from ArrayToken._isCloseTo(Token, double) in that if corresponding elements are both nil tokens, then those two elements are considered "close", see Token.NIL.
        Parameters:
        token1 - The first array token to compare.
        token2 - The second array token to compare.
        epsilon - The value that we use to determine whether two tokens are close.
        Returns:
        True if the first argument is close to this token. False if the arguments are not ArrayTokens
        Throws:
        IllegalActionException - If the elements do not support this comparison.

      • _isCloseToIfNilRecordElement

        protected static boolean _isCloseToIfNilRecordElement​(Token token1,
                                                      Token token2,
                                                      double epsilon)
                                               throws IllegalActionException
        Test whether the value of this token is close to the first argument, where "close" means that the distance between them is less than or equal to the second argument. This method only makes sense for tokens where the distance between them is reasonably represented as a double. It is assumed that the argument is a Record, and the isCloseTo() method of the record elements is used. This method differs from RecordToken._isCloseTo(Token, double) in that if corresponding elements are both nil tokens, then those two elements are considered "close", see Token.NIL.
        Parameters:
        token1 - The first array token to compare.
        token2 - The second array token to compare.
        epsilon - The value that we use to determine whether two tokens are close.
        Returns:
        True if the first argument is close to this token. False if the arguments are not ArrayTokens
        Throws:
        IllegalActionException - If the elements do not support this comparison.