An instance of the class IloCplex::BranchCallbackI represents a user-written callback in an application that invokes an instance of IloCplex to solve a mixed integer program (MIP). The user-written callback is called prior to branching at a node in the branch-and-cut tree during the optimization of a MIP. It allows the user to query how the invoking instance of IloCplex is about to create subnodes at the current node and gives the user the option to override the selection made by the invoking instance of IloCplex. The user can create zero, one, or two branches.

• The method BranchCallbackI::prune removes the current node from the search tree. No subnodes from the current node will be added to the search tree.
• The method BranchCallbackI::makeBranch tells an instance of IloCplex how to create a subproblem. You may call this method zero, one, or two times in every invocation of the branch callback. If you call it once, it creates one node; it you call it twice, it creates two nodes (one node at each call).
• If you call neither IloCplex::BranchCallBackI::prune nor IloCplex::BranchCallBackI::makeBranch, the instance of IloCplex proceeds with its own selection.
• Calling both IloCplex::BranchCallBackI::prune and IloCplex::BranchCallBackI::makeBranch in one invocation of a branch callback is an error and results in unspecified behavior.

The methods of this class are for use in deriving a user-written callback class and in implementing the main method there.

If an attempt is made to access information not available to an instance of this class, an exception is thrown.

The user must be careful when using this class. Pruning a valid node can prune the optimal solution. Also, choosing a different branching variable can result in placing an invalid bound on a variable, in case the variable was already restricted to other bounds before.

In particular, the user must not branch on variables that are implied feasible, as defined in IloCplex::ControlCallbackI::IntegerFeasibility. Branching on such variables can cut off feasible solutions.

If the user intends to branch on continuous variables, the user must disable dual presolve reductions. To disable dual presolve reductions, set the parameter to control primal and dual reduction type, IloCplex::Param::Preprocessing::Reduce, either to the value 1 (one) (that is, CPX_PREREDUCE_PRIMALONLY) or to the value 0 (zero) (that is, CPX_PREREDUCE_NOPRIMALORDUAL).

Also, if the user intends to branch on continuous variables, the user must turn off the linear reduction switch, IloCplex::Param::Preprocessing::Linear.

By design, the CPLEX branch callback calculates and provides the branching decisions that CPLEX would make in case the user does not create any branches in the callback. Depending on variable selection and other features of your model, the computation of these candidate branches can be time-consuming. Consequently, if you know that you will never use the branching candidates suggested by CPLEX, then you can save time by disabling such features as strong branching.

This constructor creates a branch callback, that is, a control callback for splitting a node into two branches.

This method accesses branching information for the i-th branch that the invoking instance of IloCplex is about to create. The argument 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 argument vars contains the variables for which new bounds will be set in the i-th branch.
• The argument bounds contains the new bounds for the variables listed in vars; that is, bounds[j] is the new bound for vars[j].
• The argument dirs specifies 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.

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

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

This method offers the same facilities as the other methods IloCplex::BranchCallbackI::makeBranch, but for a branch specified by a set of constraints and a set of variables.

See MIPCallbackI::NodeId and MIPCallbackI::NodeData.

This method offers the same facilities as the other methods IloCplex::BranchCallbackI::makeBranch, but for a branch specified by a set of constraints and a set of variables.

See MIPCallbackI::NodeId and MIPCallbackI::NodeData.

This method offers the same facilities for a branch specified by only one constraint as IloCplex::BranchCallbackI::makeBranch does for a branch specified by a set of constraints.

See MIPCallbackI::NodeId and MIPCallbackI::NodeData.

This method overrides the branch chosen by an instance of IloCplex, by specifying a branch on constraints. A method named makeBranch can be called zero, one, or two times in every invocation of the branch callback. If you call it once, it creates one node; it you call it twice, it creates two nodes (one node at each call). If you call it more than twice, it throws an exception.

• The argument cons specifies an array of constraints that are to be added for the subnode being created.
• The argument objestimate provides an estimate of the resulting optimal objective value for the subnode specified by this branch. The invoking instance of IloCplex may use this estimate to select nodes to process. Providing a wrong estimate will not influence the correctness of the solution, but it may influence performance. Using the objective value of the current node is usually a safe choice.
• The argument data allows you to add an object of type IloCplex::MIPCallbackI::NodeData to the node representing the branch created by the makeBranch call. Such data objects must be instances of a user-written subclass of IloCplex::MIPCallbackI::NodeData.

