API Reference

abstract type AbstractBenchmark

Abstract type interface for benchmark problems.

The following methods are mandatory for benchmarks:

• generate_dataset or generate_sample
• generate_statistical_model
• generate_maximizer

The following methods are optional:

• plot_data
• objective_value
• compute_gap

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

Abstract type interface for dynamic benchmark problems. This type should be used for benchmarks that involve multi-stage stochastic optimization problems.

It follows the same interface as AbstractStochasticBenchmark, with the addition of the following methods: TODO

abstract type AbstractEnvironment

Abstract type for environments in decision-focused learning benchmarks.

abstract type AbstractStochasticBenchmark{exogenous} <: AbstractBenchmark

Abstract type interface for stochastic benchmark problems. This type should be used for benchmarks that involve single stage stochastic optimization problems.

It follows the same interface as AbstractBenchmark, with the addition of the following methods:

• TODO

struct DataSample{I, F<:Union{Nothing, AbstractArray}, S<:Union{Nothing, AbstractArray}, C<:Union{Nothing, AbstractArray}}

Data sample data structure.

Fields

• x::Union{Nothing, AbstractArray}: features

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

• y_true::Union{Nothing, AbstractArray}: target solution (optional)

• instance::Any: instance object (optional)

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(::AbstractBenchmark, dataset::Vector{<:DataSample}, statistical_model, maximizer) -> Float64

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

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

Default behaviour of compute_gap for a benchmark problem where features, solutions and costs are all defined.

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{Any, Any}

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;
    kwargs...
) -> Tuple{Any, Union{Vector{T} where T<:(DataSample{Nothing, F, S, Nothing} where {F<:Union{Nothing, AbstractArray}, S<:Union{Nothing, AbstractArray}}), Vector{T} where T<:(DataSample{I, F, S, Nothing} where {I<:DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.DVSPState, F<:Union{Nothing, AbstractArray}, S<: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{true}, instance, scenario; kwargs...)

generate_dataset(::AbstractBenchmark, dataset_size::Int; 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.

generate_environment(::AbstractDynamicBenchmark, instance, rng::AbstractRNG; kwargs...)

Initialize an environment for the given dynamic benchmark instance.

generate_environments(
    bench::AbstractDynamicBenchmark,
    dataset::AbstractArray{<:DataSample};
    seed,
    rng,
    kwargs...
) -> Any

Generate a vector of environments for the given dynamic benchmark and dataset.

generate_maximizer(::AbstractBenchmark; kwargs...)

Generates a maximizer function. Returns a callable f: (θ; kwargs...) -> y, where θ is a cost array and y is a solution.

generate_policies(::AbstractBenchmark) -> Vector{Policy}

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

Generate a single DataSample for given benchmark. This is a low-level function that is used by generate_dataset to create a dataset of samples. It is not mandatory to implement this method, but it is recommended for benchmarks that have a well-defined way to generate individual samples. An alternative is to directly implement generate_dataset to create a dataset without generating individual samples.

generate_scenario(::AbstractStochasticBenchmark{true}, instance; kwargs...)

generate_statistical_model(::AbstractBenchmark; kwargs...)

Initializes and return an untrained statistical model of the CO-ML pipeline. It's usually a Flux model, that takes a feature matrix x as input, and returns a cost array θ as output.

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) -> Union{Nothing, Int64}

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.

maximizer_kwargs(
    _::AbstractBenchmark,
    sample::DataSample
) -> NamedTuple{(:instance,), <:Tuple{Any}}

For benchmarks where there is an instance object, maximizer needs the instance object as a keyword argument.

maximizer_kwargs(
    _::AbstractBenchmark,
    sample::DataSample{Nothing, F, S, C}
) -> @NamedTuple{instance::Nothing}

For simple benchmarks where there is no instance object, maximizer does not need any keyword arguments.

neg_tensor(x)

Compute minus softplus element-wise on tensor x.

objective_value(
    _::AbstractBenchmark,
    θ::AbstractArray,
    y::AbstractArray
) -> Any

Default behaviour of objective_value.

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

Compute the objective value of given solution y.

objective_value(
    bench::AbstractBenchmark,
    sample::DataSample{I, 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.

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

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

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
) -> Argmax2DBenchmark{E, Vector{Int64}} where E<:(Flux.Dense{typeof(identity), Matrix{Float32}})

Custom constructor for Argmax2DBenchmark.

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

Maximizer for the Argmax2DBenchmark.

generate_sample(
    bench::Argmax2DBenchmark,
    rng::Random.AbstractRNG
) -> DataSample{_A, Vector{Float32}} where _A

Generate a sample for the Argmax2DBenchmark.

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

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
) -> ArgmaxBenchmark{E} where E<:(Flux.Chain{T} where T<:Tuple{Flux.Dense{typeof(identity), Matrix{Float32}}, 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{Nothing, Matrix{Float32}}

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
) -> Flux.Chain{T} where T<:Tuple{Flux.Dense{typeof(identity), Matrix{Float32}}, 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;
    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,
    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.

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.

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},
    epoch_indices::Vector{Int64};
    kwargs...
) -> Any

Plot multiple epochs side by side, optionally filtering to specific epoch indices.

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;
    customer_markersize,
    depot_markersize,
    alpha_depot,
    customer_color,
    depot_color,
    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{Int64};
    kwargs...
) -> Plots.Plot

Plot a given DVSPState with routes overlaid. This version accepts routes as a single vector where routes are separated by depot visits (index 1).

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

Plot a given DVSPState with routes overlaid, showing depot, requests, 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,
    must_dispatch_color,
    postponable_color,
    show_axis_labels,
    markerstrokewidth,
    kwargs...
) -> Plots.Plot

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

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;
    rounded,
    normalization
) -> DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling.StaticInstance

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.

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.

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_environment(
    ::DynamicAssortmentBenchmark,
    instance::DecisionFocusedLearningBenchmarks.DynamicAssortment.Instance,
    rng::Random.AbstractRNG;
    kwargs...
) -> DecisionFocusedLearningBenchmarks.DynamicAssortment.Environment{I, Random.MersenneTwister, Int64} where I<:DecisionFocusedLearningBenchmarks.DynamicAssortment.Instance

