Ptolemy II Frequently Asked Questions

This FAQ can be found at:
The version of this FAQ is: $Id: ptIIfaq.htm 7355 2014-12-19 01:34:49Z cxh $
  • 1. General
  • 1.1 What is Ptolemy II?
  • 1.2 What is the copyright and license?
  • 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 Subversion 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?
  • 4.4 How do I do loops in Ptolemy II?
  • 4.5 I have a Composite with a Multiport, but it only sees one channel?
  • 4.6 How do I put a model into a PowerPoint Deck?
  • 4.7 How do I create a PDF of a model?
  • 4.8 How do I create an image (GIF or PNG) of a model?
  • 4.9 What about multicore?
  • 4.10 What about Unit Systems and Ontologies?
  • 4.11 How do a do a parameter sweep?
  • 5. Extending Ptolemy II
  • 5.1 How do I add an actor?
  • 5.2 How do I add a director?
  • 5.3 How do I add a configuration?
  • 5.4 How do I add a type?
  • 5.5 What makes an actor domain polymorphic?
  • 5.6 How do I interface to C/C++
  • 5.7 How do I customize the GUI?
  • 5.8 What file format are the models stored in?
  • 5.9 Is there a scripting interface to Ptolemy II?
  • 5.10 What about Code Generation?
  • 5.11 Does the Ptolemy project take software contributions?
  • 1. General

    1.1 What is Ptolemy II?
    Ptolemy II [1][6] is an open-source software framework supporting experimentation with actor-oriented design. Actors are software components that execute concurrently and communicate through messages sent via interconnected ports. A model is a hierarchical interconnection of actors. In Ptolemy II, the semantics of a model is not determined by the framework, but rather by a software component in the model called a director, which implements a model of computation. The Ptolemy Project has developed directors supporting process networks (PN), discrete-events (DE), dataflow (SDF), synchronous/reactive(SR), rendezvous-based models, 3-D visualization, and continuous-time models. Each level of the hierarchy in a model can have its own director, and distinct directors can be composed hierarchically. A major emphasis of the project has been on understanding the heterogeneous combinations of models of computation realized by these directors. Directors can be combined hierarchically with state machines to make modal models [2]. A hierarchical combination of continuous-time models with state machines yields hybrid systems [3]; a combination of synchronous/reactive with state machines yields StateCharts [4] (the Ptolemy II variant is close to SyncCharts).

    Ptolemy II has been under development since 1996; it is a successor to Ptolemy Classic, which was developed since 1990. The core of Ptolemy II is a collection of Java classes and packages, layered to provide increasingly specific capabilities. The kernel supports an abstract syntax, a hierarchical structure of entities with ports and interconnections. A graphical editor called Vergil supports visual editing of this abstract syntax. An XML concrete syntax called MoML provides a persistent file format for the models. Various specialized tools have been created from this framework, including HyVisual (for hybrid systems modeling), Kepler (for scientific workflows), VisualSense (for modeling and simulation of wireless networks), Viptos (for sensor network design), and some commercial products. Key parts of the infrastructure include an actor abstract semantics, which enables the interoperability of distinct models of computation with a well-defined semantics; a model of time (specifically, super-dense time, which enables interaction of continuous dynamics and imperative logic); and a sophisticated type system supporting type checking, type inference, and polymorphism. The type system has recently been extended to support user-defined ontologies [5]. Various experiments with synthesis of implementation code and abstractions for verification are included in the project.


    [1] Johan Eker, Jorn Janneck, Edward A. Lee, Jie Liu, Xiaojun Liu, Jozsef Ludvig, Sonia Sachs, Yuhong Xiong. Taming heterogeneity - the Ptolemy approach, Proceedings of the IEEE, 91(1):127-144, January 2003.
    (Key citation for the Ptolemy project)

    [2] Edward A. Lee. Finite State Machines and Modal Models in Ptolemy II, Technical report, EECS Department, University of California, Berkeley, UCB/EECS-2009-151, December, 2009.

    [3] E. A. Lee and H. Zheng, "Operational Semantics of Hybrid Systems," Invited paper in Proceedings of Hybrid Systems: Computation and Control (HSCC) LNCS 3414, Zurich, Switzerland, March 9-11, 2005, pp.25-53.

    [4] E. A. Lee, H. Zheng, "Leveraging Synchronous Language Principles for Heterogeneous Modeling and Design of Embedded Systems," EMSOFT '07, September 30 - October 3, 2007, Salzburg, Austria.

    [5] M.-K. Leung, T. Mandl, E. A. Lee, E. Latronico, C. Shelton, S. Tripakis, and B. Lickly, "Scalable Semantic Annotation using Lattice-based Ontologies," ACM/IEEE 12th International Conference on Model Driven Engineering Languages and Systems (MODELS), Denver, CO, USA, 4-9 October, 2009.

    [6]Christopher Brooks, Edward A. Lee. Ptolemy II - Heterogeneous Concurrent Modeling and Design in Java, 11 February, 2010; Poster presented at the 2010 Berkeley EECS Annual Research Symposium (BEARS).

    The Ptolemy Project web page 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 Lee. The project is named after Claudius Ptolemaeus, the second century Greek astronomer, mathematician, and geographer.

    1.2 What is the copyright and license?
    Ptolemy II is released under the fairly liberal UC Berkeley copyright, see 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

    This style of copyright is often referred to the community as a "BSD" copyright because it was used for the "Berkeley Standard Distribution" of Unix. It is much more liberal that the commonly used "GPL" or "GNU Public License," which encumbers the software and derivative works with the requirement that they carry the source code and the same copyright agreement. The BSD copyright requires that the software and derivative work carry the identity of the copyright owner, as embodied in the lines:

    Copyright (c) 1999-2014 The Regents of the University of California.
    All rights reserved.

    The copyright also requires that copies and derivative works include the disclaimer of liability in BOLD. It specifically does not require that copies of the software or derivative works carry the middle paragraph, so such copies and derivative works need not grant similarly liberal rights to users of the software.

    The intent of the BSD copyright is to maximize the potential impact of the software by enabling uses of the software that are inconsistent with disclosing the source code or granting free redistribution rights. For example, a commercial enterprise can extend the software, adding value, and sell the original software embodied with the extensions. Economic principles indicate that granting free redistribution rights may render the enterprise business model untenable, so many business enterprises avoid software with GPL licenses. Economic principles also indicate that, in theory, fair pricing of derivative works must be based on the value of the extensions, the packaging, or the associated services provided by the enterprise. The pricing cannot reflect the value of the free software, since an informed consumer will, in theory, obtain that free software from another source.

    Software with a BSD license can also be more easily included in defense or national-security related applications, where free redistribution of source code and licenses may be inconsistent with the mission of the software. Ptolemy II can include other software with copyrights that are different from the BSD copyright. In general, we do not include software with the GNU General Public License (GPL) license, because provisions of the GPL license require that software with which GLP'd code is integrated also be encumbered by the GPL license. In the past, we have made an exception for GPL'd code that is aggregated with Ptolemy II but not directly combined with Ptolemy II. For example was shipped with Ptolemy II. This file is a GPL'd Perl script that access the CVS database and generates a ChangeLog file. This script is not directly called by Ptolemy II, and we include it as a ``mere aggregation'' and thus Ptolemy II does not fall under the GPL. Note that we do not include GPL'd Java files that are compiled and then called from Ptolemy II because this would combine Ptolemy II with the GPL'd code and thus encumber Ptolemy II with the GPL.

    Another GNU license is the GNU Library General Public License now known as the GNU Lesser General Public License (LGPL). We try to avoid packages that have this license, but we on occasion we have included them with Ptolemy II. The LGPL license is less strict than the GPL - the LGPL permits linking with other packages without encumbering the other package. In general, it is best if you avoid GNU code. If you are considering using code with the GPL or LGPL, we encourage you to carefully read the license and to also consult the GNU GPL FAQ at

    We also avoid including software with proprietary copyrights that do not permit redistribution of the software.

    1.3 Is there a mailing list?
    The Ptolemy mailing lists are run by

    Ptolemy Interest Mailing list

    This moderated mailing list is for Ptolemy announcements only. 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, go to 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 (search)

    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. To subscribe to the ptolemy-hackers mailing list, go to your message. You can search this mailing list for previously posted messages on any topic.

    Newsgroup: comp.soft-sys.ptolemy

    UC Berkeley no longer has a Usenet machine, so we no longer monitor comp.soft-sys.ptolemy.

    The easiest way to read comp.soft-sys.ptolemy is via Google Groups.

    1.4 Is there a bug list?
    Current bugs are listed in 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 (6.0? 7.0? The devel tree?)
  • Whether you built it from Subversion 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

    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
    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

    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 ( and 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 ( and Actif (

    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 ( and The Kepler Project ( 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.

    Concerning using Ptolemy actors within Kepler, Norbert Podhorszki writes:
    If you find a Ptolemy actor useful, just remember its class name (e.g. In Kepler, "Tools/Instantiate Component" menu allows you to type in the class name, which will put an actor instance on your canvas just as dragging one from the actor tree.

    The ptolemy jar is stored in the kepler.jar, so you have access to any Ptolemy actors and directors.

    If you want to use a director not in Kepler tree, you have to use the "Tools/Instantiate Attribute" menu. I use it to get a DDF director frequently (class

    I suppose, you can create a kar file for any ptolemy actor just as for kepler actors, if you want to add some of them into the Kepler actor tree.

    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
    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
    3.4 How do I get Subversion access to PtolemyII
    Subversion access to the Ptolemy II development tree is available. Instructions can be found at

    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 contains shell scripts and dos scripts. Under Windows, you must build Ptolemy II with Cygwin and run (cd $PTII/bin; make) to create the ptexecute shell script. An alternative is to create an Eclipse run configuration that invokes See the Eclipse instructions in $PTII/doc/eclipse/index.htm for details about invoking Vergil. Follow those instructions and use as the class name.

    If $PTII/bin/makefile does not exist, then Eclipse was probably set up with "Use project folder as root for source and class files". See $PTII/doc/eclipse/index.htm for how to setup Eclipse and Ptolemy II.

    $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 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.

    To see a complete set of command line argument options, use the -help command line argument, for example $PTII/bin/vergil -help.

    MoMLApplication supports setting top level parameters using command line arguments.

    The ConfigurationApplication 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:
       $PTII/bin/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:
       $PTII/bin/ptolemy foo.xml -a 5 -y.b 10
    would set the values of the two parameters.

    Note that strings need to have double quotes converted to " so to set a parameter named c to the string "bar" it might be necessary to do something like:

       $PTII/bin/ptolemy foo.xml -a 5 -y.b 10 -c "\&quot\;bar\&quot\;"
    The " is necessary to convert the double quote to something safe to in an XML file. The backslashes are necessary to protect the & and ; from the shell in the shell script.

    Note that the attribute is a better way to set parameters at run time. ParameterSet is an attribute that reads multiple values from a file and sets corresponding parameters in the container.

    Toplevel parameters can be set by calling vergil with a similar syntax:
    $PTII/bin/vergil foo.xml -a 5 -y.b 10
    $PTII/bin/ptexecute foo.xml -a 5 -y.b 10
    Note that MoMLSimpleApplication does not do this type of command line parsing, but $PTII/ptolemy/moml/ extends MoMLSimpleApplication and handles command line arguments in a similar manner as above.

    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

    There are several different Ptolemy configurations that differ in the number of Ptolemy actors or models of computation that are available. The Ptiny configuration includes common domains and is sometimes easier to work with than the full version.

    The Ptiny configuration of Vergil uses the following jar files

    • ./ptolemy/ptsupport.jar
    • ./ptolemy/vergil/vergil.jar
    • ./ptolemy/lib/diva.jar
    • ./ptolemy/domains/domains.jar

    The full configuration of Vergil uses all the jar files of the Ptiny version and the following jar files:

    • ptolemy/actor/gt/gt.jar
    • ptolemy/domains/ptera/erg.jar
    • ptolemy/vergil/gt/gt.jar
    • ptolemy/vergil/ptera/erg.jar
    • ptolemy/vergil/fsm/fmv/fmv.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)

    Under Windows, to start the Ptiny version, first change to the Ptolemy directory, then run:

    java -classpath ".;./ptolemy/ptsupport.jar;\
    ./ptolemy/domains/domains.jar" \
     ptolemy.vergil.VergilApplication -ptiny

    To run the full version:

    java -classpath ".;ptolemy/ptsupport.jar;\
    ptolemy/vergil/fsm/fmv/fmv.jar" \
    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:

    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
    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

    Ptolemy II 3.0.2 and later includes - 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 - 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 and

    The way to use readFile is as an expression:

    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/ 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"
    4.4 How do I do loops in Ptolemy II?
    Norbert Podhorszki wrote some documentation about how to do loops in PN and DDF.
    4.5 I have a Composite with a Multiport, but it only sees one channel?
    The workaround is to right click on the inside relation and set the width to 0, which means "Infer the width from the connections".

    For example, if you have two Consts going to a multiport input on a composite. By default, the width of the inner relation inside the composite is set to 1 Currently, in the Ptolemy II semantics, when a multiport has width 2 on the outside and width 1 on the inside, the second channel is dropped.

    Arguably, the default width should always be 0, but we would need a proof of soundness. I.e., that the inferred width is always unique. We've looked into this in the past, but have not come up with a formal proof.

    4.6 How do I put a model into a PowerPoint Deck?
    Screen grabs of an model work ok for PowerPoint, but use GIF or PNG, not JPEG. Also, the image should not be scaled up after placing the image in PowerPoint; instead enlarge the image in Vergil and then do the capture.
    4.7 How do I create a PDF of a model?
    To include an image of a model in a LaTeX file, print the Ptolemy models to PDF. There are at least two ways to create a PDF of a model: PDF print drivers or using Export -> Export PDF

    PDF Print Drivers

    This requires that PDF printer drivers be installed on your machine.

    The size of the window matters since the print utility tries to fit the result into the 8.5x11 page, and the result doesn't scale well (line thickness don't scale proportionally). Try to make all my windows standard width before printing. Also, reset the zoom before printing.

    In Ptolemy II 8.0 and later, to print from the command line, run:

           $PTII/bin/vergil -printPDF model.xml
    This method requires that you have PDF printer drivers installed on your machine.

    Export PDF

    The Ptolemy II development tree after Ptolemy II 8.0, can be configured to use a GPL'd PDF utility. To enable this utility requires build Ptolemy II from source.
    • Download and build Ptolemy II. See
    • Download iText.jar from and place iText.jar as $PTII/vendors/misc/itext/iText.jar
    • Rerun configure or add iText.jar to your classpath.
    • Edit ptII/ptolemy/vergil/basic/, search for "Export PDF" and uncomment the block of text that enables the interface to iText.
    • Build and run. The File -> Export -> menu should now have a Export PDF menu choice

    White Background

    To get a white background, drag in a Utilities -> LocalPreferences and set the background color. To avoid including the LocalPreferences attribute in your output, zoom out, move the LocalPreferences icon away from your model and then zoom back in.

    Tweaking the PDF

    If need be, edit the results in Adobe Illustrator, including combining figures and putting borders on the grey boxes.

    Remove white space using Adobe Acrobat Pro by using Tools -> Advanced Editing -> Crop Tool, then double clicking in the interior of the crop region to bring up the Crop Pages dialog and hit OK.

    4.8 How do I create an image (GIF or PNG) of a model?
    In the Ptolemy II development tree after Ptolemy II 8.0.1, the File -> Export menu can export models in various formats.
    It is also possible to export from the command line.
    The ptolemy/vergil/basic/ file will create an image, see for documentation.
    4.9 What about multicore?
    If you use the Kahn Process Network (PN) model of computation, then each actor is a thread and, in principle, each thread will run on a separate core.

    An alternative is to use the ThreadedComposite actor, see Edward A. Lee, "ThreadedComposite: A Mechanism for Building Concurrent and Parallel Ptolemy II Models," EECS Department, University of California, Berkeley, Technical Report No. UCB/EECS-2008-151, December 7, 2008.

    See the Higher Order Component demos in $PTII/ptolemy/actor/lib/hoc/demo or See especially the Parallel Execution demo. See also 5.9 What about Code Generation?.

    4.10 What about Unit Systems and Ontologies?
    There are at least three unit systems in Ptolemy II.
    1. Static units, see:
    2. Dynamic units, see: $PTII/ptolemy/data/unit/demo/Units/Units.xml See
    3. The Unit System example from the ontologies work, see $PTIIptolemy/data/ontologies/demo/UnitSystemExample/UnitSystemExample.xml. To get access to this model, go to
      See also [5] above and:
      Ben Lickly, Charles Shelton, Elizabeth Latronico, Edward A. Lee. ``A Practical Ontology Framework for Static Model Analysis''. EMSOFT '11: Proceedings of the Ninth International Conference on Embedded Software, ACM, 23-32, 10, October, 2011.
    4.11 How do a do a parameter sweep?
    A Parameter Sweep is when a model is run a number of times with different parameters to perhaps find an optimal solution. For details, see

    5. Extending Ptolemy II

    5.1 How do I add an actor?
    See the Add Actor link in $PTII/doc/coding/addinganactor.htm, which is available as
    5.2 How do I add a director?
    See the Tutorial link in $PTII/doc/index.htm, which is available as
    5.3 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.4 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

    The Ptolemy Type system has a type lattice that is implemented in classes in A common misconception is that to add a type, one needs to add the new type to the type lattice by editing 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/ and $PTII/ptolemy/actor/lib/Security/

    5.5 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.6 How do I interface to C/C++
    Ptolemy II is written in Java, and Java has the Java Native Interface (JNI), see Oracle's JNI page at

    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 (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

    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.7 How do I customize the GUI?
    Ptolemy II uses Diva to display block diagram editors.
    Information about Diva can be found at 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

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

           <property name="JVM Properties" 

    The easiest way to add a button is to add an attribute that can be dragged in that has an action associated with it, see

    In Ptolemy II 8.0 and later, the GUI has been extended so that buttons can be added to the toolbar, see the documentation for

    5.8 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.

    The MoML dtd may be found at

    MoML files can have <configure> ... <configure> tags in them that are not part of the dtd and thus a validating parser may fail. One workaround is to remove the configure tags with a script before validating, see $PTII/ptolemy/moml/test/removeconfigure.

    To remove location information from a model, see ptolemy/moml/filter/

    MoML files do not contain information about port direction and such. This is intentional because the actors are defined elsewhere in Java or in other MoML files. These definitions may be overridden The easiest way to get all the information from a model is to parse the xml file and then traverse the model in Java and write out information of interest. For example, see the ptolemy.kernel.CompositeEntity.deepEntityList() and ptolemy.kernel.CompositeEntity.exportMoML() methods. There may be some code at that is of interest.

    In addition, MoML is registered as a MIME type, see

    5.9 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

    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

    5.10 What about Code Generation?
    Certain versions of Ptolemy II before Ptolemy 8.0 included the Copernicus code generator, which is described below. Portions of the Copernicus code generator was removed between Ptolemy II 7.0.1 and Ptolemy II 8.0.beta because it stopped passing its tests and extending it to support use of Java Generics in the Ptolemy kernel was seen as being a large task. The Copernicus code generator is no longer being developed, its features are described below.

    The Copernicus Ptolemy II code generator developed by Stephen Neuendorffer read non-hierarchical SDF models and generated Java .class files. We call this the deep Copernicus code generator. The code that is produced by deep codegen uses very little of the Ptolemy infrastructure. The ptolemy.math package is used sometimes. The Copernicus deep code generator was removed between Ptolemy II 7.0.1 and Ptolemy II 8.0.beta.

    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 Copernicus code generator. The shallow Copernicus code generator is present in Ptolemy II 8.0 and later.

        $PTII/bin/copernicus -codeGenerator shallow ~/ptII/ptolemy/actor/lib/test/auto/IIR.xml
    A class file will be generated as ptolemy/copernicus/shallow/cg/IIR/IIR/CGIIR.class To see the Java code, do:
    cd $PTII/ptolemy/copernicus/shallow/cg/IIR
    make jodeDecompile

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

    cd $PTII
    make install >& install.out
    cd $PTII/ptolemy/domains/sdf/demo
    mkdir ButterflyTest
    cp Butterfly/Butterfly.xml ButterflyTest/ButterFlyTest.xml
    cd ButterFlyTest
    $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 and was removed between Ptolemy II 7.0.1 and 8.0.beta.

    For more information about the Copernicus code generator, see
    Stephen Neuendorffer, Actor-Oriented Metaprogramming, PhD Thesis, University of California, Berkeley, December 21, 2004.
    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 first shipped in Ptolemy II 6.0 in ptolemy/codegen and we refer to it as the "codegen" code generator.

    The codegen 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 "adapter" 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've had various efforts in the codegen code generator to generate C code for PN models and to generate VHDL code, but nothing has been completed.

    For more information about codegen, see
    Chapter 7 of C. Brooks, E.A. Lee, X. Liu, S. Neuendorffer, Y. Zhao, H. Zheng (eds.), "Heterogeneous Concurrent Modeling and Design in Java (Volume 2: Ptolemy II Software Architecture)," EECS Department, University of California, Berkeley, UCB/EECS-2008-29, April 1, 2008. (HTML version of Chapter 7:
    Gang Zhou, Man-Kit Leung, Edward A. Lee. A Code Generation Framework for Actor-Oriented Models with Partial Evaluation, Proceedings of International Conference on Embedded Software and Systems 2007, LNCS 4523, Y.-H. Lee et al. (ed.), 786-799, May, 2007.
    Gang Zhou. Partial Evaluation for Optimized Compilation of Actor-Oriented Models, PhD thesis, University of California, Berkeley, May, 2008.
    Jackie Man-Kit Leung, Terry Filiba, Vinayak Nagpal. VHDL Code Generation in the Ptolemy II Environment, Technical report, EECS Department, University of California, Berkeley, UCB/EECS-2008-140, October, 2010.

    We had a project to produce NesC/TinyOS code from Ptolemy II models. We 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.

    Our currently active code generation effort may be found in the development tree in ptolemy/cg, we call it the "cg" code generator. We took the lessons learned from codegen and applied them to cg. In particular, cg more easily supports multiple backends with less code duplication. The cg code generator is under active development, we are working on code generation for large systems. For details about cg, download the Ptolemy II development tree (see and then see $PTII/ptolemy/cg/README.html.

    The cg code generator works best generating Java code for SDF models.

    The Java cg code generator can generate code for models that use actors for which we have no code generation templates. The way this works is the actor is wrapped in an opaque TypedCompositeActor and calls are made to the Ptolemy runtime. This is slower than a pure code generation solution, where all the actors have code generation templates, but it allows easy access to user defined actors.

    The cg code generator also supports models that have actors that have method bodies written in C. In Ptolemy II 8.0, see the EmbeddedCodeActor.

    In versions of Ptolemy II after 8.0, see EmbeddedCodeActor.

    Generating C code is possible as well, it just requires porting the templates that we have for Java actors.

    For information about the cg code generator, see
    Stavros Tripakis, Dai Nguyen Bui, Marc Geilen, Bert Rodiers, Edward A. Lee. Compositionality in Synchronous Data Flow: Modular Code Generation from Hierarchical SDF Graphs, Technical report, UC Berkeley, UCB/EECS-2010-52, May, 2010.
    Martin Schoeberl, Christopher Brooks, Edward A. Lee. Code Generation for Embedded Java with Ptolemy, Proceedings of the 8th IFIP Workshop on Software Technologies for Future Embedded and Ubiquitous Systems (SEUS 2010), October, 2010.
    The Modular Code Generation research summary covers work in code generation.


    In addition, 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.11 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: 2014-12-18 17:34:49 -0800 (Thu, 18 Dec 2014) $