cleanup warcraft benchmark

Author: BatyLeo

docs/src/tutorials/warcraft.jl

@@ -15,22 +15,22 @@ b = WarcraftBenchmark()
 # These benchmark objects behave as generators that can generate various needed elements in order to build an algorithm to tackle the problem.
 # First of all, all benchmarks are capable of generating datasets as needed, using the [`generate_dataset`](@ref) method.
 # This method takes as input the benchmark object for which the dataset is to be generated, and a second argument specifying the number of samples to generate:
-dataset = generate_dataset(b, 50)
+dataset = generate_dataset(b, 50);
 
-# We obtain a vector of [`DataSample`](@ref) object, which contains all needed data for the problem.
+# We obtain a vector of [`DataSample`](@ref) objects, containing all needed data for the problem.
 # Subdatasets can be created through regular slicing:
 train_dataset, test_dataset = dataset[1:45], dataset[46:50]
 
-# And getting an individual sample will return a NamedTuple with four keys: `features`, `instance`, `costs`, and `solution`:
+# And getting an individual sample will return a [`DataSample`](@ref) with four fields: `x`, `instance`, `θ`, and `y`:
 sample = test_dataset[1]
-# In the case the the Warcraft benchmark, `features` correspond to the input image:
+# `x` correspond to the input features, i.e. the input image (3D array) in the Warcraft benchmark case:
 x = sample.x
-# `costs` correspond to the true unknown terrain weights:
+# `θ` correspond to the true unknown terrain weights. They are negative because optimization is formulated as a maximization problem by convention:
 θ_true = sample.θ
-# `solution` correspond to the true shortest path:
+# `y` correspond to the optimal shortest path:
 y_true = sample.y
 # `instance` is not used in this benchmark, therefore set to nothing:
-sample.instance
+isnothing(sample.instance)
 
 # For some benchmarks, we provide the following plotting method [`plot_data`](@ref) to visualize the data:
 plot_data(b, sample)
@@ -85,4 +85,4 @@ final_gap = compute_gap(b, test_dataset, model, maximizer)
 #
 θ = model(x)
 y = maximizer(θ)
-plot_data(b, DataSample(; x, θ, y); θ_true=θ_true)
+plot_data(b, DataSample(; x, θ, y))

src/Warcraft/Warcraft.jl

@@ -15,55 +15,23 @@ using Random
 using SimpleWeightedGraphs
 using SparseArrays
 
-include("dataset.jl")
+include("utils.jl")
 
 """
 $TYPEDEF
+
+Benchmark for the Warcraft shortest path problem.
+Does not have any field.
 """
 struct WarcraftBenchmark <: AbstractBenchmark end
 
 """
 $TYPEDSIGNATURES
 
-Plot the image `im`, the weights `weights`, and the path `path` on the same Figure.
-"""
-function Utils.plot_data(
-    ::WarcraftBenchmark,
-    sample::DataSample;
-    θ_title="Weights",
-    y_title="Path",
-    θ_true=sample.θ,
-    kwargs...,
-)
-    (; x, y, θ) = sample
-    im = dropdims(x; dims=4)
-    img = convert_image_for_plot(im)
-    p1 = Plots.plot(
-        img; aspect_ratio=:equal, framestyle=:none, size=(300, 300), title="Terrain image"
-    )
-    p2 = Plots.heatmap(
-        abs.(θ);
-        yflip=true,
-        aspect_ratio=:equal,
-        framestyle=:none,
-        padding=(0.0, 0.0),
-        size=(300, 300),
-        legend=false,
-        title=θ_title,
-        clim=(minimum(θ_true), maximum(θ_true)),
-    )
-    p3 = Plots.plot(
-        Gray.(y .* 0.7);
-        aspect_ratio=:equal,
-        framestyle=:none,
-        size=(300, 300),
-        title=y_title,
-    )
-    return plot(p1, p2, p3; layout=(1, 3), size=(900, 300))
-end
+Downloads and decompresses the Warcraft dataset the first time it is called.
 
-"""
-$TYPEDSIGNATURES
+!!! warning
+    `dataset_size` is capped at 10000, i.e. the number of available samples in the dataset files.
 """
 function Utils.generate_dataset(::WarcraftBenchmark, dataset_size::Int=10)
     decompressed_path = datadep"warcraft/data"
@@ -72,6 +40,9 @@ end
 
 """
 $TYPEDSIGNATURES
+
+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.
 """
 function Utils.generate_maximizer(::WarcraftBenchmark; dijkstra=true)
     return dijkstra ? dijkstra_maximizer : bellman_maximizer
@@ -105,8 +76,47 @@ function Utils.generate_statistical_model(::WarcraftBenchmark)
     return model_embedding
 end
 
-function Utils.objective_value(::WarcraftBenchmark, θ̄::AbstractArray, y::AbstractArray)
-    return dot(-θ̄, y)
+"""
+$TYPEDSIGNATURES
+
+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.
+"""
+function Utils.plot_data(
+    ::WarcraftBenchmark,
+    sample::DataSample;
+    θ_true=sample.θ,
+    θ_title="Weights",
+    y_title="Path",
+    kwargs...,
+)
+    (; x, y, θ) = sample
+    im = dropdims(x; dims=4)
+    img = convert_image_for_plot(im)
+    p1 = Plots.plot(
+        img; aspect_ratio=:equal, framestyle=:none, size=(300, 300), title="Terrain image"
+    )
+    p2 = Plots.heatmap(
+        -θ;
+        yflip=true,
+        aspect_ratio=:equal,
+        framestyle=:none,
+        padding=(0.0, 0.0),
+        size=(300, 300),
+        legend=false,
+        title=θ_title,
+        clim=(minimum(-θ_true), maximum(-θ_true)),
+    )
+    p3 = Plots.plot(
+        Gray.(y .* 0.7);
+        aspect_ratio=:equal,
+        framestyle=:none,
+        size=(300, 300),
+        title=y_title,
+    )
+    return plot(p1, p2, p3; layout=(1, 3), size=(900, 300))
 end
 
 export WarcraftBenchmark

