Measure Operators

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

Measure Data

InfiniteOpt.DiscreteMeasureDataMethod
DiscreteMeasureData(pref::GeneralVariableRef,
    coefficients::Vector{<:Real},
    supports::Vector{<:Real};
    [label::Type{<:AbstractSupportLabel} = generate_unique_label(),
    weight_function::Function = [`default_weight`](@ref),
    lower_bound::Real = NaN,
    upper_bound::Real = NaN,
    is_expect::Bool = false]
    )::DiscreteMeasureData

Returns a 1-dimensional DiscreteMeasureData object that can be utilized to define measures using measure. This accepts input for a scalar (single) infinite parameter. A description of the other arguments is provided in the documentation for DiscreteMeasureData. Errors if supports are out bounds or an unequal number of supports and coefficients are given. Note that by default a unique label is generated via generate_unique_label to ensure the supports can be located in the infinite parameter support storage. Advanced implementations, may choose a different behavior but should do so with caution.

Example

julia> data = DiscreteMeasureData(pref, [0.5, 0.5], [1, 2]);
source
InfiniteOpt.DiscreteMeasureDataMethod
DiscreteMeasureData(prefs::AbstractArray{GeneralVariableRef},
    coefficients::Vector{<:Real},
    supports::Vector{<:AbstractArray{<:Real}};
    label::Type{<:AbstractSupportLabel} = generate_unique_label(),
    weight_function::Function = [`default_weight`](@ref),
    lower_bounds::AbstractArray{<:Real} = [NaN...],
    upper_bounds::AbstractArray{<:Real} = [NaN...],
    is_expect::Bool = false
    )::DiscreteMeasureData

Returns a DiscreteMeasureData object that can be utilized to define measures using measure. This accepts input for an array (multi) parameter. The inner arrays in the supports vector need to match the formatting of the array used for parameter_refs. A description of the other arguments is provided in the documentation for DiscreteMeasureData. Errors if supports are out bounds, an unequal number of supports and coefficients are given, the array formats do not match, or if mixed infinite parameter types are given. Note that by default a unique label is generated via generate_unique_label to ensure the supports can be located in the infinite parameter support storage. Advanced implementations, may choose a different behavior but should do so with caution.

Example

julia> data = DiscreteMeasureData(prefs, [0.5, 0.5], [[1, 1], [2, 2]]);
source
InfiniteOpt.DiscreteMeasureDataType
DiscreteMeasureData{P <: Union{JuMP.AbstractVariableRef,
                    Vector{<:JuMP.AbstractVariableRef}},
                    N, B <: Union{Float64, Vector{Float64}},
                    F <: Function
                    } <: AbstractMeasureData

A DataType for immutable measure abstraction data where the abstraction is of the form: $measure = \int_{\tau \in T} f(\tau) w(\tau) d\tau \approx \sum_{i = 1}^N \alpha_i f(\tau_i) w(\tau_i)$. The supports and coefficients are immutable (i.e., they will not change even if supports are changed for the underlying infinite parameter.) This type can be used for both 1-dimensional and multi-dimensional measures.

Fields

  • parameter_refs::P: The infinite parameter(s) over which the integration occurs. These can be comprised of multiple independent parameters, but dependent parameters cannot be mixed with other types.
  • coefficients::Vector{Float64}: Coefficients $\alpha_i$ for the above measure abstraction.
  • supports::Array{Float64, N}: Supports points $\tau_i$. This is a Vector if only one parameter is given, otherwise it is a Matrix where the supports are stored column-wise.
  • label::DataType: Label for the support points $\tau_i$ when stored in the infinite parameter(s), stemming from AbstractSupportLabel.
  • weight_function::F: Weighting function $w$ must map an individual support value to a Real scalar value.
  • lower_bounds::B: Lower bound in accordance with $T$, this denotes the intended interval of the measure and should be NaN if ignored
  • upper_bounds::B: Same as above but the upper bound.
  • is_expect::Bool: Is this data associated with an expectation call?
source
InfiniteOpt.FunctionalDiscreteMeasureDataMethod
FunctionalDiscreteMeasureData(pref::GeneralVariableRef,
    coeff_func::Function,
    min_num_supports::Int,
    label::Type{<:AbstractSupportLabel};
    [weight_function::Function = [`default_weight`](@ref),
    lower_bound::Real = NaN,
    upper_bound::Real = NaN,
    is_expect::Bool = false,
    generative_support_info::AbstractGenerativeInfo = NoGenerativeSupports()]
    )::FunctionalDiscreteMeasureData

Returns a 1-dimensional FunctionalDiscreteMeasureData object that can be utilized to define measures using measure. This accepts input for a scalar (single) infinite parameter. A description of the other arguments is provided in the documentation for FunctionalDiscreteMeasureData. Errors if pref is not an infinite parameter. Built-in choices for label include:

  • All: Use all of the supports stored in pref
  • MCSample: Use Monte Carlo samples associated with pref
  • WeightedSample: Use weighted Monte Carlo samples associated with pref
  • UniformGrid: Use uniform grid points associated with pref.

Example

julia> data = FunctionalDiscreteMeasureData(pref, my_func, 20, UniformGrid);
source
InfiniteOpt.FunctionalDiscreteMeasureDataMethod
FunctionalDiscreteMeasureData(prefs::AbstractArray{GeneralVariableRef},
    coeff_func::Function,
    min_num_supports::Int,
    label::Type{<:AbstractSupportLabel};
    [weight_function::Function = [`default_weight`](@ref),
    lower_bounds::AbstractArray{<:Real} = [NaN...],
    upper_bounds::AbstractArray{<:Real} = [NaN...],
    is_expect::Bool = false]
    )::FunctionalDiscreteMeasureData

Returns a multi-dimensional FunctionalDiscreteMeasureData object that can be utilized to define measures using measure. This accepts input for an array of infinite parameters. A description of the other arguments is provided in the documentation for FunctionalDiscreteMeasureData. Errors if prefs are not infinite parameters or if the mixed parameter types are provided. Built-in choices for label include:

  • All: Use all of the supports stored in prefs
  • MCSample: Use Monte Carlo samples associated with prefs
  • WeightedSample: Use weighted Monte Carlo samples associated with prefs
  • UniformGrid: Use uniform grid points associated with prefs.

