Combinatorial Constraints

The constraints listed here are sometimes called symbolic constraints. They are currently not reifiable. Unless documented otherwise, they maintain (at most) interval-consistency in their arguments; see The Constraint System.

count(+Val,+List,+RelOp,?Count)

where Val is an integer, List is a list of integers or domain variables, Count an integer or a domain variable, and RelOp is a relational symbol as in Arithmetic Constraints. True if N is the number of elements of List that are equal to Val and N RelOp Count. Thus, count/4 is a generalization of exactly/3 (not an exported constraint) which was used in an example earlier.

count/4 maintains domain-consistency, but in practice, the following constraint is a better alternative.

global_cardinality(+Xs,+Vals)

global_cardinality(+Xs,+Vals,+Options)

where Xs is a list of length d of integers or domain variables, and Vals is a list of length n of terms V-K, where the key V is a unique integer and K is a domain variable or an integer. True if every element of Xs is equal to some key and for each pair V-K, exactly K elements of Xs are equal to V.

If either Xs or Vals is ground, and in many other special cases, global_cardinality/[2,3] maintains domain-consistency, but generally, interval-consistency cannot be guaranteed. A domain-consistency algorithm [Regin 96] is used, roughly linear in the total size of the domains.

Options is a list of zero or more of the following:

cost(Cost,Matrix)

A cost is associated with the constraint and reflected into the domain variable Cost. Matrix should be an d*n matrix, represented as a list of m lists, each of length n. Assume that Xi equals the Pi:th key of Vals for each element Xi of Xs. The cost of the constraint is then Matrix[1,P1]+...+Matrix[m,Pm].

With this option, a domain-consistency algorithm [Regin 99] is used, the complexity of which is roughly O(d(m + n log n)) where m is the total size of the domains.

element(?X,+List,?Y)

where X and Y are integers or domain variables and List is a list of integers or domain variables. True if the X:th element of List is Y. Operationally, the domains of X and Y are constrained so that for every element in the domain of X, there is a compatible element in the domain of Y, and vice versa.

This constraint uses an optimized algorithm for the special case where List is ground.

element/3 maintains domain-consistency in X and interval-consistency in List and Y.

relation(?X,+MapList,?Y)

where X and Y are integers or domain variables and MapList is a list of integer-ConstantRange pairs, where the integer keys occur uniquely (see Syntax of Indexicals). True if MapList contains a pair X-R and Y is in the range denoted by R.

Operationally, the domains of X and Y are constrained so that for every element in the domain of X, there is a compatible element in the domain of Y, and vice versa.

If MapList is not ground, the constraint must be wrapped in call/1 to postpone goal expansion until runtime.

An arbitrary binary constraint can be defined with relation/3. relation/3 is implemented in terms of the following, more general constraint, with which arbitrary relations can be defined compactly:

case(+Template, +Tuples, +Dag)

case(+Template, +Tuples, +Dag, +Options)

Template is an arbitrary non-ground Prolog term. Its variables are merely place-holders; they should not occur outside the constraint nor inside Tuples.

Tuples is a list of terms of the same shape as Template. They should not share any variables with Template.

Dag is a list of nodes of the form node(ID,X,Successors), where X is a place-holder variable. The set of all X should equal the set of variables in Template. The first node in the list is the root node. Let rootID denote its ID.

Nodes are either internal nodes or leaf nodes. In the former case, Successors is a list of terms (Min..Max)-ID2, where the ID2 refers to a child node. In the latter case, Successors is a list of terms (Min..Max). In both cases, the Min..Max should form disjoint intervals.

ID is a unique, integer identifier of a node.

Each path from the root node to a leaf node corresponds to one set of tuples admitted by the relation expressed by the constraint. Each variable in Template should occur exactly once on each path, and there must not be any cycles.

Options is a list of zero or more of the following. It can be used to control the waking and pruning conditions of the constraint, as well as to identify the leaf nodes reached by the tuples:

leaves(TLeaf,Leaves)

TLeaf is a place-holder variable. Leaves is a list of variables of the same length as Tuples. This option effectively extends the relation by one argument, corresponding to the ID of the leaf node reached by a particular tuple.

on(Spec)

Specifies how eagerly the constraint should react to domain changes of X.

prune(Spec)

Specifies the extent to which the constraint should prune the domain of X.

Spec is one of the following, where X is a place-holder variable occurring in Template or equal to TLeaf:

dom(X)

wake up when the domain of X has changed, resp. perform full pruning on X. This is the default for all variables mentioned in the constraint.

min(X)

wake up when the lower bound of X has changed, resp. prune only the lower bound of X.

max(X)

