Kepler Hands-On Exercises

Exercise-0: Using Vergil (15 minutes)

Start Vergil [Program Files -> Ptolemy II 3.0.2 -> Vergil-full].
Open a new graph editor [File Menu -> New -> Graph editor].
Double-click on the actor library on the library of components at the left.
Select "Const" from "sources/generic sources" folder, drag-and-drop the actor.
Do the same for "Display" under "sinks/generic sinks"
Link the output port of Const to the input port of Display.
Extend the "director library" and drag-and-drop the SDF director into the model building area.
From the Debug menu, select "Animate Execution". Set the delay to 1000 mSecs.
Save the model using the save under the File menu.
Hit the play button in the toolbar to run your model. (You can also use the "Run Window" item under View menu.)
Now, let's try a little more complicated workflow. Open a new graph editor using the file menu.
Drag-and-drop the "Ramp" actor from "actor library/sources/sequence sources", the "Scale" actor from "actor library/math", the "XYPlotter" actor from "actor library/sinks/generic sinks" and an SDF director.
Configure them as described below:
- Ramp: [init=0, step=1, firingCountLimit=10]
- Scale: [factor=5]
- SDF: [iterations=10]
Customize the name for XYPlotter actor by right-clicking on XYPlotter and choosing "Customize Name" from the context menu. Set the name to "X=FactorY".
Create the links for the workflow shown at [XEqualsFactorY.xml]
You will need a relation (black diamond) to link the output of Ramp to two different inputs.
Save your model under the name "XEqualsFactorY.xml"
To run your workflow, use the "Run Window" item under View menu.

--- End of exercise-0 ---

Preparation for programming exercises: (5 minutes)

Unzip the precompiled Ptolemy II package and kepler package.
Set two environment variables: Set KEPLER to the location of your Kepler, and PTII to the location of your Ptolemy II.
Check your JAVA_HOME environment variable.
Under $KEPLER (cd $KEPLER) directory, enter "ant run". This will open the Kepler starting page. If you see the page, you're ready for the programming exercises.

Exercise-1: Creating your own "HelloWorld" actor (30 minutes)

Use Kepler directory tree and create a directory for yourself under kepler/src/edu/tutorial
Copy HelloWorld.java under your directory and open it with your java editor.

Add this file to your package:


    package edu.tutorial.%YOUR_DIRECTORY%;

Import the necessary classes to add and maintain an output port


    import ptolemy.actor.IOPort;
    import ptolemy.actor.TypedIOPort;
    import ptolemy.data.Token;
    import ptolemy.data.StringToken;
    import ptolemy.data.type.BaseType;
    import ptolemy.data.type.Type;

Define an output port to send your greeting from. Add the following code segment to the place in the code shown by "// Exercise#1: ADD THE OUTPUT PORT DEFINITION HERE."
```
    /** The output port.  The type of this port will be set to String.
     */
    public TypedIOPort output = null;
```

Create the output and set type. Add the follwing 3 lines to the class constructor.


    output = new TypedIOPort(this, "output", false, true);
    // Set the type constraint.
    output.setTypeEquals(BaseType.STRING);

Send the greeting message from your output port. Add to fire method:


    output.send(0, new StringToken("HelloWorld!"));

Comment your code...

Add the class description at the place shown in the file and write your name as the author. As class desription, add:


    "This is the implementation of a HelloWorld actor using Ptolemy II. This actor outputs "Hello World!" as string from its output port."

Add the javadoc description for the class constructor at the place shown in the file.


   /** Construct a HelloWorld source with the given container and name.
     *  @param name The name of this actor.
     *  @exception IllegalActionException If the entity cannot be contained
     *   by the proposed container.
     *  @exception NameDuplicationException If the container already has an
     *   actor with this name.
     */

Add the javadoc description for the fire method at the place shown in the file


    /** Send the token in the value parameter to the output.
     *  @exception IllegalActionException If it is thrown by the
     *   send() method sending out the token.
     */

Compile your code, using "ant compile" comment under $KEPLER
If the compilation has finished successfully, you will be able to run it under Vergil after just one more step.
Add your actor as an entity under the kepler/tutorial library. Open the file "$KEPLER/lib/tutorial.xml"
Update the file in the shown place by:
```
    <entity name="HelloWorld" class="edu.tutorial.%YOUR_DIRECTORY%.HelloWorld"/>
```
Don't forget to change %YOUR_DIRECTORY% with the directory name you have created under the tutorial directory. :-)
And now, you can run your actor! :) Run Kepler using "ant run" comment.
Under Vergil, open a new graph editor using the file menu.
You will see your actor and a 'Display' actor under actor "library/kepler/tutorial".
Create a mini-workflow using these two actors. Link HelloWorld to Display.
Drag and drop an SDF director from the director library and configure it to iterate just once. (Set iterations==1)
Save your workflow with the name "HelloWorldTest.xml" under "$KEPLER/lib". Run your workflow.
Now we will add one more functionality to the actor. We'll add a parameter and use it to greet the user with his/her name.
We need a parameter to accept user's name.

