IterateOverArray
ptolemy.actor.lib.hoc.IterateOverArray

This actor iterates the contained actor or model over input arrays. To use it, either drop an actor on it and provide arrays to the inputs, or use a default configuration where the actor contains an instance of IterateComposite. In the latter case, you can simply look inside and populate that actor with a submodel that will be applied to the array elements. The submodel is required to have a director. An SDF director will often be sufficient for operations taken on array elements, but other directors can be used as well. Note that this inside director should not impose a limit on the number of iterations of the inside model. If it does, then that limit will be respected, which may result in a failure to iterate over all the input data. <p> Each input port expects an array. When this actor fires, an array is read on each input port that has one, and its contents are provided sequentially to the contained actor or model. This actor then iterates the contained actor or model until either there are no more input data for the actor or the prefire() method of the actor or model returns false. If postfire() of the actor returns false, then postfire() of this actor will return false, requesting a halt to execution of the model. The outputs from the contained actor are collected into arrays that are produced on the outputs of this actor. <p> A special variable named "iterationCount" can be used in any expression setting the value of a parameter of this actor or its contents. This variable has an integer value that starts at 1 during the first iteration of the contained actor(s) and is incremented by 1 on each firing. If the inside actors consume one token on each firing, then its final value will be the size of the input array(s). <p> This actor is properly viewed as a "higher-order component" in that its contained actor is a parameter that specifies how to operate on input arrays. It is inspired by the higher-order functions of functional languages, but unlike those, the contained actor need not be functional. That is, it can have state. <p> Note that you cannot place class definitions inside this actor. There should be no need to because class instances inside it can be instances of classes defined outside of it. <p> This actor (and many of the other higher-order components) has its intellectual roots in the higher-order functions of functional languages, which have been in use since the 1970s. Similar actors were implemented in Ptolemy Classic, and are described in Lee & Parks, "Dataflow Process Networks," <i>Proceedings of the IEEE</i>, 1995. Those were inspired by [2]. Alternative approaches are found dataflow visual programming since the beginning (Sutherland in the 1960s, Prograph and Labview in the 1980s), and in time-based visual languages (Simulink in the 1990s). <p> There are a number of known bugs or limitations in this implementation: <ul> <li> FIXME: When you drop in an actor, and then another actor, and then select "undo," the second actor is deleted without the first one being re-created. Thus, undo is only a partial undo. The fix to this is extremely complicated. Probably the only viable mechanism is to use UndoStackAttribute.getUndoInfo() to get the undo stack and then to manipulate the contents of that stack directly. <li> FIXME: There should be an option to reset between firings of the inside actor. <li> FIXME: If you drop a new actor onto an IterateOverArray in a subclass, it will replace the version inherited from the prototype. This is not right, since it violates the derivation invariant. Any attempt to modify the contained object in the prototype will trigger an exception. There are two possible fixes. One is to relax the derivation invariant and allow derived objects to not perfectly mirror the hierarchy of the prototype. Another is for this class to somehow refuse to accept the new object in a subclass. But it is not obvious how to do this. <li> FIXME: If an instance of IterateOverArray in a derived class has overridden values of parameters, those are lost if contained entity of the instance in the base class is replaced and then an undo is requested. </ul> <p><b>References</b> <p><ol> <li> E. A. Lee and T. M. Parks, "Dataflow Process Networks," Proceedings of the IEEE, 83(5): 773-801, May, 1995. <li> H. J. Reekie, "Toward Effective Programming for Parallel Digital Signal Processing," Ph.D. Thesis, University of Technology, Sydney, Sydney, Australia, 1992. </ol>

Author(s): Edward A. Lee, Steve Neuendorffer
Version:$Id: IterateOverArray.doc.html,v 1.1 2006/02/22 18:41:22 mangal Exp $
Pt.Proposed Rating:Yellow (eal)
Pt.Accepted Rating:Red (neuendor)