This text is generated from the users_man/installation.ps file
This file is a subset of INSTALL_0.5

A.4  Troubleshooting

This section lists common difficulties encountered when Ptolemy 
is installed or run. This list is, of course, by no means 
complete. If you do not find your particular problem here, refer 
to "Additional Resources" section below.


A.4.1  pigi fails to start when put in the background

A common problem occurs when pigi is started in the background 
and the user has the line
stty tostop
in their .login or .cshrc file. This command configures the 
terminal to halt any process that is running in the background 
when it tries to write to the terminal. One possible fix is to 
run pigi in the foreground. Another possible fix is to eliminate 
this command from your .login file.


A.4.2  pigi fails to start with a message about not finding fonts

The default fonts for vem are specified in the file 
$PTOLEMY/lib/pigiXRes9, and also pigiXRes9.bw and pigiXRes9.cp. 
These files define a set of X window resources. The pigiXRes9.bw 
file is used if pigi is started with the -bw option. The 
.pigiXRes9.cp file is used in pigi is started with the -cp 
option. The definitions in these files can be overridden by the 
user. For example, a user who prefers to use microscopic fonts 
could set the X resource as follows:

Vem*font:               *-times-medium-r-normal--*-120-*
If, however, the fonts defined in these files on not available 
on the system, then the Ptolemy installer should change them in 
the files $PTOLEMY/lib/pigiXRes9*.

The fonts for tk (and hence, the fonts for most of the dialog 
boxes) are specified in $PTOLEMY/lib/tcl/ptkOptions.tcl. These 
may similarly require changing at some sites. In the worst case, 
if many standard fonts are not available, it may be necessary to 
redefine the default fonts built into the tk source code, and 
recompile tk.


A.4.3  pxgraph fails to come up or displays a blank window

If the pxgraph program is given exceptional numbers, such as the 
IEEE floating-point Inf, -Inf, or NaN ("not a number"), then it 
will issue a cryptic error message "problems with input data" 
and will fail to display a plot. The stars that use pxgraph are 
supposed to intercept this and pop up an error message in a 
window. However, on some platforms, as of this writing, this 
does not work. On such platforms, the error message, 
unfortunately, goes to the standard output, which may be buried 
several layers deep in your windowing system. It is also 
possible for the standard output to be lost, so that no error 
message appears. Thus, if you get such a pxgraph failure, look 
for instabilities in your Ptolemy schematic that would cause it 
to produce such exceptional numbers.


A.4.4  Old flowgraphs do not work (facets are inconsistent)

A pigi schematic contains references to icons. These icons are 
referenced by their location in the file system, typically using 
either an absolute path, a path relative to user's home 
directory, or a path relative to the environment variable 
PTOLEMY. If the master for any of these icons is not in the 
expected place, vem will issue a warning, telling you that the 
facet is inconsistent. In place of the icon in the schematic 
there will be blank space. To find out what icon masters are 
missing, run the program masters. Instructions for doing this 
are given in "Copying and moving designs" on page 2-43. Invalid 
masters will be labeled "INVALID". You must replace the invalid 
reference with a reference to a valid master.

One typical scenario for users upgrading from version 0.4.1 of 
Ptolemy to version 0.5 is that they will have references to 
masters in the directory tree ~ptolemy. But Ptolemy 0.5 may be 
installed somewhere else. One solution is to use the masters 
program to replace "~ptolemy" with "$PTOLEMY".

If you have flowgraphs dating back to the 0.3.1 version, you 
will encounter some significant incompatibilities. In 
particular, several stars that were included in the 0.3.1 
release of Ptolemy have been renamed. The objective was to adopt 
a consistent naming policy across all domains. One major benefit 
of this is the ability to migrate universes and galaxies from 
one domain to another. A consequence, however, is that some of 
your universes and galaxies will have inconsistencies (they will 
point to icons that no longer exist in the current release). 
Please see the file "$PTOLEMY/lib/rename/README." This file 
explains how to upgrade your universes and galaxies to the 
current release.


