ptolemy.actor.lib

Class NonStrictTest

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.InstantiableNamedObj

ptolemy.kernel.Entity<T>

ptolemy.kernel.ComponentEntity<T>

ptolemy.actor.AtomicActor<TypedIOPort>

ptolemy.actor.TypedAtomicActor

ptolemy.actor.lib.Sink

ptolemy.actor.lib.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)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	_firedOnce Set to true if fire() is called once.
protected boolean	_initialized Set to true when initialized() is called.
protected int	_iteration Count of iterations.
protected boolean[]	_matchedValues An array of booleans where if an element is true, then the corresponding element in correctValues has been seen.
protected int	_numberOfInputTokensSeen Number of input tokens seen by this actor in the fire method.
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.
protected java.util.List	_trainingTokens List to store tokens for training mode.
Parameter	correctValues A matrix specifying what the input should be.
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.
Parameter	requireOrderedValues If true, then require that inputs appear in the order recorded in the correctValues parameter.
Parameter	tolerance A double specifying how close the input has to be to the value given by correctValues.
static 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.
SharedParameter	trainingMode If true, then do not check inputs, but rather collect them into the correctValues array.

Fields inherited from class ptolemy.actor.lib.Sink

input

Fields inherited from class ptolemy.actor.TypedAtomicActor

_typesValid

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

Constructors

Constructor and Description
NonStrictTest(CompositeEntity container, java.lang.String name) Construct an actor with an input multiport.

Method Summary

Modifier and Type	Method and Description
protected void	_checkRangeOfTolerance(Token newValue) Check that the difference in exponents between the input and the tolerance is not greater than the precision of a Double.
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.
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.
protected static boolean	_isCloseToIfNilArrayElement(Token token1, Token token2, double epsilon) 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.
protected static boolean	_isCloseToIfNilRecordElement(Token token1, Token token2, double epsilon) 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.
void	attributeChanged(Attribute attribute) If the attribute being changed is tolerance, then check that it is increasing and nonnegative.
java.lang.Object	clone(Workspace workspace) Override the base class to set type constraints.
void	fire() Call super.fire() and set _firedOnce to true.
void	initialize() Override the base class to set the iteration counter to zero.
boolean	postfire() Read one token from each input channel and compare against the value specified in correctValues.
void	wrapup() If trainingMode is true, then take the collected training tokens and store them as an array in correctValues.

Methods inherited from class ptolemy.actor.TypedAtomicActor

_containedTypeConstraints, _defaultTypeConstraints, _fireAt, _fireAt, attributeTypeChanged, clone, isBackwardTypeInferenceEnabled, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, _declareDelayDependency, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, prefire, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_addPort, _description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

isFireFunctional, isStrict, iterate, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, preinitialize, removeInitializable

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

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.

Constructor Detail

NonStrictTest

public NonStrictTest(CompositeEntity container,
                     java.lang.String name)
              throws NameDuplicationException,
                     IllegalActionException

Construct an actor with an input multiport.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If the entity cannot be contained by the proposed container.

NameDuplicationException - If the container already has an actor with this name.

Method Detail

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Override the base class to set type constraints.

Overrides:

clone in class TypedAtomicActor

Parameters:

workspace - The workspace for the new object.

Returns:

A new instance of ArrayAverage.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

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.

fire

public void fire()
          throws IllegalActionException

Call super.fire() and set _firedOnce to true. Derived classes should either call this fire() method or else set _firedOnce to true.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor<TypedIOPort>

Throws:

IllegalActionException - If thrown by the baseclass.

See Also:

_firedOnce

initialize

public void initialize()
                throws IllegalActionException

Override the base class to set the iteration counter to zero.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor<TypedIOPort>

Throws:

IllegalActionException - If the base class throws it or if we are running under the test suite and the trainingMode parameter is set to true.

See Also:

MessageHandler.isNonInteractive()

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.