Example

julia> data = FunctionalDiscreteMeasureData(prefs, my_func, 20, MCSample);
source
InfiniteOpt.FunctionalDiscreteMeasureDataType
FunctionalDiscreteMeasureData{P <: Union{JuMP.AbstractVariableRef,
                              Vector{<:JuMP.AbstractVariableRef}},
                              B <: Union{Float64, Vector{Float64}},
                              I <: AbstractGenerativeInfo,
                              F1 <: Function,
                              F2 <: Function
                              } <: AbstractMeasureData

A DataType for mutable measure abstraction data where the abstraction is of the form: $measure = \int_{\tau \in T} f(\tau) w(\tau) d\tau \approx \sum_{i = 1}^N \alpha_i f(\tau_i) w(\tau_i)$. This abstraction is equivalent to that of DiscreteMeasureData, but the difference is that the supports are not fully known at the time of measure creation. Thus, functions are stored that will be used to generate the concrete support points $\tau_i$ and their coefficients $\alpha_i$ when the measure is evaluated (expanded). These supports are identified/generated in accordance with the label with a gaurantee that at least num_supports are generated. For example, if label = MCSample and num_supports = 100 then the measure will use all of the supports stored in the parameter_refs with the label MCSample and will ensure there are at least 100 are generated. This type can be used for both 1-dimensional and multi-dimensional measures.

For 1-dimensional measures over independent infinite parameters, the generative_supp_info specifies the info needed to make generative supports based on those with that exist with label. Note that only 1 kind of generative supports are allowed for each infinite parameter.

Fields

  • parameter_refs::P: The infinite parameter(s) over which the integration occurs. These can be comprised of multiple independent parameters, but dependent parameters cannot be mixed with other types.
  • coeff_function::F1: Coefficient generation function making $\alpha_i$ for the above measure abstraction. It should take all the supports as input (formatted as an Array) and return the corresponding vector of coefficients.
  • min_num_supports::Int: Specifies the minimum number of supports $\tau_i$ desired in association with parameter_refs and label.
  • label::DataType: Label for the support points $\tau_i$ which are/will be stored in the infinite parameter(s), stemming from AbstractSupportLabel.
  • generative_supp_info::I: Information needed to generate supports based on other existing ones.
  • weight_function::F2: Weighting function $w$ must map an individual support value to a Real scalar value.
  • lower_bounds::B: Lower bounds in accordance with $T$, this denotes the intended interval of the measure and should be NaN if ignored
  • upper_bounds::B: Same as above but the upper bounds.
  • is_expect::Bool: Is this data associated with an expectation call?
source
InfiniteOpt.parameter_refsMethod
parameter_refs(data::AbstractMeasureData)::Union{GeneralVariableRef,
                                                 AbstractArray{GeneralVariableRef}}

Return the infinite parameter reference(s) in data. This is intended as an internal function to be used with measure addition. User-defined measure data types will need to extend this function otherwise an error is thrown.

source
InfiniteOpt.support_labelMethod
support_label(data::AbstractMeasureData)::Type{<:AbstractSupportLabel}

Return the label stored in data associated with its supports. This is intended as en internal method for measure creation and ensures any new supports are added to parameters with such a label. User-defined measure data types should extend this functionif supports are used, otherwise an error is thrown.

source
InfiniteOpt.generative_support_infoMethod
generative_support_info(data::AbstractMeasureData)::AbstractGenerativeInfo

Return the generative support creation info that corresponds to data. This is intended as an internal method and only needs to be extended for user-defined measure data types that use generative supports.

source
JuMP.lower_boundMethod
JuMP.lower_bound(data::AbstractMeasureData)::Union{Float64, Vector{Float64}}

Return the lower bound associated with data that defines its domain. This is intended as an internal method, but may be useful for extensions. User-defined measure data types should extend this function if desired, otherwise NaN is returned

source
JuMP.upper_boundMethod
JuMP.upper_bound(data::AbstractMeasureData)::Union{Float64, Vector{Float64}}

Return the lower bound associated with data that defines its domain. This is intended as an internal method, but may be useful for extensions. User-defined measure data types should extend this function if desired, otherwise NaN is returned.

source
InfiniteOpt.supportsMethod
supports(data::AbstractMeasureData)::Array{Float64}

Return the supports associated with data and its infinite parameters. This is intended as en internal method for measure creation and ensures any new supports are added to parameters. User-defined measure data types should extend this function if appropriate, otherwise an empty vector is returned.

source
InfiniteOpt.num_supportsMethod
num_supports(data::AbstractMeasureData)::Int

Return the number supports associated with data and its infinite parameters. This is intended as an internal method for measure creation. User-defined measure data types should extend this function if appropriate, otherwise 0 is returned.

source
InfiniteOpt.min_num_supportsMethod
min_num_supports(data::AbstractMeasureData)::Int

Return the minimum number of supports associated with data. By fallback, this will just return num_supports(data). This is primarily intended for internal queries of FunctionalDiscreteMeasureData, but can be extended for other measure data types if needed.

source
InfiniteOpt.coefficient_functionMethod
coefficient_function(data::AbstractMeasureData)::Function

Return the coefficient function stored in data associated with its expansion abstraction is there is such a function. This is intended as an internal method for measure creation. User-defined measure data types should extend this function if appropriate, otherwise an error is thrown for unsupported types.

source
InfiniteOpt.coefficientsMethod
coefficients(data::AbstractMeasureData)::Vector{<:Real}

Return the coefficients associated with data associated with its expansion abstraction. This is intended as en internal method for measure creation. User-defined measure data types should extend this function if appropriate, otherwise an empty vector is returned.

source
InfiniteOpt.weight_functionMethod
weight_function(data::AbstractMeasureData)::Function

Return the weight function stored in data associated with its expansion abstraction. This is intended as en internal method for measure creation. User-defined measure data types should extend this function if appropriate, otherwise an error is thrown.

source

Definition

General

InfiniteOpt.measureFunction
measure(expr::JuMP.AbstractJuMPScalar,
        data::AbstractMeasureData;
        [name::String = "measure"])::GeneralVariableRef

