[ library(gfd) | Reference Manual | Alphabetic Index ]
search(+L, ++Arg, ++Select, +Choice, ++Method, +Option)
Interface to gecode search-engines to perform search in gecode.
- L
- is a collection (a la collection_to_list/2) of domain
variables (Arg = 0) or a collection of terms (Arg > 0)
- Arg
- is an integer, which is 0 if L is a collection of
domain variables or greater than 0 if L consists of terms of
arity greater than Arg, the value Arg indicates the
selected argument of the term
- Select
- is a predefined variable selection method. Predefined methods are
input_order, first_fail, anti_first_fail, smallest, largest,
occurrence, anti_occurrence, most_constrained,
most_constrained_per_value, least_constrained_per_value,
max_regret, max_regret_lwb, min_regret_lwb, max_regret_upb,
min_regret_upb, random, max_weighted_degree, min_weighted_degree,
max_weighted_degree_per_value, min_weighted_degree_per_value
- Choice
- is the name of a predefine value choice method for choosing
the value to try for a variable; Predefined choice methods are:
indomain, indomain_reverse_enum, indomain_min, indomain_max,
indomain_middle, indomain_median, indomain_split,
indomain_reverse_split, indomain_random, indomain_interval,
indomain_interval_min, indomain_interval_max
- Method
- is one of the following: complete,
bb_min(Cost:domain variable),
restart_min(Cost:domain variable)
- Option
- is a list of option terms. Currently recognized are:
tiebreak(+Select), stats(+Stats), limits(+Stop),
timeout(+Seconds), control(+Control), backtrack(-N),
node(+Call), nodes(+N)
Description
Search/6 provides an interface to gecode's search-engine,
to allow search to be performed by gecode. It is designed to have the same
arguments as the generic search/6 routine available for integer domain solvers.
so that for common cases, the call will work for both search/6. The generic
search/6 is available in the gfd_search module. The difference is that here
the search is performed by gecode, and is an atomic step when viewed from
ECLiPSe. For the non-optimising search method, backtracking into this
predicate will produce the next solution if it exists. By changing the
Method argument, different gecode search-engines (implementation
of different complete, partial and optimising search algorithms (and
their parameters)) can be selected and controlled. The availability of
optimising search-engines means that this predicate also provide some of
the functionality of lib(branch_and_bound). The predicate also provides a
number of pre-defined variable selection methods (to choose which variable
will be assigned next) and some pre-defined value assignment methods
(to try out the possible values for the selected variable in some
heuristic order).
In order to allow more structure in the application program, it is possible
to pass a collection of terms rather than only a collection of domain
variables. In this way all information about some entity can be easily
grouped together.
The variable selection and value choice methods are defined by gecode. They
are mapped to the closest matching methods in the generic search/6 (or with
a name following the same convention if the method have no correspondence).
For variable selection, if several entries
have the same heuristic value, then a tiebreak selection method, specified by
the tiebreak method, can be used to chose from these entries. Note that
there are some differences from ECLiPSe search in how the methods are
applied: variable selection is always performed before each value selection:
in ECLiPSe, once a variable is selected, all the possible values for that
variable are tried on backtracking without re-selecting the variable.
The pre-defined selection methods (with the gecode name in brackets)
use the following criteria:
- input_order (INT_VAR_NONE) the first entry in the list is selected
- random (INT_VAR_RND) an entry is selected at random.
- anti_occurrence (INT_VAR_DEGREE_MIN) the entry whose corresponding gecode variable with the
smallest number of attached propagators is selected
- occurrence (INT_VAR_DEGREE_MAX) the entry whose corresponding gecode variable with the
largest number of attached propagators is selected
- min_weighted_degree (INT_VAR_AFC_MIN) the entry with the smallest
weighted degree is selected.
- max_weighted_degree (INT_VAR_AFC_MAX) the entry with the largest
weighted degree is selected. Weighted degree is call AFC (accumulated failure
count) in gecode, and is a count of the number of failures so far of
propagators associated with the variable, plus the number of propagator
attached to the variable (to give reasonable starting values when there are
not failures yet).
- smallest (INT_VAR_MIN_MIN) the entry with the smallest value in the domain is selected
- smallest_upb (INT_VAR_MIN_MAX) the entry with the smallest
upper bound in the domain is selected
- largest_lwb (INT_VAR_MAX_MIN) the entry with the largest lower
bound in the domain is selected
- largest (INT_VAR_MAX_MAX) the entry with the largest value in the domain is selected
- first_fail (INT_VAR_SIZE_MIN) the entry with the smallest domain size is selected
- anti_first_fail (INT_VAR_SIZE_MAX) the entry with the largest domain size is selected
- least_constrained_per_value (INT_VAR_SIZE_DEGREE_MIN) the entry with the largest domain size
divided by the number of attached propagators.
- most_constrained_per_value (INT_VAR_SIZE_DEGREE_MAX) the entry with the smallest domain size
divided by the number of attached propagators.
- min_weighted_degree_per_value (INT_VAR_SIZE_AFC_MIN) the entry with
the smallest domain size divided by weighted degree is selected.
- max_weighted_degree_per_value (INT_VAR_SIZE_AFC_MAX) the entry with
the largest domain size divided by weighted degree is selected.
- min_regret_lwb (INT_VAR_REGRET_MIN_MIN) the entry with the smallest difference between the
smallest and second smallest value in the domain is selected.
- max_regret (INT_VAR_REGRET_MIN_MAX) the entry with the largest difference between the
smallest and second smallest value in the domain is selected. This method is
typically used if the variable represents a cost, and we are interested in the
choice which could increase overall cost the most if the best possibility is
not taken. Unfortunately, the implementation sometimes does not always
work. If two decision variables incur the same minimal cost, the regret is not
calculated as zero, but as the difference from this minimal value to the next
greater value. Note this is an alias for max_regret_lwb
- max_regret_lwb (INT_VAR_REGRET_MIN_MAX) is an alias to max_regret.
- min_regret_upb (INT_VAR_REGRET_MAX_MIN) the entry with the smallest difference between the
largest and second largest value in the domain is selected.
- max_regret_upb (INT_VAR_REGRET_MAX_MAX) the entry with the largest difference between the
largest and second largest value in the domain is selected.
- most_constrained (INT_VAR_SIZE_MIN, INT_VAR_DEGREE_MAX) the entry with the smallest domain size is
selected. If several entries have the same domain size, the entry with the
largest number of attached constraints is selected. This is provided for
compatibility, as this define a tiebreak method (occurrence). Any tiebreak
method defined in options is ignored.
The pre-defined choice methods (with gecode name in brackets) have the following meaning:
- indomain (INT_VALUES_MIN)
Values are tried in increasing order.
On failure, the previously tested value is not removed.
- indomain_reverse_enum (INT_VALUES_MAX)
Values are tried in decreasing order.
On failure, the previously tested value is not removed.
- indomain_min (INT_VAL_MIN)
Values are tried in increasing order. On failure, the previously
tested value is removed. The values are tested in the same order as
for indomain, but backtracking may occur earlier.
- indomain_max (INT_VAL_MAX)
Values are tried in decreasing order. On failure, the previously
tested value is removed.
- indomain_median(INT_VAL_MED)
Values are tried beginning from the median value of the domain. On
failure, the previously tested value is removed, and the new median value will
be chosen next.
- indomain_split (INT_VAL_SPLIT_MIN)
Values are tried by successive domain splitting, trying the lower half
of the domain first. On failure, the tried interval is removed. This
enumerates values in the same order as indomain or indomain_min, but
may fail earlier.
- indomain_reverse_split (INT_VAL_SPLIT_MAX)
Values are tried by successive domain splitting, trying the upper half
of the domain first. On failure, the tried interval is removed. This
enumerates values in the same order as indomain or indomain_max, but
may fail earlier.
- indomain_random (INT_VAL_RND)
Values are tried in a random order. On backtracking, the previously
tried value is removed. Using this routine may lead to unreproducible
results, as another call will create random numbers in a different
sequence.
- indomain_interval (INT_VAL_RANGE_MIN)
If the domain consists of several intervals, we first branch on the choice of
the interval, choosing the smallest interval. For one interval, we use domain
splitting.
- indomain_interval_min (INT_VAL_RANGE_MIN)
Alias for indomain interval.
- indomain_interval_max (INT_VAL_RANGE_MAX)
If the domain consists of several intervals, we first branch on the choice of
the interval, choosing the largest interval. For one interval, we use reverse
domain splitting.
The different search methods are
- complete (DFS)
a complete search routine which explores all alternative choices.
- bb_min(Cost) (BAB)
Branch-and-bound search to find the minimal value for the cost variable Cost.
This should be a domain variable that is instantiated at the end of the
search. The search will return an optimal solution, unless terminated early,
in which case, the best solution found (if there is one) is returned. If Cost
variable is not instantiated at the end of the search, the search is aborted.
This provide some of the functionality of branch-and-bound search in
lib(branch_and_bound), but is less flexible (no user defined search) but is
likely to be faster.
- restart_min(Cost) (Restart)
Branch-and-bound search as in bb_min, but the search is restarted after finding
a new solution and imposing the new bound.
The option list is used to pass additional parameters to and from the
procedure. The currently recognized options are:
- tiebreak(+Selection)
Selection is one of the variable selection methods, and is used as a tie-break
if the primary selection method yields more than one candidate. Obviously not
all combinations of selection methods makes sense (e.g. it should not be the
same as the primary), but no check is done, they are simply passed to gecode.
- stats(+Stats)
Stats is a named gfd_stats structure, defined as:
:- export struct(gfd_stats(prop,fail,node,depth,mem)).
The fields of the structure should be uninstantiated, and the search predicate
will instantiate the fields with statistics obtained from gecode for the search:
prop for the number of propagations, fail for the number of failed nodes,
node for number of nodes expanded, depth for maximum depth of search stack,
mem for peak memory allocated (in bytes).
- timeout(+Seconds)
Specify the number of seconds that the search will be performed before it is
terminated. Seconds can be a real or integer number, and 0 means there is
no timeout. The timer is reset each time a new solution is obtained (for the
non-optimising search).
- limits(+Stats)
Specify limits to stop the search. Stats is the same gfd_stats struct used for
obtaining statistics. To specify a limit for a particular statistics, the
corresponding field should be instantiated to the limit. Only the prop, node,
fail and mem fields are significant. Entries in the other fields are ignored.
- control(+Control)
Control is a named gfd_control structure, defined as:
:- export struct(gfd_control(commit_distance,adaptive_distance,threads)).
This is used to pass information to gecode to control the search. The
corresponding field should be instantiated to the value passed to gecode.
threads may be of most interest as if threads is set to a value >= 2,
this will allow parallel search. See the gecode manual for more
details on the options.
- backtrack(-N)
Provided for compatibility with generic search/6. Returns the number of fail
nodes (fail field of statistics.
- nodes(++N)
Provided for compatibility with generic search/6. Equivalent to setting the
node field of limits. The node field will be unified with N
Modes and Determinism
- search(+, ++, ++, +, ++, +) is nondet
Fail Conditions
Fails if the search engine does not find any solution.
For partial search methods, this does not mean that the problem does not
have a solution.
Resatisfiable
yes (non-optimising searches)
Examples
top:-
length(L,8),
L :: 1..8,
search(L,0,input_order,indomain,complete,[]).
top:-
length(L,8),
L::1..8,
L = [Cost|L],
search(L,0,input_order,indomain_max,bb_min(Cost),[]).
See Also
indomain / 1, gfd_search : indomain / 2, labeling / 1, gfd_search : delete / 5, gfd_search : search / 6