The Map star replaces itself in the graph with as many instances of the replacement block as needed to satisfy all of the inputs to the Map star. Consider the example shown in figure 4-1.

The horizontal slash through the last connection on the right in figure 4-1 is a Bus, which is much like a delay in that the icon is placed directly over the arc without any connections. Its single parameter specifies the number of connections that the single wire represents. Here, the bus width has to be three or the Map star will issue an error message. This is because there are three inputs to the Map star, so three instances of the RaisedCosine star will be created. The three outputs from these three instances need somewhere to go. The result of running this system is shown in figure 4-2

The block diagram in figure 4-1 is equivalent to that in figure 4-3.

In both figures 4-1 and 4-3, the number of instances of the RaisedCosine star is specified graphically. In figure 4-1, it is specified by implication, through the number of instances of the Impulse star. In figure 4-3 it is specified directly. Neither of these really takes advantage of higher-order functions. The block diagram in figure 4-4

The left-most star in figure 4-4 is a variant of the Map star called Src. It has no inputs, and its output data type is specialized to "float" (recall that ports of type "float" in Ptolemy actually communicate data of type "double" in C++). Ptolemy block diagrams are strongly typed, so any star with no inputs must have specific, well-defined types for its outputs (rather than "anytype"). There are variants of the Src higher-order star for all built-in data types in Ptolemy. The complete list of higher-order stars is given below.

Graphical versions of the Map star

Variants of the Map and Src stars, called MapGr and SrcGr, have the following icons:
It is important to realize that MapGr and SrcGr are single icons, each representing a single star. The complicated shape of the icon is intended to be suggestive of its function when it is found in a block diagram. The MapGr and SrcGr stars work just like the Map and Src stars, except that the user specifies the replacement block graphically rather than textually. For example, the system in figure

A variant of the MapGr star has the icon shown below:

A more complex application of the MapGr star is shown in figure 4-6.

Setting parameter values

The value can be any usual Ptolemy expression for giving the value of a parameter. If this expression has spaces in it, however, then the value should appear in quotation marks so that the whole expression is kept together. If the string instance_number appears anywhere in value, it will be replaced with the instance number of the replacement block. Note that it need not be a separate token. For example, the value xxxinstance_numberyyy will become xxx1yyy for the first instance, xxx2yyy for the second, etc. After all appearances of the string instance_number have been replaced, value is evaluated using the usual Ptolemy expression evaluator for initializing String Array states.

For example, in figure 4-1, the Map star has a blockname of RaisedCosine, and a parameter_map of

excessBW = 1.0/instance_number

When the system is run, the Map star will create three instances of RaisedCosine. The first instance will have its excessBW parameter set to 1.0 (which is 1/1), the second instance of RaisedCosine will have a excessBW of 0.5 (1/2), and the third will have a excessBW of 0.33 (1/3). Since the other RaisedCosine parameters are not mentioned in the parameter_map, they are set to their default values.

As a further example, suppose parameter_map of the Map star in figure 4-1 were set to

excessBW(1) 0.6 excessBW(2) 0.5 excessBW(3) 0.4 length 128

The first RaisedCosine would then have an excessBW of 0.6, the second would have an excessBW of 0.5 and the third would have 0.4 for its excessBW. All three of the RaisedCosine stars would have a length of 128 instead of the default length.

Number of replacement blocks

The number of instances of the replacement block is determined by the number of input or output connections that have been made to the Map star. Suppose the Map star has inputs and outputs connected to it. Suppose further that the replacement block has input ports and output ports. Then

is the number of instances that will be created. This must be an integer. Moreover, the number of input and output connections must be compatible (must satisfy the above equality), or you will get an error message like: "too many inputs for the number of outputs."

How the inputs and outputs are connected

The first inputs to the Map star will be connected to the inputs of the first instance of the replacement block. To determine in what order these connections should be made, the names of the inputs to the replacement block should be listed in the input_map parameter in the order in which they should be connected. There should be exactly names in the input_map list. The next inputs to the Map star will be connected to the next replacement block, again using the ordering specified in input_map. Similarly for the outputs. If there are no inputs at all, then the number of instances is determined by the outputs, and vice versa.

Substituting blocks with multiple input or output ports

For example, the Add star has a multiple input port named "input". If we want the replacement Add star(s) to have two inputs each, then input_map should be input input. If we want three inputs in each replacement block, then input_map should be input input input. Note that input_map and output_map are both of the String Array type. Thus one can use the shortcut string input[3] instead of the cumbersome input input input string. These two forms are equivalent as input[3] is converted automatically to input input input when the parameter is initialized by Ptolemy.

