ilog.cplex

Class IloCplex.ControlCallback

java.lang.Object

ilog.cplex.IloCplex.Callback

ilog.cplex.IloCplex.OptimizationCallback

ilog.cplex.IloCplex.MIPInfoCallback

ilog.cplex.IloCplex.MIPCallback

ilog.cplex.IloCplex.ControlCallback

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

IloCplex.BranchCallback, IloCplex.HeuristicCallback, IloCplex.LazyConstraintCallback, IloCplex.SolveCallback, IloCplex.UserCutCallback

Enclosing class:

IloCplex

public abstract static class IloCplex.ControlCallback
extends IloCplex.MIPCallback

Base class for all callback classes querying or taking control of the MIP branch-and-cut search.

This is an advanced class.

Important:

Advanced classes typically demand a profound understanding of the algorithms used by CPLEX. Thus they incur a higher risk of incorrect behavior in your application, behavior that can be difficult to debug. Therefore, the team encourages you to consider carefully whether you can accomplish the same task by means of other classes instead.

This is the base class for all callback classes that allow you to query or take control of the MIP branch-and-cut search. These classes are:

• IloCplex.BranchCallback
• IloCplex.HeuristicCallback
• IloCplex.UserCutCallback
• IloCplex.LazyConstraintCallback
• IloCplex.SolveCallback

An instance of ControlCallback is not a callback for implementing user functionality itself, but rather provides the common interface for those listed callback classes. Those callbacks share the property that they are called at every node in the branch-and-cut search tree, and allow you to access node-related data. For each branch-and-cut node, those callbacks are called in the following order:

1. IloCplex.UserCutCallback: Once the node problem has been solved and IloCplex has added all its cuts, the user cut callback is called. In case new cuts are added to the problem, the node problem is solved again. This is iterated until no more cuts are added to the problem.
2. IloCplex.HeuristicCallback: Once the node has been fully solved (that is including all the cuts that may have been added), the heuristic callback is called in an attempt to generate an integer feasible solution from the current relaxation solution at that node.
3. IloCplex.BranchCallback: Finally, if the relaxation solution at the current node is either integer infeasible or rejected by the IloCplex.IncumbentCallback, the problem is split into subproblems. At that point the IloCplex.BranchCallback can be used to control how to create the subproblems.

The 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.

Unbounded ray

In the case where the node LP is unbounded, the methods getValue return a vector that corresponds to an unbounded direction. The vector is scaled in such a way that the maximum absolute value of one of its elements is CPX_INFBOUND. Thus, often the vector can be used directly, for example to separate lazy constraints. However, due to the large values, care must be taken to deal with potential numerical errors. If in doubt, rescale the vector, and use it as an unbounded ray rather than as a primal vector.

See Also:

IloCplex.Callback, IloCplex.MIPCallback, IloCplex.BranchCallback, IloCplex.UserCutCallback, IloCplex.LazyConstraintCallback, IloCplex.HeuristicCallback

Nested Class Summary

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

IloCplex.MIPCallback.NodeData

Nested classes/interfaces inherited from class ilog.cplex.IloCplex.Callback

IloCplex.Callback.Context, IloCplex.Callback.Function

Constructor Summary

Constructors

Constructor and Description
IloCplex.ControlCallback()

Method Summary

Methods

