Address @mlubin comments

Author: blegat

docs/src/apimanual.md

@@ -4,6 +4,7 @@ DocTestSetup = quote
     using MathOptInterface
     const MOI = MathOptInterface
 end
+DocTestFilters = [r"MathOptInterface|MOI"]
 ```
 
 # Manual
@@ -929,20 +930,62 @@ If ``\mathcal{C}_i`` is a vector set, the discussion remains valid with
 ``y_i(\frac{1}{2}x^TQ_ix + a_i^T x + b_i)`` replaced with the scalar product
 between `y_i` and the vector of scalar-valued quadratic functions.
 
-### Constraint bridges
+### Automatic reformulation
+
+#### Variable reformulation
+
+A variable is often created in a set unsupported by the solver while it could be
+parametrized by variables constrained in supported sets.
+For example, the [`Bridges.Variable.VectorizeBridge`](@ref) defines the
+reformulation of a constrained variable in [`GreaterThan`](@ref) into a
+constrained vector of one variable in [`Nonnegatives`](@ref).
+The `Bridges.Variable.Vectorize` is the bridge optimizer that applies the
+[`Bridges.Variable.VectorizeBridge`](@ref) rewritting rule. Given an optimizer
+`optimizer` implementing constrained variables in [`Nonnegatives`](@ref) and,
+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})
+
+# output
+
+true
+```
+will additionally support constrained variables in [`GreaterThan`](@ref).
+Note that these [`Bridges.Variable.SingleBridgeOptimizer`](@ref) are mainly
+used for testing bridges. It is recommended to rather use
+[`Bridges.full_bridge_optimizer`](@ref) which automatically select the
+appropriate bridges for unsupported constrained variables.
+
+#### Constraint reformulation
 
 A constraint often possess different equivalent formulations, but a solver may only support one of them.
 It would be duplicate work to implement rewritting rules in every solver wrapper for every different formulation of the constraint to express it in the form supported by the solver.
 Constraint bridges provide a way to define a rewritting rule on top of the MOI interface which can be used by any optimizer.
 Some rules also implement constraint modifications and constraint primal and duals translations.
 
-For example, the `SplitIntervalBridge` defines the reformulation of a `ScalarAffineFunction`-in-`Interval` constraint into a `ScalarAffineFunction`-in-`GreaterThan` and a `ScalarAffineFunction`-in-`LessThan` constraint.
-The `SplitInterval` is the bridge optimizer that applies the `SplitIntervalBridge` rewritting rule.
-Given an optimizer `optimizer` implementing `ScalarAffineFunction`-in-`GreaterThan` and `ScalarAffineFunction`-in-`LessThan`, the optimizer
-```
-bridgedoptimizer = SplitInterval(optimizer)
+For example, the [`Bridges.Constraint.SplitIntervalBridge`](@ref) defines the
+reformulation of a [`ScalarAffineFunction`](@ref)-in-[`Interval`](@ref)
+constraint into a [`ScalarAffineFunction`](@ref)-in-[`GreaterThan`](@ref) and a
+[`ScalarAffineFunction`](@ref)-in-[`LessThan`](@ref) constraint.
+The `Bridges.Constraint.SplitInterval` is the bridge optimizer that applies the
+[`Bridges.Constraint.SplitIntervalBridge`](@ref) rewritting rule. Given an
+optimizer `optimizer` implementing [`ScalarAffineFunction`](@ref)-in-[`GreaterThan`](@ref)
+and [`ScalarAffineFunction`](@ref)-in-[`LessThan`](@ref), the optimizer
+```jldoctest; setup=:(optimizer = MOI.Utilities.Model{Float64}())
+bridged_optimizer = MOI.Bridges.Constraint.SplitInterval{Float64}(optimizer)
+MOI.supports_constraint(bridged_optimizer, MOI.ScalarAffineFunction{Float64}, MOI.Interval{Float64})
+
+# output
+
+true
 ```
 will additionally support `ScalarAffineFunction`-in-`Interval`.
+Note that these [`Bridges.Constraint.SingleBridgeOptimizer`](@ref) are mainly
+used for testing bridges. It is recommended to rather use
+[`Bridges.full_bridge_optimizer`](@ref) which automatically select the
+appropriate constraint bridges for unsupported constraints.
+
 
 ## Implementing a solver interface
 
@@ -966,6 +1009,34 @@ model = MyPackage.Optimizer()
 MOI.set(model, MyPackage.PrintLevel(), 0)
 ```
 
