Personal tools
You are here: Home Developer Reference Updating the Kepler Directors and Actors

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="&quot;ptolemy.domains.ct.kernel.solver.ExplicitRK45Solver&quot;">
        </property>
        <property name="choice1" class="ptolemy.data.expr.Parameter"
                  value="&quot;ptolemy.domains.ct.kernel.solver.ExplicitRK23Solver&quot;">
        </property>
        <property name="choice2" class="ptolemy.data.expr.Parameter"
                  value="&quot;ptolemy.domains.ct.kernel.solver.BackwardEulerSolver&quot;">
        </property>
        <property name="choice3" class="ptolemy.data.expr.Parameter"
                  value="&quot;ptolemy.domains.ct.kernel.solver.ForwardEulerSolver&quot;">
        </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="&quot;ExplicitRK23Solver&quot;">
        </property>
        <property name="choice1" class="ptolemy.data.expr.Parameter"
                  value="&quot;ExplicitRK45Solver&quot;">
        </property>
    </property>
</property>

ContinuousDirector does not have a breakpointODESolver, so remove:

<property name="breakpointODESolver" class="ptolemy.data.expr.Parameter"
          value="&quot;ptolemy.domains.ct.kernel.solver.DerivativeResolver&quot;">
    <property name="style" class="ptolemy.actor.gui.style.EditableChoiceStyle">
        <property name="choice0" class="ptolemy.data.expr.Parameter"
                  value="&quot;ptolemy.domains.ct.kernel.solver.DerivativeResolver&quot;">
        </property>
        <property name="choice1" class="ptolemy.data.expr.Parameter"
                  value="&quot;ptolemy.domains.ct.kernel.solver.BackwardEulerSolver&quot;">
        </property>
        <property name="choice2" class="ptolemy.data.expr.Parameter"
                  value="&quot;ptolemy.domains.ct.kernel.solver.ImpulseBESolver&quot;">
        </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

 







Document Actions