Model Transcription

TranscriptionModel([optimizer_constructor;
                   caching_mode::MOIU.CachingOptimizerMode = MOIU.AUTOMATIC,
                   bridge_constraints::Bool = true])::JuMP.Model

Return a JuMP.Model with TranscriptionData included in the ext data field. Accepts the same arguments as a typical JuMP Model. More detailed variable and constraint naming can be enabled via verbose_naming.

Example

julia> TranscriptionModel()
A JuMP Model
Feasibility problem with:
Variables: 0
Model mode: AUTOMATIC
CachingOptimizer state: NO_OPTIMIZER
Solver name: No optimizer attached.

TranscriptionData

A DataType for storing the data mapping an InfiniteOpt.InfiniteModel that has been transcribed to a regular JuMP.Model that contains the transcribed variables. This is stored in the ext field of a JuMP.Model to make what is called a TranscriptionModel via the TranscriptionModel constructor.

Fields

• infvar_lookup::Dict{InfiniteOpt.GeneralVariableRef, Dict{Vector{Float64}, Int}}: A lookup table of infinite variable transcriptions via support value.
• infvar_mappings::Dict{InfiniteOpt.GeneralVariableRef, Vector{JuMP.VariableRef}}: Map infinite variables to their transcription variables.
• infvar_supports::Dict{InfiniteOpt.GeneralVariableRef, Vector{Tuple}}: Map infinite variables to their support values.
• infvar_support_labels::Dict{InfiniteOpt.GeneralVariableRef, Vector{Set{DataType}}}: Map the infinite variables to their support labels.
• finvar_mappings::Dict{InfiniteOpt.GeneralVariableRef, JuMP.VariableRef}: Map finite variables to their transcription variables.
• semi_infinite_vars::Vector{InfiniteOpt.SemiInfiniteVariable{InfiniteOpt.GeneralVariableRef}}: Store the core semi-infinite variable objects of semi-infinite variables formed on transcription.
• semi_lookup::Dict{Tuple{InfiniteOpt.GeneralVariableRef, Dict{Int, Float64}}, InfiniteOpt.GeneralVariableRef}: Lookup which semi-infinite variables have already been added.
• last_point_index::Int: The last internal point variable index added.
• point_lookup::Dict{Tuple{InfiniteOpt.GeneralVariableRef, Vector{Float64}}, InfiniteOpt.GeneralVariableRef}: Lookup which point variables have already been created internally.
• measure_lookup::Dict{InfiniteOpt.GeneralVariableRef, Dict{Vector{Float64}, Int}}: A lookup table of measure transcriptions via support value.
• measure_mappings::Dict{InfiniteOpt.GeneralVariableRef, Vector{JuMP.AbstractJuMPScalar}}: Map measures to transcription expressions.
• measure_supports::Dict{InfiniteOpt.GeneralVariableRef, Vector{Tuple}}: Map measures to their supports values (if the transcribed measure is still infinite).
• measure_support_labels::Dict{InfiniteOpt.GeneralVariableRef, Vector{Set{DataType}}}: Map measures to their support labels if they have any.
• constr_mappings::Dict{InfiniteOpt.InfOptConstraintRef, Vector{JuMP.ConstraintRef}}: Map constraints to their transcriptions.
• constr_supports::Dict{InfiniteOpt.InfOptConstraintRef, Vector{Tuple}}: Map constraints to their support values.
• constr_support_labels::Dict{InfiniteOpt.InfOptConstraintRef, Vector{Set{DataType}}}: Map constraints to their support labels.
• supports::Tuple: Store the collected parameter supports here.
• support_labels::Tuple: Store the collected parameter labels here.
• has_internal_supports::Bool: Where any internal supports collected?

set_parameter_supports(trans_model::JuMP.Model,
                       inf_model::InfiniteOpt.InfiniteModel)::Nothing

