Goals can be used to control the branch & cut search in IloCplex. Goals are implemented in subclasses of the class IloCplex::GoalI. This is the base class for user-written implementation classes of CPLEX goals.

To implement your own goal you need to create a subclass of IloCplex::GoalI and implement its pure virtual methods execute and duplicateGoal. You may use one of the ILOCPLEXGOAL0 macros to assist you in doing so. After implementing your goal class, you use it by passing it to the solve method when solving the model.

The method duplicateGoal may be called by IloCplex to create copies of a goal when needed for parallel branch & cut search. Thus the implementation of this method must create and return an exact copy of the invoked object itself.

The method execute controls the branch & cut search of IloCplex by the goal it returns. When IloCplex processes a node, it pops the top goal from the node's goal stack and calls method execute of that goal. It continues executing the top goal from the stack until the node is deactivated or the goal stack is empty. If the goal stack is empty, IloCplex proceeds with the built-in search strategy for the subtree rooted at the current node.

The class IloCplex::GoalI provides several methods for querying information about the current node. The method execute controls how to proceed with the branch & cut search via the goal it returns. The returned goal, unless it is the 0 goal, is pushed on the goal stack and will thus be executed next.

See also the chapter about goals in the ILOG CPLEX User's Manual.

The goal constructor. It requires an instance of the same IloEnv as the IloCplex object with which to use the goal. The environment can later be queried by calling method getEnv.

The static methods AndGoal all return a goal that pushes the goals passed as parameters onto the goal stack in reverse order. As a consequence, the goals will be executed in the order they are passed as parameters to the AndGoal function.

This static function returns a goal that creates the same branches as the currently selected built-in branch strategy of IloCplex would choose at the current node. This goal allows you to proceed with the IloCplex search strategy, but keeps the search under goal control, thereby giving you the option to intervene at any point.

This goal is also important when you use node evaluators while you use a built-in branching strategy.

For example, consider the execute method of a goal starting like this:

  if (!isIntegerFeasible())
      return AndGoal(BranchAsCplexGoal(getEnv()), this);

  // do something

 

It would do something only when IloCplex found a solution it considers to be a candidate for a new incumbent. Note the test of integer feasibility before returning the BranchAsCplexGoal. Without it, BranchAsCplex would be executed for a solution IloCplex considers to be feasible, but IloCplex would not know how to branch on it. An endless loop would result.

This static method creates a goal that fails. That means that the branch where the goal is executed will be pruned or, equivalently, the search is discontinued at that node and the node is discarded.

This method creates a goal that when executed adds the constraints (provided in the paramter array con) as global cuts to the model. These global cuts must be valid for the entire model, not only for the current subtree. In other words, these global cuts will be respected at every node.

IloCplex takes over memory managment for the cuts passed to the method GlobalCutGoal. Thus IloCplex will call the method end as soon as it can be discarded after the goal executes. Calling end yourself or the constraints in the array con passed to method GlobalCutGoal or the array itself is an error and must be avoided.

This method creates a goal that when executed adds the constraint con (provided as a parameter) as global cuts to the model. These global cuts must be valid for the entire model, not only for the current subtree. In other words, these global cuts will be respected at every node.

IloCplex takes over memory managment for the cut passed to the method GlobalCutGoal. Thus IloCplex will call the method end as soon as it can be discarded after the goal executes. Calling end yourself for the constraint passed to method GlobalCutGoal is an error and must be avoided.

The static methods OrGoal all return a goal that creates as many branches (or, equivalently, subproblems) as there are parameters. Each of the subnodes will be initialized with the remaining goal stack of the current node. In addition, the goal parameter will be pushed on the goal stack of the corresponding subgoal. If more than six branches need to be created, instances of OrGoal can be combined.

This static method creates and returns a goal that attempts to inject a solution specified by setting the variables listed in array vars to the corresponding values listed in the array vals.

IloCplex will not blindly accept such a solution as a new incumbent. Instead, it will make sure that this solution is compatible with both the model and the goals. When checking feasibility with goals, it checks feasibility with both the goals that have already been executed and the goals that are still on the goal stack. Thus, in particular, IloCplex will reject any solution that is not compatible with the branching that has been done so far.

IloCplex takes over memory managment for arrays vars and vals passed to SolutionGoal. Thus IloCplex will call method end for these arrays as soon as they can be discarded. Calling end for the arrays passed to SolutionGoal is an error and must be avoided.

This static method creates and returns a goal that attempts to inject a solution specified by setting the variables listed in array vars to the corresponding values listed in the array vals.

IloCplex will not blindly accept such a solution as a new incumbent. Instead, it will make sure that this solution is compatible with both the model and the goals. When checking feasibility with goals, it checks feasibility with both the goals that have already been executed and the goals that are still on the goal stack. Thus, in particular, IloCplex will reject any solution that is not compatible with the branching that has been done so far.