A.4.5  Error: ld.so: libXext.so.4: not found

You have not installed the shared library needed by Ptolemy when 
it is used under Open Windows. See the "Open Windows" section in 
the installation guide.


A.4.6  Problems starting up clients such as xedit under Open 
Windows

Use the PT_DISPLAY variable to use a different editor. See the 
"Environment Variables" section in the Interactive Graphical 
Interface chapter of the User's Manual.


A.4.7  Problems with the colormap

Some applications, for example FrameMaker 4.0, allocate as many 
colors as they can from the colormap when they start up. This 
may force applications that are started later (such as pigi) to 
use a very restricted set of colors. When you start pigi, if the 
welcome window appears in black and white, then you may have 
such a situation. If the situation is worse, and there are not 
enough colors in the colormap for vem to start, then you may not 
even get this far. One solution is simply to exit the offending 
application (e.g. FrameMaker), and start pigi over. A better 
solution is to configure the offending application to use fewer 
slots in the colormap. We have found that for FrameMaker 4.0, 
the following X resources (placed in your .Xdefaults file) 
usually solve the problem:

Maker.targetExactColors: 2
Maker.minimumExactColors: 0
Maker.targetColorCube: 4
Maker.minimumColorCube: 1
This still leaves FrameMaker with a very rich set of colors to 
use. You may need to replace the 2 or 4 with smaller numbers if 
you have other color-intensive applications running (such as 
root window pictures of beaches in Tahiti).


A.4.8  Ptolemy simulation runs do not stop

In the SDF domain, particularly, it is possible to have 
multirate systems where a single iteration is very large number 
of firings of stars. This happens when the number of samples 
produced or consumed by various connected stars in the system 
are mutually prime, or they have very large least common 
multiples. If a simulation is taking an unreasonable amount of 
time, then look for such mutually prime numbers. Sometimes, in 
such circumstances, it can take a long time for the simulation 
to respond to pushing the "stop" button. It should, however, 
eventually respond.


A.4.9  Generated code in CGC fails to compile

The targets in CGC are configured by default with reasonable 
guesses about the compile and link options that are required to 
compile the code. However, the actual options required depend on 
your system configuration. For instance, your default cc 
compiler may not have been configured to automatically find the 
X11 include files. You might, therefore, get an error message 
the Xlib.h cannot be found. You should find out where on your 
system Xlib.h is installed, and add a compile option of the form 
"-Lpath_name" where path_name is the full path of the directory 
containing the file. Alternatively, you can create a symbolic 
link from /usr/include to the directory (you must have root 
permission to do this).

Certain compiles will change their behavior depending on the 
values of certain environment variables:
        The hppa cc compiler will use the CCOPTS environment 
variable. If your X11 libraries were at /usr/sww/X11R5/lib, then 
one could exit pigi, set the variable

setenv CCOPTS -L/usr/sww/X11R5/lib
and restart pigi. Then when you compile CGC demos with hppa cc, 
you should be able to find the proper libraries. See the hppa cc 
man page for more information.

        GNU gcc will also use certain environment variables. The 
LIBRARY_PATH variable may help:
setenv LIBRARY_PATH /usr/sww/X11R5/lib
See the gcc documentation for more information.

A.4.10  Ptolemy won't recompile

You may be using a substantially different version of the Gnu 
compiler. The system is most likely to build if you use the same 
tools that we used originally. The Gnu tools we used are 
supplied with the Ptolemy distribution.


A.4.11  Missing symbols while linking pigiRpc

On the sun4 with libg++-2.5.2, if you compile pigiRpc with the 
g++ -O option, then you may have missing symbols while linking 
pigiRpc. The workaround is to upgrade to libg++-2.5.3. We 
shipped libg++-2.5.2 with the 0.5beta, but we are shipping 
libg++-2.5.3 with the final 0.5 release.


A.4.12  Error involving xedit

