.\" @(#)galaxies	2.8	12/4/92
.EQ
delim off
.EN
.H1 "Using Galaxies"
.pp
.IE galaxies
In this section we will explain how to create galaxies.  Galaxies allow
you to partition your design into more manageable pieces and to re-use
designs as components in other designs.
.H2 "Creating a Galaxy"
.pp
Let's use the schematic we created in the last example to make a sine wave
generator galaxy.
.BU
Instead of modifying our previous example, we will make a copy
of it.
In your ``example'' directory, type:
.(c
cp -r wave singen
.)c
The recursive copy, ``cp -r'', is necessary because Oct stores
data using a hierarchical directory structure.
Of course,
if the
facet singen exists already, you must remove it with ``rm -r''
first before copying.
.BU
Start pigi.
.BU
Use \fIopen-palette\fP (or ``O'') to open the
``$PTOLEMY/lib/colors/ptolemy/system'' palette (the last one in
the list of palettes).
The system palette contains input and output ports which can be instantiated
into schematics just like stars.
.BU
Use \fIopen-facet\fP (or ``F'') to open the ``singen:schematic''
you created using ``cp -r''.
You must replace the default name ``untitled'' with ``singen''.
.BU
In the ``singen:schematic'' window, delete the Xgraph star and
the wire attached to it.
The easiest way to do this is draw a box (click-drag) around the
star and its input wire, press ``s'' to select these objects,
and then press ``D'' to delete them.
(You may want to enlarge your window to make it easier to work.)
.BU
Place an output port where the Xgraph star used to be and connect
it to the output of the Sin star.
The output port is the icon in the system palette with an arrowhead
(an input port, by contrast, has a fish tail).
.BU
Name the output port ``out'':
.LE
Position the cursor over the black box on the new output port.
.LE
Type "out" as a text argument, including quotation marks.
.LE
Type ``c'' for \fIcreate\fP.
Again, note that the \fIcreate\fP command has a different action
than before.  It names output terminals when given a text argument.
.BU
We now have a galaxy.  The fact that a schematic has input
or output ports distinguishes it as a galaxy.
This galaxy that you just created is similar to the ``singen'' galaxy
in the ``Signal Sources'' palette.  Find it, and look inside, to make the
comparison.
.H2 "Using a galaxy"
.pp
We have just created a galaxy that we would like to use in another
design.  In order to do this, we need to create an icon for this galaxy
which we will then instantiate in our other design.
.BU
Create an icon:
.LE
Place cursor in ``singen:schematic'' window.
.LE
Execute \fImake-schem-icon\fP in the pigi ``Extend'' menu (``@'').
.IE make-schem-icon
.LE
The dialog box should contain:
.(c
Palette:  ./user.pal
.)c
This specifies the name of the palette that will contain your icon.
By convention, we usually put galaxy icons in the palette called
``user.pal'' in the current directory.
Hence, this is the default name.
.LE
Click ``OK''.
Since you had already created an icon for the ``wave'' universe, and
that icon was copied by your ``cp -r'', VEM asks whether it is OK to
overwrite the icon.
Click ``OK''.
Wait until \fImake-schem-icon\fP is done.
VEM informs you that it is done with a message in the VEM console
window, which may be buried by now.
You should find it and bring it to the surface.
.BU
Open the palette called ``user.pal'' using \fIopen-palette\fP (``O'').  The
newly created galaxy icon should appear in this palette along with
a bright yellow dot called a \fBcursor\fP.  A \fBcursor\fP
.IE cursor
distinguishes a palette from other types of facets and it determines
where the next icon will be placed.
.BU
At this point, we have an icon for our sine wave generator
galaxy.  The icon for this galaxy is stored in an interface facet
called ``singen:schematic:interface''.  It is this icon facet
which is instantiated in the ``user'' palette.  We can now
use our sine generator galaxy simply by instantiating our
icon into another schematic.
.BU
Use \fIopen-facet\fP to create a new facet with the cell
name ``modulation''.
.BU
In the ``modulation:schematic'' window, create a universe which
takes two ``singen'' galaxies, multiplies their outputs together,
and then outputs the result using ``Xgraph''.
The ``Xgraph'' star can be found again in the ``Signal Sinks'' subpalette
of the SDF palette.
The multiplier star, called Mpy, is in the ``Arithmetic'' subpalette.
\fBHint\fR: If you place the icons so that their terminals
fall on top of one another, then a connection gets made without
having to draw a wire.
.BU
Now run the universe with the number of iterations set to 100.  The output
should appear as a squared sine wave, which is just an inverted
sine wave of twice the frequency shifted up by 1/2.
.pp
So far, we have created a galaxy and used it in another
universe.  But, we could also have used our galaxy within another
galaxy.  In this way, large systems can be broken up into smaller
more manageable pieces.
.H2 "Galaxy and Universe Parameters"
.pp
.IE "galaxy parameters"
.IE "universe parameters"
One of the problems with the ``singen'' galaxy that we just created
is that it generates sine waves with a fixed frequency.  We would
like to make the frequency of the generator parameterizable.  That
way, we could set the two ``singen'' galaxies in our ``modulation''
universe to two different frequencies.
.pp
To make a galaxy parameterizable, we create \fBformal parameters\fP
in the galaxy and then link the formal parameters to the
\fBactual parameters\fP of the instances contained in the galaxy.  The terms,
formal and actual parameters, are analogous to formal and actual
parameters in any procedural programming language.  An example
will make this clear.
.Id "formal parameters"
.Id "actual parameters"
.Id "galaxy parameters"
.BU
Create formal parameters:
.LE
Place the cursor in the ``singen:schematic'' window but away
from any instance,
i.e., in the grey background of the facet.
.LE
Execute \fIedit-params\fR (``e'')
.IE "edit-params"
and a message will appear indicating that the Galaxy has no
parameters.
To add parameters to the galaxy, execute
\fIdefine-params\fR (``+'') anywhere in the galaxy
to get a dialog box with three blanks
.IE "define-params"
.(c
New name:
New type:
New value:
.)c
Fill in the dialog as follows:
.(c
New name:  freq
New type:  float
New value:  PI/50
.)c
Then click on ``OK''.
Recall that you can use ``tab'' to move from one field to the next
of the dialog box and ``meta-return'' instead of ``OK''.
Hence, the dialog can be managed from the keyboard, without requiring
the mouse.
.pp
A common error in making entries in these dialog boxes is to type
``return''.  This has the unfortunate consequence of making a multi-line
entry, probably not desired in this case.
Although you can correct the problem by typing repeated backspaces,
it is usually easier to cancel the dialog and start over.
.IE "dialog boxes"
.LE
We just created a new formal parameter called ``freq'' with a
default value of ``PI/50''.  Additional parameters may be added or
old ones changed simply by invoking \fIdefine-params\fP again.  The
value of a formal parameter can be changed by executing
\fIedit-params\fR in the background of the galaxy, or 
on the icon representing the galaxy.
.pp
Exactly the same procedure can be used to attach formal
parameters to a universe.
.BU
Link formal parameters to actual parameters:
.LE
Place the cursor over the ramp icon in ``singen:schematic''.
.LE
Execute \fIedit-params\fP and fill in the dialog as follows:
.(c
step:  freq
value:  0.0
.)c
This allows the ``freq'' parameter of a singen instance to control
the increment of the internal ramp star, thus controlling the
output frequency.
.LE
In earlier versions of pigi, it was necessary, when adding a formal
parameter to a galaxy, to delete and recreate all instances of that
galaxy.  This is no longer required: all instances of the galaxy
that already existed will immediately ``know'' about the new parameter,
and will use the default value.
.BU
Change the frequency of one of the ``singen'' instances to
``PI/5'' by using \fIedit-params\fP.  This ``singen'' will be
ten times the frequency of the other.
.BU
Run the universe with an iteration of 100.  The output should
show the product of two sine waves with different frequencies.
Don't forget to save the facets we just created.
It would also be a good idea to create
an icon for ``modulation'' and put it
in ``init.pal''.
.H2 "Sounds"
.pp
On some workstations (currently only Sun Sparcstations), \*(PT
can play sounds over the workstation speaker.  You can try this with
the universe you just created.
Replace the ``Xgraph'' star in ``waveform:schematic''
with an instance of the ``Play''
star (second row of of the sinks palette, right of center,
with a stylized loudspeaker
as an icon).  Edit the parameters of the ``Play'' star entering 16000
for the gain parameter. (To see details about the ``Play'' star,
execute the ``profile'' command in the ``Other'' menu, or type a comma
(``,'') with the mouse on the ``Play'' icon).
The Sparcstation speaker is driven by a codec that operates at an 8kHz
sample rate.  So running this universe for 40000 samples will produce
about 5 seconds of sound.
The sound produced by the current parameters is not particularly attractive.
Experiment with different parameter values.
Try PI/1000 in place of the PI/50.
.pp
An interesting variant of this system modulates a chirp instead of
a pure sinusoid with a low
frequency sinusoid.  A chirp is sinusoid that scans a frequency range.
You could replace one of your ``sinegen'' instances with something
that generates a chirp, and again experiment with parameters.
.pp
A chirp can be created with three stars: a ``FloatRamp'', an ``Integrator''
and a ``Sin'', connected in series.
The \fIstep\fR parameter of the ``FloatRamp'' should be very small,
such as 0.0001.
With this value, you will hear some aliasing if you create 5 seconds
of sound.
The ``Integrator'' is the seventh star in the fourth row of
``main.pal'', on the right, and its default
parameter values are OK.
Use the ``profile'' command (``,'') to read about it.
Note that a fourth star, a ``FloatDC'' (upper left of ``main.pal'') is
needed to set the ``Integrator'' \fIreset\fR input to zero.
.pp
This is a good time to try out your own examples.  In general,
when you create new galaxies and universes that depend on each
other, it is a good idea to keep them together in one directory.
For example, all of the facets we have created so far are in the
``example'' directory.
You can use the extensive \*(PT demos as models.
.H2 "An Important Note"
.pp
Whenever the contents of a galaxy are changed so that
the new definition has different I/O ports, the icon must be updated as
well.  You can do this by calling \fImake-schem-icon\fP again to replace
the old icon with a new one.
.IE "make-schem-icon"
VEM will not allow you to overwrite the old icon if you have instances
of the old icon in any open window (regardless of whether the window
is iconified).  Hence, you must either close those windows with
``control-d'' or delete the offending icon before replacing
it with a new icon.
.EQ
delim $$
.EN
.\" Local variables:
.\" mode: nroff
.\" End:
