API Reference

abstract type AbstractBenchmark

Abstract type interface for benchmark problems.

Mandatory methods to implement for any benchmark:

Choose one of three primary implementation strategies:

• Implement generate_instance (returns a DataSample with y=nothing). The default generate_sample then applies target_policy if provided.
• Override generate_sample directly when the sample requires custom logic. In this case, 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
• objective_value: defaults to dot(θ, y)
• compute_gap: default implementation provided; override for custom evaluation

Optional methods (no default)

• plot_data, plot_instance, plot_solution
• generate_baseline_policies

abstract type AbstractDynamicBenchmark{exogenous} <: AbstractStochasticBenchmark{exogenous}

Abstract type interface for multi-stage stochastic (dynamic) benchmark problems.

Extends AbstractStochasticBenchmark. The {exogenous} parameter retains its meaning (whether uncertainty is independent of decisions).

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

abstract type AbstractEnvironment

Abstract type for environments in decision-focused learning benchmarks.

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 (exogenous benchmarks, {true} only)

• generate_instance(bench, rng): returns a DataSample with instance and features but no scenario. Scenarios are added later by generate_dataset via generate_scenario.
• generate_scenario(bench, rng; kwargs...): draws a random scenario. Instance and context fields are passed as keyword arguments spread from sample.context.

Optional methods

• 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 AbstractStochasticBenchmark{true} and supports all three standard structures via nb_scenarios:

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

