Display Matrix

This tool provides a method to display the values of terms in a matrix form. It is particularly useful because it can display the attributes of an attributed variable.^4.1The predicate which invokes the display matrix is considered a no-op in the tty-based ECLiPSe^4.2, and so the same code can be run without modification from either eclipse or tkeclipse, though the matrix display is only presented to the user in the latter.

This tool is invoked using either the make_display_matrix/2 predicate or the make_display_matrix/5 predicate. Adding a call to one of these predicates should be the only change you need to make to your code. For example, in the following fragment of a N-queens program, only one extra line has been added to invoke a display matrix:

   queens(N, List) :-
       length(List, N),
       List :: 1..N,
       make_display_matrix(List/0, queens),
 % sets up a matrix with all variables in 1 row. This is the only
% extra goal that has to be added to enable monitoring
       alldistinct(List),
       constrain_queens(List),
       labeling(List).

Figure 4.1: Display Matrix Tool for 4-Queens (Initial)

Figure 4.2: Display Matrix Tool for 4-Queens (During execution)

Figures 4.1 and 4.2 show the tool invoked with the example N-Queens programs for 4 Queens, at the start initially and during the execution of the program. The name of the display window is specified by the second argument of make_display_matrix/2, along with the module it is in. The values of the terms are shown in the matrix, which can be one dimensional (as in this case), or two dimensional. Spy points can be set on each individual cell of the matrix so that execution will stop when the cell is updated. The matrix can be killed using the `Kill display' button. Left-clicking on a cell will bring up a menu which shows the current and previous value of the term in the cell (the current value is shown because the space available in the cell may be too small to fully display the term), and allows the user to inspect the term using the inspector.

Note that the display matrix can be used independently of, or in conjunction with, the tracer. Multiple display matrices can be created to view different terms.

The following predicates are available in conjunction with the display matrix:

make_display_matrix(+Terms, +Name)
make_display_matrix(+Terms, +Prio, +Type, +CondList, +Name)

These predicates create a display matrix of terms that can be monitored under TkECLiPSe. The two argument form is a simplification of the five argument form, with defaults settings for the extra arguments. Terms is a list or array of terms to be displayed. A List can be specified in the form List/N, where N is the number of elements per row of the matrix. If N is 0, then the list will be displayed in one row (it could also be omitted in this case). The extra arguments are used to control how the display is updated.

The terms are monitored by placing a demon suspension on the variables in each term. When a demon wakes, the new value of the term it is associated with is sent to the display matrix (and possibly updated, depending on the interactive settings on the matrix). When the new value is backtracked, the old value is sent to the display matrix. The other arguments in this predicate is used to control when the demon wakes, and what sort of information is monitored. Prio is the priority that the demon should be suspended at, Type is designed to specify the attributes that is being monitored (currently all attributes are monitored, and Type is a dummy argument), CondList is the suspension list that the demon should be added to. Depending on these arguments, the level of monitoring can be controlled. Note that it is possible for the display matrix to show values that are out of date because the change was not monitored.

The display matrix will be removed on backtracking. However, it will not be removed if make_display_matrix has been cut - kill_display_matrix/1 can be used to explicitly remove the matrix in this case.

kill_display_matrix(+Name)

This predicate destroys an existing display matrix. Name is an atomic term which identifies the matrix.

Destroys an existing display matrix. The display matrix is removed from being displayed.

Invoking display matrix tool interactively

Display matricies can be created interactively when a program is executing, if the program is being debugged with the tracer tool. The user can select terms that are to be observed by a display matrix while at a debug port. This can be done from the inspector, the tracer, and the delay goal tools. See the online help files (available from the help menu of TkECLiPSe) for more details.