wake up when the upper bound of X has changed, resp. prune only the upper bound of X.

minmax(X)

wake up when the lower or upper bound of X has changed, resp. prune only the bounds of X.

val(X)

wake up when X has become ground, resp. only prune X when its domain has been narrowed to a singleton.

none(X)

ignore domain changes of X, resp. never prune X.

The constraint holds if path(rootID,Tuple,Leaf) holds for each Tuple in Tuples and Leaf is the corresponding element of Leaves if given (otherwise, Leaf is a free variable).

path(ID,Tuple,Leaf) holds if Dag contains a term node(ID,Var,Successors), Var is the unique k:th element of Template, I is the k:th element of Tuple, and:

• The node is an internal node, and
  1. Successors contains a term (Min..Max)-Child,
  2. Min =< I =< Max, and
  3. path(Child,Tuple,Leaf) holds; or
• The node is a leaf node, and
  1. Successors contains a term (Min..Max),
  2. Min =< I =< Max, and Leaf = ID.

For example, recall that element(X,L,Y) wakes up when the domain of X or the lower or upper bound of Y has changed, performs full pruning of X, but only prunes the bounds of Y. The following two constraints:

          element(X, [1,1,1,1,2,2,2,2], Y),
          element(X, [10,10,20,20,10,10,30,30], Z)
          

can be replaced by the following single constraint, which is equivalent declaratively as well as wrt. pruning and waking. The fourth argument illustrates the leaf feature:

          elts(X, Y, Z, L) :-
              case(f(A,B,C), [f(X,Y,Z)],
                   [node(0, A,[(1..2)-1,(3..4)-2,(5..6)-3,(7..8)-4]),
                    node(1, B,[(1..1)-5]),
                    node(2, B,[(1..1)-6]),
                    node(3, B,[(2..2)-5]),
                    node(4, B,[(2..2)-7]),
                    node(5, C,[(10..10)]),
                    node(6, C,[(20..20)]),
                    node(7, C,[(30..30)])],
                   [on(dom(A)),on(minmax(B)),on(minmax(C)),
                    prune(dom(A)),prune(minmax(B)),prune(minmax(C)),
                    leaves(_,[L])]).
          

The DAG of the previous example has the following shape:

                           +-------<0: A>------+
                          /         / \         \
                         /         /   \         \
                    1..2/     3..4/     \5..6     \7..8
                       /         /       \         \
                      /         /         \         \
                    <1: B>    <2: B>    <3: B>    <4: B>
                      :         :         :         :
                  1..1:     1..1:         :2..2     :2..2
                      :         :         :         :
                      +       <6: C=20>   +       <7: C=30>
                       \                 /
                        \               /
                         \             /
                          +---<5: C=10>
          

A couple of sample queries:

          | ?- elts(X, Y, Z, L).
          L in 5..7,
          X in 1..8,
          Y in 1..2,
          Z in 10..30 ?
          
          | ?- elts(X, Y, Z, L), Z #>= 15.
          L in 6..7,
          X in(3..4)\/(7..8),
          Y in 1..2,
          Z in 20..30 ?
          
          | ?- elts(X, Y, Z, L), Y = 1.
          Y = 1,
          L in 5..6,
          X in 1..4,
          Z in 10..20 ?
          
          | ?- elts(X, Y, Z, L), L = 5.
          Z = 10,
          X in(1..2)\/(5..6),
          Y in 1..2 ?
          
          

all_different(+Variables)

all_different(+Variables, +Options)

all_distinct(+Variables)

all_distinct(+Variables, +Options)

where Variables is a list of domain variables with bounded domains or integers. Each variable is constrained to take a value that is unique among the variables. Declaratively, this is equivalent to an inequality constraint for each pair of variables.

Options is a list of zero or more of the following:

on(On)

How eagerly to wake up the constraint. One of:

dom

(the default for all_distinct/[1,2] and assignment/[2,3]), to wake up when the domain of a variable is changed;

min

to wake up when the lower bound of a domain is changed;

max

to wake up when the upper bound of a domain is changed;

minmax

to wake up when some bound of a domain is changed;

val

(the default for all_different/[1,2]), to wake up when a variable becomes ground.

consistency(Cons)

Which algorithm to use, one of:

global

The default for all_distinct/[1,2] and assignment/[2,3]. A domain-consistency algorithm [Regin 94] is used, roughly linear in the total size of the domains.

local

The default for all_different/[1,2]. An algorithm achieving exactly the same pruning as a set of pairwise inequality constraints is used, roughly linear in the number of variables.

bound

An interval-consistency algorithm [Mehlhorn 00] is used. This algorithm is nearly linear in the number of variables and values.