Return a measure reference that evaluates expr using according to data. The measure data data determines how the measure is to be evaluated. Typically, the DiscreteMeasureData and the FunctionalDiscreteMeasureData constructors can be used to for data. The variable expression expr can contain InfiniteOpt variables, infinite parameters, other measure references (meaning measures can be nested), and constants. Typically, this is called inside of JuMP.@expression, JuMP.@objective, and JuMP.@constraint in a manner similar to sum. Note measures are not explicitly evaluated until build_transformation_backend! is called or unless they are expanded via expand or expand_all_measures!.

Example

julia> tdata = DiscreteMeasureData(t, [0.5, 0.5], [1, 2]);

julia> xdata = DiscreteMeasureData(xs, [0.5, 0.5], [[-1, -1], [1, 1]]);

julia> constr_RHS = @expression(model, measure(g - s + 2, tdata) + s^2)
measure{t}[g(t) - s + 2] + s²

julia> @objective(model, Min, measure(g - 1  + measure(T, xdata), tdata))
measure{xs}[g(t) - 1 + measure{xs}[T(t, x)]]
source
InfiniteOpt.@measureMacro
@measure(expr::JuMP.AbstractJuMPScalar,
         data::AbstractMeasureData;
         [name::String = "measure"])::GeneralVariableRef

An efficient wrapper for measure, please see its doc string for more information.

source
InfiniteOpt.build_measureFunction
build_measure(expr::JuMP.AbstractJuMPScalar,
              data::AbstractMeasureData)::Measure

Build and return a Measure given the expression to be measured expr using measure data data. This principally serves as an internal method for measure definition. Errors if the supports associated with data violate an finite variable parameter bounds of finite variables that are included in the measure.

source
InfiniteOpt.MeasureType
Measure{T <: JuMP.AbstractJuMPScalar, V <: AbstractMeasureData}

A DataType for measure abstractions. The abstraction is determined by data and is enacted on func when the measure is evaluated (expended).

Fields

  • func::T The InfiniteOpt expression to be measured.
  • data::V Data of the abstraction as described in a AbstractMeasureData concrete subtype.
  • group_int_idxs::Vector{Int}: The parameter group integer indices of the evaluated measure expression (i.e., the group integer indices of func excluding those that belong to data).
  • parameter_nums::Vector{Int}: The parameter numbers that parameterize the evaluated measure expression. (i.e., the parameter numbers of func excluding those that belong to data).
  • constant_func::Bool: Indicates if func is not parameterized by the infinite parameters in data. (i.e., do the group integer indices of func and data have no intersection?) This is useful to enable analytic evaluations if possible.
source
InfiniteOpt.add_measureFunction
add_measure(model::InfiniteModel, meas::Measure,
            name::String = "measure")::GeneralVariableRef

Add a measure to model and return the corresponding measure reference. This operates in a manner similar to JuMP.add_variable. Note this intended as an internal method.

source
InfiniteOpt.add_supports_to_parametersMethod
add_supports_to_parameters(data::AbstractMeasureData)::Nothing

Add supports as appropriate with data to the underlying infinite parameters. This is an internal method with by add_measure and should be defined for user-defined measure data types.

source
InfiniteOpt.MeasureDataType
MeasureData{M <: Measure} <: AbstractDataObject

A mutable DataType for storing Measures and their data.

Fields

  • measure::M: The measure structure.
  • name::String: The base name used for printing name(meas_expr d(par)).
  • measure_indices::Vector{MeasureIndex}: Indices of dependent measures.
  • constraint_indices::Vector{InfOptConstraintIndex}: Indices of dependent constraints.
  • derivative_indices::Vector{DerivativeIndex}: Indices of dependent derivatives.
  • in_objective::Bool: Is this used in objective?
source
InfiniteOpt.MeasureRefType
MeasureRef <: DispatchVariableRef

A DataType for referring to measure abstractions.

Fields

  • model::InfiniteModel: Infinite model.
  • index::MeasureIndex: Index of the measure in model.
source

Integrals

InfiniteOpt.MeasureToolbox.integralMethod
integral(expr::JuMP.AbstractJuMPScalar,
         pref::GeneralVariableRef,
         [lower_bound::Real = lower_bound(pref),
         upper_bound::Real = upper_bound(pref);
         kwargs...])::GeneralVariableRef

Returns a measure reference that evaluates the integral of expr with respect to infinite parameter pref from lower_bound to upper_bound. This thus considers integrals of the form: $\int_{p \in P} expr(p) w(p) dp$ where $p$ is an infinite parameter and $w$ is the weight function is 1 by default. This function provides a high-level interface that ultimately constructs an appropriate concrete form of AbstractMeasureData via generate_integral_data in accordance with the keyword arugment eval_method that is then used with measure. Note that it is preferred to call @integral when expr is not just a single variable reference. Errors for bad bound input.

The keyword arguments are as follows:

See set_uni_integral_defaults to update the default keyword argument values for all one-dimensional integral calls.

Example

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

julia> @variable(model, f, Infinite(x))
f(x)

julia> int = integral(f, x)
∫{x ∈ [0, 1]}[f(x)]

julia> expand(int)
0.2 f(0.8236475079774124) + 0.2 f(0.9103565379264364) + 0.2 f(0.16456579813368521) + 0.2 f(0.17732884646626457) + 0.2 f(0.278880109331201)
source
InfiniteOpt.MeasureToolbox.∫Method
∫(expr::JuMP.AbstractJuMPScalar,
  pref::GeneralVariableRef,
  [lower_bound::Real = NaN,
  upper_bound::Real = NaN;
  kwargs...])::GeneralVariableRef

A convenient wrapper for integral. The unicode symbol is produced via \int.

source
InfiniteOpt.MeasureToolbox.uni_integral_defaultsFunction
uni_integral_defaults()::Dict{Symbol, Any}

Get the default keyword argument values for defining one-dimensional integrals.

julia> uni_integral_defaults()
Dict{Symbol,Any} with 1 entry:
  :eval_method => Automatic()
source
InfiniteOpt.MeasureToolbox.set_uni_integral_defaultsFunction
set_uni_integral_defaults(; kwargs...)::Nothing

