Infinite Parameters

@infinite_parameter(model::InfiniteModel, kwargs...)

Add anonymous infinite parameter to the model model described by the keyword arguments kw_args and returns the parameter reference.

@infinite_parameter(model::InfiniteModel, expr, kwargs...)

Add an infinite parameter to the model model described by the expression expr, and the keyword arguments kw_args. (Note that in the following the symbol in can be used instead of ∈) The expression expr can be of the form:

• paramexpr creating parameters described by paramexpr.
• paramexpr ∈ [lb, ub] creating parameters described by paramexpr characterized by a continuous interval domain with lower bound lb and upper bound ub.
• paramexpr ~ dist creating parameters described by paramexpr characterized by the Distributions.jl distribution object dist.
• paramexpr ∈ domain creating parameters described by paramexpr characterized by the AbstractInfiniteDomain object domain.

The expression paramexpr can be of the form:

• paramname creating a scalar parameter of name paramname
• paramname[...] or [...] creating a container of parameters

The recognized keyword arguments in kwargs are the following:

• base_name: Sets the name prefix used to generate parameter names. It corresponds to the parameter name for scalar parameter, otherwise, the parameter names are set to base_name[...] for each index ... of the axes axes.
• domain: The InfiniteDomain characterizing the parameters see subtypes of AbstractInfiniteDomain.
• distribution: Sets the Distributions.jl distribution object that characterizes the parameters (specified instead of a domain).
• supports: Sets the support points for the parameters.
• num_supports: Specifies the number of supports to be automatically generated. Note that supports takes precedence. Defaults to 0.
• derivative_method: Specify the numerical method to evaluate derivatives that are taken with respect to the parameter.
• sig_digits: Specifies the number of significant digits that should be used in automatic support generation. Defaults to DefaultSigDigits.
• independent: Specifies if the each parameter is independent from each other or not. Defaults to false.
• container: Specify the container type. Defaults to Auto

Examples

julia> @infinite_parameter(m, x in [0, 1])
x

julia> @infinite_parameter(m, y[i = 1:2] ~ MvNormal(ones(2)), num_supports = 10)
2-element Array{GeneralVariableRef,1}:
 y[1]
 y[2]

julia> z = @infinite_parameter(m, [["a", "b"]], distribution = Normal(),
                               independent = true)
1-dimensional DenseAxisArray{GeneralVariableRef,1,...} with index sets:
    Dimension 1, ["a", "b"]
And data, a 2-element Array{GeneralVariableRef,1}:
 noname[a]
 noname[b]

InfOptParameter <: JuMP.AbstractVariable

An abstract type for all parameters used in InfiniteOpt.

ScalarParameter <: InfOptParameter

An abstract type for scalar parameters used in InfiniteOpt.

IndependentParameter{T <: InfiniteScalarDomain,
                     M <: AbstractDerivativeMethod,
                     I <: AbstractGenerativeInfo} <: ScalarParameter

A DataType for storing independent scalar infinite parameters.

Fields

• domain::T: The infinite domain that characterizes the parameter.
• supports::DataStructures.SortedDict{Float64, Set{DataType}}: The support points used to discretize the parameter and their associated type labels stored as DataTypess which should be a subtype of AbstractSupportLabel.
• sig_digits::Int: The number of significant digits used to round the support values.
• derivative_method::M: The derivative evaluation method used for derivatives that are conducted with respect to this parameter.
• gnerative_supp_info::I: The info associated with any generative supports that will need to be generated for measures and/or derivatives based on existing supports.

build_parameter(
    _error::Function, domain::InfiniteScalarDomain;
    [num_supports::Int = 0,
    supports::Union{Vector{<:Real}, UnitRange{<:Real}, StepRange{<:Real}} = Float64[],
    sig_digits::Int = DefaultSigDigits,
    derivative_method::AbstractDerivativeMethod = DefaultDerivativeMethod]
)::IndependentParameter

Returns a IndependentParameter given the appropriate information. This is analagous to JuMP.build_variable. Errors if supports violate the bounds associated with domain. This is meant to primarily serve as a helper method for @infinite_parameter. Here derivative_method specifies the numerical evalution method that will be applied to derivatives that are taken with respect to this infinite parameter.

Example

julia> param = build_parameter(error, IntervalDomain(0, 3), supports = Vector(0:3));

add_parameter(model::InfiniteModel, p::IndependentParameter,
              [name::String = ""])::GeneralVariableRef

Returns a GeneralVariableRef associated with the parameter p that is added to model. This adds a parameter to the model in a manner similar to JuMP.add_variable. This is used to add parameters with the use of @infinite_parameter. build_parameter should be used to construct p.

Example

julia> p = build_parameter(error, IntervalDomain(0, 3), supports = Vector(0:3));

