ptolemy.domains.sdf.lib
Class FIR

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.InstantiableNamedObj
          extended byptolemy.kernel.Entity
              extended byptolemy.kernel.ComponentEntity
                  extended byptolemy.actor.AtomicActor
                      extended byptolemy.actor.TypedAtomicActor
                          extended byptolemy.domains.sdf.lib.SDFTransformer
                              extended byptolemy.domains.sdf.lib.FIR
All Implemented Interfaces:
ptolemy.actor.Actor, ptolemy.kernel.util.Changeable, java.lang.Cloneable, ptolemy.kernel.util.Debuggable, ptolemy.kernel.util.DebugListener, ptolemy.kernel.util.Derivable, ptolemy.actor.Executable, ptolemy.kernel.util.Instantiable, ptolemy.kernel.util.ModelErrorHandler, ptolemy.kernel.util.MoMLExportable, ptolemy.kernel.util.Nameable, SequenceActor, java.io.Serializable, ptolemy.actor.TypedActor
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,v 1.81 2004/04/13 05:12:27 cxh Exp $
Author:
Edward A. Lee, Bart Kienhuis, Steve Neuendorffer
See Also:
Token, Serialized Form
Accepted Rating:
Yellow (neuendor)
Proposed Rating:
Yellow (neuendor)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.Entity
ptolemy.kernel.Entity.ContainedObjectsIterator
 
Field Summary
protected  ptolemy.data.Token[] _data
          The delay line.
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.
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.
protected  ptolemy.data.Token[] _taps
          Local cache of the tap values.
protected  ptolemy.data.Token _zero
          Local cache of the zero token.
 ptolemy.data.expr.Parameter decimation
          The decimation ratio of the filter.
 ptolemy.data.expr.Parameter decimationPhase
          The decimation phase of the filter.
 ptolemy.data.expr.Parameter interpolation
          The interpolation ratio of the filter.
 ptolemy.data.expr.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
_stopRequested
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
 
Fields inherited from interface ptolemy.actor.Executable
COMPLETED, NOT_READY, STOP_ITERATING
 
Constructor Summary
FIR(ptolemy.kernel.CompositeEntity container, java.lang.String name)
          Construct an actor with the given container and name.
 
Method Summary
protected  void _reinitialize()
           
 void attributeChanged(ptolemy.kernel.util.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(ptolemy.kernel.util.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, attributeTypeChanged, clone, newPort, typeConstraintList
 
Methods inherited from class ptolemy.actor.AtomicActor
_createReceivers, connectionsChanged, getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, iterate, newReceiver, outputPortList, postfire, preinitialize, pruneDependencies, removeDependency, setContainer, stop, stopFire, terminate, wrapup
 
Methods inherited from class ptolemy.kernel.ComponentEntity
_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, propagateExistence, setName
 
Methods inherited from class ptolemy.kernel.Entity
_description, _exportMoMLContents, _removePort, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName, validateSettables
 
Methods inherited from class ptolemy.kernel.InstantiableNamedObj
_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, workspace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface ptolemy.actor.Actor
getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, newReceiver, outputPortList
 
Methods inherited from interface ptolemy.actor.Executable
iterate, postfire, preinitialize, stop, stopFire, terminate, wrapup
 
Methods inherited from interface ptolemy.kernel.util.Derivable
getDerivedLevel, getDerivedList, propagateValue
 
Methods inherited from interface ptolemy.kernel.util.Nameable
description, getFullName, getName, getName
 

Field Detail

decimation

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


decimationPhase

public ptolemy.data.expr.Parameter decimationPhase
The decimation phase of the filter. This must contain an IntToken, and by default it has value zero.


interpolation

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


taps

public ptolemy.data.expr.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 ptolemy.data.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 ptolemy.data.Token[] _taps
Local cache of the tap values.


_zero

protected ptolemy.data.Token _zero
Local cache of the zero token.

Constructor Detail

FIR

public FIR(ptolemy.kernel.CompositeEntity container,
           java.lang.String name)
    throws ptolemy.kernel.util.NameDuplicationException,
           ptolemy.kernel.util.IllegalActionException
Construct an actor with the given container and name.

Parameters:
container - The container.
name - The name of this actor.
Throws:
ptolemy.kernel.util.IllegalActionException - If the actor cannot be contained by the proposed container.
ptolemy.kernel.util.NameDuplicationException - If the container already has an actor with this name.
Method Detail

attributeChanged

public void attributeChanged(ptolemy.kernel.util.Attribute attribute)
                      throws ptolemy.kernel.util.IllegalActionException
Set a flag that causes recalculation of various local variables that are used in execution on the next invocation of fire().

Parameters:
attribute - The attribute that changed.
Throws:
ptolemy.kernel.util.IllegalActionException

clone

public java.lang.Object clone(ptolemy.kernel.util.Workspace workspace)
                       throws java.lang.CloneNotSupportedException
Clone the actor into the specified workspace. This calls the base class and then resets the type constraints.

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.

fire

public void fire()
          throws ptolemy.kernel.util.IllegalActionException
Consume the inputs and produce the outputs of the FIR filter.

Throws:
ptolemy.kernel.util.IllegalActionException - If parameter values are invalid, or if there is no director, or if runtime type conflicts occur.

prefire

public boolean prefire()
                throws ptolemy.kernel.util.IllegalActionException
Return false if the input does not have enough tokens to fire. Otherwise, return what the superclass returns.

Specified by:
prefire in interface ptolemy.actor.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:
ptolemy.kernel.util.IllegalActionException - If the superclass throws it.

initialize

public void initialize()
                throws ptolemy.kernel.util.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.

Throws:
ptolemy.kernel.util.IllegalActionException - If the superclass throws it.

_reinitialize

protected void _reinitialize()
                      throws ptolemy.kernel.util.IllegalActionException
Throws:
ptolemy.kernel.util.IllegalActionException