[ library(ldsb) | Reference Manual | Alphabetic Index ]

# ldsb_initialise(+Xs, +Syms)

Initialise LDSB search variables.

Xs
  Array of search variables
Syms
  List of symmetries

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