Home
Forgot your password?
New user?
Updating the Kepler Directors and Actors
How to update the set of Directors and Actors that are shipped with Kepler
Kepler includes two modules, "directors" and "actors". Below is a description on how to add a new director or actor that is to be shipped with Kepler. Note that this is different than
Developing a Hello World Actor using the Kepler Build System and Eclipse, which describes how to create actors for your own use. Here we are adding a director or actor to the default configuration to be used by all users. To make a director or actor available to all Kepler users, you must have write access to the Kepler Subversion repository.
In the example below, we add a director with the classname ptolemy.domains.continuous.kernel.ContinuousDirector. This director has already been added, below are the steps that were taken.
Getting started
Download and build the Kepler development tree. See Kepler and Eclipse.
An overview of the directors module layout
After Kepler has been downloaded and Kepler has been invoked, you will have a kepler/directors directory.
bash-3.2$ ls kepler/directors build.xml kar lib resources
Below is a description of two of the directories:
- kar/
- Created when Kepler is run. The "ant run output will contain something like "[run] Building Kars..."
- resources/
- resources/kar/ contains the descriptions of the directors. See below:
bash-3.2$ ls kepler/directors/resources/kar CTDirector DDFDirector PNDirector ContinuousDirector DEDirector SDFDirector bash-3.2$ ls kepler/directors/resources/kar/CTDirector CTDirector.xml MANIFEST.MF
From the above, we can see that kepler/directors/resources/kar/CTDirector contains two files CTDirector.xml and Manifest.MF. We will use these two files as our sources.
Adding a new Director to directors/resources/kar
1. Copy the CTDirectory files:
bash-3.2$ cd kepler/directors/resources/kar
bash-3.2$ mkdir ContinuousDirector
bash-3.2$ cd ContinuousDirector
bash-3.2$ cp ../CTDirector/CTDirector.xml ContinuousDirector.xml
bash-3.2$ cp ../CTDirector/MANIFEST.MF .
bash-3.2$ ls
ContinuousDirector.xml MANIFEST.MF
2. Edit ContinuousDirector.xml and make changes
Change the name of the PropertyEntity from:
<property name="CT Director" class="org.kepler.moml.PropertyEntity">
to:
<property name="Continuous Director" class="org.kepler.moml.PropertyEntity">
Kepler uses Kepler Life Science Ids (LSIDs) to manage naming and lookup of components. When creating a new director, you should come up with a new authority and revision. For each new object, increment the revision. See How to generate a LSDID for an XML description of an actor or director.
Update the NamedObjId from:
<property name="entityId" value="urn:lsid:kepler-project.org:director:4:1"
class="org.kepler.moml.NamedObjId"/>
In the above, the authority is "kepler-project.org". If you have write access to the Kepler SVN repository, then you may use that authority. Otherwise, use the name of an internet host that you control, for example "myhost.myschool.edu". In the above, the revision is "4". If you are using "kepler-project.org", then find the highest revision of all the directors and use a number one greater. For example, if the highest revision found in kepler/directors/resources/kar/*/*.xml is "5", then the next revision would be "6". If you are using your own authority, then start with "1". Note that if you have using your own authority, you will need to keep track of the maximum revision for each object type.
FIXME: Where is the maximum revision for the actors kept? Or, do we just search.
<property name="entityId" value="urn:lsid:myhost.myschool.edu:director:1:1"
class="org.kepler.moml.NamedObjId"/>
Update the author from:
<property name="author" class="ptolemy.kernel.util.ConfigurableAttribute">
<configure>Jie Liu, Haiyang Zheng</configure>
</property>
to the value for the @author javadoc tag from the source file for the director, which is located at: ptolemy/ptolemy/domains/continuous/kernel/ContinuousDirector.java
<property name="author" class="ptolemy.kernel.util.ConfigurableAttribute">
<configure>Haiyang Zheng and Edward A. Lee, based on CTDirector by Jie Liu and
Haiyang Zheng</configure>
</property>
Update the user level documentation from:
<property name="userLevelDocumentation" class="ptolemy.kernel.util.ConfigurableAttribute"> <configure> <p>The Continuous Time (CT) Director is designed to oversee workflows that predict how systems evolve as a function of time (i.e., "dynamic systems"). In CT workflows, the rates of change of parameters are related to the current value or rates of change of other parameters, often in complex and coupled ways that are described by differential equations.</p> ... <p>For more information about the CT Director, see the Ptolemy II User Manual http://ptolemy.eecs.berkeley.edu/papers/05/ptIIdesign3-domains/ptIIdesign3-domains.pdf. </p> </configure> </property>
to the Javadoc class documentation from ContinuousDirector.java. Note that it is best if the html is well formed xml, which means that <p> tags should be closed with </p> tags etc.
The update is:
<property name="userLevelDocumentation"
class="ptolemy.kernel.util.ConfigurableAttribute">
<configure>
The continuous time domain is a timed domain that supports
continuous-time signals, discrete-event signals, and mixtures of the
two. There is a global notion of time that all the actors are aware of.
...
This director is based on the CTDirector by Jie Liu and Haiyang Zheng,
but it has a much simpler scheduler and a fixed-point semantics.</p>
</configure>
</property>
Create documentation for each parameter. Replace all the parameters in the original file:
<property name="prop:initStepSize" class="ptolemy.kernel.util.ConfigurableAttribute">
<configure>The initial integration step size. The value is a double that defaults to 0.1.</configure>
</property>
...
<property name="prop:valueResolution" class="ptolemy.kernel.util.ConfigurableAttribute">
<configure>Value resolution specifies how close values must be to be considered fixed.
The default is 1e-6.</configure>
</property>
with a new entry for each property. The format is that the name should have "prop:" followed by the property name. The contents of the <configure> tag should be the javadoc for the property. For example, the first parameter in ContinuousDirector.java is:
/** Error tolerance for data values, used with variable step
* size solvers to determine whether the current step size is accurate.
* The default value is 1e-4, and the type is double.
*/
public Parameter errorTolerance;
ContinuousDirector.xml will be updated with:
<property name="prop:errorTolerance" class="ptolemy.kernel.util.ConfigurableAttribute">
<configure>Error tolerance for data values, used with variable step size solvers to
determine whether the current step size is accurate. The default value is 1e-4,
and the type is double.</configure>
</property>
Do the same for each parameter in ContinuousDirector.java and (I think) for each parameter in the parent classes of ContinuousDirector.java (Someday, it would be nice to have a javadoc doclet that generated these files.)
For the "class" property, update the classname to the fully qualified dot separated class name and update the id to the value used in the EntityId above. Change
<property name="class" value="ptolemy.domains.ct.kernel.CTMixedSignalDirector"
class="ptolemy.kernel.util.StringAttribute">
<property name="id" value="urn:lsid:myhost.myschool.edu:director:1:1"
class="ptolemy.kernel.util.StringAttribute"/>
</property>
To:
<property name="class" value="ptolemy.domains.continuous.kernel.ContinuousDirector"
class="ptolemy.kernel.util.StringAttribute">
<property name="id" value="urn:lsid:kepler-project.org:directorclass:4:1"
class="ptolemy.kernel.util.StringAttribute"/>
</property>
The next lines deal with the semantic types. For a director, the semantic types may remain as is:
<property name="semanticType00" value="urn:lsid:localhost:onto:1:1#Director"
class="org.kepler.sms.SemanticType"/>
<property name="semanticType11" class="org.kepler.sms.SemanticType"
value="urn:lsid:localhost:onto:2:1#Director"/>
The next section indicates any SharedParameters and any Parameters that have choices. ContinuousDirector extends FixedPointDirector, which extends Director and Director has a shared Parameter "timeResolution, so leave this property
<property name="timeResolution" class="ptolemy.moml.SharedParameter" value="1E-10"> </property>
However, ContinuousDirector has an ODESolver parameter that has different choices. ContinuousDirector.java contains:
ODESolver = new StringParameter(this, "ODESolver");
ODESolver.setExpression("ExplicitRK23Solver");
ODESolver.addChoice("ExplicitRK23Solver");
ODESolver.addChoice("ExplicitRK45Solver");
Update:
<property name="ODESolver" class="ptolemy.kernel.util.Attribute">
<property name="style" class="ptolemy.actor.gui.style.EditableChoiceStyle">
<property name="choice0" class="ptolemy.data.expr.Parameter"
value=""ptolemy.domains.ct.kernel.solver.ExplicitRK45Solver"">
</property>
<property name="choice1" class="ptolemy.data.expr.Parameter"
value=""ptolemy.domains.ct.kernel.solver.ExplicitRK23Solver"">
</property>
<property name="choice2" class="ptolemy.data.expr.Parameter"
value=""ptolemy.domains.ct.kernel.solver.BackwardEulerSolver"">
</property>
<property name="choice3" class="ptolemy.data.expr.Parameter"
value=""ptolemy.domains.ct.kernel.solver.ForwardEulerSolver"">
</property>
</property>
</property>
To:
<property name="ODESolver" class="ptolemy.kernel.util.Attribute">
<property name="style" class="ptolemy.actor.gui.style.EditableChoiceStyle">
<property name="choice0" class="ptolemy.data.expr.Parameter"
value=""ExplicitRK23Solver"">
</property>
<property name="choice1" class="ptolemy.data.expr.Parameter"
value=""ExplicitRK45Solver"">
</property>
</property>
</property>
ContinuousDirector does not have a breakpointODESolver, so remove:
<property name="breakpointODESolver" class="ptolemy.data.expr.Parameter"
value=""ptolemy.domains.ct.kernel.solver.DerivativeResolver"">
<property name="style" class="ptolemy.actor.gui.style.EditableChoiceStyle">
<property name="choice0" class="ptolemy.data.expr.Parameter"
value=""ptolemy.domains.ct.kernel.solver.DerivativeResolver"">
</property>
<property name="choice1" class="ptolemy.data.expr.Parameter"
value=""ptolemy.domains.ct.kernel.solver.BackwardEulerSolver"">
</property>
<property name="choice2" class="ptolemy.data.expr.Parameter"
value=""ptolemy.domains.ct.kernel.solver.ImpulseBESolver"">
</property>
</property>
</property>
That's it for ContinuousDirector.xml
Edit MANIFEST.MF
The MANIFEST.MF file defines attributes specific to the Kepler Archive (KAR) file. See the KAR Manifest Specification for details about the file format.
At least two items need to be updated the kar lsid, name and the lsid.
The kar lsid follows the same rules as the entityID above. FIXME: how do I find the maximum kepler-project.org kar revision?
The Name should be changed from CTDirector.xml to ContinuousDirector.
The lsid of the director should be changed to the value of the entityID.
Change:
lsid: urn:lsid:kepler-project.org:kar:329:1 Name: CTDirector.xml lsid: urn:lsid:kepler-project.org:director:4:1
To:
Manifest-Version: 1.4.2 KAR-Version: 2.0 lsid: urn:lsid:myhost.myschool.edu:kar:1:1 Name: CTDirector.xml lsid: urn:lsid:myhost.myschool.edu:director:1:1
Update uiSVGIconMappingByClass.xml
To get the megaphone icon, update kepler/gui/resources/configurations/uiSVGIconMappingsByClass.xml and add the new director:
<config> <!--### DIRECTOR ICONS ###########################--> <pair> <name>ptolemy.domains.ct.kernel.CTMixedSignalDirector</name> <value>director</value> </pair>
Becomes:
<config> <!--### DIRECTOR ICONS ###########################--> <pair> <name>ptolemy.domains.continuous.kernel.ContinuousDirector</name> <value>director</value> </pair> <pair> <name>ptolemy.domains.ct.kernel.CTMixedSignalDirector</name> <value>director</value> </pair>
Run Kepler with the New Director
Then, try running Kepler:
cd kepler/build-area ant run
Then try searching for the new director "ContinuousDirector".
If you have problems, try running:
ant clean-cache ant run
about how to chage the actor's color