+### Supported constrained variables and constraints
+
+The solver interface should only implement support for constrained variables
+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 allow 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 and supports transforming free
+variables into variables in `set`. However,
+
+* if `model` does not support creating free variables, it should only implement
+  `add_constrained_variable` 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` supports free variables but does not support transforming free
+  variables into variables in `set`, then it should implement both
+  [`add_variable`](@ref) and `add_constraint_variable` but should not implement
+  any method for [`add_constraint`](@ref) for
+  [`SingleVariable`](@ref)-in-`typeof(set)`.
+
 ### Implementing copy
 
 Avoid storing extra copies of the problem when possible. This means that solver

docs/src/apireference.md

@@ -186,13 +186,25 @@ delete(::ModelLike, ::Index)
 
 ### Variables
 
-Functions for adding variables. For deleting, see index types section.
+*Free variables* are created with with [`add_variable`](@ref) or
+[`add_variables`](@ref) and *constrained variables* are created with
+[`add_constrained_variable`](@ref) or [`add_constrained_variables`](@ref).
+Note that free variables can be constrained after being created using
+[`add_constraint`](@ref) with the [`SingleVariable`](@ref) or
+[`VectorOfVariables`](@ref). However, they need to be added with
+[`add_constrained_variable`](@ref) or [`add_constrained_variables`](@ref) to
+allow [Variable bridges](@ref) to be used.
+Note further that free variables that are constrained after being created using
+[`add_constraint`](@ref) will be copied by [`copy_to`](@ref) with
+[`add_constrained_variable`](@ref) or [`add_constrained_variables`](@ref) by the
+[`Utilities.CachingOptimizer`](@ref).
+For deleting, see index types section.
 
 ```@docs
-add_variables
 add_variable
-add_constrained_variables
+add_variables
 add_constrained_variable
+add_constrained_variables
 ```
 
 List of attributes associated with variables. [category AbstractVariableAttribute]
@@ -462,24 +474,23 @@ Utilities.@model
 
 ## Bridges
 
-Bridges can be used for automatic reformulation of a certain constrained
-variables or constraints into equivalent formulations using constrained
-variables and constraints of different types.
-There are two important concepts to distinguish:
+Bridges can be used for automatic reformulation of constrained variables or
+constraints into equivalent formulations using constrained variables and
+constraints of different types. There are two important concepts to distinguish:
 * [`Bridges.AbstractBridge`](@ref)s are recipes implementing a specific
   reformulation. Bridges are not directly subtypes of
   [`Bridges.AbstractBridge`](@ref), they are either
   [`Bridges.Variable.AbstractBridge`](@ref) or
   [`Bridges.Constraint.AbstractBridge`](@ref).
-* [`Bridges.AbstractBridgeOptimizer`](@ref)s is a layer that can applied to
+* [`Bridges.AbstractBridgeOptimizer`](@ref) is a layer that can be applied to
   another [`ModelLike`](@ref) to apply the reformulation. The
-  [`Bridges.LazyBridgeOptimizer`](@ref) automatically choose the appropriate
+  [`Bridges.LazyBridgeOptimizer`](@ref) automatically chooses the appropriate
   bridges to use when a constrained variable or constraint is not supported
-  using the list of bridges that were added to it by [`Bridges.add_bridge`](@ref).
-  [`Bridges.full_bridge_optimizer`](@ref) wraps a model in a
-  [`Bridges.LazyBridgeOptimizer`](@ref) where all the bridges defined in MOI
-  are added. This is the recommended way to use bridges in the
-  [Testing guideline](@ref) and JuMP automatically calls this function when
+  by using the list of bridges that were added to it by
+  [`Bridges.add_bridge`](@ref). [`Bridges.full_bridge_optimizer`](@ref) wraps a
+  model in a [`Bridges.LazyBridgeOptimizer`](@ref) where all the bridges defined
+  in MOI are added. This is the recommended way to use bridges in the
+  [Testing guideline](@ref), and JuMP automatically calls this function when
   attaching an optimizer.
 
 ```@docs
