.\" @(#)universes	2.10	12/4/92
.EQ
delim off
.EN
.H1 "Creating Your Own Universes"
.pp
In this section, we will show how to create your own universes with
a simple example.  First, be sure you are in a directory
where you have write permission, like your home directory.
.BU
Create a new work area:
.(c
mkdir example
cd example
.)c
.BU
Start pigi:
.(c
pigi
.)c
.lp
You will see the message:
.(c
creating initial facet ``init.pal''
.)c
Wait until the startup window with the version number appears.
We are now ready to learn about the basics of using VEM.
More complete VEM documentation can be found in the VEM section
of the Almagest.
.H2 "Terminology"
.pp
As we said earlier, the fundamental Oct objects that we edit with VEM
are called \fIfacets\fP.  This means that we read an entire facet from
disk into VEM, make changes to it, and then save the facet back to
disk.
.pp
Facets are specified by three names separated by colons.  This is
usually written as ``cell:view:facet''.  The first component is the
.IE cell
.IE cell
.IE facet
cell name which is used to name the design.  In pigi, the second
component, called the view name, will always be
``schematic''.\**
.IE schematic
.(f
\** Other Oct applications use other views such as
``symbolic'' or ``physical'' but these are not used by pigi.
.)f
Last,
there is the facet component which can either be ``contents'' or
``interface''.
.IE contents
.IE interface
The former is used for block diagrams, and the latter for icons.
Note that all three facet component names may not contain any spaces.
.pp
Note also that the term ``facet'' can
refer to two different things.  It can mean the Oct object called a
facet, or it can refer to the name of the last component of a facet's
name.  The intended meaning is usually clear from context.
If the facet component is not specified, VEM assumes that you mean the
contents facet.  Thus, ``wave:schematic'' refers to the facet with cell
name ``wave'', view name ``schematic'', and facet name ``contents''.
.pp
The two kinds of facets, contents and interface, are used to store
two different kinds of data.
Contents facets contain the actual definition of a design while
interface facets contain schematic symbols.  In our example, we will
create a universe with three stars.  The universe will be stored in a
contents facet.  The three stars in our system will be represented by
schematic symbols called \fBicons\fP.  These icons are stored in
interface facets.
The universe itself can be given an icon, which will become
its interface facet.
.H2 "Building an application"
.pp
Now we are ready to create a simple universe.  Let's create a simulation
that generates a sine wave and displays it.
.BU
Open a new facet:
The facet that is already open,
called ``init.pal:schematic'', is special because pigi always
.IE "init.pal facet"
opens a facet by this name in the directory in which it starts.
Convention in Ptolemy dictates that ``init.pal'' should be used to store
icons representing complete applications, so
instead of using this facet, we will create a new one.
.in +0.5i
.LE
Place cursor in window labeled ``init.pal:schematic''.
.LE
Select the \fIopen-facet\fP command from the ``Window''
pigi menu (shift-middle-button).
Alternatively, type an ``F''.
.IE open-facet
.LE
Replace the cell Name ``untitled'' in the dialog with ``wave'' and click
the ``OK'' button.  A quick way to delete the ``untitled'' is
using control-k.  Leave the View and Facet fields
unmodified.  A new blank window will appear.
.in -0.5i
.BU
Open a palette:
.in +0.5i
.LE
Place cursor in either blank window.
.LE
Select the \fIopen-palette\fP command from the ``Window''
pigi menu.
.IE open-palette
Alternatively, type an ``O''.
.LE
Pigi will present a palette menu.
Select the ``sdf'' palette by clicking
the left button in the box next to
``$PTOLEMY/src/domains/sdf/icons/main.pal'' (the first entry),
and then click on ``OK''.
This palette shows the basic categories of
synchronous dataflow stars that are availabel.
There are too many stars to put in just one palette.
You can use the Window:look-inside (``i'') command to
open any of the palettes.
At this point you should look inside
the ``Signal Sources'', ``Nonlinear Functions'',
and ``Signal Sinks''.  Arrange these palettes on the screen so that you
can see the blank window labeled ``wave:schematic''.
.in -0.5i
.H2 "Some Basic VEM Commands"
.pp
At this time, it is worth exploring some basic VEM commands for
manipulating window displays.
VEM uses post-fix commands.  This means that the user enters the 
arguments to a command before the command name itself.  Arguments
appear in the VEM console window as the user enters them.
.pp
There are several types of arguments.  Each argument type is
entered in a different way.  All graphics arguments are created
with the left mouse button.  The five types of arguments are listed
below:
.BU
Point: position the cursor, click the left mouse button
.Ir "point in VEM"
.BU
Box: position the cursor, drag\**
.IE drag
.IE "drawing a box"
.IE "box"
.(f
\** ``Drag'' means to press
down on a mouse button, move the mouse while holding it down, and then
release the button.
.)f
the left mouse button
.BU
Line: make a point, position the cursor above point, drag the left
mouse button
.IE "drawing a line"
.IE "line"
.BU
Object: use \fIselect-objects\fP and \fIunselect-objects\fP
commands (explained later)
.BU
Text: enclose text in double quotes
.lp
Arguments can be removed from the command line by typing the delete
key, backspace key, or ``control-u'', which deletes all the current arguments.
There are three ways to enter commands:
.BU
Menus: middle-button for VEM commands, shift-middle-button
for pigi commands.  Menus are of the ``walking'' variety, as explained before.
.BU
Key bindings: commands can be bound to single keys
and activated by just pressing the key.
.IE "key bindings"
.IE "single key accelerator"
.IE "bindings"
Key bindings are case sensitive.
We have been giving key bindings for the pigi commands that have them
as we go along.
There are also tables at the end of this document summarizing
VEM and pigi commands and their key bindings.
.BU
Type-in: type a colon followed by the command name
.lp
Let's try a few examples, some of which should be familiar by now.
Place the cursor in the palette window (the one with the library
stars) and:
.BU
Type ``shift-Z'' (capital Z) for \fIzoom-out\fP.
This makes everything smaller.
.IE zoom-out
.BU
Type ``z'' (lower-case z) for \fIzoom-in\fP.
This makes everything bigger.
.IE zoom-in
If you zoom in sufficiently, labels will appear below each icon
giving the name of the star.  VEM does not display these labels
if they will be too small.
.BU
The VEM \fIshow-property\fR command (``control-p'') is useful
for finding out the name of a star when the label is not visible.
Just place the mouse cursor on the icon of interest and type
``control-p''.
.IE "show-property"
.BU
Try ``p'' for \fIpan\fP.  Pan moves the spot under the cursor
to the center of the window.
.IE pan
.BU
The VEM \fIpan\fP command can also take as an argument a point
which will indicate the new center of the window.
Recall that the argument must be entered first.
Place a point somewhere in the palette window by clicking
the left button, and type ``p''.
The location of your point became the center of the window.
.BU
The VEM \fIopen-window\fP command can take as an argument a box.
Draw a box in the palette window by dragging the left mouse button.
Then type ``o'', or find the \fIopen-window\fR command in the VEM
menu.
.IE open-window
.BU
Try placing points in the new window.
Notice that they also appear in the original palette
window.
Also notice that you are only permitted to place points
at certain locations.
VEM has an implicit \fIgrid\fR to which points \fIsnap\fR.
.IE grid
.IE snap
The default snap resolution is suitable for making \*(PT universes.
.BU
You can get rid of your point (or any argument list) by typing ``control-u''.
You can delete arguments one-at-a-time by typing ``control-h''.
Try placing several points and then deleting them one by one.
.BU
You can close the new window (or any window)
with ``control-d''.
.IE close-window
.BU
A particularly useful command at this time is \fIshow-all\fP, or ``f''.
Try this command in the palette window.
This rescales and recenters the display so that everything in
the facet is visible.
.IE "show-all"
.BU
You can also resize a window, using whatever X Window
bindings you have installed, and then type ``f'' to show all.
.H2 "Back to the example"
.BU
Create an instance of the star called ``Ramp''.
This star is the first star of the second row of the sources palette.
Its icon has an orange triangle.
To do this:
.in +0.5i
.LE
With your mouse cursor in the window ``wave:schematic'':
.LE
Create a point anywhere in the
window by clicking the left button.
.LE
Move the cursor over the ``Ramp'' icon in the palette and
press the ``c'' key.
This is a key binding that executes the VEM ``create'' command.
.IE create
.LE
You have just created an \fBinstance\fP of the ``Ramp''
icon.  The actual data which describes how the ``Ramp'' icon should
be drawn is stored in another facet (an interface facet).  An
\fBinstance\fP\ of the ``Ramp'' icon points to this facet.
.IE instance
.in -0.5i
.BU
Delete and select instances:
Sometimes in the process of editing your schematic, you may
need to delete objects.  As an example, let's create another Ramp
instance and then delete it.
.in +0.5i
.LE
Create another Ramp instance next to the first one:
place a point near the original Ramp, place the cursor over the
Ramp icon in the palette and press ``c''.
Actually, you don't have to use the icon in the palette \- you
could also put the cursor over the already existing Ramp icon
to achieve the same effect.
.LE
Place the cursor over the new Ramp icon and execute \fIselect-objects\fP
by typing ``s''.
.IE select-objects
This creates an object argument on the VEM command line.
This is necessary because the VEM \fIdelete-objects\fP command
takes arguments of type ``object''.
.IE delete-objects
The \fIselect-objects\fP command
takes point, box, and/or line arguments and turns the
items underneath them into object arguments.  The \fIunselect-objects\fP
command (``u'') does the reverse of \fIselect-objects\fP.
.IE unselect-objects
.LE
Execute \fIdelete-objects\fP by typing ``D'' (upper-case!).
This deletes the objects we selected previously.
.LE
You could also have deleted the newly created Ramp with the \fIundo\fR
command (``U'').
.IE undo
This is an infinite undo, so you can backtrack through all changes
you have made since starting the VEM session by repeatedly executing
the undo command.
.LE
Occasionally when you use the select and unselect commands, the
objects are not redrawn correctly.  When this happens, use the
VEM \fIredraw-window\fP command, ``control-l'' (lower case L), to redraw.
.IE redraw
.in -0.5i
.BU
Create the remaining instances in our example:
.in +0.5i
.LE
Create an instance of the ``Sin'' icon to the right of
the Ramp.
``Sin'' is the first icon in the second row of the ``nonlinear'' palette.
Make sure it does not overlap with the
Ramp icon.
If it overlaps, you can delete it and create a new one.
.LE
Create an ``Xgraph'' instance to the right of the
Sin icon.
``Xgraph'' is the first icon in the first row of the ``sinks'' palette.
.lp
We now have three icons: a Ramp, a Sin, and an Xgraph.  Next,
we will connect them together.
.in -0.5i
.BU
Connect the Ramp output to the sin input using the following steps:
.in +0.5i
.LE
With the mouse cursor in the ``wave:schematic'' window,
type ``f'' to show all.
This will rescale your system, and make it easier
to make connections.
.LE
Draw a line between the output of the Ramp and the input of the
Sin:
put the cursor over the Ramp output, double-click on the left mouse button,
and drag the cursor to the Sin input, and then let up on the mouse
button.
If the two terminals are not on a horizontal line, you can bend the line
by momentarily releasing the mouse button while dragging it.
.LE
Type ``c'' for \fIcreate\fP to create a wire.
Notice that the
\fIcreate\fP command creates wires or instances depending on the type of
arguments it is called with.
.LE
If you need to delete a wire, you can draw a box around it
(click and drag with the mouse),
select it (press ``s''), and then delete it (``D'').
.in -0.5i
.BU
Connect the Sin output to the Xgraph input in a similar way.
.BU
Run the universe:
We now have a complete universe that we can simulate.
.in +0.5i
.LE
Execute the \fIrun\fP command from the pigi ``Exec'' menu,
or type an ``R''.
.LE
Enter ``100'' for the number of iterations.
Do this by typing ``control-k'' to remove the default entry,
typing 100, and clicking ``OK''.
Instead of clicking ``OK'' you can also hit ``meta-return''.
.LE
A new window with a graph of a rough
sine wave should appear.
The execution of the Xgraph star created
this new window which shows the output of our simulation.
To remove this window, click on the ``Close'' button or
press ``control-d'' in it.
.in -0.5i
.BU
Save the facet by typing ``S'' (upper-case) with the cursor in
the ``wave:schematic'' window.  This executes the VEM \fIsave-window\fP
command.
.IE save-window
It is wise to periodically save your work in case the editor
or computer system fails unexpectedly.
.BU
Change parameters:
If we look at the output, the sine wave appears jagged.  This is because
the Ramp star has a set of default parameters which cause the Ramp
to generate output values with an increment that is too large.  We
can change the parameters of the Ramp star as follows:
.in +0.5i
.LE
Place the cursor over the Ramp icon and execute
\fIedit-params\fP in the pigi menu (or type ``e'').  A dialog box will appear
that shows the current parameters of the Ramp.
.IE edit-params
.LE
Replace the value of ``step'' with ``PI/50''.
(You can use ``control-k'' to erase the old value.)
Finally, click the ``OK'' button to store the new parameters.
This is an example of Ptolemy's parameter expression syntax.
This syntax supports addition, subtraction, multiplication,
and division, written exactly as they would be in C or Fortran
(exponentiation is not yet supported).  The built-in symbol PI has
the value 3.14... as you would expect.
.in -0.5i
.BU
Run the simulation again using 100 iterations.  This time the output
should look like one cycle of a sine wave.
.BU
Use \fIsave-window\fP again to save the new parameters.
.BU
To be able to conveniently access this example
again, you should create an icon for it.
To do this, use the pigi command
``Extend:make-schem-icon'', or ``@''.
.IE "make-schem-icon"
.IE icons
.IE "making icons"
Just place the mouse cursor in the ``wave'' facet
window, and hit the ``@'' key.
A dialog box appears asking for the name of the
palette in which you would like to put the icon.
By convention, we put universe icons in
palettes called ``init.pal''.
So replace the default entry (which should be ``./user.pal'') with ``init.pal''.
When making the icon is finished, find the ``init.pal''
window that first opened when you started the system,
and type ``f'' to show all.
An icon will appear.  Looking inside this icon
(``i'') will get you your ``wave'' palette.
The second item in the palette is a marker
indicating where the next icon that you create
will go.
Henceforth, anytime you start pigi in this
same directory, the first window you will see
will be this ``init.pal'' window.
.BU
Our example is now complete.  To exit:
.in +0.5i
.LE
Close all xgraph windows with ``control-d''.
.LE
Type ``control-d'' in the VEM console window.
A dialog box will appear asking you to choose buffers to be saved.
Unfortunately, as of this writing, some of the buffers listed may have
already been saved and do not need to be saved again.  Also,
some of the buffers listed may not have been changed, and therefore
do not need to be saved.  
To indicate which of the listed buffers you wish
to save, click on the box to the left of each name.  Then click on the
``OK'' button.
.LE
A final warning appears telling you that closing the console window
will terminate the program.  Click on ``Yes''.
.in -0.5i
.EQ
delim $$
.EN
.\" Local variables:
.\" mode: nroff
.\" End:
