Transformation Backends

A technical manual for optimizing (solving) InfiniteOpt models via transformation backends. See the respective guide for more information.

Optimize

JuMP.optimize!Method
JuMP.optimize!(model::InfiniteModel; [kwargs...])

Extend JuMP.optimize! to optimize infinite models using the internal transformation backend. Calls build_transformation_backend! if the optimizer model isn't up-to-date. The kwargs correspond to keyword arguments passed to build_transformation_backend! if any are defined. The kwargs can also include arguments that are passed to an optimize hook if one was set with JuMP.set_optimize_hook. Typically, this returns nothing, but certain backends may return something.

Example

julia> optimize!(model)

julia> has_values(model)
true
source

Backend Settings/Queries

InfiniteOpt.transformation_modelMethod
transformation_model(model::InfiniteModel)

Return the underlying model used by the transformation backend.

Example

julia> trans_model = transformation_model(model)
A JuMP Model
├ solver: none
├ objective_sense: FEASIBILITY_SENSE
├ num_variables: 0
├ num_constraints: 0
└ Names registered in the model: none
source
InfiniteOpt.transformation_dataMethod
transformation_data(model::InfiniteModel)

Return the underlying data (typically mapping data) used by the transformation backend.

Example

julia> mapping_data = transformation_data(model);
source
InfiniteOpt.transformation_backendFunction
transformation_backend(
    model::InfiniteModel
    )::AbstractTransformationBackend

Retrieve the transformation backend used by the model.

Example

julia> transformation_backend(model)
A TranscriptionBackend that uses a
A JuMP Model
├ solver: none
├ objective_sense: FEASIBILITY_SENSE
├ num_variables: 0
├ num_constraints: 0
└ Names registered in the model: none
source
InfiniteOpt.set_transformation_backendFunction
set_transformation_backend(
    model::InfiniteModel, 
    backend::AbstractTransformationBackend
    )::Nothing

Specify a new transformation backend backend for the model. Note that all data/settings/results associated with the previous backend will be removed.

Example

julia> transformation_backend(model)
A TranscriptionBackend that uses a
A JuMP Model
├ solver: none
├ objective_sense: FEASIBILITY_SENSE
├ num_variables: 0
├ num_constraints: 0
└ Names registered in the model: none

julia> set_transformation_backend(model, TranscriptionBackend(Ipopt.Optimizer))

julia> transformation_backend(model)
A TranscriptionBackend that uses a
A JuMP Model
├ solver: Ipopt
├ objective_sense: FEASIBILITY_SENSE
├ num_variables: 0
├ num_constraints: 0
└ Names registered in the model: none
source
InfiniteOpt.build_transformation_backend!Method
build_transformation_backend!(model::InfiniteModel; [kwargs...])::Nothing

Build the model used by the underlying transformation backend stored in model such that it is ready to solve. Specifically, translate the InfiniteOpt formulation stored in model into (typically an appoximate) formulation that is compatible with the backend. This is called automatically by optimize!; however, it this method can be used to build the transformation backend without solving it.

Example

julia> build_transformation_backend!(model)

julia> transformation_backend_ready(model)
true
source
InfiniteOpt.transformation_variableMethod
transformation_variable(vref::GeneralVariableRef; [kwargs...])

Returns the variable(s) used by the transformation backend to represent vref. Certain backends may also allow the use of keyward arguments.

The default backend TranscriptionOpt uses the keyword arguments:

  • label::Type{<:AbstractSupportLabel} = PublicLabel

By default only variables corresponding to public supports are returned, the full set can be accessed via label = All. Where possible, all the transcripted variables of infinite variables are returned as an n-dimensional array where each dimension is determined by the each independent group of infinite parameters it depends on.

Example

julia> transformation_variable(x) # infinite variable
2-element Array{VariableRef,1}:
 x(0.0)
 x(1.0)

julia> transformation_variable(z) # finite variable
z
source
InfiniteOpt.transformation_expressionMethod
transformation_expression(
    expr::JuMP.AbstractJuMPScalar; 
    [label::Type{<:AbstractSupportLabel} = PublicLabel,
    kwargs...]
    )

