API Reference

abstract type AbstractBenchmark

Abstract root type for all benchmark problems.

abstract type AbstractDynamicBenchmark{exogenous} <: AbstractBenchmark

Abstract type interface for multi-stage stochastic (dynamic) benchmark problems. The {exogenous} parameter has the same meaning (whether uncertainty is independent of decisions) as in AbstractStochasticBenchmark.

Primary entry point

• generate_environments(bench, n; rng): mandatory (or implement generate_environment(bench, rng)). The count-based default calls generate_environment once per environment.

Additional optional methods

• generate_environment(bench, rng): initialize a single rollout environment. Must return an AbstractEnvironment (see environment.jl for the full protocol: reset!, observe, step!, is_terminated). Implement this instead of overriding generate_environments when environments can be drawn independently.
• generate_baseline_policies(bench): returns named baseline callables of signature (env) -> Vector{DataSample} (full trajectory rollout).
• generate_anticipative_solver(bench): returns a callable (env; reset_env=true, kwargs...) -> Vector{DataSample} that runs the anticipative solver over a full episode. reset_env=true resets the environment before solving. reset_env=false starts from the current state.
• generate_dataset(bench, environments; target_policy, ...): generates training-ready DataSamples by calling target_policy(env) for each environment. Requires target_policy as a mandatory keyword argument.

Optional visualization methods (require Plots to be loaded)

• plot_trajectory(bench, traj): plot a full episode as a grid of subplots.
• animate_trajectory(bench, traj): animate a full episode.

abstract type AbstractEnvironment

Abstract type for environments in decision-focused learning benchmarks.

abstract type AbstractStaticBenchmark <: AbstractBenchmark

Abstract type interface for static benchmark problems.

Mandatory methods to implement for any static benchmark:

Choose one of three primary implementation strategies:

• Implement generate_instance (returns a DataSample with y=nothing). The default generate_sample forwards the call directly; generate_dataset applies target_policy afterwards if provided.
• Override generate_sample directly when the sample requires custom logic that cannot be expressed via generate_instance. Applies to static benchmarks only, stochastic benchmarks should implement the finer-grained hooks instead (generate_instance, generate_context, generate_scenario). generate_dataset applies target_policy to the result after the call returns.
• Override generate_dataset directly when samples cannot be drawn independently.

Also implement:

• generate_statistical_model
• generate_maximizer

Optional methods (defaults provided)

• is_minimization_problem: defaults to true
• compute_gap: default implementation provided; override for custom evaluation
• has_visualization: defaults to false

Mandatory methods (no default)

• objective_value(bench, sample, y): must be implemented by every static benchmark

Optional methods (no default, require Plots to be loaded)

• plot_instance, plot_solution
• generate_baseline_policies

abstract type AbstractStochasticBenchmark{exogenous} <: AbstractBenchmark

Abstract type interface for single-stage stochastic benchmark problems.

A stochastic benchmark separates the problem into an instance (the context known before the scenario is revealed) and a random scenario (the uncertain part). Decisions are taken by seeing only the instance. Scenarios are used to generate anticipative targets and compute objective values.

Required methods (ExogenousStochasticBenchmark only)

• generate_instance(bench, rng): returns a DataSample with the problem instance (solver kwargs) and, if not overriding generate_context, the ML features x. Scenarios are added later by generate_dataset via generate_scenario. When generate_context is overridden, x may be absent here and constructed there instead.
• generate_scenario(bench, rng; kwargs...): draws a random scenario. Solver kwargs are spread from ctx.context.

Optional methods

• generate_context(bench, rng, instance_sample): enriches the instance with observable context (default: identity). Override for contextual stochastic benchmarks.
• generate_anticipative_solver(bench): returns a callable (scenario; kwargs...) -> y that computes the anticipative solution per scenario.
• generate_parametric_anticipative_solver(bench): returns a callable (θ, scenario; kwargs...) -> y for the parametric anticipative subproblem argmin_{y ∈ Y} c(y, scenario) + θᵀy.

Dataset generation (exogenous only)

generate_dataset is specialised for ExogenousStochasticBenchmark and supports all three standard structures via nb_scenarios and contexts_per_instance:

By default (no target_policy), each DataSample has context holding the solver kwargs and extra=(; scenario) holding one scenario.

Provide a target_policy(ctx_sample, scenarios) -> Vector{DataSample} to compute labels. This covers both anticipative (K samples, one per scenario) and SAA (1 sample from all K scenarios) labeling strategies.

struct DataSample{K<:NamedTuple, E<:NamedTuple, F<:Union{Nothing, AbstractArray}, S<:Union{Nothing, AbstractArray}, C<:Union{Nothing, AbstractArray}}

Data sample data structure. Its main purpose is to store datasets generated by the benchmarks. It has 3 main (optional) fields: features x, cost parameters θ, and solution y. Currently, all three are restricted to AbstractArray or nothing. Additionally, it has a context field (solver and scenario-generation context, spread into the maximizer as maximizer(θ; sample.context...)) and an extra field (non-solver data, never passed to the maximizer).

The separation prevents silent breakage from accidentally passing non-solver data (e.g. a scenario, reward, or step counter) as unexpected kwargs to the maximizer.

Fields

• x::Union{Nothing, AbstractArray}: input features (optional)

• θ::Union{Nothing, AbstractArray}: intermediate cost parameters (optional)

• y::Union{Nothing, AbstractArray}: output solution (optional)

• context::NamedTuple: solver and scenario-generation context, e.g. instance, graph, contextual information

• extra::NamedTuple: additional data, never passed to the maximizer, e.g. scenario, objective value, reward, step count, etc. Can be used for any purpose by the user, such as plotting utilities.

DataSample(
;
    x,
    θ,
    y,
    extra,
    kwargs...
) -> DataSample{@NamedTuple{}, @NamedTuple{}, Nothing, Nothing, Nothing}

Constructor for DataSample with keyword arguments.

All keyword arguments beyond x, θ, y, and extra are collected into the context field (solver and scenario-generation context). The extra keyword accepts a NamedTuple of non-solver data.

Fields in context and extra must be disjoint. Neither may use a reserved struct field name (x, θ, y, context, extra). An error is thrown in both cases. Both can be accessed directly via property forwarding.

Examples

# Instance goes in context
d = DataSample(x=[1,2,3], θ=[4,5,6], y=[7,8,9], instance="my_instance")
d.instance  # "my_instance" (from context)

# Scenario goes in extra
d = DataSample(x=x, y=y, instance=inst, extra=(; scenario=ξ))
d.scenario  # ξ (from extra)

# State goes in context, reward in extra
d = DataSample(x=x, y=y, instance=state, extra=(; reward=-1.5))
d.instance  # state (from context)
d.reward    # -1.5 (from extra)

Alias for AbstractDynamicBenchmark{false}. Uncertainty depends on decisions.

Alias for AbstractStochasticBenchmark{false}. Uncertainty depends on decisions.

Alias for AbstractDynamicBenchmark{true}. Uncertainty is independent of decisions.

Alias for AbstractStochasticBenchmark{true}. Uncertainty is independent of decisions.

struct Policy{P}

Policy type for decision-focused learning benchmarks.

Run the policy and get the next decision on the given environment/instance.

struct SampleAverageApproximation{B<:ExogenousStochasticBenchmark} <: DecisionFocusedLearningBenchmarks.Utils.AbstractStaticBenchmark

Transforms an ExogenousStochasticBenchmark into a static benchmark via Sample Average Approximation (SAA).

For each (instance, context) pair, draws nb_scenarios fixed scenarios. These are stored in the sample and used for feature computation, target labeling (via target_policy), and gap evaluation.

Fields

• benchmark::ExogenousStochasticBenchmark: inner stochastic benchmark

• nb_scenarios::Int64: number of scenarios to draw per (instance, context) pair

struct TopKMaximizer

Top k maximizer.

TopKMaximizer(
    k
) -> DecisionFocusedLearningBenchmarks.Utils.TopKMaximizer

Return the top k indices of θ.

animate_trajectory(bench::AbstractDynamicBenchmark, trajectory::Vector{<:DataSample}; kwargs...)

Animate a full dynamic episode. Returns a Plots.Animation object (save with gif(result, filename)). Only available when Plots is loaded.

average_tensor(x)

Average the tensor x along its third axis.

compute_gap(
    bench::AbstractBenchmark,
    dataset::AbstractVector{<:DataSample{<:Any, <:Any, <:Any, <:AbstractArray}},
    statistical_model,
    maximizer
) -> Any
compute_gap(
    bench::AbstractBenchmark,
    dataset::AbstractVector{<:DataSample{<:Any, <:Any, <:Any, <:AbstractArray}},
    statistical_model,
    maximizer,
    op
) -> Any

Default implementation of compute_gap: average relative optimality gap over dataset. Requires labeled samples (y ≠ nothing), x, and context fields. Override for custom evaluation logic.

compute_gap(
    bench::AbstractDynamicBenchmark,
    args...;
    kwargs...
)

Intercepts accidental calls to the default compute_gap on dynamic benchmarks and throws a descriptive error. Dynamic benchmarks do not have a generic single-sample gap computation; override compute_gap directly on the concrete type if needed.

evaluate_policy!(
    policy,
    envs::Vector{<:AbstractEnvironment};
    ...
) -> Tuple{Vector{Float64}, Any}
evaluate_policy!(
    policy,
    envs::Vector{<:AbstractEnvironment},
    episodes::Int64;
    kwargs...
) -> Tuple{Vector{Float64}, Any}

Run the policy on the environments and return the total rewards and a dataset of observations. By default, the environments are reset before running the policy.

evaluate_policy!(
    policy,
    env::AbstractEnvironment,
    episodes::Int64;
    seed,
    kwargs...
) -> Tuple{Vector{Float64}, Vector}

Evaluate the policy on the environment and return the total reward and a dataset of observations. By default, the environment is reset before running the policy.

