ptolemy.actor.util
Class DefaultCausalityInterface

java.lang.Object
  ptolemy.actor.util.DefaultCausalityInterface

All Implemented Interfaces:

CausalityInterface

Direct Known Subclasses:

BreakCausalityInterface, CausalityInterfaceForComposites, ContinuousIntegrator.IntegratorCausalityInterface

public class DefaultCausalityInterface
extends java.lang.Object
implements CausalityInterface

This class provides causality interfaces for actor networks as described in the paper "Causality Interfaces for Actor Networks" by Ye Zhou and Edward A. Lee, ACM Transactions on Embedded Computing Systems (TECS), April 2008, as available as Technical Report No. UCB/EECS-2006-148, November 16, 2006. Specifically, this class represents a simple default causality interface where every output port depends on every input port, unless removeDependency(IOPort, IOPort) has been called to prune the dependencies. In the latter case, the dependencies are pruned to not include the ones that were specified in that call.

In all cases, if there is any PortParameter in the actor, then all input ports become members of the same equivalence class, regardless of what dependencies have been pruned using removeDependency(IOPort, IOPort). The reason for this is that any output, present or future, may depend on the values at such port parameters. In particular, it is necessary for inputs on these port parameters to be present when any other input is processed because it affects the parameters of the actor.

Causality interfaces represent dependencies between input and output ports of an actor and can be used to perform scheduling or static analysis on actor models.

Since:

Ptolemy II 8.0

Version:

$Id: DefaultCausalityInterface.java 57044 2010-01-27 22:41:05Z cxh $

Author:

Edward A. Lee

Accepted Rating:

Red (eal)

Proposed Rating:

Yellow (eal)

Field Summary

protected Actor	_actor The associated actor.
protected java.util.Map<IOPort,java.util.Set<IOPort>>	_backwardPrunedDependencies A record of removed dependencies from output to input, if any.
protected Dependency	_defaultDependency The default dependency of an output port on an input port.
protected java.util.Map<IOPort,java.util.Map<IOPort,Dependency>>	_delayDependencies A record of delay dependencies from input to output, if any.
protected static java.util.Collection<IOPort>	_EMPTY_COLLECTION Empty collection for use by dependentPort().
protected java.util.Map<IOPort,java.util.Set<IOPort>>	_forwardPrunedDependencies A record of removed dependencies from input to output, if any.

Constructor Summary

DefaultCausalityInterface(Actor actor, Dependency defaultDependency)
Construct a causality interface for the specified actor.

Method Summary

protected void	_growDependencies(IOPort input, java.util.Set<IOPort> inputs, java.util.Set<IOPort> outputs) If the input port is already in the inputs set, do nothing and return.
private void	_removeDependency(IOPort inputPort, IOPort outputPort) For the benefit of the dependentPorts() and equivalentPorts() methods, remove the dependency that the input has on the output.
void	declareDelayDependency(IOPort input, IOPort output, double timeDelay, int index) Set the dependency that the specified output port has on the specified input port to represent a time delay with the specified value and superdense time index.
java.util.Collection<IOPort>	dependentPorts(IOPort port) Return a collection of the ports in this actor that depend on or are depended on by the specified port.
java.util.Collection<IOPort>	equivalentPorts(IOPort input) Return a collection of the input ports in this actor that are in the same equivalence class with the specified input port.
Actor	getActor() Return the actor for which this is a dependency.
Dependency	getDefaultDependency() Return the default dependency specified in the constructor.
Dependency	getDependency(IOPort input, IOPort output) Return the dependency between the specified input port and the specified output port.
void	removeDependency(IOPort inputPort, IOPort outputPort) Remove the dependency that the specified output port has on the specified input port.
java.lang.String	toString() Return a description of the causality interfaces.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_actor

protected Actor _actor

The associated actor.

_backwardPrunedDependencies

protected java.util.Map<IOPort,java.util.Set<IOPort>> _backwardPrunedDependencies

A record of removed dependencies from output to input, if any. In this case, if the dependency between the ports are anything other than the oTimesIdentity, then the dependency is removed.

_EMPTY_COLLECTION

protected static final java.util.Collection<IOPort> _EMPTY_COLLECTION

Empty collection for use by dependentPort().

_defaultDependency

protected Dependency _defaultDependency

The default dependency of an output port on an input port.

_delayDependencies

protected java.util.Map<IOPort,java.util.Map<IOPort,Dependency>> _delayDependencies

A record of delay dependencies from input to output, if any.

_forwardPrunedDependencies

protected java.util.Map<IOPort,java.util.Set<IOPort>> _forwardPrunedDependencies

A record of removed dependencies from input to output, if any. In this case, if the dependency between the ports are anything other than the oTimesIdentity, then the dependency is removed.

Constructor Detail

DefaultCausalityInterface

public DefaultCausalityInterface(Actor actor,
                                 Dependency defaultDependency)

Construct a causality interface for the specified actor.

Parameters:

actor - The actor for which this is a causality interface.

defaultDependency - The default dependency of an output port on an input port.

Method Detail

declareDelayDependency

public void declareDelayDependency(IOPort input,
                                   IOPort output,
                                   double timeDelay,
                                   int index)

Set the dependency that the specified output port has on the specified input port to represent a time delay with the specified value and superdense time index. This method is adaptive to the type of Dependency provided in the constructor. For example, if the constructor provides a BooleanDependency, then this method defines the dependency to be TRUE if the timeDelay is 0.0 and the index is 0, and otherwise it should be FALSE. If the Dependency is a RealDependency, then it uses the timeDelay argument to define the dependency. If it is a SuperdenseDependency, then it uses both the timeDelay and the index.