IloCplex takes over memory managment for arrays vars and vals passed to SolutionGoal. Thus IloCplex will call method end for these arrays as soon as they can be discarded. Calling end for the arrays passed to SolutionGoal is an error and must be avoided.

Abort the optimization, that is, the execution of method IloCplex::solve currently in process.

This virtual method must be implemented by the user. It must return a copy of the invoking goal object. This method may be called by IloCplex when doing parallel branch & cut search.

This virtual method must be implemented by the user to specify the logic of the goal. The instance of IloCplex::Goal returned by this method will be added to the goal stack of the node where the invoking goal is being executed for further execution.

This method returns the currently best known bound on the optimal solution value of the problem at the time the invoking goal is executed by an instance of IloCplex while solving a MIP. When a model has been solved to optimality, this value matches the optimal solution value. Otherwise, this value is computed for a minimization (maximization) problem as the minimum (maximum) objective function value of all remaining unexplored nodes.

This method accesses branching information for the i-th branch that the invoking instance of IloCplex is about to create. The parameter i must be between 0 (zero) and getNbranches - 1; that is, it must be a valid index of a branch; normally, it will be zero or one.

A branch is normally defined by a set of variables and the bounds for these variables. Branches that are more complex cannot be queried. The return value is the node estimate for that branch.

• The parameter vars contains the variables for which new bounds will be set in the i-th branch.
• The parameter bounds contains the new bounds for the variables listed in vars; that is, bounds[j] is the new bound for vars[j].
• The parameter dirs indicates the branching direction for the variables in vars.

dir[j] == IloCplex::BranchUp

means that bounds[j] specifies a lower bound for vars[j].

dirs[j] == IloCplex::BranchDown

means that bounds[j] specifies an upper bound for vars[j].

This method returns the type of branching IloCplex is going to do for the current node.

The method returns the current cutoff value. An instance of IloCplex uses the cutoff value (the value of the objective function of the subproblem at a node in the search tree) to decide when to prune nodes from the search tree (that is, when to cut off that node and discard the nodes beyond it). The cutoff value is updated whenever a new incumbent is found.

Returns the solution value of var in the incumbent solution at the time the invoking goal is executed by an instance of IloCplex while solving a MIP. If there is no incumbent, this method throws an exception.

Returns the solution value of var in the incumbent solution at the time the invoking goal is executed by an instance of IloCplex while solving a MIP. If there is no incumbent, this method throws an exception.

This method returns the current pseudo cost for branching downward on the variable var.

This method returns the current pseudo cost for branching downward on the variable var.

Returns the instance of IloEnv passed to the constructor of the goal.

This method considers whether each of the variables in the array vars is integer feasible, integer infeasible, or implied integer feasible and puts the indication in the corresponding element of the array stats.

This method considers whether each of the variables in the array vars is integer feasible, integer infeasible, or implied integer feasible and puts the indication in the corresponding element of the array stats.

This method indicates whether the SOS sos is integer feasible, integer infeasible, or implied integer feasible in the current node solution.

This method indicates whether the SOS sos is integer feasible, integer infeasible, or implied integer feasible in the current node solution.

This method indicates whether the variable var is integer feasible, integer infeasible, or implied integer feasible in the current node solution.

This method indicates whether the variable var is integer feasible, integer infeasible, or implied integer feasible in the current node solution.

This method returns the value of the objective function of the incumbent solution (that is, the best integer solution found so far). If there is no incumbent, this method throws an exception.

This method returns the value of var in the incumbent solution. If there is no incumbent, this method throws an exception.

This method returns the value of var in the incumbent solution. If there is no incumbent, this method throws an exception.

Returns the value of each variable in the array vars with respect to the current incumbent solution, and it puts those values into the corresponding array vals. If there is no incumbent, this method throws an exception.

Returns the value of each variable in the array vars with respect to the current incumbent solution, and it puts those values into the corresponding array vals. If there is no incumbent, this method throws an exception.

This method returns the lower bound of var in the current node relaxation. This bound is likely to be different from the bound in the original model because an instance of IloCplex tightens bounds when it branches from a node to its subnodes.

This method returns the lower bound of var in the current node relaxation. This bound is likely to be different from the bound in the original model because an instance of IloCplex tightens bounds when it branches from a node to its subnodes.

This method puts the lower bound in the current node relaxation of each element of the array vars into the corresponding element of the array vals. These bounds are likely to be different from the bounds in the original model because an instance of IloCplex tightens bounds when it branches from a node to its subnodes.

This method puts the lower bound in the current node relaxation of each element of the array vars into the corresponding element of the array vals. These bounds are likely to be different from the bounds in the original model because an instance of IloCplex tightens bounds when it branches from a node to its subnodes.

This method returns the model currently extracted for the instance of IloCplex where the invoking goal applies.

Returns the identifier of the parallel thread being currently executed. This number is between 0 (zero) and the value returned by the method getUserThreads()-1.