evaluate_policy!(
    policy,
    env::AbstractEnvironment;
    reset_env,
    seed,
    kwargs...
) -> Tuple{Any, Union{Vector{DataSample}, Array{DataSample{K, E, F, S, C}, 1} where {K<:NamedTuple, E<:NamedTuple, F<:Union{Nothing, AbstractArray}, S<:Union{Nothing, AbstractArray}, C<:Union{Nothing, AbstractArray}}}}

Run the policy on the environment and return the total reward and a dataset of observations. By default, the environment is reset before running the policy.

generate_anticipative_solver(::AbstractBenchmark) -> callable

Return a callable that computes the anticipative (oracle) solution. The calling convention differs by benchmark category:

Stochastic benchmarks (AbstractStochasticBenchmark): Returns (scenario; context...) -> y. Called once per scenario to obtain the optimal label.

Dynamic benchmarks (AbstractDynamicBenchmark): Returns (env; reset_env=true, kwargs...) -> Vector{DataSample}, a full trajectory. reset_env=true resets the environment before solving (used for initial dataset building); reset_env=false starts from the current environment state (used inside DAgger rollouts).

generate_baseline_policies(::AbstractBenchmark) -> NamedTuple or Tuple

Return named baseline policies for the benchmark. Each policy is a callable. The calling convention matches the target_policy signature for the benchmark category:

• Static: (sample) -> DataSample
• Stochastic: (ctx_sample, scenarios) -> Vector{DataSample}
• Dynamic: (env) -> Vector{DataSample} (full trajectory rollout)

generate_context(bench::AbstractStochasticBenchmark, rng, instance_sample::DataSample)
    -> DataSample

Enrich instance_sample with observable context drawn from rng. Returns a new DataSample extending the instance: .x is the final ML feature vector (possibly augmented with context features). Any latent fields needed by generate_scenario must go into .context (they are spread as kwargs via ctx.context...), not into .extra.

Default: returns instance_sample unchanged — no context augmentation. Non-contextual benchmarks (e.g. SVS) use this default.

Override to add per-sample context features:

function generate_context(bench::MyBench, rng, instance_sample::DataSample)
    x_raw = randn(rng, Float32, bench.d)
    return DataSample(;
        x=vcat(instance_sample.x, x_raw),
        instance_sample.context...,
        x_raw,
    )
end

Fields in .context are spread into generate_scenario as kwargs.

generate_dataset(::AbstractStaticBenchmark, dataset_size::Int; target_policy=nothing, kwargs...) -> Vector{<:DataSample}

Generate a Vector of DataSample of length dataset_size for given benchmark. Content of the dataset can be visualized using plot_solution, when it applies.

By default, it uses generate_sample to create each sample in the dataset, and passes any keyword arguments to it. target_policy is applied if provided, it is called on each sample after generate_sample returns.

generate_dataset(
    bench::ExogenousDynamicBenchmark,
    environments::AbstractVector;
    target_policy,
    kwargs...
)

Generate a training dataset from pre-built environments for an exogenous dynamic benchmark.

For each environment, calls target_policy(env) to obtain a training trajectory (Vector{DataSample}). The trajectories are concatenated into a flat dataset.

target_policy is a required keyword argument. Use generate_baseline_policies to obtain standard baseline callables (e.g. the anticipative solver).

Keyword arguments

• target_policy: required callable (env) -> Vector{DataSample}.

generate_dataset(
    bench::ExogenousDynamicBenchmark,
    n::Int64;
    target_policy,
    seed,
    kwargs...
)

Convenience wrapper for exogenous dynamic benchmarks: generates n environments via generate_environments, then calls generate_dataset(bench, environments; target_policy, ...).

target_policy is a required keyword argument.

generate_dataset(
    bench::ExogenousStochasticBenchmark,
    nb_instances::Int64;
    target_policy,
    nb_scenarios,
    contexts_per_instance,
    seed,
    rng,
    kwargs...
) -> Any

Specialised generate_dataset for exogenous stochastic benchmarks.

Generates nb_instances problem instances, each with contexts_per_instance context draws and nb_scenarios scenario draws per context. The scenario→sample mapping is controlled by the target_policy:

• Without target_policy (default): M contexts × K scenarios produce M×K unlabeled samples per instance.
• With target_policy(ctx_sample, scenarios) -> Vector{DataSample}: enables anticipative labeling (K labeled samples) or SAA (1 sample aggregating all K scenarios).

Keyword arguments

• nb_scenarios::Int = 1: scenarios per context (K).
• contexts_per_instance::Int = 1: context draws per instance (M).
• target_policy: when provided, called as target_policy(ctx_sample, scenarios) to compute labels. Defaults to nothing (unlabeled samples).
• seed: passed to MersenneTwister when rng is not provided.
• rng: random number generator; overrides seed when provided.
• kwargs...: forwarded to generate_sample.

generate_dataset(
    saa::SampleAverageApproximation,
    nb_instances::Int64;
    target_policy,
    seed,
    rng,
    kwargs...
) -> Any

Specialised generate_dataset for SampleAverageApproximation.

• Without target_policy: returns one static DataSample per instance, with nb_scenarios stored in extra.scenarios.
• With target_policy(ctx_sample, scenarios) -> Vector{DataSample}: labels each instance using all stored scenarios (same signature as ExogenousStochasticBenchmark policies).

generate_environment(::AbstractDynamicBenchmark, rng::AbstractRNG; kwargs...) -> AbstractEnvironment

Initialize a single environment for the given dynamic benchmark. Primary implementation target for the count-based generate_environments default. Override generate_environments directly when environments cannot be drawn independently (e.g. loading from files).

generate_environments(
    bench::AbstractDynamicBenchmark,
    n::Int64;
    seed,
    rng,
    kwargs...
) -> Vector{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance{Float64}}, Random.MersenneTwister, Int64}}

Generate n environments for the given dynamic benchmark. Primary entry point for dynamic training algorithms. Override when environments cannot be drawn independently (e.g. loading from files).

generate_instance(::AbstractBenchmark, rng::AbstractRNG; kwargs...) -> DataSample

Generate a single unlabeled DataSample (with y=nothing) for the benchmark.

generate_maximizer(::AbstractBenchmark; kwargs...)

Returns a callable f(θ; kwargs...) -> y, solving a maximization problem.

generate_parametric_anticipative_solver(::ExogenousStochasticBenchmark) -> callable

Optional. Return a callable (θ, scenario; kwargs...) -> y that solves the parametric anticipative subproblem:

argmin_{y ∈ Y(instance)}  c(y, scenario) + θᵀy

generate_sample(::AbstractStaticBenchmark, rng::AbstractRNG; kwargs...) -> DataSample

Generate a single DataSample for the benchmark.

Default (when generate_instance is implemented): Calls generate_instance and returns the result directly.

Override this method when sample generation requires custom logic. Labeling via target_policy is always applied by generate_dataset after this call returns.

generate_sample(
    bench::ExogenousStochasticBenchmark,
    rng;
    target_policy,
    nb_scenarios,
    contexts_per_instance,
    kwargs...
) -> Any

Default generate_sample for exogenous stochastic benchmarks.

Calls generate_instance, then generate_context (default: identity), draws scenarios via generate_scenario, then:

• Without target_policy: returns M×K unlabeled samples (contexts_per_instance contexts × nb_scenarios scenarios each), each with one scenario in extra=(; scenario=ξ).
• With target_policy: calls target_policy(ctx_sample, scenarios) per context and returns the result.

target_policy(ctx_sample, scenarios) -> Vector{DataSample} enables anticipative labeling (K samples, one per scenario) or SAA (1 sample aggregating all K scenarios).

generate_scenario(::ExogenousStochasticBenchmark, rng::AbstractRNG; kwargs...) -> scenario

Draw a random scenario. Solver kwargs are passed as keyword arguments spread from sample.context:

ξ = generate_scenario(bench, rng; ctx.context...)

generate_statistical_model(::AbstractBenchmark, seed=nothing; kwargs...)

Returns an untrained statistical model (usually a Flux neural network) that maps a feature matrix x to an output array θ. The seed parameter controls initialization randomness for reproducibility.

get_path(
    parents::AbstractVector{<:Integer},
    s::Integer,
    d::Integer
) -> Vector{T} where T<:Integer

Retrieve a path from the parents array and start sand endd`` of path.

get_seed(_::AbstractEnvironment) -> Any

Seed accessor for environments. By default, environments have no seed. Override this method to provide a seed for the environment.

grid_graph(
    costs::AbstractArray{R, 2};
    acyclic
) -> SimpleWeightedGraphs.SimpleWeightedDiGraph{Int64}

Convert a grid of cell costs into a weighted directed graph from SimpleWeightedGraphs.jl, where the vertices correspond to the cells and the edges are weighted by the cost of the arrival cell.

• If acyclic = false, a cell has edges to each one of its 8 neighbors.
• If acyclic = true, a cell has edges to its south, east and southeast neighbors only (ensures an acyclic graph where topological sort will work)

This can be used to model the Warcraft shortest paths problem of

Differentiation of Blackbox Combinatorial Solvers, Vlastelica et al. (2019)

has_visualization(::AbstractBenchmark) -> Bool

Return true if plot_instance and plot_solution are implemented for this benchmark (requires Plots to be loaded). Default is false.

highs_model() -> JuMP.Model

Initialize a HiGHS model (with disabled logging).

is_minimization_problem(_::AbstractBenchmark) -> Bool

Check if the benchmark is a minimization problem.

Defaults to true. Maximization benchmarks must override this method, forgetting to do so will cause compute_gap to compute the gap with the wrong sign without any error or warning.

is_terminated(env::AbstractEnvironment) --> Bool

Check if the environment has reached a terminal state.

neg_tensor(x)

Compute minus softplus element-wise on tensor x.

objective_value(::ExogenousStochasticBenchmark, sample::DataSample, y, scenario) -> Real

Compute the objective value of solution y for a given scenario. Must be implemented by each concrete ExogenousStochasticBenchmark.

This is the primary evaluation hook for stochastic benchmarks. The 2-arg fallback objective_value(bench, sample, y) dispatches here using the scenario stored in sample.extra.scenario (or averages over sample.extra.scenarios).

objective_value(
    saa::SampleAverageApproximation,
    sample::DataSample,
    y::AbstractArray
) -> Any

