Public interface

StochasticProgram(first_stage_params::Any,
                  second_stage_params::Any,
                  scenarios::Vector{<:AbstractScenario},
                  instantiation::StochasticInstantiation,
                  optimizer_constructor = nothing)

Create a new two-stage stochastic program with a given collection of scenarios. Optionally, a capable optimizer_constructor can be supplied to later optimize the stochastic program. If multiple Julia processes are available, the resulting stochastic program will automatically be memory-distributed on these processes. This can be avoided by setting procs = [1].

StochasticProgram(first_stage_params::Any,
                  second_stage_params::Any,
                  instantiation::StochasticInstantiation,
                  optimizer_constructor=nothing) where T <: AbstractFloat

Create a new two-stage stochastic program with stage data given by first_stage_params and second_stage_params. After construction, scenarios of type Scenario can be added through add_scenario!. Optionally, a capable optimizer_constructor can be supplied to later optimize the stochastic program. If multiple Julia processes are available, the resulting stochastic program will automatically be memory-distributed on these processes. This can be avoided by setting procs = [1].

StochasticProgram(scenarios::Vector{<:AbstractScenario},
                  instantiation::StochasticInstantiation,
                  optimizer_constructor = nothing)

Create a new two-stage stochastic program with a given collection of scenarios and no stage data. Optionally, a capable optimizer_constructor can be supplied to later optimize the stochastic program. If multiple Julia processes are available, the resulting stochastic program will automatically be memory-distributed on these processes. This can be avoided by setting procs = [1].

StochasticProgram(first_stage_params::Any,
                  second_stage_params::Any,
                  ::Type{Scenario},
                  instantiation::StochasticInstantiation,
                  optimizer_constructor=nothing) where Scenario <: AbstractScenario

Create a new two-stage stochastic program with stage data given by first_stage_params and second_stage_params. After construction, scenarios of type S can be added through add_scenario!. Optionally, a capable optimizer_constructor can be supplied to later optimize the stochastic program. If multiple Julia processes are available, the resulting stochastic program will automatically be memory-distributed on these processes. This can be avoided by setting procs = [1].

StochasticProgram(::Type{Scenario},
                  instantiation::StochasticInstantiation,
                  optimizer_constructor=nothing) where Scenario <: AbstractScenario

Create a new two-stage stochastic program with scenarios of type Scenario and no stage data. Optionally, a capable optimizer_constructor can be supplied to later optimize the stochastic program.

AbstractStochasticStructure{N}

Abstract supertype for the underlying memory structure of a stochastic program. N is the number of stages.

Deterministic

Instantiates with the DeterministicEquivalent structure.

See also: DeterministicEquivalent

DistributedHorizontal

Instantiates with the HorizontalStructure on multiple cores.

See also: HorizontalStructure

DistributedVertical

Instantiates with the VerticalStructure on multiple cores.

See also: VerticalStructure

Horizontal

Instantiates with the HorizontalStructure on a single core.

See also: HorizontalStructure

StochasticInstantiation

Abstract supertype for the underlying memory structure of a stochastic program. N is the number of stages.

UnloadasbleStructure{Opt <: StochasticProgramOptimizerType, S <: AbstractStochasticStructure}

Error thrown when an optimizer of type Opt cannot load a structure of type S.

UnloadedStructure{Opt <: StochasticProgramOptimizerType}

Error thrown when an optimizer of type Opt has not yet loaded a stochastic structure and an operation which requires a structure to be loaded is called.

UnspecifiedInstantiation

Default instantiation value, which defers the choice to default_structure.

See also: default_structure

UnsupportedStructure{Opt <: StochasticProgramOptimizerType, S <: AbstractStochasticStructure}

Error indicating that an optimizer of type Opt does not support the stochastic structure S.

Vertical

Instantiates with the VerticalStructure on a single core.

See also: VerticalStructure

StochasticStructure(scenarios::NTuple{M, Vector{<:AbstractScenario}}, instantiation::StochasticInstantiation) where M

Constructs a stochastic structure over the M provided scenario sets according to the specified instantiation. Should be overrided for every defined stochastic structure.

StochasticStructure(scenario_types::ScenarioTypes{M}, instantiation::StochasticInstantiation) where M

Constructs a stochastic structure over the M provided scenario types according to the specified instantiation. Should be overrided for every defined stochastic structure.

default_structure(instantiation::StochasticInstantiation, optimizer)

Returns a StochasticInstantiation based on the provided instantiation and optimizer. If an explicit instantiation is provided it is always prioritized. Otherwise, if instantiation is UnspecifiedInstantiation, returns whatever structure requested by the optimizer. Defaults to Deterministic if no optimizer is provided.

DeterministicEquivalent

Deterministic equivalent memory structure. Stochastic program is stored as one large optimization problem. Supported by any standard AbstractOptimizer.

VerticalStructure

Vertical memory structure. Decomposes stochastic program by stages.

HorizontalStructure

Horizontal memory structure. Decomposes stochastic program by scenario.

DecisionVariable <: AbstractVariableRef

Holds a reference to the stochastic program and the corresponding MOI.VariableIndex.

fix(dvar::DecisionVariable, val::Number)

Fix the decision associated with dvar to val. In contexts where dvar is a variable, the variable is fixed to the value. In contexts where dvar is a known parameter value, the value is updated.