A note about data types

There are currently other problems with this mechanism, in that when type resolution is done before the block substitution occurs, there is no information about the substitution block. It is best, therefore, when using the Map star, to make all type conversions explicit. Future versions of Ptolemy may implement type resolution differently, hopefully overcoming these problems. The problems do not occur with the MapGr stars, because these are able to determine the data type of the inputs and outputs from the sample replacement block, which is sure to be present when type resolution is completed.

4.2.2 Managing multidimensional data

A two-dimensional array of data can be embedded in a one-dimensional stream by rasterizing it. This means that the sequence in the stream consists of the first row first, followed by the second row, followed by the third, etc. This is one example of a multiprojection, so called because higher-dimensional data is projected onto a one-dimensional sequence. Typically, however, we wish to perform some operations row-wise, and others column-wise, so the rasterized format can prove inconvenient. Row-wise operations are easy if the data is rasterized, but column-wise operations are awkward. Fortunately, in the SDF domain, we can transpose the data with a cascade of two stars, a Distributor and a Commutator, as shown below:

If the input is row-wise rasterized, then the output will be column-wise rasterized, meaning that the first column will come out first, then the second column, then the third, etc. It has been shown that any transposition of any arbitrary multiprojection can be accomplished with such a cascade [Khi94].

As an example of the use of a multi-projection transformation, consider the two-dimensional FFT shown in figure 4-9.

The effect of a transposition can be accomplished using higher-order functions in a way that is sometimes more intuitive. In particular, a matrix can be represented as a bus, where each connection in the bus carries one row, and the width of the bus is the number of rows. To make this concrete, the same two-dimensional FFT is re-implemented in figure 4-10

These examples are meant to illustrate the richness of possibilities for manipulating data. A more complete discussion of these issues and their application to radar signal processing are given in [Khi94].

4.2.3 Other higher-order control structures

An example of the use of the Chain star is a string of biquad filters in series. The IIR filter star, which can be used to create a biquad filter, has an input named "signalIn" and an output named "signalOut." To have a string of these stars in series, one would want the output of the first IIR star in the series to be connected to the input of the second star. And the output of the second star should be connected to the input of the third, etc. Thus, a Chain star that is a series of biquad filters would have an internal_map of

signalOut signalIn

to specify that the output of one block is connected to the input of the next.

Another variant is the IfElse block. This star is just like Map, except that it has two possible replacement blocks. If the condition parameter is TRUE, then the true_block is used. Otherwise, the false_block is used. It is important to realize that the condition parameter is evaluated at setup time. Once a replacement block has been selected, it cannot be changed. There are two uses for this block. It can be used to parameterize a galaxy in such a way that the parameter determines which of two functions is used within the computation. More interestingly, it can be used to implement statically-evaluated recursion.

4.2.4 Statically evaluated recursion

The IfElse star, however, can conditionally specify one of two replacement blocks. The condition parameter determines which block. One of the two replacement blocks can be a recursive reference to a galaxy as long as the condition parameter is modified. When the condition parameter changes state, going from TRUE to FALSE or FALSE to TRUE, then the choice of replacement block inside the new galaxy instance will change. This can be used to terminate the recursion.

Consider the example shown in figure 4-11.

With log2framesize = 3, after the setup phase, the topology of the galaxy will have become that shown in figure 4-12.

The bit_reverse galaxy performs the sort of data manipulation that is at the heart of the decimation-in-time FFT algorithm. See [Lee94] for an implementation of that algorithm using these same techniques (or see the demos).

4.2.5 Bus manipulation stars

Fortunately, while increasing the demand for busses, higher-order functions also provide a cost effective way to manipulate busses. Like the Map star and its variants, the bus manipulation stars in the HOF domain modify the graph at setup time and then self-destruct. Thus, they can operate in any domain, and they introduce no run-time overhead.

An example of the use of the BusSplit star is shown in figure 4-13.

A more interesting bus manipulation star is the Nop star, so called because it really performs no function at all. It can have any number of inputs, but the number of outputs must be the same as the number of inputs. All it does is connect its inputs to its outputs (at setup time) and the self-destruct. It has many icons, four of which are shown below:

Examples of the uses of Nop stars are shown in figure 4-14.

Recall that many stars in Ptolemy that have multiportholes have multiple icons, each icon configured with a different number of individual ports. This proliferation of icons is no longer necessary, and these icons will disappear from the palettes in future versions of Ptolemy. This will considerably reduce clutter in the Ptolemy palettes.

Copyright © 1990-1997, University of California. All rights reserved.