Feasible and Infeasible solution callbacks

Author: blegat

docs/src/apireference.md

@@ -77,8 +77,10 @@ submit
 List of submittables
 
 ```@docs
+RejectSolution
 LazyConstraint
 HeuristicSolution
+UserCut
 ```
 
 ## Model Interface
@@ -129,8 +131,8 @@ Silent
 TimeLimitSec
 RawParameter
 AbstractCallback
-LazyCallback
-HeuristicCallback
+FeasibleSolutionCallback
+InfeasibleSolutionCallback
 ```
 
 List of attributes useful for optimizers
@@ -229,8 +231,7 @@ Calls to `get` and `set` should include as an argument a single `VariableIndex`
 VariableName
 VariablePrimalStart
 VariablePrimal
-VariablePrimalAtIntegerNode
-VariablePrimalAtFractionalNode
+CallbackVariablePrimal
 ```
 
 ### Constraints

src/attributes.jl

@@ -407,36 +407,71 @@ end
 
 ## Submittables
 
+"""
+    RejectSolution(callback_data)
+
+Reject feasible solution provided by [`CallbackVariablePrimal`](@ref).
+
+This can be submitted only from the [`FeasibleSolutionCallback`](@ref). The
+field `callback_data` is a solver-specific callback type that is passed as the
+argument to the feasible solution callback.
+"""
+struct RejectSolution{CBDT} <: AbstractSubmittable
+    callback_data::CBDT
+end
+
 """
     LazyConstraint(callback_data)
 
-Lazy constraint `func`-in-`set` submitted as a tuple `(func, set)`. The optimal
+Lazy constraint `func`-in-`set` submitted as `func, set`. The optimal
 solution returned by [`VariablePrimal`](@ref) will satisfy all lazy
 constraints that have been submitted.
 
-This can be submitted only from the lazy callback (that is, the function set to
-[`LazyCallback`](@ref)). The field `callback_data` is a solver-specific
-callback type that is passed as the argument to the lazy callback.
+This can be submitted only from the [`FeasibleSolutionCallback`](@ref). The
+field `callback_data` is a solver-specific callback type that is passed as the
+argument to the feasible solution callback.
 """
-struct LazyConstraint <: AbstractSubmittable
-    callback_data::Any
+struct LazyConstraint{CBDT} <: AbstractSubmittable
+    callback_data::CBDT
 end
 
 """
     HeuristicSolution(callback_data)
 
-Heuristically obtained integer-feasible solutions. The solution is given by a
-`Dict{VariableIndex, Float64}` mapping the variables to their solution value.
+Heuristically obtained feasible solution. The solution is submitted as
+`variables, values` where `values[i]` gives the value of `variables[i]`,
+similarly to [`set`](@ref).
 
-This can be submitted only from the heuristic callback (that is, the function
-set to [`HeuristicCallback`](@ref)). The field `callback_data` is a
-solver-specific callback type that is passed as the argument to the heuristic
-callback.
+This can be submitted only from the [`InfeasibleSolutionCallback`](@ref). 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 reject the provided solution.
 """
-struct HeuristicSolution <: AbstractSubmittable
-    callback_data::Any
+struct HeuristicSolution{CBDT} <: AbstractSubmittable
+    callback_data::CBDT
+end
+
+"""
+    UserCut(callback_data)
+
+Constraint `func`-to-`set` suggested to render the solution given by
+[`CallbackVariablePrimal`](@ref) trivially infeasible. The solution is submitted
+as `func, set`. For instance, for a solution satisfying all constraints except
+[`SingleVariable`](@ref)-in-[`Integer`](@ref) constraints, a
+[`ScalarAffineFunction`](@ref)-in-[`LessThan`](@ref) may be submitted cut it
+off. Note that, as opposed to [`LazyConstraint`](@ref), the provided constraint
+cannot modify the feasible set, the constraint should be redundant, e.g., it
+may be a consequence of affine and integrality constraints.
+
+This can be submitted only from the [`InfeasibleSolutionCallback`](@ref). 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.
+"""
+struct UserCut{CBDT} <: AbstractSubmittable
+    callback_data::CBDT
 end
 
 ## Optimizer attributes