Set the default keyword argument settings for one-dimensional integrals. The keyword arguments of this function will be recorded in the default keyword argument dictionary. These will determine the default keyword argument values when calling integral with a single infinite parameter.

Example

julia> uni_integral_defaults()
Dict{Symbol,Any} with 1 entry:
  :eval_method => Automatic()


julia> set_uni_integral_defaults(num_supports = 5, eval_method = Quadrature(),
                                 new_kwarg = true)

julia> uni_integral_defaults()
Dict{Symbol,Any} with 3 entries:
  :new_kwarg             => true
  :num_supports          => 5
  :eval_method           => Quadrature()
source
InfiniteOpt.MeasureToolbox.clear_uni_integral_defaultsFunction
clear_uni_integral_defaults()::Nothing

Clears and resets the keyword argument defaults for univariate integrals to their default state.

Example

julia> uni_integral_defaults()
Dict{Symbol,Any} with 3 entries:
  :new_kwarg             => true
  :num_supports          => 5
  :eval_method           => Quadrature()

julia> clear_uni_integral_defaults()

julia> uni_integral_defaults()
Dict{Symbol,Any} with 1 entry:
  :eval_method => Automatic()
source
InfiniteOpt.MeasureToolbox.integralMethod
integral(expr::JuMP.AbstractJuMPScalar,
         prefs::AbstractArray{GeneralVariableRef},
         [lower_bounds::Union{Real, AbstractArray{<:Real}} = [lower_bound(pref)...],
         upper_bounds::Union{Real, AbstractArray{<:Real}} = [upper_bound(pref)...];
         kwargs...])::GeneralVariableRef

Returns a measure reference that evaluates the integral of expr with respect to infinite parameters prefs from lower_bounds to upper_bounds. This thus considers integrals of the form: $\int_{p \in P} expr(p) w(p) dp$ where $p$ is an infinite parameter and $w$ is the weight function is 1 by default. This function provides a high-level interface that ultimately constructs an appropriate concrete form of AbstractMeasureData via generate_integral_data in accordance with the keyword arugment eval_method that is then used with measure. Note that it is preferred to call @integral when expr is not just a single variable reference. Errors when the container types and dimensions do not match or the bounds are invalid.

The keyword arguments are as follows:

  • eval_method::AbstractMultivariateMethod: Used to determine the numerical evaluation scheme. Possible choices include:
  • num_supports: The minimum number of supports to be generated (if used by eval_method)
  • weight_func: $w(p)$ above with parameter value inputs and scalar output

See set_multi_integral_defaults to update the default keyword argument values for all multi-dimensional integral calls.

Example

julia> @infinite_parameter(model, x[1:2] in [0, 1], independent = true);

julia> @variable(model, f, Infinite(x));

julia> int = integral(f, x)
∫{x ∈ [0, 1]^2}[f(x)]
source
InfiniteOpt.MeasureToolbox.∫Method
∫(expr::JuMP.AbstractJuMPScalar,
  prefs::AbstractArray{GeneralVariableRef},
  [lower_bounds::Union{Real, AbstractArray{<:Real}} = NaN,
  upper_bounds::Union{Real, AbstractArray{<:Real}} = NaN;
  kwargs...])::GeneralVariableRef

A convenient wrapper for integral. The unicode symbol is produced via \int.

source
InfiniteOpt.MeasureToolbox.multi_integral_defaultsFunction
multi_integral_defaults()::Dict{Symbol, Any}

Get the default keyword argument values for defining multi-dimensional integrals.

julia> multi_integral_defaults()
Dict{Symbol,Any} with 1 entry:
  :eval_method => Automatic()
source
InfiniteOpt.MeasureToolbox.set_multi_integral_defaultsFunction
set_multi_integral_defaults(; kwargs...)::Nothing

Set the default keyword argument settings for multi-dimesnional integrals. The keyword arguments of this function will be recorded in the default keyword argument dictionary. These will determine the default keyword argument values when calling integral with an array of infinite parameters.

Example

julia> multi_integral_defaults()
Dict{Symbol,Any} with 1 entry:
  :eval_method => Automatic()

julia> set_multi_integral_defaults(num_supports = 5, new_kwarg = true)

julia> multi_integral_defaults()
Dict{Symbol,Any} with 3 entries:
  :new_kwarg             => true
  :num_supports          => 5
  :eval_method           => Automatic()
source
InfiniteOpt.MeasureToolbox.clear_multi_integral_defaultsFunction
clear_multi_integral_defaults()::Nothing

Clears and resets the keyword argument defaults for multivariate integrals to their default state.

Example

julia> multi_integral_defaults()
Dict{Symbol,Any} with 3 entries:
  :new_kwarg             => true
  :num_supports          => 5
  :eval_method           => Automatic()

julia> clear_multi_integral_defaults()

julia> multi_integral_defaults()
Dict{Symbol,Any} with 1 entry:
  :eval_method => Automatic()
source
InfiniteOpt.MeasureToolbox.@integralMacro
@integral(expr::JuMP.AbstractJuMPScalar,
          prefs::Union{GeneralVariableRef, AbstractArray{GeneralVariableRef}},
          [lower_bounds::Union{Real, AbstractArray{<:Real}} = default_bounds,
          upper_bounds::Union{Real, AbstractArray{<:Real}} = default_bounds;
          kwargs...])::GeneralVariableRef

An efficient wrapper for integral and integral. Please see the above doc strings for more information.

source
InfiniteOpt.MeasureToolbox.@∫Macro
@∫(expr::JuMP.AbstractJuMPScalar,
   prefs::Union{GeneralVariableRef, AbstractArray{GeneralVariableRef}},
   [lower_bounds::Union{Real, AbstractArray{<:Real}} = default_bounds,
   upper_bounds::Union{Real, AbstractArray{<:Real}} = default_bounds;
   kwargs...])::GeneralVariableRef

A convenient wrapper for @integral. The unicode symbol is produced via \int.

source
InfiniteOpt.MeasureToolbox.UniTrapezoidType
UniTrapezoid <: AbstractUnivariateMethod

