Merge pull request #1004 from JuliaOpt/bl/supports_constrained_variable

Add supports_constrained_variable(s)

Author: blegat

docs/src/apimanual.md

@@ -864,7 +864,7 @@ read!(io, src_2)
 ### Duals
 
 Conic duality is the starting point for MOI's duality conventions. When all functions are affine (or coordinate projections), and all constraint sets are closed convex cones, the model may be called a conic optimization problem.
-For conic-form minimization problems, the primal is:
+For a minimization problem in geometric conic form, the primal is:
 
 ```math
 \begin{align}
@@ -874,7 +874,7 @@ For conic-form minimization problems, the primal is:
 \end{align}
 ```
 
-and the dual is:
+and the dual is a maximization problem in standard conic form:
 
 ```math
 \begin{align}
@@ -888,7 +888,7 @@ and the dual is:
 
 where each ``\mathcal{C}_i`` is a closed convex cone and ``\mathcal{C}_i^*`` is its dual cone.
 
-For conic-form maximization problems, the primal is:
+For a maximization problem in geometric conic form, the primal is:
 ```math
 \begin{align}
 & \max_{x \in \mathbb{R}^n} & a_0^T x + b_0
@@ -897,7 +897,7 @@ For conic-form maximization problems, the primal is:
 \end{align}
 ```
 
-and the dual is:
+and the dual is a minimization problem in standard conic form:
 
 ```math
 \begin{align}
@@ -1052,7 +1052,7 @@ The `Bridges.Variable.Vectorize` is the bridge optimizer that applies the
 the optimizer
 ```jldoctest; setup=:(optimizer = MOI.Utilities.Model{Float64}())
 bridged_optimizer = MOI.Bridges.Variable.Vectorize{Float64}(optimizer)
-MOI.supports_constraint(bridged_optimizer, MOI.SingleVariable, MOI.GreaterThan{Float64})
+MOI.supports_add_constrained_variable(bridged_optimizer, MOI.GreaterThan{Float64})
 
 # output
 
@@ -1127,25 +1127,27 @@ MOI.set(model, MyPackage.PrintLevel(), 0)
 
 ### Supported constrained variables and constraints
 
-The solver interface should only implement support for constrained variables
-(see [`add_constrained_variable`](@ref)/[`add_constrained_variables`](@ref))
-or constraints that directly map to a structure exploited by the solver
-algorithm. There is no need to add support for additional types, this is
-handled by the [Automatic reformulation](@ref). Furthermore, this allows
+The solver interface should only implement support for support for variables
+constrained on creation (see
+[`add_constrained_variable`](@ref)/[`add_constrained_variables`](@ref)) or
+constraints that directly map to a structure exploited by the solver algorithm.
+There is no need to add support for additional types, this is handled by the
+[Automatic reformulation](@ref). Furthermore, this allows
 [`supports_constraint`](@ref) to indicate which types are exploited by the
 solver and hence allows layers such as [`Bridges.LazyBridgeOptimizer`](@ref)
 to accurately select the most appropriate transformations.
 
 As [`add_constrained_variable`](@ref) (resp. [`add_constrained_variables`](@ref))
 falls back to [`add_variable`](@ref) (resp. [`add_variables`](@ref)) followed by
 [`add_constraint`](@ref), there is no need to implement this function
-if `model` supports creating free variables. However, if `model` does not
-support creating free variables, then it should only implement
-[`add_constrained_variable`](@ref) and not [`add_variable`](@ref) nor
-[`add_constraint`](@ref) for [`SingleVariable`](@ref)-in-`typeof(set)`.
-In addition, it should implement `supports_constraint(::Optimizer,
-::Type{VectorOfVariables}, ::Type{Reals})` and return `false` so that free
-variables are bridged, see [`supports_constraint`](@ref).
+if `model` does not require that variables be constrained when they are created.
+However, if `model` requires that variables be constrained when they're created,
+then it should only implement [`add_constrained_variable`](@ref) and not
+[`add_variable`](@ref) nor [`add_constraint`](@ref) for
+[`SingleVariable`](@ref)-in-`typeof(set)`. In addition, it should implement
+`supports_add_constrained_variables(::Optimizer, ::Type{Reals})` and return
+`false` so that these variables are bridged, see
+[`supports_add_constrained_variables`](@ref).
 
 ### Handling duplicate coefficients
 

docs/src/apireference.md

@@ -224,6 +224,8 @@ add_variable
 add_variables
 add_constrained_variable
 add_constrained_variables
+supports_add_constrained_variable
+supports_add_constrained_variables
 ```
 
 List of attributes associated with variables. [category AbstractVariableAttribute]