Returns the total number of GUB cover cuts that have been added to the model so far during the current optimization.

Returns the total number of MIR cuts that have been added to the model so far during the current optimization.

This method returns the number of branches IloCplex is going to create at the current node.

Returns the total number of clique cuts that have been added to the model so far during the current optimization.

This method returns the number of columns in the current optimization model.

Returns the total number of cover cuts that have been added to the model so far during the current optimization.

Returns the total number of disjunctive cuts that have been added to the model so far during the current optimization.

Returns the total number of flow cover cuts that have been added to the model so far during the current optimization.

Returns the total number of flow path cuts that have been added to the model so far during the current optimization.

Returns the total number of fractional cuts that have been added to the model so far during the current optimization.

Returns the total number of implied bound cuts that have been added to the model so far during the current optimization.

Returns the total number of iterations executed so far during the current optimization to solve the node relaxations.

This method returns the number of nodes already processed in the current optimization.

This method returns the number of nodes left to explore in the current optimization.

This method returns the number of rows in the current optimization model.

Returns the linear objective coefficient for var in the model currently being solved.

Returns the linear objective coefficient for var in the model currently being solved.

This method puts the linear objective coefficient of each of the variables in the array vars into the corresponding element of the array vals.

This method puts the linear objective coefficient of each of the variables in the array vars into the corresponding element of the array vals.

This method returns the objective value of the solution of the current node.

Returns the branch priority used for variable var in the current optimization.

Returns the branch priority used for variable var in the current optimization.

This method returns the slack value for the constraint indicated by rng in the solution of the current node relaxation.

This method puts the slack value in the solution of the current node relaxation of each of the constraints in the array of ranges rngs into the corresponding element of the array vals.

This method returns the upper bound of the variable var in the current node relaxation. This bound is likely to be different from the bound in the original model because an instance of IloCplex tightens bounds when it branches from a node to its subnodes.

This method returns the upper bound of the variable var in the current node relaxation. This bound is likely to be different from the bound in the original model because an instance of IloCplex tightens bounds when it branches from a node to its subnodes.

This method puts the upper bound in the current node relaxation of each element of the array vars into the corresponding element of the array vals. These bounds are likely to be different from the bounds in the original model because an instance of IloCplex tightens bounds when it branches from a node to its subnodes.

This method puts the upper bound in the current node relaxation of each element of the array vars into the corresponding element of the array vals. These bounds are likely to be different from the bounds in the original model because an instance of IloCplex tightens bounds when it branches from a node to its subnodes.

This method returns the current pseudo cost for branching upward on the variable var.

This method returns the current pseudo cost for branching upward on the variable var.

This method returns the total number of parallel threads currently running.

This method returns the value of the variable var in the solution of the current node relaxation.

This method returns the value of the variable var in the solution of the current node relaxation.

This method returns the value of the expression expr in the solution of the current node relaxation.

This method puts the current node relaxation solution value of each variable in the array vars into the corresponding element of the array vals.

This method puts the current node relaxation solution value of each variable in the array vars into the corresponding element of the array vals.

This method returns IloTrue if an integer feasible solution has been found.

This method returns IloTrue if the solution of the current node is integer feasible.

This method returns IloTrue if the solution of the current node is SOS feasible for the special ordered set indicated in its argument. The SOS passed as a parameter to this method must be of type 2; the equivalent method for an SOS of type 1 is also available. See the User's Manual for more about these types of special ordered sets.

This method returns IloTrue if the solution of the current node is SOS feasible for the special ordered set indicated in its argument. The SOS passed as a parameter to this method must be of type 1; the equivalent method for an SOS of type 2 is also available. See the User's Manual for more about these types of special ordered sets.

IloCplex::GoalI::BranchType is an enumeration limited in scope to the class IloCplex::GoalI. This enumeration is used by the method IloCplex::GoalI:: getBranchType to tell what kind of branch IloCplex is about to make:

• BranchOnVariable indicates branching on a single variable.
• BranchOnAny indicates multiple bound changes and constraints will be used for branching.
• BranchOnSOS1 indicates branching on an SOS of type 1.
• BranchOnSOS2 indicates branching on an SOS of type 2.

The enumeration IloCplex::GoalI::IntegerFeasibility is an enumeration limited in scope to the class IloCplex::GoalI. This enumeration is used by IloCplex::GoalI::getFeasibility to access the integer feasibility of a variable or SOS in the current node solution:

• Feasible indicates the variable or SOS is integer feasible.
• ImpliedFeasible indicates the variable or SOS has been presolved out. It will be feasible when all other integer variables or SOS are integer feasible.
• Infeasible indicates the variable or SOS is integer infeasible.

This type defines an array type for IloCplex::GoalI::IntegerFeasibility. The fully qualified name of an integer feasibility array is IloCplex::GoalI::IntegerFeasibilityArray.