Modifier and Type	Method and Description
protected double	getDownPseudoCost(IloNumVar var) Returns the pseudo cost for branching down on variable var.
protected IloCplex.IntegerFeasibilityStatus[]	getFeasibilities(IloNumVar[] var) States whether the variables in the specified array are integer feasible, integer infeasible, or implied integer feasible in the current node solution.
protected IloCplex.IntegerFeasibilityStatus[]	getFeasibilities(IloNumVar[] var, int start, int num) Queries whether the variables specified in the array are integer feasible, integer infeasible, or implied integer feasible in the current node solution.
protected IloCplex.IntegerFeasibilityStatus	getFeasibility(IloNumVar var) States whether the variable var is integer feasible, integer infeasible, or implied integer feasible in the current node solution.
protected double	getLB(IloNumVar var) Returns the current lower bound for the variable var.
protected double[]	getLBs(IloNumVar[] var) Returns the current lower bounds for an array of variables.
protected double[]	getLBs(IloNumVar[] var, int start, int num) Returns the current lower bounds for a set of variables.
protected java.lang.Object	getNodeData() Returns the user object attached to the current node.
protected IloCplex.NodeId	getNodeId() Returns the node identifier of the current node.
protected double	getObjValue() Returns the objective function value of the solution at the current node.
protected double	getSlack(IloRange rng) Returns the slack value of a constraint for the solution of the continuous relaxation of the current node.
protected double[]	getSlacks(IloRange[] rng) Returns the slack values of an array of constraints for the solution of the current node.
protected double[]	getSlacks(IloRange[] rng, int start, int num) Returns the slack values of a set of constraints for the solution of the current node.
protected IloCplex.IntegerFeasibilityStatus	getSOSFeasibility(IloSOS1 sos) States whether the special ordered set of type 1 is integer feasible, integer infeasible, or implied integer feasible in the current node solution.
protected IloCplex.IntegerFeasibilityStatus	getSOSFeasibility(IloSOS2 sos) States whether the special ordered set of type 2 is integer feasible, integer infeasible, or implied integer feasible in the current node solution.
protected double	getUB(IloNumVar var) Returns the current upper bound for the variable var.
protected double[]	getUBs(IloNumVar[] var) Returns the current upper bounds for an array of variables.
protected double[]	getUBs(IloNumVar[] var, int start, int num) Returns the current upper bounds for a set of variables.
protected double	getUpPseudoCost(IloNumVar var) Returns the pseudo cost for branching up on variable var.
protected double	getValue(IloNumExpr expr) Returns the value expr takes for the solution of the continuous relaxation of the current node.
protected double	getValue(IloNumVar var) Returns the solution value of a variable at the current node.
protected double[]	getValues(IloNumVar[] var) Returns the solution values for an array of variables at the current node.
protected double[]	getValues(IloNumVar[] var, int start, int num) Returns the solution values for a set of variables at the current node.
protected java.lang.Object	setNodeData(java.lang.Object data) Sets the user object attached to the current node.

Methods inherited from class ilog.cplex.IloCplex.MIPCallback

getCurrentNodeDepth, getNodeDoubleInfo, getNodeIntInfo, getNodeLongInfo, getObjCoef, getObjCoefs, getObjCoefs

Methods inherited from class ilog.cplex.IloCplex.MIPInfoCallback

getBestObjValue, getCutoff, getDirection, getIncumbentObjValue, getIncumbentValue, getIncumbentValue, getIncumbentValues, getIncumbentValues, getMIPRelativeGap, getNcuts, getNiterations, getNiterations64, getNnodes, getNnodes64, getNremainingNodes, getNremainingNodes64, getPriority, getQuality, hasIncumbent

Methods inherited from class ilog.cplex.IloCplex.OptimizationCallback

getModel, getNcols, getNQCs, getNrows

Methods inherited from class ilog.cplex.IloCplex.Callback

abort, getCplexTime, getDetTime, getEndDetTime, getEndTime, getStartDetTime, getStartTime, main

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IloCplex.ControlCallback

public IloCplex.ControlCallback()

Method Detail

getNodeId

protected IloCplex.NodeId getNodeId()
                             throws IloException

Returns the node identifier of the current node.

Throws:

IloException

Returns:

the IloCplex.NodeId of the current node.

getLB

protected double getLB(IloNumVar var)
                throws IloException

Returns the current lower bound for the variable var. This bound may be different from the bound the variable has in the active model, since branching or bound strengthening may have been applied to it. The corresponding solution value from getValue may violate this bound at a node where a new incumbent has been found because the bound is tightened when an incumbent is found.

Throws:

IloException

Parameters:

var - The variable whose current lower bound is being queried.

Returns:

The lower bound for the variable var at the current node.

getLBs

protected double[] getLBs(IloNumVar[] var)
                   throws IloException

Returns the current lower bounds for an array of variables. The bounds may be different from the bounds the variables have in the active model, since branching or bound strengthening may have been applied to them. The corresponding solution values from getValues may violate these bounds at a node where a new incumbent has been found because the bounds are tightened when an incumbent is found.

Throws:

IloException

Parameters:

var - An array of variables whose current lower bounds are being queried.

Returns:

An array of double values containing the current lower bounds for the specified variables. If the returned array is called lb, lb[j] contains the lower bound of variable var[j] at the current node.

getLBs

protected double[] getLBs(IloNumVar[] var,
              int start,
              int num)
                   throws IloException

Returns the current lower bounds for a set of variables. The bounds may be different from the bounds the variables have in the active model, since branching or bound strengthening may have been applied to them. The corresponding solution values from getValues may violate these bounds at a node where a new incumbent has been found because the bounds are tightened when an incumbent is found.

Throws:

IloException

Parameters:

var - An array containing the variables whose current lower bounds are being queried.

start - The index of the first variable in var for which to query the current lower bound.

num - The number of consecutive variables in var for which to query the current lower bounds.

Returns:

An array of double values containing the current lower bounds for the specified variables. If the returned array is called lb, lb[j] contains the lower bound of variable var[j+start] at the current node, for j = 0, ..., num-1.

getUB

