DefaultCausalityInterface

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

All Implemented Interfaces:

CausalityInterface

Direct Known Subclasses:

BreakCausalityInterface, CausalityInterfaceForComposites
```
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 70398 2014-10-22 23:44:32Z cxh $

Author:

Edward A. Lee

Accepted Rating:
Red (eal)

Proposed Rating:
Yellow (eal)

Field Summary

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`DefaultCausalityInterface(Actor actor, Dependency defaultDependency)` Construct a causality interface for the specified actor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.
`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. By default, 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. However, if removeDependency(IOPort, IOPort) has been called, then it prunes the results to not include ports where the dependency has been explicitly removed.
    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.

Class DefaultCausalityInterface

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

_actor

_backwardPrunedDependencies

_EMPTY_COLLECTION

_defaultDependency

_delayDependencies

_forwardPrunedDependencies

Constructor Detail

DefaultCausalityInterface

Method Detail

declareDelayDependency

dependentPorts

equivalentPorts

getActor

getDefaultDependency

getDependency

toString

removeDependency

_growDependencies