Top Up Prev Next Bottom Contents Index Search

2.12 Other useful information

In this section we cover additional information which may be useful. More advanced topics will be covered in following chapters.

2.12.1 Plotting signals and Fourier transforms

The Ptolemy menu has a submenu called Utilities that invokes some useful, frequently used, predefined universes. For example, the "plot-signal" ("~") command will plot a signal. The signal can be read from a file or specified using the syntax for specifying the value of a floatarray parameter in pigi. For example, if the value of the signal parameter is:

1 [10] -1 [10]
then the "plot-signal" command will plot ten points with value 1.0 and ten points with value -1.0. The options parameter can accept any options understood by the pxgraph program (see the pxgraph section of the Almagest). To plot a signal stored in a file, simply use the following syntax for the signal parameter:

< filename
You may need to specify the full path name for the file.

Another useful Utilities command is DFT ("^"), which reads a signal just as above and plots the magnitude and phase of the discrete-time Fourier transform of the signal. These are plotted as a function of frequency normalized to the sampling rate, from

to
. The sampling frequency is assumed to be
. A simple phase unwrapping algorithm is used to give more meaningful phase plots. A radix-2 FFT is used, so the order (the number of points) of the fast Fourier transform must be a power of two. That is, the user actually specifies
. The order can be longer than the signal, in which case, zero-padding will occur.

2.12.2 Moving objects

Sometimes you may want to move objects around within your schematic. Use the vem command move-objects ("m") in the Selection menu to do this. You can move objects as follows:

2.12.3 Copying objects

You can create a new instance of any object in a facet by placing a point where you want the new instance, moving the mouse to the object you wish to copy, and executing "create" ("c"). However, this does not copy the parameter values. If you wish to create a new instance of a star or galaxy that has exactly the same parameter values as an existing instance, you should use the copy-objects ("x") command in the vem "Selection" menu. To do this, first select the object or objects you wish to copy. Then place a point in the center of the object. Then place a second point in the location where you would like the new object, and type "x". The new object starts life selected, so you can immediately move it, or type "control-u" to unselect it. As of this writing, vem unfortunately does not allow you to copy objects from one facet to another.

2.12.4 Labeling a design

It is often useful to annotate a block diagram with titles and comments. The vem edit-label ("E") command in the "Edit" menu will do this. It takes two arguments: a point specifying the position of the label, and the name of a layer, which determines the color of the label. Place a point where you would like the label, and then type a layer name, such as "blackSolid" (with the quotation marks). Then type "E". An Athena widget dialog box like that on page 2-14 will appear, offering various options. Type the text for your label in the "Label" box. It can contain carriage returns to get more than one line of text. To select a text height (font size) you can move the slider to the right of the "Text Height" box. The middle button moves the slider by large amounts, and the left and right buttons are used for fine tuning. The initial default is 40, in releases earlier than Ptolemy 0.6, the default was 100, which was too big for all but the loudest titles. Sizes 60 and 40 work well with the overall scaling of Ptolemy facets. You can also change the justification by clicking the left button to the right of each justification box. A pop-up menu lists the options. The colors recommended for labels are:

blackSolid
blueSolid
 
brownSolid
 
greenSolid
 
orangeSolid
 
redSolid
 
violetSolid
 
whiteSolid
 
yellowSolid

2.12.5 Icon orientation

Most Ptolemy icons have inputs coming in from the left and outputs going out to the right. To get better looking diagrams, you may sometimes wish to reorient the icons. This can be done with the vem command "transform" ("t"). Select the icon you wish to transform and type "t" as many times as necessary to get the desired orientation. Each time, you get a 90 degree rotation. Then execute the move-object "m" to commit the change. Notice that a 180 degree rotation results in an upside down icon. To avoid this, reflect the icon rather than rotating it. To reflect it in the vertical direction (exchanging what's on top for what's on the bottom), select the object, type "my" (include the quotation marks), type "t" to transform, and "m" to move. To reflect along the horizontal direction, use "mx" instead of "my". In summary:

To reflect an object horizontally, select it, and type:

"mx" t m
To reflect it vertically, type:

"my" t m

2.12.6 Finding the names of terminals

Some stars have several terminals, each with a different function. The documentation may refer to these terminals only by name. Unfortunately, the name of a terminal is not normally visible when an icon is viewed with normal scaling. However, zooming in will eventually reveal the name. The easiest way to do this is to draw a box around the terminal and open a new window with the "o" command. Then you can zoom in if necessary. Future versions of Ptolemy will hopefully have a better mechanism.

