First pass at a feasibility checker.

This is a significant item for JuMP 1.0, but there is debate on how
to define and implement distances for different sets.

See https://github.com/matbesancon/MathOptSetDistances.jl for a WIP
package exploring the options.

This PR also only addresses primal feasibility. See
joaquimg/FeasibilityOptInterface.jl#1
for a WIP attempt at dual feasibility as well.

In future, the _distance_to_set definitions will be merged into MOI.

This PR is more about defining the JuMP-level interface so we can
change internal details without breaking compatibility of JuMP 1.0.

Author: odow

docs/src/reference/solutions.md

@@ -49,4 +49,6 @@ lp_objective_perturbation_range
 lp_rhs_perturbation_range
 lp_sensitivity_report
 SensitivityReport
+
+primal_feasibility_report
 ```

docs/src/solutions.md

@@ -118,10 +118,10 @@ end
 ```
 
 !!! warning
-    Querying solution information after modifying a solved model is undefined 
+    Querying solution information after modifying a solved model is undefined
     behavior, and solvers may throw an error or return incorrect results.
-    Modifications include adding, deleting, or modifying any variable, 
-    objective, or constraint. Instead of modify then query, query the results 
+    Modifications include adding, deleting, or modifying any variable,
+    objective, or constraint. Instead of modify then query, query the results
     first, then modify the problem. For example:
     ```julia
     model = Model(GLPK.Optimizer)
@@ -324,11 +324,11 @@ Functions for querying the solutions, e.g., [`primal_status`](@ref) and
 used to specify which result to return.
 
 !!! warning
-    Even if [`termination_status`](@ref) is `MOI.OPTIMAL`, some of the returned 
+    Even if [`termination_status`](@ref) is `MOI.OPTIMAL`, some of the returned
     solutions may be suboptimal! However, if the solver found at least one
     optimal solution, then `result = 1` will always return an optimal solution.
-    Use [`objective_value`](@ref) to assess the quality of the remaining 
-    solutions. 
+    Use [`objective_value`](@ref) to assess the quality of the remaining
+    solutions.
 
 ```julia
 using JuMP
