ilog.cplex

Class IloCplex.HeuristicCallback

java.lang.Object

ilog.cplex.IloCplex.Callback

ilog.cplex.IloCplex.OptimizationCallback

ilog.cplex.IloCplex.MIPInfoCallback

ilog.cplex.IloCplex.MIPCallback

ilog.cplex.IloCplex.ControlCallback

ilog.cplex.IloCplex.HeuristicCallback

All Implemented Interfaces:

java.lang.Cloneable

Enclosing class:

IloCplex

public abstract static class IloCplex.HeuristicCallback
extends IloCplex.ControlCallback

Base class for user-written callbacks injecting integer-feasible solutions during 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 user-written callbacks allowing you to inject integer-feasible solutions during the branch-and-cut search. During branching, the heuristic callback is called after each node subproblem has been solved, including any cuts that may have been newly generated. Before branching, at the root node, the heuristic callback is also called before each round of cuts is added to the problem and re-solved.

This callback class also provides support for implementing simplex-based heuristics for constructing solutions, by allowing you to change the bounds of variables and re-solve the node relaxation. Changing the bounds in the heuristic callback has no effect on the search after the callback has completed. This callback will be called after the node relaxation (including all cuts generated at that node) has been solved.

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

Modifier	Constructor and Description
protected	IloCplex.HeuristicCallback() Constructor for user-written heuristic callbacks.

Method Summary

Methods

Modifier and Type	Method and Description
protected IloCplex.CplexStatus	getCplexStatus() Returns the CPLEX status of the current node.
protected IloCplex.Status	getStatus() Returns the solution status for the current node.
boolean	isDualFeasible() Returns true if a dual feasible solution is available for the current node.
boolean	isPrimalFeasible() Returns true if a primal feasible solution is available for the current node.
protected void	setBounds(IloNumVar[] var, double[] lb, double[] ub) Changes the upper and lower bounds of variables in the array, provided the specified variables have not been removed by presolve.
protected void	setBounds(IloNumVar[] var, double[] lb, double[] ub, int start, int num) Changes the upper and lower bounds of the specified variables in the array var, provided a specified variable has not been removed by presolve.
protected void	setBounds(IloNumVar var, double lb, double ub) Changes the upper and lower bounds of the specified variable, provided the variable has not been removed by presolve.
protected void	setSolution(IloNumVar[] vars, double[] vals) Injects a solution to be used as the potential new incumbent.
protected void	setSolution(IloNumVar[] vars, double[] vals, double obj) Injects a solution to be used as the potential new incumbent.
protected void	setSolution(IloNumVar[] vars, double[] vals, int start, int num) Injects a solution to be used as the potential new incumbent from an array that may possibly contain other elements.
protected boolean	solve() Solves the current node relaxation using the default algorithm.
protected boolean	solve(int alg) Solves the current node relaxation using a chosen algorithm.

Methods inherited from class ilog.cplex.IloCplex.ControlCallback

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

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

protected IloCplex.HeuristicCallback()

Constructor for user-written heuristic callbacks.

This constructor can be called only to construct objects of derived user-written callback classes, but not to construct HeuristicCallback objects directly.

Method Detail

setBounds

protected void setBounds(IloNumVar var,
             double lb,
             double ub)
                  throws IloException

Changes the upper and lower bounds of the specified variable, provided the variable has not been removed by presolve.

For the variable var, this method sets its upper bound to the corresponding value ub and its lower bound to the value lb. Setting bounds has no effect beyond the scope of the current invocation of the callback.

When using this method, you must avoid changing the bounds of a variable that has been removed by presolve. To check whether presolve is off, consider the parameter IloCplex.BooleanParam.PreInd. Alternatively, you can check whether a particular variable has been removed by presolve by checking the status of the variable. To do so, call IloCplex.ControlCallback.getFeasibilities. A variable that has been removed by presolve will have the status ImpliedFeasible.

Calling this method invalidates any solution currently stored in the callback. Consequently, a subsequent invocation of getFeasibilities, getValues or similar methods throws an exception after you call unless you re-calculate a new solution satisfying the new bounds by means of the method solve.