2.12.7 Multiple inputs and outputs

Ptolemy supports star definitions that do not specify how many inputs or outputs there are. The Add and Fork stars are defined this way, for instance. Consider the following two icons, found in the "arithmetic" palette of the SDF domain:

They both represent exactly the same star, as you can verify with the "look-inside" command. The icon on the right, however, has a peculiar double arrow at its input. This is a "multiple input" terminal that allows you to connect any number of signals to it. All the signals will be added. The icon on the left has two ordinary input terminals. It can add only two signals. Why have both kinds?

Sometimes, multiple input terminals are not convenient. A rather technical reason is given below, in the section "Auto-forking" on page 2-48. A more mundane reason is simply that schematics often look better with two-input adders.

There are three ways to work with a star that has a multiple-input or multiple-output connection (technically, a "multiporthole").

First, you can just draw multiple connections to or from the double-arrow porthole icon. This is easy, but it has some limitations. You can't control what order the connections will actually be made in. That doesn't matter for an Add star, but for some star types it's important to know which connection corresponds to which element of the multiporthole. Also, the connected portholes can't be connected to any other stars, nor can you use delay icons, because vem will get confused (see "Auto-forking" on page 2-48).

Second, you can attach a "bus create" or "bus break out" icon to the multiporthole terminal, choosing one that provides the right number of terminals for your schematic. (These icons are available in the "Higher order functions" section of the domain's palette.) This solves both of the problems with multiple connections to a single terminal. It may not make for a very pretty schematic, however.

Third, you can make a custom icon for the star that replaces the double-arrow terminal with the right number of simple terminals. This is what the two-input Add icon actually is.This method takes the most work but may be worth it to make the nicest-looking schematic.

Let's go through an example of how to create a star icon that has multiple input terminals based on an existing Ptolemy star that supports multiple inputs. Suppose you need an icon for an adder with eight inputs. As of this writing, unfortunately, you need to have write permission in the directory in which Ptolemy icons are stored to create this new icon. Alternatively, you can create your own version of the star in your own directory (see the programmer's manual). If you have write permission in the directory where the icons are stored, then you can create a new icon with eight inputs as follows.

In any facet, execute the pigi command "Extend:make-star" ("*"). A dialog box appears. Enter "Add.input=8" for the star name, "SDF" for the domain, and "$PTOLEMY/src/domains/sdf/stars" for the star src directory (assuming this is where the source code is stored). Note that "input" is the name of the particular multiple input that we want to specify. If you do not know where the source code is stored, then just look-inside ("i") an existing instance of the star. The vem console window and the header of the editing window that open both tell where the star source code is. A second dialog box appears asking you where you would like the icon put. Accept the default, "./user.pal". Then open user.pal using "O" to see the new eight-input adder icon. You may edit this icon, as explained in "Editing Icons" on page 2-34.

2.12.8 Using delays

In several domains, delays can be placed on arcs. A delay is not a star, but rather is a property of the arc connecting two stars. The interpretation of the delay in the dataflow domains (SDF, DDF, BDF, and most code generation domains) is as an initial particle on the arc. An initial particle for the scalar data types is one whose value is zero. When the arc passes particles containing "message" type data, a delay on the arc will create an "empty" message. Most often, the destination star of the arc must be able to interpret such "empty" messages explicitly in context of the user-defined type because a "zero" might have different meanings depending on the type. Any feedback loop in the SDF domain must have a delay, or the computation in the loop would not be able to begin.

To use these delays in pigi, the user places a delay icon on top of the wire connecting two instances. The delay icon is a white diamond with a green border in the SDF and system palettes. You can specify the number of delays by executing edit-params with the cursor on top of the delay icon.

Other domains (besides dataflow) also use delays, but the meaning can be quite different. See the appropriate chapter describing the domain.

A new feature added to Ptolemy releases greater than 0.5 is the support of initializable delays for simulation domains. These delays use a different icon from the old white diamond with green borders. The new delays use an icon that is a green diamond with a white border and has an "I" in the middle of the diamond to signify that it is initializable. We have kept around the old delays for backward compatibility, but the syntax for the two is quite different and the user should probably use just one type to prevent confusion.

