Address comments

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}
@@ -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_add_constrained_variables(::Optimizer,
-::Type{Reals})` and return `false` so that free variables are bridged,
-see [`supports_add_constrained_variables`](@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 free variables are bridged, see
+[`supports_add_constrained_variables`](@ref).
 
 ### Handling duplicate coefficients
 

src/constraints.jl

@@ -29,7 +29,7 @@ sum of a nonnegative and a nonpositive variables.
 """ # Implemented as only one method to avoid ambiguity
 function supports_constraint(model::ModelLike, F::Type{<:AbstractFunction},
                              S::Type{<:AbstractSet})
-    # TODO removed this condition, as `supports_add_constrained_variables(model, 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

src/variables.jl

@@ -53,13 +53,14 @@ 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 decide not to
+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, it will transparently be bridged
-into a supported constraint.
+`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})
@@ -106,33 +107,35 @@ definition for most models.
 
 ## Example
 
-In the standard conic form, the variables are grouped into several cones
-and the constraints are affine equality constraints.
+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
-but it should not implement
+where `SupportedCones` is the union of all cone types that are supported;
+but it does not have to implement the method
 `supports_constraint(::Type{VectorOfVariables}, Type{<:SupportedCones})`
-as it should return `false`.
+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.
-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.
+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
+`VectorOfVariables`-in-`PositiveSemidefiniteConeTriangle` constraints, but it
 should not support creating variables constrained to belong to the
-`PositiveSemidefiniteConeTriangle` as free variables are not supported.
+`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})