Collect the infinite parameter supports stored in their respective dictionaries form inf_model and process them into a tuple of vectors where each vector contains the collected supports of a particular infinite parameter. These support collections are ordered in accordance with the definition order of the parameters (i.e., their object numbers). A support collection assocciated with an independent will be a Vector{Float64} and a support collection associated with a group of dependent parameters will be a Vector{Vector{Float64}}. Note that each collection vector will include an extra final placeholder element comprised of NaNs for convenience in generating support indices via support_index_iterator. This also gathers the associated support labels.

Before this is all done, InfiniteOpt.add_generative_supports is invoked as needed.

transcribe_finite_variables!(trans_model::JuMP.Model,
                           inf_model::InfiniteOpt.InfiniteModel)::Nothing

Create a transcription variable (i.e., a JuMP variable) for each FiniteVariable stored in inf_model and add it to trans_model. The variable mapping is also stored in TranscriptionData.finvar_mappings which enables transcription_variable and lookup_by_support.

transcribe_infinite_variables!(trans_model::JuMP.Model,
                               inf_model::InfiniteOpt.InfiniteModel)::Nothing

Create transcription variables (i.e., JuMP variables) for each InfiniteVariable stored in inf_model and add them to trans_model. The variable mappings are also stored in TranscriptionData.infvar_mappings in accordance with TranscriptionData.infvar_lookup which enable transcription_variable and lookup_by_support. Note that the supports will not be generated until InfiniteOpt.variable_supports is invoked via InfiniteOpt.supports. Note that TranscriptionData.infvar_support_labels is also populated.

transcribe_derivative_variables!(trans_model::JuMP.Model,
                                 inf_model::InfiniteOpt.InfiniteModel)::Nothing

Create transcription variables (i.e., JuMP variables) for each Derivative stored in inf_model and add them to trans_model. The variable mappings are also stored in TranscriptionData.infvar_mappings in accordance with TranscriptionData.infvar_lookup which enable transcription_variable and lookup_by_support. Note that the supports will not be generated until InfiniteOpt.variable_supports is invoked via InfiniteOpt.supports. The futher derivative evaluation constraints are added when transcribe_derivative_evaluations! is invoked. Note that TranscriptionData.infvar_support_labels is also populated.

transcribe_semi_infinite_variables!(trans_model::JuMP.Model,
                              inf_model::InfiniteOpt.InfiniteModel)::Nothing

Map each SemiInfiniteVariable in inf_model to transcription variables stored in trans_model. The variable mappings are also stored in TranscriptionData.infvar_mappings in accordance with TranscriptionData.infvar_lookup which enable transcription_variable and lookup_by_support. Note that transcribe_infinite_variables! must be called first. Note that the supports will not be generated until InfiniteOpt.variable_supports is invoked via InfiniteOpt.supports. Note that TranscriptionData.infvar_support_labels is also populated.

transcribe_point_variables!(trans_model::JuMP.Model,
                           inf_model::InfiniteOpt.InfiniteModel)::Nothing

Map each PointVariable in inf_model to a transcription variable stored in trans_model. The variable mapping is also stored in TranscriptionData.finvar_mappings which enables transcription_variable and lookup_by_support. Note that transcribe_infinite_variables! must be called first and that the info constraints associated with the transcription variable will be updated in accordance with the point variable.

transcription_expression(
    model::JuMP.Model,
    expr::JuMP.AbstractJuMPScalar;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
    ndarray::Bool = false])

Return the transcribed expression(s) corresponding to expr. Errors if expr cannot be transcribed. Also can query via the syntax:

transcription_expression(expr::JuMP.AbstractJuMPScalar;
                         [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
                         ndarray::Bool = false])

If the infinite model contains a built transcription model. By default, this method returns only transcribed expressions associated with public supports. All the expressions can be returned by setting label = All.

If expr is infinite and ndarray = true then an n-dimensional array will be returned in accordance with the infinite parameters that have unique object numbers. In this case, label will be used to search the intersection of the supports that use the label. This is defers from the default behavior which considers the union.

Example

julia> transcription_expression(trans_model, my_expr)
x(support: 1) - y

julia> transcription_expression(my_expr)
x(support: 1) - y

transcription_expression(trans_model::JuMP.Model, expr, support::Vector{Float64})

