ILOG VISUAL CP: OADymPPaC extension for ILOG Discovery


This package contains an extension for ILOG Discovery enabling loading and analyzing program traces following the OADymPPaC DTD

Two new menu items are added by the extension: 

A BitFieldExpression projection element is added. This projection element enables displaying Integer column types as a bit field, for instance in the Parallel Histograms views. 

The conversion process from an XML file to a flat data table needs to be understood to take full advantage of ILOG Discovery for OADymPPaC. It is highly recommended to read the related section.


To install the OADymPPaC extension:

  1. Make sure you have installed a distribution dating after July 18th, 2003. If not, replace the Discovery.jar file in <install dir>/lib with the one provided.
  2. copy the file oadymppac.jar into the discovery distribution folder, in <install dir>/lib,
  3. launch discovery.
  4. open the Edit > Preferences dialog
  5. in the preferences > modules list, click the "+" button this has the effect of adding a new module entry, comprising 3 fields.
  6. type in ilog.oadymppac.actions.OADModule in the className field and press return to validate the change, then oadymppac.jar in the fileName field, still pressing return to validate the change.
  7. restart discovery, the module should have been installed. You can check this by seeing that 2 new menu items have been added in the "Data" menu.
  8. If you run discovery from the command line, you may want to add the file oadymppac.jar to your CLASSPATH environment variable.

Trouble shooting installation

    If the two menu items to not appear after having restarted discovery, check if the message "Warning: could not find module ilog.oadymppac.actions.OADModule" appears on the console.

Using ILOG Discovery for OADymPPaC

To use the OADymPPaC module, you generate files from your tracer, or let it accept http connections and requests. It is important that those files follow the proper semantics:

Next, you should limit the trace events to the type of information you want to display. If you are only interested in the search tree (for Prolog-like solvers) and variable's domains, you can produce only the following events: new-variable, new-constraint, select-constraint, tell, reduce, restore, solution. (By the way, this is perhaps the proper default trace that should be used in discovery.) If you want to study structure solutions, you may only output the solutions. Yet, the DTD is incomplete in this respect: for the visualizer to be able to represent the solutions, tell, restore and reduce events must also be generated. 

User Reference

Data > Open OAD File Action

This action opens an xml file or gzip compressed xml file following the proper DTD. This action lets you choose a file, then prompts you a dialog to let you specify the columns you want to see displayed:

Use combinations of click, Ctrl+click and Shift+click to select the columns you want to analyze. Highlighted columns are the one that will be inserted in the data table. See below for an explanation of each column's content. Keep in mind that depending on the trace that was generated, many columns may not contain meaningful data. Thus it is useful to carefully select the useful columns.

Data > Open OAD Connection... Action

This action opens an http connection expected to return a trace in the appropriate format. Compressed traces are accepted if the url's fine name ends with .gz or .gzip. This action lets you enter a URL instead of a file, and otherwise has the same behavior as the previous action.

BitFieldExpression field expression

This expression is used in the record > fields > field > X expressions of the projection. Instead of representing a bar of length proportional to an integer value, the display appears as a set of dots which represents the set bits inside the integer.

Trace Format

The expected input format is described in the 6th version of the DTD. I believe the semantics is correctly interpreted, modulo the few limitations we had to introduce.

Conversion from a Trace to data table

The document is transformed in a flat data table using the following scheme: 

Example: the following (fictional) events:

<new-constraint n=1 name="c1" erep="A#B">
<reduce n=2 redtype="min" constraint="c1">
<update variable="A"><domain value="1..4"/></update>
<update variable="B"><domain value="1"/></update>

Are represented in a table like:

event n constraint redtype variable domain domainSize
new-constraint 1 A#B notset

reduce 2 A#B min A 1..4 4
reduce 2 A#B min B 1 1

This representation preserves all the information provided by the trace and allows full description of any type of visualization that one may want to produce with Discovery. Internally, redundancy is minimized: lines are not repeated in memory, they are only repeated in the table model. The drawback is that it can generate a large number of columns, many of which being empty. This is why the user is prompted to select which columns to display when they open a trace.

Columns reference

Column name Corresponding XML element/attribute Type Meaning
event XML tag of the current event: Enumeration One of: "null", "new-variable", "new-constraint", "reduce", "restore",
"wake-up", "suspend", "true", "reject", "activate", "deactivate",
"select-constraint", "select-update", "tell", "solution".

Other events are ignored for now.

id node.n Integer event's number in the trace
path Reconstructed position in the search tree. String /node number/node number/ and so forth, where node numbers are a sequence of tell nodes.
constraint %constraintAttribute externalrep if defined, else internalrep, else cname String The current constraint valid anywhere the %constraintAttributes tag is defined, that is everywhere. For tell events, the last selected constraint is used.
Enumeration The constraint's type: one of "notset", "user", "system". valid only when there is a current constraint.
variable externalrep if defined, else internalrep, else vname String The current variable. valid only for reduce, update, 
Enumeration One of: "notset", "int", "rat", "real", "enum", "string"
rtype update rtype Enumeration the reduction type. This attribute is meaningful in the context of "reduce", "restore", "solution", "select-update" and "new-variable" events only. One of: "notset", "ground", "any", "min", "max", "minmax", "empty", "val", "nothing", "solution", "select", "initial", "restore".
domain valueList String a textual representation of the domain: numerically ordered list of values or ranges. individual values are separated by a space, and ranges's boundaries are separated by "..".
time time Integer an integer representing the time spent since origin. Whereas the n attribute is purely ordinal, this attribute should be considered a cardinal 
val solution val Integer solution.val or 0 if the current line is not par of a solution element.
depth depth Integer the depth attribute for tell and restore events, the parent's depth attribute for other events, or 0 for top level events. Note that since a restore is a child of a corresponding tell, the restore's depth value is actually one less than its actual position in the search tree.
domainMin valueList extract Integer the minimum value of the domain
domainMax valueList extract Integer the maximum value of the domain
domainSize valueList extract Integer The number of values held in the domain
domainInterval valueList extract Integer domainMin - domainMax + 1
reduction - Double For reduce and restore events, the new domain size / previous domain size. Useful as an attribute to evaluate the efficiency of reduce events.


The directory samples contains a simple project and some data files which have been used to test the implementation. Right now, the views we propose are only a search tree viewed as a treemap and a parallel histogram showing all the events.

Known limitations and shortcomings


Trouble shooting

The example files provided started with: <!DOCTYPE oadymppac SYSTEM "oadymppac.dtd">. This is incorrect, as it assumes that the oadymppac dtd will always be available in the same folder as the trace file, which is very unlikely. The file should either include a valid and permanent path to the DTD, or not include the DTD info at all (which is simpler). If you generate traces, you should not include this line.

Also, many externalrep tags contain useless info, such as "unknown". The tracer should not set this attribute if it is not interpretable. this results in oversized input and impossible to understand views.