next up previous index
Next: Grace Options Up: Grace 1.0 User Previous: Acknowledgements

Grace Predicates

 
grace
Switch Grace display on, this is also the default after loading the grace.pl library.

 

grace_label
Label all variables which have been registered using grace_matrix/2   and whose label   option is switched on. Grace will use the current variable and value selection strategies to select variables among the labelled ones and give them values. The variable selection strategy is applied to all variables together, no matter if they are defined inside one or several matrices. When all variables are ground, Grace stops labelling and considers this to be a solution.

 

grace_label(?Var)
Label the given variable. No manual variable selection is possible, and the corresponding buttons and menu items are disabled. This predicate is typically used inside user-defined labelling predicates to inform Grace about the selected variable.

 

grace_label(?Var, +List)
Label the given variable from the list List, but allow also the user to override this with a manual selection from the list.

 

grace_label_list(+List)
Label all variables in the given list. Grace will use the current variable and value selection strategies to select variables from the list and label them. All variables in the list should have been registered inside a variable matrix before. All variables in List will be labelled, no matter what is the label option of their matrix. When all variables in List are instantiated, this predicate succeeds, without assuming that this is a solution. When it is a solution, grace_solution/0   must be called explicitly.

This predicate is used e.g. when there are several groups of variables which should be labelled in a given order.

 

grace_lookahead_var(?Var)
Apply lookahead on the variable Var. All elements from the domain of Var will be removed which cannot be used to instantiate the variable.

 

grace_matrix(+Vars, +Name)
Register a variable matrix. Vars can be a simple list, a list of matrix rows or a structure whose arguments are rows. Each row can in turn be a list of variables or a structure with variable arguments. If it is a simple list, the matrix sizes are computed from the sizes of its column and row labels.

Domain variables and integers will be displayed in the variable matrix. If Vars contains non-domain free variables, they will be instantiated to the atom dummy_var and their positions in the variable matrix will stay empty. This is a way to structure the variable display to readable non-rectangular formats. For example, a magical hexagon with seven variables can be displayed in the matrix

[[_, A, _, B, _],
 [C, _, D, _, E],
 [_, F, _, G, _]]

If grace is on, a corresponding checkbox will be displayed in the control panel and if the show   option of this matrix is on (default), it will also be displayed. There are two possibilities how to position the variable matrix on the screen, implicit and explicit. A matrix is positioned explicitly, if its option matrix_geometry   is specified.

The first implicit variable matrix will be positioned on the screen so that its top left corner is in the position defined by the top   option (default +0+0). The next ones will be displayed right below the previous one. When one of the implicitly displayed matrices is removed from the screen by clicking on its checkbox in the control panel, all matrices that were displayed below it will move upwards to fill the gap. When the removed matrix is displayed again, it will appear below the last implicitly positioned matrix.

The background colour of the variable fields depends on the label   option of the matrix. Labelled matrices are white, the non-labelled ones gray.

 

grace_minimize(+Expression)
Find such an instantiation of all registered variables which minimises the linear expression Expression. The branch and bound method is used to find the optimum. Depending on the value of the branch_and_bound   option, either the min_max/5   or improved minimize/5   predicate is used. The Percent argument of these predicates can be specified with the option percent  . Minimum and maximum can be directly imposed on the value of the constrained expression. Nonlinear expressions can be equated to a new variable which is then used in the minimisation, i.e.
NonLinExpr #= Cost, grace_minimize(Cost)

The predicate is executed as follows: First the value of the Expression is computed and displayed in the status window and then Grace stops, waiting for (asynchronous) user input. This gives the user the possibility to modify interactively the options which control this predicate, because as soon as the optimisation starts, the optimisation parameters cannot be modified. Then a normal labelling starts. When a solution is found, it is displayed as usual, except that the number of solutions found so far displayed in the status window appears in parentheses, to make a distinction from the real solution (which is unique). The option all_solutions   controls whether Grace stops on each intermediate solution or not, i.e. it does not apply to the (real) optimal solution. During the execution, the current domain of Expression is always displayed as Cost in the status window.

 