src/Test/contconic.jl

@@ -103,7 +103,7 @@ function _lin2test(model::MOI.ModelLike, config::TestConfig, vecofvars::Bool)
     @test MOI.supports(model, MOI.ObjectiveSense())
     if vecofvars
         @test MOI.supports_constraint(model, MOI.VectorOfVariables, MOI.Nonnegatives)
-        @test MOI.supports_constraint(model, MOI.VectorOfVariables, MOI.Nonpositives)
+        @test MOI.supports_add_constrained_variables(model, MOI.Nonpositives)
         @test MOI.supports_constraint(model, MOI.VectorOfVariables, MOI.Zeros)
     else
         @test MOI.supports_constraint(model, MOI.VectorAffineFunction{Float64}, MOI.Nonnegatives)
@@ -258,7 +258,7 @@ function lin4test(model::MOI.ModelLike, config::TestConfig)
     @test MOI.supports(model, MOI.ObjectiveFunction{MOI.ScalarAffineFunction{Float64}}())
     @test MOI.supports(model, MOI.ObjectiveSense())
     @test MOI.supports_constraint(model, MOI.VectorAffineFunction{Float64}, MOI.Nonnegatives)
-    @test MOI.supports_constraint(model, MOI.VectorOfVariables, MOI.Nonpositives)
+    @test MOI.supports_add_constrained_variables(model, MOI.Nonpositives)
 
     MOI.empty!(model)
     @test MOI.is_empty(model)
@@ -586,11 +586,11 @@ function _soc1test(model::MOI.ModelLike, config::TestConfig, vecofvars::Bool)
     @test MOI.supports(model, MOI.ObjectiveFunction{MOI.ScalarAffineFunction{Float64}}())
     @test MOI.supports(model, MOI.ObjectiveSense())
     if vecofvars
-        @test MOI.supports_constraint(model, MOI.VectorOfVariables, MOI.Zeros)
+        @test MOI.supports_add_constrained_variables(model, MOI.SecondOrderCone)
     else
-        @test MOI.supports_constraint(model, MOI.VectorAffineFunction{Float64}, MOI.Zeros)
+        @test MOI.supports_constraint(model, MOI.VectorAffineFunction{Float64}, MOI.SecondOrderCone)
     end
-    @test MOI.supports_constraint(model, MOI.VectorOfVariables,MOI.SecondOrderCone)
+    @test MOI.supports_constraint(model, MOI.VectorOfVariables, MOI.Zeros)
 
     MOI.empty!(model)
     @test MOI.is_empty(model)
