Adding An Actor to Ptolemy II

Below are instructions for adding an actor to Ptolemy II and making it visible in Vergil.

Chapter 5, "Designing Actors," of the Volume 1: Introduction to Ptolemy II of the Ptolemy II Design Document at discusses how to design actors, but the design document does not discuss compiling the actor and adding it to Vergil. The reason for this omission is because we are hoping to eventually have a cleaner method for adding actors. The text below is a how-to guide for the current environment

For this example, we are going to take the Ramp actor and change the default step from 1 to 2. The new actor will be called Ramp2.

The instructions below assume that you have installed the Java Development Kit (JDK), which includes the javac binary, that you have a make binary and other tools installed, that Ptolemy II has been installed, and that $PTII/configure and make have been run. For details about the installation process, see $PTII/doc/install.htm

Under Windows XP with JDK1.4 and Cygwin, to do the setup, I did:

bash-2.04$ PTII=c:/ptII4.0
bash-2.04$ export PTII
bash-2.04$ cd "$PTII"
bash-2.04$ ./configure
bash-2.04$ make fast >& make.out
Configure and make usually generate a few warnings.

Below are the steps necessary to add an actor:

  1. Create the new .java file that implements your actor:
    1. In this case, we are just copying a to
      	cd $PTII/ptolemy/actor/lib	
      	cp -p
      Note that if we had copied our java code from a different directory, we would also have to change the package statement (usually near line 31) in the java code. This is good to keep in mind since there is no error message to clue you in to this particular error.

    2. Edit and change:
    3. public class Ramp extends SequenceSource {
      public class Ramp2 extends SequenceSource {
    4.     public Ramp(CompositeEntity container, String name)
                  throws NameDuplicationException, IllegalActionException  {
          public Ramp2(CompositeEntity container, String name)
                  throws NameDuplicationException, IllegalActionException  {
    5.         step.setExpression("1");
    6.         Ramp newObject = (Ramp)super.clone(workspace);
              Ramp2 newObject = (Ramp2)super.clone(workspace);
  2. Edit the $PTII/ptolemy/actor/lib/makefile and add to the value of JSRCS. A good place for this is just after the \ line: \ \ \
 \ \ \ \
    This step is not strictly necessary, but it is good programming practice to put all source files in the makefile. Another reason we add it to the makefile is so that our new actor will be included in the lib.jar file.

  3. Run make in the $PTII/ptolemy/actor/lib directory (which is where you should already be). make will descend into the subdirectories and compile any needed files and eventually run
    rm -f `basename .java`.class
    CLASSPATH="../../.." "/cygdrive/c/jdk1.3/bin/javac" -g -O
    and Ramp2.class will be produced.

  4. Edit $PTII/ptolemy/actor/lib/sequencesources.xml and add Ramp2 just after the lines for Ramp
    <entity name="Ramp" class="">
    <doc>Create a sequence of tokens with increasing value</doc>
    <entity name="Sinewave" class=""/>
    <entity name="Ramp" class="">
    <doc>Create a sequence of tokens with increasing value</doc>
    <entity name="Ramp2" class="">
    <doc>Create a sequence of tokens with increasing value 2</doc>
    <entity name="Sinewave" class=""/>
  5. Start up Vergil.
    bash-2.04$ vergil
    If this does not work, you may not have created an alias for vergil. Try specifying the full path name, like this.
    bash-2.04$ "$PTII/bin/vergil"
  6. In Vergil, click on File -> New -> Graph Editor

  7. In the Graph Editor window, click on actor library -> sources -> SequenceSources
  8. To test the Ramp2 actor:
    1. Drag the Ramp2 actor over to the main canvas on the right
    2. Clock on actor library -> sinks -> GenericSinks and drag a Display actor over to the main canvas
    3. Connect the two actors by left clicking on the output of the ramp2 actor and dragging over to the input of the Display actor
    4. Select director library -> SDF and drag the SDF director over to the right window
    5. Select View -> Run and change the number of iterations from 0 to 10, then hit the Run button.
    6. You should see the numbers from 0 to 18 in the display

Adding a new palette

To add a new set of actors, we first create a .xml file that lists the actor. In this case, the file is called $PTII/ptolemy/actor/lib/myactors.xml, and it contains one actor, Ramp2:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE plot PUBLIC "-//UC Berkeley//DTD MoML 1//EN"
<entity name="myactors" class="ptolemy.moml.EntityLibrary">
<doc>My Actors</doc>
<entity name="Ramp2" class="">
<doc>Create a sequence of tokens with increasing value of 2</doc>


Below we discuss two ways of adding the configuration:
  1. Adding a palette to the user configuration
    Easier to do, works with the Windows installer version, makes your new palette visible in all configurations
  2. Adding a palette to the default configuration
    Harder to do, but useful for developers

Adding a palette to the user configuration

When vergil starts up, it opens the user library, which is located at $HOME/.ptolemyII/UserLibrary.

Under Windows XP, $HOME might be found at c:/Documents and Settings/yourlogin, so the UserLibrary.xml file would be at c:/Documents and Settings/yourlogin/.ptolemyII/UserLibrary.xml

Edit UserLibrary.xml and change:

<entity name="UserLibrary" class="ptolemy.moml.EntityLibrary"/>
<entity name="UserLibrary" class="ptolemy.moml.EntityLibrary">
  <input source="ptolemy/actor/lib/myactors.xml"/>
Note that you must remove the slash in the first line:
<entity name="UserLibrary" class="ptolemy.moml.EntityLibrary"/>
<entity name="UserLibrary" class="ptolemy.moml.EntityLibrary">

After changing UserLibrary.xml, restart vergil and the myactors sub-palette will appear under UserLibrary.

Adding a palette to the default configuration

The palette on the left side of the Graph editor lists the utilities, directors and actors available for use in Vergil.

The palette and menus are determined by configuration files.

The default configuration for $PTII/bin/vergil is located at $PTII/ptolemy/configs/full/configuration.xml. (For further information about how the configuration is specified, see the VergilApplication class documentation.)

$PTII/ptolemy/configs/full/configuration.xml. includes $PTII/ptolemy/configs/defaultFullConfiguration.xml. Eventually, we includ $PTII/ptolemy/configs/basicActorLibrary.xml. We want to add our new palette, myactors.xml, to the actor library palette so we will add myactors.xml to $PTII/ptolemy/configs/basicActorLibrary.xml. Note that we want our new palette to be a sub pallet of the actor library palette, just as the sources palette is. The input statements below do not cause the palette named by the source parameter to be a sub palette. Sub-paletting is caused by the entity statement in the 4th line of your myactors.xml file.

In ptolemy/configs/basicActorLibrary.xml we change

            <input source="ptolemy/actor/lib/sources.xml"/>
            <input source="ptolemy/actor/lib/myactors.xml"/>
            <input source="ptolemy/actor/lib/sources.xml"/>
Then restart vergil, and your myactors sub-palette will appear under 'actor library'.