TranscriptionOpt
A technical manual for InfiniteOpt.TranscriptionOpt
(the default transformation backend). See the respective guide for more information.
Definition
InfiniteOpt.TranscriptionOpt.TranscriptionBackend
— TypeTranscriptionBackend(
[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();
InfiniteOpt.TranscriptionOpt.TranscriptionData
— TypeTranscriptionData
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.
InfiniteOpt.TranscriptionOpt.Transcription
— TypeTranscription <: InfiniteOpt.AbstractJuMPTag
Dispatch tag needed for TranscriptionBackend
to be based on InfiniteOpt.JuMPBackend
.
InfiniteOpt.TranscriptionOpt.set_parameter_supports
— Functionset_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 NaN
s 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.
InfiniteOpt.TranscriptionOpt.transcribe_finite_variables!
— Functiontranscribe_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
.
InfiniteOpt.TranscriptionOpt.transcribe_infinite_variables!
— Functiontranscribe_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.
InfiniteOpt.TranscriptionOpt.transcribe_derivative_variables!
— Functiontranscribe_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.
InfiniteOpt.TranscriptionOpt.transcribe_semi_infinite_variables!
— Functiontranscribe_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.
InfiniteOpt.TranscriptionOpt.transcribe_point_variables!
— Functiontranscribe_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.
InfiniteOpt.TranscriptionOpt.transcription_expression
— Functiontranscription_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!
).
InfiniteOpt.TranscriptionOpt.transcribe_measures!
— Functiontranscribe_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.
InfiniteOpt.TranscriptionOpt.transcribe_objective!
— Functiontranscribe_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!
).
InfiniteOpt.TranscriptionOpt.transcribe_constraints!
— Functiontranscribe_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.
InfiniteOpt.TranscriptionOpt.transcribe_derivative_evaluations!
— Functiontranscribe_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!
).
InfiniteOpt.TranscriptionOpt.transcribe_variable_collocation_restictions!
— Functiontranscribe_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.
InfiniteOpt.TranscriptionOpt.build_transcription_backend!
— Functionbuild_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
— MethodInfiniteOpt.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
— MethodInfiniteOpt.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!
— MethodInfiniteOpt.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
.
Queries
InfiniteOpt.TranscriptionOpt.transcription_data
— Functiontranscription_data(backend::TranscriptionBackend)::TranscriptionData
Return the mapping data used by backend
.
InfiniteOpt.TranscriptionOpt.has_internal_supports
— Functionhas_internal_supports(backend::TranscriptionBackend)::Bool
Return a Bool
whether backend
has any internal supports that were collected.
InfiniteOpt.TranscriptionOpt.transcription_variable
— Methodtranscription_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
— MethodInfiniteOpt.transformation_variable(
vref::InfiniteOpt.GeneralVariableRef,
[backend::TranscriptionBackend];
[label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel]
)
Proper extension of InfiniteOpt.transformation_variable
for TranscriptionBackend
s. This simply dispatches to transcription_variable
.
InfiniteOpt.variable_supports
— Methodvariable_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.
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.
InfiniteOpt.TranscriptionOpt.lookup_by_support
— Methodlookup_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
— MethodInfiniteOpt.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.
InfiniteOpt.TranscriptionOpt.transcription_expression
— Methodtranscription_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
— MethodInfiniteOpt.transformation_expression(
expr::JuMP.AbstractJuMPScalar,
backend::TranscriptionBackend;
[label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel]
)
Proper extension of InfiniteOpt.transformation_expression
for TranscriptionBackend
s. This simply dispatches to transcription_expression
.
InfiniteOpt.expression_supports
— Methodexpression_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
.
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.
InfiniteOpt.TranscriptionOpt.transcription_constraint
— Methodtranscription_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
— MethodInfiniteOpt.transformation_constraint(
cref::InfiniteOpt.InfOptConstraintRef,
backend::TranscriptionBackend;
[label::Type{<:InfiniteOpt.AbstractSupportLabel} = InfiniteOpt.PublicLabel]
)
Proper extension of InfiniteOpt.transformation_constraint
for TranscriptionBackend
s. This simply dispatches to transcription_constraint
.
InfiniteOpt.constraint_supports
— MethodInfiniteOpt.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.
InfiniteOpt.TranscriptionOpt.parameter_supports
— Methodparameter_supports(backend::TranscriptionBackend)::Tuple
Return the collected parameter support tuple that is stored in TranscriptionData.supports
.
Utilities
InfiniteOpt.TranscriptionOpt.support_index_iterator
— Functionsupport_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 NaN
s. 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.
InfiniteOpt.TranscriptionOpt.index_to_support
— Functionindex_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 NaN
s as appropriate for tuple elements that are unneeded.