Model Transcription

A technical manual for InfiniteOpt.TranscriptionOpt. See the respective guide for more information.

Definition

InfiniteOpt.TranscriptionOpt.TranscriptionModelFunction
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.
source
InfiniteOpt.TranscriptionOpt.TranscriptionDataType
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?
source
InfiniteOpt.TranscriptionOpt.set_parameter_supportsFunction
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.

source
InfiniteOpt.TranscriptionOpt.transcribe_infinite_variables!Function
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.

source
InfiniteOpt.TranscriptionOpt.transcribe_derivative_variables!Function
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.

source
InfiniteOpt.TranscriptionOpt.transcribe_semi_infinite_variables!Function
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.

source
InfiniteOpt.TranscriptionOpt.transcribe_point_variables!Function
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.

source
InfiniteOpt.TranscriptionOpt.transcription_expressionFunction
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
source
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!).

source
InfiniteOpt.TranscriptionOpt.transcribe_measures!Function
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.

source
InfiniteOpt.TranscriptionOpt.transcribe_constraints!Function
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.

source
InfiniteOpt.TranscriptionOpt.transcribe_derivative_evaluations!Function
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!).

source
InfiniteOpt.TranscriptionOpt.build_transcription_model!Function
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.

source
InfiniteOpt.add_point_variableMethod
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.

source
InfiniteOpt.add_semi_infinite_variableMethod
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.

source

Queries

InfiniteOpt.TranscriptionOpt.transcription_variableMethod
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
source
InfiniteOpt.variable_supportsMethod
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.

source
InfiniteOpt.TranscriptionOpt.lookup_by_supportMethod
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.

source
InfiniteOpt.internal_semi_infinite_variableMethod
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.

source
InfiniteOpt.TranscriptionOpt.transcription_expressionMethod
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
source
InfiniteOpt.expression_supportsMethod
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.

source
InfiniteOpt.TranscriptionOpt.transcription_constraintMethod
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
source
InfiniteOpt.constraint_supportsMethod
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.

source

Utilities

InfiniteOpt.TranscriptionOpt.support_index_iteratorFunction
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.

source
InfiniteOpt.TranscriptionOpt.make_ndarrayFunction
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.

source