julia> param_ref = add_parameter(model, p, "name")
name

ScalarParameterData{P <: ScalarParameter} <: AbstractDataObject

A mutable DataType for storing ScalarParameters and their data.

Fields

• parameter::P: The scalar parameter.
• group_int_idx::Int: The location of the corresponding ObjectIndex in InfiniteModel.param_group_indices.
• parameter_num::Int: Given by InfiniteModel.last_param_num (updated when prior parameters are deleted)
• name::String: The name used for printing.
• parameter_func_indices::Vector{ParameterFunctionIndex}: Indices of dependent infinite parameter functions.
• infinite_var_indices::Vector{InfiniteVariableIndex}: Indices of dependent infinite variables.
• derivative_indices::Vector{DerivativeIndex}: Indices of dependent derivatives.
• measure_indices::Vector{MeasureIndex}: Indices of dependent measures.
• constraint_indices::Vector{InfOptConstraintIndex}: Indices of dependent constraints.
• in_objective::Bool: Is this used in objective? This should be true only for finite parameters.
• generative_measures::Vector{MeasureIndex}: Indices of measures that use parameter.generative_supp_info.
• has_internal_supports::Bool: Does this parameter have internal supports?
• has_generative_supports::Bool: Have any generative supports been added?
• has_deriv_constrs::Bool: Have any derivative evaluation constraints been added to the infinite model associated with this parameter?

IndependentParameterIndex <: ObjectIndex

A DataType for storing the index of a IndependentParameter.

Fields

• value::Int64: The index value.

IndependentParameterRef <: DispatchVariableRef

A DataType for independent infinite parameters references that parameterize infinite variables.

Fields

• model::InfiniteModel: Infinite model.
• index::IndependentParameterIndex: Index of the parameter in model.

DependentParameters{T <: InfiniteArrayDomain, 
                    M <: NonGenerativeDerivativeMethod} <: InfOptParameter

A DataType for storing a collection of dependent infinite parameters.

Fields

• domain::T: The infinite domain that characterizes the parameters.
• supports::DataStructures.OrderedDict{Vector{Float64}, Set{DataType}}: Support dictionary where keys are supports and the values are the set of labels for each support.
• sig_digits::Int: The number of significant digits used to round the support values.
• derivative_methods::Vector{M}: The derivative evaluation methods associated with each parameter.

add_parameters(
    model::InfiniteModel,
    params::DependentParameters,
    names::Vector{String}
    )::Vector{GeneralVariableRef}

Add params to model and return an appropriate container of the dependent infinite parameter references. This is intended as an internal method for use with @infinite_parameter. However, if desired users can use this to add a DependentParameters object to model. Here, names denote the name of each parameter.

Example

julia> using Distributions

julia> dist = MvNormal(ones(3)); # 3 dimensional

julia> domain = MultiDistributionDomain(dist); # 3 dimensional

julia> params = DependentParameters(domain, Dict{Vector{Float64}, Set{DatatType}}(), 10);

julia> prefs = add_parameters(model, params, ["par1", "par2", "par3"])
3-element Array{GeneralVariableRef,1}:
 par1
 par2
 par3

MultiParameterData{P <: DependentParameters} <: AbstractDataObject

A mutable DataType for storing DependentParameters and their data.

Fields

• parameters::P: The parameter collection.
• group_int_idx::Int: The location of the corresponding ObjectIndex in InfiniteModel.param_group_indices.
• parameter_nums::UnitRange{Int}: Given by InfiniteModel.last_param_num (updated when prior parameters are deleted)
• names::Vector{String}: The names used for printing each parameter.
• parameter_func_indices::Vector{ParameterFunctionIndex}: Indices of dependent infinite parameter functions.
• infinite_var_indices::Vector{InfiniteVariableIndex}: Indices of dependent infinite variables.
• derivative_indices::Vector{Vector{DerivativeIndex}}: Indices of dependent derivatives.
• measure_indices::Vector{Vector{MeasureIndex}}: Indices of dependent measures.
• constraint_indices::Vector{Vector{InfOptConstraintIndex}}: Indices of dependent constraints.
• has_internal_supports::Bool: Does this parameter have internal supports?
• has_deriv_constrs::Bool: Have any derivative evaluation constraints been added to the infinite model associated with this parameter?

DependentParametersIndex <: ObjectIndex

A DataType for storing the index of a DependentParameters object.

Fields

• value::Int64: The index value.

DependentParameterIndex <: AbstractInfOptIndex

A DataType for storing the index of an indiviudal parameter in a DependentParameters object.

Fields

• object_index::DependentParametersIndex: The index of the parameter collection.
• param_index::Int: The index of the individual parameter in the above object.

DependentParameterRef <: DispatchVariableRef

A DataType for dependent infinite parameter references that parameterize infinite variables.