Given the expr from an InfiniteModel, form its transcripted version in accordance with the variable mappings available in trans_model defined at support. This should only be used once all variables and measures have been transcribed (e.g., via transcribe_finite_variables!).

transcribe_measures!(trans_model::JuMP.Model,
                     inf_model::InfiniteOpt.InfiniteModel)::Nothing

For each Measure in inf_model expand it via InfiniteOpt.expand_measure or analytic_expansion as appropriate and transcribe the expanded expression via transcription_expression. Then store the measure to transcripted expression mappings in TranscriptionData.measure_mappings and TranscriptionData.measure_lookup to enable transcription_variable and lookup_by_support. Note that the supports will not be generated until InfiniteOpt.variable_supports is invoked via InfiniteOpt.supports. Note that TranscriptionData.measure_support_labels is also populated.

transcribe_objective!(trans_model::JuMP.Model,
                      inf_model::InfiniteOpt.InfiniteModel)::Nothing

Form the transcripted version of the objective stored in inf_model and add it to trans_model. Note that all the variables and measures in inf_model must by transcripted first (e.g., via transcribe_infinite_variables!).

transcribe_constraints!(trans_model::JuMP.Model,
                        inf_model::InfiniteOpt.InfiniteModel)::Nothing

For each constraint in inf_model form its transcripted version(s) and add them to trans_model. The mappings are stored in TranscriptionData.constr_mappings and the associated supports are stored in TranscriptionData.constr_supports to enable transcription_constraint and InfiniteOpt.constraint_supports. Note that variable info constraints are simply mapped to the existing info constraints already generated along with the transcription variables. Note that the variables and measures must all first be transcripted (e.g., via transcribe_measures!). Note that TranscriptionData.constr_support_labels is also populated.

transcribe_derivative_evaluations!(trans_model::JuMP.Model, 
                                   inf_model::InfiniteOpt.InfiniteModel)::Nothing

Generate the auxiliary derivative evaluation equations and transcribe them appropriately for all the derivatives in inf_model. These are in turn added to trans_model. Note that no mapping information is recorded since the InfiniteModel won't have any constraints that correspond to these equations. Also Note that the variables and measures must all first be transcripted (e.g., via transcribe_derivative_variables!).

build_transcription_model!(trans_model::JuMP.Model,
                           inf_model::InfiniteOpt.InfiniteModel;
                           [check_support_dims::Bool = true])::Nothing

Given an empty trans_model build it using the information stored in inf_model. This is intended for a TranscriptionModel that serves as a internal optimizer model of inf_model. This detail is important to correctly enable internally generated semi-infinite variables during the transcription process such that inf_model is not modified. Note that this will add supports to inf_model via InfiniteOpt.fill_in_supports! for infinite parameters that contain no supports. Also a warning is thrown when the transcription model contains more than 15,000 support points to alert users when they may naively have a few independent supports whose product quickly yields a very large grid. For example having 3 independent parameters with 100 supports each would result in 1,000,000 supports if all three are together in at least 1 constraint. This behavior can be overcome using dependent parameters. The warning can be turned off via check_support_dims = false.

InfiniteOpt.add_point_variable(model::JuMP.Model,
                               var::InfiniteOpt.PointVariable,
                               key::Val{:TransData}
                               )::InfiniteOpt.GeneralVariableRef

Make a PointVariableRef and map it to the appropriate transcription variable and return the GeneralVariableRef. This is an extension of add_point_variable for TranscriptionOpt.

InfiniteOpt.add_semi_infinite_variable(model::JuMP.Model,
                                 var::InfiniteOpt.SemiInfiniteVariable,
                                 key::Val{:TransData}
                                 )::InfiniteOpt.GeneralVariableRef

Make a SemiInfiniteVariableRef and add var to the transcription data and return the GeneralVariableRef. This is an extension of add_semi_infinite_variable for TranscriptionOpt. Note that internal_semi_infinite_variable is also extended to be able to access the var.

InfiniteOpt.build_optimizer_model!(model::InfiniteOpt.InfiniteModel,
                                   key::Val{:TransData};
                                   check_support_dims::Bool = true)::Nothing

