Finish bridges doc

Author: blegat

docs/src/apireference.md

@@ -430,19 +430,59 @@ DeleteNotAllowed
 
 ## Bridges
 
-Bridges can be used for automatic reformulation of a certain constraint type into equivalent constraints.
+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.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
+  another [`ModelLike`](@ref) to apply the reformulation. The
+  [`Bridges.LazyBridgeOptimizer`](@ref) automatically choose 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
+  attaching an optimizer.
+
 ```@docs
 Bridges.AbstractBridge
 Bridges.AbstractBridgeOptimizer
-Bridges.Constraint.SingleBridgeOptimizer
 Bridges.LazyBridgeOptimizer
 Bridges.add_bridge
+Bridges.full_bridge_optimizer
 ```
 
 ### Variable bridges
 
+When variables are added, either free with
+[`add_variable`](@ref)/[`add_variables`](@ref),
+or constrained with
+[`add_constrained_variable`](@ref)/[`add_constrained_variables`](@ref),
+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
+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).
+
+!!! 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.
+
 ```@docs
 Bridges.Variable.AbstractBridge
+Bridges.variable_bridged_function
+Bridges.variable_unbridged_function
 ```
 
 Below is the list of variable bridges implemented in this package.
@@ -454,8 +494,25 @@ Bridges.Variable.VectorizeBridge
 Bridges.Variable.RSOCtoPSDBridge
 ```
 
+For each bridge defined in this package, a corresponding
+[`Bridges.Variable.SingleBridgeOptimizer`](@ref) is available with the same
+name without the "Bridge" suffix, e.g., `SplitInterval` is a
+`SingleBridgeOptimizer` for the `SplitIntervalBridge`. Moreover, they are all
+added in the [`Bridges.LazyBridgeOptimizer`](@ref) returned by
+[`Bridges.full_bridge_optimizer`](@ref) as it calls
+[`Bridges.Variable.add_all_bridges`](@ref).
+```@docs
+Bridges.Variable.SingleBridgeOptimizer
+Bridges.Variable.add_all_bridges
+```
+
 ### Constraint bridges
 
+When constraints are added with [`add_constraint`](@ref), constraint bridges
+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.
 ```@docs
 Bridges.Constraint.AbstractBridge
 ```
@@ -483,27 +540,34 @@ Bridges.Constraint.SOCtoPSDBridge
 Bridges.Constraint.RSOCtoPSDBridge
 Bridges.Constraint.IndicatorActiveOnFalseBridge
 ```
-For each bridge defined in this package, a corresponding bridge optimizer is available with the same name without the "Bridge" suffix, e.g., `SplitInterval` is an `SingleBridgeOptimizer` for the `SplitIntervalBridge`.
-Moreover, a `LazyBridgeOptimizer` with all the bridges defined in this package can be obtained with
+For each bridge defined in this package, a corresponding
+[`Bridges.Constraint.SingleBridgeOptimizer`](@ref) is available with the same
+name without the "Bridge" suffix, e.g., `SplitInterval` is a
+`SingleBridgeOptimizer` for the `SplitIntervalBridge`. Moreover, they are all
+added in the [`Bridges.LazyBridgeOptimizer`](@ref) returned by
+[`Bridges.full_bridge_optimizer`](@ref) as it calls
+[`Bridges.Constraint.add_all_bridges`](@ref).
 ```@docs
-Bridges.full_bridge_optimizer
+Bridges.Constraint.SingleBridgeOptimizer
+Bridges.Constraint.add_all_bridges
 ```
 
 ### Bridge interface
 
 A bridge should implement the following functions to be usable by a bridge optimizer:
 ```@docs
-supports_constraint(::Type{<:Bridges.Constraint.AbstractBridge}, ::Type{<:AbstractFunction}, ::Type{<:AbstractSet})
 Bridges.added_constrained_variable_types
 Bridges.added_constraint_types
 ```
 Additionally, variable bridges should implement:
 ```@docs
+Bridges.Variable.supports_constrained_variable
 Bridges.Variable.concrete_bridge_type
 Bridges.Variable.bridge_constrained_variable
 ```
 and constraint bridges should implement
 ```@docs
+supports_constraint(::Type{<:Bridges.Constraint.AbstractBridge}, ::Type{<:AbstractFunction}, ::Type{<:AbstractSet})
 Bridges.Constraint.concrete_bridge_type
 Bridges.Constraint.bridge_constraint
 ```