Fields

• model::InfiniteModel: Infinite model.
• index::DependentParameterIndex: Index of the dependent parameter.

parameter_by_name(model::InfiniteModel,
                  name::String)::Union{GeneralVariableRef, Nothing}

Return the parameter reference assoociated with a parameter name. Errors if multiple parameters have the same name. Returns nothing if no such name exists.

Example

julia> parameter_by_name(model, "t")
t

num_parameters(model::InfiniteModel,
               [type::Type{InfOptParameter} = InfOptParameter])::Int

Return the number of InfiniteOpt parameters assigned to model. By default, the total number of infinite and finite parameters is returned. The amount of a particular type is obtained by specifying the concrete parameter type of InfOptParameter via type. Type options include:

• InfOptParameter: all parameters
• ScalarParameter: all scalar parameters
• InfiniteParameter: all infinite parameters
• FiniteParameter: all finite parameters
• IndependentParameter: all independent infinite parameters
• DependentParameters: all dependent infinite parameters

Example

julia> num_parameters(model)
3

julia> num_parameters(model, IndependentParameter)
2

all_parameters(model::InfiniteModel,
               type::Type{InfOptParameter} = InfOptParameter
               )::Vector{GeneralVariableRef}

Return a list of all the InfiniteOpt parameters assigned to model. By default, all of the infinite and finite parameters is returned. The search is reduced to a particular type is obtained by specifying the concrete parameter type of InfOptParameter via type. Type options include:

• InfOptParameter: all parameters
• ScalarParameter: all scalar parameters
• InfiniteParameter: all infinite parameters
• FiniteParameter: all finite parameters
• IndependentParameter: all independent infinite parameters
• DependentParameters: all dependent infinite parameters

Examples

julia> all_parameters(model)
4-element Array{GeneralVariableRef,1}:
 t
 x[1]
 x[2]
 alpha

julia> all_parameters(model, FiniteParameter)
1-element Array{GeneralVariableRef,1}:
 alpha

JuMP.name(pref::Union{IndependentParameterRef, FiniteParameterRef})::String

Extend the JuMP.name function to accomodate infinite parameters. Returns the name string associated with pref.

Example

julia> name(t)
"t"

infinite_domain(pref::IndependentParameterRef)::InfiniteScalarDomain

Return the infinite domain associated with pref.

Example

julia> infinite_domain(t)
[0, 1]

JuMP.has_lower_bound(pref::IndependentParameterRef)::Bool

Extend the JuMP.has_lower_bound function to accomodate infinite parameters. Return true if the domain associated with pref has a defined lower bound or if a lower bound can be found. Extensions with user-defined infinite domain types should extend JuMP.has_lower_bound(domain::NewType).

Example

julia> has_lower_bound(t)
true

JuMP.lower_bound(pref::IndependentParameterRef)::Real

Extend the JuMP.lower_bound function to accomodate infinite parameters. Returns the lower bound associated with the infinite domain. Errors if such a bound is not well-defined.

Example

julia> lower_bound(t)
0.0

JuMP.has_upper_bound(pref::IndependentParameterRef)::Bool

Extend the JuMP.has_upper_bound function to accomodate infinite parameters. Return true if the domain associated with pref has a defined upper bound or if a upper bound can be found. Extensions with user-defined domains should extend JuMP.has_upper_bound(domain::NewType).

Example

julia> has_upper_bound(t)
true

JuMP.upper_bound(pref::IndependentParameterRef)::Real

Extend the JuMP.upper_bound function to accomodate infinite parameters. Returns the upper bound associated with the infinite domain. Errors if such a bound is not well-defined. Extensions with user-defined domain types should extend JuMP.has_upper_bound(domain::NewType) and JuMP.upper_bound(domain::NewType) if appropriate.

Example

julia> upper_bound(t)
1.0

has_supports(pref::IndependentParameterRef)::Bool

Return true if pref has supports or false otherwise.

Example

julia> has_supports(t)
true

num_supports(
    pref::IndependentParameterRef; 
    [label::Type{<:AbstractSupportLabel} = PublicLabel]
    )::Int

Return the number of support points associated with pref. By default, only the number of public supports are counted. The full amount can be determined by setting label = All. Moreover, the amount of labels that satisfy label is obtained using an AbstractSupportLabel.

Example

julia> num_supports(t)
2

supports(
    pref::IndependentParameterRef; 
    [label::Type{<:AbstractSupportLabel} = PublicLabel]
    )::Vector{Float64}

Return the support points associated with pref. Errors if there are no supports. Users can query just support points generated by a certain method using the keyword argument label. By default, the function returns all public support points regardless of the associated label. The full collection is given by setting label = All. Moreover, the amount of labels that satisfy label is obtained using an AbstractSupportLabel.

Example

