Public interface

StochasticProgram{SD <: AbstractScenario}

A mathematical model of a stochastic optimization problem. Every instance is linked to some given scenario type AbstractScenario. A StochasticProgram can be memory-distributed on multiple Julia processes.

StochasticProgram(scenarios::Vector{<:AbstractScenario};
                  solver = JuMP.UnsetSolver(),
                  procs = workers()) where {SD <: AbstractScenario}

Create a new stochastic program with a sampler and no stage data.

StochasticProgram(first_stage_data::Any,
                  second_stage_data::Any,
                  sampler::AbstractSampler;
                  solver = JuMP.UnsetSolver(),
                  procs = workers()) where {SD <: AbstractScenario}

Create a new stochastic program with a sampler that implicitly defines the scenario type.

StochasticProgram(first_stage_data::Any,
                  second_stage_data::Any,
                  scenarios::Vector{<:AbstractScenario};
                  solver = JuMP.UnsetSolver(),
                  procs = workers()) where {SD <: AbstractScenario}

Create a new stochastic program with a given collection of scenarios

StochasticProgram(scenarios::Vector{<:AbstractScenario};
                  solver = JuMP.UnsetSolver(),
                  procs = workers()) where {SD <: AbstractScenario}

Create a new stochastic program with a given collection of scenarios and no stage data.

StochasticProgram(first_stage_data::Any,
                  second_stage_data::Any,
                  ::Type{SD};
                  solver = JuMP.UnsetSolver(),
                  procs = workers()) where {SD <: AbstractScenario}

Create a new stochastic program with stage data given by first_stage_data and second_stage_data. After construction, scenarios of type SD can be added through add_scenario!. Optionally, a capable solver 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].

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.

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.

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.

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]Scenario 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 Example = begin
    ξ::Float64
end

ExampleScenario(1.0, probability = 0.5)

# output

ExampleScenario with probability 0.5

See also: @zero, @expectation, @sampler

@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 for some scenario type compatible with StochasticPrograms using the syntax

@sampler [samplername] scenario = begin
    ...internals...

    @sample 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. Optionally, give a samplername to the sampler. Otherwise, it will be named [scenario]Sampler. 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 Example = begin
    w::Float64

    Example(w::AbstractFloat) = new(w)

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

# output

ExampleScenario(Probability(0.29), 1.48)

See also: @sample, @scenario

@sample(def)

Define the sample operation 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.

@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.

Optionally, give the keyword defer after the to delay generation of the first stage model.

Examples

The following defines the first stage model given by:

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

# output

Stochastic program with:
 * 0 scenarios of type SimpleScenario
 * 2 decision variables
 * undefined second stage
Solver is default solver

See also: @second_stage

@second_stage(def)

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

@second_stage stochasticprogram::StochasticProgram = begin
    @decision var1 var2 ...
    ...
end [defer]

where JuMP syntax is used inside the block to define the second stage model. Annotate each first stage decision that appears in the second stage model with @decision. During definition, the second stage model is referenced through the reserved keyword model and the scenario specific data is referenced through the reserved keyword scenario.

Optionally, give the keyword defer after the to delay generation of the first stage 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
    @decision x₁ x₂
    ξ = scenario
    @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

# output

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

See also: @first_stage

@decision(def)

Annotate each first stage variable that appears in a @second_stage block, using the syntax

@decision var1, var2, ...

Examples

@decision x₁, x₂

See also @second_stage

add_scenario!(scenariogenerator::Function, stochasticprogram::StochasticProgram; defer::Bool = false, w = rand(workers()))

Store the second stage scenario returned by scenariogenerator in the second stage of stochasticprogram.

If defer is true, then model creation is deferred until generate!(stochasticprogram) is called. If the stochasticprogram is distributed, the worker that the scenario should be loaded on can be set through w.

add_scenario!(stochasticprogram::StochasticProgram, scenario::AbstractScenario; defer::Bool = false, w = rand(workers()))

Store the second stage scenario in the second stage of stochasticprogram.

If defer is true, then model creation is deferred until generate!(stochasticprogram) is called. If the stochasticprogram is distributed, the worker that the scenario should be loaded on can be set through w.

add_scenarios!(stochasticprogram::StochasticProgram, scenarios::Vector{<:AbstractScenario}; defer::Bool = false, w = rand(workers()))

Store the colllection of second stage scenarios in the second stage of stochasticprogram.

If defer is true, then model creation is deferred until generate!(stochasticprogram) is called. If the stochasticprogram is distributed, the worker that the scenario should be loaded on can be set through w.

decision_length(stochasticprogram::StochasticProgram)

Return the length of the first stage decision in stochasticprogram.

deferred(stochasticprogram::StochasticProgram)

Return true if stochasticprogram is not fully generated.

distributed(stochasticprogram::StochasticProgram)

Return true if stochasticprogram is memory distributed. p

expected(stochasticprogram::StochasticProgram)

Return the exected scenario of all scenarios in stochasticprogram.

first_stage_data(stochasticprogram::StochasticProgram)

