ptolemy.backtrack.automatic.ptolemy.domains.sdf.lib
Class Autocorrelation

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.backtrack.automatic.ptolemy.domains.sdf.lib.Autocorrelation

All Implemented Interfaces:

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

public class Autocorrelation
extends SDFTransformer
implements Rollbackable

This actor calculates the autocorrelation of a sequence of input tokens. It is polymorphic, supporting any input data type that supports multiplication, addition, and division by an integer. However, since integer division will lose the fractional portion of the result, type resolution will resolve the input type to double or double matrix if the input port is connected to an integer or integer matrix source, respectively.

Both biased and unbiased autocorrelation estimates are supported. If the parameter biased is true, then the autocorrelation estimate is

 N-1-k
 1  ---
 r(k) = -  \    x(n)x(n+k)
 N  /
 ---
 n=0
 

for k = 0, ... , p, where N is the number of inputs to average (numberOfInputs), p is the number of lags to estimate (numberOfLags), and x^* is the conjugate of the input (if it is complex). This estimate is biased because the outermost lags have fewer than N terms in the summation, and yet the summation is still normalized by N.

If the parameter biased is false (the default), then the estimate is

 N-1-k
 1   ---
 r(k) = ---  \    x(n)x(n+k)
 N-k  /
 ---
 n=0
 

In this case, the estimate is unbiased. However, note that the unbiased estimate does not guarantee a positive definite sequence, so a power spectral estimate based on this autocorrelation estimate may have negative components.

The output will be an array of tokens whose type is at least that of the input. If the parameter symmetricOutput is true, then the output will be symmetric and have length equal to twice the number of lags requested plus one. Otherwise, the output will have length equal to twice the number of lags requested, which will be almost symmetric (insert the last sample into the first position to get the symmetric output that you would get with the symmetricOutput being true).

Since:

Ptolemy II 1.0

Version:

$Id: Autocorrelation.java 59167 2010-09-21 17:08:02Z cxh $

Author:

Edward A. Lee and Yuhong Xiong

See Also:

Serialized Form

Accepted Rating:

Yellow (neuendor)

Proposed Rating:

Green (eal)

Nested Class Summary

private static class	Autocorrelation.FunctionTerm
private class	Autocorrelation.OutputTypeTerm Monotonic function that determines the type of the output port.

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

Entity.ContainedObjectsIterator

Field Summary

private int	_lengthOfOutput
private int	_numberOfInputs
private int	_numberOfLags
private Token[]	_outputs
private boolean	_symmetricOutput
protected Checkpoint	$CHECKPOINT
private FieldRecord	$RECORD$_lengthOfOutput
private FieldRecord	$RECORD$_numberOfInputs
private FieldRecord	$RECORD$_numberOfLags
private FieldRecord	$RECORD$_outputs
private FieldRecord	$RECORD$_symmetricOutput
protected CheckpointRecord	$RECORD$$CHECKPOINT
private FieldRecord[]	$RECORDS
Parameter	biased If true, the estimate will be biased.
Parameter	numberOfInputs Number of input samples to average.
Parameter	numberOfLags Number of autocorrelation lags to output.
Parameter	symmetricOutput If true, then the output from each firing will have 2*numberOfLags + 1 samples (an odd number) whose values are symmetric about the midpoint.

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

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

Method Summary

private int	$ASSIGN$_lengthOfOutput(int newValue)
private int	$ASSIGN$_numberOfInputs(int newValue)
private int	$ASSIGN$_numberOfLags(int newValue)
private Token	$ASSIGN$_outputs(int index0, Token newValue)
private Token[]	$ASSIGN$_outputs(Token[] newValue)
private boolean	$ASSIGN$_symmetricOutput(boolean newValue)
private Token[]	$BACKUP$_outputs()
void	$COMMIT(long timestamp) Commit changes up to the given timestamp, but not including changes made at timestamp and afterward.
Checkpoint	$GET$CHECKPOINT() Get the checkpoint object that monitors this rollbackable object.
void	$RESTORE(long timestamp, boolean trim) Restore a previous state to all the private fields of this rollbackable object.
java.lang.Object	$SET$CHECKPOINT(Checkpoint checkpoint) Set the checkpoint object of this rollbackable object.
void	attributeChanged(Attribute attribute) Check to see that the numberOfInputs parameter is positive, and that the numberOfLags parameter is positive.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() Consume tokens from the input and produce a token on the output that contains an array token that represents an autocorrelation estimate of the consumed tokens.
boolean	prefire() If there are not sufficient inputs, then return false.

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

$CHECKPOINT

protected transient Checkpoint $CHECKPOINT

biased

public Parameter biased

