TranscriptionOpt

TranscriptionBackend(
    [optimizer_constructor];
    [add_bridges::Bool = true],
    [update_parameter_functions::Bool = false]
)::InfiniteOpt.JuMPBackend{Transcription}

Return an InfiniteOpt.JuMPBackend that uses TranscriptionData and the Transcription tag. Accepts the same arguments as a typical JuMP.Model. Optionally, transcribe parameter functions using JuMP.Parameter such that they can be updated for more efficient resolves by setting update_parameter_functions = true.

Example

julia> backend = TranscriptionBackend();

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 data field of InfiniteOpt.JuMPBackend to make what is called a TranscriptionBackend via the TranscriptionBackend constructor.

Transcription <: InfiniteOpt.AbstractJuMPTag

Dispatch tag needed for TranscriptionBackend to be based on InfiniteOpt.JuMPBackend.

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.

transcribe_finite_parameters!(
    backend::TranscriptionBackend,
    model::InfiniteOpt.InfiniteModel
    )::Nothing

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

transcribe_finite_variables!(
    backend::TranscriptionBackend,
    model::InfiniteOpt.InfiniteModel
    )::Nothing

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

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.

transcribe_parameter_functions!(
    backend::TranscriptionBackend,
    model::InfiniteOpt.InfiniteModel
    )::Nothing

Create transcription variables (i.e., JuMP Parameters) corresponding to all supports of each Parameter Function 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.

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.

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.

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.

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

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!).

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.

transcribe_objective!(
    backend::TranscriptionBackend,
    model::InfiniteOpt.InfiniteModel
    )::Nothing

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

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.

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!).

transcribe_variable_collocation_restictions!(
    backend::TranscriptionBackend, 
    model::InfiniteOpt.InfiniteModel
    )::Nothing

Add constraints to backend that make infinite variables constant over collocation points following the calls made to InfiniteOpt.constant_over_collocation. Note that set_parameter_supports and transcribe_infinite_variables! must be called first.

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.

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.

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.

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.

transcription_data(backend::TranscriptionBackend)::TranscriptionData

Return the mapping data used by backend.

has_internal_supports(backend::TranscriptionBackend)::Bool

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

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

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

Proper extension of InfiniteOpt.transformation_variable for TranscriptionBackends. This simply dispatches to transcription_variable.

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.

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.

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.

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.

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

InfiniteOpt.transformation_expression(
    expr::JuMP.AbstractJuMPScalar,
    backend::TranscriptionBackend;
    [label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel]
    )

Proper extension of InfiniteOpt.transformation_expression for TranscriptionBackends. This simply dispatches to transcription_expression.

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.

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.

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

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

Proper extension of InfiniteOpt.transformation_constraint for TranscriptionBackends. This simply dispatches to transcription_constraint.

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.

parameter_supports(backend::TranscriptionBackend)::Tuple

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

InfiniteOpt.update_parameter_value(
    backend::TranscriptionBackend,
    fref::InfiniteOpt.FiniteParameterRef,
    value::Real
)::Bool

Update the value of the finite parameter referenced by fref in backend to value. Returns true if the parameter was found and updated, false otherwise.

InfiniteOpt.update_parameter_value(
    backend::TranscriptionBackend,
    pfref::InfiniteOpt.ParameterFunctionRef,
    value::Function
)::Bool

Update the values of the parameter function referenced by pfref in backend to be evaluated via value. Returns true if the parameter function was found and updated, false otherwise.

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.

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.