ILOG VISUAL CP: OADymPPaC extension for ILOG Discovery

Contents

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: 

• Data > Open OAD File...: opens an xml file or gzip compressed xml file following the proper DTD
• Data > Open OAD Connection...: 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

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.

Installation

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.

• if the message does not appear, repeat steps 4 to 6
• if still unsuccessful, edit the HOME/{.}ILOG/java/discovery/discovery.prf file by hand, adding the lines:

  modules: .util.ModuleList {
  	modules {
  		"0" {
  			className = "ilog.oadymppac.actions.OADModule"
  			fileName = "oadymppac.jar"
  		}
  	}
  }
  

• if the message appears, but not the menu items, then check that the oadymppac.jar file is placed within the CLASSPATH or in the <install dir>/lib directory.

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:

• all variables and constraints are declared with a <new-variable> or <new-constraint> event before being used.
• tell/restore and the depth attributes are properly balanced and their depth attribute is properly set.
• variable domains are integer lists.

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: 

• There is one column in the output data set for each possible element attribute: event type, path, constraint name... Depending on the event, the column's value may or may not be meaningful. This is not a problem as visual data analysis in this case will require to be performed on an homogeneous set of objects. If two event types have a similar attribute whose semantic is different, then the attribute is still visible in the same column to save space. This is not a problem either, for the same reason.
• all top level events are represented by one line whose values 
• top level events that have sub elements, like a list of updates, are represented by as many lines as there are sub elements, one for each sub line.

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>
</reduce>

Are represented in a table like:

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

Examples

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

• the following events are ignored:"new-annotation",  "new-stage", "start-stage", "suspend-stage", "resume-stage", "end-stage"
• the following tags are ignored:  "explanation", "cause" and maybe some other tags I may have forgotten. The state tag is ignored because it is not useful in the context of Discovery, as a matter of fact, its use is dubious: as said before, it has nothing to do in the trace, and state information has to be retrieved via a protocol rather than at some incontrollable points inside the trace.
• the following tags are handled, but cannot be displayed for now: context, activities.

• Domains and value lists are stored internally as a java.lang.BitSet. While this is quite convenient for small variable domains, it can be very costly for large variable domains.

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.