ptolemy.domains.wireless.lib
Class CollisionDetector

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.domains.wireless.lib.CollisionDetector

All Implemented Interfaces:

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

public class CollisionDetector
extends TypedAtomicActor

This actor models a typical physical layer front end of a wireless receiver. It models a receiver where messages have a non-zero duration and messages can collide with one another, causing a failure to receive. A message is provided to this actor at the time corresponding to the start of its transmission. Along with the message (an arbitrary token), the inputs must provide the duration of the message and its power. The message spans an interval of time starting when it is provided to this actor and ending at that time plus the duration. If another message overlaps with a given message and has sufficient power, then the given message will be sent to the collided output. Otherwise it is sent to the received output. In both cases, the message appears at the corresponding output at the time it is received plus the duration (i.e. the time at which the message has been completed).

The inputs are:

• message: The message carried by each transmission.
• power: The power of the received signal at the location of this receiver.
• duration: The time duration of the transmission.

The power and duration are typically delivered by the channel in the "properties" field of the transmission. The power is usually given as a power density (per unit area) so that a receiver can multiply it by its antenna area to determine the received power. It is in a linear scale (vs. DB), typically with units such as watts per square meter. The duration is a non-negative double, and the message is an arbitrary token.

The outputs are:

• received: The message received. This port produces an output only if the received power is sufficient and there are no collisions. The output is produced at a time equal to the time this actor receives the message plus the value received on the duration input.
• collided: The message discarded. This port produces an output only if the received message collides with another message of sufficient power. The output is produced at a time equal to the time this actor receives the message plus the value received on the duration input. The value of the output is the message that cannot be received.

This actor is typically used with a channel that delivers a properties record token that contains power and duration fields. These fields can be extracted by using a GetProperties actor followed by a RecordDisassembler. The PowerLossChannel, for example, can be used. However, in order for the type constraints to be satisfied, the PowerLossChannel's defaultProperties parameter must be augmented with a default value for the duration. Each transmitter can override that default with its own message duration and transmit power.

Any message whose power (as specified at the power input) is less than the value of the powerThreshold parameter is ignored. It will not cause collisions and is not produced at the collided output. The powerThreshold parameter thus specifies the power level at which the receiver simply fails to detect the signal. It is given in a linear scale (vs. DB) with the same units as the power input. The default value is zero, i.e. by default it won't ignore any received signal.

Any message whose power exceeds powerThreshold has the potential of being successfully received, of failing to be received due to a collision, and of causing a collision. A message is successfully received if throughout its duration, its power exceeds the sum of all other message powers by at least SNRThresholdInDB (which as the name suggests, is given in decibels, rather than in a linear scale, as is customary for power ratios). Formally, let the message power for the i-th message be p_i(t) at time t. Before the message is received and after its duration expires, this power is zero. The i-th message is successfully received if p_i(t) >= P S_{(j != i)} p_j(t) for all t where p_i(t) > 0, where P = 10^(SNRThresholdInDB/10) which is the signal to interference ratio in a linear scale.

The way this actor works is that each input that has sufficient power is recorded in a hash table indexed by the time at which its duration expires. In addition, the director is requested to fire this actor at that time. Any time a message arrives, the actor checks for collisions, and marks any message subjected to a collision by this arrival. When the duration expires, the message is produced on one of the two outputs depending on whether it is marked as having encountered a collision, and it is removed from the hash table.

NOTE: This actor assumes that the duration of messages is short relative to the rate at which the actors move. That is, the received power (and whether a receiver is in range) is determined once, at the time the message starts, and remains constant throughout the transmission. It also requires that all three inputs have tokens when fired.

Since:

Ptolemy II 4.0

Version:

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

Author:

Yang Zhao, Xiaojun Liu, Edward Lee

See Also:

PowerLossChannel, GetProperties, RecordDisassembler, Serialized Form

Accepted Rating:

Yellow (cxh)

Proposed Rating:

Green (cxh)

Nested Class Summary

private static class

CollisionDetector.Reception Data structure for storing reception data.

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

Entity.ContainedObjectsIterator

Field Summary

private double	_powerThreshold
private java.util.List	_receptions
private double	_SNRThresholdInDB
private double	_totalPower
TypedIOPort	collided The output port that produces messages that cannot be received because of a collision.
TypedIOPort	duration The input port for the time that a message transmission takes.
TypedIOPort	message The input port for the message.
TypedIOPort	power The input port for power.
Parameter	powerThreshold The power threshold above which the signal can be detected at the receiver.
TypedIOPort	received The output port that produces messages that are successfully received.
Parameter	SNRThresholdInDB The threshold for the signal to be recognized from interference.

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

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

Method Summary

void	attributeChanged(Attribute attribute) If the specified attribute is SNRThresholdInDB, or powerThreshold then check that a non-negative number is given.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
void	fire() If a new message is available at the inputs, record it in the list indexed with the time that the message shall be completed, and loop through the list to check whether there is collision.
void	initialize() Initialize the private variables.

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

message

public TypedIOPort message

The input port for the message. This has undeclared type.

power

public TypedIOPort power

The input port for power. This has type double, and is typically a power density, in units such as watts per square meter.

duration

public TypedIOPort duration

The input port for the time that a message transmission takes. This has type double.

received

public TypedIOPort received

The output port that produces messages that are successfully received. This has the same type as the message input.

collided

public TypedIOPort collided

The output port that produces messages that cannot be received because of a collision. This has the same type as the message input.

SNRThresholdInDB

public Parameter SNRThresholdInDB

The threshold for the signal to be recognized from interference. It is specified in decibels (10 * log₁₀(r), where r is the power ratio. This is a double that defaults to Infinity, which indicates that all overlapping messages are lost to collisions.

powerThreshold

public Parameter powerThreshold

The power threshold above which the signal can be detected at the receiver. Any message with a received power below this number is ignored. This has type double and defaults to 0.0, which indicates that all messages (with nonzero power) will be received.

_powerThreshold

private double _powerThreshold

_SNRThresholdInDB

private double _SNRThresholdInDB

_totalPower

private double _totalPower

_receptions

private java.util.List _receptions

Constructor Detail

CollisionDetector

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

Construct an actor with the specified name and container. The container argument must not be null, or a NullPointerException will be thrown. If the name argument is null, then the name is set to the empty string. This constructor write-synchronizes on the workspace.

Parameters:

container - The container.

name - The name of the actor.

Throws:

IllegalActionException - If the container is incompatible with this actor.

NameDuplicationException - If the name coincides with an actor already in the container.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

If the specified attribute is SNRThresholdInDB, or powerThreshold then check that a non-negative number is given. Otherwise, defer to the base class.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container.

clone

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

Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there). The result is an object with no container.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the cloned object.

Returns:

The new Attribute.

Throws:

java.lang.CloneNotSupportedException - Not thrown in this base class

See Also:

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

fire

public void fire()
          throws IllegalActionException

If a new message is available at the inputs, record it in the list indexed with the time that the message shall be completed, and loop through the list to check whether there is collision. If the current time matches one of the times that we have previously recorded as the completion time for a transmission, then output the received message to the received output port if it is not lost to a collision; otherwise, output it to the collided output port.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If an error occurs reading or writing inputs or outputs.

initialize

public void initialize()
                throws IllegalActionException

Initialize the private variables.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If thrown by the base class.