The following is a constraint over two lists of length n of variables. Each variable is constrained to take a value in 1,...,n that is unique for its list. Furthermore, the lists are dual in a sense described below.

assignment(+Xs, +Ys)

assignment(+Xs, +Ys, +Options)

where Xs and Ys are lists of domain variables or integers, both of length n. True if all Xi, Yi in 1,...,n and Xi=j iff Yj=i.

Options is a list of zero or more of the following, where Boolean must be true or false (false is the default):

on(On)

Same meaning as for all_different/2.

consistency(Cons)

Same meaning as for all_different/2.

circuit(Boolean)

If true, circuit(Xs,Ys) must hold for the constraint to be true.

cost(Cost,Matrix)

A cost is associated with the constraint and reflected into the domain variable Cost. Matrix should be an n*n matrix, represented as a list of lists. The cost of the constraint is Matrix[1,X1]+...+Matrix[n,Xn].

With this option, a domain-consistency algorithm [Sellmann 02] is used, the complexity of which is roughly O(n(m + n log n)) where m is the total size of the domains.

The following constraint can be thought of as constraining n nodes in a graph to form a Hamiltonian circuit. The nodes are numbered from 1 to n. The circuit starts in node 1, visits each node, and returns to the origin.

circuit(+Succ)

circuit(+Succ, +Pred)

where Succ is a list of length n of domain variables or integers. The i:th element of Succ (Pred) is the successor (predecessor) of i in the graph. True if the values form a Hamiltonian circuit.

The following constraint can be thought of as constraining n tasks, each with a start time Sj and a duration Dj, so that no tasks ever overlap. The tasks can be seen as competing for some exclusive resource.

serialized(+Starts,+Durations)

serialized(+Starts,+Durations,+Options)

where Starts = [S1,...,Sn] and Durations = [D1,...,Dn] are lists of domain variables with finite bounds or integers. Durations must be non-negative. True if Starts and Durations denote a set of non-overlapping tasks, i.e.:

          for all 1 =< i<j =< n:
            Si+Di =< Sj OR
            Sj+Dj =< Si OR
            Di = 0 OR
            Dj = 0
          

The serialized/[2,3] constraint is merely a special case of cumulative/[4,5] (see below).

Options is a list of zero or more of the following, where Boolean must be true or false (false is the default, except for the bounds_only option):

precedences(Ps)

Ps encodes a set of precedence constraints to apply to the tasks. Ps should be a list of terms of one of the forms:

• d(i,j,d), where i and j should be task numbers, and d should be a positive integer or sup, denoting:

                      Si+d =< Sj OR Sj =< Si, if d is an integer
                      Sj =< Si, if d is sup
                      

• i-j in r, where i and j should be task numbers, and r should be a ConstantRange (see Syntax of Indexicals), denoting:

                      Si-Sj #= Dij, Dij in r
                      

resource(R)

R is unified with a term which can be passed to order_resource/2 (see Enumeration Predicates) in order to find a consistent ordering of the tasks.

path_consistency(Boolean)

if true, a redundant path consistency algorithm will be used inside the constraint in an attempt to improve the pruning.

static_sets(Boolean)

if true, a redundant algorithm will be used which reasons about the set of tasks that must precede (be preceded by) a given task, in an attempt to tighten the lower (upper) bound of a given start variable.

edge_finder(Boolean)

if true, a redundant algorithm will be used which attempts to identify tasks that necessarily precede or are preceded by some set of tasks.

decomposition(Boolean)

if true, an attempt is made to decompose the constraint each time it is resumed.

bounds_only(Boolean)

if true, the constraints will only prune the bounds of the Si variables, and not inside the domains.

Whether it's worthwhile to switch on any of the latter five options is highly problem dependent.

serialized/3 can model a set of tasks to be serialized with sequence-dependent setup times. For example, the following constraint models three tasks, all with duration 5, where task 1 must precede task 2 and task 3 must either complete before task 2 or start at least 10 time units after task 2 started:

          ?- domain([S1,S2,S3], 0, 20),
             serialized([S1,S2,S3], [5,5,5], [precedences([d(2,1,sup),d(2,3,10)])]).
          S1 in 0..15,
          S2 in 5..20,
          S3 in 0..20 ?
          

The bounds of S1 and S2 changed because of the precedence constraint. Setting S2 to 5 will propagate S1=0 and S3 in 15..20.

The following constraint can be thought of as constraining n tasks to be placed in time and on m machines. Each machine has a resource limit, which is interpreted on a lower or upper bound on the total amount of resource used on that machine at any point in time that intersects with some task.