Evaluate a decision y against stored scenarios (average over scenarios).

objective_value(
    bench::AbstractBenchmark,
    sample::DataSample{CTX, EX, F, S<:AbstractArray, C}
) -> Any

Compute the objective value of the target in the sample (needs to exist).

objective_value(
    saa::SampleAverageApproximation,
    sample::DataSample{CTX, EX, F, S<:AbstractArray, C}
) -> Any

Evaluate the target solution in the sample against stored scenarios.

observe(env::AbstractEnvironment) --> Tuple

Get the current observation from the environment. This function should return a tuple of two elements: 1. An array of features representing the current state of the environment. 2. An internal state of the environment, which can be used for further processing (return nothing if not needed).

one_hot_argmax(
    z::AbstractArray{R<:Real, 1};
    kwargs...
) -> Any

Return a one-hot encoding of the index of the maximum value in θ.

path_to_matrix(
    path::Vector{<:Integer},
    h::Integer,
    w::Integer
) -> Matrix{Int64}

Transform path into a binary matrix of size (h, w) where each cell is 1 if the cell is part of the path, 0 otherwise.

plot_instance(bench::AbstractBenchmark, sample::DataSample; kwargs...)

Plot the problem instance (no solution). Only available when Plots is loaded.

plot_solution(bench::AbstractBenchmark, sample::DataSample; kwargs...)

Plot the instance with sample.y overlaid. Only available when Plots is loaded.

plot_trajectory(bench::AbstractDynamicBenchmark, trajectory::Vector{<:DataSample}; kwargs...)

Plot a full dynamic episode as a grid of state/decision subplots. Only available when Plots is loaded.

reset!(env::AbstractEnvironment; reset_rng::Bool, seed=get_seed(env)) --> Nothing

Reset the environment to its initial state. If reset_rng is true, the random number generator is reset to the given seed.

scip_model() -> JuMP.Model

Initialize a SCIP model (with disabled logging).

squeeze_last_dims(x)

Squeeze two last dimensions on tensor x.

step!(env::AbstractEnvironment, action) --> Float64

Perform a step in the environment with the given action. Returns the reward received after taking the action. This function may also update the internal state of the environment. If the environment is terminated, it should raise an error.

getproperty(d::DataSample, name::Symbol) -> Any

Extended property access for DataSample.

Allows accessing context and extra fields directly as properties. context is searched first; if the key is not found there, extra is searched.

propertynames(
    d::DataSample
) -> Tuple{Symbol, Symbol, Symbol, Symbol, Symbol, Vararg{Symbol}}
propertynames(
    d::DataSample,
    private::Bool
) -> Tuple{Symbol, Symbol, Symbol, Symbol, Symbol, Vararg{Symbol}}

Return all property names of a DataSample, including both struct fields and forwarded fields from context and extra.

This enables tab completion for all available properties.

show(io::IO, d::DataSample)

Display a DataSample with truncated array representations for readability.

Large arrays are automatically truncated with ellipsis (...), similar to standard Julia array printing.

coord_to_index(
    i::Integer,
    j::Integer,
    h::Integer,
    w::Integer
) -> Any

Given a pair of row-column coordinates (i, j) on a grid of size (h, w), compute the corresponding vertex index in the graph generated by grid_graph.

count_edges(h::Integer, w::Integer; acyclic)

Compute the number of edges in a grid graph of size (h, w).

index_to_coord(
    v::Integer,
    h::Integer,
    w::Integer
) -> Tuple{Any, Any}

Given a vertex index in the graph generated by grid_graph, compute the corresponding row-column coordinates (i, j) on a grid of size (h, w).

fit(
    transform_type,
    dataset::AbstractVector{<:DataSample};
    kwargs...
) -> Any

Fit the given transform type (ZScoreTransform or UnitRangeTransform) on the dataset.

reconstruct!(t, dataset::AbstractVector{<:DataSample})

Reconstruct the features in the dataset, in place.

reconstruct(t, dataset::AbstractVector{<:DataSample}) -> Any

Reconstruct the features in the dataset.

transform!(t, dataset::AbstractVector{<:DataSample})

Transform the features in the dataset, in place.

transform(t, dataset::AbstractVector{<:DataSample}) -> Any

Transform the features in the dataset.

struct Argmax2DBenchmark{E, R} <: DecisionFocusedLearningBenchmarks.Utils.AbstractStaticBenchmark

Argmax becnhmark on a 2d polytope.

Fields

• nb_features::Int64: number of features

• encoder::Any: true mapping between features and costs

• polytope_vertex_range::Any:

Argmax2DBenchmark(
;
    nb_features,
    seed,
    polytope_vertex_range
) -> Union{Argmax2DBenchmark{Flux.Dense{typeof(identity), Matrix{Float32}, Vector{Float32}}, Vector{Int64}}, Argmax2DBenchmark{Flux.Dense{typeof(identity), Matrix{Float32}, Bool}, Vector{Int64}}}

Custom constructor for Argmax2DBenchmark.

generate_maximizer(
    _::Argmax2DBenchmark
) -> typeof(DecisionFocusedLearningBenchmarks.Argmax2D.maximizer)

Maximizer for the Argmax2DBenchmark.

generate_sample(
    bench::Argmax2DBenchmark,
    rng::Random.AbstractRNG
) -> DataSample{K, @NamedTuple{}, Vector{Float32}} where K<:NamedTuple

Generate a sample for the Argmax2DBenchmark.

generate_statistical_model(
    bench::Argmax2DBenchmark;
    seed,
    rng
) -> Union{Flux.Dense{typeof(identity), Matrix{Float32}, Vector{Float32}}, Flux.Dense{typeof(identity), Matrix{Float32}, Bool}}

Generate a statistical model for the Argmax2DBenchmark.

struct ArgmaxBenchmark{E} <: DecisionFocusedLearningBenchmarks.Utils.AbstractStaticBenchmark

Basic benchmark problem with an argmax as the CO algorithm.

Fields

• instance_dim::Int64: instances dimension, total number of classes

• nb_features::Int64: number of features

• encoder::Any: true mapping between features and costs

ArgmaxBenchmark(
;
    instance_dim,
    nb_features,
    seed
) -> Union{ArgmaxBenchmark{Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Vector{Float32}}, typeof(vec)}}}, ArgmaxBenchmark{Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Bool}, typeof(vec)}}}}

Custom constructor for ArgmaxBenchmark.

one_hot_argmax(
    z::AbstractArray{R<:Real, 1};
    kwargs...
) -> Any

One-hot encoding of the argmax function.

generate_maximizer(
    _::ArgmaxBenchmark
) -> typeof(DecisionFocusedLearningBenchmarks.Argmax.one_hot_argmax)

Return an argmax maximizer.

generate_sample(
    bench::ArgmaxBenchmark,
    rng::Random.AbstractRNG;
    noise_std
) -> DataSample{K, @NamedTuple{}, Matrix{Float32}} where K<:NamedTuple

Generate a data sample for the argmax benchmark. This function generates a random feature matrix, computes the costs using the encoder, and adds noise to the costs before computing a target solution.

generate_statistical_model(
    bench::ArgmaxBenchmark;
    seed
) -> Union{Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Vector{Float32}}, typeof(vec)}}, Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Bool}, typeof(vec)}}}

Initialize a linear model for bench using Flux.

struct ContextualStochasticArgmaxBenchmark{M<:(AbstractMatrix)} <: ExogenousStochasticBenchmark

Minimal contextual stochastic argmax benchmark.

Per instance: c_base ~ U[0,1]^n (base utility, stored in context of the instance sample). Per context draw: x_raw ~ N(0, I_d) (observable context). Features: x = [c_base; x_raw]. Per scenario: ξ = c_base + W * x_raw + noise, noise ~ N(0, noise_std² I). The learner sees x and must predict θ̂ so that argmax(θ̂) ≈ argmax(ξ).

A linear model Dense(n+d → n; bias=false) can exactly recover [I | W].

Fields

• n::Int64: number of items (argmax dimension)

• d::Int64: number of context features

• W::AbstractMatrix: fixed perturbation matrix W ∈ R^{n×d}, unknown to the learner

• noise_std::Float32: noise std for scenario draws

struct AnticipativeSolver

A policy that acts with perfect information about the future scenario.

Evaluate the anticipative policy with a parametric prediction θ and a scenario. Returns the optimal action for the combined signal one_hot_argmax(scenario + θ).

Evaluate the anticipative policy for a given scenario. Returns the optimal action one_hot_argmax(scenario).

csa_saa_policy(
    ctx_sample,
    scenarios
) -> Vector{T} where T<:DataSample

SAA baseline policy: returns argmax(mean(scenarios)). For a linear argmax problem this is the exact SAA-optimal decision. Returns a single labeled DataSample with extra=(; scenarios).

generate_anticipative_solver(
    _::ContextualStochasticArgmaxBenchmark
) -> DecisionFocusedLearningBenchmarks.ContextualStochasticArgmax.AnticipativeSolver

Generates the anticipative solver for the benchmark.

generate_baseline_policies(
    _::ContextualStochasticArgmaxBenchmark
) -> @NamedTuple{saa::Policy{typeof(DecisionFocusedLearningBenchmarks.ContextualStochasticArgmax.csa_saa_policy)}}

Return the named baseline policies for ContextualStochasticArgmaxBenchmark. Each policy has signature (ctx_sample, scenarios) -> Vector{DataSample}.

generate_context(::ContextualStochasticArgmaxBenchmark, rng, instance_sample)

Draw x_raw ~ N(0, I_d) and return a context sample with:

• x = [c_base; x_raw]: full feature vector seen by the ML model.
• c_base, x_raw in context: spread into generate_scenario.

generate_instance(::ContextualStochasticArgmaxBenchmark, rng)

Draw c_base ~ U[0,1]^n and store it in context. No solver kwargs are needed (the maximizer is one_hot_argmax, which takes no kwargs).

generate_parametric_anticipative_solver(
    _::ContextualStochasticArgmaxBenchmark
) -> DecisionFocusedLearningBenchmarks.ContextualStochasticArgmax.AnticipativeSolver