Throws:

IloException

Parameters:

var - The variable whose bounds are to be changed.

lb - The lower bound of var to be changed.

ub - The upper bound of var to be changed.

setBounds

protected void setBounds(IloNumVar[] var,
             double[] lb,
             double[] ub)
                  throws IloException

Changes the upper and lower bounds of variables in the array, provided the specified variables have not been removed by presolve.

For each variable in the array var, this method sets its upper bound to the corresponding value in the array ub and its lower bound to the corresponding value in the array lb. Setting bounds has no effect beyond the scope of the current invocation of the callback.

When using this method, you must avoid changing the bounds of a variable that has been removed by presolve. To check whether presolve is off, consider the parameter IloCplex.BooleanParam.PreInd. Alternatively, you can check whether a particular variable has been removed by presolve by checking the status of the variable. To do so, call IloCplex.ControlCallback.getFeasibilities. A variable that has been removed by presolve will have the status ImpliedFeasible.

Calling this method invalidates any solution currently stored in the callback. Consequently, a subsequent invocation of getFeasibilities, getValues or similar methods throws an exception after you call unless you re-calculate a new solution satisfying the new bounds by means of the method solve.

Throws:

IloException

Parameters:

var - The array of variables for which the bounds are to be changed.

lb - The array of lower bounds to be set. The lower bound of variable var[j] will be set to lb[j].

ub - The array of upper bounds to be set. The upper bound of variable var[j] will be set to ub[j].

setBounds

protected void setBounds(IloNumVar[] var,
             double[] lb,
             double[] ub,
             int start,
             int num)
                  throws IloException

Changes the upper and lower bounds of the specified variables in the array var, provided a specified variable has not been removed by presolve.

For each variable selected from array var, this method sets its upper bound to the corresponding value in the array ub and its lower bound to the corresponding value in the array lb. Setting bounds has no effect beyond the scope of the current invocation of the callback.

When using this method, you must avoid changing the bounds of a variable that has been removed by presolve. To check whether presolve is off, consider the parameter IloCplex.BooleanParam.PreInd. Alternatively, you can check whether a particular variable has been removed by presolve by checking the status of the variable. To do so, call IloCplex.ControlCallback.getFeasibilities. A variable that has been removed by presolve will have the status ImpliedFeasible.

Calling this method invalidates any solution currently stored in the callback. Consequently, a subsequent invocation of getFeasibilities, getValues or similar methods throws an exception after you call unless you re-calculate a new solution satisfying the new bounds by means of the method solve.

Throws:

IloException

Parameters:

var - The array containing the variables for which the bounds are to be changed.

lb - The array containing the lower bounds to be set. The lower bound of variable var[j] will be set to lb[j].

ub - The array containing the upper bounds to be set. The upper bound of variable var[j] will be set to ub[j].

start - The index of the first variable in var for which the bounds are to be set.

num - The number of consecutive variables in var for which the bounds are to be set.

solve

protected boolean solve(int alg)
                 throws IloException

Solves the current node relaxation using a chosen algorithm.

This method can be used to solve the current node, usually after some bounds have been changed, for example, by the method setBounds. The algorithm alg will be used to solve the node.

Throws:

IloException

Parameters:

alg - The algorithm to use to solve the node relaxation.

Returns:

This method returns true if a feasible solution has been found and false otherwise.

See Also:

IloCplex.Algorithm

solve

protected boolean solve()
                 throws IloException

Solves the current node relaxation using the default algorithm.

This method can be used to solve the current node, usually after some bounds have been changed, for example, by the method setBounds.

Throws:

IloException

Returns:

This method returns true if a feasible solution has been found and false otherwise.

See Also:

IloCplex.Algorithm

getStatus

protected IloCplex.Status getStatus()
                             throws IloException

Returns the solution status for the current node.

This method returns the status of the solution found by the instance of IloCplex at the current node during the last call to the method IloCplex.HeuristicCallback.solve (which may have been called directly in the callback or by IloCplex when processing the node just before the callback is called).