Return the reformulation expression(s) stored in the transformation backend that correspond to expr. Also errors if no such expression can be found in the transformation backend (meaning one or more of the underlying variables have not been transformed).

The keyword argument label is what TranscriptionOpt employs and kwargs denote extra ones that user extensions may employ in accordance with their implementation of transformation_expression. Errors if such an extension has not been written.

By default only the expressions associated with public supports are returned, the full set can be accessed via label = All. Where possible, all the transformed expressions are returned as an n-dimensional array where each dimension is determined by the each independent group of infinite parameters it depends on. The corresponding supports are obtained via supports using the same keyword arguments.

Example

julia> transformation_expression(my_expr) # finite expression
x(0.0) - y
source
InfiniteOpt.transformation_constraintMethod
transformation_constraint(
    cref::InfOptConstraintRef; 
    [label::Type{<:AbstractSupportLabel} = PublicLabel, 
    kwargs...]
    )

Return the reformulation constraint(s) stored in the transformation backend that correspond to cref. Errors if no such constraint can be found in the transformation backend.

The keyword argument label is what TranscriptionOpt employs and kwargs denote extra ones that user extensions may employ in accordance with their implementation of transformation_constraint. Errors if such an extension has not been written.

By default only the constraints associated with public supports are returned, the full set can be accessed via label = All. Where possible, all the transformed cosntraints are returned as an n-dimensional array where each dimension is determined by the each independent group of infinite parameters it depends on. The corresponding supports are obtained via supports using the same keyword arguments.

Example

julia> transformation_constraint(c1) # finite constraint
c1 : x(0.0) - y <= 3.0
source
InfiniteOpt.supportsMethod
supports(
    vref::DecisionVariableRef; 
    [label::Type{<:AbstractSupportLabel} = PublicLabel, 
    kwargs...]
    )::Vector{<:Tuple}

Return the supports associated with vref in the transformation model. Errors if InfiniteOpt.variable_supports has not been extended for the transformation backend type or if vref is not reformulated in the transformation backend.

The keyword argument label is what TranscriptionOpt employs and kwargs denote extra ones that user extensions may employ in accordance with their implementation of variable_supports. Errors if such an extension has not been written.

By default only the public supports are returned, the full set can be accessed via label = All. Where possible, all the supports of infinite variables are returned as an n-dimensional array where each dimension is determined by the each independent group of infinite parameters it depends on.

Example

julia> supports(vref)
2-element Array{Tuple{Float64},1}:
 (0.0,)
 (1.0,)
source
InfiniteOpt.supportsMethod
supports(
    expr::JuMP.AbstractJuMPScalar; 
    [label::Type{<:AbstractSupportLabel} = PublicLabel,
    kwargs...]
    )

Return the support associated with expr. Errors if expr is not associated with the constraint mappings stored in the transformation backend.

The keyword arguments label is what TranscriptionOpt employs and kwargs denote extra ones that user extensions may employ in accordance with their implementation of expression_supports. Errors if such an extension has not been written.

By default only the public supports are returned, the full set can be accessed via label = All. Where possible, all the supports of an infinite expression are returned as an n-dimensional array where each dimension is determined by the each independent group of infinite parameters it depends on.

Example

julia> supports(cref)
2-element Array{Tuple{Float64},1}:
 (0.0,)
 (1.0,)
source
InfiniteOpt.supportsMethod
supports(cref::InfOptConstraintRef; 
         [label::Type{<:AbstractSupportLabel} = PublicLabel,
         kwargs...])

Return the support associated with cref. Errors if cref is not associated with the constraint mappings stored in the transformation backend.

The keyword argument label is what TranscriptionOpt employs and kwargs denote extra ones that user extensions may employ in accordance with their implementation of constraint_supports. Errors if such an extension has not been written.

By default only the public supports are returned, the full set can be accessed via label = All. Where possible, all the supports of the constraint are returned as an n-dimensional array where each dimension is determined by the each independent group of infinite parameters it depends on.

Example

julia> supports(cref)
2-element Array{Tuple{Float64},1}:
 (0.0,)
 (1.0,)
source
JuMP.set_optimizerMethod
JuMP.set_optimizer(
    model::InfiniteModel,
    [optimizer_constructor;
    add_bridges::Bool = true, 
    kwargs...]
    )

