You use the function IlcCard to control the size of a set of constraints during a Solver search. For similar functionality in a model, consider IloCard documented in the IBM ILOG Concert API.

This function creates and returns a constrained integer expression. At all times, that expression is greater than or equal to the number of integer values j such that the constraint ct is true for j. That expression is also less than or equal to the number of integer values j such that the constraint ct is not false for j.

The generic constraint ct must have been created with generic variables stemming from the index i (an argument passed to IlcCard); otherwise, Solver will throw an exception (an instance of IloSolver::SolverErrorException).

All generic variables of the constraint ct must represent arrays of constrained expressions of the same size; otherwise, Solver will throw an exception (an instance of IloSolver::SolverErrorException).

To count the number of occurrences of several values, use the function IlcDistribute.

Generic Constraints

A generic constraint is a constraint shared by an array of variables. For example, IlcAllDiff is a generic constraint that insures that all the elements of a given array are different from one another. Solver provides generic constraints to save memory since, if you use them, you can avoid allocating one object per variable.

You create a generic constraint simply by stating the constraint over generic variables. Each generic variable stands for all the elements of an array of constrained variables.

In that sense, generic variables are only syntactic objects provided by Solver to support generic constraints, and they can be used only for creating generic constraints. To create a generic variable, you use the operator []. The argument passed to that operator is known as the index for that generic variable; we say that the generic variable stems from that index.

Implementation

This function can be implemented like this:

 IlcIntExp IlcCard(IlcIndex& i, IlcConstraint ct) {
     return IlcCard(IlcSetOf(i, ct));
 }

Example

Here's how to count the number of expressions in two arrays of constrained integer variables x and y such that x[I] == y[I] + 2:

 IlcIndex I(s);
 IlcIntVar number = IlcCard(I, x[I] == y[I] + 2);

A very common use of generic constraints is to put limits on the number of times that a value can appear in a given array of variables. For example, we could use the class IlcIndex and the function IlcCard to define a function IlcCount like this:

 IlcConstraint IlcCount(IloSolver s,
                        IlcIntVar card,
                        IlcInt val,
                        IlcIntVarArray vars){
     IlcIndex i(s);
     return card == IlcCard(i, vars[i] == val);
 }

If that constraint is posted, then it constrains card to be equal to the number of occurrences of val in the arrays vars. At any given moment, the minimum of card is at least equal to the number of variables contained in vars bound to the value val; and the maximum of card is at most equal to the number of variables contained in vars that contain val in their domain.

A constrained set variable contains a constrained integer variable (called the cardinality variable) that represents the cardinality of the value of the constrained set variable. You can constrain that cardinality and thus control the size of a constrained set variable.

This function returns a constrained integer variable which is constrained to be equal to the cardinality of the domain of the invoking constrained set variable. Every call to IlcCard returns the same constrained integer variable for use during a Solver search. For similar functionality in a model, consider IloCard documented in the Concert API.

The size of the required set of the constrained set variable is less than or equal to the minimum of the domain of the constrained integer variable. The maximum of the domain of the constrained integer variable is less than or equal to the size of the possible set. More formally,

 cardinal(required) <= min(var) <= max(var) <= cardinal(possible)
 

Examples:

Here's what we write in order to constrain the value of a given constrained set variable of pointers, setVar, to contain at least four elements:

 s.add(IlcCard(setVar) >= 4); // setVar defined before
 

Here's what we write in order to constrain the value of a given constrained set variable of integers, setVar, to contain at least four elements:

 s.add(IlcCard(setVar) >= 4); // setVar defined before