Starting CLPGUI

To run CLPGUI, you have to load the Prolog program clpgui.pl which will call the Java program CLPGUI.java. Both processes will communicate by sockets.

On the Prolog side, you can directly start the clpgui binary if it is available for your machine, or call Prolog and load [clpgui]. This will start the CLP server on port 27311 by default, and will create the Java GUI client process. A different port can be given as an argument to the command line clpgui (or to the command line for calling Prolog). If you prefer to start the Java process manually, add the argument nojava after the port number in the command line, and start the GUI process with the command java CLPGUI.

This will create the following console:

The connection to the CLP server is established by pressing on CLP connect. Different viewers can be selected in the menu. Dy default, all viewers are opened. Any CLP goal, including file loading, can be executed by entering it in the text field.
 

Search tree viewers

The search tree viewers provide different views of the search tree and can be applied to very large search trees. The type of view is selected in the menu, and several viewers can be run simultaneously. A search tree can also be freezed in a particular state.

The successes are marked with a red cross. The labels of the nodes can be displayed by moving the mouse on them. The current node is always displayed, in blue.

The figure can be moved, zoomed or rotated by dragging the mouse. The mode is selected in the menu, or can be changed by a simple click. Note that the zoom preserves the position on the screen of the first point where the mouse was dragged.

A node can be selected by clicking on it. Several actions are possible in the menu bar w.r.t. to the selected node, such as hiding or showing the subtree below the node, or recomputing the state of that node as current state. The recomputation algorithm of CLPGUI supports arbitrary CLP programs with cuts and exceptions, but may produce an error with programs containing side effects (e.g. with predicate fd_minimize). This defect will be corrected in a later version.

We propose also a 3D view of the search tree obtained by alternating the planes of successors.We have found that the 3D views are the most appropriate ones to apprehend the shape of large search trees by playing with rotations. The following figure picture out a 3D representation of the search tree for the bridge scheduling problem (4000 nodes):
 
 

Finite domains viewers

These viewers are dedicated to CLP programs over finite domains. They provide a dynamic visualization of the evolution of finite domain variables over time, plus some interaction capabilities to instanciate the variables. The domains of variables are represented by their size only, their range or the list of values, according to the option set in the main console or in the CLP program.

The 2D viewer displays a simple matrix representing the current domain of each variable. Each row corresponds to a variable and each column to a value. A click in a position of the matrix will instanciate the variable to the value corresponding to the position of the click. Note that nothing is traced with this viewer if the show option is set to "size only" or "no domain". The following figure shows an optimal solution to the bridge scheduling problem:
 
 

The Sudoku finite domains viewer displays the domains of variables in a square matrix, filled line by line with the variables of the problem in order. A click in the matrix will open a dialog box for entering the value of the corresponding variable. The following figure shows the effect of the all_different constraints in lines, columns and 3x3 squares in a 9x9 Sudoku.

The 3D finite domain viewer displays the evolution of the size of the domains of variables over time. A menu of options makes it possible to trace or not backtracking steps. Backtracking steps appear in light blue, by default they are not traced.
 
 

The figure can be moved, zoomed and rotated as in the search tree viewer. Information about the executed goals at the different times or about the variables at the current time can be obtained by moving the mouse on the front line of variable or on the front time line. Variables which are not finite domain are shown with a size 0, their value (as a term) can be obtained by moving the mouse on them.
 

Annotations in the CLP program

The CLP program can be annotated for providing external names to CLP variables, creating buttons for specific goals, and specifying the level of granularity of the search tree.

For following program is an example for the puzzle SEND+MORE=MONEY:

sendmore(L):-
        L=[S,E,N,D,M,O,R,Y],
        gui_varnames(L,['S','E','N','D','M','O','R','Y']),
        fd_domain(L,0,9),
        gui_show_values,
        gui_button(fd_domain([S,M],1,9)),
        gui_button(1000*S+100*E+10*N+D + 1000*M+100*O+10*R+E #= 10000*M+1000*O+100*N+10*E+Y),
        gui_button(fd_all_different(L)),
        gui_button(gui_trace_labeling(L)),
        reverse(L,L2),
        gui_button(gui_trace_labeling(L2)).

The clause defines the external names of the variables and adds buttons to the CLPGUI console for posting constraints and for executing the labeling predicate witha choice of two variable orderings:
 
 

The following CLPGUI predicates can be used to annotate CLP programs. They are prefixed by guito be easy to repair.

gui gui(Port)
starts CLPGUI on a given port, port 27311 by default.gui is called when loading clpgui.pl.

gui_varnames(LV,LN) gui_varnames(LV)
associates external names to a list of CLP variables LV, which may be not  finite domain. If no names are provided, standard names V1, V2,... are created.

gui_addvarnames(LV,LN)
associates external names to a list of CLP variables LV but does not inform the GUI.

gui_varnames
sends the list of variable names to the GUI (necessary only after gui_addvarnames).

gui_show_sizes gui_show_intervals gui_show_values gui_show_no_domain
defines the information sent on variable domains (can be redefined form the CLPGUI console). The default is the size of domains.

gui_button(Goal)
creates a button for executing Goal

gui_bagof_buttons(GoalTemplate,Goal)
creates a button for each instance of GoalTemplate success of Goal. Note that due to a bug in bagof, gui_bagof_buttons must be called before variables are given a finite domain.

gui_trace_search(Goal)
traces the call to Goal with one call node and as many child nodes as successes to the goal. Child nodes are useful to distinguish the choice points of traced goals from the choice points created by non traced goals.

gui_trace_call(Goal)
traces the call to Goal with one call node only.

gui_trace_search_predicate(P/A) gui_trace_call_predicate(P/A)
trace all the calls to predicate P of arity A. The clauses of P must be declared dynamic.

gui_trace_labeling(L)
traces the labeling of the variables in L. It is defined by:
    gui_trace_labeling([]).
    gui_trace_labeling([X|L]):- gui_trace_search(fd_labeling(X)), gui_trace_labeling(L).

gui_show
marks the last node with a red cross.

gui_show(Term)
creates a dummy node labeled by Term in red.

gui_interact
creates a break point where the user can interact from the console and continue the resolution.

gui_no_trace_backtracking gui_trace_backtracking
sets option to the 3D finite domains viewer
 

The file nogui.pl redefines these predicates as doing nothing. Loading nogui.pl is useful for keeping the annotations in a CLP program and execute it without CLPGUI.
 
 

Examples (GNU-Prolog)

append.pl, send.pl, queens.pl, bridge.pl, sudoku.pl
 

Reference:

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.

Technical manual

OaDymPpac project, Tools for Dynamic Analysis and Debugging of Constraint Programs.

Home page