The syntax for the new delays is that the arguments to the delay are the initial value themselves. There is no value in the argument that signifies the number of delay particles. Instead, a count of the number of values in the delay arguments is the number of delay particles that will be added to the buffer of the arc corresponding to the delay. These arguments are specified as a string and are parsed according to the data type associated to the arc. For example, an initializable delay with parameter "1 0 1" on an arc passing float particles will have a buffer with three initial particles. The three particles will have the values 1.0, 0.0, and 1.0 respectively. If the arc was working on complex particles instead, an error would be given since complex numbers must be specified using a pair of numbers. A proper argument list for the delay in that case would be "(1,0) (0,0) (1,1)". The shorthand for declaring multiple values in the argument list is valid, just as in the arraystate case. For example, an argument list of "2 [5]" would specify five initial particles with value 2.

Initializable delays also work on arcs which handle matrix particles. The argument string in this case is parsed differently than above. The first two values in the last specify the number of rows and columns in the initial matrix, respectively. For example, an initializable delay with parameter "1 2 3 [2]" on an arc passing integer matrices would place one matrix with dimension one row by two columns, whose entries all have the value three, in the buffer for that arc. For the case where multiple initial matrices are desired, simply give enough entries in the delay argument string to fill multiple numbers of initial matrices of the given size. For example, an initializable delay with parameter "1 2 3 3 4 4 5 5" on an arc passing integer matrices would create three matrices, all of dimension one row by two columns, such that the first initial matrix on the buffer has all entries equal to three, the second has all entries equal to four, and the last matrix has all entries equal to five.

2.12.9 Auto-forking

In pigi, a single output can be connected to any number of inputs, as one would expect. The interpretation in most domains is that the one output is broadcast to all the inputs. There are several point-to-point connections, therefore, represented by the net.

However, there are restrictions. To understand these restrictions, it is worth explaining that vem stores connectivity information in the form of netlists, simply listing all terminals that are connected together. If a delay appears somewhere on a net, and that net has more than one point-to-point connection, then it is not easy to determine for which connection(s) the delay is intended. Consequently, at the time of this writing, delays are disallowed on nets with more than one connection. If you attempt to put a delay on such a net, then when you try to run the system, an error message will be issued, and the offending net will be highlighted. To get rid of the highlighting, execute the pigi command "Edit:clear-marks". To fix the problem, delete the offending net, and replace it with one or more fork stars and a set of point-to-point connections. An incorrect and correct example are shown below:

This example also illustrates the use of a delay on a feedback loop. The delay is required here, assuming we are in the SDF domain, because without it, deadlock would ensue. This is due to the fact that the fork star cannot fire until the add star does, but the add star cannot fire until the fork star produces its output.

A second restriction is that forks must be explicit when connected directly to input or output terminals of a galaxy. An incorrect and correct example are shown below:

There is also a more subtle restriction. Suppose two outputs are connected to a single multiple-input terminal. Then neither of these outputs can also be connected to some other input terminal. If they are, Ptolemy will issue the error message "multiple output ports found on the same node." The reason this happens is simple. Vem knows nothing about multiple inputs, so it sees a net with more than one output and more than one input. Ptolemy is not given enough information to reconcile this and figure out which outputs should be connected to which inputs. To avoid this problem, it is again necessary to use explicit fork stars, as shown below:

Another solution, which may look nicer than inserting an explicit fork star, is to replace the multiple-input terminal with several simple terminals. You can do that by inserting a "bus create" icon or by using a different icon for the multiple-input star, as was explained in "Multiple inputs and outputs" on page 2-46.

All of the above restrictions may be eliminated in future versions.

2.12.10 Dealing with errors

Ptolemy is composed of several components, as shown in figure 2-6 on page 2-22. When errors occur, it helps to know which component detected the error so that it can be corrected.

When errors occur in vem, vem prints the error in the console window. For example, if you enter a point argument and execute create when the cursor is not over an instance, then vem displays the message "Can't find any instance under spot." Usually, vem errors are easy to fix. In this case, vem expects the user to specify the instance to be created.

Errors in the pigiRpc process can occur when any of the pigi commands are invoked. The error messages, in this case, are displayed in a popup window, which is much more helpful. Error messages may also be displayed in the xterm window in which pigi was started. In addition, pigi often highlights in red the object in the schematic associated with the error. When this happens, you can execute the clear-marks command to clear the highlighting. If such an error occurs and the reason for the error is not obvious, try deleting the indicated objects and redrawing them.

2.12.11 Copying and moving designs

