
select_var(-X, +Vars, +Handle, +Arg, ?Select)

   Pick a domain variable from a collection according to selection criterion.

Arguments
   X                    a free variable
   Vars                 a collection of existing domain variables or terms, or a handle 
   Handle              free variable, will be bound to handle for remaining collection
   Arg                  an integer
   Select              a predefined selection method.

Type
   library(gfd)

Description

This predicate picks one domain variable in Vars based on some selection 
criterion. The selected entry is returned in X. Vars is either a 
collection of domain variables/terms containing domain variables, or 
a handle representing domain variables returned in Handle from a
previous call to select_var/5. 

This predicate provides similar functionality as delete/5 of gfd_search,
and is designed to be used in a similar way -- the selection is done on
the variables represented in Vars, while Handle is then passed as the
next Vars argument for variable selection in the next call to select_var/5,
as is done with Rest for delete/5. select_var/5 can thus be used as a 
replacement for delete/5 in gfd_search:search/6.

The main difference with delete/5 is that Handle is a low-level
representation of all the domain variables in Vars, rather than the
rest of the domain variables with the selected variable removed as in Rest
for delete/5. This allows select_var/5 to be used for both the 'indomain'
style labelling (where a selected variable is labelled to different values on 
backtracking), or the more Gecode-like labelling (where variable
selection and a binary value choice is performed for each labelling step).
Unlike delete/5, a domain variable that is instantiated will not be selected,
and the search is complete when select_var/5 fails because all the 
domain variables in Vars are instantiated. 

When select_var/5 is called with Vars being a collection, the domain variables
in the collection are extracted according to Arg in the same way as
delete/5, i.e. the Arg'th argument of each element in the collection is the
domain variable for that element. In addition to creating the low-level
 handle representation of the domain variables in Handle, additional
initialisation is done for some selection methods that have initialisation
parameters (i.e. those involving weighted degree or activity). When 
select_var/5 is called with Vars being a handle created from a previous 
call to select_var/5, then Args and any initialisation parameters given 
with Select are ignored. 

Select is one of the following predefined selection methods:
input_order, occurrence, anti_occurrence, 
smallest, largest, smallest_upb, largest_lwb,
first_fail, anti_first_fail, 
most_constrained,  most_constrained_per_value, least_constrained_per_value, 
max_regret, max_regret_lwb, min_regret_lwb, max_regret_upb.
max_weighted_degree, min_weighted_degree,
max_weighted_degree_per_value, min_weighted_degree_per_value,
max_activity, min_activity,
max_activity_per_value, min_activity_per_value

These are essentially the same selection methods supported for using
Gecode's search engine (search/6), except for random, which is not
supported here. For methods that uses activity or weighted degree,
Select can include an optional argument in the form of a list, where each 
list item is a parameter setting. If a parameter is not specified in the
list, the default setting for the parameter will be used.
These parameters are:

For weighted degree:

decay(Decay) specify the decay factor (number between
 0 and 1, where 1 is no decay). Default is the existing decay factor 
for weighted degree (normally 1, unless explicitly changed).

init(Init) set the start values for activity for the
search variables according to Init. Init can be:

 degree(+Factor) set the start value to 
Factor*degree for the variable. Factor is a non-negative number.

 vals(Pos,Starts) set the start values to those specified in
Starts. Starts is a collection of either the start values (Pos=0), or 
compound terms containing the value, in the Pos'th argument. The number
of start values is the same as the number of variable, and each value
is a non-negative number. Starts can be the same collection as Vars,
with each item in the collection storing both a variable and its
activity start value.

 none no initialisation (default)




For activity:

decay(Decay) specify the decay factor (number between
 0 and 1, where 1 is no decay). Default is 1.

init(Init) set the initial values for activity according
 to Init. Init can be:

 degree
 vals(Starts) set the initial values to those specified in
 Starts.Starts is a collection of non-negative numbers, and is the
 same size as Vars, i.e. each item in Starts represents the initial
 activity value of the corresponding search variable in Vars.
 corresponding variable in Vars.

 none no initialisation (default)





Due to the way gfd implement activity, there are some limitations to
the way activity can be used. Gecode requires activity to be declared
for a fixed set of variables -- and activity information for these variables
will then be collected subsequently. In gfd this is done during the
 initialisation call to select_var/5. Thus, to use selection methods
 that involve activity, it must be used in the initialisation call. In
addition, gfd supports only one activity declaration per Gecode solver
 state, so activity can only be used as a selection method for one set
 of variable in each branch of the search.  
 


Modes and Determinism
   select_var(-, +, +, +, ?) is semidet

Fail Conditions
   fails if no variable can be selected

Examples
   
% Simple labelling implemented using select_var/5 and indomain/2
labelling1(Vars, Select, Choice) :-
        (select_var(V, Vars, Rest, 0, Select) ->
            indomain(V, Choice),
            labelling1(Rest, Select, Choice)
        ;
            true
        ).

% Variant using select_var/5 and try_value/2
labelling2(Vars, Select, Choice) :-
        (select_var(V, Vars, Rest, 0, Select) ->
            try_value(V, Choice),
            labelling2(Rest, Select, Choice)
        ;
            true
        ).



        % A call with max_activity with parameters
        select_var(V, Vars, Rest, 0, 
                   max_activity([init(degree),
                                 decay(0.9)
                                ])),



See Also
   try_value / 2, gfd_search : indomain / 2, search / 6, gfd_search : search / 6