See also unfix.

unfix(dvar::DecisionVariable)

Unfix the decision associated with dvar. If the decision is already in a NotTaken state, this does nothing.

See also fix.

decision(dvar::DecisionVariable)

Return the internal Decision associated with dvar.

state(dvar::DecisionVariable)

Return the DecisionState of dvar.

DecisionRef <: AbstractVariableRef

Holds a reference to the model and the corresponding MOI.VariableIndex.

KnownRef <: AbstractVariableRef

Holds a reference to the model and the corresponding MOI.VariableIndex.

fix(dref::DecisionRef, val::Number)

Fix the decision associated with dref to val.

See also unfix.

fix(kref::KnownRef, val::Number)

Update the known decision value of kref to val.

all_decision_variables(model::JuMP.Model)

Returns a list of all decisions currently in the model. The decisions are ordered by creation time.

all_known_decision_variables(model::JuMP.Model)

Returns a list of all known decisions currently in the model. The decisions are ordered by creation time.

decision(dref::Union{DecisionRef, KnownRef})

Return the internal Decision associated with dref.

num_decisions(model::JuMP.Model)

Return the number of decisions in model.

num_decisions(model::JuMP.Model)

Return the number of known decisions in model.

state(dref::DecisionRef)

Return the DecisionState of dref.

AbstractScenario

Abstract supertype for scenario objects.

ExpectedScenario{S <: AbstractScenario}

Wrapper type around an AbstractScenario. Should for convenience be used as the result of a call to expected.

See also expected

Probability

A type-safe wrapper for Float64 used to represent probability of a scenario occuring.

Scenario

Conveniece type that adheres to the AbstractScenario abstraction. Useful when uncertain parameters are a finite set of scalar values.

expected(scenarios::Vector{<:AbstractScenario})

Return the expected scenario out of the collection scenarios in an ExpectedScenario wrapper.

This is defined through classical expectation: sum([probability(s)*s for s in scenarios]), and is always defined for scenarios created through @scenario, if the requested fields support it.

Otherwise, user-defined scenario types must implement this method for full functionality.

See also ExpectedScenario

probability(scenario::AbstractScenario)

Return the probability of scenario occuring.

Is always defined for scenarios created through @scenario. Other user defined scenario types must implement this method to generate a proper probability. The default behaviour is to assume that scenario has a probability field of type Probability

See also: Probability

probability(scenarios::Vector{<:AbstractScenario})

Return the probability of that any scenario in the collection scenarios occurs.

scenariotext(io::IO, scenario::AbstractScenario)

Custom printout called when printing scenario.

set_probability!(scenario::AbstractScenario, probability::AbstractFloat)

Set the probability of scenario occuring.

Is always defined for scenarios created through @scenario. Other user defined scenario types must implement this method.

AbstractSampler

Abstract supertype for sampler objects.

Sampler

General purpose sampler object that samples Scenario.

See also: Scenario, @sampler

sample(sampler::AbstractSampler{S})

Sample a scenario of type S using sampler.

sample(sampler::AbstractSampler{S}, π::AbstractSampler)

Sample a scenario of type S using sampler and set the probability of the sampled scenario to π.

@scenario(def)

Define a scenario type compatible with StochasticPrograms using the syntax

@scenario name = begin
    ...structdef...

    [@zero begin
        ...
        return zero(scenario)
    end]

    [@expectation begin
        ...
        return expected(scenarios)
     end]
end

The generated type is referenced through name and a default constructor is always generated. This constructor accepts the keyword probability to set the probability of the scenario occuring. Otherwise, any internal variables and specialized constructors are defined in the @scenario block as they would be in any Julia struct.

If possible, a zero method and an expected method will be generated for the defined type. Otherwise, or if the default implementation is not desired, these can be user provided through @zero and @expectation.

The defined scenario type will be available on all Julia processes.

Examples

The following defines a simple scenario $ξ$ with a single value.

@scenario ExampleScenario = begin
    ξ::Float64
end

ExampleScenario(1.0, probability = 0.5)

# output

ExampleScenario with probability 0.5
  ξ: 1.0

See also: @zero, @expectation, @sampler

@container_scenario([i=..., j=..., ...], expr, probability = 1.0)

Wraps JuMP's @container macro to create Scenario instances with DenseAxisArray or SparseAxisArray as underlying data. See @container for syntax.

@zero(def)

Define the additive zero scenario inside a @scenario block using the syntax:

@zero begin
    ...
    return zero_scenario
end

Examples

The following defines a zero scenario for the example scenario defined in @scenario

@zero begin
    return ExampleScenario(0.0)
end

See also @scenario

@expectation(def)

Define how to form the expected scenario inside a @scenario block. The scenario collection is accessed through the reserved keyword scenarios.

@zero begin
    ...
    return zero_scenario
end

Examples

The following defines expectation for the example scenario defined in @scenario

@expectation begin
    return ExampleScenario(sum([probability(s)*s.ξ for s in scenarios]))
end

See also @scenario

@sampler(def)

Define a sampler type for some scenariotype compatible with StochasticPrograms using the syntax

@sampler samplername = begin
    ...internals...

    @sample scenariotype begin
        ...
        return scenario
    end
end

Any internal state required by the sampler, as well as any specialized constructor, are defined in the @sampler block as they would be in any Julia struct. Define the sample operation inside the @sample block and specify the scenariotype that the sampler returns. The defined sampler will be available on all Julia processes.