The program xedit is a program provided with Ptolemy to display 
files on your screen during a Ptolemy run. If there is some 
problem with xedit that you cannot solve, or you do not like 
xedit, it is possible to change the display program used by 
Ptolemy. To do this, you need to set the PT_DISPLAY environment 
variable before you run pigi. For example, to use PT_DISPLAY to 
view files in a new xterm window with the vi editor, do

setenv PT_DISPLAY "xterm -e vi %s"
The value of the PT_DISPLAY variable is a printf format string 
with one %s in it. That %s is replaced with the file to be 
viewed, for look-inside commands and to view generated code. The 
default value is "xedit %s".


A.4.13  Emacs confuses .pl files with Prolog

The .pl extension used to define Ptolemy stars is the same 
extension used for the Prolog language. Some text editors, such 
as emacs, have special modes for editing Prolog files. These 
modes are inappropriate for editing Ptolemy files. You can 
create the following line your .emacs file in your home 
directory:

(setq auto-mode-alist (cons '("\\.pl$" . c++-mode) 
auto-mode-alist))

A.4.14  The window manager crashes

The window manager twm sometimes crashes when you are running 
Ptolemy. We do not know why. Our solution is to simply restart 
it. You may wish to make sure your configuration does not log 
you out when the window manager exits.


A.4.15  Path and/or Environment Variables not set in "debug" pigi

When running Ptolemy's interactive graphical interface with the 
debug option:
pigi -debug
The path is not set correctly, or environment variables are not 
at their normal values. This is caused by the Gnu debugger, GDB, 
overwriting values set by the pigi start-up script. From the GDB 
manual:

*Warning:* GDB runs your program using the shell indicated by 
your `SHELL' environment variable if it exists (or `/bin/sh' if 
not). If your `SHELL' variable names a shell that runs an 
initialization file--such as `.cshrc' for C-shell, or `.bashrc' 
for BASH--any variables you set in that file affect your 
program. You may wish to move setting of environment variables 
to files that are only run when you sign on, such as `.login' or 
`.profile'.

If your .cshrc file specifies a value for a variable, it will 
override anything in the pigi start-up script. If this is the 
case, perhaps setting SHELL to /bin/sh before firing off the 
debugger will fix the problem.


A.4.16  CGC demos won't run

If . (dot, the current working directory) is not in your path, 
then when you run the CGC demos you may see:
sh: butterfly: not found
The workaround is to exit pigi, place . in your path, and 
restart pigi. For security reasons, placing . in your path after 
all of your other directories is best:

set path = ($path .)

A.4.17  EOF messages while using tar on Suns

There is a bug in the SunOS4.1.3 version of /bin/tar. Sometimes 
a command such as:
zcat atarfile.tar.Z | /bin/tar -xf -
may produce error message such as:
tar: read error: unexpected EOF
when reading from a pipe. One workaround is to use GNU tar, 
another is to uncompress the tar file, and then use /bin/tar on 
the uncompressed file:

uncompress atarfile.tar.Z; /bin/tar -xf atarfile.tar

A.4.18  Dynamic Linking fails

Ptolemy has the ability to load stars dynamically during run 
time. The stars are compiled into .o files and loaded with the 
Unix loader. Dynamic linking is tricky and dependent on the Unix 
loader. There are several reasons dynamic linking can fail:

        Dynamic linking is not currently supported on the hppa 
and hppa.cfront platforms. We are working towards fixing this in 
a later release.

        If you are upgrading from an earlier release, including 
Ptolemy-0.5beta, be sure to remove all the .o files in the 
directory where the source files for you star is.

        If you are using prebuilt Ptolemy binaries, be sure that 
you are using the prebuilt Gnu compiler that is also available 
with the Ptolemy binaries. The alternative is to rebuild Ptolemy 
with your local Gnu compiler, but be aware that versions earlier 
than gcc-2.5.6 and libg++-2.5.3 have bugs. gcc-2.4.x and 
libg++-2.4.x and earlier are know to have serious bugs, so you 
may want to upgrade. For more information, see the Gnu 
Installation section in this Installation document.

        If you are using prebuilt Ptolemy binaries and have the 
