ptolemy.domains.continuous.lib

Class LevelCrossingDetector

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.domains.continuous.lib.LevelCrossingDetector

All Implemented Interfaces:

java.lang.Cloneable, Actor, ContinuousStepSizeController, Executable, FiringsRecordable, Initializable, TypedActor, 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 generated 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 has a one microstep delay before it will produce an output. That is, when a level crossing is detected, the actor requests a refiring in the next microstep at the current time, and only in that refiring produces the output. This ensures that the output satisfies the piecewise continuity constraint. It is always absent at microstep 0.

This actor will not produce an event at the time of the first firing unless there is a level crossing discontinuity at that time.

Since:

Ptolemy II 6.0

Version:

$Id$

Author:

Edward A. Lee, Haiyang Zheng

Pt.AcceptedRating:

Red (hyzheng)

Pt.ProposedRating:

Yellow (hyzheng)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
protected double	_level The level threshold this actor detects.
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.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
LevelCrossingDetector(CompositeEntity container, java.lang.String name) Construct an actor in the specified container with the specified name.

Method Summary

Modifier and Type	Method and Description
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	declareDelayDependency() Declare that the output does not depend on the input in a firing.
void	fire() Detect whether 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	isStrict() Return false.
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

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

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, _declareDelayDependency, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, 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

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

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 TypedAtomicActor

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)

declareDelayDependency

public void declareDelayDependency()
                            throws IllegalActionException

Declare that the output does not depend on the input in a firing.

Overrides:

declareDelayDependency in class AtomicActor<TypedIOPort>

Throws:

IllegalActionException - If the causality interface cannot be computed.

See Also:

AtomicActor.getCausalityInterface()

fire

public void fire()
          throws IllegalActionException

Detect whether 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. If there is such a level crossing, then postfire will request a refiring at the current time, and the next invocation of fire() will produce the output event.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor<TypedIOPort>

Throws:

IllegalActionException - If it cannot get a token from the trigger port or cannot send a 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<TypedIOPort>

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.

isStrict

public boolean isStrict()

Return false. This actor can produce some outputs even the inputs are unknown. This actor is usable for breaking feedback loops.

Specified by:

isStrict in interface Executable

Overrides:

isStrict in class AtomicActor<TypedIOPort>

Returns:

False.

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<TypedIOPort>

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<TypedIOPort>

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.