ILOBLACKBOX0

A black-box expression is a numerical expression for which the closed form is not known or cannot be formulated using CP Optimizer's classical expressions. A black-box expression is specified by providing a C++ code that evaluates the expression at given points. This function is called by the engine during the resolution.

This macro defines a black-box expression named bbfunc with n arguments. When n is greater than zero, the types and names of the black-box function arguments must be supplied as arguments to the macro. Each argument is defined by its type bbtypen and a name bbvarn.

Here is an example of a black-box expression f:

IloNum PI = 3.14159265358979323846;

ILOBLACKBOX2(f, IloNumExpr, x, IloNumExpr, y) {
  // f(x,y) = cos(4.pi.x) + cos(4.pi.y) + 5(x+y) + 2
  IloNum vx = getValue(x);
  IloNum vy = getValue(y);
  IloNum v = cos(4*PI*vx) + cos(4*PI*vy) + 5*(vx+vy) + 2;
  returnValue(v);
}

An instance of this black-box expression can be created in the model with the following signature, and used as an IloNumExpr:

IloBlackbox f(IloEnv env, IloNumExpr x, IloNumExpr y);

For example, here is a small complete model using the above black-box expression:

IloEnv env;
IloModel model(env);
IloIntVar x(env, 0, 100, "x");
IloIntVar y(env, 0, 100, "y");
model.add(x <= y); // Symmetry breaking as f(x,y)=f(y,x)
IloNumExpr obj = f(env, x/100.0, y/100.0);
model.add(5*(x+y) <= 100*(1+obj)); // Lower-bounding expression
model.add(IloMinimize(env, obj));
IloCP cp(model);
cp.solve();
env.end();

Once defined with the macro ILOBLACKBOX, a black-box expression can be used in the same way as classical numerical expressions in the model. In particular, it can be mixed with other expressions (classical or black-box expressions), used as part of the objective function, used in constraints, used in the scope of other black-box expressions, and used as a KPI or part of a KPI.

The following functions are available inside the evaluation code to access the current values of variables/expressions in the scope of the black-box:

IloInt  getValue  (IloIntVar x)      const;
IloInt  getValue  (IloIntExpr x)     const;
IloNum  getValue  (IloNumExpr x)     const;
IloBool isPresent (IloIntervalVar x) const;
IloBool isAbsent  (IloIntervalVar x) const;
IloInt  getStart  (IloIntervalVar x) const;
IloInt  getEnd    (IloIntervalVar x) const;
IloInt  getSize   (IloIntervalVar x) const;
IloIntervalVar getFirst(IloIntervalSequenceVar s) const;
IloIntervalVar getLast (IloIntervalSequenceVar s) const;
IloIntervalVar getNext (IloIntervalSequenceVar s, IloIntervalVar x) const;
IloIntervalVar getPrev (IloIntervalSequenceVar s, IloIntervalVar x) const;

Black-box expressions can return a single value or multiple values through the following functions:

void returnValue(IloNum val); // Return value of a single value function
void returnValue(IloInt i, IloNum val); // Return ith element of a multiple value function

When the black-box expression returns a vector of values, each component of the vector can be accessed with the operator[] on IloBlackbox:

IloNumExpr IloBlackbox::operator[](IloInt i);

In the simpler case of a single value, the class IloBlackbox can directly be used as an IloNumExpr.

Macro ILOBLACKBOX0