Examples

The following defines a simple dummy sampler, with some internal weight value, for the scenario defined in @scenario, and samples one scenario.

@sampler ExampleSampler = begin
    w::Float64

    ExampleSampler(w::AbstractFloat) = new(w)

    @sample ExampleScenario begin
        @parameters w
        return ExampleScenario(w*randn(), probability = rand())
    end
end
s = ExampleSampler(2.0)
s()

# output

ExampleScenario with probability 0.29
  ξ: 1.48

See also: @sample, @scenario

@sample(def)

Define the sample operaton inside a @sampler block, using the syntax

@sample begin
    ...
    return sampled_scenario
end

The sampler object is referenced through the reserved keyword sampler, from which any internals can be accessed.

@stage(def)

Add a stage model generation recipe to stochasticprogram using the syntax

@stage stage stochasticprogram::StochasticProgram = begin
    @parameters param1 param2 ...
    @decision(model, var) ...
    @uncertain ξ
    ... JuMPdef ...
    ...
end

where JuMP syntax is used inside the block to define the stage model. During definition, the second stage model is referenced through the reserved keyword model.

Examples

The following defines the first stage model given by:

and the second-stage model given by:

where $q₁(ξ), q₂(ξ), d₁(ξ), d₂(ξ)$ depend on the scenario $ξ$ and $x₁, x₂$ are first stage variables. Two scenarios are added so that two second stage models are generated.

ξ₁ = Scenario(q₁ = 24.0, q₂ = 28.0, d₁ = 500.0, d₂ = 100.0, probability = 0.4)
ξ₂ = Scenario(q₁ = 28.0, q₂ = 32.0, d₁ = 300.0, d₂ = 300.0, probability = 0.6)

sp = StochasticProgram([ξ₁, ξ₂])

@stage 1 sp = begin
    @decision(model, x₁ >= 40)
    @decision(model, x₂ >= 20)
    @objective(model, Min, 100*x₁ + 150*x₂)
    @constraint(model, x₁ + x₂ <= 120)
end

@stage 2 sp = begin
    @uncertain q₁ q₂ d₁ d₂
    @variable(model, 0 <= y₁ <= d₁)
    @variable(model, 0 <= y₂ <= d₂)
    @objective(model, Max, q₁*y₁ + q₂*y₂)
    @constraint(model, 6*y₁ + 10*y₂ <= 60*x₁)
    @constraint(model, 8*y₁ + 5*y₂ <= 80*x₂)
end

# output

Stochastic program with:
 * 2 decision variables
 * 2 scenarios of type Scenario
Solver is default solver

See also: @parameters, @decision, @uncertain

@first_stage(def)

Add a first stage model generation recipe to stochasticprogram using the syntax

@first_stage stochasticprogram::StochasticProgram = begin
    ...
end [defer]

where JuMP syntax is used inside the block to define the first stage model. During definition, the first stage model is referenced through the reserved keyword model.

Examples

The following defines the first stage model given by:

@first_stage sp = begin
    @decision(model, x₁ >= 40)
    @decision(model, x₂ >= 20)
    @objective(model, Min, 100*x₁ + 150*x₂)
    @constraint(model, x₁ + x₂ <= 120)
end

See also: @second_stage

@second_stage(def)

Add a second stage model generation recipe to stochasticprogram using the syntax

@second_stage stochasticprogram::StochasticProgram = begin
    @known var1 var2 ...
    ...
end

where JuMP syntax is used inside the block to define the second stage model. During definition, the second stage model is referenced through the reserved keyword model.

Examples

The following defines the second stage model given by:

where $q₁(ξ), q₂(ξ), d₁(ξ), d₂(ξ)$ depend on the scenario $ξ$ and $x₁, x₂$ are first stage variables. Two scenarios are added so that two second stage models are generated.

@second_stage sp = begin
    @known x₁ x₂
    @uncertain q₁ q₂ d₁ d₂
    @variable(model, 0 <= y₁ <= d₁)
    @variable(model, 0 <= y₂ <= d₂)
    @objective(model, Min, q₁*y₁ + q₂*y₂)
    @constraint(model, 6*y₁ + 10*y₂ <= 60*x₁)
    @constraint(model, 8*y₁ + 5*y₂ <= 80*x₂)
end

See also: @first_stage

@decision(model, expr, args..., kw_args...)

Add a decision variable to model described by the expression expr. If used inside a @stage block, the created variable can be used in subsequent stage blocks. See @variable for syntax details.

Examples

@decision(model, x >= 40)

See also @parameters, @uncertain, @stage

@known(def)

Annotate each decision taken in the previous stage. Any @decision included in a @stochastic_model definition will implicitly add @known annotations to subsequent stages.

Examples

@known x₁, x₂

See also @decision, @parameters, @uncertain, @stage

@parameters(def)

Define the problem parameters in a @stage block

@parameters param1, param2, ...

possibly with default values. Any defined parameter without a default value must be supplied as a keyword argument to instantiate when creating models.

Examples

@parameters d

@parameters begin
    Crops = [:wheat, :corn, :beets]
    Cost = Dict(:wheat=>150, :corn=>230, :beets=>260)
    Budget = 500
end

See also @decision, @uncertain, @stage

@uncertain(def)

