ptolemy.domains.sdf.lib
Class LMSAdaptive

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.domains.sdf.lib.SDFTransformer
                              ptolemy.domains.sdf.lib.FIR
                                  ptolemy.domains.sdf.lib.LMSAdaptive

All Implemented Interfaces:

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

public class LMSAdaptive
extends FIR

An adaptive filter using the Least-Mean Square (LMS) algorithm, also known as the stochastic gradient algorithm. The initial filter coefficients are given by the initialTaps parameter. The tap values can be observed on the tapValues output. The default initial taps initialTaps are {1, 0, 0, 0}. This actor supports decimation, but not interpolation.

When used correctly, this LMS adaptive filter will adapt to try to minimize the mean-squared error of the signal at its error input. In order for this to be possible, the output of the filter should be compared (subtracted from) some reference signal to produce an error signal. That error signal should be fed back to the error input.

The stepSize parameter determines the rate of adaptation. If its magnitude is too large, or if it has the wrong sign, then the adaptation algorithm will be unstable.

The errorDelay parameter must equal the total number of delays in the path from the output of the filter back to the error input. This ensures correct alignment of the adaptation algorithm. The number of delays must be greater than zero.

This actor is type polymorphic, supporting any data type that supports multiplication by a scalar (the stepSize) and addition.

The algorithm is simple. Prior to each invocation of the parent class (an FIR filter), which computes the output given the input, this actor updates the coefficients according to the following formula,

 newTapValue = oldTapValue + error * stepSize * tapData
 

where tapData is the contents of the delay line at the tap in question. This assumes that the decimation parameter is set to 1 (the default). If it has a value different from 1, the algorithm is slightly more involved. Similarly, this assumes that the errorDelay is 1.

Since:

Ptolemy II 1.0

Version:

$Id: LMSAdaptive.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Edward A. Lee

See Also:

Serialized Form

Accepted Rating:

Red (eal)

Proposed Rating:

Yellow (eal)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

TypedIOPort	error The error input port.
Parameter	errorDelay The number of samples of delay in the feedback loop that brings the error back.
Parameter	initialTaps The initial taps of the filter.
Parameter	stepSize The adaptation step size.
TypedIOPort	tapValues The output of tap values.

Fields inherited from class ptolemy.domains.sdf.lib.FIR

_data, _decimationPhaseValue, _decimationValue, _interpolationValue, _mostRecent, _phaseLength, _reinitializeNeeded, _taps, _zero, decimation, decimationPhase, interpolation, taps

Fields inherited from class ptolemy.domains.sdf.lib.SDFTransformer

input, input_tokenConsumptionRate, output, output_tokenInitProduction, output_tokenProductionRate

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

LMSAdaptive(CompositeEntity container, java.lang.String name)
Construct an actor with the given container and name.

Method Summary

void	attributeChanged(Attribute attribute) Override the base class to set the taps parameter if the initialTaps parameter is changed.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() Consume the inputs, update the taps, and produce the outputs.
void	initialize() Override the base class to re-initialize the taps.
boolean	prefire() Return false if the error input does not have enough tokens to fire.

Methods inherited from class ptolemy.domains.sdf.lib.FIR

_initializeTaps, _initTypeConstraints, _reinitialize

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, postfire, preinitialize, 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, postfire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, preinitialize, 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

error

public TypedIOPort error

The error input port. The type of this port must match that of the input port.

errorDelay

public Parameter errorDelay

The number of samples of delay in the feedback loop that brings the error back. This has a type integer, and defaults to 1.

initialTaps

public Parameter initialTaps

The initial taps of the filter. This has a type of ArrayToken. By default, it contains the array {1.0, 0.0, 0.0, 0.0}, meaning that the output of the filter is initially the same as the input, and that the adaptive filter has four taps.

stepSize

public Parameter stepSize

The adaptation step size. This must have a type that can be multiplied by the input. It defaults to 0.01, a double.

tapValues

public TypedIOPort tapValues

The output of tap values. This has the same type as the initialTaps.

Constructor Detail

LMSAdaptive

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

Construct an actor with the given container and name.

Parameters:

container - The container.

name - The name of this actor.

Throws:

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

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

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Override the base class to set the taps parameter if the initialTaps parameter is changed. that are used in execution on the next invocation of fire().

Overrides:

attributeChanged in class FIR

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the attribute contains an invalid value or if the super method throws it.

clone

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

Clone the actor into the specified workspace. This calls the base class and then resets the type constraints.

Overrides:

clone in class FIR

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

Consume the inputs, update the taps, and produce the outputs.

Specified by:

fire in interface Executable

Overrides:

fire in class FIR

Throws:

IllegalActionException - If parameter values are invalid, or if there is no director, or if runtime type conflicts occur.

prefire

public boolean prefire()
                throws IllegalActionException

Return false if the error input does not have enough tokens to fire. Otherwise, return what the superclass returns.

Specified by:

prefire in interface Executable

Overrides:

prefire in class FIR

Returns:

False if the number of input tokens available is not at least equal to the decimation parameter.

Throws:

IllegalActionException - If the superclass throws it.

initialize

public void initialize()
                throws IllegalActionException

Override the base class to re-initialize the taps.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class FIR

Throws:

IllegalActionException - If the superclass throws it.