In one of our examples, we used cp -r to make a copy of a facet. In general, however, copying entire designs this way does not work. For it to work in the general case, you must also change some data in the facets that you copy. In particular, each facet has pointers to the icons it uses. If you move a galaxy, for example, then any pointer to the icon for that galaxy becomes invalid (or "inconsistent" in oct terminology).

A utility program called masters has been provided for this purpose. This replaces the program from the octtools distribution, called octmvlib, that was used with earlier versions of Ptolemy.

Palettes, star icons, galaxies, and universes are stored as oct facets. Special care is required when moving or copying oct facets. First, as emphasized before, every oct facet is stored as a directory tree, so a copy should use cp -r. Next, keep in mind that there may be pointers to the moved object in other facets. If you know where all these pointers might be, then moving facets is easy. If you do not know where all the pointers are, then your only practical choice is to leave a symbolic link in place of the old location pointing to the new.

Moving facets

Suppose you have developed a fantastic new galaxy called alphaCentaur, and you wish to install it in a directory that is available for general use. Since you have developed the galaxy, you know where it is used. The galaxy icon itself is stored in two facets:

	alphaCentaur/schematic/contents; 
	alphaCentaur/schematic/interface;
 The first of these stores the schematic, the second stores the icon. The peculiar semicolon at the end is actually part of the file name. First move the icon:

	mv alphaCentaur destinationDirectory
This moves the entire directory tree. You must now change all references to the icon so that they reflect the new location. Suppose you have a test universe called alphaTest. This should be modified by running the masters program as follows:

% masters alphaTest 
Running masters on wave 
Pathname to replace (? for a listing):
 User input is shown in bold type; program output is shown in regular (not bold) type. Enter a question mark to get a list of all icons referenced in the facet:

Pathname to replace (? for a listing): ? 
Pathnames currently found in the facet: 
	~yourname/oldDirectory/alphaCentaur 
	$PTOLEMY/src/domains/sdf/icons/Ramp 
	$PTOLEMY/src/domains/sdf/icons/Sin 
	$PTOLEMY/src/domains/sdf/icons/XMgraph 
Pathname to replace (? for help):
 The last three items are pointers to official Ptolemy icons. There is no need to change these. You should now enter the string you need to replace and the replacement value:

Pathname to replace (? for help): ~yourname/oldDirectory 
New pathname: ~yourname/destinationDirectory
 Next, use masters the same way to modify any palettes that reference the moved icon. For instance, the "user.pal" palette in the directory in which you developed AlphaCentaur is a likely candidate. If you miss a reference, oct will issue an error message when it tries to open the offending palette, indicating that it is inconsistent.

2.12.12 Environment variables

The following environment variables can be set to customize certain behavior. These should be set (normally) in the user's .cshrc file.

PIGIBW
This variable tells Ptolemy to display all of its windows in black and white.
PIGIRPC
Specifies an alternative executable file for Ptolemy. Ptolemy is an extensible, modifiable system. Many users will wish to create their own versions to incorporate their own extensions. Details on how to write extensions are given in the programmer's manual, volume 3 of the Almagest. Once you (or someone else) has created a customized version, you can invoke it by specifying the precise name of the executable (complete with its full path, or path relative to an environment variable or user's name). The default executable is $PTOLEMY/bin.$PTARCH/pigiRpc. An alternative specification might be: 
		setenv PIGIRPC ~myname/Ptolemy/bin.sol2.5/pigiRpc
PT_DISPLAY
Determines the text editor used to display text files. This determines how text files will be displayed to the user. The value of this variable is a printf format string with one %s in it. That %s is replaced with the name of the file to be viewed. In the default, the PT_DISPLAY variable is not set, and the Tycho editor is used.For example, to view files in a new xterm window with the vi editor, put the following line in your .cshrc file 
		setenv PT_DISPLAY "xterm -e vi %s"
and source the file before starting pigi.
PTARCH
This variable specifies the computer architecture you are using such as sol2.5. The architecture setting is returned by the $PTOLEMY/bin/ptarch script.
PT_DEBUG
If set, this specifies the script to execute when starting pigi in debug mode (using the -debug option). An example of a suitable script is ptgdb, located in $PTOLEMY/bin. This script invokes gdb, the Gnu debugger, inside emacs.
PTOLEMY
This variable points to the root directory of where Ptolemy is installed.
PTPWD
This variable gives the command to print the current working directory, which is usually pwd.
TYCHO
This variable points to the root directory of where Tycho is installed. Ptolemy is based on Tcl and [incr Tcl]. These packages set the following environment variables: TCL_LIBRARY, TK_LIBRARY, ITCL_LIBRARY, ITK_LIBRARY, and IWIDGETS_LIBRARY. See $PTOLEMY/bin/ptsetup.csh.