Creates an Environment from an Instance of the dynamic assortment benchmark. The seed of the environment is 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_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_sample(
    b::DynamicAssortmentBenchmark
) -> DataSample{I, Nothing, Nothing, Nothing} where I<:DecisionFocusedLearningBenchmarks.DynamicAssortment.Instance
generate_sample(
    b::DynamicAssortmentBenchmark,
    rng::Random.AbstractRNG
) -> DataSample{I, Nothing, Nothing, Nothing} where I<:DecisionFocusedLearningBenchmarks.DynamicAssortment.Instance

Outputs a data sample containing an Instance.

generate_statistical_model(
    b::DynamicAssortmentBenchmark;
    seed
) -> Flux.Chain{T} where T<:Tuple{Flux.Dense{typeof(identity), Matrix{Float32}}, Flux.Dense{typeof(identity), Matrix{Float32}}, typeof(vec)}

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}, Nothing}

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.

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
) -> DecisionFocusedLearningBenchmarks.FixedSizeShortestPath.var"#shortest_path_maximizer#8"{DecisionFocusedLearningBenchmarks.FixedSizeShortestPath.var"#shortest_path_maximizer#5#9"{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
) -> Flux.Chain{T} where T<:Tuple{Flux.Dense{typeof(identity), Matrix{Float32}}}

Initialize a linear model for bench using Flux.

generate_sample(
    bench::FixedSizeShortestPathBenchmark,
    rng::Random.AbstractRNG;
    type
) -> Union{DataSample{Nothing, Vector{Float32}, BitVector, Vector{Float32}}, DataSample{Nothing, Vector{Float32}, BitVector, Vector{Float64}}}

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

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#3"{Float32, Matrix{Float32}, Int64}

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

generate_statistical_model(
    bench::PortfolioOptimizationBenchmark
) -> Flux.Dense{typeof(identity), Matrix{Float32}}

Initialize a linear model for bench using Flux.

generate_sample(
    bench::PortfolioOptimizationBenchmark,
    rng::Random.AbstractRNG;
    type
) -> DataSample{Nothing, 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
) -> RankingBenchmark{E} where E<:(Flux.Chain{T} where T<:Tuple{Flux.Dense{typeof(identity), Matrix{Float32}}, 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{Nothing, Matrix{Float32}}

Generate a labeled sample for the ranking problem.

generate_statistical_model(
    bench::RankingBenchmark;
    seed
) -> Flux.Chain{T} where T<:Tuple{Flux.Dense{typeof(identity), Matrix{Float32}}, 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
) -> Flux.Dense{typeof(identity), Matrix{Float32}}

Initialize a linear model for bench using Flux.

generate_sample(
    bench::SubsetSelectionBenchmark,
    rng::Random.AbstractRNG
) -> DataSample{Nothing, Vector{Float32}}

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{<:DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance{DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City}};
    kwargs...
) -> Plots.Plot

plot_solution(
    ::StochasticVehicleSchedulingBenchmark,
    sample::DataSample{<:DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.Instance{DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling.City}};
    kwargs...
) -> Plots.Plot

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

generate_statistical_model(
    ::StochasticVehicleSchedulingBenchmark;
    seed
) -> Flux.Chain{T} where T<:Tuple{Flux.Dense{typeof(identity), Matrix{Float32}}, 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_sample(
    benchmark::StochasticVehicleSchedulingBenchmark,
    rng::Random.AbstractRNG;
    store_city,
    compute_solutions,
    algorithm,
    kwargs...
) -> DataSample{I, Matrix{Float32}, S, Nothing} where {I, S<:Union{Nothing, AbstractArray}}

Generate a sample for the given StochasticVehicleSchedulingBenchmark. If you want to not add label solutions in the sample, set compute_solutions=false. By default, they will be computed using column generation. Note that computing solutions can be time-consuming, especially for large instances. You can also use instead compact_mip or compact_linearized_mip as the algorithm to compute solutions. If you want to provide a custom algorithm to compute solutions, you can pass it as the algorithm keyword argument. If algorithm takes keyword arguments, you can pass them as well directly in kwargs.... If store_city=false, the coordinates and unnecessary information about instances will not be stored in the sample.

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.