Import the classes to add and maintain a parameter.


    import ptolemy.data.expr.Parameter;

Define the parameter. Add the parameter to the place shown in HelloWorld.


    /** The name of the user.
     */
    public Parameter userName;

Create the parameter in the class constructor. Add the following line to the place shown in the class constructor:
```
    userName = new Parameter(this, "userName", new StringToken(""));
```

Send the personalized greeting :) through the output port. Replace the "output.send(...)" line in the fire method by:


    String userNameStr =  userName.getToken().toString();
    userNameStr = userNameStr.substring(1, userNameStr.length() - 1);
    output.send(0, new StringToken("Hello " + userNameStr + "!"));

You can also use the following two lines instead of these three lines:


    String userNameStr =  ((StringToken)userName.getToken()).stringValue();
    output.send(0, new StringToken("Hello " + userNameStr + "!"));

Notice that you did not need to remove the double-quotes in this one since you directly got the string value of the string token.

We are finished with adding the parameter. Compile your code and run it.
Open the "HelloWorldTest.xml" workflow that you have created using your HelloWorld actor again.
Double-click on the HelloWorld actor and put your name between double-quotes. Save it and run the workflow. You'll see the message. :)

--- End of exercise-1 ---

Exercise-2: Creating a Scale Actor(30 minutes)

Copy Scale.java under your directory and open it with your java editor.

Add this file to your package:


    package edu.tutorial.%YOUR_DIRECTORY%;

Set the type constraint for the polymorphic output port. Add the following line to the constructor:


    // set the type constraints.
    output.setTypeAtLeast(new PortParameterFunction(input, factor));

In the "fire" method, receive the input token from the "input" port.


    Token in = input.get(0);

Add the following implementation for the scale function into the scale function.


    if (input instanceof ArrayToken) {
      Token[] argArray = ( (ArrayToken) input).arrayValue();
      Token[] result = new Token[argArray.length];
      for (int i = 0; i < argArray.length; i++) {
        result[i] = _scale(argArray[i], factor);
      }

      return new ArrayToken(result);
    }
    else {
      return factor.multiply(input);
    }

Call the scale function in the fire method. Add to the fire:


      result = _scale(in, factorToken);

Add your actor as an entity under the kepler/tutorial library.

Open the "XEqualsFactorY.xml" (2nd workflow from Exercise#0.)

Replace the Scale actor with the actor you have just built and run the new model. --- End of exercise-2 ---

Exercise-3: Creating a Stop Actor using the "manager"(20 minutes)

Copy Stop.java under your directory and open it with your java editor.

Add this file to your package:


    package edu.tutorial.%YOUR_DIRECTORY%;

Import the classes for manager and composite actor.

    import ptolemy.actor.CompositeActor;
    import ptolemy.actor.Manager;
    import ptolemy.actor.lib.Sink;

Add the icon description to the class constructor at the place shown by a comment.



    // Icon is a stop sign.
    _attachText("_iconDescription", "<svg>\n"
                + "<polygon points=\"-8,-19 8,-19 19,-8 19,8 8,19 "
                + "-8,19 -19,8 -19,-8\" "
                + "style=\"fill:red\"/>\n"
                + "<text x=\"-15\" y=\"4\""
                + "style=\"font-size:11; fill:white; font-family:SansSerif\">"
                + "STOP</text>\n"
                + "</svg>\n");

Stop the execution at the postfire method by adding the following piece of code to the postfire.(in the place marked) Here, the manager of the top-level composite actor is found and made to call the finish function. Also make sure you go over to code to see that one token from each domain is consumed before the execution is stopped. Think about the reasons of this...(MoCs, deadlocks, etc...)


            Nameable container = getContainer();
            if (container instanceof CompositeActor) {
                Manager manager = ((CompositeActor)container).getManager();
                if (manager != null) {
                    manager.finish();
                } else {
                    throw new IllegalActionException(this,
                            "Cannot stop without a Manager.");
                }

Throw the IllegalActionException if the container is not an instance of CompositeActor. Add the following code to the place pointed in the postfire method code:


                throw new IllegalActionException(this,
                        "Cannot stop without a container that is a CompositeActor.");

Add your actor to your tutorial library and download stopModel.xml.
Open "stopModel.xml" and add you Stop actor after the comparator to stop the execution of the model.

--- End of exercise-3 ---

Exercise-4: Inserting an existing application into Kepler(15 minutes)

Copy FractalDemo.java under your directory and open it with your java editor.

Add this file to your package:


    package edu.tutorial.%YOUR_DIRECTORY%;

Import the application you want to use. Add the following to the import statements:
```
    
    import edu.tutorial.MainFractal;
    
```
In the fire method, invoke the application you want to use. Add the following two lines to the fire method:
```
    
    MainFractal MF = new MainFractal();
    MF.invoke();
    
```
Add your actor to your tutorial library, use it in a workflow and run the workflow.

--- End of exercise-4 ---