A task is represented by a term task(O,D,E,H,M) where O is the start time, D the duration, E the end time, H the resource consumption, and M a machine identifier.

A machine is represented by a term machine(M,L) where M is the identifier and L is the resource limit of the machine.

All fields are domain variables with bounded domains, or integers. L must be an integer. D must be non-negative, but H may be either positive or negative. A negative resource consumption is interpreted as a resource demand.

cumulatives(+Tasks,+Machines)

cumulatives(+Tasks,+Machines,+Options)

Options is a list of zero or more of the following, where Boolean must be true or false (false is the default):

bound(B)

If lower (the default), each resource limit is treated as a lower bound. If upper, each resource limit is treated as an upper bound.

prune(P)

If all (the default), the constraint will try to prune as many variables as possible. If next, only variables that occur in the first non-ground task term (wrt. the order given when the constraint was posted) can be pruned.

generalization(Boolean)

If true, extra reasoning based on assumptions on machine assignment will be done to infer more.

task_intervals(Boolean)

If true, extra global reasoning will be performed in an attempt to infer more.

The following constraint can be thought of as constraining n tasks, each with a start time Sj, a duration Dj, and a resource amount Rj, so that the total resource consumption does not exceed Limit at any time:

cumulative(+Starts,+Durations,+Resources,?Limit)

cumulative(+Starts,+Durations,+Resources,?Limit,+Options)

where Starts = [S1,...,Sn], Durations = [D1,...,Dn], Resource = [R1,...,Rn] are lists of domain variables with finite bounds or integers, and Limit is a domain variable with finite bounds or an integer. Durations, Resources and Limit must be non-negative. Let:

          a = min(S1,...,Sn),
          b = max(S1+D1,...,Sn+Dn)
          Rij = Rj, if Sj =< i < Sj+Dj
          Rij = 0 otherwise
          

The constraint holds if:

          Ri1+...+Rin =< Limit, for all a =< i < b
          

If given, Options should be of the same form as in serialized/3, except the resource(R) option is not useful in cumulative/5.

The cumulative/4 constraint is due to Aggoun and Beldiceanu [Aggoun & Beldiceanu 93].

The following constraint captures the relation between a list of values, a list of the values in ascending order, and their positions in the original list:

sorting(+Xs,+Is,+Ys)

where the arguments are lists of equal length N of domain variables or integers. The elements of Is are in 1..N. The constraint holds if the following are true:

• Ys is in ascending order.
• Is is a permutation of 1..N.
• For i in 1..N, Xs[i] equals Ys[Is[i]].

In practice, the underlying algorithm [Mehlhorn 00] is likely to achieve interval-consistency, and is guaranteed to do so if Is is ground or completely free.

The following constraints model a set or lines or rectangles, respectively, so that no pair of objects overlap:

disjoint1(+Lines)

disjoint1(+Lines,+Options)

where Lines is a list of terms F(Sj,Dj) or F(Sj,Dj,Tj), Sj and Dj are domain variables with finite bounds or integers denoting the origin and length of line j respectively, F is any functor, and the optional Tj is an atomic term denoting the type of the line. Tj defaults to 0 (zero).

Options is a list of zero or more of the following, where Boolean must be true or false (false is the default):

decomposition(Boolean)

if true, an attempt is made to decompose the constraint each time it is resumed.

global(Boolean)

if true, a redundant algorithm using global reasoning is used to achieve more complete pruning.

wrap(Min,Max)

If used, the space in which the lines are placed should be thought of as a circle where positions Min and Max coincide, where Min and Max should be integers. That is, the space wraps around. Furthermore, this option forces the domains of the origin variables to be inside Min..(Max-1).

margin(T1,T2,D)

This option imposes a minimal distance D between the end point of any line of type T1 and the origin of any line of type T2. D should be a positive integer or sup. If sup is used, all lines of type T2 must be placed before any line of type T1.

This option interacts with the wrap/2 option in the sense that distances are counted with possible wrap-around, and the distance between any end point and origin is always finite.

The file library('clpfd/examples/bridge.pl') contains an example where disjoint1/2 is used for scheduling non-overlapping tasks.

disjoint2(+Rectangles)

disjoint2(+Rectangles,+Options)

where Rectangles is a list of terms F(Sj1,Dj1,Sj2,Dj2) or F(Sj1,Dj1,Sj2,Dj2,Tj), Sj1 and Dj1 are domain variables with finite bounds or integers denoting the origin and size of rectangle j in the X dimension, Sj2 and Dj2 are the values for the Y dimension, F is any functor, and the optional Tj is an atomic term denoting the type of the rectangle. Tj defaults to 0 (zero).

