ilog.opl

Class IloCplex.BranchCallback

java.lang.Object

ilog.opl.IloCplex.Callback

ilog.opl.IloCplex.MIPInfoCallback

ilog.opl.IloCplex.MIPCallback

ilog.opl.IloCplex.ControlCallback

ilog.opl.IloCplex.BranchCallback

All Implemented Interfaces:

java.lang.Cloneable

Enclosing class:

IloCplex

public abstract static class IloCplex.BranchCallback
extends IloCplex.ControlCallback

This is the base class for user-written callbacks that control branching during the branch-and-cut search.

This callback will be called prior to the creation of the children of the current node. It allows you to query how the invoking instance of IloCplex is about to create the children, and gives you the opportunity to override this branch creation.

You can create one or two branches by calling one of the makeBranch methods once or twice. It is an error to call makeBranch more than twice.

By calling method prune, you remove the current node from the search tree. In other words, no subnodes from the current node will be added to the search tree. Calling both prune and makeBranch in one invocation of a branch callback is an error and yields unspecified behavior.

If you call neither prune nor makeBranch, the instance of IloCplex proceeds with its own branching.

The constructor and methods of this class are protected to make sure that they are used only to derive a user-written callback class or to implement the main method in it.

See Also:

IloCplex.ControlCallback

Nested Class Summary

Nested classes/interfaces inherited from class ilog.opl.IloCplex.MIPCallback

IloCplex.MIPCallback.NodeData

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	IloCplex.BranchCallback() Constructor for user-written branch callbacks.

Method Summary

Methods

Modifier and Type	Method and Description
protected double[]	getBranches(IloNumVar[][] vars, double[][] bounds, IloCplex.BranchDirection[][] dirs) Queries the branches IloCplex would create at the current node if not overridden by the invoking callback.
protected IloCplex.BranchType	getBranchType() Returns the type of branching IloCplex is going to do at the current node unless overridden by the invoking callback.
protected int	getNbranches() Returns the number of branches IloCplex is going to create at the current node unless overridden by the invoking callback.
protected IloCplex.NodeId	getNodeId() Returns the IloCplex.NodeId of the current node.
protected boolean	isIntegerFeasible() Returns true if the current node solution is considered to be integer feasible and thus potentially eligible as a new incumbent.
protected IloCplex.NodeId	makeBranch(IloConstraint[] cuts, double objestimate) Creates a child node for the current node.
protected IloCplex.NodeId	makeBranch(IloConstraint[] cuts, double objestimate, java.lang.Object data) Creates a child node for the current node.
protected IloCplex.NodeId	makeBranch(IloNumVar[] vars, double[] bounds, IloCplex.BranchDirection[] dirs, double objestimate) Creates a child node for the current node.
protected IloCplex.NodeId	makeBranch(IloNumVar[] vars, double[] bounds, IloCplex.BranchDirection[] dirs, double objestimate, java.lang.Object data) Creates a child node for the current node.
protected IloCplex.NodeId	makeBranch(IloNumVar var, double bound, IloCplex.BranchDirection dir, double objestimate) Creates a child node for the current node.
protected IloCplex.NodeId	makeBranch(IloNumVar var, double bound, IloCplex.BranchDirection dir, double objestimate, java.lang.Object data) Creates a child node for the current node.
protected IloCplex.NodeId	makeBranch(IloRange rng, double objestimate) Creates a child node for the current node.
protected IloCplex.NodeId	makeBranch(IloRange rng, double objestimate, java.lang.Object data) Creates a child node for the current node.
protected IloCplex.NodeId	makeBranch(int i, java.lang.Object o)
protected void	prune() Instructs the IloCplex branch-and-cut search not to create any child nodes for the current node.

Methods inherited from class ilog.opl.IloCplex.ControlCallback

getDownPseudoCost, getFeasibilities, getFeasibilities, getFeasibility, getLB, getLBs, getLBs, getNodeData, getObjValue, getSlack, getSlacks, getSlacks, getSOSFeasibility, getSOSFeasibility, getUB, getUBs, getUBs, getUpPseudoCost, getValue, getValue, getValues, getValues, setNodeData

Methods inherited from class ilog.opl.IloCplex.MIPCallback