grace_minimize(+List, +Expression)
This predicate is similar to grace_minimize/1  , except that the list of variables to be labelled is specified explicitly. This is useful e.g. when we want to label in a pre-defined order.

 

grace_option(?Window, +Option, ?Value)
This predicate modifies or returns the value of a given option. If Value is instantiated, the option value is set, if it is free, it will be bound to the current value of the option. Window is either the name of the window to which this option applies, one of control, varstack, elements (the window which displays a variable domain when pressing the right mouse button in a variable matrix), matrix (generic for all variable matrices), menu (all menus) or constraints (the constraint listbox displayed with the constraint list menu item). If it applies to a variable matrix, Window is either the name of the matrix, or, if the option should apply to all variable matrices, a free variable.

Value, if instantiated, is the value of the option, there is however one exception: if Value is a structure (not a list), Grace interprets it as a callable term which provides the option value dynamically. It adds one argument at the structure end and the resulting goal is called. When it returns, the value of the additional argument provides the option value. The goal is called by default in the caller module of the grace_start/1   predicate. This can be modified by specifying the value as Module:Pred, then the goal will be called in the module Module.

 

grace_solution
This predicate is called when the labelling is finished and the current variable instantiations represent a solution. When grace_label/0   is used, this predicate must not be called because grace_label/0   already calls it internally.

The number of solutions displayed in the control panel will be incremented by one and the message Found a solution is displayed in the status line. If the option display_solutions   is on, all other displays are updated as well. If the option all_solutions   is off, the program stops and waits for user input, otherwise this predicate immediately fails to force the program to look for the next solution.

 

grace_start(+Title)
Start Grace , initialise its internal data and display the control panel with the title Title and the varstack. The title can be inspected from the title   option. If a file .gracerc  exists in the current directory or in the user's home directory, it is compiled. This file can contain e.g. any user-, program- or machine-dependent options settings. Finally, the step mode is set and the predicate succeeds.

If the control panel is already displayed and its title equals to Title, Grace will perform a warm start without reading .gracerc and all option settings are kept.

This predicate is nondeterministic, it always creates an alternative which is used to restart the program either when the RESTART button is pressed or when the program finds all solutions.

 

grace_stop(+Message)
Stop the execution and process user events. Message is displayed in the status line of the control panel. Since this is not a regular step boundary, only asynchronous actions are accepted, in particular no variable selection or modification is possible. This predicate may be used e.g. after labelling a subset of variables to inspect the current state and possibly change the strategy before labelling the next group of variables.

 

grace_var_selection(+Name, +MinOrMax, +Pred, +Var, +Value)
This predicate provides an easy interface for defining new variable selection strategies. Very often the criterion which selects a new variable for labelling is a numerical value, and we want to select the variable whose value is minimal or maximal. The predicate which performs such a selection has always the same skeleton:

selectpred([H|T], Var) :-
    var_size(H, Val),
    find_var(T, H, Val, Var).
 
find_var([], Chosen, _, Chosen).
find_var([H|T], SoFar, OldVal, Var) :-
    var_size(H, NewVal),
    (
        NewVal >= OldVal             % when minimising
    ->
        find_var(T, SoFar, OldVal, Var)
    ;
        find_var(T, H, NewVal, Var)
    ).

We first compute the value for the first variable and then we go through the list looking for the best value. The predicate grace_var_selection/5 provides a simple way to define such predicates without having to write the skeleton again and again. Pred is the name (atom) of the defined predicate, MinOrMax is either min when we minimise or max to maximise. Pred is a callable term which represents the goal which computes the value Value for a given variable Var. The skeleton above would thus be defined by calling

grace_var_selection(selectpred, min, var_size(Var, Val), Var, Val)

 

nograce
Switch the Grace display off. A program executed with grace off will ignore all Grace predicates except for those which are necessary for its execution. Thus e.g. all options are set properly and grace_label/0   or grace_minimize/1 will have the usual effect.



next up previous index
Next: Grace Options Up: Grace 1.0 User Previous: Acknowledgements



Micha Meier
Tue Jul 2 10:07:34 MET DST 1996