Generates the parametric anticipative solver for the benchmark.

generate_scenario(::ContextualStochasticArgmaxBenchmark, rng; c_base, x_raw, kwargs...)

Draw ξ = c_base + W * x_raw + noise, noise ~ N(0, noise_std² I). c_base and x_raw are spread from ctx.context by the framework.

struct DynamicVehicleSchedulingBenchmark <: ExogenousDynamicBenchmark

Abstract type for dynamic vehicle scheduling benchmarks.

Fields

• max_requests_per_epoch::Int64: maximum number of customers entering the system per epoch

• Δ_dispatch::Float64: time between decision and dispatch of a vehicle

• epoch_duration::Float64: duration of an epoch

• two_dimensional_features::Bool: whether to use two-dimensional features

DVSPEnv(
    instance::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.Instance,
    scenario::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.Scenario;
    seed
) -> DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance{Float64}}, Random.MersenneTwister, Nothing}

Constructor for DVSPEnv from a pre-existing scenario.

DVSPEnv(
    instance::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.Instance;
    seed
) -> DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance{Float64}}, Random.MersenneTwister, Nothing}

Constructor for DVSPEnv.

State data structure for the Dynamic Vehicle Scheduling Problem.

struct Instance{I<:DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance, T}

Instance data structure for the dynamic vehicle scheduling problem.

struct KleopatraVSPPolicy{P}

Kleopatra policy for the Dynamic Vehicle Scheduling Problem.

struct Point{T}

Basic point structure.

struct StaticInstance{T}

Instance data structure for the (deterministic and static) Vehicle Scheduling Problem.

Fields

• coordinate::Array{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.Point{T}, 1} where T: coordinates of the locations. The first one is always the depot.

• service_time::Vector: service time at each location

• start_time::Vector: start time at each location

• duration::Matrix: duration matrix between locations

struct VSPSolution

Solution for the static Vehicle Scheduling Problem.

Fields

• routes::Vector{Vector{Int64}}: list of routes, each route being a list of request indices in corresponding instance (excluding the depot).

• edge_matrix::BitMatrix: size (nblocations, nblocations). edge_matrix[i, j] is equal to 1 if a route takes edge (i, j).

VSPSolution(
    routes::Vector{Vector{Int64}};
    max_index
) -> DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.VSPSolution

Build a VSPSolution from routes. Set max_index to manually define the size of the edge_index matrix.

anticipative_solver(
    env::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv;
    ...
) -> Tuple{Union{Float64, Vector{Float64}}, Vector}
anticipative_solver(
    env::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv,
    scenario;
    model_builder,
    two_dimensional_features,
    reset_env,
    nb_epochs,
    seed,
    verbose
) -> Tuple{Union{Float64, Vector{Float64}}, Vector}

Solve the anticipative VSP problem for environment env. For this, it uses the current environment history, so make sure that the environment is terminated before calling this method.

remove dispatched customers, and update must-dispatch and postponable flags.

Return a Dict with plot-ready information extracted from a vector of DataSample objects.

The returned dictionary contains:

• :n_epochs => Int
• :coordinates => Vector{Vector{Tuple{Float64,Float64}}} (per-epoch list of (x,y) tuples, empty if instance missing)
• :start_times => Vector{Vector{Float64}} (per-epoch start times, empty if instance missing)
• :node_types => Vector{Vector{Symbol}} (per-epoch node-type labels aligned with coordinates)
• :routes => Vector{Vector{Vector{Int}}} (per-epoch normalized routes; empty vector when no routes)
• :epoch_costs => Vector{Float64} (per-epoch cost; NaN if not computable)

This lets plotting code build figures without depending on plotting internals.

coordinate(
    state::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState
) -> Array{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.Point{T}, 1} where T

Get the coordinates vector.

coordinate(
    instance::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance
) -> Array{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.Point{T}, 1} where T

Get the coordinates vector.

cost(
    routes::Vector{Vector{Int64}},
    duration::AbstractMatrix
) -> Any

Compute the total cost of a set of routes given a distance matrix, i.e. the sum of the distances between each location in the route. Note that the first location is implicitly assumed to be the depot, and should not appear in the route.

create_graph(
    state::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState
) -> Graphs.SimpleGraphs.SimpleDiGraph{Int64}

Create the acyclic digraph associated with the given VSP state.

create_graph(
    instance::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance
) -> Graphs.SimpleGraphs.SimpleDiGraph{Int64}

Create the acyclic digraph associated with the given VSP instance.

customer_count(
    state::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState
) -> Int64

Return the number of customers in state.

customer_count(
    instance::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance
) -> Int64

Return the number of customers in instance (excluding the depot).

duration(
    state::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState
) -> Matrix

Get the duration matrix.

duration(
    instance::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance
) -> Matrix

Get the duration matrix.

edge_matrix(
    solution::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.VSPSolution
) -> BitMatrix

Get edge matrix from solution.

generate_environment(
    ::DynamicVehicleSchedulingBenchmark,
    instance::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.Instance,
    rng::Random.AbstractRNG;
    kwargs...
) -> DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance{Float64}}, Random.MersenneTwister, Int64}

Creates an environment from an Instance of the dynamic vehicle scheduling benchmark. The seed of the environment is randomly generated using the provided random number generator.

is_feasible(
    state::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState,
    routes::Vector{Vector{Int64}};
    verbose
) -> Bool

Check if the given routes are feasible. Routes should be given with global indexation. Use env_routes_from_state_routes if needed to convert the indices beforehand.

location_count(
    state::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState
) -> Int64

Return the number of locations in state (customers + depot).

location_count(
    instance::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance
) -> Int64

Return the number of locations in instance (customers + depot).

planning_start_time(
    env::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv
) -> Any

Get the planning start time of the environment, i.e. the time at which vehicles routes dispatched in current epoch can depart.

prize_collecting_vsp(
    θ::AbstractVector;
    instance,
    model_builder,
    kwargs...
)

Solve the Prize Collecting Vehicle Scheduling Problem defined by instance and prize vector θ.

read_vsp_instance(
    filepath::String;
    normalization,
    digits
) -> DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance{Float64}

Create a VSPInstance from file filepath containing a VRPTW instance. It uses time window values to compute task times as the middle of the interval.

Round all values to Int if rounded=true. Normalize all time values by the normalization parameter.

retrieve_routes(
    y::AbstractArray,
    graph::Graphs.AbstractGraph
) -> Vector{Vector{Int64}}

Retrieve routes solution from the given MIP solution y matrix and graph.

retrieve_routes_anticipative(
    y::AbstractArray,
    dvspenv::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv,
    customer_index,
    epoch_indices
) -> Any

Retrieve anticipative routes solution from the given MIP solution y. Outputs a set of routes per epoch.

routes(
    solution::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.VSPSolution
) -> Vector{Vector{Int64}}

Get routes from solution.

sample_indices(rng::Random.AbstractRNG, k, N) -> Any

Sample k random different indices from 2 to N+1.

sample_times(
    rng::Random.AbstractRNG,
    k,
    min_time,
    max_time;
    digits
) -> Any

Sample k random time values between mintime and maxtime.

service_time(
    state::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState
) -> Vector

Get the service time vector

service_time(
    instance::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance
) -> Vector

Get the service time vector.

start_time(
    state::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState
) -> Vector

Get the start time vector.

start_time(
    instance::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance
) -> Vector

Get the start time vector.

time(
    env::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv
) -> Any

Get the current time of the environment, i.e. the start time of the current_epoch.

generate_anticipative_solver(
    _::DynamicVehicleSchedulingBenchmark
) -> DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.var"#103#104"{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.var"#105#106"}

Return the anticipative solver for the dynamic vehicle scheduling benchmark. The callable takes an environment and solver kwargs and returns a training trajectory as a Vector{DataSample}. Set reset_env=true (default) to reset the environment before solving, or reset_env=false to plan from the current state.

generate_baseline_policies(
    _::DynamicVehicleSchedulingBenchmark
) -> @NamedTuple{lazy::Policy{typeof(DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.lazy_policy)}, greedy::Policy{typeof(DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.greedy_policy)}}

Generate baseline policies for the dynamic vehicle scheduling benchmark. Returns a tuple containing:

• lazy: A policy that dispatches vehicles only when they are ready
• greedy: A policy that dispatches vehicles to the nearest customer

generate_environments(
    b::DynamicVehicleSchedulingBenchmark,
    n::Int64;
    seed,
    rng,
    kwargs...
) -> Vector{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance{Float64}}, Random.MersenneTwister, Int64}}

Generate environments for the dynamic vehicle scheduling benchmark. Reads from pre-existing DVRPTW files and creates DVSPEnv environments.

generate_maximizer(
    _::DynamicVehicleSchedulingBenchmark
) -> InferOpt.LinearMaximizer{typeof(DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.oracle), typeof(DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.g), typeof(DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.h)}

Returns a linear maximizer for the dynamic vehicle scheduling benchmark, of the form: θ ↦ argmax_{y} θᵀg(y) + h(y)

generate_statistical_model(
    b::DynamicVehicleSchedulingBenchmark;
    seed
) -> Union{Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Vector{Float32}}, typeof(vec)}}, Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Bool}, typeof(vec)}}}

Generate a statistical model for the dynamic vehicle scheduling benchmark. The model is a simple linear chain with a single dense layer that maps features to a scalar output. The input dimension depends on whether two-dimensional features are used (2 features) or not (27 features).

is_terminated(
    env::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv
) -> Bool

Check if the episode is terminated, i.e. if the current epoch is the last one.

observe(
    env::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv
) -> Tuple{Any, DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState}

Get the current state of the environment.

reset!(
    env::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv;
    seed,
    reset_rng
)

Reset the environment to its initial state. Also reset the rng to seed if reset_rng is set to true.

step!(
    env::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv,
    routes
) -> Any
step!(
    env::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPEnv,
    routes,
    scenario
) -> Any

Remove dispatched customers, advance time, and add new requests to the environment.

struct DynamicAssortmentBenchmark{exogenous, M} <: AbstractDynamicBenchmark{exogenous}

