Ptolemy II 6.0.2 Release Notes
Ptolemy II is a set of Java packages supporting heterogeneous,
concurrent modeling and design. Its kernel package
supports clustered hierarchical graphs, which are collections of
entities and relations between those entities. Its
actor package extends the kernel so that entities have
functionality and can communicate via the relations. Its
domains extend the actor package by imposing models of
computation on the interaction between entities. Examples of
models of computation include discrete-event systems, dataflow,
process networks, synchronous/reactive systems, and communicating
sequential processes.
Ptolemy II includes a number of support packages, such as
data, providing a type system, data encapsulation and an
expression parser,
plot, providing visual display of data,
math, providing matrix and vector math and signal
processing functions, and
graph, providing graph-theoretic manipulations.
The three volumes of the Ptolemy II Design Document
describes the Ptolemy II design and
the implementation of the Java classes.
The
"Using Vergil"
describes how to use Vergil.
Complete List of Domains in Ptolemy II
- CI:
component interaction (experimental),
- CSP:
communicating sequential processes,
- CT:
continuous-time modeling,
- DE:
discrete-event modeling,
- DDE:
distributed discrete events (experimental),
- DDF:
dynamic dataflow
- DT:
discrete time,
- FSM:
finite state machines,
- Giotto:
periodic time-driven (experimental),
- GR:
3-D graphics (experimental),
- HDF:
heterochronous dataflow
- PN:
process networks,
- PSDF:
parameterized synchronous dataflow (experimental),
- Rendezvous:
rendezvous (experimental),
- SDF:
synchronous dataflow,
- SR:
synchronous/reactive,
- TM:
timed multitasking (experimental), and
- Wireless:
wireless (experimental).
Platforms
The core of Ptolemy II 5.0 is 100% Java, so it should work on any
platform that has JDK 1.4 or later.
We developed Ptolemy II 5.0 under Solaris 8 and Windows XP sp2
and with JDK1.4.2_08.
Ptolemy II 5.0 will not compile under Java 1.3 because we use the
java.lang.URI class, which is present only in Java 1.4 and later.
Ptolemy II has been compiled and run
under IBM JDK 1.4.2_01-b06. There are the following limitations
under IBM JDK 1.4.2:
Contents:
Ptolemy II 6.0 Highlights
- Ptolemy II C Code Generation
Primary Developers: Jackie Leung, Gang Zhou, Ye Zhou, Edward A. Lee,
Christopher Brooks
Ptolemy II can now generate C code for SDF, FSM and HDF models.
This new code generator consists of actor templates (called helpers)
that contain C code stubs that are stitched together. Only a subset
of actors have helpers, so only a subset of models can be converted
to C. Creating new helpers is fairly easy though. The code generator
has been written to be easily extensible to languages other than C.
- The
Rendezvous domain:
Primary Authors: Thomas Huining Feng, Edward A. Lee
In the Rendezvous domain in Ptolemy II, each actor executes in
its own thread of control, and communication between actors is
by rendezvous. If an actor is ready to send a message,
it blocks until the receiving actor is ready to receive it. Similarly if
an actor is ready to receive a message, it blocks until the sending actor
is ready to send it.
This domain supports both conditional and multi-way rendezvous.
In conditional rendezvous, an actor is willing to rendezvous with
any one of several other actors. In multiway rendezvous, an actor requires
rendezvous with multiple other actors at the same time.
When using conditional rendezvous, the choice of which rendezvous
occurs is nondeterministic, in general.
The model of computation is based on the Communicating Sequential
Processesmodel first proposed by Hoare in 1978. Rendezvous-based
communication is also known as synchronous message passing, but we
avoid this term to avoid confusion with the SR (synchronous/reactive)
domain.
- Viptos:
Visual editor and code generator for TinyOS programs.
Primary Author: Elaine Cheong
Viptos is an interface between TinyOS and Ptolemy II that
provides a graphical user interface for TinyOS developers.
- Distributed SDF Domain using Jini
Authors: Daniel Lazaro Cuadrado (Aalborg University).
The Distributed-SDF domain is an extended version of the existing SDF
Domain that performs the simulation in a distributed manner using
Jini.
- CaseDirector
Primary Author: Edward A. Lee
The Case actor has been further developed so that it is easier
to build models that execute one of several refinements.
- Publisher,
Subscriber and
SubscriptionAggregator
Primary Authors: Raymond Cardillo, Edward A. Lee
These actors use publish/subscribe semantics to read
and write tokens on a named channel.
The tokens are
"tunneled" to any instance of Subscriber that names the same channel
and that is under the control of the same director. That is, it can
be at a different level of the hierarchy, or in an entirely different
composite actor, as long as the relevant composite actors are
transparent (have no director).
- A Token can now be "nil", which means that the data is missing.
If Token.nil() is
called, it indicates that a token is a nil or missing token, which contains no data.
Nil or missing tokens are common in analytical systems like R and SAS
where they are used to handle sparsely populated data sources.
In database parlance, missing tokens are sometimes called
null tokens. Since null is a Java keyword, we use the term "nil".
The PN Remove Nil Tokens
demo illustrates use of nil tokens.
A number of new and enhanced actor libraries are included in version 6.0.2.
You may also wish to refer to the
ptolemy.actor.lib
package, where most of the domain-polymorphic actors reside (domain-polymorphic actors are
those that can be used in more than one domain).
New generic actors:
New Communicating Sequential Processes (CSP) actors:
New Discrete Event (DE) actors:
- New Communicating Sequential Processes (CSP) demonstrations:
- New Continuous Time (CT) demonstrations:
- New Discrete Event (DE)demonstration:
- New Heterochronous Dataflow (HDF) demonstrations:
- New Rendezvous demonstrations:
- New Synchronous Dataflow (SDF) demonstrations:
- Case (New in Ptolemy II 6.0) (with codegen)
- New Process Network (PN) demonstrations:
- Actor and model documentation system
Primary Authors: Edward A. Lee, Christopher Brooks.
Actor and model documentation is now displayed using a custom
widget. The documentation for an actor or model can be edited by
the user. To view the documentation for an actor, right click on
the actor and select Documentation -> Get Documentation.
This functionality is implemented using
DocTableau
and other classes in vergil.actor and the
PtDoclet doclet.
- Relation Groups
Relations mediate connections between ports. For flexibility,
particularly with visual syntaxes, the Ptolemy II abstract syntax
permits any number of relations to be involved in any one
connection. Relations may be linked to
other relations. Any two relations that are linked are said to be
members of the same relation group. Specifically, a relation group is
a maximal set of linked relations. Semantically, a relation group has
the same meaning as a single relation.
The API of the Relation class, support linking and unlinking
relations, and also provides a method to obtain a list of all the
relations in a relation group.
In a relation group, there is no significance to the order in which
relations are linked, unlike the order in which ports are linked to
relations. Also, unlike links between relations and ports, there is no
significance to multiple links between the same relations. Any two
relations are either linked or not linked.
-
CheckModelSize:
about:copyright
facility has been extended so that model screen size and screen
location are checked.
- PtolemyPreferences:
A preference system for UI related preferences, including:
- preference to specify link bend radius
- preference to specify relation size
- preference to show parameters
- WelcomeWindow,
WelcomeWindowTableau:
An alternative start up screen infrastructure.
- MultiCompositeActor,
MultiCompositePort,
Refinement,
RefinementPort,
CTCaseDirector,
CTCase,
CTRefinement,
CaseGraphFrame,
CaseGraphTableau,
Case:
Used by the Case facility.
- TokenSentEvent,
TokenSentListener:
Two listeners created by Oscar Barney to help with
Kepler.
- DataflowWithRates,
DDFFactory,
DDF:
Caltrop work by Jörn W/ Janneck, and Steve Neuendorffer
- ASTPtUnionConstructNode,
UnionType,
UnionToken:
Support for the Union type
- Precision:
- Provide support for unsigned FixPoint values
- Modify the way Precision is represented internally
(sign, bits, exponent offset)
- Provide 4 String representations of a given precision
(including ability to parse and recognize the appropriate
precision format)
"3.2" (integer.fraction)
"5/3" (length/integer)
"2:-2" (vhdl)
"5e-2" (length e exponent)
FixPoint:
- Provide "lossless" arithmetic operators. These operators
will generate FixPoint results that "grow" if overflow occurs.
- Provide quantized versions of these operators. Quantization
is a parameter for each operator.
Fixpoint and Precision work by Mike Wirthlin (Brigham Young University)
- AbstractBranchController,
BranchActor,
MultiwayBranchController:
Support for CSP changes
- CachedSDFScheduler
- LibraryBuilder:
Support for Kepler,
added by Chad Berkeley.
- Haiyang Zheng just enriched the exception handling
capabilities in Ptolemy II... Currently, if you create an actor
that implements the ExceptionHandler interface and put it into a model,
then any exception that occurs when the model is executes gets delegated
to that actor. The first such actor is a test actor that can be used
to make regression tests that ensure that an exception is thrown.
- ExecuteCommands,
StreamExec:
Code that executes subprocesses
- DocEffigy,
DocManager,
DocTableau,
CustomizeDocumentationAction,
DocAttribute,
DocViewerFactory,
GetDocumentationAction,
RemoveCustomDocumentationAction,
ActorIndex
NamedObjClassesSeen:
Support for actor and model documentation
- LinkManhattanConnector,
PortConnectSite,
PortTerminal,
ActorNameIcon,
NameIcon,
VisibleAttribute,
RotateOrFlipPorts:
Vergil features such as controllable port orientation.
- VergilInitializer:
A class that may be called during startup.
- New deadlock detection mechanism in process domains supporting
multi-threaded actors
- SDFDirector has a period parameter now, making it timed.
and a synchronizeToRealTime parameters.
- SDF scheduler runs faster
- Workspace has wait(object, timeout) method, and DE uses it (some deadlocks
prevented when using synchronizeToRealTime).
- Miscellaneous user interface enhancements:
- Decorative attributes properly go to background or foreground
- Display name for parameters (need not match the name)
- Multiport connections show ordering
- Bus relations displayed better
- Custom Icons can have a "dashArray" parameter, which
creates dashed lines
- Java compatibility:
Ptolemy II can be compiled under Java 1.5.0_06 and Java 1.4.2_07
Java 1.5.0_06 is preferred though.
- Support changing the order of attributes, ports, etc., and
support moving objects towards the foreground or background
in the user interface. This is particularly helpful when
editing icons, since the elements of the icon can now be sent
to the background or brought to the foreground by right clicking
and selecting the appropriate option.
- Fixed memory leaks in MoMLParser
- Create hierarchy didn't work with classes
- Undo didn't always work with classes
- Couldn't drop a director (or anything containing a SharedParameter)
into a class that already had an instance.
- Relation groups didn't always work with hierarchy.
- Paste of hierarchical models would mess up locations on the inside.
- The highlighting of classes and of inherited elements is now opaque.
They used to be translucent so that the highlights could compose even
though they overlapped. However, if you print a model to EPS or PDF,
the presence of translucent elements forces the rendition to be
rasterized. This results is a major loss of quality...
- Paste of relations not properly offset.
Backward Compatibility
Most models developed under Ptolemy II 1.0.1,
2.0.1, 3.0.2, 4.0.1, 5.0.2 or HyVisual 2.2-beta, 3.0, 4.0.1, 5.0.1
should run under Ptolemy II 6.0.2
The MoMLParser includes a list of backward
compatibility filters that make certain changes on models
when read, handling such issues as actors being moved or renamed
and parameter names being changed.
The filters themselves are defined in
ptolemy.moml.filter.
If you have developed your own actors under earlier versions of Ptolemy II by
writing your own Java files, you should recompile all your java code with
the new release. In theory, copying the .class files should work, but
recompiling is safer.
Features that were new in previous Ptolemy II releases
Features that were new in previous Ptolemy II releases
Version 6.0.2 has the following limitations:
Release Limitations
Limitations in the Class Mechanism
The class mechanism is highly preliminary and is likely to change
in future releases. There are several known problems:
- Several higher-order-components will not work inside class definitions.
(ModalModel, several CT actors, etc.).
- Name collisions can occur when adding objects to base classes
whose names collide with objects in derived classes.
Auto naming should look through the derivedList for name conflicts.
- Propagation of changes to a base class is very slow in Vergil.
If there are more than just a very few instances or derived
classes, interactive editing is not practical. As a workaround,
put the class definitions in a separate file and edit them
without opening the model that creates instances. The probable
reason is that MoMLParser handles propagation by issuing large
numbers of change requests.
- Certain actors, such as MathFunction, change the number of ports
when parameters change. This violates the derivation invariance
for classes. To demonstrate the bug, put a MathFunction actor
in a base class that has a subclass. Change the function parameter
in the subclass to anything but "modulo". Then change the function
in the base class to "modulo" (which adds a port). Now attempt
to insert a parameter into the port. You will get an
InternalErrorException when it tries to propagate the change.
Limitations in the Actor Libraries
- The actor library is far from complete.
- The Expression actor does not properly propagate type constraints in
an expression-dependent fashion. It works correctly for double-valued
expressions of double-valued inputs.
- The Ptolemy parameter parser uses comma "," to separate elements
in an array. This causes problems when Ptolemy is run on
European machines that use a comma "1,0" instead of a period "1.1"
in floating point numbers.
- The Display actor uses the Swing JTextArea component which is
known to have memory leaks.
- The readFile() parameter function does not work with applets.
Instead, use readResource().
- The Matlab interface works only under Windows and it requires that
Matlab be installed on the local machine.
The Matlab interface should work with version of Matlab from
R11 (5.3) and up to and including R13 (6.5)
Didier Mauuary reports that under Windows 98, configure failed
to set up the MATLAB_DIR, PTCC
and PTDLLTOOL makefile variables, but after
he set them by hand:
MATLAB_DIR = /cygdrive/c/MATLABR11
PTCC = gcc
PTDLLTOOL = dlltool
he was able to get farther with the recompilation of the Matlab interface.
- Under Windows, the Matlab interface has problems at runtime with gcc-3.3.
Under Windows, we recommend using gcc-3.2, or Microsoft Visual C.
- Under Windows, Matlab models sometimes cause Ptolemy to exit the
second time the model is run!
The problem seems to be a segfault within a Windows library.
The problem only affects systems where Matlab is compiled with
Microsoft Visual C.
- The actor.lib.comm.SerialComm actor requires that Javacomm is installed
http://java.sun.com/products/javacomm/index.html.
The SerialComm actor will only work under Windows.
- IterateOverArray has the following problems
Limitations in the PN Domain
The PN domain documents that it locally handles mutations. However, this
is currently not true in the implementation. For the basic PN model, this
doesn't really matter, since mutations happen pretty much the same as they
would otherwise. (i.e. they are non-deterministic in when they execute)
However, for timed PN models, there is actually some expressiveness
lost, since timed PN models can locally execute mutations deterministically.
Embedding a PN typed composite actor inside a non-process top level
such as DE does not work. In fact embedding a process domain inside
a non-process domain is likely to have problems. Profess Lee wrote:
Yes, it looks as if the code is designed so that process domains
(PN, CSP) can only be used within process domains. I'm not sure
to what extent this is a limitation of the process domains vs. a
semantic problem. What would PN mean within DE? Since PN has
no well-defined notion of a "firing", how would you assign time
stamps to the outputs of a PN actor? By default in DE, the time
stamps of the outputs of an actor match those of the inputs that
triggered the firing. There is no such notion in PN.
Limitations in the User Interface
Below are some of the limitations of Vergil, the Ptolemy II Graphical
User Interface.
Limitations in JNI
Code Generation Limitations
Code Generation limitations are covered on the
Code Generation page.
Missing Domains
- Boolean and integer dataflow.
For limitations discovered after the release, see the
Ptolemy II 6.0 website
Last Updated: $Date: 2007/02/05 05:59:36 $