Adding An Actor to Ptolemy II

Chapter 5, "Designing Actors," of the Volume 1: Introduction to Ptolemy II of the Ptolemy II Design Document at http://ptolemy.eecs.berkeley.edu/ptolemyII/designdoc.htm 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

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 Ramp.java to Ramp2.java

      	cd $PTII/ptolemy/actor/lib	
      	cp -p Ramp.java Ramp2.java
      	

      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 Ramp2.java and change:

      public class Ramp extends SequenceSource {
      

      to

      public class Ramp2 extends SequenceSource {
      

          public Ramp(CompositeEntity container, String name)
                  throws NameDuplicationException, IllegalActionException  {
      

      to

          public Ramp2(CompositeEntity container, String name)
                  throws NameDuplicationException, IllegalActionException  {
      

              step.setExpression("1");
      

      to

              step.setExpression("2");
      

              Ramp newObject = (Ramp)super.clone(workspace);
      

      to

              Ramp2 newObject = (Ramp2)super.clone(workspace);
      

2. Edit the $PTII/ptolemy/actor/lib/makefile and add Ramp2.java to the value of JSRCS. A good place for this is just after the Ramp.java \ line:

   	Quantizer.java \
   	Ramp.java \
   	RandomSource.java \
   

   	Quantizer.java \
   	Ramp.java \
   	Ramp2.java \
   	RandomSource.java \
   
   

   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 Ramp2.java .java`.class
   CLASSPATH="../../.." "/cygdrive/c/jdk1.3/bin/javac" -g -O Ramp2.java
   

   and Ramp2.class will be produced.

4. Edit $PTII/ptolemy/actor/lib/sequencesources.xml and add Ramp2 just after the lines for Ramp
   Change:

   <entity name="Ramp" class="ptolemy.actor.lib.Ramp">
   <doc>Create a sequence of tokens with increasing value</doc>
   </entity>
   
   <entity name="Sinewave" class="ptolemy.actor.lib.Sinewave"/>
   
   

   To:

   <entity name="Ramp" class="ptolemy.actor.lib.Ramp">
   <doc>Create a sequence of tokens with increasing value</doc>
   </entity>
   
   <entity name="Ramp2" class="ptolemy.actor.lib.Ramp2">
   <doc>Create a sequence of tokens with increasing value 2</doc>
   </entity>
   
   <entity name="Sinewave" class="ptolemy.actor.lib.Sinewave"/>
   
   

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

<?xml version="1.0" standalone="no"?>
<!DOCTYPE plot PUBLIC "-//UC Berkeley//DTD MoML 1//EN"
    "http://ptolemy.eecs.berkeley.edu/xml/dtd/MoML_1.dtd">
<entity name="myactors" class="ptolemy.moml.EntityLibrary">
  <configure>
    <?moml
      <group>
<doc>My Actors</doc>
<entity name="Ramp2" class="ptolemy.actor.lib.Ramp2">
<doc>Create a sequence of tokens with increasing value of 2</doc>
</entity>

      </group>
    ?>
  </configure>
</entity>

<entity name="UserLibrary" class="ptolemy.moml.EntityLibrary"/>

<entity name="UserLibrary" class="ptolemy.moml.EntityLibrary">
<group>
  <input source="ptolemy/actor/lib/myactors.xml"/>
</group>
</entity>

<entity name="UserLibrary" class="ptolemy.moml.EntityLibrary"/>

<entity name="UserLibrary" class="ptolemy.moml.EntityLibrary">

            <input source="ptolemy/actor/lib/sources.xml"/>

            <input source="ptolemy/actor/lib/myactors.xml"/>
            <input source="ptolemy/actor/lib/sources.xml"/>