ilog.cplex

Class IloCplex.Callback

java.lang.Object

ilog.cplex.IloCplex.Callback

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

IloCplex.OptimizationCallback, IloCplex.TuningCallback

Enclosing class:

IloCplex

public abstract static class IloCplex.Callback
extends java.lang.Object
implements java.lang.Cloneable

The callback base class.

This class defines the common interface available to all callback classes. A callback is an object with a method main implemented by the user. This method is called by the IloCplex algorithm at specific points during the optimization. For each of these points, CPLEX provides a context or an extension of IloCplex.Callback. To implement and use a particular callback, the user must observe the following steps:

• Select the callback class corresponding to the callback to be implemented, and create an extension of that class.
• Implement the method main for this extension. When doing so, you can use all of the methods defined in the callback class and its base classes.
• If the default implementation of the method clone is not adequate, and if the callback is to be used for parallel optimization, this method also needs to be implemented by the user. Recall that the default clone method performs a shallow copy, so typically a user implementation needs to perform a deep copy for objects that should be local to threads or the user implementation must use the synchronize keyword where synchronization is required.
• Create an instance of the user-written callback class and pass it to IloCplex with the method IloCplex.use.

The next time a solution method is executed on the IloCplex object for which the callback has been set, the method main of the callback will be called each time the corresponding point in the optimization algorithm is reached, for example at each iteration.

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

This class serves two different purposes:

• It is the base class for the legacy callbacks. A legacy callback is implemented by inheritance from any of the descendants of this class and by the user implementation of the main method.
• It provides a namespace for the more generic callback that is implemented by implementation of the IloCplex.Callback.Function interface (more specifically the IloCplex.Callback.Function.invoke(IloCplex.Callback.Context) method) and then using the IloCplex.Callback.Context passed into that function to performs queries and actions.

See Also:

IloCplex.use(IloCplex.Callback)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	IloCplex.Callback.Context Context for the CPLEX callback.
static interface	IloCplex.Callback.Function Interface for CPLEX callbacks.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	abort() Instructs CPLEX to stop the current optimization after the user-written callback finishes.
double	getCplexTime() Returns a time stamp.
double	getDetTime() This method returns a deterministic time stamp in ticks.
protected double	getEndDetTime() This method returns a deterministic time stamp specifying when the solving process terminates.
protected double	getEndTime() This method returns a time stamp specifying when solving process terminates.
protected double	getStartDetTime() This method returns a deterministic time stamp specifying when the solving process started.
protected double	getStartTime() This method returns a time stamp specifying when the solving process started.
protected abstract void	main() The method to be implemented by user callback classes.

Methods inherited from class java.lang.Object

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

Method Detail

main

protected abstract void main()
                      throws IloException

The method to be implemented by user callback classes.

Throws:

IloException

abort

protected void abort()

Instructs CPLEX to stop the current optimization after the user-written callback finishes.

This method can be called from a user-written implementation of a main method to instruct the invoking CPLEX optimizer to stop the current optimization.

After an invocation of this method, it is possible to resume optimization by another invocation of the method solve. In such a case, optimization continues at the node of the search tree where the abort method was called. In fact, any time that solve stops for a reason other than an error, you can resume optimization by re-invoking solve.

In contrast, executing additional callback methods in the callback can lead to unpredictable behavior. For example, callback methods such as IloCplex.SolveCallback.solve or IloCplex.BranchCallback.makeBranch can overwrite the callback status and thus enable the optimization to continue. Therefore, to abort an optimization effectively, a user should exit the callback by one of the following ways:

• Call return immediately after the call of abort.
• Structure the callback so that it calls no additional methods of IloCplex.Callback and its subclasses after abort.

getCplexTime

public double getCplexTime()
                    throws IloException

Returns a time stamp.

To measure time spent between a starting point and ending point of an operation, take the time stamp at the starting point; take the time stamp at the ending point; subtract the starting time stamp from the ending time stamp to get elapsed time in seconds.

This computation measures either wall clock time (also known as real time) or CPU time, depending on the setting of the clock type parameter ClockType.

The absolute value of the time stamp is not meaningful.

Throws:

IloException

getDetTime

public double getDetTime()
                  throws IloException

This method returns a deterministic time stamp in ticks.

To measure deterministic time spent between a starting point and ending point of an operation, take the time stamp at the starting point; take the time stamp at the ending point; subtract the starting time stamp from the ending time stamp to get elapsed time in deterministic ticks.

The absolute value of a deterministic time stamp is not meaningful.

Throws:

IloException

getStartTime

protected double getStartTime()
                       throws IloException

This method returns a time stamp specifying when the solving process started.

To compute elapsed time in seconds, subtract the result of getCplexTime from the result of this method.

The absolute value of the time stamp is not meaningful.

Throws:

IloException

getStartDetTime

protected double getStartDetTime()
                          throws IloException

This method returns a deterministic time stamp specifying when the solving process started.

To compute elapsed time in deterministic ticks, subtract the result of getDetTime from the result of this method.

The absolute value of a deterministic time stamp is not meaningful.

Throws:

IloException

getEndTime

protected double getEndTime()
                     throws IloException

This method returns a time stamp specifying when solving process terminates.

To compute remaining time in seconds, subtract the result of IloCplex.getCplexTime from the result of this method. This computation yields either wall clock time (also known as real time) or CPU time, depending on the clock type set by the parameter ClockType.

The absolute value of the time stamp is not meaningful.

Throws:

IloException

getEndDetTime

protected double getEndDetTime()
                        throws IloException

This method returns a deterministic time stamp specifying when the solving process terminates.

To compute remaining time in deterministic ticks, subtract the result of IloCplex.getDetTime from the result of this method.

The absolute value of the time stamp is not meaningful.

Throws:

IloException