Transcribe model and store it as a TranscriptionModel in the model.optimizer_model field which can be accessed with transcription_model. Ths clears the existing TranscriptionModel via InfiniteOpt.clear_optimizer_model_build! and then builds a new one using build_transcription_model!.

is_transcription_model(model::JuMP.Model)::Bool

Return true if model is a TranscriptionModel or false otherwise.

Example

julia> is_transcription_model(model)
true

transcription_data(model::JuMP.Model)::TranscriptionData

Return the TranscriptionData from a TranscriptionModel. Errors if it is not a TranscriptionModel.

has_internal_supports(model::JuMP.Model)::Bool

Return a Bool whether model has any internal supports that were collected.

transcription_model(model::InfiniteOpt.InfiniteModel)::JuMP.Model

Return the transcription model stored in model if that is what is stored in model.optimizer_model.

transcription_variable(model::JuMP.Model,
    vref::InfiniteOpt.GeneralVariableRef;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
     ndarray::Bool = false])

Return the transcribed variable reference(s) corresponding to vref. Errors if no transcription variable is found. Also can query via the syntax:

transcription_variable(vref::InfiniteOpt.GeneralVariableRef; 
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
     ndarray::Bool = false])

If the infinite model contains a built transcription model. By default, this method returns only transcribed variables associated with public supports. All the variables can be returned by setting label = All.

If vref is infinite and ndarray = true then an n-dimensional array will be returned in accordance with the infinite parameters that have unique object numbers. In this case, label will be used to search the intersection of variable supports that use the label. This is defers from the default behavior which considers the union.

Example

julia> transcription_variable(trans_model, infvar)
2-element Array{VariableRef,1}:
 infvar(support: 1)
 infvar(support: 2)

julia> transcription_variable(trans_model, hdvar)
hdvar

julia> transcription_variable(infvar)
2-element Array{VariableRef,1}:
 infvar(support: 1)
 infvar(support: 2)

julia> transcription_variable(hdvar)
hdvar

InfiniteOpt.optimizer_model_variable(vref::InfiniteOpt.GeneralVariableRef,
    ::Val{:TransData};
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
    ndarray::Bool = false])

Proper extension of InfiniteOpt.optimizer_model_variable for TranscriptionModels. This simply dispatches to transcription_variable.

InfiniteOpt.variable_supports(model::JuMP.Model,
    vref::InfiniteOpt.DecisionVariableRef,
    key::Val{:TransData} = Val(:TransData);
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
    ndarray::Bool = false])

Return the support alias mapping associated with vref in the transcription model. Errors if vref does not have transcripted variables. See transcription_variable for an explanation of ndarray.

lookup_by_support(model::JuMP.Model,
                  vref::InfiniteOpt.GeneralVariableRef,
                  support::Vector)

Return the transcription expression of vref defined at its support. This is intended as a helper method for automated transcription.

InfiniteOpt.internal_semi_infinite_variable(
    vref::InfiniteOpt.SemiInfiniteVariableRef,
    ::Val{:TransData}
    )::InfiniteOpt.SemiInfiniteVariable{InfiniteOpt.GeneralVariableRef}

Return the internal semi-infinite variable associated with vref, assuming it was added internally during measure expansion at the transcription step. This extends InfiniteOpt.internal_semi_infinite_variable as described in its docstring. Errors, if no such variable can be found.

transcription_expression(
    model::JuMP.Model,
    expr::JuMP.AbstractJuMPScalar;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
    ndarray::Bool = false])

Return the transcribed expression(s) corresponding to expr. Errors if expr cannot be transcribed. Also can query via the syntax:

transcription_expression(expr::JuMP.AbstractJuMPScalar;
                         [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
                         ndarray::Bool = false])

If the infinite model contains a built transcription model. By default, this method returns only transcribed expressions associated with public supports. All the expressions can be returned by setting label = All.

If expr is infinite and ndarray = true then an n-dimensional array will be returned in accordance with the infinite parameters that have unique object numbers. In this case, label will be used to search the intersection of the supports that use the label. This is defers from the default behavior which considers the union.

