ptolemy.domains.continuous.lib
Class LevelCrossingDetector

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.domains.continuous.lib.LevelCrossingDetector

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, ContinuousStepSizeController, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class LevelCrossingDetector
extends TypedAtomicActor
implements ContinuousStepSizeController

An event detector that converts continuous signals to discrete events when the input trigger signal crosses a threshold specified by the level parameter. The direction parameter can constrain the actor to detect only rising or falling transitions. It has three possible values, "rising", "falling", and "both", where "both" is the default. This actor will produce an output whether the input is continuous or not. That is, if a discontinuity crosses the threshold in the right direction, it produces an output at the time of the discontinuity. If the input is continuous, then the output is produced when the input is within errorTolerance of the level. The value of the output is given by the value parameter, which by default has the value of the level parameter.

This actor will not produce an event on its very first firing. If you need an output at time zero, then you need generate a level crossing discontinuity at time zero.

This actor will also not produce an event if the current microstep is 0. In that case, the output is postponed by one microstep. This ensures that the output signal, which is discrete, satisfies the piecewise continuity constraint, and is absent at microstep 0.

Since:

Ptolemy II 6.0

Version:

$Id: LevelCrossingDetector.java 57046 2010-01-27 23:35:53Z cxh $

Author:

Edward A. Lee, Haiyang Zheng

See Also:

Serialized Form

Accepted Rating:

Red (hyzheng)

Proposed Rating:

Yellow (hyzheng)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

private boolean	_detectFallingCrossing
private boolean	_detectRisingCrossing
private double	_errorTolerance
private boolean	_eventMissed
private double	_lastTrigger
protected double	_level The level threshold this actor detects.
private Time	_postponed
private boolean	_postponedOutputProduced
private double	_thisTrigger
StringParameter	direction A parameter that can be used to limit the detected level crossings to rising or falling.
Parameter	errorTolerance The error tolerance specifying how close the value of a continuous input needs to be to the specified level to produce the output event.
Parameter	level The parameter that specifies the level threshold.
TypedIOPort	output The output port.
TypedIOPort	trigger The trigger port.
Parameter	value The output value to produce when a level-crossing is detected.

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

LevelCrossingDetector(CompositeEntity container, java.lang.String name)
Construct an actor in the specified container with the specified name.

Method Summary

void	attributeChanged(Attribute attribute) Update the attribute if it has been changed.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() Produce an output event if the current input compared to the input on the last iteration indicates that a level crossing in the appropriate direction has occurred, if the time is within errorTolerance of the time at which the crossing occurs.
void	initialize() Initialize the execution.
boolean	isStepSizeAccurate() Return false if with the current step size we miss a level crossing.
boolean	postfire() Prepare for the next iteration, by making the current trigger token to be the history trigger token.
void	preinitialize() Make sure the actor runs with a ContinuousDirector.
double	refinedStepSize() Return the refined step size if there is a missed event, otherwise return the current step size.
double	suggestedStepSize() Return the maximum Double value.

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, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate, wrapup

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, removeInitializable, wrapup

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

direction

public StringParameter direction

A parameter that can be used to limit the detected level crossings to rising or falling. There are three choices: "falling", "rising", and "both". The default value is "both".

errorTolerance

public Parameter errorTolerance

The error tolerance specifying how close the value of a continuous input needs to be to the specified level to produce the output event. Note that this indirectly affects the accuracy of the time of the output since the output can be produced at any time after the level crossing occurs while it is still within the specified error tolerance of the level. This is a double with default 1e-4.

level

public Parameter level

The parameter that specifies the level threshold. By default, it contains a double with value 0.0. Note, a change of this parameter at run time will not be applied until the next iteration.

value

public Parameter value

The output value to produce when a level-crossing is detected. This can be any data type. It defaults to the same value as the level parameter.

output

public TypedIOPort output

The output port. The type is at least the type of the value parameter.

trigger

public TypedIOPort trigger

The trigger port. This is an input port with type double.

_level

protected double _level

The level threshold this actor detects.

_detectRisingCrossing

private boolean _detectRisingCrossing

_detectFallingCrossing

private boolean _detectFallingCrossing

_errorTolerance

private double _errorTolerance

_eventMissed

private boolean _eventMissed

_lastTrigger

private double _lastTrigger

_postponed

private Time _postponed

_postponedOutputProduced

private boolean _postponedOutputProduced

_thisTrigger

private double _thisTrigger

Constructor Detail

LevelCrossingDetector

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

Construct an actor in the specified container with the specified name. The name must be unique within the container or an exception is thrown. The container argument must not be null, or a NullPointerException will be thrown.

Parameters:

container - The subsystem that this actor is lived in

name - The actor's name

Throws:

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

NameDuplicationException - If name coincides with an entity already in the container.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Update the attribute if it has been changed. If the attribute is errorTolerance or level, then update the local cache.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that has changed.

Throws:

IllegalActionException - If the attribute change failed.

clone

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

Clone the actor into the specified workspace.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the new object.

Returns:

A new actor.

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)

fire

public void fire()
          throws IllegalActionException

Produce an output event if the current input compared to the input on the last iteration indicates that a level crossing in the appropriate direction has occurred, if the time is within errorTolerance of the time at which the crossing occurs.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If can not get token from the trigger port or can not send token through the output port.

initialize

public void initialize()
                throws IllegalActionException

Initialize the execution.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If thrown by the super class.

isStepSizeAccurate

public boolean isStepSizeAccurate()

Return false if with the current step size we miss a level crossing.

Specified by:

isStepSizeAccurate in interface ContinuousStepSizeController

Returns:

False if the step size needs to be refined.

postfire

public boolean postfire()
                 throws IllegalActionException

Prepare for the next iteration, by making the current trigger token to be the history trigger token.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True always.

Throws:

IllegalActionException - If thrown by the super class.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Make sure the actor runs with a ContinuousDirector.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AtomicActor

Throws:

IllegalActionException - If the director is not a ContinuousDirector or the parent class throws it.

refinedStepSize

public double refinedStepSize()

Return the refined step size if there is a missed event, otherwise return the current step size.

Specified by:

refinedStepSize in interface ContinuousStepSizeController

Returns:

The refined step size.

suggestedStepSize

public double suggestedStepSize()

Return the maximum Double value. This actor does not suggest or constrain the step size for the next iteration.

Specified by:

suggestedStepSize in interface ContinuousStepSizeController

Returns:

java.Double.MAX_VALUE.