2.2 Quick Start

This section shows how to start Vergil, how to execute and explore pre-built models, and how to construct your own models.

2.2.1 Starting Vergil

First start Vergil. From the command line, enter "vergil", or select Ptolemy II and Vergil in the Start menu¹, or click on a Web Start link on a web page supporting the web edition. You should see an initial welcome window that looks like the one in figure 2.2. Feel free to explore the links in this window. The "Quick tour" link takes you to the page shown in figure 2.3.

2.2.2 Executing a Pre-Built Model: A Signal Processing Example

The very first example on the quick tour page is the model shown in figure 2.1. It creates a sinusoidal signal, multiplies it by a sinusoidal carrier, adds noise, and then estimates the power spectrum. You can execute this model in either of two ways. First, you can select Run Window in the View menu, and then click on Go. The result is shown in figure 2.4. The upper plot shows the spectrum of the time-domain signal shown in the lower plot. Note the four peaks, which indicate the modulated sinusoid. In the run window you can adjust the frequencies of the signal and the carrier as well as the amount of noise. These can also be adjusted in the block diagram in figure 2.1 by double clicking on the bulleted parameters near the upper right of the window.

The second alternative for running the model is to click on the run button in the toolbar, which is indicated by a red triangle pointing to the right. If you use this alternative, then the two signal plots are displayed in their own windows.

You can study the way the model is constructed in figure 2.1. Note the Expression actor in the middle, whose icon indicates the expression being calculated: "signal*carrier + noise". The identifiers in this expression, signal, carrier, and noise refer to the input ports by name. The names of these ports are shown in the diagram. The Expression actor is a very flexible actor in the Ptolemy II actor library. It can have any number of input ports, with arbitrary names, and uses a rich and expressive expression language to specify the value of the output as a function of the inputs (and parameters of the containing model, if desired).

Three of the actors in figure 2.1 are composite actors, which means that their implementation is itself given as a block diagram. Composite actors are indicated visually by the red outline. You can look inside to reveal the implementation, as shown in figure 2.5, which shows the implementation of the Signal Source in figure 2.1. It is evident from the block diagram how a sinusoidal signal is generated.

2.2.3 Executing a Pre-Built Model: A Continuous-Time Example

A key principle of the Ptolemy II system is that the model of computation that defines the meaning of a block diagram is not built-in, but is rather specified by the director component that is included in the model. The box labeled "SDF Director" in figures 2.1 and 2.5 specifies that these block diagrams have synchronous dataflow semantics, which is explained further below. The second example in the quick tour of figure 2.3, by contrast, has continuous-time semantics (the one labeled "Continuous-Time Modeling"). The example is the well-known Lorenz attractor, a non-linear feedback system that exhibits chaotic behavior.
The Lorenz attractor model, shown in figure 2.6, is a block diagram representation of a set of nonlinear ordinary differential equations. The blocks with integration signs in their icons are integrators. At any given time t, their output is given by

(1) ,

where is the initial state of the integrator, is the start time of the model, and is the input signal. Note that since the output is the integral of the input, then at any given time, the input is the derivative of the output,

(2) .

Thus, the system describes either an integral equation or a differential equation, depending on which of these two forms you use.

Let the output of the top integrator in figure 2.6 be , the output of the middle integrator be , and the output of the bottom integrator be . Then the equations described by figure 2.6 are

(3) .

For each equation, the expression on the right is implemented by an Expression actor, whose icon shows the expression. Each expression refers to parameters (such as lambda for and sigma for ) and input ports of the actor (such as x1 for and x2 for ). The names of the input ports are not shown in the diagram, but if you linger over them with the mouse cursor, the name will pop up in a tooltip. The expression in each Expression actor can be edited by double clicking on the actor, and the parameter values can be edited by double clicking on the parameters, which are shown next to bullets on the right.

The integrators each also have initial values, which you can examine and change by double clicking on the corresponding integrator icon. These define the initial values of , , and , respectively. For this example, all three are set to 1.0.

The Continuous-Time (CT) Solver, shown at the upper left, manages a simulation of the model. It contains a sophisticated ODE solver, and to use it effectively, you will need to understand some of its parameters. The parameters are accessed by double clicking on the solver box, which results in the dialog shown in figure 2.7. The simplest of these parameters are the startTime and the stopTime, which are self-explanatory. They define the region of the time line over which a simulation will execute.

To execute the model, you can click on the run button in the toolbar (with a red triangle icon), or you can open the Run Window in the View menu. In the former case, the model executes, and the results are plotted in their own window, as shown in figure 2.8. What is plotted is vs. for values of t in between startTime and stopTime.

Like the Lorenz model, a typical continuous-time model contains integrators in feedback loops, or more elaborate blocks that realize linear and non-linear dynamical systems given abstract mathematical representations of them (such as Laplace transforms). In the next section, we will explore how to build a model from scratch.

2.2.4 Creating a New Model