Throws:

IloException

See Also:

IloCplex.Status

getCplexStatus

protected IloCplex.CplexStatus getCplexStatus()
                                       throws IloException

Returns the CPLEX status of the current node.

This method returns the IloCplex.CplexStatus of the solution found by the instance of IloCplex at the current node during the most recent call to the method IloCplex.HeuristicCallback.solve (which may have been called directly in the callback or by IloCplex when it was processing the node just before the callback was called).

Throws:

IloException

See Also:

IloCplex.CplexStatus

isDualFeasible

public boolean isDualFeasible()
                       throws IloException

Returns true if a dual feasible solution is available for the current node.

If false is returned, the solution may still be dual feasible, but the algorithm did not determine the feasibility before it terminated.

Throws:

IloException

isPrimalFeasible

public boolean isPrimalFeasible()
                         throws IloException

Returns true if a primal feasible solution is available for the current node.

If false is returned, the solution may still be primal feasible, but the algorithm did not determine the feasibility before it terminated.

Throws:

IloException

setSolution

protected void setSolution(IloNumVar[] vars,
               double[] vals,
               int start,
               int num)
                    throws IloException

Injects a solution to be used as the potential new incumbent from an array that may possibly contain other elements.

The injected solution is specified by providing solution values for all variables in the model. The array used to specify the values may contain more elements; in that case, use the argument start to specify the starting element and the argument num to specify the number of consecutive elements to use.

If a user heuristic is successful in finding a new candidate for an incumbent, it can be passed to IloCplex by the method setSolution. IloCplex analyzes the solution and, if it is both feasible and better than the current incumbent, IloCplex uses it as the new incumbent. A solution is specified using arrays vars and vals, where vals[i] specifies the solution value for vars[i].

Do not call this method multiple times. Calling it again overwrites any previously specified solution.

Throws:

IloException

Parameters:

vars - An array containing variables whose solution values are specified.

vals - An array containing the solution values for the variables specified in vars. vals[j] specifies the solution value for vars[j] for j in start through start+num-1.

start - The index of the first element to consider in arrays vars and vals.

num - The number of consecutive elements to consider in arrays vars and vals.

setSolution

protected void setSolution(IloNumVar[] vars,
               double[] vals)
                    throws IloException

Injects a solution to be used as the potential new incumbent.

The injected solution is specified by providing solution values for all variables. If a user heuristic is successful in finding a new candidate for an incumbent, it can be passed to IloCplex by the method setSolution. IloCplex analyzes the solution and, if it is both feasible and better than the current incumbent, uses it as the new incumbent. A solution is specified using arrays vars and vals, where vals[i] specifies the solution value for vars[i].

Do not call this method multiple times. Calling it again overwrites any previously specified solution.

Throws:

IloException

Parameters:

vars - An array of variables whose solution values are specified.

vals - An array containing the solution values for the variables specified in vars. vals[j] specifies the solution value for vars[j].

setSolution

protected void setSolution(IloNumVar[] vars,
               double[] vals,
               double obj)
                    throws IloException

Injects a solution to be used as the potential new incumbent.

The injected solution is specified by providing solution values for all variables. If a user heuristic is successful in finding a new candidate for an incumbent, it can be passed to IloCplex by the method setSolution. IloCplex analyzes the solution and, if it is both feasible and better than the current incumbent, uses it as the new incumbent. A solution is specified using arrays vars and vals, where vals[i] specifies the solution value for vars[i].

Do not call this method multiple times. Calling it again overwrites any previously specified solution.

Throws:

IloException

Parameters:

vars - An array of variables whose solution values are specified.

vals - An array containing the solution values for the variables specified in vars. vals[j] specifies the solution value for vars[j].

obj - The objective function value of the injected solution. The value must be accurate because IloCplex does not verify the solution value but uses it as is. If there is any uncertainty about its accuracy, use the corresponding method without the obj argument instead. This argument allows you to avoid the computational overhead of having IloCplex recompute the objective function value for the injected solution.