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.
- Stochastic hybrid systems:
IncreasingRatePoisson
(see also
HysteresisWithRandomDelay,
Brownian
).
Stochastic hybrid systems add random behavior to continuous-time models mixed
with discrete events. The
IncreasingRatePoisson
models spontaneous mode transitions governed by a Poisson process.
The HysteresisWithRandomDelay
example uses similar spontaneous mode transitions to model random delay in mode transitions.
The Brownian example
models a stochastic differential equation describing a random walk process.
- 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:
- Java compatibility:
Ptolemy II can be compiled under Java 1.5.0_01. Java 1.4.2_07
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.
- Fractional math:
A new library supporting arithmetic on fractions has been created. See:
- Added external source (URL) option to the Instantiate Entity
command in the Graph menu.
- Other New java files:
- 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
- ptolemy.moml.filter.AddEditorFactory: If a parameter has a _location, then
add a VisibleParameterEditorFactory named _editorFactory.
- ptolemy.moml.filter.AddIcon: Add specialized icons that display the value
of one of the parameters.
The affected actors are:
- ptolemy.actor.lib.Const
- ptolemy.actor.lib.MathFunction
- ptolemy.actor.lib.TrigFunction
- ptolemy.actor.lib.Scale
- ptolemy.actor.lib.Expression
- ptolemy.moml.filter.ClassChanges: change any class names that have been renamed and remove obsolete classes.
Below are original class names followed by the new class names:
- ptolemy.vergil.fsm.modal.ModalController -> ptolemy.domains.fsm.modal.ModalController
- ptolemy.vergil.fsm.modal.ModalModel$ModalTableauFactory -> ptolemy.vergil.fsm.modal.ModalTableauFactory
- ptolemy.vergil.fsm.modal.TransitionRefinement -> ptolemy.domains.fsm.modal.TransitionRefinement
- ptolemy.vergil.fsm.modal.RefinementPort -> ptolemy.domains.fsm.modal.RefinementPort
- ptolemy.vergil.fsm.modal.Refinement -> ptolemy.domains.fsm.modal.Refinement
- ptolemy.kernel.util.VersionAttribute -> ptolemy.kernel.attributes.VersionAttribute
- ptolemy.vergil.icon.ImageEditorIcon -> ptolemy.vergil.icon.ImageIcon
- ptolemy.domains.fsm.kernel.InterfaceAutomatonTransition -> ptolemy.domains.fsm.kernel.ia.InterfaceAutomatonTransition
- ptolemy.vergil.fsm.modal.ModalPort -> ptolemy.domains.fsm.modal.ModalPort
- ptolemy.kernel.attributes.IDAttribute -> ptolemy.vergil.kernel.attributes.IDAttribute
- ptolemy.vergil.fsm.modal.TransitionRefinementPort -> ptolemy.domains.fsm.modal.TransitionRefinementPort
- ptolemy.kernel.attributes.FileAttribute -> ptolemy.data.expr.FileParameter
- ptolemy.domains.sr.lib.Latch -> ptolemy.domains.sr.lib.Current
- ptolemy.domains.sdf.kernel.SDFIOPort -> ptolemy.actor.TypedIOPort
- ptolemy.moml.Location -> ptolemy.kernel.util.Location
- ptolemy.domains.fsm.lib.RelationList -> ptolemy.domains.fsm.kernel.RelationList
- ptolemy.domains.gr.lib.ViewScreen -> ptolemy.domains.gr.lib.ViewScreen3D
- ptolemy.actor.lib.comm.SerialComm -> ptolemy.actor.lib.io.comm.SerialComm
- ptolemy.actor.hoc.MultiInstanceComposite -> ptolemy.actor.lib.hoc.MultiInstanceComposite
- ptolemy.vergil.fsm.modal.ModalModel -> ptolemy.domains.fsm.modal.ModalModel
Below are the classes to remove:
- ptolemy.data.expr.NotEditableParameter
- ptolemy.domains.de.kernel.DEIOPort
- ptolemy.moml.filter.HideAnnotationNames: If an annotation name ends with
'annotation1', then add _hideName if necessary.
- ptolemy.moml.filter.MultiportToSinglePort: Update any actor multiports that are now
single ports.
Below are the actors that are affected, along with the port name:
- ptolemy.actor.lib.gui.MatrixViewer
- input ptolemy.domains.sdf.lib.Autocorrelation
- output ptolemy.actor.lib.Const
- output ptolemy.actor.lib.NonStrictTest
- input
- ptolemy.moml.filter.ParameterNameChanges: Update any Parameter names
that have been renamed.
Below are the actors that are affected, along with the Parameter name
and the new name:
- ptolemy.domains.de.lib.Server
serviceTime -> newServiceTime
- ptolemy.domains.pn.kernel.PNDirector
Initial_queue_capacity -> initialQueueCapacity
- ptolemy.domains.de.lib.VariableDelay
defaultDelay -> delay
- ptolemy.moml.filter.PortClassChanges: Update any actor port classes that have been
changed.
Below are the actors that are affected, along
with the old port class and the new port class:
- ptolemy.domains.sdf.lib.vq.HTVQEncode.input
- ptolemy.domains.sdf.kernel.SDFIOPort -> ptolemy.actor.TypedIOPort
- output
- ptolemy.domains.sdf.kernel.SDFIOPort -> ptolemy.actor.TypedIOPort
- ptolemy.domains.de.lib.Server.newServiceTime
- ptolemy.domains.de.kernel.DEIOPort -> ptolemy.actor.parameters.ParameterPort
- ptolemy.domains.sdf.lib.vq.VQDecode.input
- ptolemy.domains.sdf.kernel.SDFIOPort -> ptolemy.actor.TypedIOPort
- output
- ptolemy.domains.sdf.kernel.SDFIOPort -> ptolemy.actor.TypedIOPort
- ptolemy.domains.sdf.lib.vq.ImagePartition.input
- ptolemy.domains.sdf.kernel.SDFIOPort -> ptolemy.actor.TypedIOPort
- output
- ptolemy.domains.sdf.kernel.SDFIOPort -> ptolemy.actor.TypedIOPort
- ptolemy.domains.de.lib.VariableDelay.delay
ptolemy.domains.de.kernel.DEIOPort -> ptolemy.actor.parameters.ParameterPort
- ptolemy.domains.sdf.lib.vq.ImageUnpartition.input
- ptolemy.domains.sdf.kernel.SDFIOPort -> ptolemy.actor.TypedIOPort
- output
- ptolemy.domains.sdf.kernel.SDFIOPort -> ptolemy.actor.TypedIOPort
- ptolemy.moml.filter.PortNameChanges: Update any actor port names that have been
renamed.
Below are the actors that are affected, along
with the old port name and the new port name:
- ptolemy.domains.de.lib.Server
serviceTime -> newServiceTime
- ptolemy.actor.lib.comm.Scrambler
initial -> initialState
- ptolemy.actor.lib.conversions.CartesianToComplex
imag -> y
real -> x
- ptolemy.actor.lib.comm.ConvolutionalCoder
uncodeBlockSize -> uncodedRate
initial -> initialState
- ptolemy.actor.lib.comm.ViterbiDecoder
uncodeBlockSize -> uncodedRate
amplitude -> constellation
- ptolemy.actor.lib.Sleep
delay -> sleepTime
- ptolemy.actor.lib.conversions.ComplexToCartesian
imag -> y
real -> x
- ptolemy.moml.filter.PropertyClassChanges: Update any actor port class names
that have been renamed.
Below are the actors that are affected, along with the port name
and the new classname:
- ptolemy.domains.ct.lib.ZeroCrossingDetector
useEventValue -> null
- ptolemy.actor.lib.MathFunction
function -> ptolemy.data.expr.StringParameter
- ptolemy.domains.ct.lib.LevelCrossingDetector
useEventValue -> null
- ptolemy.domains.ct.kernel.CTEmbeddedDirector
breakpointODESolver -> null
- ptolemy.domains.sdf.lib.Autocorrelation
- ptolemy.domains.sdf.lib.FIR
- ptolemy.domains.sdf.lib.Chop
- ptolemy.domains.sdf.lib.BitsToInt
- ptolemy.domains.sdf.lib.DownSample
- ptolemy.domains.sdf.lib.DoubleToMatrix
- ptolemy.domains.sdf.lib.IntToBits
- ptolemy.domains.sdf.lib.ArrayToSequence
- ptolemy.domains.sdf.lib.CountTrues
- ptolemy.domains.sdf.lib.VariableFIR
- ptolemy.domains.sdf.lib.MatrixToSequence
- ptolemy.domains.sdf.lib.IFFT
- ptolemy.domains.sdf.lib.SequenceToArray
- ptolemy.domains.sdf.lib.FFT
- ptolemy.domains.sdf.lib.SampleDelay
- ptolemy.domains.sdf.lib.MatrixToDouble
- ptolemy.domains.sdf.lib.LineCoder
- ptolemy.domains.sdf.lib.SequenceToMatrix
- ptolemy.domains.sdf.lib.Repeat
- ptolemy.domains.sdf.lib.UpSample
tokenProductionRate -> null
tokenInitProduction -> null
tokenConsumptionRate -> null
- ptolemy.kernel.util.Attribute
_hideName -> ptolemy.kernel.util.SingletonAttribute
- ptolemy.domains.sr.kernel.Director
scheduler -> ptolemy.data.expr.StringParameter
- ptolemy.actor.lib.io.DirectoryListing
directoryOrURL -> ptolemy.actor.parameters.FilePortParameter
- ptolemy.actor.lib.TrigFunction
function -> ptolemy.data.expr.StringParameter
- ptolemy.vergil.actor.lib.VisualModelReference
modelFileOrURL -> ptolemy.actor.parameters.FilePortParameter
- ptolemy.actor.lib.Expression
expression -> ptolemy.kernel.util.StringAttribute
- ptolemy.domains.ct.kernel.CTMixedSignalDirector
breakpointODESolver -> null
- ptolemy.actor.lib.hoc.ModelReference
modelFileOrURL -> ptolemy.actor.parameters.FilePortParameter
- ptolemy.matlab.Expression
expression -> ptolemy.data.expr.StringParameter
- ptolemy.domains.fsm.modal.ModalModel
_Director -> null
directorClass -> ptolemy.data.expr.StringParameter
- ptolemy.domains.ct.kernel.CTMultiSolverDirector
breakpointODESolver -> null
- ptolemy.moml.filter.GRColorChanges: Update GR actor with the following changes:
Parameter name "RGB color" --> "diffuseColor"
- ptolemy.moml.filter.RemoveProperties: Remove the properties listed below:
- stopTime
- MaxDouble -> null
- ptolemy.data.expr.Parameter -> null
- 1.7976931348623157E308 -> null
- 1.7976931348623E308 -> null
- 1.797693134862316E308 -> null
- directorClass
- ptolemy.data.expr.StringParameter -> null
- ptolemy.domains.fsm.kernel.HSDirector -> null
- ptolemy.kernel.util.StringAttribute -> null
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.
- 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 5.0 website
Last Updated: $Date: 2005/07/21 16:01:28 $