Benchmark for the dynamic assortment problem.

Fields

• customer_choice_model::Any: customer choice model (price, hype, saturation, and features)

• N::Int64: number of items

• d::Int64: dimension of feature vectors (in addition to hype, satisfaction, and price)

• K::Int64: assortment size constraint

• max_steps::Int64: number of steps per episode

Reference: https://arxiv.org/abs/2505.19053

mutable struct Environment{I<:DecisionFocusedLearningBenchmarks.DynamicAssortment.Instance, R<:Random.AbstractRNG, S<:Union{Nothing, Int64}} <: AbstractEnvironment

Environment for the dynamic assortment problem.

Fields

• instance::DecisionFocusedLearningBenchmarks.DynamicAssortment.Instance: associated instance

• step::Int64: current step

• purchase_history::Vector{Int64}: purchase history (used to update hype feature)

• rng::Random.AbstractRNG: rng

• seed::Union{Nothing, Int64}: seed for RNG

• utility::Vector{Float64}: customer utility for each item

• features::Matrix{Float64}: current full features

• d_features::Matrix{Float64}: satisfaction + hype feature change from the last step

Environment(
    instance::DecisionFocusedLearningBenchmarks.DynamicAssortment.Instance;
    seed,
    rng
) -> DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment{I, Random.MersenneTwister, Int64} where I<:DecisionFocusedLearningBenchmarks.DynamicAssortment.Instance

Creates an Environment from an Instance of the dynamic assortment benchmark.

struct Instance{B<:DynamicAssortmentBenchmark}

Instance of the dynamic assortment problem.

Fields

• config::DynamicAssortmentBenchmark: associated benchmark

• prices::Vector{Float64}: item prices (including no purchase action)

• features::Matrix{Float64}: static features, size (d, N)

• starting_hype_and_saturation::Matrix{Float64}: starting hype and saturation features, size (2, N)

Instance(
    b::DynamicAssortmentBenchmark,
    rng::Random.AbstractRNG
) -> DecisionFocusedLearningBenchmarks.DynamicAssortment.Instance

Generates a random instance:

• random prices uniformly in [1, 10]
• random features uniformly in [1, 10]
• random starting hype and saturation uniformly in [1, 10]

buy_item!(
    env::DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment,
    item::Int64
)

Updates the environment state after a purchase of item.

choice_probabilities(
    env::DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment,
    assortment::BitVector
) -> Vector{Float64}

Compute the choice probabilities for each item in assortment.

compute_expected_revenue(
    env::DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment,
    assortment::BitVector
) -> Float64

Compute the expected revenue of offering assortment.

expert_policy(
    env::DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment
) -> BitVector

Expert policy that computes the optimal assortment by enumerating all possible assortments.

greedy_policy(
    env::DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment
) -> BitVector

Greedy policy that selects the assortment containing items with the highest prices.

hype_update(
    env::DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment
) -> Vector{Float64}

Compute an hype multiplier vector based on the purchase history. The hype multiplier (equal to 1 by default) for each item is updated as follows:

• If the item was purchased in the last step, its hype multiplier increases by 0.02.
• If the item was purchased in the last 2 to 5 steps, its hype multiplier decreases by 0.005.

generate_baseline_policies(
    _::DynamicAssortmentBenchmark
) -> @NamedTuple{expert::Policy{typeof(DecisionFocusedLearningBenchmarks.DynamicAssortment.expert_policy)}, greedy::Policy{typeof(DecisionFocusedLearningBenchmarks.DynamicAssortment.greedy_policy)}}

Returns two policies for the dynamic assortment benchmark:

• Greedy: selects the assortment containing items with the highest prices
• Expert: selects the assortment with the highest expected revenue (through brute-force enumeration)

generate_environment(
    b::DynamicAssortmentBenchmark,
    rng::Random.AbstractRNG;
    kwargs...
) -> DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment{I, Random.MersenneTwister, Int64} where I<:DecisionFocusedLearningBenchmarks.DynamicAssortment.Instance

Creates an Environment for the dynamic assortment benchmark. The instance and seed are randomly generated using the provided random number generator.

generate_maximizer(
    b::DynamicAssortmentBenchmark
) -> DecisionFocusedLearningBenchmarks.Utils.TopKMaximizer

Outputs a top k maximizer, with k being the assortment size of the benchmark.

generate_statistical_model(
    b::DynamicAssortmentBenchmark;
    seed
) -> Flux.Chain

Generates a statistical model for the dynamic assortment benchmark. The model is a small neural network with one hidden layer of size 5 and no activation function.

get_seed(
    env::DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment
) -> Union{Nothing, Int64}

Outputs the seed of the environment.

is_terminated(
    env::DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment
) -> Bool

Checks if the environment has reached the maximum number of steps.

observe(
    env::DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment
) -> Tuple{Matrix{Float64}, Tuple{Matrix{Float64}, Vector{Int64}}}

Features observed by the agent at current step, as a concatenation of:

• current full features (including prices, hype, saturation, and static features)
• change in hype and saturation features from the last step
• change in hype and saturation features from the starting state
• normalized current step (divided by max steps and multiplied by 10)

All features are normalized by dividing by 10.

State Return as a tuple:

• env.features: the current feature matrix (feature vector for all items).
• env.purchase_history: the purchase history over the most recent steps.

reset!(
    env::DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment;
    reset_rng,
    seed
)

Resets the environment to the initial state:

• reset the rng if reset_rng is true
• reset the step to 1
• reset the features to the initial features
• reset the change in features to zero
• reset the utility to the initial utility
• clear the purchase history

step!(
    env::DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment,
    assortment::BitVector
) -> Float64

Performs one step in the environment given an assortment. Draw an item according to the customer choice model and updates the environment state.

struct FixedSizeShortestPathBenchmark <: DecisionFocusedLearningBenchmarks.Utils.AbstractStaticBenchmark

Benchmark problem for the shortest path problem. In this benchmark, all graphs are acyclic directed grids, all of the same size grid_size. Features are given at instance level (one dimensional vector of length p for each graph).

Data is generated using the process described in: https://arxiv.org/abs/2307.13565.

Fields

• graph::Graphs.SimpleGraphs.SimpleDiGraph{Int64}: grid graph instance

• grid_size::Tuple{Int64, Int64}: grid size of graphs

• p::Int64: size of feature vectors

• deg::Int64: degree of formula between features and true weights

• ν::Float32: multiplicative noise for true weights sampled between [1-ν, 1+ν], should be between 0 and 1

FixedSizeShortestPathBenchmark(
;
    grid_size,
    p,
    deg,
    ν
) -> FixedSizeShortestPathBenchmark

Constructor for FixedSizeShortestPathBenchmark.

generate_maximizer(
    bench::FixedSizeShortestPathBenchmark;
    use_dijkstra
) -> Union{DecisionFocusedLearningBenchmarks.FixedSizeShortestPath.var"#shortest_path_maximizer#10"{DecisionFocusedLearningBenchmarks.FixedSizeShortestPath.var"#shortest_path_maximizer#5#11"{typeof(Graphs.bellman_ford_shortest_paths), Vector{Int64}, Vector{Int64}, Int64, Int64, Graphs.SimpleGraphs.SimpleDiGraph{Int64}}}, DecisionFocusedLearningBenchmarks.FixedSizeShortestPath.var"#shortest_path_maximizer#10"{DecisionFocusedLearningBenchmarks.FixedSizeShortestPath.var"#shortest_path_maximizer#5#11"{typeof(Graphs.dijkstra_shortest_paths), Vector{Int64}, Vector{Int64}, Int64, Int64, Graphs.SimpleGraphs.SimpleDiGraph{Int64}}}}

Outputs a function that computes the longest path on the grid graph, given edge weights θ as input.

maximizer = generate_maximizer(bench)
maximizer(θ)

generate_sample(
    bench::FixedSizeShortestPathBenchmark,
    rng::Random.AbstractRNG;
    type
) -> Union{DataSample{K, @NamedTuple{}, Vector{Float32}, BitVector, Vector{Float32}} where K<:NamedTuple, DataSample{K, @NamedTuple{}, Vector{Float32}, BitVector, Vector{Float64}} where K<:NamedTuple}

Generate a labeled sample for the fixed size shortest path benchmark.

generate_statistical_model(
    bench::FixedSizeShortestPathBenchmark;
    seed
) -> Union{Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Vector{Float32}}}}, Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Bool}}}}

Initialize a linear model for bench using Flux.

struct MaintenanceBenchmark <: ExogenousDynamicBenchmark

Benchmark for a standard maintenance problem with resource constraints. Components are identical and degrade independently over time. A high cost is incurred for each component that reaches the final degradation level. A cost is also incurred for maintaining a component. The number of simultaneous maintenance operations is limited by a maintenance capacity constraint.

Fields

• N::Int64: number of components

• K::Int64: maximum number of components that can be maintained simultaneously

• n::Int64: number of degradation states per component

• p::Float64: degradation probability

• c_f::Float64: failure cost

• c_m::Float64: maintenance cost

• max_steps::Int64: number of steps per episode

MaintenanceBenchmark(;
    N=2,
    K=1,
    n=3,
    p=0.2
    c_f=10.0,
    c_m=3.0,
    max_steps=80,
)

Constructor for MaintenanceBenchmark. By default, the benchmark has 2 components, maintenance capacity 1, number of degradation levels 3, degradation probability 0.2, failure cost 10.0, maintenance cost 3.0, 80 steps per episode, and is exogenous.

mutable struct Environment{R<:Random.AbstractRNG, S<:Union{Nothing, Int64}} <: AbstractEnvironment

Environment for the maintenance problem.

Fields

• instance::DecisionFocusedLearningBenchmarks.Maintenance.Instance: associated instance

• step::Int64: current step

• degradation_state::Vector{Int64}: degradation state

• rng::Random.AbstractRNG: rng

• seed::Union{Nothing, Int64}: seed for RNG

Environment(
    instance::DecisionFocusedLearningBenchmarks.Maintenance.Instance;
    seed,
    rng
) -> DecisionFocusedLearningBenchmarks.Maintenance.Environment{Random.MersenneTwister, Int64}