protected double getUB(IloNumVar var)
                throws IloException

Returns the current upper bound for the variable var. This bound may be different from the bound the variable has in the active model, since branching or bound strengthening may have been applied to it. The corresponding solution value from getValue may violate this bound at a node where a new incumbent has been found because the bound is tightened when an incumbent is found.

Throws:

IloException

Parameters:

var - The variable whose current upper bound is being queried.

Returns:

The upper bound for the variable var at the current node.

getUBs

protected double[] getUBs(IloNumVar[] var)
                   throws IloException

Returns the current upper bounds for an array of variables. The bounds may be different from the bounds the variables have in the active model, since branching or bound strengthening may have been applied to them. The corresponding solution values from getValues may violate these bounds at a node where a new incumbent has been found because the bounds are tightened when an incumbent is found.

Throws:

IloException

Parameters:

var - An array of variables whose current upper bounds are being queried.

Returns:

An array of double values containing the current upper bounds for the specified variables. If the returned array is called ub, ub[j] contains the upper bound of variable var[j] at the current node.

getUBs

protected double[] getUBs(IloNumVar[] var,
              int start,
              int num)
                   throws IloException

Returns the current upper bounds for a set of variables. The bounds may be different from the bounds the variables have in the active model, since branching or bound strengthening may have been applied to them. The corresponding solution values from getValues may violate these bounds at a node where a new incumbent has been found because the bounds are tightened when an incumbent is found.

Throws:

IloException

Parameters:

var - An array containing the variables whose current upper bounds are being queried.

start - The index of the first variable in var for which to query the current upper bound.

num - The number of consecutive variables in var for which to query the current upper bounds.

Returns:

An array of double values containing the current upper bounds for the specified variables. If the returned array is called ub, ub[j] contains the upper bound of variable var[j+start] at the current node, for j = 0, ..., num-1.

getObjValue

protected double getObjValue()
                      throws IloException

Returns the objective function value of the solution at the current node.

Throws:

IloException

Returns:

The objective function value of the solution at the current node.

getValue

protected double getValue(IloNumVar var)
                   throws IloException

Returns the solution value of a variable at the current node.

Throws:

IloException

Parameters:

var - The variable whose current solution value is being queried.

Returns:

The solution value of variable var at the current node.

getValues

protected double[] getValues(IloNumVar[] var)
                      throws IloException

Returns the solution values for an array of variables at the current node.

Throws:

IloException

Parameters:

var - An array of variables whose current solution values are being queried.

Returns:

An array of double values containing the solution values of the specified variables at the current node. If the returned array is called x, x[j] contains the current solution value for the variable var[j].

getValues

protected double[] getValues(IloNumVar[] var,
                 int start,
                 int num)
                      throws IloException

Returns the solution values for a set of variables at the current node.

Throws:

IloException

Parameters:

var - An array containing the variables whose current solution values are being queried.

start - The index of the first variable in var for which to query the current solution values.

num - The number of consecutive variables in var for which to query the current solution values.

Returns:

An array of double values containing the solution values of the specified variables at the current node. If the returned array is called x, x[j] contains the current solution value for the variable var[j+start].

getSlack

protected double getSlack(IloRange rng)
                   throws IloException

Returns the slack value of a constraint for the solution of the continuous relaxation of the current node.

Throws:

IloException

Parameters:

rng - The constraint whose current slack value is being queried.

Returns:

The slack value of constraint rng for the solution of the continuous relaxation of the current node.

getSlacks

protected double[] getSlacks(IloRange[] rng)
                      throws IloException

Returns the slack values of an array of constraints for the solution of the current node.

Throws:

IloException

Parameters:

rng - An array of constraints whose current slack values are being queried.

Returns:

An array of double values containing the slack values of the specified constraints for the solution of the continuous relaxation of the current node. If the returned array is called s, s[i] contains the current slack value for constraint rng[i].

getSlacks

protected double[] getSlacks(IloRange[] rng,
                 int start,
                 int num)
                      throws IloException

Returns the slack values of a set of constraints for the solution of the current node.

Throws:

IloException

Parameters:

rng - An array containing the constraints whose current slack values are being queried.

start - The index of the first constraint in rng for which to query the current slack values.

num - The number of consecutive constraints in rng for which to query the current slack values.

Returns:

An array of double values containing the slack values of the specified constraints for the solution of the continuous relaxation of the current node. If the returned array is called s, s[i] contains the current slack value for constraint rng[i+start].

getValue

protected double getValue(IloNumExpr expr)
                   throws IloException

Returns the value expr takes for the solution of the continuous relaxation of the current node.

Throws:

IloException

Parameters:

expr - The expression for which to evaluate the current solution.

Returns:

The value expr takes for the solution of the continuous relaxation of the current node.