Return the first stage data structure, if any exists, in 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_nconstraints(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.

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

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

internal_model(stochasticprogram::StochasticProgram)

Return the internal model of the solver object in stochasticprogram, after a call to optimize!(stochasticprogram).

masterterms(stochasticprogram::StochasticProgram, i::Integer)

Return the first stage terms appearing in scenario i in stochasticprogram.

The master terms are given in sparse format as an array of tuples (row,col,coeff) which specify the occurance of master problem variables in the second stage constraints.

nscenarios(stochasticprogram::StochasticProgram)

Return the number of scenarios in stochasticprogram.

nstages(stochasticprogram::StochasticProgram)

Return the number of stages in stochasticprogram. Will return 2 for two-stage problems.

nsubproblems(stochasticprogram::StochasticProgram)

Return the number of subproblems in stochasticprogram.

optimal_decision(stochasticprogram::StochasticProgram, var::Symbol)

Return the optimal second stage variable var of stochasticprogram in the ith scenario, after a call to optimize!(stochasticprogram).

optimal_decision(stochasticprogram::StochasticProgram, i::Integer)

Return the optimal second stage decision of stochasticprogram in the ith scenario, after a call to optimize!(stochasticprogram).

optimal_decision(stochasticprogram::StochasticProgram, var::Symbol)

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

optimal_decision(stochasticprogram::StochasticProgram)

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

optimal_value(stochasticprogram::StochasticProgram, i::Integer)

Return the optimal value of the ith subproblem in stochasticprogram, after a call to optimize!(stochasticprogram).

optimal_value(stochasticprogram::StochasticProgram)

Return the optimal value of stochasticprogram, after a call to optimize!(stochasticprogram).

optimize!(sp::StochasticProgram; solver::SPSolverType = JuMP.UnsetSolver())

Optimize sp after calls to @first_stage sp = begin ... end and second_stage sp = begin ... end, assuming scenarios are available.

generate!(sp) is called internally, so deferred models can be passed. Optionally, supply an AbstractMathProgSolver or an AbstractStructuredSolver as solver. Otherwise, any previously set solver will be used.

Examples

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

using LShapedSolvers
using GLPKMathProgInterface

optimize!(sp, solver = LShapedSolver(:ls, GLPKSolverLP()));

# output

L-Shaped Gap  Time: 0:00:01 (4 iterations)
  Objective:       -855.8333333333339
  Gap:             0.0
  Number of cuts:  7
:Optimal

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

using GLPKMathProgInterface

optimize!(sp, solver = GLPKSolverLP())

:Optimal

See also: VRP

probability(stochasticprogram::StochasticProgram)

Return the probability of scenario ith scenario in stochasticprogram occuring.

probability(stochasticprogram::StochasticProgram)

Return the probability of any scenario in stochasticprogram occuring. A well defined model should return 1.

recourse_length(stochasticprogram::StochasticProgram)

Return the length of the second stage decision in stochasticprogram.

sample!(stochasticprogram::StochasticProgram, n::Integer; defer::Bool = false)

Sample n scenarios from the sampler object in stochasticprogram, if any, and generates subproblems for each of them.

If defer is true, then model creation is deferred until generate!(stochasticprogram) is called.

sampler(stochasticprogram::StochasticProgram)

Return the sampler object, if any, in stochasticprogram.

scenario(stochasticprogram::StochasticProgram, i::Integer)

Return the ith scenario in stochasticprogram.

scenarioproblems(stochasticprogram::StochasticProgram)

Return the scenario problems in stochasticprogram.

scenarios(stochasticprogram::StochasticProgram)

Return an array of all scenarios in stochasticprogram.

scenariotype(stochasticprogram::StochasticProgram)

Return the type of the scenario structure associated with stochasticprogram.

second_stage_data(stochasticprogram::StochasticProgram)

Return the second stage data structure, if any exists, in stochasticprogram.

set_first_stage_data!(stochasticprogram::StochasticProgram, data::Any)

Store the first stage data in the first stage of stochasticprogram.

set_second_stage_data!(stochasticprogram::StochasticProgram, data::Any)

Store the second stage data in the second stage of stochasticprogram.

set_spsolver(stochasticprogram::StochasticProgram, spsolver::Union{MathProgBase.AbstractMathProgSolver,AbstractStructuredSolver})

Store the stochastic program solver spsolver in stochasticprogram.

spsolver(stochasticprogram::StochasticProgram)

Return the stochastic program solver spsolver in stochasticprogram.

subproblem(stochasticprogram::StochasticProgram, i::Integer)

Return the ith subproblem in stochasticprogram.

subproblems(stochasticprogram::StochasticProgram)

Return an array of all subproblems in stochasticprogram.

generate!(stochasticprogram::StochasticProgram)

Generate the stochasticprogram after giving model definitions with @firststage and @secondstage.

Generate the first stage model once, and generate second stage models for each supplied scenario that has not been considered yet.

outcome_model(stochasticprogram::StochasticProgram,
              scenario::AbstractScenario,
              x::AbstractVector;
              solver::MathProgBase.AbstractMathProgSolver = JuMP.UnsetSolver())

Return the resulting second stage model if x is the first stage decision in scenario ì, in stochasticprogram. Optionally, supply a capable solver to the outcome model.

stage_two_model(stochasticprogram::StochasticProgram)

Return a generated second stage model corresponding to scenario, in stochasticprogram.

evaluate_decision(stochasticprogram::StochasticProgram,
                  x::AbstractVector;
                  solver = JuMP.UnsetSolver())

Evaluate the first stage decision x in stochasticprogram.

In other words, evaluate the first stage objective at x and solve outcome models of x for every available scenario. Optionally, supply a capable solver to solve the outcome models. Otherwise, any previously set solver will be used.

evaluate_decision(stochasticprogram::StochasticProgram,
                  scenario::AbstractScenario,
                  x::AbstractVector;
                  solver = JuMP.UnsetSolver())

Evaluate the result of taking the first stage decision x if scenario is the actual outcome in stochasticprogram.

stage_one_model(stochasticprogram::StochasticProgram)

Return a generated copy of the first stage model in stochasticprogram.

DEP(stochasticprogram::StochasticProgram; solver = JuMP.UnsetSolver())

Generate the deterministically equivalent problem (DEP) of the stochasticprogram.

In other words, generate the extended form the stochasticprogram as a single JuMP model. Optionally, a capable solver can be supplied to DEP. Otherwise, any previously set solver will be used.

See also: VRP, WS

EEV(stochasticprogram::StochasticProgram; solver = JuMP.UnsetSolver())

Calculate the expected value of using the expected value solution (EEV) in stochasticprogram.

In other words, evaluate the EVP decision. Optionally, supply a capable solver to solve the intermediate problems. The default behaviour is to rely on any previously set solver.

See also: EVP, EV

EV(stochasticprogram::StochasticProgram; solver = JuMP.UnsetSolver())

Calculate the optimal value of the EVP in stochasticprogram.

Optionally, supply a capable solver to solve the expected value problem. The default behaviour is to rely on any previously set solver.

See also: EVP, EVP_decision, EEV

EVP(stochasticprogram::StochasticProgram; solver = JuMP.UnsetSolver())

Generate the expected value problem (EVP) in stochasticprogram.

In other words, generate a wait-and-see model corresponding to the expected scenario over all available scenarios in stochasticprogram. Optionally, supply a capable solver to EVP. Otherwise, any previously set solver will be used.

See also: EVP_decision, EEV, EV, WS

EVPI(stochasticprogram::StochasticProgram; solver = JuMP.UnsetSolver())

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

In other words, calculate the gap between VRP and EWS. Optionally, supply a capable solver to solve the intermediate problems. Otherwise, any previously set solver will be used.

See also: VRP, EWS, VSS

EVP_decision(stochasticprogram::StochasticProgram; solver = JuMP.UnsetSolver())

Calculate the optimizer of the EVP in stochasticprogram.

Optionally, supply a capable solver to solve the expected value problem. The default behaviour is to rely on any previously set solver.

See also: EVP, EV, EEV

EWS(stochasticprogram::StochasticProgram; solver = JuMP.UnsetSolver())

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. Optionally, a capable solver can be supplied to solve the intermediate problems. Otherwise, any previously set solver will be used.

See also: VRP, WS

SSA(stochasticprogram::StochasticProgram, n::Integer; solver = JuMP.UnsetSolver())

Generate a sample average approximation (SSA) of size n for the stochasticprogram.

In other words, sample n scenarios, if a sampler exists, and solve the resulting stochastic program. Optionally, a capable solver can be supplied to SSA. Otherwise, any previously set solver will be used.

See also: sample!

SSA(stochasticprogram::StochasticProgram, sampler::AbstractSampler, n::Integer; solver = JuMP.UnsetSolver())

Generate a sample average approximation (SSA) of size n for the stochasticprogram using the sampler.

In other words, sample n scenarios, of type consistent with stochasticprogram, and solve the resulting stochastic program. Optionally, a capable solver can be supplied to SSA. Otherwise, any previously set solver will be used.

See also: sample!

VRP(stochasticprogram::StochasticProgram; solver = JuMP.UnsetSolver())

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

In other words, optimize the stochastic program and return the optimal value. Optionally, supply a capable solver to optimize the stochastic program. Otherwise, any previously set solver will be used.

See also: EVPI, EWS

VSS(stochasticprogram::StochasticProgram; solver = JuMP.UnsetSolver())

Calculate the value of the stochastic solution (VSS) of the stochasticprogram.

In other words, calculate the gap between EEV and VRP. Optionally, supply a capable solver to solve the intermediate problems. The default behaviour is to rely on any previously set solver.

WS(stochasticprogram::StochasticProgram, scenario::AbstractScenarioaDta; solver = JuMP.UnsetSolver())

Generate a wait-and-see (WS) model of the 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 solver can be supplied to WS. Otherwise, any previously set solver will be used.

See also: DEP, EVP