- 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.