Ptolemy II Frequently Asked Questions

This FAQ can be found at: http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIfaq.htm
The version of this FAQ is: $Id: ptIIfaq.htm,v 1.58 2006/10/26 19:18:11 cxh Exp $
  • 1. General
  • 1.1 What is Ptolemy II?
  • 1.2 What is the copyright?
  • 1.3 Is there a mailing list?
  • 1.4 Is there a bug list?
  • 2. Relationship with other packages
  • 2.1 What about compatibility with Ptolemy Classic (Ptolemy 0.7.x)?
  • 2.2 How are Ptolemy II and Matlab/Simulink different?
  • 2.3 What is the relationship between Ptolemy and Metropolis?
  • 2.4 What is the relationship between Ptolemy and Kepler?
  • 3. Installation questions
  • 3.1 How do I download Ptolemy II?
  • 3.2 What platforms does Ptolemy II run under?
  • 3.3 What do I need to Install Ptolemy II?
  • 3.4 How do I get CVS access to PtolemyII
  • 4. Using Ptolemy II
  • 4.1 How do I invoke Ptolemy II?
  • 4.2 Ptolemy II is hanging, how do I get a stack trace?
  • 4.3 How do I read data from a file?
  • 5. Extending Ptolemy II
  • 5.1 How do I add an actor?
  • 5.2 How do I add a configuration?
  • 5.3 How do I add a type?
  • 5.4 What makes an actor domain polymorphic?
  • 5.5 How do I interface to C/C++
  • 5.6 How do I customize the GUI?
  • 5.7 What file format are the models stored in?
  • 5.8 Is there a scripting interface to Ptolemy II?
  • 5.9 What about Code Generation?
  • 5.10 Does the Ptolemy project take software contributions?
  • 1. General

    1.1 What is Ptolemy II?

    Ptolemy II is a software framework developed as part of the Ptolemy project. It is a Java-based component assembly framework with a graphical user interface called Vergil. Vergil itself is a component assembly defined in Ptolemy II.

    The Ptolemy project studies modeling, simulation, and design of concurrent, real-time, embedded systems. The focus is on assembly of concurrent components. The key underlying principle in the project is the use of well-defined models of computation that govern the interactions between components. A major problem area being addressed is the use of heterogeneous mixtures of models of computation.

    The Ptolemy Project (http://ptolemy.eecs.berkeley.edu) contains much more information about the project. The work is conducted in the Department of Electrical Engineering and Computer Sciences of the University of California at Berkeley. The project is directed by Prof. Edward A. Lee (http://ptolemy.eecs.berkeley.edu/~eal) The project is named after Claudius Ptolemaeus, the second century Greek astronomer, mathematician, and geographer.

    1.2 What is the copyright?
    Ptolemy II is released under the fairly liberal UC Berkeley copyright, see http://ptolemy.eecs.berkeley.edu/ptIIcopyright.htm Most files have the copyright at the top.

    Ptolemy II is free for academic and commercial use. You an incorporate it into products, but you need to include follow the instructions in the copyright notice.

    This copyright is based on the Tcl copyright that was used when Prof. Ousterhout was developing Tcl here at UC Berkeley. This copyright was also used in Ptolemy Classic, which has been used in commercial products, see http://ptolemy.eecs.berkeley.edu/archive/links.htm

    1.3 Is there a mailing list?
    The Ptolemy mailing lists are run by the Majordomo mailing list server. This server can automatically subscribe you to mailing lists and it can send you monthly archive files for each of the lists. To find out more about our Majordomo sever, send an email letter to: majordomo@ptolemy.eecs.berkeley.edu with the word "help" in the body of the letter.
    Ptolemy Interest Mailing list
    This moderated mailing list is for Ptolemy announcements only. Thus, you cannot post to this group. The amount of mail here is kept very light (a few messages a year).

    To subscribe to the ptolemy-interest mailing list, send mail to: ptolemy-interest-request@ptolemy.eecs.berkeley.edu with the word "subscribe" in the body (not the subject) of the letter.

    All mail to ptolemy-interest also goes to ptolemy-hackers, so if you subscribe to ptolemy-hackers, there is no need to subscribe to ptolemy-interest too.

    Ptolemy Hackers Mailing list
    This is a discussion list for Ptolemy questions, bug reports, and to share Ptolemy additions and applications. Since this is a discussion group, mail volume can sometimes be heavy. All mail sent to Ptolemy- hackers is automatically cross posted to the comp.soft-sys.ptolemy newsgroup.

    To subscribe to the ptolemy-hackers mailing list, send mail to: ptolemy-hackers-request@ptolemy.eecs.berkeley.edu with the word "subscribe" in the body of the letter. To leave the newsgroup put the word "unsubscribe" in the body of your message.

    The best way to get questions answered is to subscribe to ptolemy-hackers and then send email to that list.

    Ptolemy is distributed without support or warranty. However, if you really need to contact a human being with a Ptolemy question, you can send email to: ptolemy at eecs berkeley edu.

    The Ptolemy Mailing lists and search engine can be found at http://ptolemy.eecs.berkeley.edu/search/

    1.4 Is there a bug list?
    Current bugs are listed in http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/limitations.htm and in $PTII/doc/limitations.htm

    If you find a bug, please report it using Ptolemy-hackers mailing list.

    A good bug report includes:

  • The version of Ptolemy you are running (5.0? 6.0)
  • Whether you built it from CVS sources or from the sources shipped with the Windows installer or are running from the Windows installer.
  • Your platform (Windows? Linux) and version, along with the the version of Java you are running
  • Important: a small test model, or else really detailed instructions on how to replicate the bug, what happened for you and what you expected to happen.
  • There is also a Bugzilla bug handler. To use bugzilla, you will need an account on the Chess, Embedded or Trust websites. If you do not have an account, request a ptexternal workgroup on the Chess website:
    Chess website account request
    For more information, see the Chess Bugzilla Help Page.

    2. Relationship with other packages

    2.1 What about compatibility with Ptolemy Classic (Ptolemy 0.7.x)?

    This FAQ covers Ptolemy II. The Ptolemy Classic FAQ can be found at http://ptolemy.eecs.berkeley.edu/ptolemyclassic/ptolemy.faq

    Ptolemy 0.x is fairly mature software in that the design is stable and mostly unchanging. The Ptolemy II software system is under active development.

  • They are written in different languages (Java vs. C++)
  • They have different file formats. Ptolemy 0.x uses Octtools, Ptolemy II uses a system based on XML
  • They have different user interfaces. The Ptolemy II UI is much easier to use than the Ptolemy Classic UI.
  • Ptolemy Classic works best under Unix. There is a Windows port of Ptolemy Classic, but it does not work well.
    Ptolemy II works under both Unix and Windows.
  • Ptolemy Classic can generate code for various DSP primarily using SDF semantics.
    Ptolemy II can generate code for non-hierarchical SDF models and for hierarchical Giotto models.
  • For more information about the current status of code generation in Ptolemy II, see 5.9 What about Code Generation?

    Various people have made efforts to use a different front end with Ptolemy Classic. See the Ptolemy Website Links Page for possible solutions, including:

  • MLDesigner 2.1 is a commercial product that was released in January 2002 and it includes a conversion utility from Ptolemy Classic models.
  • The PeaCE (Ptolemy extension as Codesign Environment) might offer some ideas and does have some software available.
  • The 2001 Ptolemy Miniconference had the following talk:

    "An Approach to Executing Ptolemy Classic Models under Ptolemy II" Ned Stoffel, Dwight Richards, Neil Smyth*, and Matt Goodman, Telcordia Technologies, Inc. (* Smyth is now with Altio).

    The slides for this talk can be found at http://ptolemy.eecs.berkeley.edu/conferences/01/src/miniconf/Telcordia.pdf
    We are not sure if Telcordia has any software available for release.

  • 2.2 How are Ptolemy II and Matlab/Simulink different?
    Ptolemy II has very little in common with Matlab, which is a textual, imperative, interactive, scientific programming language. Ptolemy II works with Matlab, thanks to an interface developed by Zoltan Kemenczy and others at Research In Motion, Ltd. See http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/ptolemy/matlab/matlab.htm

    Ptolemy II has much more in common with Simulink, which is a graphical block-diagram language, originally developed for control system design. Simulink has a rich and expressive model of computation with continuous-time semantics and support for periodic discrete-time signals. Some of its principles have been incorporated in the CT (continuous-time) domain of Ptolemy II, but not all. The CT domain, for example, does not have the notion of "sample time" (which in Simulink provides the periodic discrete-time support) nor the support for algebraic loops. There is also currently no code generation support in CT (in Simulink, this is provided through the associated product Real-Time Workshop). Also, the CT domain has implemented fewer ODE solvers than those provided by Simulink and has a smaller actor library.

    Ptolemy II and Simulink both support extension of the actor library through well-defined interfaces (in Simulink, this is called the S-function interface). However, Ptolemy II is a more open architecture in that its infrastructure is open source, and the interfaces to the core mechanisms in the software are published and documented. The persistent file format (MoML) is XML in Ptolemy II, which makes it both more verbose and more portable than the Simulink syntax (MDL files). Simulink supports one model of computation, whereas Ptolemy II supports several, and can be extended with new models of computation. Simulink can also be extended, as for example it has been with the associated product Stateflow, which supports state-machine modeling. But in Simulink, the extension is done by defining new blocks using the S-function interface. As such, additional models of computation added this way are second class. For example, they cannot define the model of computation at the top level of the hierarchy, and cannot contain Simulink models within their own components.

    2.3 What is the relationship between Ptolemy and Metropolis?
    Ptolemy (http://ptolemy.eecs.berkeley.edu) and Metropolis (http://embedded.eecs.berkeley.edu/metropolis/) are separate research projects at Berkeley, albeit ones with considerable cross-influences. Ptolemy is headed by Edward Lee, while Metropolis is headed by Alberto Sangiovanni-Vincentelli.
    A key principle in Metropolis is its "meta model," which in the terminology of the Ptolemy project we would call its "abstract semantics." In Metropolis, models consist of processes, with their own thread of control, that communicate through ports and "media." The media are roughly equivalent to Ptolemy Receivers; they define the communication semantics between components. The abstract semantics of Metropolis, is an abstraction of the model of computation that appears in the Ptolemy PN and CSP domains. It is an abstraction because in Metropolis, the communication semantics is not defined, whereas in PN and CSP, it is (in two different ways). Metropolis model builders construct the media that processes use to communicate. One could build, for example, media in Metropolis to implement either PN or CSP. Moreover, Metropolis model builders construct much of what would be the director in a Ptolemy model.

    In Ptolemy, two parts of the abstract semantics are separated, control and communication. The abstract semantics of control is based on the Executable interface. The abstract semantics of communication is based on the IOPort/Receiver interface. The Metropolis metamodel is more fixed about control semantics (i.e. components are process based), but allows a richer interface to communications media (since a media can expose arbitrary interfaces to components). This design choice makes communication refinement easier (since the interface to a media can change) but makes it more difficult to build domain-polymorphic components since media often have different interfaces. It also emphasizes process-oriented concurrency that often exists at the top-level of a system, and de-emphasizes the construction of hierarchical models.

    The abstract semantics that binds most Ptolemy domains (with the exception of PN and CSP) is significantly different. Instead of processes, components are actors with three-phase firings. The objective of this abstract semantics is to be able to define "domain polymorphic" actors, which are actors that operate in several models of computation. This enables hierarchically composing distinct models of computation, since an aggregation of actors in one domain becomes an actor in another. No such composition is possible (by any method we know of) with processes. Indeed, both PN and CSP do not compose well with other domains. There is no useful way to embed PN or CSP models within other, firing-based models of computation.

    A key reason for the choice of abstract semantics in Metropolis is the desire to model several aspects of a system, including particularly its performance when mapped to hardware resources. The separate threads of control model parallel hardware systems well, and mesh well with trends in hardware design.

    Processes in Metropolis are defined in a Java-like syntax, and use a model of computation in which components are processes with global synchronization points. Constraints are an explicit, declarative manner to specify requirements on performance (e.g. power or timing) and sharing of computation and communication resources. For example, timing constraints are expressed in linear temporal logic and timed logic. A variety of back-ends have been built or are under construction, to perform simulation, formal verification and synthesis, including ones that target Java, SystemC, and C.

    By contrast, in Ptolemy, actors are defined in ordinary Java. More easily retargetted actor-definition languages are under development, including Cal (http://embedded.eecs.berkeley.edu/caltrop). and Actif (http://embedded.eecs.berkeley.edu/compose).

    One of the key innovations in Metropolis is the notion of "quantity managers." Quantity managers contain code that is invoked when a request is made to annotate a process transition with a quantity, such as time, energy, or memory. Such requests are made, for example, on the execution of a statement, or on a communication action over a medium. A special case of quantity manager is the global time manager, which is used to implement a discrete event semantics, where events are processed in chronological order. Constraints in terms of quantities are expressed formally in the Logic Of Constraints, a logic particularly suitable for specifying constraints at the abstract system level, where coordination of executions, not the low level interaction, is of concern. LOC is a formalism designed to reason about simulation traces. It consists of all the terms and operators allowed in sentential logic, with additions that make it possible to specify system level quantitative constraints.

    In Ptolemy, quantity managers would be associated with the director, although no director has been developed (to our knowledge) with such a broadly applicable mechanism.

    2.4 What is the relationship between Ptolemy and Kepler?
    Ptolemy (http://ptolemy.eecs.berkeley.edu) and The Kepler Project (http://www.kepler-project.org/) are two separate projects. The Kepler Project FAQ says
    What is the difference between Kepler and Ptolemy?
    Roughly speaking, Ptolemy aims at modeling concurrent systems, studying system models, various models of computation, etc. as explained above. In constrast, Kepler aims at execution of scientific workflows (by end users and/or workflow engineers), inheriting modeling and design capabilities including the Vergil GUI and workflow scheduling and execution capabilities from Ptolemy.

    How does Kepler extend Ptolemy?
    Kepler extensions to Ptolemy include an ever increasing number of components (called actors in Ptolemy terminology) aimed particularly at scientific applications, e.g., for remote data and metadata access, data transformations, data analysis, interfacing with legacy applications, web service invocation and deployment, provenance tracking, etc. Target application areas include bioinformatics, cheminformatics, ecoinformatics, and geoinformatics workflows among others.

    Kepler also inherits from Ptolemy the actor-oriented modeling paradigm that separates workflow components from the overall workflow orchestration (via so-called directors), making components more easily reusable. Through actor-oriented and hierarchical modeling features built into Ptolemy, Kepler scientific workflows can operate at very different level of granularity, from low-level "plumbing workflows" that explictely move data around, start and monitor remote jobs, etc. to high-level "conceptual workflows" that interlink complex, domain specific data analysis steps.

    3. Installation questions

    3.1 How do I download Ptolemy II?
    Ptolemy II is available in several formats including applets, source code, a Windows installer and Web Start. For details, see http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/
    3.2 What platforms does Ptolemy II run under?
    Ptolemy II is written in Java, so it should run on any platform that supports a recent Java Virtual machine. Locally, we use Windows XP with the Cygwin toolkit for development. The nightly builds run under Solaris 8. Some people in the group use Linux.
    3.3 What do I need to Install Ptolemy II?
    At the minimum, you need the Java Runtime Environment. For details, see the installation pages at http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/
    3.4 How do I get CVS access to PtolemyII
    CVS access to the Ptolemy II development tree is available. Instructions can be found at http://chess.eecs.berkeley.edu/ptexternal

    4. Using Ptolemy II

    4.1 How do I invoke Ptolemy II?
    If you install Ptolemy II using the Windows installer, then menu choices should be added to Start -> Programs -> Ptolemy.

    Ptolemy II models can be run from the command line, this is what we do for the nightly test suite.

    $PTII/bin/vergil foo.xml
    will bring up a visual editor for the model defined in foo.xml. The visual editor allows you to change the model and run it.
    $PTII/bin/ptolemy foo.xml
    will bring up a run control panel for that model and allow you to run it
    $PTII/bin/ptexecute foo.xml
    will run the model. The model need not be graphical.
    java -classpath $PTII ptolemy.actor.gui.MoMLSimpleApplication foo.xml
    will run the model without requiring a connection to a display. Use this method for running models as part of cron jobs etc.

    MoMLApplication supports setting top level parameters using command line arguments.

    The MoMLApplication docs say:

    If a Ptolemy model is instantiated on the command line, either by giving a MoML file or a -class argument, then parameters of that model can be set on the command line. The syntax is:
       ptolemy modelFile.xml -parameterName value
       
    where parameterName is the name of a parameter relative to the top level of a model or the director of a model. For instance, if foo.xml defines a toplevel entity named x and x contains an entity named y and a parameter named a, and y contains a parameter named b, then:
       ptolemy foo.xml -a 5 -y.b 10
       
    would set the values of the two parameters.

    Note that strings need to be carefully backslashed, so to set a parameter named c to the string "bar" it might be necessary to do something like:

       ptolemy foo.xml -a 5 -y.b 10 -c \\\"bar\\\"
       
    The reason the backslashes are necessary is because ptolemy is a shell script which tends to strip off the double quotes.
    Toplevel parameters can be set by calling vergil with a similar syntax:
    $PTII/bin/vergil foo.xml -a 5 -y.b 10
    
    or
    $PTII/bin/ptexecute foo.xml -a 5 -y.b 10
    
    Note that MoMLSimpleApplication does not do this type of command line parsing.

    If you want to start Vergil by hand, the answer depends on which version of Ptolemy II you are using.

    If you downloaded the source files and compiled them, then the only jar file that might need to be included is diva.jar. Releases after Ptolemy II 3.0.2 include the diva source files, so in theory,

    java -classpath "$PTII" ptolemy.vergil.VergilApplication
    
    should work.

    Under Windows with Cygwin with Ptolemy II 3.0.2 and earlier, try:

    java -classpath "$PTII;$PTII/lib/diva.jar" ptolemy.vergil.VergilApplication
    

    If you have chose the Windows Installer, then the individual .class files have been placed in jar files Vergil uses the following jar files

    • ./ptolemy/ptsupport.jar
    • ./ptolemy/vergil/vergil.jar
    • ./ptolemy/lib/diva.jar
    • ./ptolemy/domains/domains.jar
    • ./ptolemy/copernicus/copernicus.jar
    The directory where Ptolemy II is installed should also be in the classpath.

    To start Vergil by hand when the Ptolemy II was installed from the Windows installer, try starting up by cd'ing to where the release is installed and typing in the following (all on one line)

    java -classpath ".;./ptolemy/ptsupport.jar;\
    ./ptolemy/vergil/vergil.jar;./lib/diva.jar;\
    ./ptolemy/copernicus/copernicus.jar;\
    ./ptolemy/domains/domains.jar"\
     ptolemy.vergil.VergilApplication
    
    See also 5.2 How do I add a configuration?
    4.2 Ptolemy II is hanging, how do I get a stack trace?
    If Ptolemy II is hanging, try generating a stack trace using one of the following methods:

    Under Windows, when you have built from source, try using "Control-Backslash", that is holding the Control key down and hitting the backslash key. Note that the Window that started the java process should have the focus when you hit Control-Backslash. Sometimes Function-Break or Control-Break will also work.

    Under Unix, try using kill -3 on the Java process id. To get the Java process id, use the ps command. For example:

    $PTII/bin/vergil
    ps | grep java
    Note the process id (pid) of the java process
    kill -3 pid
    

    If you are running Ptolemy II using the Windows installer, then standard out and standard error will be hidden. To work around this:

    1. Go to the directory where Ptolemy II is located and open the corresponding .lax file.
      For example, Ptolemy II 5.0 is usually installed in c:/Ptolemy/ptII5.0 and there is vergil-full.lax file that is read when vergil-full.exe is run. So, vergil-full.lax is the file to edit.
    2. In the .lax file, change
      lax.stderr.redirect=
      
      to
      lax.stderr.redirect=console
      
      and
      lax.stdout.redirect=
      
      to
      lax.stdout.redirect=console
      
    3. Start up vergil-full and two windows will appear, one is the regular vergil splash screen, the other is a window titled vergil-full.exe that contains the console output.
    4. Click on the vergil-full.exe window and hit Control-Backslash. If that does not work, try Control-Break and Function-Break.
    5. The stacktrace should appear in window. If it does not, try invoking Ptolemy II by hand
    6. To copy the stack trace from the vergil-full.exe window, click on the small Mr. Ptolemy Icon on the upper left side of the Window title bar, select Properties -> Options -> Quick Edit Mode. Then click OK twice to close the dialog.
      In the vergil-full.exe window, drag the mouse over the text and hit return. Then paste the text into a file.
    4.3 How do I read data from a file?

    Actors that read and write data are visible in Vergil under Actors -> IO.

    When an actor takes a URL as an argument, use file:./filename. For details, see the Ptolemy II 2.0.1 DoubleReader actor at http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/codeDoc/ptolemy/actor/lib/DoubleReader.html

    Ptolemy II 3.0.2 and later includes http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/codeDoc/ptolemy/actor/lib/LineReader.html - Reads a file or URL, one line at a time, and outputs each line as a String.

    Ptolemy II 3.0.2 and later also includes http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/codeDoc/ptolemy/actor/lib/ExpressionReader.html - Reads a file or URL, one line at a time, evaluates each line as an expression and outputs the tokens resulting from the evaluation.

    These actors use a

    FileParameter to specifies a file or URL.

    Actors that have Parameters may read data using the readFile, findFile and readMatrix expression operators, see http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/expressions.htm and http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/codeDoc/ptolemy/data/expr/UtilityFunctions.html

    The way to use readFile is as an expression:

    eval(readFile("foo.txt"))
    
    where foo.txt contains a single line that gets parsed as a Ptolemy expression. For example, if foo.txt contained
    {1.0, 2.0}
    
    Then the expression would resolve to an array of two elements, 1.0 and 2.0.

    ptII/ptolemy/data/expr/Constants.java defines PTII and HOME as variables like PI and true. PTII can be used in an expression to refer to a file relative to the Ptolemy II installation directory.

    PTII is the value of the ptolemy.ptII.dir Java property, which is set when vergil is invoked.

    HOME is the value of the user.dir property. Unsigned applets can read user.dir

    The expression language includes the property() method that will read Java properties from the local environment.

    property("ptolemy.ptII.dir") is set to the value of $PTII when vergil etc. are invoked.

    For example:

    property("ptolemy.ptII.dir") + "/ptolemy/actor/lib/test/auto/FileWriter1Output.txt"
    

    5. Extending Ptolemy II

    5.1 How do I add an actor?
    See the Add Actor link in http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/coding/
    5.2 How do I add a configuration?
    When the $PTII/bin/vergil command is invoked, it reads the Ptolemy II onfiguration from $PTII/ptolemy/configs/full/configuration.xml. Other configurations may be read by passing command line options to vergil. For example, $PTII/bin/vergil -ptiny invokes the "Ptiny" version of Ptolemy II, which is a subset of the full set of actors and directors. To see a complete set of configurations, run $PTII/bin/vergil -help.

    To add a configuration, start with a configuration that is close to what you want, copy the files from that configuration and modify them.

    For example, we create "mypt" from the full configuration:

    1. Copy the full configuration
      cd $PTII/ptolemy/configs
      cp -r full mypt
      
    2. Edit the doc attribute in mypt/configuration.xml and mypt/intro.htm and mypt/welcomeWindow.htm to describe the configuration
    3. Update the mypt/makefile
    4. Run your configuration with vergil -mypt
    5. full/configuration.xml and mypt/configuration.xml merely read in $PTII/ptolemy/configs/defaultConfiguration.xml See the other configurations for ways to build smaller configurations.

    See also 4.1 How do I invoke Ptolemy II?

    5.3 How do I add a type?
    The Ptolemy Type system is covered in a chapter in "Volume 2: Ptolemy II Software Architecture," which can be found via http://ptolemy.eecs.berkeley.edu/ptolemyII/designdoc.htm

    The Ptolemy Type system has a type lattice that is implemented in classes in ptolemy.data.type. A common misconception is that to add a type, one needs to add the new type to the type lattice by editing ptolemy.data.type.BaseType. However, you need only add a type to the type lattice if you want to automatically convert your type to preexisting types (other than UNKNOWN and GENERAL). If you have a type class, then the type system will check types for you. For examples, see $PTII/ptolemy/data/type/test/TestToken.java and $PTII/ptolemy/actor/lib/Security/KeyToken.java.

    5.4 What makes an actor domain polymorphic?
    As for making actors domain polymorphic, the general rule we follow is:
  • return false in prefire() if there is insufficient input data to fire
  • consume a token at each input if one is present in fire()
  • produce outputs in fire()
  • update the state of the actor in postfire(), not fire
  • If more than one output token is produced on an output port or consumed on an input port in fire(), then the input port should have a tokenConsumptionRate parameter or the output port tokenProductionRate Parameter indicating how many tokens are produced. (To see sample values, in the FIR actor, right click on the input or output port and select configure).

    If these rules are followed, then the actor will work in at least: DE, SDF, CT, PN, SR, CI
    The most difficult of the rules to follow is updating the state only in postfire(). This rule only matters in CT because CT may have to backtrack time

    5.5 How do I interface to C/C++
    Ptolemy II is written in Java, and Java has the Java Native Interface (JNI), see Sun's JDK1.4 JNI Enhancements page at http://java.sun.com/j2se/1.4/docs/guide/jni/index.html.

    Vincent Arnould and others at Thales have implemented a prototype of an interface between Ptolemy II actors and C code using the Java Native Interface (JNI), see http://ptolemy.eecs.berkeley.edu/ptolemyII/ptII4.0/ptII/doc/codeDoc/jni/package-summary.html. (This interface shipped in Ptolemy II 4.0, but not in Ptolemy II 5.0).

    Zoltan Kemenczy and others at Research In Motion, Ltd. developed an interface to Matlab that uses JNI, see http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/ptolemy/matlab/matlab.htm

    Using JNI to interface to a C/C++ package on one platform is fairly straightforward, but it can be difficult to configure the paths that JNI in truly platform independent manner so that the same code will work on multiple platforms.

    5.6 How do I customize the GUI?
    Ptolemy II uses Diva to display block diagram editors.
    Information about Diva can be found at http://embedded.eecs.berkeley.edu/diva Ptolemy II uses the notion of Tableaus to manage state for tools. The Ptolemy II design document has a chapter that discusses the UI API.

    The code that brings up the JVM Properties window is a simple example, the code is at http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/ptolemy/actor/gui/JVMTableau.java

    $PTII/ptolemy/configs/vergilConfiguration.xml adds this feature with this line:

           <property name="JVM Properties" 
                      class="ptolemy.actor.gui.JVMTableau$Factory"/>
    
    5.7 What file format are the models stored in?
    Ptolemy II stores models in an XML format called MoML. The design doc covers MoML in detail.

    The beauty of using a human readable (though verbose) file format is that we can use standard tools like XSLT and sed to transform models.

    5.8 Is there a scripting interface to Ptolemy II ?
    The PythonScript actor includes and interface to Jython, a Java implementation of Python. The PythonScript actor allows the user to define an actor on the fly by defining the fire() and other methods in Python. Using an interpreted language in this context instead of defining actors in Java means that we need not recompile and restart Ptolemy II to make a change to an actor. The tradeoff is that a PythonScript actor will run more slowly than a similar actor implemented in Java.
    For details, see http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/codeDoc/ptolemy/actor/lib/python/PythonScript.html

    The Ptolemy II test suite uses Jacl, a Java implementation of Tcl as a scripting language. With Jacl, we can build and run models using an interpreted scripting environment without compilation and avoiding the usual edit/compile/run loop.
    For details, see the Testing link in http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/coding/

    5.9 What about Code Generation?
    Ptolemy II include a code generator developed by Stephen Neuendorffer that reads non-hierarchical SDF models and generates Java .class files. This code generator is called Copernicus. We call this the deep code generator. The code that is produced by deep codegen uses very little of the Ptolemy infrastructure. The ptolemy.math package is used sometimes.

    In addition, Copernicus can read in models from other domains and generate a .class file that uses much more of the Ptolemy infrastructure. We call this the shallow code generator.

    Copernicus can also read in models and generate applets.
    To generate an applet within the Ptolemy II tree, try

    cd $PTII/ptolemy/domains/sdf/demo
    mkdir ButterflyTest
    cp Butterfly/Butterfly.xml ButterflyTest/ButterFlyTest.xml
    $PTII/bin/copernicus -codeGenerator applet -targetPath ptolemy/domains/sdf/demo/ButterflyTest ButterflyTest.xml
    

    The Copernicus deep and shallow codegenerators can use treeshaking to run the model, make a list of the classes that are used and create a jar file that contains only those class files. We can also use the Jode obfuscator to reduce jar file size. We've had limited success using the deep and shallow code generators with the GNU gcj compiler to create small standalone binaries.

    Another Copernicus effort is the C code generator, which was created by Ankush Varma and Professor Shuvra S. Bhattacharyya of the University of Maryland, The Copernicus C code generator generates C files for certain SDF models. This C code generator is still very experimental.

    For more information about the Copernicus code generator, see http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/codegen.htm
    and
    Stephen Neuendorffer, Actor-Oriented Metaprogramming, PhD Thesis, University of California, Berkeley, December 21, 2004.
    and
    Ankush Varma, "Retargetable Optimizing Java-to-C Compiler for Embedded Systems," Master's Report, Department of Electrical and Computer Engineering, University of Maryland, College Park, MD, 2003.

    As of Ptolemy II 4.0, no further development is occuring in Copernicus. However, the Ptolemy group is developing a Ptolemy Classic style code generator that uses template files to build C files. This code generator is not available in Ptolemy II 5.0, but is available via CVS and will ship in May, 2006.

    The current template effort synthesizes C code from certain Ptolemy II models (synchronous dataflow and heterochronous dataflow are functional, SR, and DE are being planned). In this technology, we define "helper" classes associated with Ptolemy II actors that define the C code implementation for the actor. The code generator functions (as in Giotto) to coordinate the components. This effort is focused on efficiency. Our objective is to generate zero-overhead C code. We have simple demo systems and a limited actor library.

    We have an ongoing project to produce NesC/TinyOS code from Ptolemy II models. We have created a tool based on Ptolemy called VIPTOS where designers jointly design code for sensor network "motes" and use the Ptolemy II wireless systems modeling environment (called VisualSense) to create models of the wireless networking environment for the motes.

    Xilinx research labs has an ongoing effort to synthesize FPGA configurations from Ptolemy II models. They use actor libraries defined in Cal, our experimental actor definition language. We do not know what (if any) plans they have for releasing this capability.

    5.10 Does the Ptolemy project take software contributions?
    Yes, the Ptolemy project has a long history of folding in software contributions from off site developers.

    The most critical issue is that it is easiest if the copyright of any contributed code uses the same wording as the standard Ptolemy II copyright. It is best if the Regents of the University of California retain the copyright, but it is acceptable if the someone else retains the copyright.

    The second most critical issue is that the code follow the Ptolemy coding convention. Since we consider software releases a form of publication, we expect code to be readable, which means that comments have complete sentences, identifiers are complete words with embedded capitalization and the source code has been spell checked. For details see the Ptolemy II coding style guide in $PTII/ptolemy/doc/coding/style.htm and in the first few chapters of the Ptolemy II Design Document.

    It is best if contributed code has a few small, concise examples illustrating its use, and includes models that can be run as part of the test suite. These models usually reside in a test/auto/ directory and do not use the an graphical actors so that they can be run as part of the nightly build.

    If you have code that you would like to contribute, please email ptolemy at eecs berkeley edu with a description of your code.

    Last Updated: $Date: 2006/10/26 19:18:11 $