Creates an Environment from an Instance of the maintenance benchmark.

struct Instance{MaintenanceBenchmark}

Instance of the maintenance problem.

Fields

• config::Any: associated benchmark

• starting_state::Vector{Int64}: starting degradation states

Instance(
    b::MaintenanceBenchmark,
    rng::Random.AbstractRNG
) -> DecisionFocusedLearningBenchmarks.Maintenance.Instance{MaintenanceBenchmark}

Generates an instance with random starting degradation states uniformly in [1, n]

struct TopKPositiveMaximizer

Top k maximizer.

TopKPositiveMaximizer(
    k
) -> DecisionFocusedLearningBenchmarks.Maintenance.TopKPositiveMaximizer

Return the top k indices of θ.

degrad!(
    env::DecisionFocusedLearningBenchmarks.Maintenance.Environment
) -> Vector{Int64}

Draw random degradations for all components.

degradation_cost(
    env::DecisionFocusedLearningBenchmarks.Maintenance.Environment
) -> Float64

Compute degradation cost.

greedy_policy(
    env::DecisionFocusedLearningBenchmarks.Maintenance.Environment
) -> BitVector

Greedy policy that maintains components when they are in the last state before failure, up to the maintenance capacity.

maintain!(
    env::DecisionFocusedLearningBenchmarks.Maintenance.Environment,
    maintenance::BitVector
) -> Vector{Int64}

Maintain components.

maintenance_cost(
    env::DecisionFocusedLearningBenchmarks.Maintenance.Environment,
    maintenance::BitVector
) -> Float64

Compute maintenance cost.

generate_baseline_policies(
    _::MaintenanceBenchmark
) -> @NamedTuple{greedy::Policy{typeof(DecisionFocusedLearningBenchmarks.Maintenance.greedy_policy)}}

Returns a policy for the maintenance benchmark:

• Greedy: maintains components when they are in the last state before failure, up to the maintenance capacity

generate_environment(
    b::MaintenanceBenchmark,
    rng::Random.AbstractRNG;
    kwargs...
) -> DecisionFocusedLearningBenchmarks.Maintenance.Environment{Random.MersenneTwister, Int64}

Creates an Environment for the maintenance benchmark. The instance and seed are randomly generated using the provided random number generator.

generate_maximizer(
    b::MaintenanceBenchmark
) -> DecisionFocusedLearningBenchmarks.Maintenance.TopKPositiveMaximizer

Outputs a top k maximizer, with k being the maintenance capacity of the benchmark.

generate_sample(
    b::MaintenanceBenchmark,
    rng::Random.AbstractRNG
) -> DataSample{@NamedTuple{instance::DecisionFocusedLearningBenchmarks.Maintenance.Instance{MaintenanceBenchmark}}, @NamedTuple{}, Nothing, Nothing, Nothing}

Outputs a data sample containing an Instance.

generate_statistical_model(
    b::MaintenanceBenchmark;
    seed
) -> Flux.Chain

Generates a statistical model for the maintenance benchmark. The model is a small neural network with one hidden layer no activation function.

get_seed(
    env::DecisionFocusedLearningBenchmarks.Maintenance.Environment
) -> Union{Nothing, Int64}

Outputs the seed of the environment.

is_terminated(
    env::DecisionFocusedLearningBenchmarks.Maintenance.Environment
) -> Bool

Checks if the environment has reached the maximum number of steps.

observe(
    env::DecisionFocusedLearningBenchmarks.Maintenance.Environment
) -> Tuple{Vector{Int64}, Vector{Int64}}

Returns features, state tuple. The features observed by the agent at current step are the degradation states of all components. It is also the internal state, so we return the same thing twice.

reset!(
    env::DecisionFocusedLearningBenchmarks.Maintenance.Environment;
    reset_rng,
    seed
)

Resets the environment to the initial state:

• reset the rng if reset_rng is true
• reset the step to 1
• reset the degradation state to the starting state

step!(
    env::DecisionFocusedLearningBenchmarks.Maintenance.Environment,
    maintenance::BitVector
) -> Float64

Performs one step in the environment given a maintenance. Draw random degradations for components that are not maintained.

struct PortfolioOptimizationBenchmark <: DecisionFocusedLearningBenchmarks.Utils.AbstractStaticBenchmark

Benchmark problem for the portfolio optimization problem.

Data is generated using the process described in: https://arxiv.org/abs/2307.13565.

Fields

• d::Int64: number of assets

• p::Int64: size of feature vectors

• deg::Int64: hypermarameter for data generation

• ν::Float32: another hyperparameter, should be positive

• Σ::Matrix{Float32}: covariance matrix

• γ::Float32: maximum variance of portfolio

• L::Matrix{Float32}: useful for dataset generation

• f::Vector{Float32}: useful for dataset generation

PortfolioOptimizationBenchmark(
;
    d,
    p,
    deg,
    ν,
    seed
) -> PortfolioOptimizationBenchmark

Constructor for PortfolioOptimizationBenchmark.

generate_maximizer(
    bench::PortfolioOptimizationBenchmark
) -> DecisionFocusedLearningBenchmarks.PortfolioOptimization.var"#portfolio_maximizer#portfolio_maximizer##0"{Float32, Matrix{Float32}, Int64}

Create a function solving the MIQP formulation of the portfolio optimization problem.

generate_sample(
    bench::PortfolioOptimizationBenchmark,
    rng::Random.AbstractRNG;
    type
) -> DataSample{@NamedTuple{}, @NamedTuple{}, Vector{Float32}, Vector{Float64}, Vector{Float64}}

Generate a labeled sample for the portfolio optimization problem.

generate_statistical_model(
    bench::PortfolioOptimizationBenchmark;
    seed
) -> Union{Flux.Dense{typeof(identity), Matrix{Float32}, Vector{Float32}}, Flux.Dense{typeof(identity), Matrix{Float32}, Bool}}

Initialize a linear model for bench using Flux.

struct RankingBenchmark{E} <: DecisionFocusedLearningBenchmarks.Utils.AbstractStaticBenchmark

Basic benchmark problem with ranking as the CO algorithm.

Fields

• instance_dim::Int64: instances dimension, total number of classes

• nb_features::Int64: number of features

• encoder::Any: true mapping between features and costs

RankingBenchmark(
;
    instance_dim,
    nb_features,
    seed
) -> Union{RankingBenchmark{Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Vector{Float32}}, typeof(vec)}}}, RankingBenchmark{Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Bool}, typeof(vec)}}}}

Custom constructor for RankingBenchmark.

ranking(θ::AbstractVector; rev, kwargs...) -> Any

Compute the vector r such that rᵢ is the rank of θᵢ in θ.

generate_maximizer(
    bench::RankingBenchmark
) -> typeof(DecisionFocusedLearningBenchmarks.Ranking.ranking)

Return a ranking maximizer.

generate_sample(
    bench::RankingBenchmark,
    rng::Random.AbstractRNG;
    noise_std
) -> DataSample{K, @NamedTuple{}, Matrix{Float32}} where K<:NamedTuple

Generate a labeled sample for the ranking problem.

generate_statistical_model(
    bench::RankingBenchmark;
    seed
) -> Union{Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Vector{Float32}}, typeof(vec)}}, Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Bool}, typeof(vec)}}}

Initialize a linear model for bench using Flux.

struct SubsetSelectionBenchmark{M} <: DecisionFocusedLearningBenchmarks.Utils.AbstractStaticBenchmark

Benchmark problem for the subset selection problem. Reference: https://arxiv.org/abs/2307.13565.

The goal is to select the best k items from a set of n items, without knowing their values, but only observing some features.

Fields

• n::Int64: total number of items

• k::Int64: number of items to select

• mapping::Any: hidden unknown mapping from features to costs

generate_maximizer(
    bench::SubsetSelectionBenchmark
) -> Base.Fix2{typeof(DecisionFocusedLearningBenchmarks.SubsetSelection.top_k), Int64}

Return a top k maximizer.

generate_sample(
    bench::SubsetSelectionBenchmark,
    rng::Random.AbstractRNG
) -> DataSample{K, @NamedTuple{}, Vector{Float32}} where K<:NamedTuple

Generate a labeled instance for the subset selection problem.

generate_statistical_model(
    bench::SubsetSelectionBenchmark;
    seed
) -> Union{Flux.Dense{typeof(identity), Matrix{Float32}, Vector{Float32}}, Flux.Dense{typeof(identity), Matrix{Float32}, Bool}}

Initialize a linear model for bench using Flux.

struct StochasticVehicleSchedulingBenchmark <: ExogenousStochasticBenchmark

Data structure for a stochastic vehicle scheduling benchmark.

Fields

• nb_tasks::Int64: number of tasks in each instance

• nb_scenarios::Int64: number of scenarios in each instance (only used to compute features and objective evaluation)

struct VSPScenario

Represents a single scenario for the stochastic vehicle scheduling problem.

Fields

• delays::Vector{Float64}: delays per task (length = nbtasks + 2): scenarioendtime - nominalend_time

• slacks::SparseArrays.SparseMatrixCSC{Float64, Int64}: scalar slack per arc for this scenario

build_stochastic_instance(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance,
    scenarios::Vector{DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.VSPScenario}
) -> DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance{_A, G, M1, Matrix{Float64}} where {_A, G<:Graphs.AbstractGraph, M1<:(AbstractMatrix)}

Build a stochastic Instance from a base instance and a vector of fresh VSPScenarios. Each scenario contributes one column to the intrinsic_delays matrix and one entry per edge to the slacks sparse matrix.

column_generation_algorithm(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance;
    scenario_range,
    bounding,
    use_convex_resources,
    silent,
    close_gap
) -> BitVector

Solve input instance using column generation.

compact_linearized_mip(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance;
    ...
) -> Any
compact_linearized_mip(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance,
    θ;
    scenario_range,
    model_builder,
    silent
) -> Any

Returns the optimal solution of the Stochastic VSP instance, by solving the associated compact MIP. Quadratic constraints are linearized using Mc Cormick linearization. Note: If you have Gurobi, use grb_model as model_builder instead of highs_model.