In a @stage block, annotate each uncertain variable using the syntax

@uncertain var1, var2, ...

or using JuMP's container syntax

@uncertain ξ[i=..., j=..., ...]

This assumes that the [Scenario] type is used. Alternatively, user-defined scenarios can be specified by annotating the type. Also, inside a @stochastic_model block, user-defined scenarios can be created during the @uncertain annotation, following @scenario.

Examples

@uncertain q₁ q₂ d₁ d₂

@scenario Simple = begin
    q₁::Float64
    q₂::Float64
    d₁::Float64
    d₂::Float64
end
@uncertain ξ::SimpleScenario

@stochastic_model begin
    ...
    @uncertain ξ::SimpleScenario = begin
        q₁::Float64
        q₂::Float64
        d₁::Float64
        d₂::Float64
    end
    ...
end

See also @scenario, @parameters, @decision, @stage

@stochastic_model(def)

Define a stochastic model capable of instantiating stochastic programs, using the syntax

sm = @stochastic_model begin
    ...
    @stage x begin
      ...
    end
    ...
end

where the inner blocks are @stage blocks. At least two stages must be specified in consecutive order. A stochastic model object can later be used to instantiate stochastic programs using a given set of scenarios or by using samplers.

Examples

The following defines a stochastic model consisitng of the first stage model given by:

and the second-stage model given by:

where $q₁(ξ), q₂(ξ), d₁(ξ), d₂(ξ)$ depend on the scenario $ξ$.

sm = @stochastic_model begin
    @stage 1 begin
        @decision(model, x₁ >= 40)
        @decision(model, x₂ >= 20)
        @objective(model, Min, 100*x₁ + 150*x₂)
        @constraint(model, x₁ + x₂ <= 120)
    end
    @stage 2 begin
        @decision x₁ x₂
        @uncertain q₁ q₂ d₁ d₂
        @variable(model, 0 <= y₁ <= d₁)
        @variable(model, 0 <= y₂ <= d₂)
        @objective(model, Min, q₁*y₁ + q₂*y₂)
        @constraint(model, 6*y₁ + 10*y₂ <= 60*x₁)
        @constraint(model, 8*y₁ + 5*y₂ <= 80*x₂)
    end
end

See also: @stage, @parameters, @decision, @uncertain

objective_value(stochasticmodel::StochasticModel; result::Int = 1)

Returns the value of the recourse problem after a call to optimize!(stochasticmodel).

objective_value(stochasticprogram::StochasticProgram; result::Int = 1)

Return the objective value associated with result index result of the most-recent solution after a call to optimize!(stochasticprogram).

optimize!(stochasticmodel::StochasticModel, sampler::AbstractSampler; crash::AbstractCrash = Crash.None(), kw...)

Approximately optimize the stochasticmodel when the underlying scenario distribution is inferred by sampler. If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

optimize!(stochasticprogram::StochasticProgram; crash::AbstractCrash = Crash.None(); kw...)

Optimize the stochasticprogram in expectation. If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown. An optional crash procedure can be set to warm-start.

Examples

The following solves the stochastic program sp using the L-shaped algorithm.

set_optimizer(sp, LShaped.Optimizer)
set_optimizer_attribute(sp, MasterOptimizer(), GLPK.Optimizer)
set_optimizer_attribute(sp, SubproblemOptimizer(), GLPK.Optimizer)
optimize!(sp);

# output

L-Shaped Gap  Time: 0:00:02 (6 iterations)
  Objective:       -855.8333333333358
  Gap:             0.0
  Number of cuts:  8
  Iterations:      6

The following solves the stochastic program sp using GLPK on the extended form.

using GLPK

set_optimizer(sp, GLPK.Optimizer)
optimize!(sp)

See also: VRP

set_optimizer(stochasticmodel::StochasticModel, optimizer)

Set the optimizer of the stochasticmodel.

set_optimizer(stochasticprogram::StochasticProgram, optimizer)

Set the optimizer of the stochasticprogram.

set_optimizer_attribute(stochasticprogram::StochasticProgram, attr::MOI.AbstractOptimizerAttribute, value)

Set the solver-specific attribute attr in stochasticprogram to value.

See also: get_optimizer_attribute

set_optimizer_attribute(stochasticprogram::StochasticProgram, name::Union{Symbol, String}, value)

Sets solver-specific attribute identified by name to value in the stochasticprogram.

See also: get_optimizer_attribute

set_optimizer_attributes(stochasticprogram::StochasticProgram, pairs::Pair...)

Given a list of attribute => value pairs or a collection of keyword arguments, calls set_optimizer_attribute(stochasticprogram, attribute, value) for each pair.

See also: get_optimizer_attribute

add_scenario!(scenariogenerator::Function, stochasticprogram::StochasticProgram, stage::Integer = 2)

Store the second stage scenario returned by scenariogenerator in the second stage of the stochasticprogram. Defaults to the second stage. If the stochasticprogram is distributed, the scenario will be defined on the node that currently has the fewest scenarios.

add_scenario!(stochasticprogram::StochasticProgram, scenario::AbstractScenario, stage::Integer = 2)

Store the second stage scenario in the stochasticprogram at stage. Defaults to the second stage.

If the stochasticprogram is distributed, the scenario will be defined on the node that currently has the fewest scenarios.

