Function cp::Cardinality(inspectedBinding, inspectedValues, lookupValueBinding, lookupValues, numberOfOccurrences, occurrenceLimit)

cp::Cardinality

The function cp::Cardinality can be used to restrict the number of occurrences of a particular value in (a slice of) an indexed identifier or expression. This function is typically used in constraints that enforce selected values a limited number of times. The function cp::Cardinality counts the number of occurrences of a collection of values and either ensures that the number of occurrences is within bounds, or sets this equal to the value of a variable.

Mathematical Formulation

The function cp::Cardinality(i,x_i,j,c_j,y_j[,u_j]) returns 1 if the number of occurrences where \(x_i\) equals \(c_j\) is equal to \(y_j\) or in the range {\(y_j\)..\(u_j\)}for all \(j\). cp::Cardinality(i,x_i,j,c_j,y_j) is equivalent to

\[\forall j: \sum_i (x_i=c_j) = y_j\]

and cp::Cardinality(i,x_i,j,c_j,l_j,u_j) is equivalent to

\[\forall j: l_j \leq \sum_i (x_i=c_j) \leq u_j\]

Function Prototype

cp::Cardinality(
        inspectedBinding,    ! (input) an index binding
        inspectedValues,     ! (input) an expression
        lookupValueBinding,  ! (input) an index binding
        lookupValues,        ! (input) an expression
        numberOfOccurrences, ! (input/output) an expression
        occurrenceLimit)     ! (optional/input) an expression

Arguments

inspectedBinding

An index binding that specifies and possibly limits the scope of indices. This argument follows the syntax of the index binding argument of iterative operators.

inspectedValues

An expression that may involve variables, but can only contain integer or element values (i.e. no strings, fractional or unit values). The result is a vector with an element for each possible value of the indices according to inspectedBinding.

lookupValueBinding

An index binding that specifies and possibly limits the scope of indices. This argument follows the syntax of the index binding argument of iterative operators.

lookupValues

An expression that does not involve variables. The result is a vector with an element for each possible value of the indices according to lookupValueBinding.

numberOfOccurrences

An expression that may involve variables. The result is a vector with an element for each possible value of the indices according to lookupValueBinding.

occurrenceLimit

An optional expression that does not involve variables. The result is a vector with an element for each possible value of the indices according to lookupValueBinding. In addition, if this argument is specified, the argument numberOfOccurrences is not allowed to contain variables either.

Return Value

This function returns 1 if the above condition is met. Also if the index binding argument lookupValueBinding is empty, this function will return 1.

Example

In car sequencing the next constraint ensures that the demand nbCarsPerClass( c ) for each class c of type car(i) is met. The value of element variable car is a class of car.

Constraint meetDemand {
    Definition   : {
        cp::Cardinality(
             inspectedBinding    :  i,
             inspectedValues     :  car(i),
             lookupValueBinding  :  c,
             lookupValues        :  c,
             numberOfOccurrences :  nbCarsPerClass( c ),
             occurrenceLimit     :  nbCars)
    }
}

See also