Extend JuMP.set_optimizer to set optimizer used by the underlying transformation backend associated with model. If a backend uses JuMP then add_bridges can be used as a keyword argument.

Example

julia> set_optimizer(model, HiGHS.Optimizer)

julia> transformation_model(model)
A JuMP Model
├ solver: HiGHS
├ objective_sense: FEASIBILITY_SENSE
├ num_variables: 0
├ num_constraints: 0
└ Names registered in the model: none
source
JuMP.set_silentMethod
JuMP.set_silent(model::InfiniteModel)

Extend JuMP.set_silent to accept InfiniteModels. This relies on the underlying transformation backend supporting JuMP.set_attribute with attribute MathOptInterface.Silent().

source
JuMP.unset_silentMethod
JuMP.unset_silent(model::InfiniteModel)

Extend JuMP.unset_silent to accept InfiniteModels. This relies on the underlying transformation backend supporting JuMP.set_attribute with attribute MathOptInterface.Silent().

source
JuMP.set_time_limit_secMethod
JuMP.set_time_limit_sec(model::InfiniteModel, value::Real)

Extend JuMP.set_time_limit_sec to accept InfiniteModels. This relies on the underlying transformation backend supporting JuMP.set_attribute with attribute MOI.TimeLimitSec().

source
JuMP.time_limit_secMethod
JuMP.time_limit_sec(model::InfiniteModel)

Extend JuMP.time_limit_sec to accept InfiniteModels. This relies on the underlying transformation backend supporting JuMP.get_attribute with attribute MathOptInterface.TimeLimitSec().

source
JuMP.solver_nameMethod
JuMP.solver_name(model::InfiniteModel)

Extend JuMP.solver_name to accept InfiniteModels. This relies on the underlying transformation backend supporting JuMP.get_attribute with attribute MathOptInterface.SolverName().

source
JuMP.modeMethod
JuMP.mode(model::InfiniteModel)

Extend JuMP.mode to accept InfiniteModels. This relies on the underlying transformation backend supporting JuMP.mode.

source
JuMP.copy_conflictMethod
JuMP.copy_conflict(model::InfiniteModel)

Extend JuMP.copy_conflict to accept InfiniteModels. This relies on the underlying transformation backend supporting JuMP.copy_conflict.

source
JuMP.add_bridgeMethod
JuMP.add_bridge(model::InfiniteModel, value)

Extend JuMP.add_bridge to accept InfiniteModels. This relies on the underlying transformation backend supporting JuMP.add_bridge.

source
JuMP.print_active_bridgesMethod
JuMP.print_active_bridges([io::IO = stdout,] model::InfiniteModel)

JuMP.print_active_bridges([io::IO = stdout,] model::InfiniteModel, ::Type{<:JuMP.AbstractJuMPScalar})

JuMP.print_active_bridges([io::IO = stdout,] model::InfiniteModel, ::Type{<:JuMP.AbstractJuMPScalar}, ::Type{<:MOI.AbstractSet})

JuMP.print_active_bridges([io::IO = stdout,] model::InfiniteModel, ::Type{<:MOI.AbstractSet})

Extend JuMP.print_active_bridges to accept InfiniteModels. This relies on the underlying transformation backend supporting JuMP.print_active_bridges.

source
JuMP.set_attributeMethod
JuMP.set_attribute(model::InfiniteModel, attr, value)::Nothing

Specify an attribute attr to the transformation backend of model. Typically, this corresponds to MOI.AbstractOptimizerAttributes.

Example

julia> set_attribute(model, MOI.TimeLimitSec(), 42.0)
source
JuMP.set_attributesFunction
JuMP.set_attributes(model::InfiniteModel, pairs::Pair...)::Nothing

Specify multiple optimizer transformation backend attributes as Pairs of the form attr => value which are used for set_attribute(model, attr, value).

Example

julia> set_attributes(model, "tol" => 1e-4, "max_iter" => 100)
source
JuMP.get_attributeMethod
JuMP.get_attribute(model::InfiniteModel, attr)

Retrieve an attribute attr from the transformation backend of model. Typically, this corresponds to MOI.AbstractOptimizerAttributes.