src/Warcraft/dataset.jl renamed to src/Warcraft/utils.jl

@@ -29,34 +29,20 @@ Create the dataset corresponding to the data located at `decompressed_path`, pos
 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.
 """
-function create_dataset(decompressed_path::String, nb_samples::Int=10000)
+function create_dataset(decompressed_path::String, nb_samples::Int)
+    N = min(nb_samples, 10000)
     terrain_images, terrain_labels, terrain_weights = read_dataset(
         decompressed_path, "train"
     )
     X = [
         reshape(terrain_images[:, :, :, i], (size(terrain_images[:, :, :, i])..., 1)) for
-        i in 1:nb_samples
+        i in 1:N
     ]
-    Y = [terrain_labels[:, :, i] for i in 1:nb_samples]
-    WG = [terrain_weights[:, :, i] for i in 1:nb_samples]
+    Y = [terrain_labels[:, :, i] for i in 1:N]
+    WG = [-terrain_weights[:, :, i] for i in 1:N]
     return [DataSample(; x, y, θ) for (x, y, θ) in zip(X, Y, WG)]
 end
 
-# """
-# $TYPEDSIGNATURES
-
-# Split a dataset contained in `X` into train and test datasets.
-# The proportion of the initial dataset kept in the train set is `train_percentage`.
-# """
-# function train_test_split(X::AbstractVector, train_percentage::Real=0.5)
-#     N = length(X)
-#     N_train = floor(Int, N * train_percentage)
-#     N_test = N - N_train
-#     train_ind, test_ind = 1:N_train, (N_train + 1):(N_train + N_test)
-#     X_train, X_test = X[train_ind], X[test_ind]
-#     return X_train, X_test
-# end
-
 """
 $TYPEDSIGNATURES
 
@@ -72,66 +58,6 @@ function convert_image_for_plot(image::Array{Float32,3})::Array{RGB{N0f8},2}
     return new_img
 end
 
-# """
-# $TYPEDSIGNATURES
-
-# Plot the image `im`, the weights `weights`, and the path `path` on the same Figure.
-# """
-# function plot_image_path(x, y; y_title="Path")
-#     im = dropdims(x; dims=4)
-#     img = convert_image_for_plot(im)
-#     p1 = Plots.plot(
-#         img; aspect_ratio=:equal, framestyle=:none, size=(300, 300), title="Terrain image"
-#     )
-#     p3 = Plots.plot(
-#         Gray.(y .* 0.7);
-#         aspect_ratio=:equal,
-#         framestyle=:none,
-#         size=(300, 300),
-#         title=y_title,
-#     )
-#     return plot(p1, p3; layout=(1, 2), size=(600, 300))
-# end
-
-# """
-# $TYPEDSIGNATURES
-
-# Plot the train and test losses, as well as the train and test gaps computed over epochs.
-# """
-# function plot_loss_and_gap(losses::Matrix{Float64}, gaps::Matrix{Float64}; filepath=nothing)
-#     nb_epochs = length(losses)
-#     p1 = plot(
-#         collect(1:nb_epochs),
-#         losses;
-#         title="Loss",
-#         xlabel="epochs",
-#         ylabel="loss",
-#         label=["train" "test"],
-#     )
-#     p2 = plot(
-#         collect(0:nb_epochs),
-#         gaps;
-#         title="Gap",
-#         xlabel="epochs",
-#         ylabel="ratio",
-#         label=["train" "test"],
-#     )
-#     pl = plot(p1, p2; layout=(1, 2))
-#     isnothing(filepath) || Plots.savefig(pl, filepath)
-#     return pl
-# end
-
-"""
-$TYPEDSIGNATURES
-"""
-function dijkstra_maximizer(θ::AbstractMatrix; kwargs...)
-    g = grid_graph(-θ)
-    p = dijkstra_shortest_paths(g, 1)
-    path = get_path(p.parents, 1, nv(g))
-    y = path_to_matrix(path, 12, 12)
-    return y
-end
-
 """
     grid_bellman_ford_warcraft(g, s, d, length_max)
 
@@ -184,10 +110,30 @@ end
 
 """
 $TYPEDSIGNATURES
+
+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.
 """
 function bellman_maximizer(θ::AbstractMatrix; kwargs...)
     g = grid_graph(-θ)
     path = grid_bellman_ford_warcraft(g, 1, nv(g))
     y = path_to_matrix(path, 12, 12)
     return y
 end
+
+"""
+$TYPEDSIGNATURES
+
+Computes the longest path in given grid graph weights by computing the shortest path in the graph with opposite weights.
+Using the Dijkstra algorithm.
+
+!!! warning
+    Only works on graph with positive weights, i.e. if `θ` only contains negative values.
+"""
+function dijkstra_maximizer(θ::AbstractMatrix; kwargs...)
+    g = grid_graph(-θ)
+    p = dijkstra_shortest_paths(g, 1)
+    path = get_path(p.parents, 1, nv(g))
+    y = path_to_matrix(path, 12, 12)
+    return y
+end