http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIfaq.htm
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.
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
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.
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.
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/
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.
For more information about the current status of code generation in Ptolemy II, see 5.8 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:
"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.
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.
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.
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.
http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/
http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/
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
$PTII/bin/ptolemy foo.xml
$PTII/bin/ptexecute foo.xml
java -classpath $PTII ptolemy.actor.gui.MoMLSimpleApplication foo.xml
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:Toplevel parameters can be set by calling vergil with a similar syntax:ptolemy modelFile.xml -parameterName valuewhere 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 namedx
andx
contains an entity namedy
and a parameter nameda
, andy
contains a parameter namedb
, then:ptolemy foo.xml -a 5 -y.b 10would 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 becauseptolemy
is a shell script which tends to strip off the double quotes.
$PTII/bin/vergil foo.xml -a 5 -y.b 10or
$PTII/bin/ptexecute foo.xml -a 5 -y.b 10Note 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.VergilApplicationshould 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
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
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:
.lax
file.
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.
.lax
file, change
lax.stderr.redirect=to
lax.stderr.redirect=consoleand
lax.stdout.redirect=to
lax.stdout.redirect=console
vergil-full.exe
that contains the console output.
vergil-full.exe
window and hit
Control-Backslash. If that does not work, try Control-Break and
Function-Break.
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.
vergil-full.exe
window, drag the mouse
over the text and hit return. Then paste the text into 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"
Add Actor
link in
http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/coding/
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
.
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
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.
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"/>
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.
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.
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/
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.
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/01/27 15:55:19 $