2.4 Hierarchy

Ptolemy II supports (and encourages) hierarchical models. These are models that contain components that are themselves models. Such components are called composite actors. Consider a small signal processing problem, where we are interested in recovering a signal based only on noisy measurements of it. We will create a composite actor modeling a communication channel that adds noise, and then use that actor in a model.

2.4.1 Creating a Composite Actor

First open a new graph editor and drag in a CompositeActor from the Utilities library. This actor is going to add noise to our measurements. First, using the context menu (obtained by right clicking¹ over the composite actor), select "Customize Name", and give the composite a better name, like "Channel", as shown in figure 2.20. Then, using the context menu again, select "Look Inside" on the actor. You should get a blank graph editor, as shown in figure 2.21. The original graph editor is still open. To see it, move the new graph editor window by dragging the title bar of the window.

2.4.2 Adding Ports to a Composite Actor

First we have to add some ports to the composite actor. There are several ways to do this, but clicking on the port buttons in the toolbar is probably the easiest. You can explore the ports in the toolbar by lingering with the mouse over each button in the toolbar. A tool tip pops up that explains the button. The buttons are summarized in figure 2.22. Create an input port and an output port and rename them input and output by right clicking on the ports and selecting "Customize Name". Note that, as shown in figure 2.23, you can also right click² on the background of the composite actor and select Configure Ports to change whether a port is an input, an output, or a multiport. The resulting dialog also allows you to set the type of the port, although much of the time you will not need to do this, since the type inference mechanism in Ptolemy II will figure it out from the connections. You can also specify the direction of a port (where it appears on the icon; by default inputs appear on the left, outputs on the right, and ports that are both inputs and outputs appear on the bottom of the icon). You can also control whether the name of the port is shown outside the icon (by default it is not), and even whether the port is shown at all. The "Units" column will be discussed further below.

Then using these ports, create the diagram shown in figure 2.24³. The Gaussian actor creates values from a Gaussian distributed random variable, and is found in the Random library. Now if you close this editor and return to the previous one, you should be able to easily create the model shown in figure 2.25. The Sinewave actor is listed under sources, and the SequencePlotter actor is found in sinks. Notice that the Sinewave actor is also a hierarchical model, as suggested by its red outline (try looking inside). If you execute this model (you will probably want to set the iterations to something reasonable, like 100), you should see something like figure 2.26.

2.4.3 Setting the Types of Ports

In the above example, we never needed to define the types of any ports. The types were inferred from the connections. Indeed, this is usually the case in Ptolemy II, but occasionally, you will need to set the types of the ports. Notice in figure 2.23 that there is a column in the dialog box that configures ports for specifying the type. Thus, to specify that a port has type boolean, you could enter boolean into the dialog box. There are other commonly used types: complex, double, fixedpoint, general, int, long, matrix, object, scalar, string, and unknown. Let's take a more complicated case. How would you specify that the type of a port is a double matrix? Easy:

 
[double] 
 

This expression actually creates a 1 by 1 matrix containing a double (the value of which is irrelevant). It thus serves as a prototype to specify a double matrix type. Similarly, we can specify an array of complex numbers as

 
{complex} 
 

In the Ptolemy II expression language, square braces are used for matrices, and curly braces are used for arrays. What about a record containing a string named "name" and an integer named "address"? Easy:

 
{name=string, address=int} 
 

¹ On a Macintosh, control-click.

² On a Macintosh, control-click.

³ Hint: to create a connection starting on one of the external ports, hold down the control key when dragging, or on a Macintosh, the command key.