julia> supports(t)
2-element Array{Float64,1}:
 0.0
 1.0

has_internal_supports(pref::Union{IndependentParameterRef, DependentParameterRef})::Bool

Indicate if pref has internal supports that will be hidden from the user by default.

significant_digits(pref::IndependentParameterRef)::Int

Return the number of significant digits enforced on the supports of pref.

Example

julia> significant_digits(t)
12

derivative_method(pref::IndependentParameterRef)::AbstractDerivativeMethod

Returns the numerical derivative evaluation method employed with pref when it is used as an operator parameter in a derivative.

Example

julia> derivative_method(pref) 
FiniteDifference(Backward, true)

is_used(pref::Union{IndependentParameterRef, FiniteParameterRef})::Bool

Return true if pref is used in the model or false otherwise.

Example

julia> is_used(t)
true

used_by_infinite_variable(pref::IndependentParameterRef)::Bool

Return true if pref is used by an infinite variable or false otherwise.

Example

julia> used_by_infinite_variable(t)
true

used_by_parameter_function(pref::IndependentParameterRef)::Bool

Return true if pref is used by an infinite parameter function or false otherwise.

Example

julia> used_by_parameter_function(t)
false

used_by_derivative(pref::IndependentParameterRef)::Bool

Return true if pref is used by a derivative or false otherwise.

Example

julia> used_by_derivative(t)
false

used_by_measure(pref::Union{IndependentParameterRef, FiniteParameterRef})::Bool

Return true if pref is used by a measure or false otherwise.

Example

julia> used_by_measure(t)
false

used_by_constraint(pref::Union{IndependentParameterRef, FiniteParameterRef})::Bool

Return true if pref is used by a constraint or false otherwise.

Example

julia> used_by_constraint(t)
true

