Ptolemy II 5.0 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),
- 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.
There are various problems with Sun Java 1.5.0:
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:
- Dynamic Dataflow:
HanoiTower
(see also
Eratosthenes,
IfThenElse,
Loop,
OrderedMerge,
RandomWalk)
In dynamic dataflow (DDF) models, actors are fired in response to available
input data. The schedule is dynamic and data dependent, and actors can
change their production and consumption rates in each firing.
Unlike synchronous dataflow, the DDF model of computation is Turing
complete, and questions of deadlock and boundedness are undecidable.
The HanoiTower
example exploits this to give an algorithmic solution to the well-known
towers of Hanoi problem.
-
Modeling of hybrid systems:
NewtonsCradleComplicated.
Hybrid systems are a special case of modal models
where finite-state machines (FSMs) are combined with the continuous-time (CT) models
to get mixed continuous-time and discrete-event models.
The HyVisual package
is a subset of Ptolemy II that includes the FSM and CT domains and libraries
that support the design of hybrid systems.
Version 5.0 introduces significant rework of the hybrid systems
modeling infrastructure to have more complete and predictable
semantics, as described in the paper
"
Operational Semantics of Hybrid Systems".
The
NewtonsCradleComplicated
example illustrates this with a model of a physical system that has simultaneous
events.
- Heterochronous Dataflow:
Fibonacci
(see also
Merge).
Heterochronous dataflow (HDF) is an extension of synchronous dataflow
(SDF) that permits dynamically changing production and consumption
patterns without sacrificing static scheduling. In SDF, the production
and consumption patterns of an actor are constant.
In HDF they are allowed to change between iterations of the HDF schedule.
Modal models can be used to change these patterns.
Although HDF can express many data-dependent computations that cannot
be represented by SDF, it is not Turing complete. Consequently, deadlock
and boundedness remain decidable.
The Fibonacci
example uses this mechanism in a clever way to extract a Fibonacci sequence
from a counting sequence.
- Unbounded model time:
LongRuns.
Version 5.0 introduces a new
Time class
that represents model time in a manner that has a specified resolution
and unbounded growth potential. Any two time values that are within the specified
resolution are treated as equal. Moreover, time can increase forever without
concern for loss of resolution or overflow.
The LongRuns
example is a discrete-event model that can be run forever, in principle,
without (significant) growth of memory requirements and without loss
of (internal) precision in model time.
The precision of time representations is given by a director parameter
whose value is shared across all directors in a model (see
SharedParameter).
- Synchronous Reactive Modeling:
GuardedCount.
The synchronous/reactive (SR) domain,
which is inspired by the synchronous languages Esterel, Lustre, and Signal,
realizes a concurrency model where actors react instantaneously and simultaneously
at ticks of a logical clock. Version 5.0 introduces a richer set of actors
for use with this domain, as well as a bug fix permitting
SROptimizedScheduler to be used inside a composite actor.
The GuardedCount
example illustrates some of these new capabilities.
The new actors are:
- Nondeterministic merge in Process Networks (PN):
NondeterministicMerge.
The PN domain now supports a NondeterministicMerge actor, which merges two
incoming streams nondeterministically. This new actor should be used with
caution, since determinism is one of the key features of PN. Use of this
actor is risky because any given execution is only representative of
the possible executions. Nonetheless, this offers a considerable
increment in expressiveness.
- New Parameters:
A number of new parameters have been introduced.
The DoubleRangeParameter
limits the range and precision of a double-valued parameter,
and is supported in the user interface by providing a slider by default in parameter
editing dialogs.
The FilePortParameter
is used by actors to specify a file or URL using both a
parameter and a port. The user interface supports this by offering a file browser
dialog by default when editing this parameter. The
SharedParameter
is a parameter
whose value is constrained to be identical to a suite of other instances of
SharedParameter in the same model. This parameter is used, for example, to
handle seeds in random number generators, as illustrated for example in
ColtRandom.
- Higher Order Components:
ExecDemos
(see also
IterateOverArray).
The higher-order component capabilities of Ptolemy II continue to evolve.
The ExecDemos model, when executed, starts a new
Java virtual machine that then executes the
RunDemos model,
which runs all demos in a specified directory using full-screen mode.
This illustrates how to use higher-order actors to control the lifecylcle of other Ptolemy II
models. This example can be set up to automatically and repeatedly run demos
unattended by following the instructions in the
README.txt file.
The new higher-order actors include:
- Graphics domain:
SolarSystem
(see also Helen).
The graphics (GR) domain has been extensively revised to take better advantage of underlying
capabilities in the Java 3D package. For example, the
SolarSystem
model illustrates transparency (see the rings of Saturn), and the
Helen model
illustrates texture mapping and movable viewer positioning.
The following capabilities are now supported:
- transparency
- texture mapping
- shininess
- colors use ColorAttribute
- more colors can be set
- settable resolution
- wireframe option for shapes
- flat facets option for shapes
- run-time changes of parameter values
- parameters in the Text3D actor
- movable viewer position
A number of new and enhanced actor libraries are included in version 5.0.
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:
- Random number generators:
ColtRandom.
A new library of random number generators, developed jointly with
David Bauer and Kostas Oikonomou from AT&T Research, is based on the popular
Colt "Open Source Libraries for High
Performance Scientific and Technical
Computing in Java."
Colt is described at
http://hoschek.home.cern.ch/hoschek/colt/.
The library supports many
commonly used probability distributions and provides
systematic management of seeds and random number generation
techniques.
- New discrete-event actors:
- Communications library:
The communications library
includes a number of new actors:
- New Continuous Time demos:
- New Discrete Event (DE) demos:
- New Dynamic Dataflow (DDF) demos:
- New Heterochronous Dataflow (HDF) demos:
- New Giotto demos:
- New Graphics (GR) demos
(requires Java 3D, see the GR domain):
- New Wireless demos:
- Fixed "Restore Defaults" when actors and directors
use the three argument constructor for parameters.
- Previously, if a class definition were to show the name
of ports, there was no way to turn this off (the attribute
_showName) could not be removed. Now, marker attributes
such as _showName are boolean valued parameters, so they
can be turned off by overriding their value.
- Fixed long standing bug in copy where objects are represented
in the wrong order in the exported MoML.
- Fixed some subtle bugs in ModalModel, where changes to
input/output status and ordering of ports were not properly
reflected in the mirror ports.
- A number of potential deadlocks have been fixed:
- deadlock while dragging actors during a run.
- deadlocks in PN when exceptions occur in the model.
Backward Compatibility
Most models developed under Ptolemy II 1.0.1,
2.0.1, 3.0.2, 4.01 or HyVisual 2.2-beta an Hyvisual 3.0
should run under Ptolemy II 5.0
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.
Backward compatible issues that are handled automatically
Features that were new in previous Ptolemy II releases
Features that were new in previous Ptolemy II releases
Version 5.0 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.
- 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
- IterateOverArray: When you drop in an actor, and then
another actor, and then select "undo," the second actor is
deleted without the first one being re-created. Thus, undo is
only a partial undo. The fix to this is extremely
complicated. Probably the only viable
mechanism is to use UndoStackAttribute.getUndoInfo() to get the undo
stack and then to manipulate the contents of that stack directly.
- IterateOverArray: There should be an option to reset
between firings of the inside actor.
- IterateOverArray: If you drop a new actor onto an IterateOverArray
in a subclass, it will simply acquire the new contents, but not
actually do anything with them. It should somehow refuse to accept
the new object in the subclass, since to do so, it would have to
delete the original object defined in the base class, and this would
violate the derived invariant.
- IterateOverArray: If an instance of IterateOverArray in a derived
class has overridden values of parameters, those are lost if
contained entity of the instance in the base class is replaced and
then an undo is requested.
- IterateOverArray: When an actor with a display icon like
Const, Expression, or MathFunction is put into
IterateOverArray, the CopyCatIcon doesn't reflect the text display.
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
The Interface to C actors using the Java Native Interface
is not available via the Windows Installer (or Web Start).
To use the JNI/Ptolemy II interface, you must download
Ptolemy II as source files and compile.
The JNI user interface does not permit creation of new JNI actors.
If you follow the instructions in
JNIUtilities, then
eventually you will get a NameDuplicationException.
The resulting model will be missing
<property name="output" class="jni.Argument" value="false,false,true,double">
</property>
We are working with the original authors on a solution.
In the short term, one workaround is to edit the xml file directly
and add the appropriate property by hand.
JNI will not work with Hierarchical classes, subclasses, and inner
classes
If Ptolemy exits when running the JNI model, then
try using gcc-3.2.x in the Cygwin installer from
http://ptolemy.eecs.berkeley.edu/ptolemyII/ptII5.0/cygwin.htm
which includes gcc-3.2.x
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 5.0 website
Last Updated: $Date: 2005/05/14 00:23:34 $