@@ -499,22 +510,104 @@ or constrained with
 variable bridges allow to return *bridged variables* that do not correspond to
 variables of the underlying model. These variables are parametrized by
 variables of the underlying model and this parametrization can be obtained with
-[`Bridges.variable_bridged_function`](@ref). Similarly, the variables of the
+[`Bridges.bridged_variable_function`](@ref). Similarly, the variables of the
 underlying model that were created by the bridge can be expressed in terms of
 the bridged variables and this expression can be obtained with
-[`Bridges.variable_unbridged_function`](@ref).
+[`Bridges.unbridged_variable_function`](@ref).
+For instance, consider a model bridged by the
+[`Bridges.Variable.VectorizeBridge`](@ref):
+```jldoctest bridged_variable_function
+model = MOI.Utilities.Model{Float64}()
+bridged_model = MOI.Bridges.Variable.Vectorize{Float64}(model)
+bridged_variable, bridged_constraint = MOI.add_constrained_variable(bridged_model, MOI.GreaterThan(1.0))
+
+# output
+
+(MOI.VariableIndex(-1), MOI.ConstraintIndex{MOI.SingleVariable,MOI.GreaterThan{Float64}}(-1))
+```
+The constrained variable in `MOI.GreaterThan(1.0)` returned is a bridged
+variable as its index in negative. In `model`, a constrained variable in
+`MOI.Nonnegatives` is created:
+```jldoctest bridged_variable_function
+inner_variables = MOI.get(model, MOI.ListOfVariableIndices())
+
+# output
+
+1-element Array{MOI.VariableIndex,1}:
+ MOI.VariableIndex(1)
+```
+In the functions used for adding constraints or setting the objective to
+`bridged_model`, `bridged_variable` is substituted for `inner_variables[1]` plus
+1:
+```jldoctest bridged_variable_function
+MOI.Bridges.bridged_variable_function(bridged_model, bridged_variable)
+
+# output
+
+MOI.ScalarAffineFunction{Float64}(MOI.ScalarAffineTerm{Float64}[ScalarAffineTerm{Float64}(1.0, VariableIndex(1))], 1.0)
+```
+When getting [`ConstraintFunction`](@ref) or [`ObjectiveFunction`](@ref),
+`inner_variables[1]` is substituted for `bridged_variable` minus 1:
+```jldoctest bridged_variable_function
+MOI.Bridges.unbridged_variable_function(bridged_model, inner_variables[1])
+
+# output
+
+MOI.ScalarAffineFunction{Float64}(MOI.ScalarAffineTerm{Float64}[ScalarAffineTerm{Float64}(1.0, VariableIndex(-1))], -1.0)
+```
+
 
 !!! note
     A notable exception is with [`Bridges.Variable.ZerosBridge`](@ref) where no
     variable is created in the underlying model as the variables are simply
     transformed to zeros. When this bridge is used, it is not possible to
