2.8 Using galaxies

In this section we will explain how to create galaxies. Galaxies allow you to use hierarchy to partition your design into more manageable pieces and to re-use designs as components in other designs.

2.8.1 Creating a galaxy

Use the schematic we created in the last example to make a sine wave generator galaxy.

Instead of modifying our previous example, we will make a copy of it. In your "example" directory, type:

cp -r wave singen

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.

Start pigi.
Use open-palette (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. The contents of the palette are shown below:
Use open-facet (or "F") to open the "singen" you created using "cp -r". You can use the file browser shown on page 2-23; just double click on the name "singen" in the lower window of the browser.
In the "singen" window, delete the XMgraph 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.)
Place an output port where the XMgraph 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), as shown above.
Name the output port "out": - Position the cursor over the black box on the new output port.
- Type "out" as a text argument, including quotation marks.
- Type "c" for create. Again, note that the create command has a different action than before. It names input or output terminals when given a text argument.

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.

2.8.2 Using a galaxy

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 that we will then instantiate in our other design.

Create an icon: - Place cursor in "singen:schematic" window.
- Execute make-schem-icon in the pigi "Extend" menu ("@").
- The dialog box should contain:
Palette: ./user.palThis 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.
- 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 make-schem-icon is done. Vem informs you that it is done with a message in the vem console window, which may be buried by now.
Open the palette called "user.pal" using open-palette ("O"). The newly created galaxy icon should appear in this palette along with the same special icon we saw before, called a cursor. A cursor distinguishes a palette from other types of facets and it determines where the next icon will be placed.
At this point, we have an icon for our sine wave generator galaxy. It is this icon facet that is instantiated in the "user.pal" palette. We can now use our sine generator galaxy simply by instantiating our icon into another schematic.
Use open-facet to create a new facet with the name "modulation".
In the "modulation" window, create a universe that takes two "singen" galaxies, multiplies their outputs together, and then plots the result using "XMgraph". The "XMgraph" star can be found again in the "Signal Sinks" subpalette of the SDF palette. The multiplier star, called Mpy, is in the "Arithmetic" subpalette.

Hint: 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.

Now run the universe with "when to stop" set to 100. The output should appear as a squared sine wave, which is just a sine wave of twice the frequency shifted up by 1/2.

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.

2.8.3 Galaxy and 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.

To make a galaxy parameterizable, we create formal parameters in the galaxy and then link the formal parameters to the actual parameters 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.

Create formal parameters: - Place the cursor in the "singen" window but away from any instance, i.e., in the grey background of the facet.
- Execute edit-params ("e"). An empty parameter window will appear, looking like this:

To add parameters to the galaxy, click on the "Add parameter" button. A window appears looking like this:
Fill in the dialog as follows:

	name: freq

	type: float

	value: PI/50

The value will be the default value. Then click on "OK". Recall that you can use "tab" to move from one field to the next of the dialog box and "Return" instead of "OK". Hence, the dialog can be managed from the keyboard without requiring the mouse.

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. The default value of a formal parameter can always be changed by executing edit-params in the background of the galaxy. Executing edit-params on the icon representing the galaxy changes the parameter values only for the instance represented by the icon. It overrides the default value specified in the background of the galaxy definition. The possible types for parameters are listed in table

2-6. The syntax for specifying values for parameters is described above in "Changing or setting parameters" on page 2-15. Exactly the same procedure can be used to attach formal parameters to a universe. This allows you to parameterize a complete Ptolemy application.

Link formal parameters to actual parameters: - Place the cursor over the Ramp icon in the singen window.
- Execute edit-params and fill in the dialog as follows:
step: freq value: 0.0This allows the freq parameter of a singen instance to control the increment of the internal ramp star, thus controlling the output frequency.
Change the frequency of one of the singen instances to "PI/5" by using edit-params. This singen will be ten times the frequency of the other.
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.