Example

julia> get_attribute(model, MOI.TimeLimitSec())
60.0
source
JuMP.backendMethod
JuMP.backend(model::InfiniteModel)

Extend JuMP.backend to accept InfiniteModels. This relies on the underlying transformation backend supporting JuMP.backend.

source

Transformation Backend API

InfiniteOpt.JuMPBackendType
JuMPBackend{TAG <: AbstractJuMPTag, T, D} <: AbstractTransformationBackend

A transformation backend type for transformation backends that use JuMP Models. This serves as the main extension point for defining new JuMP-based backends. In which case a new AbstractJuMPTag should be made with which the JuMPBackend is created:

backend = JuMPBackend{MyTag}(model::JuMP.GenericModel, data)

where data stores information used by the backend (typically mapping information to the overlying InfiniteModel).

The JuMP Model can be accessed by transformation_model and the data can be retrieved via transformation_data.

source
InfiniteOpt.transformation_modelMethod
transformation_model(backend::AbstractTransformationBackend)

Return the underlying model used by the backend. This serves as an extension point for new backend types. No extension is needed for JuMPBackends.

source
InfiniteOpt.transformation_dataMethod
transformation_data(backend::AbstractTransformationBackend)

Return the underlying data (typically mapping data) used by the backend. This serves as an extension point for new backend types. No extension is needed for JuMPBackends.

source
JuMP.get_attributeMethod
JuMP.get_attribute(backend::AbstractTransformationBackend, attr)

Retrieve some attribute attr from the backend. This is a general purpose method typically used to query optimizer related information. This serves as an extension point for new backend types. New backends should include extensions for the following attributes as appropriate: - MOI.Silent - MOI.TimeLimitSec - MOI.RawOptimizerAttribute - MOI.SolverName - MOI.TerminationStatus - MOI.RawStatusString - MOI.PrimalStatus - MOI.DualStatus - MOI.SolveTimeSec - MOI.ResultCount - MOI.SimplexIterations - MOI.BarrierIterations - MOI.NodeCount - MOI.ObjectiveBound - MOI.RelativeGap - MOI.ObjectiveValue - MOI.DualObjectiveValue

No extension is needed for JuMPBackends.

source
JuMP.set_attributeMethod
JuMP.set_attribute(backend::AbstractTransformationBackend, attr, value)::Nothing

Specify some attribute attr to the backend. This is a general purpose method typically used to set optimizer related information. This serves as an extension point for new backend types. New backends should include extensions for attributes of type: - MOI.Silent - MOI.TimeLimitSec - MOI.RawOptimizerAttribute

No extension is needed for JuMPBackends.

source
Base.empty!Method
Base.empty!(backend::AbstractTransformationBackend)

Empty backend of all its contents. For new backend types, this needs to be defined such that empty!(model::InfiniteModel) works. For JuMPBackends this defaults to

empty!(transformation_model(backend))
empty!(transformation_data(backend))
source
InfiniteOpt.build_transformation_backend!Method
build_transformation_backend!(
    model::InfiniteModel, 
    backend::AbstractTransformationBackend;
    [kwargs...]
    )::Nothing

Given model, transform it into the representation used by backend. Once completed, backend should be ready to be solved. This serves as an extension point for new types of backends. If needed, keyword arguments can be added. Typically, this should clear out the backend before reconstructing it.

source
JuMP.optimize!Method
JuMP.optimize!(backend::AbstractTransformationBackend)

Invoke the relevant routines to solve the underlying model used by backend. Note that build_transformation_backend! will be called before this method is. This needs to be extended for new backend types, but no extension is needed for JuMPBackends. Optionally, information can be returned if desired.

source
JuMP.set_optimizerMethod
JuMP.set_optimizer(
    backend::AbstractTransformationBackend,
    optimizer_constructor;
    [kwargs...]
    )::Nothing

Specify the optimizer optimizer_constructor that should be used by backend. This is intended as an extension point for new transformation backend types. Keyword arguments can be added as needed. No extension is necessary for JuMPBackends.

source
JuMP.modeMethod
JuMP.mode(backend::AbstractTransformationBackend)

