This assignment does not count toward the final grade.

Getting Started with Ptolemy

  • Due 29 Mar 2022 by 15:00
  • Points 0

For most of the laboratory assignments, you will use the Ptolemy II modeling framework. Once you get access to a Ptolemy installation, you should go through at least one tutorial from their Tutorial page. Our recommendation is that you read and replicate in your environment the tutorial given in "Building Graphical Models" (the first on the page mentioned above).

A. Install the tools on your own machine

Install Ptolemy II on your machine using the instructions from the official website. This is the recommended way of using the Ptolemy II tools since you will not depend on the connection to the university machines.

B. Use the tools remotely on the university machines

The tools we will use in Ptolemy II have a GUI requiring an X11 server. If you have a machine running an X11 server, you can always connect to login.student.lth.se via ssh as below:

ssh -Y [yourlucatid]@login.student.lth.se

This should allow you to run X11 applications on the university machine and have them display the window on your machine (if you have an X11 server running). The tools are located in /usr/local/cs/EDAN15 and to set up your environment you should type in the terminal open with ssh:

source /usr/local/cs/EDAN15/setup

Feel free to examine the contents of that script. You should now be able to run vergil from the command line and have its GUI open on your own machine. (X forwarding via ssh is not very fast, so be patient)

Get an X11 server on...

A Very Short and Incomplete User Guide

1. Starting Vergil

The lab assignments will primarily make use of the GUI available in Ptolemy, located in "Ptolemy/bin/" called Vergil. Starting Vergil should take you to the introductory window from where you can choose to open a file using the File menu. You may of course start a new model by opening the File/New menu, where you will use mainly the Graph Editor and FSM Editor. In general, working with models using the GUI is rather intuitive and similar to other graphical tools. 

2. Saving & Loading a Model

When you want to save your model, use the File/Save or File/SaveAs menus in Vergil. All Ptolemy models are saved in xml format. You can edit them using a text editor but it is safer to let Vergil modify them. To open an existing model use File/Open File menu and select the desired .xml file. Alternatively, you may choose to load your design as a library module. You can do this with Graph/Import Library.

3. Adding & Deleting Modules & Connections

To add new modules (directors, parameters, actors) you may use the library view on the left. Once you locate the desired module, drag and drop it on the modeling workspace (right view).

You may connect ports (the black or white triangles of the actors) by left-click and drag the mouse from the source to the destination port. If you don't drag the connection all the way, it will remain selected. You may then drag the desired endpoint over the destination port.

To delete a component or a group of components, select them (left click or area select) first and press Del. You may also Copy & Paste components by selecting them and using the Edit menu.

4. Configuring Modules

First, if you linger with your mouse pointer over any object in your design (modules, ports, etc.) you will get a pop up with information about that specific object. You can, for example, verify the name of a specific port, or the module type in case you can't figure it out from its name or aspect.

Right-clicking on a module gets you a pop-up menu. You can use this to, among others:

  • Customize:
    • Configure: Modify the parameters for this module.
    • Rename: Change the name that appears above the module.
    • Ports: Edit the ports of the current module.
  • Documentation/Get Documentation: Opens a new window with a specific description for the java class implementation of the current module. (See the "More on Ports" section)
  • Listen to Actor: Opens a window with a runtime trace of the actor. May be useful in debugging.
  • Open Actor: If it's a composite actor, this will open a new design window displaying the inside structure of the actor. If this is a module implemented as a java class, you will get a window containing the java source code for the current module.

Parameters

The Customize/Configure menu lets you modify the parameters for these modules. You can add, delete, change parameters. A parameter value can any valid expression (See the "Using Expressions" section).

Whenever possible it is recommended to use one of the Parameter modules found in the left library view of the design window, under Utilities directory. Just drag and drop it in your design view. This will add a parameter to the module defined by the respective design view. You will be required to give a name and a value for that parameter using the Configure pop-up menu.

Parameters are downwards visible in the module hierarchy. Suppose you have for example the following hierarchy: The top view includes A and B, where A is a composite actor including C and D. If you define a parameter a in module A, this parameter will be visible (can be used in any expression) in A, C, and D but not in B. The parameters, if they are visible, are always accessible only through their name, specified by you.

Top-level parameters can be modified in View/Run Window menu.

5. More on Ports

Ports are the way to send/receive information as tokens. There are several types of ports:

  • Depending on the information transfer direction:
    • input - consumes tokens (an arrow going in)
    • output - produces tokens (an arrow going out)
    • inout - may produce and consume tokens
  • Depending on the number of connections:
    • single - accepts only one connection (black)
    • multiport - accepts an arbitrary number of connections (white)

If you want to connect more than two single ports at one time, you need a relation. A relation is a special entity that takes and replicates the incoming connection (from an output port) to all outgoing connections (to input ports). To form a new relation click the black diamond in the toolbar, or use the Graph/New Relation menu. To connect ports to relations, either drag the mouse pointer from the port to the relation or press Ctrl + drag the mouse pointer from the relation to the desired port.

To add or delete ports to/from a component, right-click on it and select the Customize/Ports from the pop-up menu. You may add ports to the top-level component if you right-click on the background and use that pop-up menu. You may also use the toolbar buttons or the Graph menu to achieve the same result.
Once you selected the Customize/Ports menu, a "Configure Ports for ..." dialog will appear. You may now change the configuration and the types for the existing ports. You may also remove ports or add new ones. If you decide to add a port you will be requested a name and a class for the port. Use the Help button for more information on the port configuration dialog. 

6. Using Expressions

Expressions are very useful in Vergil since they save a lot of time by being compact. In principle, everything you do with expressions can be done using a group of other components, but expressions can make it easier to understand.

You will find the Expression module under Actors/Math in the library view on the left. To specify the exact expression you want to compute, choose Customize/Configure in the pop-up menu and type in the expression parameter. You may use a series of functions (see the online documentation for Expression), any visible parameters, and input ports for the current expression module. If you need to pass runtime information to an expression, add ports for each variable and then use them in the expression. In general, avoid restricting the types of the ports (use "unknown") since they will be resolved at runtime, or as soon as you connect the ports of the expression module.

For more information please refer to PtolemyII_DigitalV1_02.pdf

1648558800 03/29/2022 03:00pm