@@ -875,7 +875,7 @@ function _rotatedsoc1test(model::MOI.ModelLike, config::TestConfig, abvars::Bool
     @test MOI.supports(model, MOI.ObjectiveSense())
     if abvars
         @test MOI.supports_constraint(model, MOI.SingleVariable, MOI.EqualTo{Float64})
-        @test MOI.supports_constraint(model, MOI.VectorOfVariables, MOI.RotatedSecondOrderCone)
+        @test MOI.supports_add_constrained_variables(model, MOI.RotatedSecondOrderCone)
     else
         @test MOI.supports_constraint(model, MOI.VectorAffineFunction{Float64}, MOI.RotatedSecondOrderCone)
     end
@@ -977,7 +977,7 @@ function rotatedsoc2test(model::MOI.ModelLike, config::TestConfig)
     @test MOI.supports_constraint(model, MOI.SingleVariable,MOI.EqualTo{Float64})
     @test MOI.supports_constraint(model, MOI.SingleVariable,MOI.LessThan{Float64})
     @test MOI.supports_constraint(model, MOI.SingleVariable,MOI.GreaterThan{Float64})
-    @test MOI.supports_constraint(model, MOI.VectorOfVariables,MOI.RotatedSecondOrderCone)
+    @test MOI.supports_add_constrained_variables(model, MOI.RotatedSecondOrderCone)
 
     MOI.empty!(model)
     @test MOI.is_empty(model)
@@ -1045,7 +1045,7 @@ function rotatedsoc3test(model::MOI.ModelLike, config::TestConfig; n=2, ub=3.0)
     @test MOI.supports(model, MOI.ObjectiveFunction{MOI.ScalarAffineFunction{Float64}}())
     @test MOI.supports(model, MOI.ObjectiveSense())
     @test MOI.supports_constraint(model, MOI.SingleVariable, MOI.EqualTo{Float64})
-    @test MOI.supports_constraint(model, MOI.VectorOfVariables, MOI.Nonnegatives)
+    @test MOI.supports_add_constrained_variables(model, MOI.Nonnegatives)
     @test MOI.supports_constraint(model, MOI.SingleVariable, MOI.GreaterThan{Float64})
     @test MOI.supports_constraint(model, MOI.SingleVariable, MOI.LessThan{Float64})
     @test MOI.supports_constraint(model, MOI.VectorAffineFunction{Float64}, MOI.RotatedSecondOrderCone)
@@ -1152,7 +1152,7 @@ function rotatedsoc4test(model::MOI.ModelLike, config::TestConfig; n=2, ub=3.0)
     @test MOI.supports(model, MOI.ObjectiveFunction{MOI.ScalarAffineFunction{Float64}}())
     @test MOI.supports(model, MOI.ObjectiveSense())
     @test MOI.supports_constraint(model, MOI.ScalarAffineFunction{Float64}, MOI.LessThan{Float64})
-    @test MOI.supports_constraint(model, MOI.VectorOfVariables, MOI.RotatedSecondOrderCone)
+    @test MOI.supports_add_constrained_variables(model, MOI.RotatedSecondOrderCone)
 
     MOI.empty!(model)
     @test MOI.is_empty(model)

src/constraints.jl

@@ -27,9 +27,16 @@ If `model` does not support free variables, it should not implement
 this method and return `false`. This allows free variables to be bridged as the
 sum of a nonnegative and a nonpositive variables.
 """ # Implemented as only one method to avoid ambiguity
-function supports_constraint(::ModelLike, F::Type{<:AbstractFunction},
+function supports_constraint(model::ModelLike, F::Type{<:AbstractFunction},
                              S::Type{<:AbstractSet})
-    return F === VectorOfVariables && S === Reals
+    # TODO remove this condition, as `supports_add_constrained_variables(model, Reals)`
+    # should be called instead of
+    # `supports_constraint(model, ::VectorOfVariables, ::Reals)
+    if F === VectorOfVariables && S === Reals
+        return supports_add_constrained_variables(model, Reals)
+    else
+        return false
+    end
 end
 
 """

src/variables.jl

@@ -34,6 +34,40 @@ done in the current state of the model `model`.
 """
 add_variable(model::ModelLike) = throw(AddVariableNotAllowed())
 
+"""
+    supports_add_constrained_variable(
+        model::ModelLike,
+        S::Type{<:AbstractScalarSet}
+    )::Bool
+
+Return a `Bool` indicating whether `model` supports constraining a variable
+to belong to a set of type `S` either on creation of the variable with
+[`add_constrained_variable`](@ref) or after the variable is created with
+[`add_constraint`](@ref).
+
+By default, this function falls back to
+`supports_add_constrained_variables(model, Reals) &&
+supports_constraint(model, MOI.SingleVariable, S)` which is the correct
+definition for most models.
+
+## Example
+
+Suppose that a solver supports only two kind of variables: binary variables
+and continuous variables with a lower bound. If the solver decides not to
+support `SingleVariable`-in-`Binary` and `SingleVariable`-in-`GreaterThan`
+constraints, it only has to implement `add_constrained_variable` for these
+two sets which prevents the user to add both a binary constraint and a
+lower bound on the same variable. Moreover, if the user adds a
+`SingleVariable`-in-`GreaterThan` constraint, implementing this interface (i.e.,
+`supports_add_constrained_variables`) enables the constraint to be transparently
+bridged into a supported constraint.
+"""
+function supports_add_constrained_variable(model::ModelLike,
+                                       S::Type{<:AbstractScalarSet})
+    return supports_add_constrained_variables(model, Reals) &&
+        supports_constraint(model, SingleVariable, S)
+end
+
 """
     add_constrained_variable(
         model::ModelLike,
@@ -55,6 +89,61 @@ function add_constrained_variable(model::ModelLike, set::AbstractScalarSet)
     return variable, constraint
 end
 
+"""
+    supports_add_constrained_variables(
+        model::ModelLike,
+        S::Type{<:AbstractScalarSet}
+    )::Bool
+
+Return a `Bool` indicating whether `model` supports constraining a vector of
+variables to belong to a set of type `S` either on creation of the vector of
+variables with [`add_constrained_variables`](@ref) or after the variable is
+created with [`add_constraint`](@ref).
+
+By default, if `S` is `Reals` then this function returns `true` and otherwise,
+it falls back to `supports_add_constrained_variables(model, Reals) &&
+supports_constraint(model, MOI.VectorOfVariables, S)` which is the correct
+definition for most models.
+
+## Example
+
+In the standard conic form (see [Duals](@ref)), the variables are grouped into
+several cones and the constraints are affine equality constraints.
+If `Reals` is not one of the cones supported by the solvers then it needs
+to implement `supports_add_constrained_variables(::Optimizer, ::Type{Reals}) = false`
+as free variables are not supported.
+The solvers should then implement
+`supports_add_constrained_variables(::Optimizer, ::Type{<:SupportedCones}) = true`
+where `SupportedCones` is the union of all cone types that are supported;
+it does not have to implement the method
+`supports_constraint(::Type{VectorOfVariables}, Type{<:SupportedCones})`
+as it should return `false` and it's the default.
+This prevents the user to constrain the same variable in two different cones.
+When a `VectorOfVariables`-in-`S` is added, the variables of the vector
+have already been created so they already belong to given cones.
+If bridges are enabled, the constraint will therefore be bridged by adding slack
+variables in `S` and equality constraints ensuring that the slack variables are
+equal to the corresponding variables of the given constraint function.
+
+Note that there may also be sets for which
+`!supports_add_constrained_variables(model, S)` and
+`supports_constraint(model, MOI.VectorOfVariables, S)`.
+For instance, suppose a solver supports positive semidefinite variable
+constraints and two types of variables: binary variables and nonnegative
+variables. Then the solver should support adding
+`VectorOfVariables`-in-`PositiveSemidefiniteConeTriangle` constraints, but it
+should not support creating variables constrained to belong to the
+`PositiveSemidefiniteConeTriangle` because the variables in
+`PositiveSemidefiniteConeTriangle` should first be created as either binary or
+non-negative.
+"""
+function supports_add_constrained_variables(
+    model::ModelLike, S::Type{<:AbstractVectorSet})
+    return supports_add_constrained_variables(model, Reals) &&
+        supports_constraint(model, VectorOfVariables, S)
+end
+supports_add_constrained_variables(::ModelLike, ::Type{Reals}) = true
+
 """
     add_constrained_variables(
         model::ModelLike,

test/Utilities/model.jl

@@ -61,15 +61,18 @@ struct DummySet <: MOI.AbstractScalarSet end
     @testset "`SingleVariable`-in-`S`" begin
         @test !MOI.supports_constraint(model, DummyFunction, DummySet)
         @test !MOI.supports_constraint(model, MOI.SingleVariable, DummySet)
+        @test !MOI.supports_add_constrained_variable(model, DummySet)
         for S in [MOI.EqualTo{T}, MOI.GreaterThan{T}, MOI.LessThan{T},
                   MOI.Interval{T}, MOI.Integer, MOI.ZeroOne,
                   MOI.Semicontinuous{T}, MOI.Semiinteger{T}]
             @test MOI.supports_constraint(model, MOI.SingleVariable, S)
+            @test MOI.supports_add_constrained_variable(model, S)
         end
         U = Float32
         for S in [MOI.EqualTo{U}, MOI.GreaterThan{U}, MOI.LessThan{U},
                   MOI.Interval{U}, MOI.Semicontinuous{U}, MOI.Semiinteger{U}]
             @test !MOI.supports_constraint(model, MOI.SingleVariable, S)
+            @test !MOI.supports_add_constrained_variable(model, S)
         end
     end
 end