@@ -353,3 +353,25 @@ for i in 2:result_count(model)
     end
 end
 ```
+
+## Checking feasibility of solutions
+
+To check the feasibility of a primal solution, use
+[`primal_feasibility_report`](@ref). The returned `report` is `nothing` if the
+point is feasible. Otherwise, it is a dictionary mapping the infeasible
+constraint references to the distance between the point and the nearest point in
+the set.
+
+```@example
+using JuMP
+model = Model()
+@variable(model, x >= 1, Int)
+@constraint(model, c1, x <= 1.95)
+point = Dict(x => 2.5)
+report = primal_feasibility_report(model, point)
+```
+
+To use the point from a previous solve, use:
+```julia
+point = Dict(v => value(v) for v in all_variables(model))
+```

src/JuMP.jl

@@ -1109,6 +1109,7 @@ include("lp_sensitivity.jl")
 include("lp_sensitivity2.jl")
 include("callbacks.jl")
 include("file_formats.jl")
+include("feasibility_checker.jl")
 
 # JuMP exports everything except internal symbols, which are defined as those
 # whose name starts with an underscore. Macros whose names start with

src/feasibility_checker.jl

@@ -0,0 +1,77 @@
+#  Copyright 2017, Iain Dunning, Joey Huchette, Miles Lubin, and contributors
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""
+    primal_feasibility_report(
+        model::Model,
+        [point::Dict{VariableRef,Float64}];
+        atol::Float64 = 1e-8,
+    )::Union{Nothing,Dict{Any,Float64}}
+
+Check the primal feasibility of `model` at the point given by the dictionary
+`point` mapping variables to primal values. If a variable is not given in
+`point`, the value is assumed to be `0.0`.
+
+If the point is feasible, this function returns `nothing`. If infeasible, this
+function returns a dictionary mapping the constriant reference of each violated
+constraint to the distance it is from being feasible.
+
+To obtain `point` from a solution of a solved model, use:
+```julia
+point = Dict(v => value(v) for v in all_variables(model))
+```
+"""
+function primal_feasibility_report(
+    model::Model,
+    point::Dict{VariableRef,Float64};
+    atol::Float64 = 1e-8,
+)
+    point_f = x -> get(point, x, 0.0)
+    violated_constraints = Dict{Any,Float64}()
+    for (F, S) in list_of_constraint_types(model)
+        # This loop is not type-stable because `F` and `S` change, but it should
+        # be fine because no one should be using this in performance-critical
+        # code.
+        for con in all_constraints(model, F, S)
+            obj = constraint_object(con)
+            d = _distance_to_set(value(obj.func, point_f), obj.set)
+            if d > atol
+                violated_constraints[con] = d
+            end
+        end
+    end
+    return length(violated_constraints) == 0 ? nothing : violated_constraints
+end
+
+function _distance_to_set(::Any, set::MOI.AbstractSet)
+    error(
+        "Feasibility checker for set type $(typeof(set)) has not been " *
+        "implemented yet."
+    )
+end
+
+function _distance_to_set(x::Float64, set::MOI.LessThan{Float64})
+    return max(x - set.upper, 0.0)
+end
+
+function _distance_to_set(x::Float64, set::MOI.GreaterThan{Float64})
+    return max(set.lower - x, 0.0)
+end
+
+function _distance_to_set(x::Float64, set::MOI.EqualTo{Float64})
+    return abs(set.value - x)
+end
+
+function _distance_to_set(x::Float64, set::MOI.Interval{Float64})
+    return max(x - set.upper, set.lower - x, 0.0)
+end
+
+function _distance_to_set(x::Float64, ::MOI.ZeroOne)
+    return min(abs(x - 0.0), abs(x - 1.0))
+end
+
+function _distance_to_set(x::Float64, ::MOI.Integer)
+    return abs(x - round(Int, x))
+end

test/feasibility_checker.jl

@@ -0,0 +1,80 @@
+#  Copyright 2017, Iain Dunning, Joey Huchette, Miles Lubin, and contributors
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+module TestFeasibilityChecker
+
+using JuMP
+using Test
+
+function test_distance_to_set()
+    @test JuMP._distance_to_set(1.0, MOI.LessThan(2.0)) ≈ 0.0
+    @test JuMP._distance_to_set(1.0, MOI.LessThan(0.5)) ≈ 0.5
+    @test JuMP._distance_to_set(1.0, MOI.GreaterThan(2.0)) ≈ 1.0
+    @test JuMP._distance_to_set(1.0, MOI.GreaterThan(0.5)) ≈ 0.0
+    @test JuMP._distance_to_set(1.0, MOI.EqualTo(2.0)) ≈ 1.0
+    @test JuMP._distance_to_set(1.0, MOI.EqualTo(0.5)) ≈ 0.5
+    @test JuMP._distance_to_set(1.0, MOI.Interval(1.0, 2.0)) ≈ 0.0
+    @test JuMP._distance_to_set(0.5, MOI.Interval(1.0, 2.0)) ≈ 0.5
+    @test JuMP._distance_to_set(2.75, MOI.Interval(1.0, 2.0)) ≈ 0.75
+    @test JuMP._distance_to_set(0.6, MOI.ZeroOne()) ≈ 0.4
+    @test JuMP._distance_to_set(-0.01, MOI.ZeroOne()) ≈ 0.01
+    @test JuMP._distance_to_set(1.01, MOI.ZeroOne()) ≈ 0.01
+    @test JuMP._distance_to_set(0.6, MOI.Integer()) ≈ 0.4
+    @test JuMP._distance_to_set(3.1, MOI.Integer()) ≈ 0.1
+    @test JuMP._distance_to_set(-0.01, MOI.Integer()) ≈ 0.01
+    @test JuMP._distance_to_set(1.01, MOI.Integer()) ≈ 0.01
+end
+
+function test_feasible()
+    model = Model()
+    @variable(model, x, Bin)
+    @variable(model, 0 <= y <= 2, Int)
+    @variable(model, z == 0.5)
+    @constraint(model, x + y + z >= 0.5)
+    @test primal_feasibility_report(model, Dict(z => 0.5)) === nothing
+end
+
+function test_bounds()
+    model = Model()
+    @variable(model, x, Bin)
+    @variable(model, 0 <= y <= 2, Int)
+    @variable(model, z == 0.5)
+    report = primal_feasibility_report(model, Dict(x => 0.1, y => 2.1))
+    @test report[BinaryRef(x)] ≈ 0.1
+    @test report[UpperBoundRef(y)] ≈ 0.1
+    @test report[IntegerRef(y)] ≈ 0.1
+    @test report[FixRef(z)] ≈ 0.5
+    @test length(report) == 4
+end
+
+function test_affine()
+    model = Model()
+    @variable(model, x)
+    @constraint(model, c1, x <= 0.5)
+    @constraint(model, c2, x >= 1.25)
+    @constraint(model, c3, x == 1.1)
+    @constraint(model, c4, 0 <= x <= 0.5)
+    report = primal_feasibility_report(model, Dict(x => 1.0))
+    @test report[c1] ≈ 0.5
+    @test report[c2] ≈ 0.25
+    @test report[c3] ≈ 0.1
+    @test report[c4] ≈ 0.5
+    @test length(report) == 4
+end
+
+function runtests()
+    for name in names(@__MODULE__; all = true)
+        if !startswith("$(name)", "test_")
+            continue
+        end
+        @testset "$(name)" begin
+            getfield(@__MODULE__, name)()
+        end
+    end
+end
+
+end
+
+TestFeasibilityChecker.runtests()