Package ptolemy.domains.pthales.kernel

Class PthalesDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, PeriodicDirector, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class PthalesDirector
extends SDFDirector
    A director for multidimensional dataflow.

    This is based on Array-OL, as described by:

    1. Boulet, P. (2007). "Array-OL Revisited, Multidimensional Intensive Signal Processing Specification," Technical Report 6113, INRIA, Orsay, France.

    A more detailed documentation of the Pthales domain can be found in a technical report currently under preparation and accessible at:

    1. Remi Barrere, Eric Lenormand, Dai Bui, Edward A. Lee, Christopher Shaver and Stavros Tripakis, "An Introduction to the Pthales Domain of Ptolemy II, EECS Department, University of California, Berkeley, Technical Report No. UCB/EECS-2011-32, April 26, 2011. (http://www.eecs.berkeley.edu/Pubs/TechRpts/2011/EECS-2011-32.html)

    The notation used here is intended to follow the spirit of SpearDE [FIXME: Reference?], from Thales, a software system based on Array-OL. In this notation, unlike Boulet's, dimensions are named, and patterns for reading and writing arrays are given using those names.

    [FIXME: the description that follows needs update, the contents and syntax of parameter specs have changed] [FIXME: it seems mostly OK to me (Stavros): I made a mild pass. Please check] The execution is governed by the following parameters in the model. In all cases except for the "repetitions" parameter, the parameters are OrderedRecords of the form "[x = n, y = m, ...]", where x and y are arbitrary dimension names and n and m are non-negative integers. For parameters that supports strides (such as the "pattern" parameter), n and m can be replaced by {n,s} or {m,s}, where s is the stride (a positive integer). The stride defaults to 1 if not specified. Unless otherwise stated, the parameters do not support strides. Ports contain the following parameters:

    1. size: This is a parameter of each output port that specifies the size of the array written in that output port. All dimensions must be specified. This parameter is optional, as the size of an output array can be deduced from the other parameters. In addition, every input port of a composite actor that contains a PthalesDirector must also have such a parameter. [FIXME: true?]
    2. base: This mandatory parameter gives the base location (origin) of the output or input array at which an actor begins writing or reading at each iteration of this director. All dimensions must be specified. The order in which they are specified does not matter.
    3. pattern: This is a parameter of each port that specifies the shape of the portion of the array produced or consumed on that port at each firing of the actor within an iteration. The number of firings of an actor within an iteration is specified by the "repetitions" parameter of the actor (see below). Moreover, if an actor reads from or writes to the port sequentially (using get() and send() methods), then the pattern specifies the order in which the array is filled. For example, if you send tokens with values 1, 2, 3, 4, 5, 6 using a pattern [x=3, y=2], then the array is filled as follows (assuming base=[x=0, y=0]):
      x y value
      0 0 1
      1 0 2
      2 0 3
      0 1 4
      1 1 5
      2 1 6
      If on the other hand you specify a pattern [y=2, x=3], then an array of the same shape is used, but it is now filled as follows:
      x y value
      0 0 1
      0 1 2
      1 0 3
      1 1 4
      2 0 5
      2 1 6
      If a stride is given, then the pattern may have gaps in it. For example, "x = {2,2}" specifies that two values are produced in the x dimension, and that they are separated by one value that is not produced. Values that are not produced default to zero (the value of zero depends on the data type; for example, zero for strings is the empty string, whereas zero for doubles is 0.0).
    4. tiling: This parameter gives the increment of the base location in each dimension for each successive firing of the actor within an iteration. This is a property of an output or an input port of an actor.
    In addition, actors must contain the following parameter:
    1. repetitions: This is a required parameter for every actor in the Pthales domain. It is an array of positive integers of the form "{ k, l, ... }". It specifies the number of times an actor fires within an iteration. This number is equal to the product of all elements in the repetitions vector. So, "{2, 4}" specifies that the actor should fire a total of 2*4=8 times at each iteration. Moreover, this parameter defines a set of nested loops (of depth equal to the length of the array) and the number of iterations of each loop (from the inner to the outer loop). So "{2, 4}" specifies an inner loop with 2 iterations and an outer loop with 4 iterations. There is a one-to-one mapping between the elements of the repetitions array and the fields of the tiling parameters of all ports of the corresponding actor. The body of the inner-most loop specifies the processing that the actor performs on a given pattern, during one firing of the actor within an iteration. A complete execution of the entire nested loop specifies the entire processing of the array by the actor. Thus, each firing of the actor produces or consumes only portions of the array and the complete processing is done by assembling these portions together according to the above parameters.

    In all cases, when indexes are incremented, they are incremented in a toroidal fashion, wrapping around when they reach the size of the array. Thus, it is always possible (though rarely useful) for an array size to be 1 in every dimension. [FIXME?]

    NOTE: It should be possible to define a PtalesPort and PtalesCompositeActor that contain the above parameters, as a convenience. These could be put in a library.

    NOTE: It should be possible to create a single interface for this director so that when double clicked, it brings up an interactive dialog that has the form of a Spear table. It would have one row per port, plus a header row to specify the iterations.

    FIXME: Need to export production and consumption data for SDF, allowing these Pthales models to be nested within SDF or within Pthales, which will also allow it to be nested within modal models.

    Since:
    Ptolemy II 10.0
    Version:
    $Id$
    Author:
    Edward A. Lee, Eric Lenormand, Stavros Tripakis
    Pt.AcceptedRating:
    Red (cxh)
    Pt.ProposedRating:
    Red (cxh)

    • Constructor Detail

      • PthalesDirector

        public PthalesDirector​(CompositeEntity container,
                       java.lang.String name)
                throws IllegalActionException,
                       NameDuplicationException
        Constructs a PthalesDirector object, using PthalesScheduler.
        Parameters:
        container - Container of the director.
        name - Name of this director.
        Throws:
        IllegalActionException - If the director is not compatible with the specified container. May be thrown in a derived class.
        NameDuplicationException - If the container is not a CompositeActor and the name collides with an entity in the container.

    • Method Detail

      • 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 SDFDirector
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        The new object.
        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
        Calculate the current schedule, if necessary, and iterate the contained actors in the order given by the schedule. Iterating an actor involves calling the actor's iterate() method, which is equivalent to calling the actor's prefire(), fire() and postfire() methods in succession. If iterate() returns NOT_READY, indicating that the actor is not ready to execute, then an IllegalActionException will be thrown. The values returned from iterate() are recorded and are used to determine the value that postfire() will return at the end of the director's iteration. NOTE: This method does not conform with the strict actor semantics because it calls postfire() of actors. Thus, it should not be used in domains that require a strict actor semantics, such as SR or Continuous.
        Specified by:
        fire in interface Executable
        Overrides:
        fire in class SDFDirector
        Throws:
        IllegalActionException - If any actor executed by this actor return false in prefire.
        InvalidStateException - If this director does not have a container.

      • preinitialize

        public void preinitialize()
                   throws IllegalActionException
        Preinitialize the actors associated with this director and compute the schedule. The schedule is computed during preinitialization so that hierarchical opaque composite actors can be scheduled properly, since the act of computing the schedule sets the rate parameters of the external ports. In addition, performing scheduling during preinitialization enables it to be present during code generation. The order in which the actors are preinitialized is arbitrary.
        Specified by:
        preinitialize in interface Initializable
        Overrides:
        preinitialize in class SDFDirector
        Throws:
        IllegalActionException - If the preinitialize() method of one of the associated actors throws it.

      • transferInputs

        public boolean transferInputs​(IOPort port)
                       throws IllegalActionException
        Override the base class method to transfer enough tokens to complete an internal iteration. If there are not enough tokens, then throw an exception. If the port is not connected on the inside, or has a narrower width on the inside than on the outside, then consume exactly one token from the corresponding outside channels and discard it. Thus, a port connected on the outside but not on the inside can be used as a trigger for an SDF composite actor.
        Overrides:
        transferInputs in class SDFDirector
        Parameters:
        port - The port to transfer tokens from.
        Returns:
        True if data are transferred.
        Throws:
        IllegalActionException - If the port is not an opaque input port, or if there are not enough input tokens available.

      • transferOutputs

        public boolean transferOutputs​(IOPort port)
                        throws IllegalActionException
        Override the base class method to transfer enough tokens to fulfill the output production rate. This behavior is required to handle the case of non-homogeneous opaque composite actors. The port argument must be an opaque output port. If any channel of the output port has no data, then that channel is ignored.
        Overrides:
        transferOutputs in class SDFDirector
        Parameters:
        port - The port to transfer tokens from.
        Returns:
        True if data are transferred.
        Throws:
        IllegalActionException - If the port is not an opaque output port.