TranscriptionOpt

A technical manual for InfiniteOpt.TranscriptionOpt (the default transformation backend). See the respective guide for more information.

Definition

InfiniteOpt.TranscriptionOpt.TranscriptionBackendType
TranscriptionBackend(
    [optimizer_constructor];
    [add_bridges::Bool = true]
    )::InfiniteOpt.JuMPBackend{Transcription}

Return an InfiniteOpt.JuMPBackend that uses TranscriptionData and the Transcription tag. Accepts the same arguments as a typical JuMP.Model. More detailed variable and constraint naming can be enabled via verbose_naming.

Example

julia> backend = TranscriptionBackend();
source
InfiniteOpt.TranscriptionOpt.set_parameter_supportsFunction
set_parameter_supports(
    backend::TranscriptionBackend,
    model::InfiniteOpt.InfiniteModel
    )::Nothing

Collect the infinite parameter supports stored in their respective dictionaries form 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 group integer indices). 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!(
    backend::TranscriptionBackend,
    model::InfiniteOpt.InfiniteModel
    )::Nothing

Create transcription variables (i.e., JuMP variables) for each InfiniteVariable stored in model and add them to backend. 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!(
    backend::TranscriptionBackend,
    model::InfiniteOpt.InfiniteModel
    )::Nothing

Create transcription variables (i.e., JuMP variables) for each Derivative stored in model and add them to backend. 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!(
    backend::TranscriptionBackend,
    model::InfiniteOpt.InfiniteModel
    )::Nothing

Map each SemiInfiniteVariable in model to transcription variables stored in backend. 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!(
    backend::TranscriptionBackend,
    model::InfiniteOpt.InfiniteModel
    )::Nothing

Map each PointVariable in model to a transcription variable stored in backend. 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(
    expr::JuMP.AbstractJuMPScalar,
    backend::TranscriptionBackend;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel]
    )

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]
    )

If the infinite model contains a built transcription backend. 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, then 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(my_expr, backend)
x[1] - y

julia> transcription_expression(my_expr)
x[1] - y
source
transcription_expression(
    expr,
    backend::TranscriptionBackend,
    support::Vector{Float64}
    )

Given the expr from an InfiniteModel, form its transcripted version in accordance with the variable mappings available in backend 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!(
    backend::TranscriptionBackend,
    model::InfiniteOpt.InfiniteModel
    )::Nothing

For each Measure in 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!(
    backend::TranscriptionBackend,
    model::InfiniteOpt.InfiniteModel
    )::Nothing

For each constraint in model form its transcripted version(s) and add them to backend. 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!(
    backend::TranscriptionBackend, 
    model::InfiniteOpt.InfiniteModel
    )::Nothing

Generate the auxiliary derivative evaluation equations and transcribe them appropriately for all the derivatives in model. These are in turn added to backend. 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_backend!Function
build_transcription_backend!(
    backend::TranscriptionBackend,
    model::InfiniteOpt.InfiniteModel;
    [check_support_dims::Bool = true]
    )::Nothing

Given an empty backend build it using the information stored in model. This is intended for a TranscriptionModel that serves as a internal transformation backend of model. This detail is important to correctly enable internally generated semi-infinite variables during the transcription process such that model is not modified. Note that this will add supports to model via InfiniteOpt.fill_in_supports! for infinite parameters that contain no supports. Also a warning is thrown when the transcription backend 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(
    backend::TranscriptionBackend,
    var::InfiniteOpt.PointVariable,
    support::Vector{Float64}
    )::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(
    backend::TranscriptionBackend,
    var::InfiniteOpt.SemiInfiniteVariable
    )::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
InfiniteOpt.build_transformation_backend!Method
InfiniteOpt.build_transformation_backend!(
    model::InfiniteOpt.InfiniteModel,
    backend::TranscriptionBackend;
    check_support_dims::Bool = true
    )::Nothing

Build backend and set it as the transformation backend to model. Ths clears out the existing backend and rebuilds it. Optionally, the dimension check to through a warning if there is potentially a very large number of supports can be turned off via check_support_dims = false.

source

Queries

InfiniteOpt.TranscriptionOpt.transcription_variableMethod
transcription_variable(
    vref::InfiniteOpt.GeneralVariableRef,
    backend::TranscriptionBackend;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel]
     )

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]
    )

If the infinite model contains a built TranscriptionBackend. 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, then 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(infvar, trans_backend)
2-element Array{VariableRef,1}:
 infvar[1]
 infvar[2]

julia> transcription_variable(hdvar, trans_backend)
hdvar

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

julia> transcription_variable(hdvar)
hdvar
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.variable_supports(
    vref::InfiniteOpt.DecisionVariableRef,
    backend::TranscriptionBackend;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel]
    )

Return the support alias mapping associated with vref in the transcription backend. Errors if vref does not have transcripted variables.

source
InfiniteOpt.TranscriptionOpt.lookup_by_supportMethod
lookup_by_support(
    vref::InfiniteOpt.GeneralVariableRef,
    backend::TranscriptionBackend,
    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,
    backend::TranscriptionBackend
    )::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(
    expr::JuMP.AbstractJuMPScalar,
    backend::TranscriptionBackend;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel]
    )

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]
    )

If the infinite model contains a built transcription backend. 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, then 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(my_expr, backend)
x[1] - y

julia> transcription_expression(my_expr)
x[1] - y
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.expression_supports(
    expr::JuMP.AbstractJuMPScalar,
    backend::TranscriptionBackend;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel]
    )

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

source
InfiniteOpt.TranscriptionOpt.transcription_constraintMethod
transcription_constraint(
    cref::InfiniteOpt.InfOptConstraintRef,
    backend::TranscriptionBackend;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel]
    )

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]
    )

If the infinite model contains a built transcription backend. 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, then 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(fin_con, backend)
fin_con : x[1] - y <= 3.0

julia> transcription_constraint(fin_con)
fin_con : x[1] - y <= 3.0
source
InfiniteOpt.constraint_supportsMethod
InfiniteOpt.constraint_supports(
    cref::InfiniteOpt.InfOptConstraintRef,
    backend::TranscriptionBackend;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel])

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

source

Utilities

InfiniteOpt.TranscriptionOpt.support_index_iteratorFunction
support_index_iterator(backend::TranscriptionBackend, [group_int_idxs::Vector{Int}])::CartesianIndices

Return the CartesianIndices that determine the indices of the unique combinations of TranscriptionData.supports stored in backend. If group_int_idxs is specified, then the indices will only include the tuple elements uses indices are included in the parameter group integer indices group_int_idxs 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.index_to_supportFunction
index_to_support(backend::TranscriptionBackend, index::CartesianIndex)::Vector{Float64}

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

source