getObjCoef, getObjCoefs, getObjCoefs, getUserThreads

Methods inherited from class ilog.opl.IloCplex.MIPInfoCallback

getBestObjValue, getCutoff, getDirection, getIncumbentObjValue, getIncumbentValue, getIncumbentValue, getIncumbentValues, getIncumbentValues, getMIPRelativeGap, getMyThreadNum, getNiterations, getNnodes, getNremainingNodes, getPriority, hasIncumbent

Methods inherited from class ilog.opl.IloCplex.Callback

abort, getCplexTime, getDetTime, getEndDetTime, getEndTime, getEnvImpl, getModel, getNcols, getNQCs, getNrows, getStartDetTime, getStartTime, 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()

Constructor for user-written branch callbacks. This constructor can be called only to construct objects of derived user-written callback classes, but not to construct IloCplex.BranchCallback objects directly.

Method Detail

getNodeId

protected IloCplex.NodeId getNodeId()
                             throws IloException

Returns the IloCplex.NodeId of the current node.

Throws:

IloException

Returns:

the IloCplex.NodeId of the current node.

getNbranches

protected int getNbranches()

Returns the number of branches IloCplex is going to create at the current node unless overridden by the invoking callback.

Returns:

The number of branches IloCplex is going to create at the current node.

getBranchType

protected IloCplex.BranchType getBranchType()

Returns the type of branching IloCplex is going to do at the current node unless overridden by the invoking callback.

Returns:

The type of branching IloCplex is going to do at the current node.

getBranches

protected double[] getBranches(IloNumVar[][] vars,
                   double[][] bounds,
                   IloCplex.BranchDirection[][] dirs)
                        throws IloException

Queries the branches IloCplex would create at the current node if not overridden by the invoking callback. The returned branch will be performed if the callback does not call the method makeBranch or prune.

Throws:

IloException

Parameters:

vars - An array of length at least getNbranches of arrays. Upon completion, vars[i] will contain the list of variables whose bounds will be changed in child i of the current node.

bounds - An array of length at least getNbranches of arrays. Upon completion, bounds[i] will contain the list of new bounds used for child i. One bound of variable vars[i][j] will be set to bounds[i][j] for all possible pairs i, j.

dirs - An array of length at least getNbranches of arrays. Upon completion of this method dirs[i] will contain the list of branch directions used for child 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.

Returns:

An array of double values containing the node estimates for the branches.

isIntegerFeasible

protected boolean isIntegerFeasible()
                             throws IloException

Returns true if the current node solution is considered to be integer feasible and thus potentially eligible as a new incumbent. Note that in this case, getNbranches returns 0.

Throws:

IloException

Returns:

true if the current node solution is integer feasible.

makeBranch

protected IloCplex.NodeId makeBranch(IloNumVar[] vars,
                         double[] bounds,
                         IloCplex.BranchDirection[] dirs,
                         double objestimate)
                              throws IloException

Creates a child node for the current node. This method or any of the other makeBranch methods can be called zero, one, or two times. Each time one of the makeBranch methods is called a child node of the current node is created, thereby overriding the branch decision taken by the invoking IloCplex object. It is an error to call one of the makeBranch methods more than twice. If no makeBranch method is called and the method prune is not called as well, the search is continued with the branching decision taken by the invoking IloCplex object.

Each call specifies a branch; in other words, it instructs the invoking IloCplex optimizer how to create a subnode from the current node. With this method this is done by specifying new, tighter bounds for a set of variables. 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. A poor 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.

Throws:

IloException

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. Setting dirs[j] to IloCplex.BranchDirection.Up specifies that the lower bound of variable vars[j] is to be set to bounds[j]. Setting dirs[j] to IloCplex.BranchDirection.Down specifies that the upper bound of variable vars[j] is to be set to bounds[j].

objestimate - An estimate of the objective value at the subnode specified by this branch.

Returns:

The IloCplex.NodeId of the created child node.

makeBranch

protected IloCplex.NodeId makeBranch(IloNumVar[] vars,
                         double[] bounds,
                         IloCplex.BranchDirection[] dirs,
                         double objestimate,
                         java.lang.Object data)
                              throws IloException