Implement JuMP.mode for transformation backends. If applicable, this should be extended for new backend types. No extension is needed for JuMPBackends.

source
JuMP.add_bridgeMethod
JuMP.add_bridge(backend::AbstractTransformationBackend, value)

Implement JuMP.add_bridge for transformation backends. If applicable, this should be extended for new backend types. No extension is needed for JuMPBackends.

source
JuMP.print_active_bridgesMethod
JuMP.print_active_bridges(
    io::IO, 
    backend::AbstractTransformationBackend, 
    args...
    )

Implment JuMP.print_active_bridges for transformation backends. If applicable, this should be extended for new backend types. No extension is needed for JuMPBackends. Here, args can be one of the following:

  • empty (print all the bridges)
  • the objective type (print the objective bridges)
  • a function type and set type from a constraint
  • a constraint set type
source
JuMP.print_bridge_graphMethod
JuMP.print_bridge_graph(
    io::IO, 
    backend::AbstractTransformationBackend
    )

Implment JuMP.print_bridge_graph for transformation backends. If applicable, this should be extended for new backend types. No extension is needed for JuMPBackends.

source
JuMP.backendMethod
JuMP.backend(backend::AbstractTransformationBackend)

Implement JuMP.backend for transformation backends. If applicable, this should be extended for new backend types. No extension is needed for JuMPBackends.

source
InfiniteOpt.transformation_variableMethod
transformation_variable(
    vref::GeneralVariableRef, 
    backend::AbstractTransformationBackend; 
    [kwargs...]
    )

Return the variable(s) that map to vref used by backend. This serves as an extension point for new backend types. If needed, keywords arguments can be added.

source
InfiniteOpt.transformation_expressionMethod
transformation_expression(expr, backend::AbstractTransformationBackend; [kwargs...])

Return the reformulation expression(s) stored in the transformation backend that correspond to expr. This needs to be defined for extensions that implement a new AbstractTransformationBackend. Keyword arguments can be added as needed. Note that if expr is a GeneralVariableRef this just dispatches to transformation_variable.

source
InfiniteOpt.transformation_constraintMethod
transformation_constraint(
    cref::InfOptConstraintRef,
    backend::AbstractTransformationBackend; 
    [kwargs...]
    )

Return the reformulation constraint(s) stored in the transformation backend that correspond to cref. This needs to be defined for extensions that implement a custom transformation backend type. Keyword arguments can be added as needed.

source
InfiniteOpt.variable_supportsMethod
variable_supports(
    vref::DecisionVariableRef,
    backend::AbstractTransformationBackend;
    [kwargs...]
    )

Return the supports associated with the mappings of vref in backend. This dispatches off of backend which permits transformation backend extensions. This should throw an error if vref is not associated with the variable mappings stored in backend. Keyword arguments can be added as needed. Note that no extension is necessary for point or finite variables.

source
InfiniteOpt.expression_supportsMethod
expression_supports(
    expr,
    backend::AbstractTransformationBackend;
    [kwargs...]
    )

Return the supports associated with the mappings of expr in backend. This should throw an error if expr is not associated with the variable mappings stored in backend. Keyword arguments can be added as needed. Note that if expr is a GeneralVariableRef this just dispatches to variable_supports.

source
InfiniteOpt.constraint_supportsMethod
constraint_supports(
    cref::InfOptConstraintRef
    backend::AbstractTransformationBackend; 
    [kwargs...]
    )

Return the supports associated with the mappings of cref in backend. This should throw an error if cref is not associated with the variable mappings stored in backend. Keyword arguments can be added as needed.

source
InfiniteOpt.transformation_backend_readyFunction
transformation_backend_ready(model::InfiniteModel)::Bool

Return Bool if the transformation backend model is up-to-date with model and ready to be optimized.

Example

julia> transformation_backend_ready(model)
false
source
InfiniteOpt.set_transformation_backend_readyFunction
set_transformation_backend_ready(model::InfiniteModel, status::Bool)::Nothing

Set the status of the transformation backend model to whether it is up-to-date or not. Note is more intended as an internal function, but is useful for extensions.

Example

julia> set_transformation_backend_ready(model, true)

julia> transformation_backend_ready(model)
true
source