CLPGUI 2.1.6 Technical Manual

François Fages, Projet Contraintes, INRIA Rocquencourt, France
January 9th 2003
updated August 24th 2006

Porting to other Constraint Programming Systems

Porting CLPGUI to another constraint programming system basically amounts to extend your favorite CP system with a facility for:

  1. writing the (trace) messages on the socket read by the GUI
  2. interpreting the (control) messages sent from the GUI
The syntax of these messages is described below. Note that this syntax will evolve to the XML syntax for generic trace formats defined in the OaDymPPac project when it is stable.

On the CLP side, CLPGUI needs to implement annotations (for sending messages to the GUI) and a meta-interpreter for interpreting the control messages sent from the GUI. CLPGUI uses GNU-Prolog backtrackable global variables (g_link predicate) to implement a general timestamp mechanism and references to variables. This should be the main difficulty to port CLPGUI to other Prolog systems. See for example the file for the porting to Sicstus Prolog.

Porting to non-Prolog based Constraint Programming systems should be feasible as well as long as there is some notion of search tree.

Communication from CLP to GUI

These messages are read in the GUI in Java by BufferedReader.readLine(). One message is thus one line of text and the messages are separated by new lines.

In the following, the numbers are positive integers, the names are strings separated by blanks, and the domains of variables are given in GNU-Prolog syntax. The domain of a finite domain variable is a parenthesized list of intervals (noted l..u) or single values, separated by :, like for instance (1:3:5..10:13:15..200) That domain can be prefixed by the variable internal name which is ignored. The domain or value of other variables is communicated as an uninterpreted string.

Information on variables:
a number_of_variables name1 ... nameN communicates the ordered list of variable names.
z size1 ... sizeN communicates the list of current domain sizes.
l size1 min1 max1 ... sizeN minN maxN communicates the list of current domain intervals.
v size1 domain1 ... sizeN domainN communicates the list of current domains of variables, following the GNU-Prolog syntax for domains explained above.
i name=string  sends as a string the value or domain of the named variable.

b string asks to create a button for posting a constraint, or executing a goal, represented as a string.

General control:
t number current time stamp representing the depth in the (traced) search tree.
e  clear.

Search tree:
n string creates a call node.
o string creates a call node the label of which will be always shown.
c string creates a child node.
s  success.
w  alsways show the label of the current node.
r  end of recomputation.

Simple directives concerning the viewers of domains:
nt don't trace backtracked goals
tr trace backtracked goals
sn show no domain
sz show sizes only
sv show values
sl show intervals only

Communication from GUI to CLP

(The following names should not be used as program predicates)

These messages are sent by the GUI to the CLP process. One message is one line of text terminated by a dot.

Simple directives concerning the sending of variable domains:
sn. show no domain.
sz. show sizes.
sv. show values.
sl. show intervals.
i name.
  asks for the value or the domain of the named variable.

General control:
d.  disconnect.
e.  clear.
  backtrack to last interaction.
b.  backtrack.
goal.  execute a Prolog goal.

j i1 ... iN. recomputes the state of the node represented by its path from the root given as a sequence of either integers representing the branch to follow in each node, or strings representing the goal to execute in an interactive node.
l. last node of recomputation.
c.continue recomputation.
k. allow backtracking above a recomputed node.


Currently, constraint propagation is not traced, simply because such traces are not available yet in GNU-Prolog. A generic trace format for constraint propagators is defined in the OaDymPpac project and will be implemented in the future.

The addition of new viewers currently imposes to get into the code of An API for viewers will be developped in the future using the Java event classes. That API will make it possible to add new application-oriented viewers to CLPGUI without changing the code of the GUI.

Recomputations may fail for programs with side effects (or using optimization predicates). This can be fixed by giving the possibility of recomputing not just the path from the root to the node, but the complete tree, or more efficiently with ad hoc techniques for builtin predicates like optimization predicates.


User Manual

CLPGUI: a Generic Graphical User Interface for Constraint Logic Programming  by François Fages, Sylvain Soliman and Rémi Coolen. Journal of Constraints 9(4) 2004. Preprint available at ps.gz.

Feedback appreciated:

Mail to  Franç