compact_linearized_mip(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance,
    scenarios::Vector{DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.VSPScenario};
    kwargs...
) -> Any

SAA variant: build stochastic instance from scenarios then solve via compact_linearized_mip.

compact_mip(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance;
    ...
) -> Any
compact_mip(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance,
    θ;
    scenario_range,
    model_builder,
    silent
) -> Any

Returns the optimal solution of the Stochastic VSP instance, by solving the associated compact quadratic MIP. Note: If you have Gurobi, use grb_model as model_builder instead of highs_model.

compact_mip(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance,
    scenarios::Vector{DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.VSPScenario};
    ...
) -> Any
compact_mip(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance,
    scenarios::Vector{DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.VSPScenario},
    θ;
    kwargs...
) -> Any

SAA variant: build stochastic instance from scenarios then solve via compact_mip.

deterministic_mip(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance;
    model_builder,
    silent
) -> Any

Solves the deterministic version of the vehicle scheduling problem using a MIP model. Does not take into account the stochastic nature of the problem.

evaluate_solution(
    path_value::BitMatrix,
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance
) -> Any

Compute total weighted objective of solution.

evaluate_solution(
    solution::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Solution,
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance
) -> Any

Compute total weighted objective of solution.

is_feasible(
    solution::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Solution,
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance;
    verbose
) -> Bool

Check if solution is an admissible solution of instance.

local_search(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance;
    num_iterations
) -> BitVector

Very simple heuristic, using local_search initialised with the solution of the deterministic Linear program

generate_maximizer(
    ::StochasticVehicleSchedulingBenchmark;
    model_builder
) -> DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.StochasticVechicleSchedulingMaximizer{typeof(DecisionFocusedLearningBenchmarks.Utils.highs_model)}

generate_statistical_model(
    ::StochasticVehicleSchedulingBenchmark;
    seed
) -> Union{Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Vector{Float32}}, typeof(vec)}}, Flux.Chain{Tuple{Flux.Dense{typeof(identity), Matrix{Float32}, Bool}, typeof(vec)}}}

struct City

Data structure for a city in the vehicle scheduling problem. Contains all the relevant information to build an instance of the problem.

Fields

• width::Int64: city width (in minutes)

• vehicle_cost::Float64: cost of a vehicle in the objective function

• delay_cost::Float64: cost of one minute delay in the objective function

• nb_tasks::Int64: number of tasks to fulfill

• tasks::Vector{DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Task}: tasks list (see Task), that should be ordered by start time

• district_width::Int64: idth (in minutes) of each district

• districts::Matrix{DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.District}: districts matrix (see District), indices corresponding to their relative positions

• random_inter_area_factor::Distributions.LogNormal{Float64}: a log-normal distribution modeling delay between districts

• scenario_inter_area_factor::Matrix{Float64}: size (nb_scenarios, 24), each row correspond to one scenario, each column to one hour of the day

City(
;
    nb_scenarios,
    width,
    vehicle_cost,
    nb_tasks,
    tasks,
    district_width,
    districts,
    delay_cost,
    random_inter_area_factor,
    scenario_inter_area_factor
) -> DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City

Constructor for City.

struct District

Data structure for a district in the vehicle scheduling problem.

Fields

• random_delay::Distributions.LogNormal{Float64}: log-normal distribution modeling the district delay

• scenario_delay::Matrix{Float64}: size (nb_scenarios, 24), observed delays for each scenario and hour of the day

District(; random_delay, nb_scenarios)

Constructor for District. Initialize a district with a given number of scenarios, with zeros in scenario_delay.

struct Instance{CC, G<:Graphs.AbstractGraph, M1<:(AbstractMatrix), M2<:(AbstractMatrix), F, C}

Instance of the stochastic VSP problem.

Fields

• graph::Graphs.AbstractGraph: graph computed from city with the create_VSP_graph(city::City) method

• features::Matrix: features matrix computed from city

• slacks::AbstractMatrix: slack matrix

• intrinsic_delays::AbstractMatrix: intrinsic delays scenario matrix

• vehicle_cost::Any: cost of a vehicle

• delay_cost::Any: cost of one minute delay

• city::Any: associated city

Instance(
;
    nb_tasks,
    nb_scenarios,
    rng,
    store_city,
    kwargs...
)

Constructor for Instance. Build an Instance for the stochatsic vehicle scheduling problem, with nb_tasks tasks and nb_scenarios scenarios.

struct Point

2D point data structure.

struct Solution

Should always be associated with an Instance.

Fields

• value::BitVector: for each graph edge of instance, 1 if selected, else 0

• path_value::BitMatrix: each row represents a vehicle, each column a task. 1 if task is done by the vehicle, else 0

Solution(
    path_value::BitMatrix,
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance
) -> DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Solution

Create a Solution from a BitMatrix path value.

Solution(
    value::BitVector,
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance
) -> DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Solution

Create a Solution from a BitVector value.

struct StochasticVechicleSchedulingMaximizer{M}

Deterministic vsp maximizer for the StochasticVehicleSchedulingBenchmark.

Apply the maximizer with the stored model builder.

struct Task

Data structure for a task in the vehicle scheduling problem.

Fields

• type::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.TaskType: type of the task (depot start, job, or depot end)

• start_point::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Point: starting location of the task

• end_point::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Point: end location of the task

• start_time::Float64: start time (in minutes) of the task

• end_time::Float64: end time (in minutes) of the task

• random_delay::Distributions.LogNormal{Float64}: lognormal distribution modeling the task start delay

• scenario_start_time::Vector{Float64}: size (nb_scenarios), observed delayed start times for each scenario

• scenario_end_time::Vector{Float64}: size (nb_scenarios), observed delayed end times for each scenario

Task(
;
    type,
    start_point,
    end_point,
    start_time,
    end_time,
    nb_scenarios,
    random_delay
)

Constructor for Task.

show(
    io::IO,
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance
)

Display a compact summary of an Instance: number of tasks, scenarios, and edges.

show(
    io::IO,
    s::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.VSPScenario
)

Display a compact summary of a VSPScenario: number of tasks and edges.

_local_search(
    solution::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Solution,
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance;
    nb_it
) -> Tuple{DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Solution, Any, Vector{Int64}, Vector}

Very simple local search heuristic, using the neighborhood defined by move_one_random_task

column_generation(instance::Instance)

Note: If you have Gurobi, use grb_model as model_builder instead of glpk_model.

compute_delays(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City
) -> Matrix{Float64}

Compute delays for instance.

compute_features(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City
) -> Matrix{Float32}

Returns a matrix of features of size (20, nb_edges). For each edge, compute the following features (in the same order):

• travel time
• vehicle_cost if edge is connected to source, else 0
• 9 deciles of the slack
• cumulative probability distribution of the slack evaluated in [-100, -50, -20, -10, 0, 10, 50, 200, 500]

compute_perturbed_end_times!(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City
)

Compute the end times of the tasks for each scenario.

compute_slacks(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City,
    graph::Graphs.AbstractGraph
) -> Any

Compute slack for instance. TODO: differentiate from other method

compute_slacks(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City,
    old_task_index::Int64,
    new_task_index::Int64
) -> Vector{Float64}

Compute slack for features.

compute_solution_from_selected_columns(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance,
    paths;
    bin,
    model_builder,
    scenario_range,
    silent
) -> Tuple{Float64, Any, Any}

Note: If you have Gurobi, use grb_model as model_builder instead od glpk_model.

create_VSP_graph(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City
) -> Graphs.SimpleGraphs.SimpleDiGraph{Int64}

Return the acyclic directed graph corresponding to city. Each vertex represents a task. Vertices are ordered by start time of corresponding task. There is an edge from task u to task v the (end time of u + tie distance between u and v <= start time of v).

create_random_city(
;
    αᵥ_low,
    αᵥ_high,
    first_begin_time,
    last_begin_time,
    district_μ,
    district_σ,
    task_μ,
    task_σ,
    seed,
    rng,
    city_kwargs...
) -> DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City

• Creates a city from city_kwargs
• Depot location at city center
• Randomize tasks, and add two dummy tasks : one source task at time=0 from the depot, and one destination task ending at time=end at depot
• Roll every scenario.

delay_sum(path, slacks, delays)

Evaluate the total delay along path.

distance(
    p₁::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Point,
    p₂::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Point
) -> Float64

Returns euclidean distance between p₁ and p₂.

draw_random_point(distrib::Distributions.Distribution; rng)

Returns a Point with random x and y, drawn from distrib.

draw_scenario(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City,
    graph::Graphs.AbstractGraph,
    rng::Random.AbstractRNG
) -> DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.VSPScenario

Draw a single fresh scenario from the city's random distributions, independently of the stored scenario draws in the City struct.

evaluate_scenario(path_value::BitMatrix, instance::Instance, scenario_index::Int)

Compute total delay of scenario.

evaluate_scenario(
    solution::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Solution,
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance,
    scenario_index::Int64
) -> Any

Compute total delay of scenario.

evaluate_task(
    i_task::Integer,
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance,
    old_task_index::Integer,
    old_delay::Real,
    scenario::Int64
) -> Any

Evaluate the total delay of task i_task in scenario, knowing that current delay from task old_task_index is old_delay.

find_first_one(A::AbstractVector) -> Int64

Returns index of first non zero element of A.

generate_scenarios!(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City;
    rng
)

Draw all delay scenarios for the city.

get_district(point::Point, city::City)

Return indices of the city district containing point.

get_features(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance
) -> Matrix

Returns the feature matrix associated to instance.

get_nb_scenarios(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City
) -> Int64

Returns the number of scenarios in city.

get_nb_scenarios(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance
) -> Any

Returns the number of scenarios in instance.

get_nb_tasks(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City
) -> Int64

Returns the number of tasks in city.

get_nb_tasks(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance
) -> Any

Returns the number of tasks in instance.

get_perturbed_travel_time(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City,
    old_task_index::Int64,
    new_task_index::Int64,
    scenario::Int64
) -> Float64