getDownPseudoCost

protected double getDownPseudoCost(IloNumVar var)
                            throws IloException

Returns the pseudo cost for branching down on variable var.

Throws:

IloException

Parameters:

var - The variable whose down pseudo cost is being queried.

Returns:

The pseudo cost for branching down on variable var.

getUpPseudoCost

protected double getUpPseudoCost(IloNumVar var)
                          throws IloException

Returns the pseudo cost for branching up on variable var.

Throws:

IloException

Parameters:

var - The variable whose up pseudo cost is being queried.

Returns:

The pseudo cost for branching up on variable var.

getFeasibility

protected IloCplex.IntegerFeasibilityStatus getFeasibility(IloNumVar var)
                                                    throws IloException

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

Before you query the feasibility of a solution from an instance of SolveCallback, a solution must exist. That is, you must first create the solution by calling the CPLEX optimization method solve, and then you must verify that the method solve generated a solution by checking its return value before you invoke the method getFeasibility.

Throws:

IloException

Parameters:

var - The variable whose integer feasibility status is being queried.

Returns:

The integer feasibility status.

getFeasibilities

protected IloCplex.IntegerFeasibilityStatus[] getFeasibilities(IloNumVar[] var)
                                                        throws IloException

States whether the variables in the specified array are integer feasible, integer infeasible, or implied integer feasible in the current node solution.

Before you query the feasibility of a solution from an instance of SolveCallback, a solution must exist. That is, you must first create the solution by calling the CPLEX optimization method solve, and then you must verify that the method solve generated a solution by checking its return value before you invoke the method getFeasibilities.

Throws:

IloException

Parameters:

var - The array of variables whose integer feasibility status is being queried.

Returns:

An array containing the integer feasibility statuses for the variables in var at the current node. The integer feasibility status of variable var[j] will be returned as element j of the returned array.

getFeasibilities

protected IloCplex.IntegerFeasibilityStatus[] getFeasibilities(IloNumVar[] var,
                                                   int start,
                                                   int num)
                                                        throws IloException

Queries whether the variables specified in the array are integer feasible, integer infeasible, or implied integer feasible in the current node solution.

Before you query the feasibility of a solution from an instance of SolveCallback, a solution must exist. That is, you must first create the solution by calling the CPLEX optimization method solve, and then you must verify that the method solve generated a solution by checking its return value before you invoke the method getFeasibility.

Throws:

IloException

Parameters:

var - An array containing the variables whose integer feasibility status is being queried.

start - The index of the first variable in the array var for which the integer feasibility status is queried.

num - The number of consecutive variables in the array var, for which the integer infeasibility statuses are queried.

Returns:

An array containing the integer feasibility statuses for the specified variables in var at the current node. If the returned array is inf, the feasibility status for the variable var[start+j] will be returned as inf[j].

getSOSFeasibility

protected IloCplex.IntegerFeasibilityStatus getSOSFeasibility(IloSOS1 sos)
                                                       throws IloException

States whether the special ordered set of type 1 is integer feasible, integer infeasible, or implied integer feasible in the current node solution.

Before you query the feasibility of a solution from an instance of SolveCallback, a solution must exist. That is, you must first create the solution by calling the CPLEX optimization method solve, and then you must verify that the method solve generated a solution by checking its return value before you invoke the method getSOSFeasibility.

Throws:

IloException

Parameters:

sos - The SOS1 for which the integer feasibility status is queried.

Returns:

The integer feasibility status for sos.

getSOSFeasibility

protected IloCplex.IntegerFeasibilityStatus getSOSFeasibility(IloSOS2 sos)
                                                       throws IloException

States whether the special ordered set of type 2 is integer feasible, integer infeasible, or implied integer feasible in the current node solution.

Before you query the feasibility of a solution from an instance of SolveCallback, a solution must exist. That is, you must first create the solution by calling the CPLEX optimization method solve, and then you must verify that the method solve generated a solution by checking its return value before you invoke the method getSOSFeasibility.

Throws:

IloException

Parameters:

sos - The SOS2 for which the integer feasibility status is queried.

Returns:

The integer feasibility status for sos.

getNodeData

protected java.lang.Object getNodeData()
                                throws IloException

Returns the user object attached to the current node. User objects can be attached to a node when the node is created with the method IloCplex.BranchCallback.makeBranch in a branch callback.

Throws:

IloException

Returns:

The user object attached to the current node. If no user object is attached to the current node, null will be returned.

setNodeData

protected java.lang.Object setNodeData(java.lang.Object data)
                                throws IloException

Sets the user object attached to the current node.

Throws:

IloException

Parameters:

data - The user object to be attached to the current node.

Returns:

The user object that was previously attached to the current node.