ilog.cplex
Class IloCplex.BranchCallback

java.lang.Object
  |
  +--ilog.cplex.IloCplex.Callback
        |
        +--ilog.cplex.IloCplex.MIPCallback
              |
              +--ilog.cplex.IloCplex.ControlCallback
                    |
                    +--ilog.cplex.IloCplex.BranchCallback
public abstract static class IloCplex.BranchCallback
extends IloCplex.ControlCallback

An instance of this class represents a user-written callback in an application that uses 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 you to query how the invoking instance of IloCplex is about to create subnodes at the current node and gives you the option to override the selection made by the invoking instance of IloCplex.

You can create zero, one, or two branches. The method prune() removes the current node from the search tree. No subnodes from the current node will be added to the search tree. The method makeBranch tells an instance of IloCplex how to create a subproblem. You may call this member function 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 prune() nor makeBranch, then the instance of IloCplex proceeds with its own selection.

Calling both prune() and makeBranch in one invocation of a branch callback is an error and yields unspecified behavior.

The methods of this class are for use in deriving a user-written callback class and in implementing the main method in it. If an attempt is made to access information not available to an instance of this class, an exception is thrown.

See Also:
IloCplex.ControlCallback

Constructor Summary
protected IloCplex.BranchCallback()
          This constructor is used to create a user-written callback class which is called prior to branching at a node in the branch and cut tree during the optimization of a MIP.
 
Method Summary
protected  void getBranches(IloNumVar[][] vars, double[][] bounds, IloCplex.BranchDirection[][] dirs)
          Queries the branches IloCplex would create at the current node.
protected  IloCplex.BranchType getBranchType()
          Gets the type of branching IloCplex is going to do for the current node.
protected  int getNbranches()
          Gets the number of branches IloCplex is going to create at the current node.
protected  IloCplex.NodeId getNodeId()
          Gets the node id of the current node.
protected  IloCplex.NodeId makeBranch(IloNumVar[] vars, double[] bounds, IloCplex.BranchDirection[] dirs, double objestimate)
          Creates one or two nodes which override the branch chosen by an instance of IloCplex.
protected  IloCplex.NodeId makeBranch(IloNumVar var, double bound, IloCplex.BranchDirection dir, double objestimate)
          Creates one or two nodes which override the branch chosen by an instance of IloCplex at variable var.
protected  void prune()
          Instructs the CPLEX branch and cut search not to create any child nodes from the current node.
 
Methods inherited from class ilog.cplex.IloCplex.ControlCallback
getDownPseudoCost, getFeasibilities, getFeasibilities, getFeasibility, getLB, getLBs, getLBs, getObjCoef, getObjCoefs, getObjCoefs, getObjValue, getSlack, getSlacks, getSlacks, getSOSFeasibility, getSOSFeasibility, getUB, getUBs, getUBs, getUpPseudoCost, getValue, getValue, getValues, getValues
 
Methods inherited from class ilog.cplex.IloCplex.MIPCallback
getBestObjValue, getCutoff, getDirection, getIncumbentObjValue, getIncumbentValue, getIncumbentValues, getIncumbentValues, getNcliques, getNcovers, getNdisjunctiveCuts, getNflowCovers, getNflowPaths, getNfractionalCuts, getNGUBcovers, getNimpliedBounds, getNiterations, getNMIRs, getNnodes, getNremainingNodes, getPriority, isIntegerFeasible
 
Methods inherited from class ilog.cplex.IloCplex.Callback
abort, main
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IloCplex.BranchCallback

protected IloCplex.BranchCallback()
This constructor is used to create a user-written callback class which is called prior to branching at a node in the branch and cut tree during the optimization of a MIP.
Method Detail

getNodeId

protected IloCplex.NodeId getNodeId()
Gets the node id of the current node.
Returns:
the node id of the current node.

getNbranches

protected int getNbranches()
Gets the number of branches IloCplex is going to create at the current node.
Returns:
The number of branches IloCplex is going to create at the current node.

getBranchType

protected IloCplex.BranchType getBranchType()
Gets the type of branching IloCplex is going to do for the current node.
Returns:
the type of branching IloCplex is going to do for the current node.

getBranches

protected void getBranches(IloNumVar[][] vars,
                           double[][] bounds,
                           IloCplex.BranchDirection[][] dirs)
                    throws IloException
Queries the branches IloCplex would create at the current node.
Parameters:
vars - An array of length at least getNbranches() of arrays, where the variables for each branch will be stored. vars[i] will contain an array with the list of variables used for branch i.
bounds - An array of length at least getNbranches() of arrays where the bound values for each branch will be stored. bounds[i] will contain an array with the list of new bounds used for branch i. One bound of variable vars[i][j] will be set to bounds[i][j] for all possible pairs i, j.
bounds - An array of length at least getNbranches() of arrays where the branch directions for each branch will be stored. dirs[i] will contain an array with the list of branch directions used for branch i. If dirs[i][j] is IloCplex.BranchDirection.Up the lower bound of variable vars[i][j] will be set to bounds[i][j] for all possible pairs i, j. Similarly, if dirs[i][j] is IloCplex.BranchDirection.Down the upper bound of variable vars[i][j] will be set to bounds[i][j] for all possible pairs i, j.

makeBranch

protected IloCplex.NodeId makeBranch(IloNumVar[] vars,
                                     double[] bounds,
                                     IloCplex.BranchDirection[] dirs,
                                     double objestimate)
                              throws IloException
Creates one or two nodes which override the branch chosen by an instance of IloCplex. It 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 tells how to create a subnode from the current node by specifying new, tighter bounds for a set of variables. The variables used to specify a branch must not have been presolved out. That is, calling getFeasibility must not return ImpliedFeasible.

The parameter 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.
Parameters:
vars - The array of variables for which new bounds will be set in the branch.
bounds - The array of new bounds for the variables corresponding to the variables in vars.
dirs - The array of branching directions for the variables in vars.
objestimate - An estimate of the objective value at the subnode specified by this branch.
Returns:
A new branching node.

makeBranch

protected IloCplex.NodeId makeBranch(IloNumVar var,
                                     double bound,
                                     IloCplex.BranchDirection dir,
                                     double objestimate)
                              throws IloException
Creates one or two nodes which override the branch chosen by an instance of IloCplex at variable var. It 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 tells how to create a subnode from the current node by specifying new, tighter bounds for a set of variables. The variables used to specify a branch must not have been presolved out. That is, calling getFeasibility must not return ImpliedFeasible.

The parameter 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.
Parameters:
var - The variable for which a new bound will be set in the branch.
bounds - The new bound for the variable var.
dirs - The branching direction for the variable var.
objestimate - An estimate of the objective value at the subnode specified by this branch.
Returns:
A new branching node.

prune

protected void prune()
Instructs the CPLEX branch and cut search not to create any child nodes from the current node. It will discard nodes below the current node, and will not revisit the discarded nodes below the current node. In short, it creates no branches. It is an error to call prune and code>makeBranch in one invocation of a callback.