Callbacks
MathOptInterface.AbstractCallback
— Typeabstract type AbstractCallback <: AbstractModelAttribute end
Abstract type for a model attribute representing a callback function. The value set to subtypes of AbstractCallback
is a function that may be called during optimize!
. As optimize!
is in progress, the result attributes (that is, the attributes attr
such that is_set_by_optimize(attr)
) may not be accessible from the callback, hence trying to get result attributes might throw a OptimizeInProgress
error.
At most one callback of each type can be registered. If an optimizer already has a function for a callback type, and the user registers a new function, then the old one is replaced.
The value of the attribute should be a function taking only one argument, commonly called callback_data
, that can be used for instance in LazyConstraintCallback
, HeuristicCallback
and UserCutCallback
.
MathOptInterface.AbstractSubmittable
— TypeAbstractSubmittable
Abstract supertype for objects that can be submitted to the model.
MathOptInterface.submit
— Functionsubmit(
optimizer::AbstractOptimizer,
sub::AbstractSubmittable,
values...,
)::Nothing
Submit values
to the submittable sub
of the optimizer optimizer
.
An UnsupportedSubmittable
error is thrown if model
does not support the attribute attr
(see supports
) and a SubmitNotAllowed
error is thrown if it supports the submittable sub
but it cannot be submitted.
Attributes
MathOptInterface.CallbackNodeStatus
— TypeCallbackNodeStatus(callback_data)
An optimizer attribute describing the (in)feasibility of the primal solution available from CallbackVariablePrimal
during a callback identified by callback_data
.
Returns a CallbackNodeStatusCode
Enum.
MathOptInterface.CallbackVariablePrimal
— TypeCallbackVariablePrimal(callback_data)
A variable attribute for the assignment to some primal variable's value during the callback identified by callback_data
.
MathOptInterface.CallbackNodeStatusCode
— TypeCallbackNodeStatusCode
An Enum of possible return values from calling get
with CallbackNodeStatus
.
Values
Possible values are:
CALLBACK_NODE_STATUS_INTEGER
: the primal solution available fromCallbackVariablePrimal
is integer feasible.CALLBACK_NODE_STATUS_FRACTIONAL
: the primal solution available fromCallbackVariablePrimal
is integer infeasible.CALLBACK_NODE_STATUS_UNKNOWN
: the primal solution available fromCallbackVariablePrimal
might be integer feasible or infeasible.
MathOptInterface.CALLBACK_NODE_STATUS_INTEGER
— ConstantCALLBACK_NODE_STATUS_INTEGER::CallbackNodeStatusCode
An instance of the CallbackNodeStatusCode
enum.
CALLBACK_NODE_STATUS_INTEGER
: the primal solution available from CallbackVariablePrimal
is integer feasible.
MathOptInterface.CALLBACK_NODE_STATUS_FRACTIONAL
— ConstantCALLBACK_NODE_STATUS_FRACTIONAL::CallbackNodeStatusCode
An instance of the CallbackNodeStatusCode
enum.
CALLBACK_NODE_STATUS_FRACTIONAL
: the primal solution available from CallbackVariablePrimal
is integer infeasible.
MathOptInterface.CALLBACK_NODE_STATUS_UNKNOWN
— ConstantCALLBACK_NODE_STATUS_UNKNOWN::CallbackNodeStatusCode
An instance of the CallbackNodeStatusCode
enum.
CALLBACK_NODE_STATUS_UNKNOWN
: the primal solution available from CallbackVariablePrimal
might be integer feasible or infeasible.
Lazy constraints
MathOptInterface.LazyConstraintCallback
— TypeLazyConstraintCallback() <: AbstractCallback
The callback can be used to reduce the feasible set given the current primal solution by submitting a LazyConstraint
. For instance, it may be called at an incumbent of a mixed-integer problem. Note that there is no guarantee that the callback is called at every feasible primal solution.
The current primal solution is accessed through CallbackVariablePrimal
. Trying to access other result attributes will throw OptimizeInProgress
as discussed in AbstractCallback
.
Examples
x = MOI.add_variables(optimizer, 8)
MOI.set(optimizer, MOI.LazyConstraintCallback(), callback_data -> begin
sol = MOI.get(optimizer, MOI.CallbackVariablePrimal(callback_data), x)
if # should add a lazy constraint
func = # computes function
set = # computes set
MOI.submit(optimizer, MOI.LazyConstraint(callback_data), func, set)
end
end)
MathOptInterface.LazyConstraint
— TypeLazyConstraint(callback_data)
Lazy constraint func
-in-set
submitted as func, set
. The optimal solution returned by VariablePrimal
will satisfy all lazy constraints that have been submitted.
This can be submitted only from the LazyConstraintCallback
. The field callback_data
is a solver-specific callback type that is passed as the argument to the feasible solution callback.
Examples
Suppose x
and y
are VariableIndex
s of optimizer
. To add a LazyConstraint
for 2x + 3y <= 1
, write
func = 2.0x + 3.0y
set = MOI.LessThan(1.0)
MOI.submit(optimizer, MOI.LazyConstraint(callback_data), func, set)
inside a LazyConstraintCallback
of data callback_data
.
User cuts
MathOptInterface.UserCutCallback
— TypeUserCutCallback() <: AbstractCallback
The callback can be used to submit UserCut
given the current primal solution. For instance, it may be called at fractional (that is, non-integer) nodes in the branch and bound tree of a mixed-integer problem. Note that there is not guarantee that the callback is called everytime the solver has an infeasible solution.
The infeasible solution is accessed through CallbackVariablePrimal
. Trying to access other result attributes will throw OptimizeInProgress
as discussed in AbstractCallback
.
Examples
x = MOI.add_variables(optimizer, 8)
MOI.set(optimizer, MOI.UserCutCallback(), callback_data -> begin
sol = MOI.get(optimizer, MOI.CallbackVariablePrimal(callback_data), x)
if # can find a user cut
func = # computes function
set = # computes set
MOI.submit(optimizer, MOI.UserCut(callback_data), func, set)
end
end
MathOptInterface.UserCut
— TypeUserCut(callback_data)
Constraint func
-to-set
suggested to help the solver detect the solution given by CallbackVariablePrimal
as infeasible. The cut is submitted as func, set
. Typically CallbackVariablePrimal
will violate integrality constraints, and a cut would be of the form ScalarAffineFunction
-in-LessThan
or ScalarAffineFunction
-in-GreaterThan
. Note that, as opposed to LazyConstraint
, the provided constraint cannot modify the feasible set, the constraint should be redundant, for example, it may be a consequence of affine and integrality constraints.
This can be submitted only from the UserCutCallback
. The field callback_data
is a solver-specific callback type that is passed as the argument to the infeasible solution callback.
Note that the solver may silently ignore the provided constraint.
Heuristic solutions
MathOptInterface.HeuristicCallback
— TypeHeuristicCallback() <: AbstractCallback
The callback can be used to submit HeuristicSolution
given the current primal solution. For example, it may be called at fractional (that is, non-integer) nodes in the branch and bound tree of a mixed-integer problem. Note that there is no guarantee that the callback is called every time the solver has an infeasible solution.
The current primal solution is accessed through CallbackVariablePrimal
. Trying to access other result attributes will throw OptimizeInProgress
as discussed in AbstractCallback
.
Examples
x = MOI.add_variables(optimizer, 8)
MOI.set(optimizer, MOI.HeuristicCallback(), callback_data -> begin
sol = MOI.get(optimizer, MOI.CallbackVariablePrimal(callback_data), x)
if # can find a heuristic solution
values = # computes heuristic solution
MOI.submit(optimizer, MOI.HeuristicSolution(callback_data), x,
values)
end
end
MathOptInterface.HeuristicSolution
— TypeHeuristicSolution(callback_data)
Heuristically obtained feasible solution. The solution is submitted as variables, values
where values[i]
gives the value of variables[i]
, similarly to set
. The submit
call returns a HeuristicSolutionStatus
indicating whether the provided solution was accepted or rejected.
This can be submitted only from the HeuristicCallback
. The field callback_data
is a solver-specific callback type that is passed as the argument to the heuristic callback.
Some solvers require a complete solution, others only partial solutions.
MathOptInterface.HeuristicSolutionStatus
— TypeHeuristicSolutionStatus
An Enum of possible return values for submit
with HeuristicSolution
. This informs whether the heuristic solution was accepted or rejected.
Values
Possible values are:
HEURISTIC_SOLUTION_ACCEPTED
: The heuristic solution was acceptedHEURISTIC_SOLUTION_REJECTED
: The heuristic solution was rejectedHEURISTIC_SOLUTION_UNKNOWN
: No information available on the acceptance
MathOptInterface.HEURISTIC_SOLUTION_ACCEPTED
— ConstantHEURISTIC_SOLUTION_ACCEPTED::HeuristicSolutionStatus
An instance of the HeuristicSolutionStatus
enum.
HEURISTIC_SOLUTION_ACCEPTED
: The heuristic solution was accepted
MathOptInterface.HEURISTIC_SOLUTION_REJECTED
— ConstantHEURISTIC_SOLUTION_REJECTED::HeuristicSolutionStatus
An instance of the HeuristicSolutionStatus
enum.
HEURISTIC_SOLUTION_REJECTED
: The heuristic solution was rejected
MathOptInterface.HEURISTIC_SOLUTION_UNKNOWN
— ConstantHEURISTIC_SOLUTION_UNKNOWN::HeuristicSolutionStatus
An instance of the HeuristicSolutionStatus
enum.
HEURISTIC_SOLUTION_UNKNOWN
: No information available on the acceptance