@@ -525,43 +560,97 @@ attributes (i.e, 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`](@ref) error.
 
+Some solvers require a complete solution, others only partial solutions. It's up
+to you to provide the appropriate one. If in doubt, give a complete solution.
+
 The value of the attribute should be a function taking only one argument, that
 is commonly called `callback_data`, that can be used for instance in
-[`LazyCallback`](@ref), [`HeuristicSolution`](@ref).
+[`FeasibleSolutionCallback`](@ref), [`InfeasibleSolutionCallback`](@ref).
 """
 abstract type AbstractCallback <: AbstractOptimizerAttribute end
 
 """
-    LazyCallback() <: AbstractCallback
+    FeasibleSolutionCallback() <: AbstractCallback
 
-The *lazy* callback can be used to submit [`LazyConstraint`](@ref) which are
-added on-demand at integer nodes in the branch and bound tree. Note that there
-is no guarantee that the callback is called at *every* integer primal solution.
+The callback can be used to reject a feasible primal solution by submitting
+[`RejectSolution`](@ref) and/or [`LazyConstraint`](@ref). Note that there
+is no guarantee that the callback is called at *every* feasible primal solution.
 
-The solution at the integer node is accessed through
-[`VariablePrimalAtIntegerNode`](@ref). Trying to access other result
+The feasible primal solution is accessed through
+[`CallbackVariablePrimal`](@ref). Trying to access other result
 attributes will throw [`OptimizeInProgress`](@ref) as discussed in
 [`AbstractCallback`](@ref).
+
+## Examples
+
+```julia
+x = MOI.add_variables(optimizer, 8)
+MOI.submit(optimizer, MOI.FeasibleSolutionCallback(), callback_data -> begin
+    sol = MOI.get(optimizer, MOI.CallbackVariablePrimal(callback_data), x)
+    if MOI.supports(optimizer, MOI.RejectSolution(callback_data))
+        # determine if it should be rejected only if it's supported as it may
+        # be time consuming.
+        if # should reject
+            MOI.submit(optimizer, MOI.RejectSolution(callback_data))
+        end
+    end
+    if MOI.supports(optimizer, MOI.LazyConstraint(callback_data))
+        # determine the lazy constraint only if it's supported as it may be time
+        # consuming.
+        if # should add a lazy constraint
+            func = # computes function
+            set = # computes set
+            MOI.submit(optimizer, MOI.LazyConstraint(callback_data), func, set)
+        end
+    end
+end
+```
 """
-struct LazyCallback <: AbstractCallback end
+struct FeasibleSolutionCallback <: AbstractCallback end
 
 """
-    HeuristicCallback() <: AbstractCallback
+    InfeasibleSolutionCallback() <: AbstractCallback
 
-The *heuristic* callback can be used to submit [`HeuristicSolution`](@ref) at
-fractional (i.e., non-integer) nodes in the branch and bound tree. Note that
-there is not guarantee that the callback is called *everytime* the solver has a
-fractional solution.
+The callback can be used to submit [`HeuristicSolution`](@ref) and/or
+[`UserCut`](@ref) given an infeasible primal solution.
+For instance, it may be called at fractional (i.e., 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 solution at the fractional node is accessed through
-[`VariablePrimalAtFractionalNode`](@ref). Trying to access other result
+The infeasible solution is accessed through
+[`CallbackVariablePrimal`](@ref). Trying to access other result
 attributes will throw [`OptimizeInProgress`](@ref) as discussed in
 [`AbstractCallback`](@ref).
 
-Some solvers require a complete solution, others only partial solutions. It's up
-to you to provide the appropriate one. If in doubt, give a complete solution.
+## Examples
+
+```julia
+x = MOI.add_variables(optimizer, 8)
+MOI.submit(optimizer, MOI.InfeasibleSolutionCallback(), callback_data -> begin
+    sol = MOI.get(optimizer, MOI.CallbackVariablePrimal(callback_data), x)
+    if MOI.supports(optimizer, MOI.HeuristicSolution(callback_data))
+        # determine the heuristic solution only if it it's supported as it may
+        # be time consuming.
+        if # can find a heuristic solution
+            values = # computes heuristic solution
+            MOI.submit(optimizer, MOI.HeuristicSolution(callback_data), x,
+                       values)
+        end
+    end
+    if MOI.supports(optimizer, MOI.UserCut(callback_data))
+        # determine the user cut only if it's supported as it may be time
+        # consuming.
+        if # can find a user cut
+            func = # computes function
+            set = # computes set
+            MOI.submit(optimizer, MOI.UserCut(callback_data), func, set)
+        end
+    end
+end
+```
 """
-struct HeuristicCallback <: AbstractCallback end
+struct InfeasibleSolutionCallback <: AbstractCallback end
 
 ## Model attributes
 
@@ -784,25 +873,13 @@ end
 VariablePrimal() = VariablePrimal(1)
 
 """
-    VariablePrimalAtIntegerNode(callback_data)
-
-A variable attribute for the assignment to some primal variable's value at the
-integer node from which the [`LazyCallback`](@ref) corresponding to
-`callback_data` was called.
-"""
-struct VariablePrimalAtIntegerNode <: AbstractVariableAttribute
-    callback_data::Any
-end
-
-"""
-    VariablePrimalAtFractionalNode(callback_data)
+    CallbackVariablePrimal(callback_data)
 
-A variable attribute for the assignment to some primal variable's value at the
-fractional node from which the [`HeuristicCallback`](@ref) corresponding to
-`callback_data` was called.
+A variable attribute for the assignment to some primal variable's value during
+the callback identified by `callback_data`.
 """
-struct VariablePrimalAtFractionalNode <: AbstractVariableAttribute
-    callback_data::Any
+struct CallbackVariablePrimal{CBDT} <: AbstractVariableAttribute
+    callback_data::CBDT
 end
 
 """