An integral evalution method that uses the trapezoid rule to in combination with all parameter supports available when the integral is expanded and/or when the infinite model is optimized, whichever comes first. Note this method will ignore the num_supports keyword argument. The upper and lower bounds of the integral will automatically be added as supports. Note this is valid only for finite integral domains. Contains no fields.

source
InfiniteOpt.MeasureToolbox.UniMCSamplingType
UniMCSampling <: AbstractUnivariateMethod

An integral evaluation method that uses uniform Monte Carlo sampling to approximate the integral. This variant will add more supports to the model as needed to satisfy num_supports and it will include all supports with the MCSample label up till the integral is expanded and/or when the infinite model is optimized, whichever comes first. Note this is valid only for finite integral domains. Contains no fields.

source
InfiniteOpt.MeasureToolbox.UniIndepMCSamplingType
UniIndepMCSampling <: AbstractUnivariateMethod

An integral evaluation method that uses uniform Monte Carlo sampling to approximate the integral similar to UniMCSampling. However, this variant will generate its own set of supports and ignore all other supports with the MCSample label. Note this is valid only for finite integral domains. This is not compatible with individual dependent parameters. Contains no fields.

source
InfiniteOpt.MeasureToolbox.QuadratureType
Quadrature <: AbstractUnivariateMethod

A general integral evaluation method that will automatically select the appropriate quadrature method to approximate the integral. Please note that this will generate a unique set of parameter supports and will ignore existing supports when the integral is evaluated and thus should be used with caution. However, this method is able to handle infinite and semi-infinite integral domains. This is not compatible with individual dependent parameters. Contains no fields.

source
InfiniteOpt.MeasureToolbox.GaussHermiteType
GaussHermite <: AbstractUnivariateMethod

An integral evaulation method that uses Gauss-Hermite quadrature to evaluate integrals. This is valid for infinite integral domains. It will take this form:

$\int_{-∞}^{∞} f(x) e^{-x^2} \approx \sum_{i=1}^{n} \alpha_i f(x_i)$

Using the weight function: $w(x)$ = $e^{-x^2}$

Note this will generate its own set of supports and will ignore other parameter supports. This is not compatible with individual dependent parameters.

source
InfiniteOpt.MeasureToolbox.GaussLegendreType
GaussLegendre <: FiniteGaussQuad

An integral evaulation method that uses Gauss-Legendre quadrature to evaluate integrals. This is valid for finite integral domains. Note this will generate its own set of supports and will ignore other parameter supports. This is not compatible with individual dependent parameters. Contains no fields.

source
InfiniteOpt.MeasureToolbox.GaussRadauType
GaussRadau <: FiniteGaussQuad

An integral evaulation method that uses Gauss-Radau quadrature to evaluate integrals. This is valid for finite integral domains. Note this will generate its own set of supports and will ignore other parameter supports. This is not compatible with individual dependent parameters. Contains no fields.

source
InfiniteOpt.MeasureToolbox.GaussLobattoType
GaussLobatto <: FiniteGaussQuad

An integral evaulation method that uses Gauss-Lobatto quadrature to evaluate integrals. This is valid for finite integral domains. Note this will generate its own set of supports and will ignore other parameter supports. This is not compatible with individual dependent parameters. Contains no fields.

source
InfiniteOpt.MeasureToolbox.GaussJacobiType
GaussJacobi <: FiniteGaussQuad

An integral evaulation method that uses Gauss-Jacobi quadrature to evaluate integrals. It will take this form:

$\int_{-1}^{1} f(x) (1-x)^\alpha (1+x)^\beta dx \approx \sum_{i=1}^{n} \alpha_i f(x_i)$

Where,

$(1-x)^\alpha (1+x)^\beta$

is the weight function. This is valid for finite integral domains. This requires the user to input the alpha and beta shape parameters for their function. This will then generate its own set of supports and will ignore other parameter supports. This is not compatible with individual dependent parameters. If α or β is < -1, an error will be returned.

Fields

  • α::Float64: Shape parameter that must be > -1
  • β::Float64: Shape parameter that must be > -1
source
InfiniteOpt.MeasureToolbox.FEGaussLobattoType
FEGaussLobatto <: AbstractUnivariateMethod

Integral evaluation method that allows for the user to specify supports to be included in quadrature evaluation. The upper and lower bounds of the integral will automatically be added as supports. This method uses Gauss Lobatto quadrature to decompose the overall Integral into smaller integrals that span the user defined supports as follows:

$\int_{x_1}^{x_3} f(x) dx = \int_{x_1}^{x_2} f(x) dx + \int_{x_2}^{x_3} f(x) dx$

where the integrals are evaluated using Gauss Lobatto quadrature:

$\int f(x) dx \approx \sum_{i=1}^{n} \alpha_i f(x_i)$

source
InfiniteOpt.MeasureToolbox.GaussChebyshevType
GaussChebyshev <: FiniteGaussQuad

An integral evaulation method that uses Gauss-Chebyshev quadrature to evaluate integrals. This is valid for finite integral domains. This requires the user to input the order of Guass-Chebyshev Quadrature they want to use. If the order is not between 1 and 4 an error will be returned. The integral evaluated is as follows:

$\int_{-1}^{1} f(x) w(x) \approx \sum_{i=1}^{n} \alpha_i f(x_i)$

The weight functions are as follows:

  • 1st order: $w(x) = \frac{1}{\sqrt{1-x^2}}$
  • 2nd order: $w(x) = {\sqrt{1-x^2}}$
  • 3rd order: $w(x) = \sqrt{(1+x)/(1-x)}$
  • 4th order: $w(x) = \sqrt{(1-x)/(1+x)}$

This will then generate its own set of supports and will ignore other parameter supports. This is not compatible with individual dependent parameters.

Fields

  • order::Int: Specifies the order of Gauss-Chebyshev Quadrature. Must be between 1 and 4.
source
InfiniteOpt.MeasureToolbox.GaussLaguerreType
GaussLaguerre <: AbstractUnivariateMethod

An integral evaulation method that uses Gauss-Laguerre quadrature to evaluate integrals. This is valid for semi-infinite integral domains.

This method evaluates the following integral:

$\int_{0}^{+∞} f(x) e^{-x} \approx \sum_{i=1}^{n} \alpha_i f(x_i)$