See MIPCallbackI::NodeId and MIPCallbackI::NodeData.

For a branch specified by only one variable, this method offers the same facilities as IloCplex::BranchCallbackI::makeBranch for a branch specified by a set of variables.

See MIPCallbackI::NodeId and MIPCallbackI::NodeData.

For a branch specified by only one variable, this method offers the same facilities as IloCplex::BranchCallbackI::makeBranch for a branch specified by a set of variables.

See MIPCallbackI::NodeId and MIPCallbackI::NodeData.

This method overrides the branch chosen by an instance of IloCplex. A method named makeBranch can be called zero, one, or two times in every invocation of the branch callback. If you call it once, it creates one node; it you call it twice, it creates two nodes (one node at each call). If you call it more than twice, it throws an exception.

Each call specifies a branch; in other words, it instructs the invoking IloCplex object how to create a subnode from the current node by specifying new, tighter bounds for a set of variables.

• The argument vars contains the variables for which new bounds will be set in the branch.
• The argument bounds contains the new bounds for the variables listed in vars; that is, bounds[j] is the new bound to be set for vars[j].
• The argument dirs specifies 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].

• The argument objestimate provides an estimate of the resulting optimal objective value for the subnode specified by this branch. The invoking instance of IloCplex may use this estimate to select nodes to process. Providing a wrong estimate will not influence the correctness of the solution, but it may influence performance. Using the objective value of the current node is usually a safe choice.
• The argument data allows you to add an object of type IloCplex::MIPCallbackI::NodeData to the node representing the branch created by the makeBranch call. Such data objects must be instances of a user-written subclass of IloCplex::MIPCallbackI::NodeData.

See MIPCallbackI::NodeId and MIPCallbackI::NodeData.

This method overrides the branch chosen by an instance of IloCplex. A method named makeBranch can be called zero, one, or two times in every invocation of the branch callback. If you call it once, it creates one node; if you call it twice, it creates two nodes (one node at each call). If you call it more than twice, it throws an exception.

Each call specifies a branch; in other words, it instructs the invoking IloCplex object how to create a subnode from the current node by specifying new, tighter bounds for a set of variables.

• The argument vars contains the variables for which new bounds will be set in the branch.

• The argument bounds contains the new bounds for the variables listed in vars; that is, bounds[j] is the new bound to be set for vars[j].

• The argument dirs specifies 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].

• The argument objestimate provides an estimate of the resulting optimal objective value for the subnode specified by this branch. The invoking instance of IloCplex may use this estimate to select nodes to process. Providing a wrong estimate will not influence the correctness of the solution, but it may influence performance. Using the objective value of the current node is usually a safe choice.

• The argument data allows you to add an object of type IloCplex::MIPCallbackI::NodeData to the node representing the branch created by the makeBranch call. Such data objects must be instances of a user-written subclass of IloCplex::MIPCallbackI::NodeData.

See MIPCallbackI::NodeId and MIPCallbackI::NodeData.

This method overrides the branch chosen by an instance of IloCplex. A method named makeBranch can be called zero, one, or two times in every invocation of the branch callback. If you call it once, it creates one node; if you call it twice, it creates two nodes (one node at each call). If you call it more than twice, it throws an exception.

Each call creates a child node for the current node that is identical to the branch number that CPLEX is executing and attaches the user object data to the new child node.

The same index num must not be used with more than one call of the function.

• The argument num specifies the CPLEX branch to replicate.

• The argument data allows you to add an object of type IloCplex::MIPCallbackI::NodeData to the node representing the branch created by the makeBranch call. Such data objects must be instances of a user-written subclass of IloCplex::MIPCallbackI::NodeData.

See MIPCallbackI::NodeId and MIPCallbackI::NodeData.

By calling this method, you instruct the CPLEX branch-and-cut search not to create any child nodes from the current node, or, in other words, to discard nodes below the current node; it does not revisit the discarded nodes below the current node. In short, it creates no branches. It is an error to call both prune and makeBranch in one invocation of a callback.

Pruning nodes in this way is not compatible with the method IloCplex::populate because that method retains fathomed nodes for subsequent use.

This method returns the callback type of the invoking callback object.

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

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