Create a new model by selecting File->New->Graph Editor in the welcome window. You should see something like the window shown in figure 2.9. Ignoring the menus and toolbar for a moment, on the left is a palette of objects that can be dragged onto the page on the right. To begin with, the page on the right is blank. Open the Actors library in the palette, and go into the Sources library. Find the Const actor under GenericSources and drag an instance over onto the blank page. Then go into the Sinks library (GenericSinks sublibrary) and drag a Display actor onto the page. Each of these actors can be dragged around on the page. However, we would like to connect one to the other. To do this, drag a connection from the output port on the right of the Const actor to the input port of the Display actor. Lastly, open the Directors library and drag an SDFDirector onto the page. The director gives a meaning (semantics) to the graph, but for now we don't have to be concerned about exactly what that is.

Now you should have something that looks like figure 2.10. The Const actor is going to create our string, and the Display actor is going to print it out for us. We need to take care of one small detail to make it look like figure 2.10: we need to tell the Const actor that we want the string "Hello World". To do this we need to edit one of the parameters of the Const. To do this, either double click on the Const actor icon, or right click² on the Const actor icon and select "Configure". You should see the dialog box in figure 2.11. Enter the string "Hello World" for the value parameter and click the Commit button. Be sure to include the double quotes, so that the expression is interpreted as a string.

You may wish to save your model, using the File menu. File names for Ptolemy II models should end in ".xml" or ".moml" so that Vergil will properly process the file the next time you open that file.

2.2.5 Running the Model

To run the example, go to the View menu and select the Run Window. If you click the "Go" button, you will see a large number of strings in the display at the right. To stop the execution, click the "Stop" button. To see only one string, change the iterations parameter of the SDF Director to 1, which can be done in the run window, or in the graph editor in the same way you edited the parameter of the Const actor before. The run window is shown in figure 2.12.

2.2.6 Making Connections

The model constructed above contained only two actors and one connection between them. If you move either actor (by clicking and dragging), you will see that the connection is routed automatically. We can now explore how to create and manipulate more complicated connections.

First create a model in a new graph editor that includes an SDFDirector, a Ramp actor (found in the Sources) library, a Display actor, and a SequencePlotter actor, found in the Sinks library, as shown in figure 2.13. Suppose we wish to route the output of the Ramp to both the Display and the SequencePlotter. If we simply attempt to make the connections, we get the exception shown in figure 2.14. Don't panic! Exceptions are normal and common. The key information in this exception report is the text:

 
Attempt to link more than one relation to a single port. 
 

The last line gives the names of the objects involved, which in this case are:

 
in .broadcastRelations.Ramp.output and .broadcastRelations.relation2 
 

(This assumes the model has been saved under the name "broadcastRelations.") In Ptolemy II models, all objects have a dotted name. The dots separate elements in the hierarchy. Thus, ".<Unnamed Object>.Ramp.output" is an object named "output" contained by an object named "Ramp", which is contained by an unnamed object (the model itself). The model has no name because we have not assigned one (it acquires a name when we save it).

Why did this exception occur? Ptolemy II supports two distinct flavors of ports, indicated in the diagrams by a filled triangle or an unfilled triangle. The output port of the Ramp actor is a single port, indicated by a filled triangle, which means that it can only support a single connection. The input port of the Display and SequencePlotter actors are multiports, indicated by unfilled triangles, which means that they can support multiple connections. Each connection is treated as a separate channel, which is a path from an output port to an input port (via relations) that can transport a single stream of tokens.

So how do we get the output of the Ramp to the other two actors? We need an explicit relation in the diagram. A relation is represented in the diagram by a black diamond, as shown in figure 2.15. It can be created by either control-clicking on the background or by clicking on the button in the toolbar with the black diamond on it.

Making a connection to a relation can be tricky, since if you just click and drag on the relation, the relation gets selected and moved. To make a connection, hold the control button while clicking and dragging on the relation.³

In the model shown in figure 2.15, the relation is used to broadcast the output from a single port to a number of places. The single port still has only one connection to it, a connection to a relation. Relations can also be used to control the routing of wires in the diagram. However, as of the 4.0 release of Ptolemy II, a connection can only have a single relation on it, so the degree to which routing can be controlled is limited.

To explore multiports, try putting some other signal source in the diagram and connecting it to the SequencePlotter or to the Display. If you explore this fully, you will discover that the SequencePlotter can only accept inputs of type double, or some type that can be losslessly converted to double, such as int. These data type issues are explored next.

¹ Depending on your installation, you could have several versions of Vergil available in the Start menu. This document assumes you select "Vergil - Full." There are separate tutorial documents for "Vergil - HyVisual" (which is specialized for modeling hybrid systems) and "Vergil - VisualSense" (which is specialized for modeling wireless and sensor network systems).

² On a Macintosh, which typically has only one mouse button, instead of right clicking, hold the control key and click the one button.

³ On a Macintosh, hold the command key rather than the control key.