
ldsb_initialise(+Xs, +Syms)

   Initialise LDSB search variables.

Arguments
   Xs                  Array of search variables
   Syms                List of symmetries

Type
   library(ldsb)

Description
  Initialise an array of search variables
to use LDSB with the given symmetries.  A variables must be
initialised with ldsb_initialise before it can be used with ldsb_try
or any predicate that relies on it such as ldsb_indomain.

 Each element of Syms must be a symmetry specifier from the
following set:



 variable_interchange(L).  This specifies that the variables in
the list L are interchangeable.

 value_interchange(L).  This specifies that the values in the list
L are interchangeable.

 parallel_variable_interchange(Ls).  This specifies that the lists
of variables in the list L are interchangeable.  Each list in Ls must
have the same length.  For example,
parallel_variable_interchange([A,B,C],[D,E,F],[G,H,I]) says that the
sequence A-B-C can be interchanged with the sequence D-E-F and the
sequence G-H-I.

 parallel_value_interchange(Ls).  This specifies that the lists of
values in the list L are interchangeable.  It is the same as
parallel_variable_interchange, but for values.

 variables_interchange.  This specifies that all variables in Xs
are interchangeable.

 values_interchange.  This specifies that all values in the
domains of the variables in Xs are interchangeable.  Note that for
this specifier it is assumed that all variables in Xs have the same
domain.

 rows_interchange.  This specifies that the rows of variables in
Xs are interchangeable.  Assumes that Xs is a 2D matrix of variables.

 columns_interchange.  This specifies that the columns of
variables in Xs are interchangeable.  Assumes that Xs is a 2D matrix
of variables.

 diagonal_reflection.  This specifies that the variables of Xs can
be reflected around the main diagonal.  Assumes that Xs is a 2D matrix
of variables.

 row_reflection.  This specifies that the rows of Xs can be
reflected around their centre.  Assumes that Xs is a 2D matrix of
variables.

 column_reflection.  This specifies that the columns of Xs can be
reflected around their centre.  Assumes that Xs is a 2D matrix of
variables.

 value_reflection(L, U).  This specifies that the values in the
sequence L..U can be reflected; i.e. value L+i maps to U-i.

 value_reflection.  This is the same as value_reflection(L,U),
where L and U are taken from the minimum and maximum values in the
domain of the first variable in Xs.

 

Modes and Determinism
   ldsb_initialise(+, +) is det

Resatisfiable
   no

Examples
   
% A vector of interchangeable variables.
dim(Xs, [N]),
[...]
ldsb_initialise(Xs, [variables_interchange])

% Vector of piecewise interchangeable variables.
Xs = [](A,B,C,D,E,F),
[...]
% A,B,C are interchangeable; D,E,F are interchangeable.
ldsb_initialise(Xs, [variable_interchange([A,B,C]),
                     variable_interchange([D,E,F])])

% Variables with interchangeable values.
dim(Xs, [N]),
Xs #:: 1..M,
ldsb_initialise(Xs, [values_interchange])

% N-queens, with one boolean variable per square.
dim(A, [N,N]),
A #:: 0..1,
[...]
ldsb_initialise(A, [row_reflection, column_reflection, diagonal_reflection])

% N-queens with one integer variable per queen.
% Note that only half of the symmetries are represented.
dim(Xs, [1,N]),    % make Xs a 1xN matrix.
Xs #:: 1..N,
[...]
ldsb_initialise(Xs, [column_reflection, value_reflection])

% Latin square of order N.
dim(Xs, [N,N]),
Xs #:: 1..N,
[...]
ldsb_initialise(Xs, [rows_interchange, columns_interchange, values_interchange, diagonal_reflection])

% Social Golfers problem with one set variable per group.
dim(Xs, [W,G]),
[...]
% Within each week, the groups are interchangeable.
( for(I, 1, W), foreach(Subsym, Subsyms), param(Xs,G) do
    subscript(Xs, [I, 1..G], Submatrix),
    variables_interchange(Submatrix, Subsym) ),
% rows_interchange: weeks are interchangeable
% values_interchange: golfers are interchangeable
ldsb_initialise(Xs, [rows_interchange, values_interchange | Subsyms])


See Also
   ldsb_try / 3, ldsb_indomain / 1, ldsb_indomain_set / 1