Specified by:

declareDelayDependency in interface CausalityInterface

Parameters:

input - The input port.

output - The output port with a time delay dependency on the input port.

timeDelay - The time delay.

index - The superdense time index.

dependentPorts

public java.util.Collection<IOPort> dependentPorts(IOPort port)
                                            throws IllegalActionException

Return a collection of the ports in this actor that depend on or are depended on by the specified port. A port X depends on a port Y if X is an output and Y is an input and getDependency(X,Y) returns oTimesIdentity() of the default dependency specified in the constructor.

This base class presumes (but does not check) that the argument is a port contained by the associated actor. If the actor is an input, then it returns a collection of all the outputs. If the actor is output, then it returns a collection of all the inputs.

Derived classes may override this, but they may need to also override getDependency(IOPort, IOPort) and equivalentPorts(IOPort) to be consistent.

Specified by:

dependentPorts in interface CausalityInterface

Parameters:

port - The port to find the dependents of.

Returns:

a collection of ports that depend on or are depended on by the specified port.

Throws:

IllegalActionException - Not thrown in this base class.

equivalentPorts

public java.util.Collection<IOPort> equivalentPorts(IOPort input)
                                             throws IllegalActionException

Return a collection of the input ports in this actor that are in the same equivalence class with the specified input port. This base class returns a collection of all the input ports of the associated actor, unless removeDependencies() has been called. In the latter case, it constructs the equivalence class based on the remaining dependencies on output ports, unless there is an instance of PortParameter in the actor. In that case, it again returns a collection of all the input ports.

If derived classes override this, they may also need to override getDependency(IOPort,IOPort) and dependentPorts(IOPort) to be consistent. The returned result should always include the specified input port.

An equivalence class is defined as follows. If input ports X and Y each have a dependency on any common port or on two equivalent ports, or they each can affect the state of the associated actor, then they are in an equivalence class. That is, there is a causal dependency. They are also in the same equivalence class if there is a port Z in an equivalence class with X and in an equivalence class with Y. If the actor has any instance of ParameterPort, then all input ports are in the same equivalence class. Otherwise, they are not in the same equivalence class.

Specified by:

equivalentPorts in interface CausalityInterface

Parameters:

input - The port to find the equivalence class of.

Returns:

set of the input ports in this actor that are in an equivalence class with the specified input.

Throws:

java.lang.IllegalArgumentException - If the argument is not contained by the associated actor.

IllegalActionException - Not thrown in this base class.

getActor

public Actor getActor()

Return the actor for which this is a dependency.

Specified by:

getActor in interface CausalityInterface

Returns:

The actor for which this is a dependency.

getDefaultDependency

public Dependency getDefaultDependency()

Return the default dependency specified in the constructor.

Specified by:

getDefaultDependency in interface CausalityInterface

Returns:

The default dependency.

getDependency

public Dependency getDependency(IOPort input,
                                IOPort output)
                         throws IllegalActionException

Return the dependency between the specified input port and the specified output port. This base class returns the default dependency if the first port is an input port owned by this actor and the second one is an output port owned by this actor. Otherwise, it returns the additive identity of the dependency. Also, if removeDependency(IOPort, IOPort) has been called with the same two specified ports, then this method will return the additive identity.

Derived classes should override this method to provide actor-specific dependency information. If they do so, then they may also need to override equivalentPorts(IOPort) and dependentPorts(IOPort) to be consistent.

Specified by:

getDependency in interface CausalityInterface

Parameters:

input - The input port.

output - The output port.

Returns:

The dependency between the specified input port and the specified output port.

Throws:

IllegalActionException - Not thrown in this base class.

toString

public java.lang.String toString()

Return a description of the causality interfaces.

Overrides:

toString in class java.lang.Object

Returns:

A description of the causality interfaces.

removeDependency

public void removeDependency(IOPort inputPort,
                             IOPort outputPort)

Remove the dependency that the specified output port has on the specified input port. Specifically, calling this method ensures that getDependency(inputPort, outputPort) will return defaultDependency.oPlusIdentity() instead of the default defaultDependency.oTimesIdentity(). It also adjusts what is returned by equivalentPorts(IOPort) and dependentPorts(IOPort).

Specified by:

removeDependency in interface CausalityInterface

Parameters:

inputPort - The input port.

outputPort - The output port that does not depend on the input port.

See Also:

getDependency(IOPort, IOPort)

_growDependencies

protected void _growDependencies(IOPort input,
                                 java.util.Set<IOPort> inputs,
                                 java.util.Set<IOPort> outputs)
                          throws IllegalActionException

If the input port is already in the inputs set, do nothing and return. Otherwise, add the input port to the inputs set, and its output dependents to the outputs set. If any of those output dependents were not already in the outputs set, add them, and then recursively invoke this same method on all input ports that depend on those outputs.

Parameters:

input - The input port.

inputs - The set of inputs to which input is added if it is not already present.

outputs - The set of output dependents to which the output dependents are added if input was not in the inputs set.

Throws:

IllegalActionException - Not thrown in this base class.

_removeDependency

private void _removeDependency(IOPort inputPort,
                               IOPort outputPort)

For the benefit of the dependentPorts() and equivalentPorts() methods, remove the dependency that the input has on the output.

Parameters:

inputPort - The input.

outputPort - The output.