add_scenarios!(stochasticprogram::StochasticProgram, scenarios::Vector{<:AbstractScenario}, stage::Integer = 2)

Store the collection of second stage scenarios in the stochasticprogram at stage. Defaults to the second stage. If the stochasticprogram is distributed, scenarios will be distributed evenly across workers.

add_scenarios!(scenariogenerator::Function, stochasticprogram::StochasticProgram, n::Integer, stage::Integer = 2; defer::Bool = false)

Generate n second-stage scenarios using scenariogeneratorand store in the stochasticprogram at stage. Defaults to the second stage. If the stochasticprogram is distributed, scenarios will be distributed evenly across workers.

add_worker_scenario!(stochasticprogram::StochasticProgram, scenario::AbstractScenario, w::Integer, stage::Integer = 2)

Store the second stage scenario in worker node w of the stochasticprogram at stage. Defaults to the second stage.

add_worker_scenario!(scenariogenerator::Function, stochasticprogram::StochasticProgram, w::Integer, stage::Integer = 2)

Store the second stage scenario returned by scenariogenerator in worker node w of the stochasticprogram at stage. Defaults to the second stage.

add_worker_scenarios!(stochasticprogram::StochasticProgram, scenarios::Vector{<:AbstractScenario}, w::Integer, stage::Integer = 2; defer::Bool = false)

Store the collection of second stage scenarios in in worker node w of the stochasticprogram at stage. Defaults to the second stage.

add_worker_scenarios!(scenariogenerator::Function, stochasticprogram::StochasticProgram, n::Integer, w::Integer, stage::Integer = 2; defer::Bool = false)

Generate n second-stage scenarios using scenariogeneratorand store them in worker node w of the stochasticprogram at stage. Defaults to the second stage.

all_decision_variables(stochasticprogram::StochasticProgram{N}) where N

Returns a list of all decisions currently in the stochasticprogram. The decisions are ordered by creation time.

decision(stochasticprogram::StochasticProgram, index::MOI.VariableIndex)

Return the current value of the first-stage decision at index of stochasticprogram.

decision(stochasticprogram::StochasticProgram)

Return the current first-stage decision values of stochasticprogram.

deferred(stochasticprogram::StochasticProgram)

Return true if stochasticprogram is not fully generated.

distributed(stochasticprogram::StochasticProgram, s::Integer = 2)

Return true if the stochasticprogram is memory distributed at stage s. Defaults to the second stage.

expected(stochasticprogram::StochasticProgram, s::Integer = 2)

Return the exected scenario of all scenarios of the stochasticprogram at stage s. Defaults to the second stage.

first_stage(stochasticprogram::StochasticProgram)

Return the first stage of stochasticprogram.

first_stage_dims(stochasticprogram::StochasticProgram)

Return a the number of variables and the number of constraints in the the first stage of stochasticprogram as a tuple.

first_stage_num_constraints(stochasticprogram::StochasticProgram)

Return the number of constraints in the the first stage of stochasticprogram.

generator(stochasticprogram::StochasticProgram, key::Symbol)

Return the problem generator associated with key in stochasticprogram.

get_optimizer_attribute(stochasticprogram::StochasticProgram, attr::MOI.AbstractOptimizerAttribute)

Return the value of the solver-specific attribute attr in stochasticprogram.

See also: set_optimizer_attribute, set_optimizer_attributes.

get_optimizer_attribute(stochasticprogram::StochasticProgram, name::String)

Return the value associated with the solver-specific attribute named name in stochasticprogram.

See also: set_optimizer_attribute, set_optimizer_attributes.

has_generator(stochasticprogram::StochasticProgram, key::Symbol)

Return true if a problem generator with key exists in stochasticprogram.

instantiate(stochasticmodel::StochasticModel{2},
            scenarios::Vector{<:AbstractScenario};
            instantiation::StochasticInstantiation = UnspecifiedInstantiation(),
            optimizer = nothing;
            defer::Bool = false,
            kw...)

Instantiate a new two-stage stochastic program using the model definition stored in the two-stage stochasticmodel, and the given collection of scenarios. Optionally, supply an optimizer. If no explicit instantiation is provided, the structure is induced by the optimizer. The structure is Deterministic by default.

instantiate(stochasticmodel::StochasticModel,
            scenarios::Vector{<:AbstractScenario};
            instantiation::StochasticInstantiation = UnspecifiedInstantiation(),
            optimizer = nothing,
            defer::Bool = false,
            kw...)

Instantiate a new stochastic program using the model definition stored in stochasticmodel, and the given collection of scenarios. Optionally, supply an optimizer. If no explicit instantiation is provided, the structure is induced by the optimizer. The structure is Deterministic by default.

instantiate(stochasticmodel::StochasticModel{2};
            instantiation::StochasticInstantiation = UnspecifiedInstantiation(),
            optimizer = nothing,
            scenario_type::Type{S} = Scenario,
            defer::Bool = false,
            kw...) where S <: AbstractScenario

Instantiate a deferred two-stage stochastic program using the model definition stored in the two-stage stochasticmodel over the scenario type S. Optionally, supply an optimizer. If no explicit instantiation is provided, the structure is induced by the optimizer. The structure is Deterministic by default.

instantiate(stochasticmodel::StochasticModel,
            sampler::AbstractSampler,
            n::Integer;
            instantiation::StochasticInstantiation = UnspecifiedInstantiation(),
            optimizer = nothing,
            defer::Bool = false,
            kw...)

