Bridge interface
To be usable by a bridge optimizer, a bridge must implement the following functions:
MathOptInterface.Bridges.added_constrained_variable_types
— Functionadded_constrained_variable_types(
BT::Type{<:Variable.AbstractBridge},
)::Vector{Tuple{Type}}
Return a list of the types of constrained variables that bridges of concrete type BT
add. This is used by the LazyBridgeOptimizer
.
MathOptInterface.Bridges.added_constraint_types
— Functionadded_constraint_types(
BT::Type{<:Constraint.AbstractBridge},
)::Vector{Tuple{Type, Type}}
Return a list of the types of constraints that bridges of concrete type BT
add. This is used by the LazyBridgeOptimizer
.
Additionally, variable bridges must implement:
MathOptInterface.Bridges.Variable.supports_constrained_variable
— Functionsupports_constrained_variable(
::Type{<:AbstractBridge},
::Type{<:MOI.AbstractSet},
)::Bool
Return a Bool
indicating whether the bridges of type BT
support bridging constrained variables in S
.
MathOptInterface.Bridges.Variable.concrete_bridge_type
— Functionconcrete_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_variable
— Functionbridge_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 must implement:
MathOptInterface.supports_constraint
— MethodMOI.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_type
— Functionconcrete_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_constraint
— Functionbridge_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 must implement:
MathOptInterface.Bridges.set_objective_function_type
— Functionset_objective_function_type(
BT::Type{<:Objective.AbstractBridge},
)::Type{<:MOI.AbstractScalarFunction}
Return the type of objective function that bridges of concrete type BT
set. This is used by the LazyBridgeOptimizer
.
MathOptInterface.Bridges.Objective.concrete_bridge_type
— Functionconcrete_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_objective
— Functionbridge_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 must provide access to the variables and constraints it has created by implementing the following methods of get
:
MathOptInterface.get
— MethodMOI.get(b::AbstractBridge, ::MOI.NumberOfVariables)
The number of variables created by the bridge b
in the model.
MathOptInterface.get
— MethodMOI.get(b::AbstractBridge, ::MOI.ListOfVariableIndices)
The list of variables created by the bridge b
in the model.
MathOptInterface.get
— MethodMOI.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.get
— MethodMOI.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.