Suffices and Callbacks
Suffices
A mathematical program has a number of suffices which can be used for various purposes. Typical examples are:
To obtain information about the solution process. This information is filled in by the solver at the end of the solution process. These suffixes are presented in this table.
To determine when and how to activate a callback procedure. This information can be filled in between solution steps. See also Implementing Advanced Algorithms for Mathematical Programs where an alternative method for callbacks is presented. These suffixes are presented in this table.
To get statistics of the generated mathematical program. These statistics are determined when the generated mathematical program is constructed. These suffixes are presented in this table.
Suffix |
Meaning |
|---|---|
|
Current objective value |
|
Current incumbent value |
|
Best bound on objective value |
|
Current program status |
|
Current solver status |
|
Current number of iterations |
|
Current number of nodes
( |
|
Current generation time in [second] |
|
Current solution time in [second] |
|
Number of nodes visited by a CP solver |
|
Number of leaf nodes without solution in a CP search tree |
|
Final number of infeasibilities |
|
Final sum of the infeasibilities |
Suffix |
Meaning |
|---|---|
|
Name of callback procedure |
|
Return to callback after this number of iterations |
|
Name of callback procedure to be called after some elapsed time |
|
Name of callback procedure to be called after a status change |
|
Name of callback procedure to be called for every new incumbent |
|
Name of callback procedure to be called to add additional cuts (CPLEX and Gurobi) |
|
Return status of callback |
Suffix |
Meaning |
|---|---|
|
Total number of applied |
|
Number of individual constraints |
|
Number of individual variables |
|
Number of nonzeros |
|
Number of individual integer variables |
|
Number of individual constraints with an activating condition |
|
Number of individual SOS1 constraints |
|
Number of individual SOS2 constraints |
|
Number of individual nonlinear constraints |
|
Number of individual nonlinear variables |
|
Number of nonlinear nonzeros |
Solver callbacks
After each iteration the external solver calls back to the AIMMS system to offer AIMMS the opportunity to take control. AIMMS, in turn, allows you to execute a procedure which is referred to as a callback procedure. Once the callback procedure has finished, the control is returned to the external solver to continue with the next iteration. By including a callback procedure you can perform several tasks such as:
inspect the current status of the solution process,
update one or more model parameters, which can be used, for instance, to provide a graphical overview of the solution process,
retrieve (part of) the current solution, and
abort the solution process, and
You can nominate any procedure as a callback procedure by assigning its
name to the suffix CallbackProcedure of the associated mathematical
program as in:
TransportModel.CallbackProcedure := 'MyCallbackProcedure' ;
Note that values assigned to the suffix CallbackProcedure or any of
the other suffices holding the name of a callback procedure, must be
elements of the predefined set AllProcedures. Therefore, if you
assign a literal procedure name to such a suffix, you should make sure
to quote it, as illustrated in the example above.
When activated
Callback procedures under your control may cause a considerable computational overhead, and should only be activated when necessary. To give you control of the frequency of callbacks, AIMMS provide three separate suffices to trigger a callback procedure. Specifically, a callback procedure can be called
after a specified number of iterations,
after a specified number of seconds,
after a change of status of the solution process, or
at every new incumbent during the solution process of a mixed integer program.
Activated after iterations
With the suffix CallbackIterations you can indicate after how many
iterations the callback procedure specified by the CallbackProcedure
suffix must be called again. If you specify the number 0 (default), no
such callbacks will be made.
Activated after time
With the suffix CallbackTime you specify the name of the callback
procedure to be called when a certain number of seconds has elapsed.
When not specified (the default), no such callbacks are made.
Activated after status change
With the suffix CallbackStatusChange you specify the name of the
callback procedure to be performed when the status of the solution
process changes. When not specified (the default), no such callbacks are
made.
Activated after new incumbent
With the suffix CallbackIncumbent you specify the name of the
callback procedure to be performed when the solver finds a new incumbent
during the solution process of a mixed integer program. When not
specified (the default), no such callbacks are made.
Watch objective values
During a callback procedure you can access various objective values as they are reported by the solver during a mixed integer program through several suffices of the mathematical program at hand. The following suffices provide information about the objective values:
through the suffix
Incumbentyou can obtain the objective value of the best integer solution found so far,through the suffix
BestBoundyou can obtain the best bound on the objective value during the branch-and-bound process, andthrough the suffix
Objectiveyou can obtain the current objective value reported by the solver at the precise time of the callback.
For mixed integer programs the suffix Objective will be meaningless
in most cases during the solution process.
Watch intermediate solution values
In a callback procedure you can access the current solution values of the variables in the mathematical program, and assign these to other identifiers in your model. One possible use of this feature is to store multiple feasible integer solutions of a mixed integer linear program.
The procedure RetrieveCurrentVariableValues
For some solvers there may be a considerable overhead involved to retrieve the current variable values during the running solution process. Therefore, AIMMS will only do so when you explicitly call the procedure
:any:`RetrieveCurrentVariableValues`(VariableSet)
With the VariableSet argument you can specify the subset of the set
AllVariables consisting of all (symbolic) variables for which you
want the current values to be retrieved. When you call this procedure
outside the context of a solver callback procedure, AIMMS will produce a
runtime error.
Adding additional cuts
When you want to add additional cuts during the solution process of a
mixed integer program, you should install a callback procedure to
generate these constraints using the CallbackAddCut suffix. This
procedure is called at every node that has an LP-optimal solution with
an objective function value below the current cutoff and is integer
infeasible. The procedure allows you to add individual constraints using
the GenerateCut(row, local) function. The row argument should
always be a scalar reference to an existing constraint name in your
model. The local argument should be a scalar binary that indicates
whether the cut is a local cut (value 1) or a global one (value 0). The
local argument is an optional argument, and has a default of 1.
Example
Consider a model with the following constraint.
Constraint Triangle_Cut {
IndexDomain : (i1,i2,i3) | (i1 < i2) and (i2 < i3);
Definition : x(i1) + x(i2) + x(i3) - y(i1,i2) - y(i1,i3) - y(i2,i3) <= 1;
}
Then the following piece of code, when specified as the procedure body
of the CallbackAddCut procedure, will only add those triangle cuts
that are violated.
RetrieveCurrentVariableValues(AllVariables);
for ( (i1,i2,i3) | (i1 < i2) and (i2 < i3) ) do
if ( x(i1) + x(i2) + x(i3) - y(i1,i2) - y(i1,i3) - y(i2,i3) > 1 + eps ) then
GenerateCut( Triangle_Cut(i1,i2,i3), 1 );
endif;
endfor;
Aborting the solution process
When you want to abort the solution process, you can set the suffix
CallbackReturnStatus to 'abort' during the execution of your
callback procedure, as in:
TransportModel.CallbackReturnStatus := 'abort' ;
After aborting the process, AIMMS will retrieve the current solution and
set the final solver status to UserInterrupt.
Example
Consider a mathematical program TransportModel which incorporates a
callback procedure. The following callback procedure will abort the
solution process if the total solution time exceeded 1800 seconds, and
if the progress is less than 1% compared to the last nonzero objective
function value.
if ( TransportModel.SolutionTime > 1800 [second] and PreviousObjective and
(TransportModel.Objective - PreviousObjective) < 0.01*PreviousObjective )
then
TransportModel.CallbackReturnStatus := 'abort';
else
PreviousObjective := TransportModel.Objective;
endif;
Solver and program status
Both the ProgramStatus and the SolverStatus suffix take their
value in the predefined set AllSolutionStates presented in
this table.
Program status |
Solver status |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|