`parameter_group_int_index(pref::IndependentParameterRef)::Int

Return the infinite parameter group integer index corresponding to pref.

core_object(pref::IndependentParameterRef)::IndependentParameter

Retrieve the underlying core [IndependentParameter] object for pref. This is intended as an advanced method for developers.

JuMP.name(pref::DependentParameterRef)::String

Extend JuMP.name to return the names of infinite dependent parameters.

Example

julia> name(pref)
"par_name"

infinite_domain(pref::DependentParameterRef)::InfiniteScalarDomain

Return the infinite domain associated with the particular infinite dependent parameter pref if valid. Errors if the underlying DependentParameters object does not use a CollectionDomain.

Example

julia> infinite_domain(x[1])
[-1, 1]

infinite_domain(prefs::AbstractArray{<:DependentParameterRef})::InfiniteArrayDomain

Return the infinite domain associated with the container of infinite dependent parameters prefs. Errors if the container prefs is incomplete.

Example

julia> infinite_domain(x)
ZeroMeanDiagNormal(
dim: 2
μ: [0.0, 0.0]
Σ: [1.0 0.0; 0.0 1.0]
)

JuMP.has_lower_bound(pref::DependentParameterRef)::Bool

Extend the JuMP.has_lower_bound function to accomodate a single dependent infinite parameter. Return true if the domain associated with pref has a defined lower bound or if a lower bound can be found. Extensions with user-defined scalar infinite domain types should extend JuMP.has_lower_bound(domain::NewType).

Example

julia> has_lower_bound(x[1])
true

JuMP.lower_bound(pref::DependentParameterRef)::Number

Extend the JuMP.lower_bound function to accomodate a single dependent infinite parameter. Returns the lower bound associated with the infinite domain. Errors if such a bound is not well-defined.

Example

julia> lower_bound(x[1])
0.0

JuMP.has_upper_bound(pref::DependentParameterRef)::Bool

Extend the JuMP.has_upper_bound function to accomodate a single dependent infinite parameter. Return true if the domain associated with pref has a defined upper bound or if a upper bound can be found. Extensions with user-defined scalar infinite domain types should extend JuMP.has_upper_bound(domain::NewType).

Example

julia> has_upper_bound(x[1])
true

JuMP.upper_bound(pref::DependentParameterRef)::Number

Extend the JuMP.upper_bound function to accomodate a single dependent infinite parameter. Returns the upper bound associated with the infinite domain. Errors if such a bound is not well-defined.

Example

julia> upper_bound(x[1])
0.0

has_supports(pref::DependentParameterRef)::Bool

Return true if pref has supports or false otherwise.

Example

julia> has_supports(x[1])
true

has_supports(prefs::AbstractArray{<:DependentParameterRef})::Bool

Return true if prefs have supports or false otherwise. Errors if not all of the infinite dependent parameters are from the same object.

Example

julia> has_supports(x)
true

num_supports(
    pref::DependentParameterRef; 
    [label::Type{<:AbstractSupportLabel} = PublicLabel]
    )::Int

Return the number of support points associated with a single dependent infinite parameter pref. Specify a subset of supports via label to only count the supports with label. By default only the amount of public supports are given, but the full amount is obtained via label == All.

Example

julia> num_supports(x[1])
2

julia> num_supports(x[1], label = MCSample)
0

num_supports(
    prefs::AbstractArray{<:DependentParameterRef};
    [label::Type{<:AbstractSupportLabel} = PublicLabel]
    )::Int

Return the number of support points associated with dependent infinite parameters prefs. Errors if not all from the same underlying object. Specify a subset of supports via label to only count the supports with label. By default only the amount of public supports are given, but the full amount is obtained via label == All.

Example

julia> num_supports(x)
2

supports(
    pref::DependentParameterRef; 
    [label::Type{<:AbstractSupportLabel} = PublicLabel]
    )::Vector{Float64}

Return the support points associated with pref. A subset of supports can be returned via label to return just the supports associated with label. By default only the public supports are given, but the full set is obtained via label == All.

Example

julia> supports(x[1])
2-element Array{Float64,1}:
 0.0
 1.0

supports(
    prefs::AbstractArray{<:DependentParameterRef};
    [label::Type{<:AbstractSupportLabel} = PublicLabel]
    )::Union{Vector{<:AbstractArray{<:Real}}, Array{Float64, 2}}

Return the support points associated with prefs. Errors if not all of the infinite dependent parameters are from the same object. This will return a matrix if prefs is Vector, otherwise a vector of arrays is returned where each array is a support point matching the format of prefs. A subset of supports can be returned via label to return just the supports associated with label. By default only the public supports are given, but the full set is obtained via label == All.

Example

julia> supports(x) # columns are supports
2×2 Array{Float64,2}:
 0.0  1.0
 0.0  1.0

significant_digits(pref::DependentParameterRef)::Int

Return the number of significant digits enforced on the supports of pref.

Example

julia> significant_digits(x[1])
12

derivative_method(pref::DependentParameterRef)::NonGenerativeDerivativeMethod

Returns the numerical derivative evaluation method employed with pref when it is used as an operator parameter in a derivative.

Example

julia> derivative_method(pref) 
FiniteDifference

is_used(pref::DependentParameterRef)::Bool

Return a Bool indicating if the dependent infinite parameter pref is used in the model.

Example

julia> is_used(pref)
true

used_by_infinite_variable(pref::DependentParameterRef)::Bool

Return a Bool indicating if the dependent infinite parameter pref is used by an infinite variable.

Example

julia> used_by_infinite_variable(pref)
true

used_by_parameter_function(pref::DependentParameterRef)::Bool

Return a Bool indicating if the dependent infinite parameter pref is used by an infinite parameter function.

Example

julia> used_by_parameter_function(pref)
true

used_by_derivative(pref::DependentParameterRef)::Bool

Return a Bool indicating if the dependent infinite parameter pref is used by a derivative.

Example

julia> used_by_derivative(pref)
false

used_by_measure(pref::DependentParameterRef)::Bool

Return a Bool indicating if the dependent infinite parameter pref is used by a measure.

Example

julia> used_by_measure(pref)
true

used_by_constraint(pref::DependentParameterRef)::Bool

Return a Bool indicating if the dependent infinite parameter pref is used by a constraint.

Example

julia> used_by_constraint(pref)
false

parameter_group_int_index(pref::DependentParameterRef)::Int

Return the infinite parameter group integer index that corresponds to pref.

core_object(pref::DependentParameterRef)::DependentParameters

Retrieve the underlying core DependentParameters object for pref. Note that this object applies to pref and the other infinite parameters it is coupled with. This is intended as an advanced method for developers.

fill_in_supports!(model::InfiniteModel; [num_supports::Int = DefaultNumSupports,
                  modify::Bool = true])::Nothing

Automatically generate support points for all infinite parameters in model. This calls fill_in_supports! for each parameter in the model. See fill_in_supports! for more information. Errors if one of the infinite domain types is unrecognized. Note that no supports will be added to a particular parameter if it already has some and modify = false.

Example

julia> fill_in_supports!(model, num_supports = 4)

julia> supports(t)
4-element Array{Float64,1}:
 0.0
 0.333
 0.667
 1.0

JuMP.set_name(pref::ScalarParameterRef, name::String)

Extend the JuMP.set_name function to accomodate infinite parameters. Set a new base name to be associated with pref.

Example

julia> set_name(t, "time")

julia> name(t)
"time"

set_infinite_domain(pref::IndependentParameterRef,
                 domain::InfiniteScalarDomain)::Nothing

Reset the infinite domain of pref with another InfiniteScalarDomain. An error will be thrown if pref is being used by some measure.

Example

julia> set_infinite_domain(t, IntervalDomain(0, 2))

julia> infinite_domain(t)
[0, 2]

JuMP.set_lower_bound(pref::IndependentParameterRef, lower::Real)::Nothing

Extend the JuMP.set_lower_bound function to accomodate infinite parameters. Updates the infinite domain lower bound if such an operation is supported. Set extensions that seek to employ this should extend JuMP.set_lower_bound(domain::NewType, lower::Number).

Example

julia> set_lower_bound(t, -1)

julia> lower_bound(t)
-1.0

JuMP.set_upper_bound(pref::IndependentParameterRef, lower::Real)::Nothing

Extend the JuMP.set_upper_bound function to accomodate infinite parameters. Updates the infinite domain upper bound if and only if it is an IntervalDomain. Errors otherwise. Extensions with user-defined infinite domains should extend JuMP.set_upper_bound(domain::NewType, upper::Number) if appropriate.

Example

julia> set_upper_bound(t, 2)

julia> upper_bound(t)
2.0

add_supports(
    pref::IndependentParameterRef,
    supports::Union{Real, Vector{<:Real}, UnitRange{<:Real}, StepRange{<:Real}, NTuple, Base.Generator};
    [label::Type{<:AbstractSupportLabel} = UserDefined]
    )::Nothing

Add additional support points for pref with identifying label label.

Example

julia> add_supports(t, 0.5)

julia> supports(t)
3-element Array{Float64,1}:
 0.0
 0.5
 1.0

julia> add_supports(t, [0.25, 1])

julia> supports(t)
4-element Array{Float64,1}:
 0.0
 0.25
 0.5
 1.0

set_supports(
    pref::IndependentParameterRef,
    supports::Union{Vector{<:Real}, UnitRange{<:Real}, StepRange{<:Real}, NTuple, Base.Generator};
    [force::Bool = false,
    label::Type{<:AbstractSupportLabel} = UserDefined]
    )::Nothing

Specify the support points for pref. Errors if the supports violate the bounds associated with the infinite domain. Warns if the points are not unique. If force this will overwrite exisiting supports otherwise it will error if there are existing supports.

Example

julia> set_supports(t, [0, 1])

julia> supports(t)
2-element Array{Int64,1}:
 0
 1

delete_supports(
    pref::IndependentParameterRef; 
    [label::Type{<:AbstractSupportLabel} = All]
    )::Nothing

Delete the support points for pref. If label != All then delete label and any supports that solely depend on it.

Example

julia> delete_supports(t)

julia> supports(t)
ERROR: Parameter t does not have supports.

generate_and_add_supports!(
    pref::IndependentParameterRef,
    domain::AbstractInfiniteDomain,
    [method::Type{<:AbstractSupportLabel}];
    [num_supports::Int = DefaultNumSupports]
    )::Nothing

Generate supports for independent parameter pref via generate_support_values and add them to pref. This is intended as an extendable internal method for fill_in_supports!. Most extensions that empoy user-defined infinite domains can typically enable this by extending generate_support_values. Errors if the infinite domain type is not recognized.

fill_in_supports!(
    pref::IndependentParameterRef;
    [num_supports::Int = DefaultNumSupports]
    )::Nothing

Automatically generate support points for a particular independent parameter pref. Generating num_supports for the parameter. The supports are generated uniformly if the underlying infinite domain is an IntervalDomain or they are generating randomly accordingly to the distribution if the domain is a UniDistributionDomain. Will add nothing if there are supports and modify = false. Extensions that use user defined domain types should extend generate_and_add_supports! and/or generate_support_values as needed. Errors if the infinite domain type is not recognized.

Example

julia> fill_in_supports!(x, num_supports = 4)

julia> supports(x)
4-element Array{Number,1}:
 0.0
 0.333
 0.667
 1.0

JuMP.delete(model::InfiniteModel, pref::ScalarParameterRef)::Nothing

Extend JuMP.delete to delete scalar parameters and their dependencies. All variables, constraints, and measure functions that depend on pref are updated to exclude it. Errors if the parameter is used by an infinite variable or if it is contained in an AbstractMeasureData DataType that is employed by a measure since the measure becomes invalid otherwise. Thus, measures that contain this dependency must be deleted first. Note that parameter_refs needs to be extended to allow deletion of parameters when custom AbstractMeasureData datatypes are used.

Example

julia> delete(model, x)

JuMP.set_name(pref::DependentParameterRef, name::String)::Nothing

Extend JuMP.set_name to set names of dependent infinite parameters.

Example

julia> set_name(vref, "par_name")

julia> name(vref)
"para_name"

set_infinite_domain(pref::DependentParameterRef,
                 domain::InfiniteScalarDomain)::Nothing

Specify the scalar infinite domain of the dependent infinite parameter pref to domain if pref is part of a CollectionDomain, otherwise an error is thrown. Note this will reset/delete all the supports contained in the underlying DependentParameters object. Also, errors if pref is used by a measure.

Example

julia> set_infinite_domain(x[1], IntervalDomain(0, 2))

julia> infinite_domain(x[1])
[0, 2]

set_infinite_domain(prefs::AbstractArray{<:DependentParameterRef},
                 domain::InfiniteArrayDomain)::Nothing

Specify the multi-dimensional infinite domain of the dependent infinite parameters prefs to domain. Note this will reset/delete all the supports contained in the underlying DependentParameters object. This will error if the not all of the dependent infinite parameters are included, if any of them are used by measures.

Example

julia> set_infinite_domain(x, CollectionDomain([IntervalDomain(0, 1), IntervalDomain(0, 2)]))

JuMP.set_lower_bound(pref::DependentParameterRef, lower::Real)::Nothing

Extend the JuMP.set_lower_bound function to accomodate a single dependent infinite parameter. Updates the infinite domain lower bound if such an operation is supported. Infinite scalar domain extensions that seek to employ this should extend JuMP.set_lower_bound(domain::NewType, lower::Number). This will call set_infinite_domain and will error if this is not well-defined. Note that existing supports will be deleted.

Example

julia> set_lower_bound(t, -1)

julia> lower_bound(t)
-1.0

JuMP.set_upper_bound(pref::DependentParameterRef, upper::Real)::Nothing

Extend the JuMP.set_upper_bound function to accomodate a single dependent infinite parameter. Updates the infinite domain upper bound if such an operation is supported. Infinite scalar domain extensions that seek to employ this should extend JuMP.set_upper_bound(domain::NewType, upper::Number). This will call set_infinite_domain and will error if this is not well-defined. Note that existing supports will be deleted.

Example

julia> set_upper_bound(t, -1)

julia> upper_bound(t)
-1.0

add_supports(
    prefs::AbstractArray{<:DependentParameterRef},
    supports::Vector{<:AbstractArray{<:Real}};
    [label::Type{<:AbstractSupportLabel} = UserDefined]
    )::Nothing

Add additional support points for prefs. Errors if the supports violate the domain of the infinite domain, if the dimensions don't match up properly, if prefs and supports have different indices, or not all of the prefs are from the same dependent infinite parameter container.

    add_supports(
        prefs::Vector{DependentParameterRef},
        supports::Array{<:Real, 2};
        [label::Type{<:AbstractSupportLabel} = UserDefined]
        )::Nothing

Specify the supports for a vector prefs of dependent infinite parameters. Here rows of supports correspond to prefs and the columns correspond to the supports. This is more efficient than the above method and will error for the same reasons.

Example

julia> add_supports(x, [[1], [1]])

julia> supports(x)
2×2 Array{Float64,2}:
 0.0  1.0
 0.0  1.0

julia> add_supports(x, ones(2, 1) * 0.5)

julia> supports(t)
2×3 Array{Float64,2}:
 0.0  1.0  0.5
 0.0  1.0  0.5

set_supports(
    prefs::AbstractArray{<:DependentParameterRef},
    supports::Vector{<:AbstractArray{<:Real}};
    [force::Bool = false,
    label::Type{<:AbstractSupportLabel} = UserDefined]
    )::Nothing

Specify the support points for prefs. Errors if the supports violate the domain of the infinite domain, if the dimensions don't match up properly, if prefs and supports have different indices, not all of the prefs are from the same dependent infinite parameter container, there are existing supports and force = false. Note that it is strongly preferred to use add_supports if possible to avoid destroying measure dependencies.

    set_supports(
        prefs::Vector{DependentParameterRef},
        supports::Array{<:Real, 2};
        [force::Bool = false,
        label::Type{<:AbstractSupportLabel} = UserDefined]
        )::Nothing

Specify the supports for a vector prefs of dependent infinite parameters. Here rows of supports correspond to prefs and the columns correspond to the supports. This is more efficient than the above method and will error for the same reasons.

Example

julia> set_supports(y, [[0, 1], [0, 1]])

julia> set_supports(x, [0 1; 0 1])

julia> supports(x)
2×2 Array{Float64,2}:
 0.0  1.0
 0.0  1.0

delete_supports(
    prefs::AbstractArray{<:DependentParameterRef};
    [label::Type{<:AbstractSupportLabel} = All]
    )::Nothing

Delete the support points for prefs. Errors if any of the parameters are used by a measure or if not all belong to the same set of dependent parameters. If label != All then that label is removed along with any supports that solely contain that label.

Example

julia> delete_supports(w)

generate_and_add_supports!(prefs::AbstractArray{<:DependentParameterRef},
                           domain::InfiniteArrayDomain,
                           [method::Type{<:AbstractSupportLabel}];
                           [num_supports::Int = DefaultNumSupports])::Nothing

Generate supports for prefs via generate_support_values and add them to pref. This is intended as an extendable internal method for fill_in_supports!. Most extensions that employ user-defined infinite domains can typically enable this by extending generate_support_values. However, in some cases it may be necessary to extend this when more complex operations need to take place then just adding supports to a set of infinite parameters. Errors if the infinite domain type is not recognized.

fill_in_supports!(prefs::AbstractArray{<:DependentParameterRef};
                  [num_supports::Int = DefaultNumSupports,
                   modify::Bool = true])::Nothing

Automatically generate support points for a container of dependent infinite parameters prefs. Generating up to num_supports for the parameters in accordance with generate_and_add_supports!. Will add nothing if there are supports and modify = false. Extensions that use user defined domain types should extend generate_and_add_supports! and/or generate_support_values as needed. Errors if the infinite domain type is not recognized.

Example

julia> fill_in_supports!(x, num_supports = 4)

julia> supports(x)
2×4 Array{Float64,2}:
 0.0  0.333  0.667  1.0
 0.0  0.333  0.667  1.0

JuMP.delete(model::InfiniteModel,
            prefs::AbstractArray{<:DependentParameterRef})::Nothing

Extend JuMP.delete to delete dependent infinite parameters and their dependencies. All variables, constraints, and measure functions that depend on prefs are updated to exclude them. Errors if the parameters are contained in an AbstractMeasureData datatype that is employed by a measure since the measure becomes invalid otherwise. Thus, measures that contain this dependency must be deleted first. Note that parameter_refs needs to be extended to allow deletion of parameters when custom AbstractMeasureData datatypes are used. Note that any dependent infinite variables will have their start values reset to the default via reset_start_value_function.

Example

julia> print(model)
Min measure(g(t, x)*t + x) + z
Subject to
 z ≥ 0.0
 g(t, x) + z ≥ 42.0, ∀ t ∈ [0, 6], x[1] ∈ [-1, 1], x[2] ∈ [-1, 1]
 g(0.5, x) = 0, x[1] ∈ [-1, 1], x[2] ∈ [-1, 1]

julia> delete(model, x)

julia> print(model)
Min measure(g(t)*t) + z
Subject to
 g(t) + z ≥ 42.0, ∀ t ∈ [0, 6]
 g(0.5) = 0

AbstractGenerativeInfo

An abstract type for storing information about generating supports that are made based on existing supports as required by certain measures and/or derivatives that depend on a certain independent infinite parameter. Such as the case with internal collocation supports.

NoGenerativeSupports <: AbstractGenerativeInfo

A DataType to signify that no generative supports will be generated for the measures and/or the derivatives. Has no fields.

UniformGenerativeInfo <: AbstractGenerativeInfo

A DataType for generative supports that will be generated in a uniform manner over finite elements (i.e., in between the existing supports). These generative supports are described by the support_basis which lie in a nominal domain [0, 1]. The constructor is of the form:

    UniformGenerativeInfo(support_basis::Vector{<:Real}, label::DataType, 
                          [lb::Real = 0, ub::Real = 1])

where the support_basis is defined over [lb, ub].

Fields

• support_basis::Vector{Float64}: The basis of generative supports defined in [0, 1] that will be transformed for each finite element.
• label::DataType: The unique label to be given to each generative support.

has_generative_supports(pref::IndependentParameterRef)::Bool

Return whether generative supports have been added to pref in accordance with its generative support info.

support_label(info::AbstractGenerativeInfo)::DataType

Return the support label to be associated with generative supports produced in accordance with info. This is intended an internal method that should be extended for user defined types of AbstractGenerativeInfo.

generative_support_info(pref::IndependentParameterRef)::AbstractGenerativeInfo

Return the generative support information associated with pref.

make_generative_supports(info::AbstractGenerativeInfo,
                         pref::IndependentParameterRef,
                         existing_supps::Vector{Float64}
                         )::Vector{Float64}

Generate the generative supports for pref in accordance with info and the existing_supps that pref has. The returned supports should not include existing_supps. This is intended as internal method to enable add_generative_supports and should be extended for any user defined info types that are created to enable new measure and/or derivative evaluation techniques that require the creation of generative supports.

add_generative_supports(pref::IndependentParameterRef)::Nothing

Create generative supports for pref if needed in accordance with its generative support info using make_generative_supports and add them to pref. This is intended as an internal function, but can be useful user defined transformation backend extensions that utlize our support system.

add_generative_supports(prefs; [kwargs...])

Define add_generative_supports for general variable references. It relies on add_generative_supports being defined for the underlying DispatchVariableRef, otherwise an ArgumentError is thrown. See the underlying docstrings for more information. Note that this is a auto generated wrapper and the underlying method may or may not use kwargs.