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:
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.
modules: .util.ModuleList {
modules {
"0" {
className = "ilog.oadymppac.actions.OADModule"
fileName = "oadymppac.jar"
}
}
}
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.
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.
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.
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.
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.
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>
</reduce>
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.
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. |
ctype | 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, |
vtype | 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.
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.