API

This section documents the BilevelJuMP API.

As a JuMP extension, most JuMP functions should just work. Some JuMP function will return error saying they are not implemented for BileveJuMP structures such as BilevelModel. If that happens and you consider that function should be implemented, please, open an issue.

Constructors

BilevelJuMP.BilevelModelType
BilevelModel()

Create an empty BilevelModel with default settings, no solver and no solve mode.

Example

julia> model = BilevelModel()
BilevelModel(solver::Function; mode = BilevelJuMP.SOS1Mode(), add_bridges::Bool = true)

Create a BilevelModel with the given solver and solve mode.

  • solver: is a functions that takes no arguments and returns a JuMP solver object.
  • mode: is a solve mode object that defines how the model is solved.
  • add_bridges: if true (default) then bridges are added to the model. If false then bridges are not added and the model is not modified.

Example

julia> model = BilevelModel(
    HiGHS.Optimizer,
    mode = BilevelJuMP.FortunyAmatMcCarlMode(primal_big_M = 1e6, dual_big_M = 1e6))

which is equivalent to

julia> model = BilevelModel(
    ()->HiGHS.Optimizer(),
    mode = BilevelJuMP.FortunyAmatMcCarlMode(primal_big_M = 1e6, dual_big_M = 1e6))

and equivalent to

julia> model = BilevelModel()

julia> BilevelJuMP.set_solver(model, HiGHS.Optimizer)

julia> BilevelJuMP.set_mode(model, BilevelJuMP.FortunyAmatMcCarlMode(primal_big_M = 1e6, dual_big_M = 1e6))
source
BilevelJuMP.UpperFunction
Upper(model::BilevelModel)

Create a reference to the upper level of a bilevel model.

Example

julia> model = BilevelModel();

julia> @variable(Upper(model), x >= 0)
source
BilevelJuMP.LowerFunction
Lower(model::BilevelModel)

Create a reference to the lower level of a bilevel model.

Example

julia> model = BilevelModel();

julia> @variable(Lower(model), x >= 0)
source
BilevelJuMP.DualOfType
DualOf(constraint::ConstraintRef)

Get the dual variable associated with a constraint. This is only valid for constraints in the upper level of a bilevel model.

Examples

julia> m = BilevelModel();

julia> @variable(Lower(m), x >= 0);

julia> @constraint(Lower(m), c, x <= 1);

julia> @variable(Upper(m), y, DualOf(c));
source

Advanced constructors

BilevelJuMP.UpperOnlyFunction
UpperOnly(model::BilevelModel)

Create a special reference to the upper level of a bilevel model. Variables created with this reference will not be shared with the lower level.

source
BilevelJuMP.LowerOnlyFunction
LowerOnly(model::BilevelModel)

Create a special reference to the lower level of a bilevel model. Variables created with this reference will not be shared with the upper level.

source

Enums

BilevelJuMP.LOWER_ONLYConstant

Indicates and object that is part of the lower level problem, but is not shared with the upper level.

source
BilevelJuMP.UPPER_ONLYConstant

Indicates and object that is part of the upper level problem, but is not shared with the lower level.

source
BilevelJuMP.ZERO_ONEConstant

Activates the indicator constraint on the primal constraint if the auxiliaty binary is zero and activates the indicator constraint on the dual variable if the auxiliary binary is one.

source
BilevelJuMP.ZERO_ZEROConstant

Activates the indicator constraint on the primal constraint if the auxiliaty binary is zero and activates the indicator constraint on the dual variable if the auxiliary binary is zero.

source
BilevelJuMP.ONE_ONEConstant

Activates the indicator constraint on the primal constraint if the auxiliaty binary is one and activates the indicator constraint on the dual variable if the auxiliary binary is one.

source

Structs

Modes

BilevelJuMP.SOS1ModeType
SOS1Mode()

Used to solve a bilevel problem with the MPEC reformulation using SOS1 constraints to convert complementarity constraints into mixed-integer constraints.

source
BilevelJuMP.IndicatorModeType
IndicatorMode(method::IndicatorSetting = BilevelJuMP.ONE_ONE)

Used to solve a bilevel problem with the MPEC reformulation using indicator constaints to convert complementarity constraints to a mixed integer formulation.

  • method indicates how the indicator constraints are activated for primal cosntraints and dual variables. See IndicatorSetting for more details.
source
BilevelJuMP.ProductModeType
ProductMode(epsilon = 0.0; with_slack = false, aggregation_group = nothing)

Used to solve a bilevel problem with the MPEC reformulation using products to convert complementarity constraints into non-convex quadratic constraints.

  • with_slack indicates whether to use slack variables to reformulate the complementarity constraints. Given a pair expr and var, the reformulation is expr == slack and var * slack == 0 instead of expr * slack == 0.

  • aggregation_group indicates whether to aggregate the products into a single quadratic constraint. If aggregation_group is nothing, then each product is converted into a quadratic constraint. If aggregation_group is a positive integer, then products with the same aggregation_group are aggregated into a single quadratic constraint.