Generate a sampled instance of size n using the model stored in the two-stage stochasticmodel, and the provided sampler. Optionally, supply an optimizer. If no explicit instantiation is provided, the structure is induced by the optimizer. The structure is Deterministic by default.

master_optimizer(stochasticprogram::StochasticProgram)

Return a MOI optimizer using the currently provided optimizer of stochasticprogram.

num_decisions(stochasticprogram::TwoStageStochasticProgram)

Return the number of first-stage decision of stochasticprogram.

num_decisions(stochasticprogram::StochasticProgram, s::Integer = 2)

Return the number of decisions at stage s in the stochasticprogram.

num_scenarios(stochasticprogram::StochasticProgram, s::Integer = 2)

Return the number of scenarios in the stochasticprogram at stage s. Defaults to the second stage.

num_stages(stochasticprogram::StochasticProgram)

Return the number of stages in stochasticprogram.

num_subproblems(stochasticprogram::StochasticProgram, s::Integer = 2)

Return the number of subproblems in the stochasticprogram at stage s. Defaults to the second stage.

optimal_decision(stochasticmodel::StochasticModel)

Return the optimal first stage decision of stochasticmodel, after a call to optimize!(stochasticmodel).

optimal_decision(stochasticprogram::StochasticProgram)

Return the optimal first stage decision of stochasticprogram, after a call to optimize!(stochasticprogram).

optimizer(stochasticmodel::StochasticModel)

Return the optimizer attached to stochasticmodel.

optimizer(stochasticprogram::StochasticProgram)

Return the optimizer attached to stochasticprogram.

optimizer_constructor(stochasticmodel::StochasticModel)

Return any optimizer constructor supplied to the stochasticmodel.

optimizer_constructor(stochasticprogram::StochasticProgram)

Return any optimizer constructor supplied to the stochasticprogram.

optimizer_name(stochasticmodel::StochasticModel)

Return the currently provided optimizer type of stochasticmodel.

optimizer_name(stochasticprogram::StochasticProgram)

Return the currently provided optimizer type of stochasticprogram.

probability(stochasticprogram::StochasticProgram, i::Integer, s::Integer = 2)

Return the probability of scenario ith scenario in the stochasticprogram at stage s occuring. Defaults to the second stage.

sample!(stochasticprogram::StochasticProgram, sampler::AbstractSampler, n::Integer, stage::Integer = 2)

Sample n scenarios using sampler and add to the stochasticprogram at stage. Defaults to the second stage. If the stochasticprogram is distributed, scenarios will be distributed evenly across workers.

scenario(stochasticprogram::StochasticProgram, i::Integer, s::Integer = 2)