Compute the achieved travel time of scenario scenario from old_task_index to new_task_index.

hour_of(minutes::Real) -> Int64

Returns hour of the day corresponding to minutes amount.

init_districts!(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City,
    district_μ::Distributions.Distribution,
    district_σ::Distributions.Distribution;
    rng
)

Initialize the districts of the city.

init_tasks!(
    city::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City,
    αᵥ_low::Real,
    αᵥ_high::Real,
    first_begin_time::Real,
    last_begin_time::Real,
    task_μ::Distributions.Distribution,
    task_σ::Distributions.Distribution;
    rng
)

Draw the tasks of the city.

move_one_random_task!(
    path_value::BitMatrix,
    graph::Graphs.AbstractGraph
)

Select one random (uniform) task and move it to another random (uniform) feasible vehicle

nb_scenarios(
    task::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Task
) -> Int64

Return the number of scenarios for the given task.

roll(
    district::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.District,
    rng::Random.AbstractRNG
)

Populate scenario_delay with delays drawn from random_delay distribution for each (scenario, hour) pair.

roll(
    task::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Task,
    rng::Random.AbstractRNG
)

Populate scenario_start_time with delays drawn from the random_delay distribution of the given task for each scenario.

scenario_next_delay(
    previous_delay::Real,
    random_delay::Distributions.Distribution,
    rng::Random.AbstractRNG
) -> Any

Return one scenario of future delay given current delay and delay distribution.

solution_from_JuMP_array(
    x::AbstractArray,
    graph::Graphs.AbstractGraph
) -> Any

Create a Solution from a JuMP array.

solution_from_paths(
    paths,
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance
) -> DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Solution

Create a Solution from routes.

solve_deterministic_VSP(
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance;
    include_delays,
    model_builder,
    verbose
) -> Tuple{Union{Float64, Vector{Float64}}, Any}

Return the optimal solution of the deterministic VSP problem associated to instance. The objective function is vehicle_cost * nb_vehicles + include_delays * delay_cost * sum_of_travel_times Note: If you have Gurobi, use grb_model as model_builder instead od highs_model.

svs_deterministic_policy(
    ctx_sample,
    scenarios;
    model_builder
) -> Vector{T} where T<:DataSample

Deterministic baseline policy: solves the deterministic MIP (ignores scenario delays). Returns a single labeled DataSample with extra=(; scenarios).

svs_generate_baseline_policies(
    _::StochasticVehicleSchedulingBenchmark
) -> @NamedTuple{deterministic::Policy{typeof(DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.svs_deterministic_policy)}, saa::Policy{typeof(DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.svs_saa_policy)}, saa_mip::Policy{typeof(DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.svs_saa_mip_policy)}, local_search::Policy{typeof(DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.svs_local_search_policy)}}

Return the named baseline policies for StochasticVehicleSchedulingBenchmark. Each policy has signature (ctx_sample, scenarios) -> Vector{DataSample}.

svs_local_search_policy(
    ctx_sample,
    scenarios
) -> Vector{T} where T<:DataSample

Local search baseline policy: builds a stochastic instance from all K scenarios and solves via local search heuristic. Returns a single labeled DataSample with extra=(; scenarios).

svs_saa_mip_policy(
    ctx_sample,
    scenarios;
    model_builder
) -> Vector{T} where T<:DataSample

Exact SAA MIP policy (linearized): solves the stochastic VSP exactly for the given scenarios via compact_linearized_mip. Returns a single labeled DataSample with extra=(; scenarios).

Prefer this over svs_saa_policy when an exact solution is needed; requires SCIP (default) or Gurobi.

svs_saa_policy(
    ctx_sample,
    scenarios
) -> Vector{T} where T<:DataSample

SAA baseline policy: builds a stochastic instance from all K scenarios and solves via column generation. Returns a single labeled DataSample with extra=(; scenarios).

to_array(
    solution::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Solution,
    instance::DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance
) -> Any

Returns a BitMatrix, with value true at each index (i, j) if corresponding edge of graph is selected in the solution

vsp_maximizer(
    θ::AbstractVector;
    instance,
    model_builder,
    silent
)

Given arcs weights θ, solve the deterministic VSP problem associated to instance.

generate_anticipative_solver(
    ::StochasticVehicleSchedulingBenchmark;
    model_builder
) -> DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.AnticipativeSolver{typeof(DecisionFocusedLearningBenchmarks.Utils.scip_model), typeof(DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.compact_mip)}

Return the anticipative solver: a callable (scenario::VSPScenario; instance, kwargs...) -> y that solves the 1-scenario stochastic VSP.

Keyword Arguments

• model_builder: a function returning an empty JuMP.Model with a solver attached (defaults to scip_model).

generate_baseline_policies(
    bench::StochasticVehicleSchedulingBenchmark
) -> @NamedTuple{deterministic::Policy{typeof(DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.svs_deterministic_policy)}, saa::Policy{typeof(DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.svs_saa_policy)}, saa_mip::Policy{typeof(DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.svs_saa_mip_policy)}, local_search::Policy{typeof(DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.svs_local_search_policy)}}

generate_instance(
    benchmark::StochasticVehicleSchedulingBenchmark,
    rng::Random.AbstractRNG;
    store_city,
    kwargs...
) -> DataSample{K, @NamedTuple{}, Matrix{Float32}, Nothing, Nothing} where K<:NamedTuple

Generate an unlabeled instance for the given StochasticVehicleSchedulingBenchmark. Returns a DataSample with features x and instance set, but y=nothing.

To obtain labeled samples, pass a target_policy to generate_dataset:

policy = sample -> DataSample(; sample.context..., x=sample.x,
                                y=column_generation_algorithm(sample.instance))
dataset = generate_dataset(benchmark, N; target_policy=policy)

If store_city=false, coordinates and city information are not stored in the instance, and generate_scenario will not work. This can be used to save memory if you only need to evaluate solutions on a fixed set of scenarios.

generate_parametric_anticipative_solver(
    ::StochasticVehicleSchedulingBenchmark;
    model_builder
) -> DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.AnticipativeSolver{typeof(DecisionFocusedLearningBenchmarks.Utils.scip_model), typeof(DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.compact_mip)}

Return the parametric anticipative solver: a callable (θ, scenario::VSPScenario; instance, kwargs...) -> y.

Keyword Arguments

• model_builder: a function returning an empty JuMP.Model with a solver attached (defaults to scip_model).

generate_scenario(
    ::StochasticVehicleSchedulingBenchmark,
    rng::Random.AbstractRNG;
    instance,
    kwargs...
)

Draw a single fresh VSPScenario for the given instance. Requires store_city=true (the default) when generating instances.

struct WarcraftBenchmark <: DecisionFocusedLearningBenchmarks.Utils.AbstractStaticBenchmark

Benchmark for the Warcraft shortest path problem. Does not have any field.

generate_dataset(::WarcraftBenchmark; ...) -> Vector
generate_dataset(
    ::WarcraftBenchmark,
    dataset_size::Int64;
    target_policy,
    seed,
    rng,
    kwargs...
) -> Vector

Downloads and decompresses the Warcraft dataset the first time it is called.

generate_maximizer(
    ::WarcraftBenchmark;
    dijkstra
) -> typeof(DecisionFocusedLearningBenchmarks.Warcraft.dijkstra_maximizer)

Returns an optimization algorithm that computes a longest path on the grid graph with given weights. Uses a shortest path algorithm on opposite weights to get the longest path.

generate_statistical_model(
    ::WarcraftBenchmark;
    seed
) -> Flux.Chain{T} where T<:Tuple{Any, Any, Any, Any, Flux.AdaptiveMaxPool{4, 2}, typeof(DecisionFocusedLearningBenchmarks.Utils.average_tensor), typeof(DecisionFocusedLearningBenchmarks.Utils.neg_tensor), typeof(DecisionFocusedLearningBenchmarks.Utils.squeeze_last_dims)}

Create and return a Flux.Chain embedding for the Warcraft terrains, inspired by differentiation of blackbox combinatorial solvers.

The embedding is made as follows:

1. The first 5 layers of ResNet18 (convolution, batch normalization, relu, maxpooling and first resnet block).
2. An adaptive maxpooling layer to get a (12x12x64) tensor per input image.
3. An average over the third axis (of size 64) to get a (12x12x1) tensor per input image.
4. The element-wize neg_tensor function to get cell weights of proper sign to apply shortest path algorithms.
5. A squeeze function to forget the two last dimensions.

bellman_maximizer(
    θ::AbstractMatrix;
    kwargs...
) -> Matrix{Int64}

Computes the longest path in given grid graph weights by computing the shortest path in the graph with opposite weights. Using the Ford-Bellman dynamic programming algorithm.

convert_image_for_plot(
    image::Array{Float32, 3}
) -> Matrix{ColorTypes.RGB{FixedPointNumbers.N0f8}}

Convert image to the proper data format to enable plots in Julia.

create_dataset(
    decompressed_path::String,
    nb_samples::Int64
) -> Vector

Create the dataset corresponding to the data located at decompressed_path, possibly sub-sampling nb_samples points. The dataset is made of images of Warcraft terrains, cell cost labels and shortest path labels. It is a Vector of tuples, each Tuple being a dataset point.

dijkstra_maximizer(
    θ::AbstractMatrix;
    kwargs...
) -> Matrix{Int64}

Computes the longest path in given grid graph weights by computing the shortest path in the graph with opposite weights. Using the Dijkstra algorithm.

grid_bellman_ford_warcraft(g, s, d, length_max)

Apply the Bellman-Ford algorithm on an GridGraph g, and return a ShortestPathTree with source s and destination d, among the paths having length smaller than length_max.

read_dataset(
    decompressed_path::String
) -> Tuple{Any, Any, Any}
read_dataset(
    decompressed_path::String,
    dtype::String
) -> Tuple{Any, Any, Any}

Read the dataset of type dtype at the decompressed_path location. The dataset is made of images of Warcraft terrains, cell cost labels and shortest path labels. They are returned separately, with proper axis permutation and image scaling to be consistent with Flux embeddings.