source
BilevelJuMP.StrongDualityModeType
StrongDualityMode(eps = 0.0, inequality = true)

A mode that adds a strong duality constraint of the lower level problem instead of reformulating the complementarity constraints.

  • eps: The tolerance for the strong duality constraint. Defaults to 0.0.

  • inequality: If true the strong duality constraint is added as two inequality constraints. If false the strong duality constraint is added as an equality constraint. Defaults to true.

source
BilevelJuMP.ComplementModeType
ComplementMode(; with_slack = false)

Used to solve a bilevel problem with the MPEC reformulation using actual complementarity constraints. A limited number of solvers support this mode. One example is Knitro.

  • with_slack indicates whether to use slack variables to reformulate the complementarity constraints. Given a pair expr and var, the reformulation is expr == slack and var ⟂ slack instead of expr ⟂ slack.
source
BilevelJuMP.MixedModeType
MixedMode(; default = SOS1Mode())

A mode that allows to mix different modes for different constraints and variables.

  • default is the default mode to use for all constraints and variables that are not explicitly mapped to a mode.
source

Bound hints

BilevelJuMP.set_dual_upper_bound_hintFunction
set_dual_upper_bound_hint(cref, value)

Set a upper bound to the dual variable of the constraint cref to value. This bound will not be dualized. The dual upper bound hint is used to help the solution method.

Solution modes can be benefitted from this hint:

  • BigMMode will use this information to compute a tighter bound for the dual variable.

  • Other modes will be stabilized by the existence of the bounds on variables that would otherwise no be bounded.

  • Bounds that are not dualized are also useful for binary expansions of products of variables that can be done with QuadraticToBinary.jl.

source
BilevelJuMP.set_dual_lower_bound_hintFunction
set_dual_lower_bound_hint(cref, value)

Set a lower bound to the dual variable of the constraint cref to value. This bound will not be dualized. The dual lower bound hint is used to help the solution method.

Solution modes can be benefitted from this hint:

  • BigMMode will use this information to compute a tighter bound for the dual variable.

  • Other modes will be stabilized by the existence of the bounds on variables that would otherwise no be bounded.

  • Bounds that are not dualized are also useful for binary expansions of products of variables that can be done with QuadraticToBinary.jl.

source
BilevelJuMP.set_primal_upper_bound_hintFunction
set_primal_upper_bound_hint(vref, value)

Set a upper bound to the prima variable vref to value. This bound will not be dualized. The upper bound hint is used to help the solution method.

Solution modes can be benefitted from this hint:

  • BigMMode will use this information to compute a tighter bound for the primal constraint variable.

  • Other modes will be stabilized by the existence of the bounds on variables that would otherwise no be bounded.

  • Bounds that are not dualized are also useful for binary expansions of products of variables that can be done with QuadraticToBinary.jl.

source
BilevelJuMP.set_primal_lower_bound_hintFunction
set_primal_lower_bound_hint(vref, value)

Set a lower bound to the prima variable vref to value. This bound will not be dualized. The lower bound hint is used to help the solution method.

Solution modes can be benefitted from this hint:

  • BigMMode will use this information to compute a tighter bound for the primal constraint variable.

  • Other modes will be stabilized by the existence of the bounds on variables that would otherwise no be bounded.

  • Bounds that are not dualized are also useful for binary expansions of products of variables that can be done with QuadraticToBinary.jl.

source

Attributes getters and setters

BilevelJuMP.set_modeFunction
set_mode(bm::BilevelModel, mode::AbstractBilevelSolverMode)

Set the mode of a bilevel model.

source
set_mode(ci::BilevelVariableRef, mode::AbstractBilevelSolverMode)

Set the mode of a constraint. This is used in MixedMode reformulations.

source
set_mode(vi::BilevelVariableRef, mode::AbstractBilevelSolverMode)

Set the mode of the bounds of a variable. This is used in MixedMode reformulations.

source
BilevelJuMP.get_modeFunction
get_mode(ci::BilevelConstraintRef)

Get the mode of a constraint. This is used in MixedMode reformulations.

source
get_mode(vi::BilevelVariableRef)

Get the mode of the bounds of a variable. This is used in MixedMode reformulations.

source
BilevelJuMP.unset_modeFunction
unset_mode(ci::BilevelConstraintRef)

Unset the mode of a constraint. This will use the default mode for the constraint. This is used in MixedMode reformulations.

source
unset_mode(vi::BilevelVariableRef)

Unset the mode of the bounds of a variable. This will use the default mode for the bounds. This is used in MixedMode reformulations.

source
BilevelJuMP.get_pass_startFunction
get_pass_start(model::BilevelModel)

Checks if passing start values (both primal and dual) to the solver is activated.

source