Using the weight function:

$w(x) = e^{-x}$

Note this will generate its own set of supports and will ignore other parameter supports. This is not compatible with individual dependent parameters.

source
InfiniteOpt.MeasureToolbox.MultiMCSamplingType
MultiMCSampling <: AbstractMultivariateMethod

An integral evaluation method that uses uniform Monte Carlo sampling to approximate the integral. This variant will add more supports to the model as needed to satisfy num_supports and it will include all supports with the MCSample label up till the integral is expanded and/or when the infinite model is optimized, whichever comes first. Note this is valid only for finite integral domains. If an array of independent infinite parameters is specified, they must use the same amount of supports. Contains no fields.

source
InfiniteOpt.MeasureToolbox.MultiIndepMCSamplingType
MultiIndepMCSampling <: AbstractMultivariateMethod

An integral evaluation method that uses uniform Monte Carlo sampling to approximate the integral similar to MultiMCSampling. However, this variant will generate its own set of supports and ignore all other supports with the MCSample label. Note this is valid only for finite integral domains. Contains no fields.

source
InfiniteOpt.MeasureToolbox.generate_integral_dataFunction
generate_integral_data(
    prefs::Union{InfiniteOpt.GeneralVariableRef, Vector{InfiniteOpt.GeneralVariableRef}},
    lower_bounds::Union{Real, Vector{<:Real}},
    upper_bounds::Union{Real, Vector{<:Real}},
    method::V; [num_supports::Int = InfiniteOpt.DefaultNumSupports,
    weight_func::Function = InfiniteOpt.default_weight,
    extra_kwargs...]
    )::InfiniteOpt.AbstractMeasureData where {V <: AbstractIntegralMethod}

Generate the appropriate concrete realization of AbstractMeasureData using method. Here prefs, lower_bounds, and upper_bounds will always have a 1 to 1 correspondence when this is called from integral. Please refer to the method docstrings for an explanation of each one.

User-defined method extensions should first define a concrete method type inheriting from AbstractUnivariateMethod or AbstractMultivariateMethod as appropriate and then implement extend this method using that type for method.

source

Expectations