Example

julia> transcription_expression(trans_model, my_expr)
x(support: 1) - y

julia> transcription_expression(my_expr)
x(support: 1) - y

InfiniteOpt.optimizer_model_expression(expr::JuMP.AbstractJuMPScalar,
    ::Val{:TransData};
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
    ndarray::Bool = false])

Proper extension of InfiniteOpt.optimizer_model_expression for TranscriptionModels. This simply dispatches to transcription_expression.

InfiniteOpt.expression_supports(model::JuMP.Model,
    expr::JuMP.AbstractJuMPScalar,
    key::Val{:TransData} = Val(:TransData);
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
    ndarray::Bool = false])

Return the support alias mappings associated with expr. Errors if expr cannot be transcribed.

transcription_constraint(model::JuMP.Model,
    cref::InfiniteOpt.InfOptConstraintRef;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
    ndarray::Bool = false])

Return the transcribed constraint reference(s) corresponding to cref. Errors if cref has not been transcribed. Also can query via the syntax:

transcription_constraint(cref::InfiniteOpt.InfOptConstraintRef;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
    ndarray::Bool = false])

If the infinite model contains a built transcription model. By default, this method returns only transcribed constraints associated with public supports. All the constraints can be returned by setting label = All.

If cref is infinite and ndarray = true then an n-dimensional array will be returned in accordance with the infinite parameters that have unique object numbers. In this case, label will be used to search the intersection of the supports that use the label. This is defers from the default behavior which considers the union.

Example

julia> transcription_constraint(trans_model, fin_con)
fin_con : x(support: 1) - y <= 3.0

julia> transcription_constraint(fin_con)
fin_con : x(support: 1) - y <= 3.0

InfiniteOpt.optimizer_model_constraint(
    cref::InfiniteOpt.InfOptConstraintRef,
    ::Val{:TransData};
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel
    ndarray::Bool = false])

Proper extension of InfiniteOpt.optimizer_model_constraint for TranscriptionModels. This simply dispatches to transcription_constraint.

InfiniteOpt.constraint_supports(model::JuMP.Model,
    cref::InfiniteOpt.InfOptConstraintRef,
    key::Val{:TransData} = Val(:TransData);
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel,
    ndarray::Bool = false])

Return the support alias mappings associated with cref. Errors if cref is not transcribed.

parameter_supports(model::JuMP.Model)::Tuple

Return the collected parameter support tuple that is stored in TranscriptionData.supports.

support_index_iterator(model::JuMP.Model, [obj_nums::Vector{Int}])::CartesianIndices

Return the CartesianIndices that determine the indices of the unique combinations of TranscriptionData.supports stored in model. If obj_nums is specified, then the indices will only include the tuple elements uses indices are included in the object numbers obj_nums and all others will be assigned the last index which should correspond to an appropriately sized placeholder comprised of NaNs. Note this method assumes that set_parameter_supports has already been called and that the last elements of each support vector contains a placeholder value.

index_to_support(model::JuMP.Model, index::CartesianIndex)::Vector{Float64}

Given a particular support index generated via support_index_iterator using model, return the corresponding support from TranscriptionData.supports using placeholder NaNs as appropriate for tuple elements that are unneeded.

index_to_labels(model::JuMP.Model, index::CartesianIndex)::Set{DataType}

Given a particular support index generated via support_index_iterator using model, return the corresponding support label set from TranscriptionData.support_labels.

make_narray(model::JuMP.Model, 
            ref::Union{JuMP.AbstractJuMPScalar, InfiniteOpt.InfOptConstraintRef}, 
            info::Vector, 
            label::Type{<:InfiniteOpt.AbstractSupportLabel})::Array

Take the resultsinfo associated with ref and rearrange them into an n-dimensional array where the axes correspond to the infinite parameter dependencies in accordance with their creation. Note that this works by querying the object numbers. Thus, independent infinite parameters will each get their own dimension (even if they are defined at the same time in an array) and each dependent infinite parameter group will have its own dimension.