ptolemy.actor.lib
Class NonStrictTest

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.actor.lib.Sink
                              ptolemy.actor.lib.NonStrictTest

All Implemented Interfaces:

java.io.Serializable, 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.

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. The input data type is undeclared, so it can resolve to anything.

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: NonStrictTest.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Paul Whitaker, Christopher Hylands, Edward A. Lee

See Also:

Test, Serialized Form

Accepted Rating:

Yellow (cxh)

Proposed Rating:

Yellow (cxh)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

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 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	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.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _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

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

Method Summary

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.
static boolean	isRunningNightlyBuild() If the trainingMode parameter is true and the model is being run as part of the test suite, then return true.
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

_addPort, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, 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

_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, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, 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, propagateValue, propagateValues, removeChangeListener, removeDebugListener, 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.

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.

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

_numberOfInputTokensSeen

protected int _numberOfInputTokensSeen

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

_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.

_iteration

protected int _iteration

Count of iterations.

_trainingTokens

protected java.util.List _trainingTokens

List to store tokens for training mode.

_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.

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 AtomicActor

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

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

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:

isRunningNightlyBuild()

isRunningNightlyBuild

public static boolean isRunningNightlyBuild()

If the trainingMode parameter is true and the model is being run as part of the test suite, then return true. This method merely checks to see if "ptolemy.ptII.isRunningNightlyBuild" property exists and is not empty. To run the test suite in the Nightly Build mode, use

  make nightly
  

Returns:

True if the nightly build is running.

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

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

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.

_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.