-    recover functions with bridged variables from functions of the underlying
-    model.
+    recover functions with bridged variables from functions of the inner
+    model. Consider for instance that we create two zero variables:
+    ```jldoctest cannot_unbridge_zero
+    model = MOI.Utilities.Model{Float64}()
+    bridged_model = MOI.Bridges.Variable.Zeros{Float64}(model)
+    bridged_variables, bridged_constraint = MOI.add_constrained_variables(bridged_model, MOI.Zeros(2))
+
+    # output
+
+    (MOI.VariableIndex[VariableIndex(-1), VariableIndex(-2)], MOI.ConstraintIndex{MOI.VectorOfVariables,MOI.Zeros}(-1))
+    ```
+    Consider the following functions in the variables of `bridged_model`:
+    ```jldoctest cannot_unbridge_zero
+    func = MOI.Utilities.operate(+, Float64, MOI.SingleVariable.(bridged_variables)...)
+
+    # output
+
+    MOI.ScalarAffineFunction{Float64}(MOI.ScalarAffineTerm{Float64}[ScalarAffineTerm{Float64}(1.0, VariableIndex(-1)), ScalarAffineTerm{Float64}(1.0, VariableIndex(-2))], 0.0)
+    ```
+    We can obtain the equivalent function in the variables of `model` as follows:
+    ```jldoctest cannot_unbridge_zero
+    inner_func = MOI.Bridges.bridged_function(bridged_model, func)
+
+    # output
+
+    MOI.ScalarAffineFunction{Float64}(MOI.ScalarAffineTerm{Float64}[], 0.0)
+    ```
+    However, it's not possible to invert this operations. Indeed, since the
+    bridged variables are substituted for zeros, we cannot deduce whether
+    they were present in the initial function.
+    ```jldoctest cannot_unbridge_zero; filter = r"Stacktrace:.*"s
+    MOI.Bridges.unbridged_function(bridged_model, inner_func)
+
+    # output
+
+    ERROR: Cannot unbridge function because some variables are bridged by variable bridges that do not support reverse mapping, e.g., `ZerosBridge`.
+    Stacktrace:
+     [1] error(::String, ::String, ::String) at ./error.jl:42
+     [2] throw_if_cannot_unbridge at /home/blegat/.julia/dev/MathOptInterface/src/Bridges/Variable/map.jl:343 [inlined]
+     [3] unbridged_function(::MOI.Bridges.Variable.SingleBridgeOptimizer{MOI.Bridges.Variable.ZerosBridge{Float64},MOI.Utilities.Model{Float64}}, ::MOI.ScalarAffineFunction{Float64}) at /home/blegat/.julia/dev/MOI/src/Bridges/bridge_optimizer.jl:920
+     [4] top-level scope at none:0
+    ```
 
 ```@docs
 Bridges.Variable.AbstractBridge
-Bridges.variable_bridged_function
-Bridges.variable_unbridged_function
+Bridges.bridged_variable_function
+Bridges.unbridged_variable_function
 ```
 
 Below is the list of variable bridges implemented in this package.
@@ -545,6 +638,50 @@ allow to return *bridged constraints* that do not correspond to
 constraints of the underlying model. These constraints were enforced by an
 equivalent formulation that added constraints (and possibly also variables) in
 the underlying model.
+For instance, consider a model bridged by the
+[`Bridges.Constraint.SplitIntervalBridge`](@ref):
+```jldoctest split_interval
+model = MOI.Utilities.Model{Float64}()
+bridged_model = MOI.Bridges.Constraint.SplitInterval{Float64}(model)
+x, y = MOI.add_variables(bridged_model, 2)
+func = MOI.Utilities.operate(+, Float64, MOI.SingleVariable(x), MOI.SingleVariable(y))
+c = MOI.add_constraint(bridged_model, func, MOI.Interval(1.0, 2.0))
+
+# output
+
+MOI.ConstraintIndex{MOI.ScalarAffineFunction{Float64},MOI.Interval{Float64}}(1)
+```
+We can see the constraint was bridged to two constraints, one for each bound,
+in the inner model.
+```jldoctest split_interval
+MOI.get(model, MOI.ListOfConstraints())
+
+# output
+
+2-element Array{Tuple{DataType,DataType},1}:
+ (MOI.ScalarAffineFunction{Float64}, MOI.GreaterThan{Float64})
+ (MOI.ScalarAffineFunction{Float64}, MOI.LessThan{Float64})
+```
+However, `bridged_model` hides transparently hides these constraints and create the
+illusion that an interval constraint was created.
+```jldoctest split_interval
+MOI.get(bridged_model, MOI.ListOfConstraints())
+
+# output
+
+1-element Array{Tuple{DataType,DataType},1}:
+ (MOI.ScalarAffineFunction{Float64}, MOI.Interval{Float64})
+```
+It is nevertheless possible to differentiate this constraint from a constraint
+added to the inner model by asking whether it is bridged:
+```jldoctest split_interval
+MOI.Bridges.is_bridged(bridged_model, c)
+
+# output
+
+true
+```
+
 ```@docs
 Bridges.Constraint.AbstractBridge
 ```
@@ -720,7 +857,7 @@ is set to `AUTOMATIC` or to `MANUAL`.
   a constraint) results in a drop to the state `EMPTY_OPTIMIZER`.
 
 When calling [`Utilities.attach_optimizer`](@ref), the `CachingOptimizer` copies
-the cached model to the optimizer with [`MathOptInterface.copy_to`](@ref).
+the cached model to the optimizer with [`copy_to`](@ref).
 We refer to [Implementing copy](@ref) for more details.
 
 ```@docs