A filter takes as input an array of variables. It evaluates them once and selects a subset. The most basic filter contains an evaluator (see the concept Selectors in the IBM ILOG Solver Reference Manual). It evaluates each variable and selects the variables that have the smallest evaluation.

For example, if we consider the evaluator that returns the domain size:

ILOEVALUATOR0(SizeEvaluator, IlcIntVar, x) {
  return x.getSize(); 
}

we can build a basic filter with it and add it to an instance g of IloCustomizableGoal with the call:

g.addFilter(SizeEvaluator(env));

It will filter variables and keep only the one that has the smallest domain. Ties can be broken by adding another filter that will select variables from those remaining after filtering with SizeEvaluator. If there are still ties and no filter to break them, then the variable selected is the one having the smallest index in the array vars.

Other ways of selecting variables are available. A filter added with the following member function selects at least number variables among the best ones:

void IloCustomizableGoal::addMinNumberFilter(IloEvaluator<IlcIntVar> e,
                                             IlcFloat number);

The following member function selects a number of variables that is proportional to the size of the input. The value proportion must be strictly greater than zero and less than or equal to 1:

void IloCustomizableGoal::addMinProportionFilter(IloEvaluator<IlcIntVar> e,
                                                 IlcFloat proportion);

The following function selects variables that are at a distance of at most tol from the best evaluation:

void IloCustomizableGoal::addAbsoluteToleranceFilter(IloEvaluator<IlcIntVar> e,
                                                     IlcFloat tol);

The following function does the same but the tolerance is relative:

void IloCustomizableGoal::addRelativeToleranceFilter(IloEvaluator<IlcIntVar> e,
                                                     IlcFloat tol);

To illustrate the effects of different filters assume a filter with an input of 10 variables whose evaluations are:

The smallest evaluation is 1.0. A basic filter will select two variables: x2 and x6 because they have the same --best--evaluation. A filter with an absolute tolerance of 0.1 will select all variables having an evaluation between 1.0 (the best one) and 1.1. namely x1, x2, x3, x5, and x6. A filter with a relative tolerance of 0.2 will select six variables: x1, x2, x3, x4, x5, and x6. A filter with a minimum number of three will select x1, x2, x3, x5, and x6. Note that in this case we had to keep five variables because there are only two variables with the best evaluation and x1, x3, and x5 have the second best evaluation.

There are a certain number of already defined functions returning evaluators, among them the following, which return, respectively, the impact, the local impact, and the domain size of a variable:

IloEvaluator<IlcIntVar> IlcImpactVarEvaluator(IloEnv env); 
IloEvaluator<IlcIntVar> IlcImpactVarEvaluator(IloSolver solver);
IloEvaluator<IlcIntVar> IlcLocalImpactVarEvaluator(IloEnv env, IloInt depth); 
IloEvaluator<IlcIntVar> IlcLocalImpactVarEvaluator(IloSolver solver, 
                                                   IloInt depth); 
IloEvaluator<IlcIntVar> IlcSizeVarEvaluator(IloEnv env); 
IloEvaluator<IlcIntVar> IlcSizeVarEvaluator(IloSolver solver); 

There is also the following function, which returns a number between 0 and 1. This evaluator is used to build a filter that chooses randomly to break remaining ties.:

IloEvaluator<IlcIntVar> IlcRandomVarEvaluator(IloEnv env); 
IloEvaluator<IlcIntVar> IlcRandomVarEvaluator(IloSolver solver);