Return the ith scenario of stochasticprogramat stages`. Defaults to the second stage.

scenario_type(stochasticprogram::StochasticProgram, s::Integer = 2)

Return the type of the scenario structure associated with stochasticprogram at stage s. Defaults to the second stage.

scenario_types(stochasticprogram::StochasticProgram, s::Integer = 2)

Return the scenario types of each stage of stochasticprogram.

scenarios(stochasticprogram::StochasticProgram, s::Integer = 2)

Return an array of all scenarios of the stochasticprogram at stage s. Defaults to the second stage.

stage_parameters(stochasticprogram::StochasticProgram, s::Integer)

Return the parameters at stage s in stochasticprogram.

stage_probability(stochasticprogram::StochasticProgram, s::Integer = 2)

Return the probability of any scenario in the stochasticprogram at stage s occuring. A well defined model should return 1. Defaults to the second stage.

structure(stochasticprogram::StochasticProgram)

Return the underlying structure of the stochasticprogram.

structure_name(stochasticprogram::StochasticProgram)

Return the name of the underlying structure of the stochasticprogram.

subproblem(stochasticprogram::StochasticProgram, i::Integer, s::Integer = 2)

Return the ith subproblem of the stochasticprogram at stage s. Defaults to the second stage.

subproblem_optimizer(stochasticprogram::StochasticProgram)

Return a MOI optimizer for solving subproblems using the currently provided optimizer of stochasticprogram.

subproblems(stochasticprogram::StochasticProgram, s::Integer = 2)

Return an array of all subproblems of the stochasticprogram at stage s. Defaults to the second stage.

clear!(stochasticprogram::StochasticProgram)

Clear the stochasticprogram, removing all model definitions.

generate!(stochasticprogram::StochasticProgram)

Generate the stochasticprogram using the model definitions from @stage and available data.

outcome_model(stochasticprogram::TwoStageStochasticProgram,
              decision::AbstractVector,
              scenario::AbstractScenario;
              optimizer = nothing)

Return the resulting second stage model if decision is the first-stage decision in the provided scenario, in stochasticprogram. The supplied decision must match the defined decision variables in stochasticprogram. Optionally, supply a capable optimizer to the outcome model.

outcome_model(stochasticprogram::StochasticProgram{N},
              decisions::NTuple{N-1,AbstractVector}
              scenario_path::NTuple{N-1,AbstractScenario},
              optimizer = nothing)

Return the resulting N:th stage model if decisions are the decisions taken in the previous stages and scenario_path are the realized scenarios up to stage N in stochasticprogram. Optionally, supply a capable solver to the outcome model.

stage_model(stochasticprogram::StochasticProgram, stage::Integer, scenario::AbstractScenario; optimizer = nothing)

Return a generated stage model corresponding to scenario, in stochasticprogram. Optionally, supply a capable optimizer to the stage model.

stage_one_model(stochasticprogram::StochasticProgram; optimizer = nothing)

Return a generated copy of the first stage model in stochasticprogram. Optionally, supply a capable optimizer to the stage model.

confidence_interval(stochasticmodel::StochasticModel{2}, sampler::AbstractSampler)

Generate a confidence interval around the true optimum of the two-stage stochasticmodel at level confidence using SAA, over the scenario distribution induced by sampler.

The attribute NumSamples is the size of the sampled models used to generate the interval and generally governs how tight it is. The attribute NumLowerTrials is the number of sampled models used in the lower bound calculation and the attribute NumUpperTrials is the number of sampled models used in the upper bound calculation. The attribute NumEvalSamples is the size of the sampled models used in the upper bound calculation. The confidence level can be set through the Confidence attribute.

If a sample-based optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

evaluate_decision(stochasticmodel::StochasticModel{2}, decision::AbstractVector, sampler::AbstractSampler; kw...)

Return a statistical estimate of the objective of the two-stage stochasticmodel at decision in the form of a confidence interval at the current confidence level, over the scenario distribution induced by sampler.

In other words, evaluate decision on a sampled model and generate an confidence interval using the sample variance of the evaluation. The confidence level can be set through the Confidence attribute and the sample size can be set through the NumEvalSamples attribute.

The supplied decision must match the defined decision variables in stochasticmodel. If a sample-based optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: confidence_interval

evaluate_decision(stochasticprogram::TwoStageStochasticProgram, decision::AbstractVector, scenario::AbstractScenario)

Evaluate the result of taking the first-stage decision if scenario is the actual outcome in stochasticprogram. The supplied decision must match the defined decision variables in stochasticprogram. If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

evaluate_decision(stochasticprogram::TwoStageStochasticProgram, decision::AbstractVector)

Evaluate the first-stage decision in stochasticprogram.

In other words, evaluate the first-stage objective at decision and solve outcome models of decision for every available scenario. The supplied decision must match the defined decision variables in stochasticprogram. If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

gap(stochasticmodel::StochasticModel{2}, decision::UnionAbstractVector, sampler::AbstractSampler)

Generate a confidence interval around the gap between the result of using decision and the true optimum of the two-stage stochasticmodel at the current confidence level, over the scenario distribution induced by sampler.

The attribute NumSamples is the size of the sampled models used to generate the interval and generally governs how tight it is. The attribute NumLowerTrials is the number of sampled models used in the lower bound calculation and the attribute NumUpperTrials is the number of sampled models used in the upper bound calculation. The attribute NumEvalSamples is the size of the sampled models used in the upper bound calculation. The confidence level can be set through the Confidence attribute.

The supplied decision must match the defined decision variables in stochasticmodel. If a sample-based optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

lower_bound(stochasticmodel::StochasticModel{2}, sampler::AbstractSampler; kw...)

Generate a confidence interval around a lower bound on the true optimum of the two-stage stochasticmodel at the current confidence level, over the scenario distribution induced by sampler.

The attribute NumSamples is the size of the sampled models used to generate the interval and generally governs how tight it is. The attribute NumLowerTrials is the number of sampled models. The confidence level can be set through the Confidence attribute.

If a sample-based optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

statistically_evaluate_decision(stochasticprogram::TwoStageStochasticProgram, decision::AbstractVector)

Statistically evaluate the first-stage decision in stochasticprogram, returning the evaluated value and the spread over the scenarios.

The supplied decision must match the defined decision variables in stochasticprogram. If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

upper_bound(stochasticmodel::StochasticModel{2}, decision::AbstractVector, sampler::AbstractSampler; kw...)

Generate a confidence interval around an upper bound of the expected value of decision in the two-stage stochasticmodel at the current confidence level, over the scenario distribution induced by sampler.

The attribute NumUpperTrials is the number of sampled models and the attribute NumEvalSamples is the size of the evaluation models. The confidence level can be set through the Confidence attribute.

The supplied decision must match the defined decision variables in stochasticmodel. If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

upper_bound(stochasticmodel::StochasticModel{2}, sampler::AbstractSampler; kw...)

Generate a confidence interval around an upper bound of the true optimum of the two-stage stochasticmodel at the current confidence level, over the scenario distribution induced by sampler, by generating and evaluating a candidate decision.

The attribute NumSamples is the size of the sampled model used to generate a candidate decision. The attribute NumUpperTrials is the number of sampled models and the attribute NumEvalSamples is the size of the evaluation models. The confidence level can be set through the Confidence attribute.

If a sample-based optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

DEP(stochasticprogram::TwoStageStochasticProgram; optimizer = nothing)

Generate the deterministically equivalent problem (DEP) of the two-stage stochasticprogram, unless a cached version already exists.

In other words, generate the extended form the stochasticprogram as a single JuMP model. Optionally, a capable optimizer can be supplied to DEP.

See also: VRP, WS

EEV(stochasticmodel::StochasticModel{2}, sampler::AbstractSampler)

Approximately calculate the expected value of the expected value decision (EEV) of the two-stage stochasticmodel to the current confidence level, over the scenario distribution induced by sampler.

The attribute NumEEVSamples is the size of the sampled models used in the eev calculation. The confidence level can be set through the Confidence attribute.

If a sample-based optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: EVP, EV

EEV(stochasticprogram::TwoStageStochasticProgram)

Calculate the expected value of the expected value solution (EEV) of the two-stage stochasticprogram.

In other words, evaluate the EVP decision. If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: EVP, EV

EV(stochasticprogram::TwoStageStochasticProgram)

Calculate the optimal value of the EVP of the two-stage stochasticprogram.

If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: EVP, expected_value_decision, EEV

EVP(stochasticprogram::TwoStageStochasticProgram; optimizer = nothing)

Generate the expected value problem (EVP) of the two-stage stochasticprogram.

In other words, generate a wait-and-see model corresponding to the expected scenario over all available scenarios in stochasticprogram. Optionally, a capable optimizer can be supplied to WS.

See also: expected_value_decision, EEV, EV, WS

EVPI(stochasticmodel::StochasticModel{2}, sampler::AbstractSampler)

Approximately calculate the expected value of perfect information (EVPI) of the two-stage stochasticmodel to the current confidence level, over the scenario distribution induced by sampler.

In other words, calculate confidence intervals around VRP and EWS. If they do not overlap, the EVPI is statistically significant, and a confidence interval is calculated and returned.

The attribute NumSamples is the size of the sampled models used to generate the interval and generally governs how tight it is. The attribute NumLowerTrials is the number of sampled models used in the lower bound calculation and the attribute NumUpperTrials is the number of sampled models used in the upper bound calculation. The attribute NumEvalSamples is the size of the sampled models used in the upper bound calculation. The confidence level can be set through the Confidence attribute.

If a sample-based optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: VRP, EWS, VSS

EVPI(stochasticprogram::TwoStageStochasticProgram)

Calculate the expected value of perfect information (EVPI) of the two-stage stochasticprogram.

In other words, calculate the gap between VRP and EWS. If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: VRP, EWS, VSS

EWS(stochasticmodel::StochasticModel{2}, sampler::AbstractSampler)

Approximately calculate the expected wait-and-see result (EWS) of the two-stage stochasticmodel to the current confidence level, over the scenario distribution induced by sampler.

The attribute NumEWSSamples is the size of the sampled models used to generate the interval and generally governs how tight it is. The confidence level can be set through the Confidence attribute.

If a sample-based optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: VRP, WS

EWS(stochasticprogram::StochasticProgram)

Calculate the expected wait-and-see result (EWS) of the stochasticprogram.

In other words, calculate the expectated result of all possible wait-and-see models, using the provided scenarios in stochasticprogram.

If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: VRP, WS

VRP(stochasticmodel::StochasticModel{2}, sampler::AbstractSampler; confidence = 0.95)

Return a confidence interval around the value of the recouse problem (VRP) of stochasticmodel to the given confidence level.

If a sample-based optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: EVPI, VSS, EWS

VRP(stochasticprogram::StochasticProgram)

Calculate the value of the recouse problem (VRP) in stochasticprogram.

In other words, optimize the stochastic program and return the optimal value.

If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: EVPI, EWS

VSS(stochasticmodel::StochasticModel{2}, sampler::AbstractSampler)

Approximately calculate the value of the stochastic solution (VSS) of the two-stage stochasticmodel to the current confidence level, over the scenario distribution induced by sampler.

In other words, calculate confidence intervals around EEV and VRP. If they do not overlap, the VSS is statistically significant, and a confidence interval is calculated and returned. Ñ is the number of samples in the out-of-sample evaluation of EEV.

The attribute NumSamples is the size of the sampled models used to generate the interval and generally governs how tight it is. The same size is used to generate the expected value decision. The attribute NumLowerTrials is the number of sampled models used in the lower bound calculation and the attribute NumUpperTrials is the number of sampled models used in the upper bound calculation. The attribute NumEvalSamples is the size of the sampled models used in the upper bound calculation and the attribute [NumEEVSamples] is the size of the sampled models used in the EEV calculation. The confidence level can be set through the Confidence attribute.

If a sample-based optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: VRP, EEV, EVPI

VSS(stochasticprogram::TwoStageStochasticProgram)

Calculate the value of the stochastic solution (VSS) of the two-stage stochasticprogram.

In other words, calculate the gap between EEV and VRP. If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

WS(stochasticprogram::TwoStageStochasticProgram, scenario::AbstractScenarioaData; optimizer = nothing)

Generate a wait-and-see (WS) model of the two-stage stochasticprogram, corresponding to scenario.

In other words, generate the first stage and the second stage of the stochasticprogram as if scenario is known to occur. Optionally, a capable optimizer can be supplied to WS.

See also: DEP, EVP

expected_value_decision(stochasticprogram::TwoStageStochasticProgram)

Calculate the optimizer of the EVP of the two-stage stochasticprogram.

If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: EVP, EV, EEV

wait_and_see_decision(stochasticprogram::TwoStageStochasticProgram, scenario::AbstractScenario, optimizer_constructor = nothing)

Calculate the optimizer of the wait-and-see (WS) model of the two-stage stochasticprogram, corresponding to scenario.

If an optimizer has not been set yet (see set_optimizer), a NoOptimizer error is thrown.

See also: WS