.\" @(#)other	1.14	12/4/92
.EQ
delim off
.EN
.H1 "Other Useful Information"
.pp
In this section we cover additional information which may be useful.
More advanced topics will be covered in following sections.
.H2 "Plotting Signals and Fourier Transforms"
.pp
The \*(PT menu has a submenu called \fIUtilities\fR that invokes
some useful, frequently used, predefined universes.
For example, the \fIplot signal\fR (``~'') command will plot a signal.
The signal can be read from a file, or specified using the
syntax for specifying the value of a \fIfloatarray\fR parameter
in pigi.
For example, if the value of the \fIsignal\fR parameter is:
.(c
1 [10] -1 [10]
.)c
then the \fIplot signal\fR command will plot ten points with value 1.0
and ten points with value -1.0.
.IE "plot signal"
The \fIoptions\fR parameter can accept any options understood by the
xgraph program (see the xgraph section of the Almagest).
To plot a signal stored in a file, simply use the following syntax
for the \fIsignal\fR parameter:
.(c
< filename
.)c
.pp
Another useful \fIUtilities\fR command is \fIDFT\fR (``^''), which
reads a signal just as above and plots the magnitude and phase of the
discrete-time Fourier transform of the signal.
.IE "Fourier transform"
.IE "spectrum plot"
These are plotted as a function of frequency normalized
to the sampling rate, from -(PI) to PI.
The sampling frequency is assumed to be 2 PI.
A simple phase unwrapping algorithm is used to give more meaningful
phase plots.
A radix-2 FFT is used, so the order of the Fourier transform
must be a power of two.  The order can be longer than the signal,
in which case, zero-padding will occur.
.H2 "Setting parameters"
.pp
The \fIedit-params\fR or \fIdefine-params\fR commands in pigi permit
the user to set the initial value of a settable state of any star,
and to define parameters for a galaxy or universe.
The syntax for linking the values of the star parameters to
values of galaxy or universe parameters is simple.
Furthermore, a fairly general expression language is supported.
.pp
Parameter values set through pigi can be expressions.
This is particularly useful for propagating values down from
a universe parameter to star parameters somewhere down in the hierarchy.
An example of a valid parameter expression is:
.(c
	PI/(2*order)
.)c
where
.c order
is a parameter defined in the galaxy or universe.
The basic arithmetic operators are addition (+), subtraction (-),
multiplication (*), division (/), and exponentiation (^).
These operators work on integers and floats.
Currently all intermediate expressions are converted to the type
of the parameter being computed.  Hence, it is necessary to be very
careful when, for example, using floating point values to compute
an integer parameter.  All intermediate expressions will be converted
to integers.
.pp
When defining complex values, the basic syntax is
.(c
	(real, imag)
.)c
where
.c real
and
.c imag
evaluate to integers or floats.
.pp
When defining arrays of integers, floats, or complex numbers,
the basic syntax is a simple list separated by spaces.
For example,
.(c
	1 2 3 4 5
.)c
defines an integer array with five elements.
The elements can be expressions if they are surrounded by parentheses:
.(c
	1 2 PI (2*PI)
.)c
Repetition can be indicated using the following syntax:
.(c
	value [n]
.)c
where
.c n
evaluates to an integer.
.IE "file input"
.IE "reading from a file"
An array or portion of an array can be input from a file,
using the symbol ``<'' as in the following example:
.(c
	1 2 < filename 3 4
.)c
Here, the first two elements of the array will be 1 and 2,
the next elements will be read from file
.c filename,
and the last two elements will be 3 and 4.
This latter capability can be used in combination with the
.c WaveForm
star to read a signal from a file.
.pp
For string valued parameters, most of the above expressions will not work.
Furthermore, there is a bit of complication when one wishes to set
a string parameter equal to the value of a galaxy or universe parameter,
because a distinction must be made between a sequence of characters
that give the name of a symbol and a sequence of characters to be
interpreted literally.  The syntax to use is explained in the example:
.(c
	This string has the word {word} taken from another parameter
.)c
Here,
.c {word}
represents the value of a string universe or galaxy parameter.
.H2 "Particle Types"
.pp
The packets of data that pass from one star to another
in \*(PT are called \fIparticles\fR.
.IE "particle type"
.IE "types"
So far, all particles have been simply floating point numbers representing
samples of signals.  However, several other data types are supported.
Each star icon has a protrusion for each porthole.
.IE "porthole type"
In pigi, if you are using a color monitor, the color of the stem
indicates the type of data that the porthole consumes or produces.
A blue stem on an input
or output of a star icon indicates type "float", a white stem
indicates type "complex", a green stem indicates "packet",
and a red stem indicates "anytype".
.pp
Ptolemy usually make conversions between these types automatically.
The float to complex conversion does the obvious thing,
putting the float value into the real part of the complex,
and setting the imaginary part to zero.  The complex to float
conversion computes the magnitude of the complex number.
The XGraph star, and most other stars that generate output,
accept "anytype" of input.  If the input is complex, the magnitude
will be plotted, because it will be cast to a float internally.
If you want to plot both the real and imaginary parts, you
should use the ComplexReal conversion star first.
.pp
For technical reasons too involved to explain here, automatic type conversions
cannot always be made.  In particular, Ptolemy can only do one
type conversion for any given output of a star.  So if a single
output is connected to multiple inputs of different types,
Ptolemy may complain.  For example, suppose you connect a "float" output
to both a "complex" input and a "float" input.  Ptolemy will complain.
A simple solution is to insert a unit gain (use the FloatGain star)
between the "float" output and the "complex" input.
Then the type conversion occurs on the output of the FloatGain star,
which goes only to a "complex" input.
.pp
Automatic type conversions have one potentially serious pitfall.
Suppose you connect a "float" output to a "complex" and "anytype" input.
This is legal, because Ptolemy can satisfy the constraints with just
one type conversion, float to complex.  However, suppose the "anytype"
input belongs to an XGraph star.  As explained above, the XGgraph
star plots the magnitude of a complex number, unless you have
an explicit ComplexReal conversion star.  Hence, instead of plotting
the "float" output, XGraph will plot the magnitude, converting
all negative numbers to positive.  Inserting a ComplexReal is one
way to correct the problem.  Another way is to use the FloatGain star
with unity gain to postpone the conversion to complex on the other fork.
.H2 "Moving objects"
.pp
.IE "moving objects"
Sometimes you may want to move objects around within your schematic.
Use the VEM command \fImove-objects\fP (``m'')
in the \fISelection\fR menu to do this.
You can move objects as follows:
.BU
Select the objects that you want to move.
.BU
Using the right mouse button, drag the objects to the desired
location.
.BU
Execute \fImove-objects\fP, ``m''.
.IE move-objects
.H2 "Copying objects"
.pp
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 \fIcopy-objects\fR
.IE "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.
.H2 "Labeling a Design"
.pp
It is useful to annotate a block diagram with titles and comments.
.IE labels
.IE annotations
The VEM \fIedit-label\fR (``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 \fIlayer\fR, which determines the color of the label.
.IE layers
Place a point where you would like the label,
and then type a layer name, such as "whiteSolid" (with the quotation marks).
Then type ``E''.  A dialog box will appear, offering various options.
Type the text for your label in the ``Label'' box.
It can contain carriage returns.
To select a text height (font size)
.IE fonts
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 default, 100, is too big for all but the loudest titles.
Sizes 60 and 40 work well with the overall scaling of \*(PT facets.
You can also change the justification by clicking the left button
to the right of each justification box.  A popup menu lists the options.
.pp
To determine which layers (colors) are available for text labels,
open the layers palette.  This can be done with the VEM \fIpalette\fR
(``P'') command in the ``System'' menu.
.IE "palette VEM command"
A window will pop up showing the available colors.
The names of the colors appear at the top of each column of boxes.
.IE "layer names"
.IE "colors"
The layers "redSolid" and "blackSolid" work well for labels.
The layers "redOutline" and "blackOutline" are similar, except
that a box will be drawn around the label.
.H2 "Icon Orientation"
.pp
.IE "transform, VEM command"
.IE "icons, rotating"
.IE "icons, reflecting"
Most \*(PT 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".
.H2 "Finding the names of terminals"
.pp
.IE "names of terminals"
Some stars have several terminals, each with a different function.
The documentation may refer to these terminals only by name.
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 here if necessary.
.H2 "Multiple inputs and outputs"
.pp
.IE "multiple inputs"
.IE "multiple outputs"
\*(PT supports star definitions that do not specify how many
inputs or outputs there are.
The
.c Add
and
.c Fork
stars are defined this way, for instance.
Take a close look at the third star in the third row
of the SDF main.pal palette.
It is an adder with only one input terminal.
However, the input terminal is unusual in that it has
two arrow heads.  This signals a multiple input.
Any number of outputs can be connected to this terminal
(subject to restrictions explained below), and
each of those outputs will be added.
.pp
Sometimes, such terminals are not convenient.
It is better to have a set of icons for the commonly used numbers
of terminals.  The icon two to the left of the multi-input
.c FloatAdd
is also a
.c FloatAdd,
but it has an icon that shows only two normal inputs.
The
.c fork
stars in the sixth row of the palette are similarly just different
icons for the same star.
It is easy to create such icons for any existing star.
.pp
Suppose you wish to create an icon for an adder with four inputs.
In any facet, execute the pigi command ``Extend:make-star'' (``*'').
.IE "make-star"
A dialog box appears.
Enter ``FloatSum.input=4'' for the star name,
``SDF'' for the domain, and
``~ptolemy/src/domains/sdf/stars'' for the star src directory
(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.
.IE "source code, finding"
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 four-input adder icon.
You may edit this icon, as explained below.
.H2 "Using delays"
.pp
.IE delays
In the SDF and DDF domains, delays can be placed on arcs.
A delay in these domains is not a star, but rather is a property
of the arc connecting two stars.
The interpretation of the delay is as an initial particle on the arc.
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 green diamond in the SDF and system palettes.
You can specify the number of delays by executing
\fIedit-params\fP with the cursor on top of the delay icon.
.H2 "Auto-forking"
.pp
.IE auto-forks
.IE "nets"
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.
.pp
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''.
.IE "clear-marks"
To fix the problem, delete the offending net, and replace it
with one or more \fIfork\fR stars and a set of point-to-point connections.
All domains for which this problem occurs have fork stars.
.pp
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 it is, \*(PT 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.  \*(PT 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.
.pp
Both of the above restrictions may be eliminated in future versions.
.H2 "Dealing with errors"
.pp
.IE errors
Ptolemy is composed of several components of which pigi is one.  When
errors occur, it helps to know which component detected the error so
that it can be corrected.
.pp
There are three main components involved in processing a schematic:
VEM, pigi, and the Ptolemy kernel.  Each component corresponds to one
phase of processing:
.ip \fBVEM\fP 1.5i
.IE VEM
Handles schematic entry and maintains net list information
for the design.  VEM also handles all accesses to Oct.
.ip \fBpigi\fP 1.5i
Translates schematic information that VEM produces
into the textual language which the Ptolemy kernel expects.
.ip "\fBPtolemy kernel\fP" 1.5i
.IE kernel
Handles the execution
of the design.
.pp
Errors can occur in any of these phases.  When correcting errors,
it helps to know in which phase the error occurs.
.pp
When errors occur in VEM, VEM prints the error in the console window.
For example, if you enter a point argument and execute \fIcreate\fP
when the cursor is not over an instance, then VEM displays the message
``Cannot place contact''.  Usually, VEM errors are easy to fix.  In
this case, VEM expects the user to specify the instance to be created.
.pp
Pigi errors can occur when any of the pigi commands are invoked.  When
errors occur during compilation, pigi usually highlights in red the
object in the schematic associated with the error.  When this happens,
you can execute the \fIclear-marks\fP command to clear the
.IE clear-marks
highlighting.  If such an error occurs and the reason for the error is
not obvious, try deleting the indicated objects and redrawing them.
.pp
.H2 "Copying and moving designs"
.pp
.IE "copying facets"
.IE "moving facets"
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).
.Ir inconsistent
.pp
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 \*(PT.
.H3 "Moving palettes, stars, galaxies, and universes"
.pp
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.
.H3 "Moving stars"
.pp
Suppose you have developed a fantastic new star called alphaCentaur,
and you wish to install it in a palette that is available for
general use.  Since you have developed the star, you know
where it is used.  The star icon itself is stored in two facets:
.(c
	alphaCentaur/schematic/contents;
	alphaCentaur/schematic/interface;
.)c
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 source code:
.(c
	mv alphaCentaur.pl destinationDirectory
.)c
Then edit the makefile or make.template in that directory to be able
to compile the new star.
Then move the icon:
.(c
	mv alphaCentaur destinationDirectory
.)c
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:
.(c
foucault.berkeley.edu 102: masters alphaTest
Running masters on wave
Pathname to replace (? for a listing):
.)c
Enter a question mark to get a list of all icons referenced in the facet:
.(c
Pathname to replace (? for a listing): ?

Pathnames currently found in the facet (minus connectors and delays):
	~yourname/oldDirectory/alphaCentaur
        $PTOLEMY/src/domains/sdf/icons/Ramp
        $PTOLEMY/src/domains/sdf/icons/Sin
        $PTOLEMY/src/domains/sdf/icons/Xgraph
Pathname to replace (? for help):
.)c
The last three items are pointers to official \*(PT icons.
There is no need to change these.
You should now enter the string you need to replace and the replacement
value:
.(c
Pathname to replace (? for help): ~yourname/oldDirectory
New pathname: ~yourname/destinationDirectory
.)c
Next, use masters the same way
to modify any palettes that reference the moved icon.
For instance, the "user.pal" palette is a likely candidate.
If you miss a reference, Oct will issue an error message when it tries
to open the offending palette.  
.EQ
delim $$
.EN
.\" Local variables:
.\" mode: nroff
.\" End:
