[Bridges] improvements to Variable bridge docstrings (#1864)

Author: odow

docs/src/submodules/Bridges/reference.md

@@ -31,23 +31,11 @@ Bridges.debug_supports
 Bridges.bridged_variable_function
 Bridges.unbridged_variable_function
 Bridges.bridged_function
-Bridges.Variable.unbridged_map
-```
-
-## Constraint bridges
-
-```@docs
-Bridges.Constraint.AbstractBridge
-Bridges.Constraint.AbstractFunctionConversionBridge
-Bridges.Constraint.SingleBridgeOptimizer
-Bridges.Constraint.add_all_bridges
 ```
 
-### [SetMap bridges](@id constraint_set_map)
+### [SetMap API](@id constraint_set_map)
 
 ```@docs
-Bridges.Variable.SetMapBridge
-Bridges.Constraint.SetMapBridge
 Bridges.map_set
 Bridges.inverse_map_set
 Bridges.map_function
@@ -56,11 +44,21 @@ Bridges.adjoint_map_function
 Bridges.inverse_adjoint_map_function
 ```
 
-### [Bridges implemented](@id constraint_bridges_ref)
+## Constraint bridge API
 
 ```@docs
+Bridges.Constraint.AbstractBridge
+Bridges.Constraint.AbstractFunctionConversionBridge
+Bridges.Constraint.SingleBridgeOptimizer
+Bridges.Constraint.add_all_bridges
 Bridges.Constraint.FlipSignBridge
 Bridges.Constraint.AbstractToIntervalBridge
+Bridges.Constraint.SetMapBridge
+```
+
+## [Constraint bridges implemented](@id constraint_bridges_ref)
+
+```@docs
 Bridges.Constraint.GreaterToIntervalBridge
 Bridges.Constraint.LessToIntervalBridge
 Bridges.Constraint.GreaterToLessBridge
@@ -97,18 +95,20 @@ Bridges.Constraint.SemiToBinaryBridge
 Bridges.Constraint.ZeroOneBridge
 ```
 
-## [Variable bridges](@id ref_variable_bridges)
+## [Variable bridge API](@id ref_variable_bridges)
 
 ```@docs
 Bridges.Variable.AbstractBridge
 Bridges.Variable.SingleBridgeOptimizer
 Bridges.Variable.add_all_bridges
+Bridges.Variable.FlipSignBridge
+Bridges.Variable.SetMapBridge
+Bridges.Variable.unbridged_map
 ```
 
-### [Bridges implemented](@id variable_bridges_ref)
+## [Variable bridges implemented](@id variable_bridges_ref)
 
 ```@docs
-Bridges.Variable.FlipSignBridge
 Bridges.Variable.ZerosBridge
 Bridges.Variable.FreeBridge
 Bridges.Variable.NonposToNonnegBridge
@@ -118,15 +118,15 @@ Bridges.Variable.RSOCtoSOCBridge
 Bridges.Variable.RSOCtoPSDBridge
 ```
 
-## Objective bridges
+## Objective bridge API
 
 ```@docs
 Bridges.Objective.AbstractBridge
 Bridges.Objective.SingleBridgeOptimizer
 Bridges.Objective.add_all_bridges
 ```
 
-### [Bridges implemented](@id objective_bridges_ref)
+### [Objective bridges implemented](@id objective_bridges_ref)
 
 ```@docs
 Bridges.Objective.SlackBridge

src/Bridges/Variable/bridge.jl

@@ -10,7 +10,7 @@
 Subtype of [`MathOptInterface.Bridges.AbstractBridge`](@ref) for variable
 bridges.
 """
-abstract type AbstractBridge <: MOIB.AbstractBridge end
+abstract type AbstractBridge <: MOI.Bridges.AbstractBridge end
 
 """
     supports_constrained_variable(
@@ -81,10 +81,10 @@ MathOptInterface.Bridges.Variable.VectorizeBridge{Float64, MathOptInterface.Nonn
 concrete_bridge_type(::Type{BT}, ::Type{<:MOI.AbstractSet}) where {BT} = BT
 
 function concrete_bridge_type(
-    b::MOIB.AbstractBridgeOptimizer,
+    b::MOI.Bridges.AbstractBridgeOptimizer,
     S::Type{<:MOI.AbstractSet},
 )
-    return concrete_bridge_type(MOIB.bridge_type(b, S), S)
+    return concrete_bridge_type(MOI.Bridges.bridge_type(b, S), S)
 end
 
 """
@@ -121,7 +121,7 @@ function MOI.get(
     ::MOI.ModelLike,
     attr::MOI.AbstractVariableAttribute,
     bridge::AbstractBridge,
-    ::MOIB.IndexInVector,
+    ::MOI.Bridges.IndexInVector,
 )
     return throw(
         ArgumentError(
@@ -144,7 +144,7 @@ function MOI.set(
     attr::MOI.AbstractVariableAttribute,
     bridge::AbstractBridge,
     value,
-    ::MOIB.IndexInVector...,
+    ::MOI.Bridges.IndexInVector...,
 )
     if MOI.is_copyable(attr) && !MOI.supports(model, attr, typeof(bridge))
         throw(MOI.UnsupportedAttribute(attr))
@@ -154,7 +154,7 @@ function MOI.set(
 end
 
 """
-   unbridged_map(
+    unbridged_map(
        bridge::MOI.Bridges.Variable.AbstractBridge,
         vi::MOI.VariableIndex,
     )
@@ -163,21 +163,25 @@ For a bridged variable in a scalar set, return a tuple of pairs mapping the
 variables created by the bridge to an affine expression in terms of the
 bridged variable `vi`.
 
-    unbridged_map(
-        bridge::MOI.Bridges.Variable.AbstractBridge,
-        vis::Vector{MOI.VariableIndex},
-    )
+```julia
+unbridged_map(
+    bridge::MOI.Bridges.Variable.AbstractBridge,
+    vis::Vector{MOI.VariableIndex},
+)
+```
 
 For a bridged variable in a vector set, return a tuple of pairs mapping the
 variables created by the bridge to an affine expression in terms of the bridged
 variable `vis`. If this method is not implemented, it falls back to calling
 the following method for every variable of `vis`.
 
-    unbridged_map(
-        bridge::MOI.Bridges.Variable.AbstractBridge,
-        vi::MOI.VariableIndex,
-        i::MOIB.IndexInVector,
-    )
+```julia
+unbridged_map(
+    bridge::MOI.Bridges.Variable.AbstractBridge,
+    vi::MOI.VariableIndex,
+    i::MOI.Bridges.IndexInVector,
+)
+```
 
 For a bridged variable in a vector set, return a tuple of pairs mapping the
 variables created by the bridge to an affine expression in terms of the bridged
@@ -192,7 +196,7 @@ function unbridged_map end
 function unbridged_map(bridge::AbstractBridge, vis::Vector{MOI.VariableIndex})
     mappings = Pair{MOI.VariableIndex,MOI.AbstractScalarFunction}[]
     for (i, vi) in enumerate(vis)
-        vi_mappings = unbridged_map(bridge, vi, MOIB.IndexInVector(i))
+        vi_mappings = unbridged_map(bridge, vi, MOI.Bridges.IndexInVector(i))
         if vi_mappings === nothing
             return
         end

src/Bridges/Variable/bridges/flip_sign.jl

@@ -5,11 +5,9 @@
 # in the LICENSE.md file or at https://opensource.org/licenses/MIT.
 
 """
-    FlipSignBridge{T,S1,S2} <: SetMapBridge{T,S2,S1}
+    abstract type FlipSignBridge{T,S1,S2} <: SetMapBridge{T,S2,S1} end
 
-Bridge constrained variables in `S1` into constrained variables in `S2` by
-multiplying the variables by `-1` and taking the point reflection of the set
-across the origin.
+An abstract type that simplifies the creation of other bridges.
 """
 abstract type FlipSignBridge{T,S1<:MOI.AbstractSet,S2<:MOI.AbstractSet} <:
               SetMapBridge{T,S2,S1} end
@@ -47,11 +45,26 @@ function MOI.delete(
 end
 
 """
-    NonposToNonnegBridge{T} <:
-    FlipSignBridge{T,MOI.Nonpositives,MOI.Nonnegatives}
+    NonposToNonnegBridge{T} <: Bridges.Variable.AbstractBridge
 
-Transforms constrained variables in [`MOI.Nonpositives`](@ref) into constrained
-variables in [`MOI.Nonnegatives`](@ref).
+`NonposToNonnegBridge` implements the following reformulation:
+
+* ``x \\in \\mathbb{R}_-`` into ``y \\in \\mathbb{R}_+`` with the substitution
+  rule ``x = -y``,
+
+where `T` is the coefficient type of `-y`.
+
+## Source node
+
+`NonposToNonnegBridge` supports:
+
+* [`MOI.VectorOfVariables`](@ref) in [`MOI.Nonpositives`](@ref)
+
+## Target nodes
+
+`NonposToNonnegBridge` creates:
+
+* One variable node: [`MOI.VectorOfVariables`](@ref) in [`MOI.Nonnegatives`](@ref),
 """
 struct NonposToNonnegBridge{T} <:
        FlipSignBridge{T,MOI.Nonpositives,MOI.Nonnegatives}

src/Bridges/Variable/bridges/free.jl

@@ -7,8 +7,24 @@
 """
     FreeBridge{T} <: Bridges.Variable.AbstractBridge
 
-Transforms constrained variables in [`MOI.Reals`](@ref) to the difference of
-constrained variables in [`MOI.Nonnegatives`](@ref).
+`FreeBridge` implements the following reformulation:
+
+* ``x \\in \\mathbb{R}`` into ``y, z \\ge 0`` with the substitution
+  rule ``x = y - z``,
+
+where `T` is the coefficient type of `y - z`.
+
+## Source node
+
+`FreeBridge` supports:
+
+ * [`MOI.VectorOfVariables`](@ref) in [`MOI.Reals`](@ref)
+
+## Target nodes
+
+`FreeBridge` creates:
+
+ * One variable node: [`MOI.VectorOfVariables`](@ref) in [`MOI.Nonnegatives`](@ref)
 """
 struct FreeBridge{T} <: AbstractBridge
     variables::Vector{MOI.VariableIndex}
@@ -24,20 +40,18 @@ function bridge_constrained_variable(
 ) where {T}
     variables, constraint = MOI.add_constrained_variables(
         model,
-        MOI.Nonnegatives(2MOI.dimension(set)),
+        MOI.Nonnegatives(2 * MOI.dimension(set)),
     )
     return FreeBridge{T}(variables, constraint)
 end
 
-function supports_constrained_variable(::Type{<:FreeBridge}, ::Type{MOI.Reals})
-    return true
-end
+supports_constrained_variable(::Type{<:FreeBridge}, ::Type{MOI.Reals}) = true
 
-function MOIB.added_constrained_variable_types(::Type{<:FreeBridge})
+function MOI.Bridges.added_constrained_variable_types(::Type{<:FreeBridge})
     return Tuple{Type}[(MOI.Nonnegatives,)]
 end
 
-function MOIB.added_constraint_types(::Type{FreeBridge{T}}) where {T}
+function MOI.Bridges.added_constraint_types(::Type{FreeBridge{T}}) where {T}
     return Tuple{Type,Type}[]
 end
 
@@ -73,7 +87,7 @@ end
 function MOI.delete(
     model::MOI.ModelLike,
     bridge::FreeBridge,
-    i::MOIB.IndexInVector,
+    i::MOI.Bridges.IndexInVector,
 )
     n = div(length(bridge.variables), 2)
     MOI.delete(model, bridge.variables[i.value])
@@ -113,38 +127,34 @@ function MOI.get(
     model::MOI.ModelLike,
     attr::Union{MOI.VariablePrimal,MOI.VariablePrimalStart},
     bridge::FreeBridge{T},
-    i::MOIB.IndexInVector,
+    i::MOI.Bridges.IndexInVector,
 ) where {T}
     n = div(length(bridge.variables), 2)
     return MOI.get(model, attr, bridge.variables[i.value]) -
            MOI.get(model, attr, bridge.variables[n+i.value])
 end
 
-function MOIB.bridged_function(
+function MOI.Bridges.bridged_function(
     bridge::FreeBridge{T},
-    i::MOIB.IndexInVector,
+    i::MOI.Bridges.IndexInVector,
 ) where {T}
     n = div(length(bridge.variables), 2)
-    return MOIU.operate(
-        -,
-        T,
-        bridge.variables[i.value],
-        bridge.variables[n+i.value],
-    )
+    y = bridge.variables[i.value]
+    z = bridge.variables[n+i.value]
+    return MOI.Utilities.operate(-, T, y, z)
 end
 
 # x_free has been replaced by x[i] - x[n + i].
 # To undo it we replace x[i] by x_free and x[n + i] by 0.
 function unbridged_map(
     bridge::FreeBridge{T},
     vi::MOI.VariableIndex,
-    i::MOIB.IndexInVector,
+    i::MOI.Bridges.IndexInVector,
 ) where {T}
-    # `unbridged_map` is required to return a `MOI.ScalarAffineFunction`.
-    func = convert(MOI.ScalarAffineFunction{T}, vi)
     n = div(length(bridge.variables), 2)
-    return bridge.variables[i.value] =>
-        func, bridge.variables[n+i.value] => zero(MOI.ScalarAffineFunction{T})
+    y = bridge.variables[i.value] => convert(MOI.ScalarAffineFunction{T}, vi)
+    z = bridge.variables[n+i.value] => zero(MOI.ScalarAffineFunction{T})
+    return y, z
 end
 
 function MOI.supports(
@@ -160,17 +170,10 @@ function MOI.set(
     attr::MOI.VariablePrimalStart,
     bridge::FreeBridge,
     value,
-    i::MOIB.IndexInVector,
+    i::MOI.Bridges.IndexInVector,
 )
-    if value < 0
-        nonneg = zero(value)
-        nonpos = -value
-    else
-        nonneg = value
-        nonpos = zero(value)
-    end
     n = div(length(bridge.variables), 2)
-    MOI.set(model, attr, bridge.variables[i.value], nonneg)
-    MOI.set(model, attr, bridge.variables[n+i.value], nonpos)
+    MOI.set(model, attr, bridge.variables[i.value], max(zero(value), value))
+    MOI.set(model, attr, bridge.variables[n+i.value], -min(zero(value), value))
     return
 end