Creates a child node for the current node. This method or any of the other makeBranch methods can be called zero, one or two times. Each time one of the makeBranch methods is called a child node of the current node is created, thereby overriding the branch decision taken by the invoking IloCplex object. It is an error to call one of the makeBranch methods more than twice. If no makeBranch method is called and the method prune is not called as well, the search is continued with the branching decision taken by the invoking IloCplex object.

Each call specifies a branch; in other words, it instructs the invoking IloCplex optimizer how to create a subnode from the current node. With this method this is done by specifying new, tighter bounds for a set of variables. 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. A poor 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.

Throws:

IloException

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. Setting dirs[j] to IloCplex.BranchDirection.Up specifies that the lower bound of variable vars[j] is to be set to bounds[j]. Setting dirs[j] to IloCplex.BranchDirection.Down specifies that the upper bound of variable vars[j] is to be set to bounds[j].

objestimate - An estimate of the objective value at the subnode specified by this branch.

data - A user object that will be assigned to the newly created node. This object can later be queried from other callbacks with the method getNodeData.

Returns:

The IloCplex.NodeId of the created child node.

makeBranch

protected IloCplex.NodeId makeBranch(IloNumVar var,
                         double bound,
                         IloCplex.BranchDirection dir,
                         double objestimate)
                              throws IloException

Creates a child node for the current node. This method or any of the other makeBranch methods can be called zero, one or two times. Each time one of the makeBranch methods is called a child node of the current node is created, thereby overriding the branch decision taken by the invoking IloCplex object. It is an error to call one of the makeBranch methods more than twice. If no makeBranch method is called and the method prune is not called as well, the search is continued with the branching decision taken by the invoking IloCplex object.

Each call specifies a branch; in other words, it instructs the invoking IloCplex optimizer how to create a subnode from the current node. With this method this is done by specifying a new, tighter bound for one variable.

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. A poor 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.

Throws:

IloException

Parameters:

var - The variable for which a new bounds will be set in the branch.

bound - The new bound for variable var.

dir - The branching direction for var. Setting dir to IloCplex.BranchDirection.Up specifies that the lower bound of variable var is to be set to bound. Setting dir to IloCplex.BranchDirection.Down specifies that the upper bound of variable var is to be set to bound.

objestimate - An estimate of the objective value at the subnode specified by this branch.

Returns:

The IloCplex.NodeId of the created child node.

makeBranch

protected IloCplex.NodeId makeBranch(IloNumVar var,
                         double bound,
                         IloCplex.BranchDirection dir,
                         double objestimate,
                         java.lang.Object data)
                              throws IloException

Creates a child node for the current node. This method or any of the other makeBranch methods can be called zero, one or two times. Each time one of the makeBranch methods is called a child node of the current node is created, thereby overriding the branch decision taken by the invoking IloCplex object. It is an error to call one of the makeBranch methods more than twice. If no makeBranch method is called and the method prune is not called as well, the search is continued with the branching decision taken by the invoking IloCplex object.

Each call specifies a branch; in other words, it instructs the invoking IloCplex optimizer how to create a subnode from the current node. With this method this is done by specifying a new, tighter bound for one variable.

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. A poor 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.

Throws:

IloException

Parameters:

var - The variable for which a new bounds will be set in the branch.

bound - The new bound for variable var.

dir - The branching direction for var. Setting dir to IloCplex.BranchDirection.Up specifies that the lower bound of variable var is to be set to bound. Setting dir to IloCplex.BranchDirection.Down specifies that the upper bound of variable var is to be set to bound.

objestimate - An estimate of the objective value at the subnode specified by this branch.

data - A user object that will be assigned to the newly created node. This object can later be queried from other callbacks with the method getNodeData.

Returns:

The IloCplex.NodeId of the created child node.

makeBranch

protected IloCplex.NodeId makeBranch(IloConstraint[] cuts,
                         double objestimate)
                              throws IloException

Creates a child node for the current node. This method or any of the other makeBranch methods can be called zero, one or two times. Each time one of the makeBranch methods is called a child node of the current node is created, thereby overriding the branch decision taken by the invoking IloCplex object. It is an error to call one of the makeBranch methods more than twice. If no makeBranch method is called and the method prune is not called as well, the search is continued with the branching decision taken by the invoking IloCplex object.