If true, the estimate will be biased. This is a boolean with default value false.

numberOfInputs

public Parameter numberOfInputs

Number of input samples to average. This is an integer with default value 256.

numberOfLags

public Parameter numberOfLags

Number of autocorrelation lags to output. This is an integer with default value 64.

symmetricOutput

public Parameter symmetricOutput

If true, then the output from each firing will have 2*numberOfLags + 1 samples (an odd number) whose values are symmetric about the midpoint. If false, then the output from each firing will have 2*numberOfLags samples (an even number) by omitting one of the endpoints (the last one). This is a boolean with default value false.

_numberOfInputs

private int _numberOfInputs

_numberOfLags

private int _numberOfLags

_lengthOfOutput

private int _lengthOfOutput

_symmetricOutput

private boolean _symmetricOutput

_outputs

private Token[] _outputs

$RECORD$$CHECKPOINT

protected transient CheckpointRecord $RECORD$$CHECKPOINT

$RECORD$_numberOfInputs

private transient FieldRecord $RECORD$_numberOfInputs

$RECORD$_numberOfLags

private transient FieldRecord $RECORD$_numberOfLags

$RECORD$_lengthOfOutput

private transient FieldRecord $RECORD$_lengthOfOutput

$RECORD$_symmetricOutput

private transient FieldRecord $RECORD$_symmetricOutput

$RECORD$_outputs

private transient FieldRecord $RECORD$_outputs

$RECORDS

private transient FieldRecord[] $RECORDS

Constructor Detail

Autocorrelation

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

Check to see that the numberOfInputs parameter is positive, and that the numberOfLags parameter is positive. Based on the new values, recompute the size of the output array.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that has changed.

Throws:

IllegalActionException - If the parameters are out of range.

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 sets 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 has an attribute that cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

fire

public void fire()
          throws IllegalActionException

Consume tokens from the input and produce a token on the output that contains an array token that represents an autocorrelation estimate of the consumed tokens. The estimate is consistent with the parameters of the object, as described in the class comment.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If there is no director.

prefire

public boolean prefire()
                throws IllegalActionException

If there are not sufficient inputs, then return false. Otherwise, return whatever the base class returns.

Specified by:

prefire in interface Executable

Overrides:

prefire in class SDFTransformer

Returns:

True if it is ok to continue.

Throws:

IllegalActionException - If the base class throws it.

$ASSIGN$_numberOfInputs

private final int $ASSIGN$_numberOfInputs(int newValue)

$ASSIGN$_numberOfLags

private final int $ASSIGN$_numberOfLags(int newValue)

$ASSIGN$_lengthOfOutput

private final int $ASSIGN$_lengthOfOutput(int newValue)

$ASSIGN$_symmetricOutput

private final boolean $ASSIGN$_symmetricOutput(boolean newValue)

$ASSIGN$_outputs

private final Token[] $ASSIGN$_outputs(Token[] newValue)

$ASSIGN$_outputs

private final Token $ASSIGN$_outputs(int index0,
                                     Token newValue)

$BACKUP$_outputs

private final Token[] $BACKUP$_outputs()

$COMMIT

public void $COMMIT(long timestamp)

Description copied from interface: Rollbackable

Commit changes up to the given timestamp, but not including changes made at timestamp and afterward.

Specified by:

$COMMIT in interface Rollbackable

Parameters:

timestamp - The timestamp.

$RESTORE

public void $RESTORE(long timestamp,
                     boolean trim)

Description copied from interface: Rollbackable

Restore a previous state to all the private fields of this rollbackable object.

Specified by:

$RESTORE in interface Rollbackable

Parameters:

timestamp - The timestamp taken at the time when the previous state was recorded.

trim - Whether to delete the records used for the rollback.

See Also:

Checkpoint.rollback(long, boolean)

$GET$CHECKPOINT

public final Checkpoint $GET$CHECKPOINT()

Description copied from interface: Rollbackable

Get the checkpoint object that monitors this rollbackable object.

Specified by:

$GET$CHECKPOINT in interface Rollbackable

Returns:

The checkpoint object.

$SET$CHECKPOINT

public final java.lang.Object $SET$CHECKPOINT(Checkpoint checkpoint)

Description copied from interface: Rollbackable

Set the checkpoint object of this rollbackable object. A merge operation is performed on the current checkpoint object and the new checkpoint object, so that the two checkpoint objects monitor the same set of objects when this function returns.

Specified by:

$SET$CHECKPOINT in interface Rollbackable

Parameters:

checkpoint - The new checkpoint object.

Returns:

This rollbackable object itself.

See Also:

Checkpoint.setCheckpoint(Checkpoint)