API Reference

dualize(args...; kwargs...)

The dualize function works in three different ways. The user can provide:

• A MathOptInterface.ModelLike

  The function will return a DualProblem struct that has the dualized model and PrimalDualMap{Float64} for users to identify the links between primal and dual model. The PrimalDualMap{Float64} maps variables and constraints from the original primal model into the respective objects of the dual model.

• A MathOptInterface.ModelLike and a DualProblem{T}

• A JuMP.Model

  The function will return a JuMP model with the dual representation of the problem.

• A JuMP.Model and an optimizer constructor

  The function will return a JuMP model with the dual representation of the problem with the optimizer constructor attached.

On each of these methods, the user can provide the following keyword arguments:

• dual_names: of type DualNames struct. It allows users to set more intuitive names for the dual variables and dual constraints created.

• variable_parameters: A vector of MOI.VariableIndex containing the variables that should not be considered model variables during dualization. These variables will behave like constants during dualization. This is especially useful for the case of bi-level modelling, where the second level depends on some decisions from the upper level.

• ignore_objective: a boolean indicating if the objective function should be added to the dual model. This is also useful for bi-level modelling, where the second level model is represented as a KKT in the upper level model.

• assume_min_if_feasibility: a boolean indicating if the objective function is of type MOI.FEASIBILITY_SENSE then the objective is treated as MOI.MIN_SENSE. Therefore, the dual will have a MOI.MAX_SENSE objective. This is set to false by default, to warn users about the outcome.

dual_optimizer(
    optimizer_constructor;
    coefficient_type::Type{T} = Float64,
    kwargs...,
) where {T<:Number}

A user-friendly constructor for DualOptimizer that can be passed directly to the JuMP Model constructor.

Example

julia> using Dualization, JuMP, HiGHS

julia> model = Model(dual_optimizer(HiGHS.Optimizer))
A JuMP Model
Feasibility problem with:
Variables: 0
Model mode: AUTOMATIC
CachingOptimizer state: EMPTY_OPTIMIZER
Solver name: Dual model with HiGHS attached

DualOptimizer(dual_optimizer::OT) where {OT <: MOI.ModelLike}

The DualOptimizer finds the solution for a problem by solving its dual representation. It builds the dual model internally and solve it using the dual_optimizer as the solver.

Primal results are obtained by querying dual results of the internal problem solved by dual_optimizer. Analogously, dual results are obtained by querying primal results of the internal problem.

The user can define the model providing the DualOptimizer and the solver of its choice.

Example

julia> using Dualization, JuMP, HiGHS

julia> model = Model(dual_optimizer(HiGHS.Optimizer))
A JuMP Model
Feasibility problem with:
Variables: 0
Model mode: AUTOMATIC
CachingOptimizer state: EMPTY_OPTIMIZER
Solver name: Dual model with HiGHS attached

DualNames(dual_variable_name_prefix, dual_constraint_name_prefix)

A struct to pass the prefix of dual variables and dual constraints names to the dual_names keyword argument of dualize.

Example

julia> using JuMP, Dualization

julia> begin
           model = Model()
           @variable(model, x)
           @constraint(model, c, x >= 1)
           @objective(model, Min, x)
           dual_model = dualize(model; dual_names = DualNames("dual_var_", "dual_con_"))
       end;

julia> print(model)
Min x
Subject to
 c : x ≥ 1

julia> print(dual_model)
Max dual_var_c
Subject to
 dual_con_x : dual_var_c = 1
 dual_var_c ≥ 0

supported_constraint(::Type{F}, ::Type{S})

Return true if Dualization supports dualizing the constraint type F-in-S.

supported_constraints(con_types::Vector{Tuple{Type, Type}})

Returns true if Function-in-Set is supported for Dualization and throws an error if it is not.

supported_constraints(F::MOI.AbstractFunction, S::MOI.AbstractSet)

Returns true if Function-in-Set is supported for Dualization and false if it is not.

supported_objective(primal_model::MOI.ModelLike)

Returns true if MOI.ObjectiveFunctionType() is supported for Dualization and throws an error if it is not.

supported_objective(obj_func_type::Type)

Returns true if obj_func_type is supported for Dualization and throws an error if it is not.

PrimalVariableData{T}

Data structure used in PrimalDualMap to hold information about primal variables and their dual counterparts.

• primal_constrained_variable_constraint::Union{Nothing,MOI.ConstraintIndex}: if primal variable is chosen to be a constrained variable by Dualization.jl, then this value is different from nothing.

• primal_constrained_variable_index::Int: if variable is a scalar constrained variable then it is 0. If variable is not a constrained variable then it is -1. If variable is part of a vector constrained variable, then this is the position in that vector.

• dual_constraint::Union{Nothing,MOI.ConstraintIndex}: dual constraint associated with the variable. If the variable is not constrained then the set is EqualTo{T}(zero(T)). If the variable is a constrained variable then the set is the dual set of the constrained variable set. If the dual set is Reals then the field is kept as nothing as teh constraint is not added.

• dual_function::Union{Nothing,MOI.ScalarAffineFunction{T}}: if the constrained variable is VectorOfVariables-in-Zeros or VariableIndex-in-EqualTo(zero(T)) then the dual is func-in-Reals, which is "irrelevant" to the model. But this information is cached for completeness of the DualOptimizer for getting ConstraintDuals.

To got from the constrained variable constraint to the primal variable, use the primal_constrained_variables field of PrimalDualMap.

See also PrimalDualMap and PrimalConstraintData.

PrimalConstraintData{T}

Data structure used in PrimalDualMap to hold information about primal constraints and their dual counterparts.

Constraint indices for constrained variables are not in this structure. They are added in the primal_constrained_variables field of PrimalDualMap.

• primal_set_constants::Vector{T}: a vector of primal set constants that are used in MOI getters. This is used to get the primal constants of the primal constraints.

• dual_variables::Vector{MOI.VariableIndex}: vector of dual variables. If primal constraint is scalar then, the vector has length = 1.

• dual_constrained_variable_constraint::Union{Nothing,MOI.ConstraintIndex}: if primal set is EqualTo or Zeros, then the dual constraint is Reals then the dual variable is free (no constraint in the dual model).

PrimalDualMap{T}

Maps information from all structures of the primal to the dual model.

Main maps:

• primal_variable_data::Dict{MOI.VariableIndex,Dualization.PrimalVariableData{T}}: maps primal variable indices to their data. The data is a structure that contains information about the primal variable and its dual counterpart. In particular, it contains the primal constrained variable constraint index, the primal constrained variable index, the dual constraint index and the primal function for the case of constraints that are not added in the dual.

• primal_constraint_data::Dict{MOI.ConstraintIndex,Dualization.PrimalConstraintData{T}}: maps primal constraint indices to their data. The data is a structure that contains information about the primal constraint and its dual counterpart. In particular, it contains the primal set constants, the dual variables and the dual constrained variable constraint index.

• primal_constrained_variables::Dict{MOI.ConstraintIndex,Vector{MOI.VariableIndex}}: maps primal constrained variable constraint indices to their primal constrained variables.

Addtional maps

• primal_parameter_to_dual_parameter::Dict{MOI.VariableIndex,MOI.VariableIndex}: maps parameters in the primal model to parameters in the dual model.

• primal_var_in_quad_obj_to_dual_slack_var::Dict{MOI.VariableIndex,MOI.VariableIndex}: maps primal variables (that appear in quadratic objective terms) to dual "slack" variables. These primal variables might appear in other maps.