Each call specifies a branch; in other words, it instructs the invoking IloCplex optimizer how to create a subnode from the current node. With this method this is done by specifying additional constraints that are added to the current node in order to define the child node.

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. A poor 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.

Throws:

IloException

Parameters:

cuts - The array of constraints that will be added to the current node in order to define the child node. All constraints must be linear.

objestimate - An estimate of the objective value at the subnode specified by this branch.

Returns:

The IloCplex.NodeId of the created child node.

makeBranch

protected IloCplex.NodeId makeBranch(int i,
                         java.lang.Object o)
                              throws IloException

Throws:

IloException

makeBranch

protected IloCplex.NodeId makeBranch(IloConstraint[] cuts,
                         double objestimate,
                         java.lang.Object data)
                              throws IloException

Creates a child node for the current node. This method or any of the other makeBranch methods can be called zero, one or two times. Each time one of the makeBranch methods is called a child node of the current node is created, thereby overriding the branch decision taken by the invoking IloCplex object. It is an error to call one of the makeBranch methods more than twice. If no makeBranch method is called and the method prune is not called as well, the search is continued with the branching decision taken by the invoking IloCplex object.

Each call specifies a branch; in other words, it instructs the invoking IloCplex optimizer how to create a subnode from the current node. With this method this is done by specifying additional constraints that will be added to the current node in order to define the child node.

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. A poor 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.

Throws:

IloException

Parameters:

cuts - The array of constraints that will be added to the current node in order to define the child node. All constraints must be linear.

objestimate - An estimate of the objective value at the subnode specified by this branch.

data - A user object that will be assigned to the newly created node. This object can later be queried from other callbacks with the method getNodeData.

Returns:

The IloCplex.NodeId of the created child node.

makeBranch

protected IloCplex.NodeId makeBranch(IloRange rng,
                         double objestimate)
                              throws IloException

Creates a child node for the current node. This method or any of the other makeBranch methods can be called zero, one or two times. Each time one of the makeBranch methods is called a child node of the current node is created, thereby overriding the branch decision taken by the invoking IloCplex object. It is an error to call one of the makeBranch methods more than twice. If no makeBranch method is called and the method prune is not called as well, the search is continued with the branching decision taken by the invoking IloCplex object.

Each call specifies a branch; in other words, it instructs the invoking IloCplex optimizer how to create a subnode from the current node. With this method this is done by specifying an additional constraint that needs to be added to the current node in order to define the child node.

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. A poor 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.

Throws:

IloException

Parameters:

rng - The constraint that will be added to the current node in order to define the child node. The constraint must be linear.

objestimate - An estimate of the objective value at the subnode specified by this branch.

Returns:

The IloCplex.NodeId of the created child node.

makeBranch

protected IloCplex.NodeId makeBranch(IloRange rng,
                         double objestimate,
                         java.lang.Object data)
                              throws IloException

Creates a child node for the current node. This method or any of the other makeBranch methods can be called zero, one or two times. Each time one of the makeBranch methods is called a child node of the current node is created, thereby overriding the branch decision taken by the invoking IloCplex object. It is an error to call one of the makeBranch methods more than twice. If no makeBranch method is called and the method prune is not called as well, the search is continued with the branching decision taken by the invoking IloCplex object.

Each call specifies a branch; in other words, it instructs the invoking IloCplex optimizer how to create a subnode from the current node. With this method this is done by specifying an additional constraint that will be added to the current node in order to define the child node.

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. A poor 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.

Throws:

IloException

Parameters:

rng - The constraint that will be added to the current node in order to define the child node. The constraint must be linear.

objestimate - An estimate of the objective value at the subnode specified by this branch.

data - A user object that will be assigned to the newly created node. This object can later be queried from other callbacks with the method getNodeData.

Returns:

The IloCplex.NodeId of the created child node.

prune

protected void prune()

Instructs the IloCplex branch-and-cut search not to create any child nodes for the current node. In short, if this method is called IloCplex creates no branches at the current node. It is an error to call methods prune and makeBranch in one invocation of a branch callback.