Bridge interface

A bridge should implement the following functions to be usable by a bridge optimizer:

Additionally, variable bridges should implement:

MathOptInterface.Bridges.Variable.concrete_bridge_typeFunction
concrete_bridge_type(
    BT::Type{<:AbstractBridge},
    S::Type{<:MOI.AbstractSet},
)::Type

Return the concrete type of the bridge supporting variables in S constraints. This function can only be called if MOI.supports_constrained_variable(BT, S) is true.

Examples

As a variable in MathOptInterface.GreaterThan is bridged into variables in MathOptInterface.Nonnegatives by the VectorizeBridge:

MOI.Bridges.Variable.concrete_bridge_type(
    MOI.Bridges.Variable.VectorizeBridge{Float64},
    MOI.GreaterThan{Float64},
)

# output

MathOptInterface.Bridges.Variable.VectorizeBridge{Float64, MathOptInterface.Nonnegatives}
MathOptInterface.Bridges.Variable.bridge_constrained_variableFunction
bridge_constrained_variable(
    BT::Type{<:AbstractBridge},
    model::MOI.ModelLike,
    set::MOI.AbstractSet,
)

Bridge the constrained variable in set using bridge BT to model and returns a bridge object of type BT. The bridge type BT should be a concrete type, that is, all the type parameters of the bridge should be set. Use concrete_bridge_type to obtain a concrete type for given set types.

constraint bridges should implement:

MathOptInterface.supports_constraintMethod
MOI.supports_constraint(
    BT::Type{<:AbstractBridge},
    F::Type{<:MOI.AbstractFunction},
    S::Type{<:MOI.AbstractSet},
)::Bool

Return a Bool indicating whether the bridges of type BT support bridging F-in-S constraints.

MathOptInterface.Bridges.Constraint.concrete_bridge_typeFunction
concrete_bridge_type(
    BT::Type{<:AbstractBridge},
    F::Type{<:MOI.AbstractFunction},
    S::Type{<:MOI.AbstractSet}
)::Type

Return the concrete type of the bridge supporting F-in-S constraints. This function can only be called if MOI.supports_constraint(BT, F, S) is true.

Examples

As a MathOptInterface.VariableIndex-in-MathOptInterface.Interval constraint is bridged into a MathOptInterface.VariableIndex-in-MathOptInterface.GreaterThan and a MathOptInterface.VariableIndex-in-MathOptInterface.LessThan by the SplitIntervalBridge:

MOI.Bridges.Constraint.concrete_bridge_type(
    MOI.Bridges.Constraint.SplitIntervalBridge{Float64},
    MOI.VariableIndex,
    MOI.Interval{Float64},
)

# output

MathOptInterface.Bridges.Constraint.SplitIntervalBridge{Float64, MathOptInterface.VariableIndex, MathOptInterface.Interval{Float64}, MathOptInterface.GreaterThan{Float64}, MathOptInterface.LessThan{Float64}}
MathOptInterface.Bridges.Constraint.bridge_constraintFunction
bridge_constraint(
    BT::Type{<:AbstractBridge},
    model::MOI.ModelLike,
    func::AbstractFunction,
    set::MOI.AbstractSet,
)

Bridge the constraint func-in-set using bridge BT to model and returns a bridge object of type BT. The bridge type BT should be a concrete type, that is, all the type parameters of the bridge should be set. Use concrete_bridge_type to obtain a concrete type for given function and set types.

and objective bridges should implement:

MathOptInterface.Bridges.Objective.concrete_bridge_typeFunction
concrete_bridge_type(
    BT::Type{<:MOI.Bridges.Objective.AbstractBridge},
    F::Type{<:MOI.AbstractScalarFunction},
)::Type

Return the concrete type of the bridge supporting objective functions of type F. This function can only be called if MOI.supports_objective_function(BT, F) is true.

MathOptInterface.Bridges.Objective.bridge_objectiveFunction
bridge_objective(
    BT::Type{<:MOI.Bridges.Objective.AbstractBridge},
    model::MOI.ModelLike,
    func::MOI.AbstractScalarFunction,
)

Bridge the objective function func using bridge BT to model and returns a bridge object of type BT. The bridge type BT should be a concrete type, that is, all the type parameters of the bridge should be set. Use concrete_bridge_type to obtain a concrete type for a given function type.

When querying the NumberOfVariables, NumberOfConstraints ListOfVariableIndices, and ListOfConstraintIndices, the variables and constraints created by the bridges in the underlying model are hidden by the bridge optimizer. For this purpose, the bridge should provide access to the variables and constraints it has created by implementing the following methods of get:

MathOptInterface.getMethod
MOI.get(b::AbstractBridge, ::MOI.NumberOfVariables)

The number of variables created by the bridge b in the model.

MathOptInterface.getMethod
MOI.get(b::AbstractBridge, ::MOI.ListOfVariableIndices)

The list of variables created by the bridge b in the model.

MathOptInterface.getMethod
MOI.get(b::AbstractBridge, ::MOI.NumberOfConstraints{F, S}) where {F, S}

The number of constraints of the type F-in-S created by the bridge b in the model.

MathOptInterface.getMethod
MOI.get(b::AbstractBridge, ::MOI.ListOfConstraintIndices{F, S}) where {F, S}

A Vector{ConstraintIndex{F,S}} with indices of all constraints of type F-inS created by the bride b in the model (i.e., of length equal to the value of NumberOfConstraints{F,S}()).

SetMap bridges

Implementing a constraint bridge relying on linear transformation between two sets is easier thanks to the SetMap interface. The bridge simply needs to be a subtype of [Bridges.Variable.SetMapBridge] for a variable bridge and [Bridges.Constraint.SetMapBridge] for a constraint bridge and the linear transformation is represented with Bridges.map_set, Bridges.map_function, Bridges.inverse_map_set, Bridges.inverse_map_function, Bridges.adjoint_map_function and Bridges.inverse_adjoint_map_function. Note that the implementing last 4 methods is optional in the sense that if they are not implemented, bridging constraint would still work but some features would be missing as described in the docstrings. See [L20, Section 2.1.2] for more details including [L20, Example 2.1.1] that illustrates the idea for Bridges.Variable.SOCtoRSOCBridge, Bridges.Variable.RSOCtoSOCBridge, Bridges.Constraint.SOCtoRSOCBridge and Bridges.Constraint.RSOCtoSOCBridge.

[L20] Legat, Benoît. Set Programming: Theory and Computation. PhD thesis. 2020.