InfiniteOpt.MeasureToolbox.expectFunction
expect(expr::JuMP.AbstractJuMPScalar,
       prefs::Union{GeneralVariableRef, AbstractArray{GeneralVariableRef};
       [num_supports::Int = DefaultNumSupports])::GeneralVariableRef

Makes a measure for expr based on its expectation with respect to prefs. For prefs with distribution domains this is essentially equivalent to

1/total_num_supports * support_sum(expr, prefs, label = WeightedSample)

Thus, for these domain types it only considers supports that are added to prefs via generation on creation (i.e., specifying the num_supports keyword when creating prefs). For incorporating other supports consider calling integral and using the weight_func argument to specify the probability density function.

For a single infinite parameter defined over a bounded interval domain the syntax becomes:

    expect(expr::JuMP.AbstractJuMPScalar,
           prefs::GeneralVariableRef;
           [num_supports::Int = DefaultNumSupports,
           pdf::Function = (supp) -> 1 / (ub - lb)])::GeneralVariableRef

The behavior with the default pdf is equivalent to evaluating the mean value theorem for integrals for expr with respect to pref using UniTrapezoid. Other density functions can be given via pdf. Errors if the interval domain is not bounded.

Note that num_supports should be 0 if a single dependent parameter is given. Also, note that it is preferred to call @expect when expr is not just a single variable reference.

Example

julia> @infinite_parameter(model, x ~ Normal(), num_supports = 2)
x

julia> @variable(model, f, Infinite(x))
f(x)

julia> meas = expect(f, x)
𝔼{x}[f(x)]

julia> expand(meas)
0.5 f(0.6791074260357777) + 0.5 f(0.8284134829000359)
source
InfiniteOpt.MeasureToolbox.@expectMacro
@expect(expr::JuMP.AbstractJuMPScalar,
        prefs::Union{GeneralVariableRef, AbstractArray{GeneralVariableRef};
        [num_supports::Int = DefaultNumSupports, 
        kwargs...]
        )::GeneralVariableRef

An efficient wrapper for expect. Please see its doc string more information.

source
InfiniteOpt.MeasureToolbox.𝔼Function
𝔼(expr::JuMP.AbstractJuMPScalar,
  prefs::Union{GeneralVariableRef, AbstractArray{GeneralVariableRef}};
  [num_supports::Int = DefaultNumSupports, 
  kwargs...]
  )::GeneralVariableRef)

A convenient wrapper for expect. The unicode symbol 𝔼 is produced by \bbE.

source
InfiniteOpt.MeasureToolbox.@𝔼Macro
@𝔼(expr::JuMP.AbstractJuMPScalar,
   prefs::Union{GeneralVariableRef, AbstractArray{GeneralVariableRef};
   [num_supports::Int = DefaultNumSupports],
   kwargs...)::GeneralVariableRef

A convenient wrapper for @expect. The unicode symbol 𝔼 is produced by \bbE.

source
InfiniteOpt.MeasureToolbox.generate_expect_dataFunction
generate_expect_data(domain::AbstractInfiniteDomain, 
                     prefs::Union{GeneralVariableRef, Vector{GeneralVariableRef}}, 
                     num_supports::Int; 
                     [kwargs...])::AbstractMeasureData

Generate a concrete instance of AbstractMeasureData in accordance with the domain and infinite parameter(s) prefs given for computing the expectation. This is intended as an internal method, but should be extended for user defined infinite domain types.

source

Support Sum

InfiniteOpt.MeasureToolbox.@support_sumMacro
@support_sum(expr::JuMP.AbstractJuMPScalar,
             prefs::Union{GeneralVariableRef, AbstractArray{GeneralVariableRef}};
             label = All
             )::GeneralVariableRef

An efficient wrapper for support_sum please see its doc string for more information.

source
InfiniteOpt.MeasureToolbox.support_sumFunction
support_sum(expr::JuMP.AbstractJuMPScalar,
            params::Union{GeneralVariableRef, AbstractArray{GeneralVariableRef}};
            label = All
            )::GeneralVariableRef

Creates a measure that represents the sum of the expression over a parameter(s) using all of its supports corresponding to label. Also, note that it is preferred to call @support_sum when expr is not just a single variable reference.

Example

julia> @infinite_parameter(model, x in [0, 1], supports = [0.3, 0.7])
x

julia> @variable(model, f, Infinite(x))
f(x)

julia> meas = support_sum(f, x)
support_sum{x}[f(x)]

julia> expand(meas)
f(0.3) + f(0.7)
source

Queries

JuMP.nameMethod
JuMP.name(mref::MeasureRef)::String

Extend JuMP.name to return the name associated with a measure reference.

source
InfiniteOpt.num_measuresFunction
num_measures(model::InfiniteModel)::Int

Return the number of measures defined in model.

Example

julia> num_measures(model)
2
source
InfiniteOpt.all_measuresFunction
all_measures(model::InfiniteModel)::Vector{GeneralVariableRef}

Return the list of all measures added to model.

Examples

julia> all_measures(model)
2-element Array{GeneralVariableRef,1}:
 ∫{t ∈ [0, 6]}[w(t, x)]
 𝔼{x}[w(t, x)]
source
InfiniteOpt.measure_functionFunction
measure_function(mref::MeasureRef)::JuMP.AbstractJuMPScalar

Return the function associated with mref.

Example

julia> measure_function(meas)
y(x, t) + 2
source
measure_function(mref::GeneralVariableRef)

Define measure_function for general variable references. Errors if mref does not correspond to a MeasureRef. See the underlying docstrings for more information.

source
InfiniteOpt.measure_dataFunction
measure_data(mref::MeasureRef)::AbstractMeasureData

Return the measure data associated with mref.

Example

julia> data = measure_data(meas);

julia> typeof(data)
FunctionalDiscreteMeasureData{Vector{GeneralVariableRef},Vector{Float64}}
source
measure_data(mref::GeneralVariableRef)

Define measure_data for general variable references. Errors if mref does not correspond to a MeasureRef. See the underlying docstrings for more information.

source
InfiniteOpt.is_analyticFunction
is_analytic(mref::MeasureRef)::Bool

Return if mref is evaluated analytically.

Example

julia> is_analytic(meas)
false
source
is_analytic(mref::GeneralVariableRef)

Define is_analytic for general variable references. Errors if mref does not correspond to a MeasureRef. See the underlying docstrings for more information.

source
InfiniteOpt.parameter_refsMethod
parameter_refs(mref::MeasureRef)::Tuple

Return the tuple of infinite parameters that the measured expression associated mref depends on once the measure has been evaluated. Note that this will correspond to the parameter dependencies of the measure function excluding those included in the measure data.

Example

julia> parameter_refs(meas)
(t,)
source
InfiniteOpt.is_usedMethod
is_used(mref::MeasureRef)::Bool

Return a Bool indicating if mref is used in the model.

Example

julia> is_used(mref)
true
source
InfiniteOpt.used_by_derivativeMethod
used_by_derivative(mref::MeasureRef)::Bool

Return a Bool indicating if mref is used by a derivative.

Example

julia> used_by_derivative(mref)
true
source
InfiniteOpt.used_by_constraintMethod
used_by_constraint(mref::MeasureRef)::Bool

Return a Bool indicating if mref is used by a constraint.

Example

julia> used_by_constraint(mref)
false
source
InfiniteOpt.used_by_measureMethod
used_by_measure(mref::MeasureRef)::Bool

Return a Bool indicating if mref is used by a measure.

Example

julia> used_by_measure(mref)
true
source
InfiniteOpt.used_by_objectiveMethod
used_by_objective(mref::MeasureRef)::Bool

Return a Bool indicating if mref is used by the objective.

Example

julia> used_by_objective(mref)
true
source
InfiniteOpt.core_objectMethod
core_object(mref::MeasureRef)::Measure

Retrieve the underlying core Measure object for vref. This is intended as an advanced method for developers.

source

Modification

JuMP.set_nameMethod
JuMP.set_name(mref::MeasureRef, name::String)::Nothing

Extend JuMP.set_name to specify the name of a measure reference.

source
JuMP.deleteMethod
JuMP.delete(model::InfiniteModel, mref::MeasureRef)::Nothing

Extend JuMP.delete to delete measures. Errors if measure is invalid, meaning it does not belong to the model or it has already been deleted.

Example

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

julia> delete(model, meas)

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

Expansion

InfiniteOpt.expandFunction
expand(mref::MeasureRef)::JuMP.AbstractJuMPScalar

Return a JuMP scalar function containing the explicit expansion of the measure mref. This expansion is done according to the measure data. Note that variables are added to the model as necessary to accomodate the expansion (i.e., point variables and semi-infinite variables are made as needed). Errors if expansion is undefined for the measure data and/or the measure expression. If desired this can be used in combination with measure to expand measures on the fly.

This is useful for extensions that employ a custom transformation backend since it can be used evaluate measures before expressions are translated to the new model. This method can also be extended to handle custom measure data types by extending expand_measure. Optionally, analytic_expansion can also be extended which is triggered by is_analytic for such types if analytic expansion is possible in certain cases.

Example

julia> tdata = DiscreteMeasureData(t, [0.5, 0.5], [0, 1])

julia> expr = expand(measure(g + z + T - h - 2, tdata))
0.5 g(0) + 0.5 g(1) + z + 0.5 T(0, x) + 0.5 T(1, x) - h(x) - 2
source
expand(mref::GeneralVariableRef)

Define expand for general variable references. Errors if mref does not correspond to a MeasureRef. See the underlying docstrings for more information.

source
InfiniteOpt.expand_all_measures!Function
expand_all_measures!(model::InfiniteModel)::Nothing

Expand all of the measures used in the objective and/or constraints of model. The objective and constraints are updated accordingly. Note that variables are added to the model as necessary to accomodate the expansion (i.e., point variables and semi-infinite variables are made as needed). Errors if expansion is undefined for the measure data and/or the measure expression.

This is useful for extensions that employ a custom transformation backend since it can be used evaluate measures before model is translated into the new model. This method can also be extended to handle custom measure data types by extending expand_measure. Note that this method leverages expand_measure via expand_measures. Optionally, analytic_expansion can also be extended which is triggered by is_analytic for such types if analytic expansion is possible in certain cases.

Example

julia> print(model)
Min integral{t ∈ [0, 6]}[g(t)*t] + z
Subject to
 T(t, x) ≥ 0.0, ∀ t ∈ [0, 6], xi ∈ [-1, 1]
 z ≥ 0.0
 g(t) + z ≥ 42.0, ∀ t ∈ [0, 6]
 integral{t ∈ [0, 6]}[T(t, x)] ≥ 0.0, ∀ x ∈ [-1, 1]

julia> expand_all_measures!(model)

julia> print(model)
Min 3 g(6) + z
Subject to
 T(t, x) ≥ 0.0, ∀ t ∈ [0, 6], xi ∈ [-1, 1]
 z ≥ 0.0
 g(t) + z ≥ 42.0, ∀ t ∈ [0, 6]
 0.5 T(0, x) + 0.5 T(6, xi) ≥ 0.0, ∀ x ∈ [-1, 1]
source
InfiniteOpt.expand_measureFunction
expand_measure(
    expr, 
    data::AbstractMeasureData,
    write_model::Union{InfiniteModel, AbstractTransformationBackend}
    )::JuMP.AbstractJuMPScalar

Return the finite reformulation of a measure containing a variable/parameter expression expr with measure data data. Here write_model is the target model where this expanded expression will be used. Thus, any variables that need to be created will be added to write_model. The methods make_point_variable_ref and make_semi_infinite_variable_ref should be used as appropriate to create these variables. Note this is intended as an internal function, but will need to be extended for unsupported expr types and for user-defined measure data types. Principally, this is leveraged to enable the user methods expand and expand_all_measures!.

source
InfiniteOpt.analytic_expansionFunction
analytic_expansion(
    expr, 
    data::AbstractMeasureData,
    write_model::Union{InfiniteModel, AbstractTransformationBackend}
    )::JuMP.AbstractJuMPScalar

Analytically, evaluate measure in the simple case where the measure expression expr doesn't depend on data and thus expr can be treated as a constant in conjunction with an analytic result of the data. This is intended as an internal method that is used by expand and expand_measures. For unrecognized data types, expand_measure is called instead. User defined measure data type may choose to extend this method if desired. This is triggered when is_analytic(mref) = true.

source
InfiniteOpt.expand_measuresFunction
expand_measures(
    expr, 
    write_model::Union{InfiniteModel, AbstractTransformationBackend}
    )

Expand all MeasureRefs in expr in-place via expand_measure and return the expanded expression. This is an internal method used by expand_all_measures! and TranscriptionOpt but can be useful for user-defined transformation backend extensions that add implement add_point_variable/add_semi_infinite_variable in combination with expand_measure. write_model is the model that the measure variables are added to as described in expand_measure.

source
InfiniteOpt.make_point_variable_refFunction
make_point_variable_ref(
    write_model::Union{InfiniteModel, AbstractTransformationBackend},
    ivref::GeneralVariableRef,
    support::Vector{Float64}
    )::GeneralVariableRef

Make a point variable for infinite variable/derivative ivref at support, add it to the write_model, and return the GeneralVariableRef. This is an internal method for point variables produced by expanding measures via expand_measure. This is also useful for those writing extension transformation backends and wish to expand measures without modifiying the InfiniteModel. In such cases, write_model should be the transformation backend and add_point_variable should be extended appropriately for point variables. Errors if write_model is an transformation backend and add_point_variable is not properly extended.

Note this is also accomodates infinite parameter functions, in which case the infinite parameter function is called with the support as input.

source
InfiniteOpt.make_semi_infinite_variable_refFunction
make_semi_infinite_variable_ref(
    write_model::Union{InfiniteModel, AbstractTransformationBackend},
    ivref::GeneralVariableRef,
    indices::Vector{Int},
    values::Vector{Float64}
    )::GeneralVariableRef

Make a semi-infinite variable for infinite variable/derivative/parameter function ivref at support, add it to the write_model, and return the GeneralVariableRef. This is an internal method for semi-infinite variables produced by expanding measures via expand_measure. This is also useful for those writing extension transformation backends and wish to expand measures without modifiying the InfiniteModel. In such cases, write_model should be the transformation backend and add_semi_infinite_variable should be extended appropriately for semi-infinite variables. Errors if write_model is an transformation backend and add_semi_infinite_variable is not properly extended. Note this is only intended for transformation backends that are currently stored in InfiniteModel.backend.

source
InfiniteOpt.add_point_variableMethod
add_point_variable(
    backend::AbstractTransformationBackend, 
    ivref::GeneralVariableRef, 
    support::Vector{Float64}
    )::GeneralVariableRef

Add a point variable (defined by restricting ivref to support) to the tranformation backend backend and return the correct InfiniteOpt variable reference. This is an internal method used by make_point_variable_ref to make point variables when the write_model is an transformation backend. This is useful for extensions that wish to expand measures, but without changing the original InfiniteModel. An error is thrown for unextended backend types.

source
InfiniteOpt.add_semi_infinite_variableMethod
add_semi_infinite_variable(
    backend::AbstractTransformationBackend, 
    var::SemiInfiniteVariable, 
    )::GeneralVariableRef

Add a semi-infinite variable var to the transformation backend backend and return the correct InfiniteOpt variable reference. This is an internal method used by make_semi_infinite_variable_ref to make semi-infinite variables when the write_model is a transformation backend. This is useful for extensions that wish to expand measures, but without changing the original InfiniteModel. An error is thrown for new transformation backend types. Note if this is extended, than internal_semi_infinite_variable should also be extended in order to direct semi-infinite variables references to the underlying SemiInfiniteVariable.

source
InfiniteOpt.internal_semi_infinite_variableFunction
internal_semi_infinite_variable(
    vref::SemiInfiniteVariableRef,
    backend::AbstractTransformationBackend
    )::SemiInfiniteVariable

Return the semi-infinite variable object of vref assuming it is an internal variable made during measure expansion within a transformation backend. This will apply to transformation backend extensions that utilize add_measure_variable in combination with expand_measure.

source