prebuilt Gnu compiler, be sure that either the Ptolemy 
distribution is available as /users/ptolemy, or you are setting 
the Gnu environment variables in $PTOLEMY/bin/g++-setup. Again, 
see the Gnu Installation section.

        If, at linktime, you see messages about undefined 
symbols, and the undefined symbols begin with _vt, then you 
probably have compiler version incompatibilities. Note that you 
can find out what files have the undefined symbols by using the 
Unix nm command.

        Dynamic linking may not work on machines that have a 
different release of the OS. In particular, we found that 
dynamic linking with the prebuilt binaries failed on mips 
running Ultrix4.3 if our mips prebuilt binaries were created 
under Ultrix4.3A. The workaround is to relink Ptolemy on the 
local machine.

        If you are having problems compiling the star from 
Ptolemy, try running the compile by hand from the shell. 
Unfortunately, part of the compile command is not always visible 
in the vem window. To see the all of the compile command, try 
running a few vem commands, such as `i' (look-inside) to flush 
the vem buffer. Once you have produced a .o file, you can load 
the .o file into Ptolemy with the load-star command.


A.4.19  The DE stars "And" and "Or" no longer work

These stars have been replaced by the Logic star. Use this new 
star instead.

A.4.20  Multi-porthole Galaxies Fail

If a galaxy contains a multi-porthole input or output, and the 
icon of the galaxy is named Foo.input=2, Foo.output=2, etc., the 
galaxy will fail to compile. This is because Ptolemy behaves as 
if anything ending in input=X or output=X must be a star. Avoid 
using names like "Foo.input=3" for galaxies.


A.5  Known Bugs

There are a number of known bugs that we have not had a chance 
to fix.

A.5.1  Bugs in Vem

        When graphical animation is turned on and a simulation 
is running, if you execute the "look-inside" command, vem 
terminates the pigiRpc application.

        Labels that end with a carriage return are neither 
displayed nor printed correctly.
        Editing icons stimulates a memory leak in vem that can 
make the process grow quite big. After editing a few dozen 
icons, you may wish to exit vem and restart.

        When you edit a label, a dialog box frequently appears 
with the message "ambiguous layer" and a checklist of colors. 
Check and color and continue. The choice of color has no effect.

        The "layer" command only works when editing icons, not 
when editing schematics.
        The "copy-objects" command will copy from one window to 
another only when editing icons, not when editing schematics.

        If you obtain the other.src tar files and attempt to 
build vem from scratch, do not use gcc, use cc instead. Vem 
binaries built with gcc may fail to start up, or may crash later 
with memory errors.


A.5.2  Bugs in pigi

        The "run-all-demos" command does not always work. In 
particular, it fails on most Tcl/Tk demos, because these assume 
that a run control panel is present, but the run-all-demos 
command does not open a control panel. Also, some demos 
deliberately trigger an error, in order to demonstrate some 
failure modes in the domain. The run-all-demos command quits 
when it encounters such an error.

        It is possible to make more than one icon to represent a 
given star. For instance, the icon And and And.input=2 refer to 
the same star, but the former can have any number of inputs, 
while the latter has exactly two inputs. As of this writing, 
this facility does not work for galaxies. You should create only 
one icon for each galaxy.

        Simulations that run for a very long time may not 
respond quickly enough to pushing the stop button in the control 
panel.

        If you try to run the CGC demos that generate sound, and 
you do not have a properly configured audio device, or you do 
not have write permission to /dev/audio, then you get a cryptic 
and uninformative error message, rather than something useful.

        The CGC Multi-processor demos have Berkeley machine 
names hardwired into them. These demos probably won't work at 
other sites unless the machine names are changed.

        The CGC tcltk BallAsync demo fails on the mips platform. 
We believe that this is due to interactions between tcltk and 
the select() function. This bug only affects demos which use the 
sleep star on the mips platforms.

        The sim-CG96 target was not compiled into the release. 
Thus, the only CG96 target available is the default-CG96 target. 
Unfortunately, the demos use the sim-CG96 specific IO stars, so 
they cannot be run with the default target. To use the sim-CG96 
target, add the line below to the file $PTOLEMY/mk/stars.mk and 
rebuild pigi.

CG96TARGETS =   $(CG96T)/Sim96Target.o

A.5.3  Bugs in pxgraph

        If pxgraph is given only one point to plot, nothing 
appears in the plot window.
        If pxgraph is given exceptional numeric input, such as 
the IEEE floating point Inf,
-Inf, or NaN, then it displays a blank window only.
        If pxgraph is given an empty file to plot, all it does 
is send a message "problems with input data" to the standard 
output.


A.5.4  HPPA specific bugs

As stated earlier, the hppa port in Ptolemy0.5 is fundamentally 
unchanged from the hppa port in Ptolemy0.5beta. We anticipate 
rereleasing the hppa port soon. Below is a list of known hppa 
specific bugs.

        Dynamic linking does not work on the hppa.
        The hppa.cfront architecture is new port, and is known 
to have problems with random numbers. The hppa does not have a 
random() function, and the rand() function returns numbers over 
a different range than random(). There is a patch for this bug 
available via anonymous ftp from ptolemy.eecs.berkeley.edu at 
pub/ptolemy/ptolemy0.5/patches/pt-0.5-patch1.

        On the hppa, pxgraph does not print hardcopy perhaps 
because the hppa does not have an lpr command.
        On the hppa, compiling with gcc-2.5.8 with the -O option 
fails because of an undefined symbol. This is a Gnu compiler bug.

        On the hppa, oct2ps core dumps, so printing facets 
probably won't work.
        On the hppa, the octtools masters program may core dump.
        On the hppa, problems have been reported in the de 
domain. The de:basic:real-time demo hangs.
        On the hppa, under cfront, Xhistogram may have rounding 
problems.

A.5.5  GNU compiler bugs

If you write your own stars, then be aware that gcc-2.5.8 may 
not choose the expected cast. In particular, g++ has been know 
to cast everything to Fix if the explicit cast is omitted. The 
arithmetic is then performed using fixed-point computations. 
This will be dramatically slower than double or integer 
arithmetic, and may yield unexpected results. It is best to 
explicitly cast states to the desired form. For more 
information, see the ptlang chapter in the Ptolemy Programmers 
Manual.

On the mips, files must be compiled with the -G O option for 
dynamic linking to work. Unfortunately, under gcc-2.5.8, gcc 
spits out lots of warnings like:

warning: T_EOF not found in original or external symbol tables
These warnings may be ignored.

A.6  Additional Resources

The best, most complete source for information on Ptolemy is to 
be found in the Ptolemy manual, The Almagest. The manual is 
included in every distribution. In addition, the printed 
documentation is also available from the ILP office at the 
following address:

        EECS/ERL Industrial Liaison Program Office
Software Distribution
205 Cory Hall
University of California at Berkeley
Berkeley, CA 94720
(510) 643-6687
email: ilpsoftware@eecs.berkeley.edu
A second source is the "ptolemy-hackers@ohm.eecs.berkeley.edu" 
mailing list. This list provides a forum for Ptolemy questions 
and issues. Users of the current release who have a Ptolemy 
question, comment, or think they've found a bug should send mail 
to ptolemy-hackers. See the "Mailing Lists" section above for 
details.

Another source is the Ptolemy FTP site. To access this, use 
anonymous FTP to ptolemy.eecs.berkeley.edu. The directory 
"pub/ptolemy/papers" contains some of the latest Ptolemy papers 
and articles. The directory "pub/ptolemy/mailing-lists" contains 
the logs from the "ptolemy-hackers" mailing list. Check there to 
see if your question has been asked before.