Below we discuss a few Unix system environment variables that affect how Ptolemy functions.

DISPLAY
Specifies what X11 Display Ptolemy should start up on. If you are unfamiliar with $DISPLAY, then see
GCC_EXEC_PREFIX
C_INCLUDE_PATH
CPLUS_INCLUDE_PATH
LIBRARY_PATH

These variables are used by the Gnu compilers to find components of the compilers, see
HOME
This variable points to the root directory of the user's account. This variable must be set for itclsh and the software that uses itclsh (ptcl and tycho) to work properly.
LD_LIBRARY_PATH

This variable is used by the run time linker to find shared libraries. If you are using prebuilt binaries, and your Ptolemy installation is not at
/users/ptolemy, then you may need to set this variable, see
PATH
This variable contains a list of directories of executable programs. The order of the directories listed is very important. See $PTOLEMY/.cshrc for guidelines on the proper order.
PRINTER
Determines the default printer used for hardcopy output. This is used to determine the default printer when printing vem facets. If you use the provided makefile to print Ptolemy documentation, then this environment variable will determine the printer used. In $PTOLEMY/.cshrc the pertinent line reads: 
		setenv PRINTER lw
You should replace lw with whatever printer name you are using.
SHLIB_PATH
Hewlett-Packard systems use SHLIB_PATH instead of LD_LIBRARY_PATH to find shared libraries. See the LD_LIBRARY_PATH description above for details.
USER
This variable gives the name of the user running Ptolemy. This variable is set by every shell. In your .cshrc file, add the following line: 
		if (! $?USER) setenv USER $LOGNAME
 Many of Ptolemy's domains rely on additional environment variables. The CG56 domain relies on S56DSP to indicate the path name where the tools for the S56X Motorola 56000 board are installed and QCKMON to indicate the path name where the QCK Monitor tools are installed. The VHDL domain relies on SYNOPSYS to indicate the root directory for the installation of Synopsys tools and SIM_ARCH to be set to the computer architecture you are using for the Synopsys tools.

2.12.13 Command-line options

The pigi program is actually a csh script, located in $PTOLEMY/bin. That script starts two processes: vem and pigiRpc. The usage is

pigi [options] [facet-name]
The optional facet name specifies a vem facet that should be opened upon starting the system. The command-line options are:

-bw
Use black and white, even on a color monitor. This is useful for generating readable hardcopy from X Window dumps.
-cp
Fine tune the colors to improve the quality of hardcopy made on a color printer from X Window dumps.
-debug Invoke Ptolemy running under gdb, a symbolic debugger. If a version of the pigiRpc executable with debug symbols can be found, the script will it. If $PIGIRPC is set then that binary is used. If $PIGIRPC is not set, then the program first looks for
$PTOLEMY/bin.$PTARCH/pigiRpc.debug
If that is not found, then the program looks for
$PTOLEMY/obj.$PTARCH/pigiRpc/pigiRpc.debug
If that is not found, then
Invoke Ptolemy running under gdb, a symbolic debugger. If a version of the pigiRpc executable with debug symbols can be found, the script will it. If $PIGIRPC is set then that binary is used. If $PIGIRPC is not set, then the program first looks for
$PTOLEMY/bin.$PTARCH/pigiRpc.debug
If that is not found, then the program looks for
$PTOLEMY/obj.$PTARCH/pigiRpc/pigiRpc.debug
If that is not found, then
$PTOLEMY/bin.$PTARCH/pigiRpc
is used. If the PT_DEBUG environment variable is set, then its value is the name of a script used to invoke the debugger. For example, the script ptgdb, located in $PTOLEMY/bin, invokes gdb under emacs.
-ptiny
Invoke the smallest version of Ptolemy, if it can be found. The executable that is used is called pigiRpc.ptiny. This version contains only the SDF and DE domains, but without the image processing stars and the user-contributed stars.
-ptrim
Invoke an intermediate-sized version of Ptolemy, if it can be found. The executable used is called pigiRpc.ptrim. This version contains only SDF, BDF, DDF, DE, and CGC domains, but without the parallel targets.
-help
print out the usage information

Top Up Prev Next Bottom Contents Index Search

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