Provide a target_policy(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{CTX<:NamedTuple, EX<: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. Additionally, it has a context field (solver kwargs, 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: context information as solver kwargs, e.g. instance, graph, etc.

• 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 kwargs). The extra keyword accepts a NamedTuple of non-solver data.

Fields in context and extra must be disjoint. An error is thrown if they overlap. 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)

struct Policy{P}

Policy type for decision-focused learning benchmarks.

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

struct TopKMaximizer

Top k maximizer.

TopKMaximizer(
    k
) -> DecisionFocusedLearningBenchmarks.Utils.TopKMaximizer

Return the top k indices of θ.

average_tensor(x)

Average the tensor x along its third axis.

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

Default implementation of compute_gap: average relative optimality gap over dataset. Requires samples with x, θ, and y fields. Override for custom evaluation logic.

compute_gap(::AbstractBenchmark, dataset::Vector{<:DataSample}, statistical_model, maximizer) -> Float64

Compute the average relative optimality gap of the pipeline on the dataset.

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{CTX, EX, F, S, C}, 1} where {CTX<:NamedTuple, EX<: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_solution(::AbstractStochasticBenchmark, instance, scenario; kwargs...)

generate_baseline_policies(::AbstractBenchmark) -> NamedTuple or Tuple

Return named baseline policies for the benchmark. Each policy is a callable.

• For static/stochastic benchmarks: signature (sample) -> DataSample.
• For dynamic benchmarks: signature (env) -> Vector{DataSample} (full trajectory).

generate_dataset(::AbstractBenchmark, 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_data, when it applies.

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

generate_dataset(
    bench::AbstractDynamicBenchmark{true},
    environments::AbstractVector;
    target_policy,
    seed,
    rng,
    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}.
• seed: passed to MersenneTwister when rng is not provided.
• rng: random number generator.

generate_dataset(
    bench::AbstractDynamicBenchmark{true},
    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::AbstractStochasticBenchmark{true},
    nb_instances::Int64;
    target_policy,
    nb_scenarios,
    seed,
    rng,
    kwargs...
)

Specialised generate_dataset for exogenous stochastic benchmarks.

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

• Without target_policy (default): K scenarios produce K unlabeled samples (1:1).
• With target_policy(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 instance (K).
• target_policy: when provided, called as target_policy(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_environment(::AbstractDynamicBenchmark, rng::AbstractRNG; kwargs...)

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_sample(::AbstractBenchmark, rng::AbstractRNG; target_policy=nothing, kwargs...) -> DataSample

Generate a single DataSample for the benchmark.

Framework default (when generate_instance is implemented): Calls generate_instance, then applies target_policy(sample) if provided.

Override directly (instead of implementing generate_instance) when the sample requires custom logic. In this case, generate_dataset applies target_policy after the call returns.

generate_sample(
    bench::AbstractStochasticBenchmark{true},
    rng;
    target_policy,
    nb_scenarios,
    kwargs...
) -> DataSample{@NamedTuple{instance::DecisionFocusedLearningBenchmarks.Maintenance.Instance{MaintenanceBenchmark}}, @NamedTuple{}, Nothing, Nothing, Nothing}

Default generate_sample for exogenous stochastic benchmarks.

Calls generate_instance, draws nb_scenarios scenarios via generate_scenario, then:

• Without target_policy: returns K unlabeled samples, each with one scenario in extra=(; scenario=ξ).
• With target_policy: calls target_policy(sample, scenarios) and returns the result.

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

generate_scenario(::AbstractStochasticBenchmark{true}, rng::AbstractRNG; kwargs...) -> scenario

Draw a random scenario. Instance and context fields are passed as keyword arguments, spread from sample.context:

scenario = generate_scenario(bench, rng; sample.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)

highs_model() -> JuMP.Model

Initialize a HiGHS model (with disabled logging).

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(
    _::AbstractBenchmark,
    θ::AbstractArray,
    y::AbstractArray
) -> Any

Compute dot(θ, y). Override for non-linear objectives.

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

Compute the objective value of given solution y.

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

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

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_data(::AbstractBenchmark, ::DataSample; kwargs...)

Plot a data sample from the dataset created by generate_dataset. Check the specific benchmark documentation of plot_data for more details on the arguments.

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

generate_anticipative_solver(::AbstractStochasticBenchmark{true}) -> callable

Return a callable that computes the anticipative solution for a given scenario. The instance and other solver-relevant fields are spread from the sample context.

• For AbstractStochasticBenchmark: returns (scenario; context...) -> y.

• For AbstractDynamicBenchmark: returns (scenario; context...) -> Vector{DataSample} — a full training trajectory.

  solver = generateanticipativesolver(bench) y = solver(scenario; sample.context...) # stochastic trajectory = solver(scenario; sample.context...) # dynamic

generate_parametric_anticipative_solver(::AbstractStochasticBenchmark{true}) -> callable

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

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

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

is_minimization_problem(_::AbstractBenchmark) -> Bool

Check if the benchmark is a minimization problem.

plot_instance(::AbstractBenchmark, instance; kwargs...)

Plot the instance object of the sample.

plot_solution(::AbstractBenchmark, sample::DataSample, [solution]; kwargs...)

Plot solution if given, else plot the target solution in the sample.

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} <: AbstractBenchmark

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{CTX, @NamedTuple{}, Vector{Float32}} where CTX<: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.

plot_data(
    bench::Argmax2DBenchmark,
    sample::DataSample;
    instance,
    θ,
    kwargs...
) -> Plots.Plot

Plot the data sample for the Argmax2DBenchmark.

struct ArgmaxBenchmark{E} <: AbstractBenchmark

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(
    bench::ArgmaxBenchmark
) -> typeof(DecisionFocusedLearningBenchmarks.Argmax.one_hot_argmax)

Return an argmax maximizer.

generate_sample(
    bench::ArgmaxBenchmark,
    rng::Random.AbstractRNG;
    noise_std
) -> DataSample{CTX, @NamedTuple{}, Matrix{Float32}} where CTX<: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 DynamicVehicleSchedulingBenchmark <: AbstractDynamicBenchmark{true}

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.

animate_epochs(
    data_samples::Vector{<:DataSample};
    filename,
    fps,
    figsize,
    margin,
    legend_margin_factor,
    titlefontsize,
    guidefontsize,
    legendfontsize,
    tickfontsize,
    show_axis_labels,
    show_cost_bar,
    show_colorbar,
    cost_bar_width,
    cost_bar_margin,
    cost_bar_color_palette,
    kwargs...
) -> Plots.Animation

Create an animated GIF showing the evolution of states and routes over epochs. Each frame shows the state and routes for one epoch.

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.

plot_epochs(
    data_samples::Vector{<:DataSample};
    plot_routes_flag,
    cols,
    figsize,
    margin,
    legend_margin_factor,
    titlefontsize,
    guidefontsize,
    legendfontsize,
    tickfontsize,
    show_axis_labels,
    show_colorbar,
    kwargs...
) -> Any

Plot multiple epochs side by side from a vector of DataSample objects. Each DataSample should contain an instance (DVSPState) and optionally y_true (routes). All subplots will use the same xlims and ylims to show the dynamics clearly.

plot_instance(
    instance::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance;
    kwargs...
) -> Plots.Plot

Plot the given static VSP instance.

plot_routes(
    state::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState,
    routes::BitMatrix;
    kwargs...
) -> Plots.Plot

Plot a given DVSPState with routes overlaid. This version accepts routes as a BitMatrix where entry (i,j) = true indicates an edge from location i to location j.

plot_routes(
    state::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState,
    routes::Vector{Vector{Int64}};
    reward,
    route_color,
    route_linewidth,
    route_alpha,
    kwargs...
) -> Plots.Plot

Plot a given DVSPState with routes overlaid, showing depot, customers, and vehicle routes. Routes should be provided as a vector of vectors, where each inner vector contains the indices of locations visited by that route (excluding the depot).

plot_state(
    state::DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState;
    customer_markersize,
    depot_markersize,
    alpha_depot,
    depot_color,
    depot_marker,
    must_dispatch_color,
    postponable_color,
    must_dispatch_marker,
    postponable_marker,
    show_axis_labels,
    markerstrokewidth,
    show_colorbar,
    kwargs...
) -> Plots.Plot

Plot a given DVSPState showing depot, must-dispatch customers, and postponable customers.

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_solution(
    b::DynamicVehicleSchedulingBenchmark,
    args...;
    kwargs...
) -> Tuple{Union{Float64, Vector{Float64}}, Vector}

Generate an anticipative solution for the dynamic vehicle scheduling benchmark. The solution is computed using the anticipative solver with the benchmark's feature configuration.

generate_anticipative_solver(
    _::DynamicVehicleSchedulingBenchmark
) -> DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.var"#156#157"{DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.var"#158#159"}

Return the anticipative solver for the dynamic vehicle scheduling benchmark. The callable takes a scenario and solver kwargs (including instance) and returns a training trajectory as a Vector{DataSample}.

generate_baseline_policies(
    _::DynamicVehicleSchedulingBenchmark
) -> Tuple{Policy{typeof(DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.lazy_policy)}, 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
) -> Tuple{Policy{typeof(DecisionFocusedLearningBenchmarks.DynamicAssortment.expert_policy)}, 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_sample(
    b::DynamicAssortmentBenchmark
) -> DataSample{CTX, @NamedTuple{}, Nothing, Nothing, Nothing} where CTX<:NamedTuple
generate_sample(
    b::DynamicAssortmentBenchmark,
    rng::Random.AbstractRNG
) -> DataSample{CTX, @NamedTuple{}, Nothing, Nothing, Nothing} where CTX<:NamedTuple

Outputs a data sample containing an Instance.

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 <: AbstractBenchmark

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

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

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

struct MaintenanceBenchmark <: AbstractDynamicBenchmark{true}

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
) -> Tuple{Policy{typeof(DecisionFocusedLearningBenchmarks.Maintenance.greedy_policy)}}

Returns two policies for the dynamic assortment 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 <: AbstractBenchmark

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

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.

struct RankingBenchmark{E} <: AbstractBenchmark

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{CTX, @NamedTuple{}, Matrix{Float32}} where CTX<: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} <: AbstractBenchmark

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

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

Generate a labeled instance for the subset selection problem.

struct StochasticVehicleSchedulingBenchmark <: AbstractBenchmark

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

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;
    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_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.

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

plot_instance(
    ::StochasticVehicleSchedulingBenchmark,
    sample::DataSample;
    kwargs...
) -> Plots.Plot

plot_solution(
    ::StochasticVehicleSchedulingBenchmark,
    sample::DataSample;
    kwargs...
) -> Plots.Plot

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.

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

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.

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_instance(
    benchmark::StochasticVehicleSchedulingBenchmark,
    rng::Random.AbstractRNG;
    store_city,
    kwargs...
) -> DataSample{CTX, @NamedTuple{}, Matrix{Float32}, Nothing, Nothing} where CTX<: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.

struct WarcraftBenchmark <: AbstractBenchmark

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

generate_dataset(::WarcraftBenchmark) -> Vector
generate_dataset(
    ::WarcraftBenchmark,
    dataset_size::Int64
) -> 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.

plot_data(
    ::WarcraftBenchmark,
    sample::DataSample;
    θ_true,
    θ_title,
    y_title,
    kwargs...
) -> Any

Plot the content of input DataSample as images. x as the initial image, θ as the weights, and y as the path.

The keyword argument θ_true is used to set the color range of the weights plot.

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.