src/Bridges/Variable/bridge.jl

@@ -51,13 +51,13 @@ function MOI.get(::MOI.ModelLike, attr::MOI.AbstractVariableAttribute,
 end
 
 """
-    supports_constrained_variables(::Type{<:AbstractBridge},
+    supports_constrained_variable(::Type{<:AbstractBridge},
                                    ::Type{<:MOI.AbstractSet})::Bool
 
 Return a `Bool` indicating whether the bridges of type `BT` support bridging
 constrained variables in `S`.
 """
-function supports_constrained_variables(::Type{<:AbstractBridge},
+function supports_constrained_variable(::Type{<:AbstractBridge},
                                         ::Type{<:MOI.AbstractSet})
     return false
 end
@@ -128,7 +128,7 @@ end
                          S::Type{<:MOI.AbstractSet})::DataType
 
 Return the concrete type of the bridge supporting variables in `S` constraints.
-This function can only be called if `MOI.supports_constrained_variables(BT, S)`
+This function can only be called if `MOI.supports_constrained_variable(BT, S)`
 is `true`.
 
 ## Examples

src/Bridges/Variable/flip_sign.jl

@@ -9,7 +9,7 @@ stored in the `flipped_constraint` field by convention.
 abstract type FlipSignBridge{
     T, S1<:MOI.AbstractSet, S2<:MOI.AbstractSet} <: AbstractBridge end
 
-function supports_constrained_variables(
+function supports_constrained_variable(
     ::Type{<:FlipSignBridge{T, S1}}, ::Type{S1}) where {T, S1<:MOI.AbstractVectorSet}
     return true
 end

src/Bridges/Variable/free.jl

@@ -22,7 +22,7 @@ function bridge_constrained_variable(::Type{FreeBridge{T}},
                          nonpos_variables, nonpos_constraint)
 end
 
-function supports_constrained_variables(
+function supports_constrained_variable(
     ::Type{<:FreeBridge}, ::Type{MOI.Reals})
     return true
 end

src/Bridges/Variable/map.jl

@@ -261,20 +261,28 @@ function function_for(map::Map, ci::MOI.ConstraintIndex{MOI.VectorOfVariables})
 end
 
 """
-    unbridged_function(map::Map, vi::MOI.VariableIndex)
+    throw_if_cannot_unbridge(map::Map)
 
-Return the expression of `vi` in terms of bridged variables.
+Throw an error if some bridged variables do not have any reverse mapping.
 """
-function unbridged_function(map::Map, vi::MOI.VariableIndex)
+function throw_if_cannot_unbridge(map::Map)
     if map.unbridged_function === nothing
         error("Cannot unbridge function because some variables are bridged by",
               " variable bridges that do not support reverse mapping, e.g.,",
               " `ZerosBridge`.")
-    else
-        return get(map.unbridged_function, vi, nothing)
     end
 end
 
+"""
+    unbridged_function(map::Map, vi::MOI.VariableIndex)
+
+Return the expression of `vi` in terms of bridged variables.
+"""
+function unbridged_function(map::Map, vi::MOI.VariableIndex)
+    throw_if_cannot_unbridge(map)
+    return get(map.unbridged_function, vi, nothing)
+end
+
 """
     EmptyMap <: AbstractDict{MOI.VariableIndex, AbstractBridge}
 

src/Bridges/Variable/rsoc_to_psd.jl

@@ -40,7 +40,7 @@ function bridge_constrained_variable(::Type{RSOCtoPSDBridge{T}},
     return RSOCtoPSDBridge{T}(variables, psd, off_diag, diag)
 end
 
-function supports_constrained_variables(
+function supports_constrained_variable(
     ::Type{<:RSOCtoPSDBridge}, ::Type{MOI.RotatedSecondOrderCone})
     return true
 end

src/Bridges/Variable/single_bridge_optimizer.jl

@@ -25,12 +25,12 @@ bridges(bridge::SingleBridgeOptimizer) = bridge.map
 function MOIB.supports_bridging_constraint(
     b::SingleBridgeOptimizer{BT}, ::Type{MOI.SingleVariable},
     S::Type{<:MOI.AbstractScalarSet}) where BT
-    return supports_constrained_variables(BT, S)
+    return supports_constrained_variable(BT, S)
 end
 function MOIB.supports_bridging_constraint(
     b::SingleBridgeOptimizer{BT}, ::Type{MOI.VectorOfVariables},
     S::Type{<:MOI.AbstractVectorSet}) where BT
-    return supports_constrained_variables(BT, S)
+    return supports_constrained_variable(BT, S)
 end
 function MOIB.is_bridged(b::SingleBridgeOptimizer, S::Type{<:MOI.AbstractScalarSet})
     return MOIB.supports_bridging_constraint(b, MOI.SingleVariable, S)

src/Bridges/Variable/vectorize.jl

@@ -17,7 +17,7 @@ function bridge_constrained_variable(
     return VectorizeBridge{T, S}(variables[1], vector_constraint, set_constant)
 end
 
-function supports_constrained_variables(
+function supports_constrained_variable(
     ::Type{VectorizeBridge{T}}, ::Type{<:MOIU.ScalarLinearSet{T}}) where T
     return true
 end

src/Bridges/Variable/zeros.jl

@@ -22,7 +22,7 @@ function bridge_constrained_variable(::Type{ZerosBridge{T}},
     return ZerosBridge{T}(MOI.dimension(set))
 end
 
-function supports_constrained_variables(
+function supports_constrained_variable(
     ::Type{<:ZerosBridge}, ::Type{MOI.Zeros})
     return true
 end

src/Bridges/bridge_optimizer.jl

@@ -828,15 +828,16 @@ end
 bridged_function(bridge::AbstractBridgeOptimizer, value) = value
 
 """
-    variable_bridged_function(b::AbstractBridgeOptimizer,
+    variable_unbridged_function(b::AbstractBridgeOptimizer,
                               vi::MOI.VariableIndex)
 
 Return a `MOI.AbstractScalarFunction` of variables of `b` that equals `vi`.
 That is, if the variable `vi` is an internal variable of `b.model` created by a
 but not visible to the user, it returns its expression in terms of the variables
 of bridged variables. Otherwise, it returns `MOI.SingleVariable(vi)`.
 """
-function variable_unbridged_function(b, vi::MOI.VariableIndex)
+function variable_unbridged_function(b::AbstractBridgeOptimizer,
+                                     vi::MOI.VariableIndex)
     func = Variable.unbridged_function(Variable.bridges(b), vi)
     if func === nothing
         return MOI.SingleVariable(vi)
@@ -860,6 +861,10 @@ function unbridged_function(b::AbstractBridgeOptimizer,
     if !Variable.has_bridges(Variable.bridges(b))
         return func
     end
+    # If `func` does not contain any variable, this will never call
+    # `variable_unbridged_function` hence it might silently return an incorrect
+    # function so we call `throw_if_cannot_unbridge` here.
+    Variable.throw_if_cannot_unbridge(Variable.bridges(b))
     return MOIU.substitute_variables(
         vi -> variable_unbridged_function(b, vi),
         func)::typeof(func)