ptolemy.domains.sdf.lib
Class FIR

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

All Implemented Interfaces:

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

Direct Known Subclasses:

LMSAdaptive, RaisedCosine, VariableFIR

public class FIR
extends SDFTransformer

This actor implements a type polymorphic finite-impulse response filter with multirate capability. Since this filter operates on Tokens, it is polymorphic in the type of data it operates on.

Note that the current implementation of this actor only reads its parameters during initialization, so the filter cannot be changed during execution.

When the decimation (interpolation) parameters are different from unity, the filter behaves exactly as it were followed (preceded) by a DownSample (UpSample) actor. However, the implementation is much more efficient than it would be using UpSample or DownSample actors; a polyphase structure is used internally, avoiding unnecessary use of memory and unnecessary multiplication by zero. Arbitrary sample-rate conversions by rational factors can be accomplished this way.

To design a filter for a multirate system, simply assume the sample rate is the product of the interpolation parameter and the input sample rate, or equivalently, the product of the decimation parameter and the output sample rate. In particular, considerable care must be taken to avoid aliasing. Specifically, if the input sample rate is f, then the filter stopband should begin before f/2. If the interpolation ratio is i, then f/2 is a fraction 1/2i of the sample rate at which you must design your filter.

The decimationPhase parameter is somewhat subtle. It is exactly equivalent the phase parameter of the DownSample actor. Its interpretation is as follows; when decimating, samples are conceptually discarded (although a polyphase structure does not actually compute the discarded samples). If you are decimating by a factor of three, then you will select one of every three outputs, with three possible phases. When decimationPhase is zero (the default), the latest (most recent) samples are the ones selected. The decimationPhase must be strictly less than the decimation ratio.

Note: in this description "sample rate" refers to the physical sampling rate of an A/D converter in the system. In other words, the number of data samples per second. This is not usually specified anywhere in an SDF system, and most definitely does NOT correspond to the SDF rate parameters of this actor. This actor automatically sets the rates of the input and output ports to the decimation and interpolation ratios, respectively.

For more information about polyphase filters, see F. J. Harris, "Multirate FIR Filters for Interpolating and Desampling", in Handbook of Digital Signal Processing, Academic Press, 1987.

Since:

Ptolemy II 0.2

Version:

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

Author:

Edward A. Lee, Bart Kienhuis, Steve Neuendorffer

See Also:

Token, Serialized Form

Accepted Rating:

Yellow (neuendor)

Proposed Rating:

Yellow (neuendor)

Nested Class Summary

private class

FIR.OutputTypeFunction This class implements a monotonic function of the input port type.

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

Entity.ContainedObjectsIterator

Field Summary

protected Token[]	_data The delay line.
private Token	_dataItem
protected int	_decimationPhaseValue DecimationPhase value.
protected int	_decimationValue Decimation value.
protected int	_interpolationValue Interpolation value.
protected int	_mostRecent The index into the delay line of the most recent input.
private Token	_outToken
protected int	_phaseLength The phaseLength is ceiling(length/interpolation), where length is the number of taps.
protected boolean	_reinitializeNeeded Indicator that at least one attribute has been changed since the last initialization.
private Token	_tapItem
protected Token[]	_taps Local cache of the tap values.
protected Token	_zero Local cache of the zero token.
Parameter	decimation The decimation ratio of the filter.
Parameter	decimationPhase The decimation phase of the filter.
Parameter	interpolation The interpolation ratio of the filter.
Parameter	taps The taps of the filter.

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

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

Method Summary

protected void	_initializeTaps() Initialize the taps.
protected void	_initTypeConstraints() Initialize the type constraints for this actor.
protected void	_reinitialize() Reinitialize local variables in response to changes in attributes.
void	attributeChanged(Attribute attribute) Set a flag that causes recalculation of various local variables that are used in execution on the next invocation of fire().
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() Consume the inputs and produce the outputs of the FIR filter.
void	initialize() Perform domain-specific initialization by calling the initialize(Actor) method of the director.
boolean	prefire() Return false if the input does not have enough tokens to fire.

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

decimation

public Parameter decimation

The decimation ratio of the filter. This must contain an IntToken, and by default it has value one.

decimationPhase

public Parameter decimationPhase

The decimation phase of the filter. This must contain an IntToken, and by default it has value zero.

interpolation

public Parameter interpolation

The interpolation ratio of the filter. This must contain an IntToken, and by default it has value one.

taps

public Parameter taps

The taps of the filter. This has a type of ArrayToken. By default, it contains an array with a single integer one, meaning that the output of the filter is the same as the input.

_data

protected Token[] _data

The delay line.

_mostRecent

protected int _mostRecent

The index into the delay line of the most recent input.

_phaseLength

protected int _phaseLength

The phaseLength is ceiling(length/interpolation), where length is the number of taps.

_decimationValue

protected int _decimationValue

Decimation value.

_interpolationValue

protected int _interpolationValue

Interpolation value.

_decimationPhaseValue

protected int _decimationPhaseValue

DecimationPhase value.

_reinitializeNeeded

protected boolean _reinitializeNeeded

Indicator that at least one attribute has been changed since the last initialization.

_taps

protected Token[] _taps

Local cache of the tap values.

_zero

protected Token _zero

Local cache of the zero token.

_outToken

private Token _outToken

_tapItem

private Token _tapItem

_dataItem

private Token _dataItem

Constructor Detail

FIR

public FIR(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

Set a flag that causes recalculation of various local variables that are used in execution on the next invocation of fire().

Overrides:

attributeChanged in class NamedObj

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

Consume the inputs and produce the outputs of the FIR filter.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

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

initialize

public void initialize()
                throws IllegalActionException

Perform domain-specific initialization by calling the initialize(Actor) method of the director. The director may reject the actor by throwing an exception if the actor is incompatible with the domain. Set a flag that reinitializes the data buffer at the first firing.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If the superclass throws it.

prefire

public boolean prefire()
                throws IllegalActionException

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

Specified by:

prefire in interface Executable

Overrides:

prefire in class SDFTransformer

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.

_initializeTaps

protected void _initializeTaps()
                        throws IllegalActionException

Initialize the taps.

Throws:

IllegalActionException - If we can't get the token from the parameter taps.

_initTypeConstraints

protected void _initTypeConstraints()

Initialize the type constraints for this actor.

_reinitialize

protected void _reinitialize()
                      throws IllegalActionException

Reinitialize local variables in response to changes in attributes.

Throws:

IllegalActionException - If there is a problem reinitializing.