• 2.8.1 Creating a galaxy
• 2.8.2 Using a galaxy
• 2.8.3 Galaxy and universe parameters

2.8.1 Creating a galaxy

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

• 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-35; 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

• 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.pal
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.

  - 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

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:

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

• 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.0
This 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.