Options is a list of zero or more of the following, where Boolean must be true or false (false is the default):

decomposition(Boolean)

If true, an attempt is made to decompose the constraint each time it is resumed.

global(Boolean)

If true, a redundant algorithm using global reasoning is used to achieve more complete pruning.

wrap(Min1,Max1,Min2,Max2)

Min1 and Max1 should be either integers or the atoms inf and sup respectively. If they are integers, the space in which the rectangles are placed should be thought of as a cylinder which wraps around the X dimension where positions Min1 and Max1 coincide. Furthermore, this option forces the domains of the Sj1 variables to be inside Min1..(Max1-1).

Min2 and Max2 should be either integers or the atoms inf and sup respectively. If they are integers, the space in which the rectangles are placed should be thought of as a cylinder which wraps around the Y dimension where positions Min2 and Max2 coincide. Furthermore, this option forces the domains of the Sj2 variables to be inside Min2..(Max2-1).

If all four are integers, the space is a toroid which wraps around both dimensions.

margin(T1,T2,D1,D2)

This option imposes minimal distances D1 in the X dimension and D2 in the Y dimension between the end point of any rectangle of type T1 and the origin of any rectangle of type T2. D1 and D2 should be positive integers or sup. If sup is used, all rectangles of type T2 must be placed before any rectangle of type T1 in the relevant dimension.

This option interacts with the wrap/4 option in the sense that distances are counted with possible wrap-around, and the distance between any end point and origin is always finite.

The file library('clpfd/examples/squares.pl') contains an example where disjoint2/2 is used for tiling squares.

synchronization(Boolean)

Let the assignment dimension and the temporal dimension denote the two dimensions, no matter which is the X and which is the Y dimension. If Boolean is true, a redundant algorithm is used to achieve more complete pruning for the following case:

• All rectangles have size 1 in the assignment dimension.
• Some rectangles have the same origin and size in the temporal dimension, and that origin is not yet fixed.

The following example shows an artificial placement problem involving 25 rectangles including four groups of rectangles whose left and right borders must be aligned. If Synch is true, it can be solved with first-fail labeling in 23 backtracks. If Synch is false, 60 million backtracks do not suffice to solve it.

          ex([O1,Y1a,Y1b,Y1c,
              O2,Y2a,Y2b,Y2c,Y2d,
              O3,Y3a,Y3b,Y3c,Y3d,
              O4,Y4a,Y4b,Y4c],
             Synch) :-
                  domain([Y1a,Y1b,Y1c,
                          Y2a,Y2b,Y2c,Y2d,
                          Y3a,Y3b,Y3c,Y3d,
                          Y4a,Y4b,Y4c], 1, 5),
                  O1 in 1..28,
                  O2 in 1..26,
                  O3 in 1..22,
                  O4 in 1..25,
                  disjoint2([t(1,1,5,1),    t(20,4,5,1),
                             t(1,1,4,1),    t(14,4,4,1),
                             t(1,2,3,1),    t(24,2,3,1),
                             t(1,2,2,1),    t(21,1,2,1),
                             t(1,3,1,1),    t(14,2,1,1),
                             t(O1,3,Y1a,1),
                             t(O1,3,Y1b,1),
                             t(O1,3,Y1c,1),
                             t(O2,5,Y2a,1),
                             t(O2,5,Y2b,1),
                             t(O2,5,Y2c,1),
                             t(O2,5,Y2d,1),
                             t(O3,9,Y3a,1),
                             t(O3,9,Y3b,1),
                             t(O3,9,Y3c,1),
                             t(O3,9,Y3d,1),
                             t(O4,6,Y4a,1),
                             t(O4,6,Y4b,1),
                             t(O4,6,Y4c,1)],
                            [synchronization(Synch)]).
          

The following constraints express the fact that several vectors of domain variables are in ascending lexicographic order:

lex_chain(+Vectors)

lex_chain(+Vectors,+Options)

where Vectors is a list of vectors (lists) of domain variables with finite bounds or integers. The constraint holds if Vectors are in ascending lexicographic order.

Options is a list of zero or more of the following:

op(Op)

If Op is the atom #=< (the default), the constraints holds if Vectors are in non-descending lexicographic order. If Op is the atom #<, the constraints holds if Vectors are in strictly ascending lexicographic order.

among(Least,Most,Values)

If given, Least and Most should be integers such that 0 =< Least =< Most =< N and Values should be a list of N distinct integers. This option imposes the additional constraint on each vector in Vectors that at least Least and at most Most elements should belong to Values.

In the absence of an among/3 option, the underlying algorithm [Carlsson & Beldiceanu 02] guarantees domain-consistency.