update docs and tutorial

Author: BatyLeo

docs/Project.toml

@@ -1,3 +1,7 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Flux = "587475ba-b771-5e3f-ad9e-33799f191a9c"
+InferOpt = "4846b161-c94e-4150-8dac-c7ae193c601f"
 InferOptBenchmarks = "2fbe496a-299b-4c81-bab5-c44dfc55cf20"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"

docs/make.jl

@@ -1,23 +1,37 @@
 using Documenter
 using InferOptBenchmarks
+using Literate
 
 cp(joinpath(@__DIR__, "..", "README.md"), joinpath(@__DIR__, "src", "index.md"); force=true)
 
+md_dir = joinpath(@__DIR__, "src")
+tutorial_dir = joinpath(@__DIR__, "src", "tutorials")
+tutorial_files = readdir(tutorial_dir)
+md_tutorial_files = [split(file, ".")[1] * ".md" for file in tutorial_files]
+
+for file in tutorial_files
+    filepath = joinpath(tutorial_dir, file)
+    Literate.markdown(filepath, md_dir; documenter=true, execute=false)
+end
+
 makedocs(;
     modules=[InferOptBenchmarks, InferOptBenchmarks.Warcraft],
     authors="Members of JuliaDecisionFocusedLearning",
     sitename="InferOptBenchmarks.jl",
     format=Documenter.HTML(),
     pages=[
-        "Home" => "index.md",  #
-        "API reference" => [
-            "interface.md",
-            "decision_focused.md",
-            "warcraft.md",  #
-        ],
+        "Home" => "index.md",
+        "Tutorials" => md_tutorial_files,
+        "API reference" =>
+            ["api/interface.md", "api/decision_focused.md", "api/warcraft.md"],
     ],
 )
 
+for file in md_tutorial_files
+    filepath = joinpath(md_dir, file)
+    rm(filepath)
+end
+
 deploydocs(;
     repo="github.com/JuliaDecisionFocusedLearning/InferOptBenchmarks.jl", devbranch="main"
 )

docs/src/decision_focused.md renamed to docs/src/api/decision_focused.md

@@ -0,0 +1,37 @@
+# # Path-finding on image maps
+
+using InferOptBenchmarks
+using InferOpt
+using Flux
+using Plots
+
+b = WarcraftBenchmark()
+
+dataset = generate_dataset(b, 50)
+model = generate_statistical_model(b)
+maximizer = generate_maximizer(b)
+
+train_dataset, test_dataset = dataset[1:45], dataset[46:50]
+X_train = train_dataset.features
+Y_train = train_dataset.solutions
+
+perturbed_maximizer = PerturbedMultiplicative(maximizer; ε=0.2, nb_samples=100)
+loss = FenchelYoungLoss(perturbed_maximizer)
+
+starting_gap = compute_gap(b, test_dataset, model, maximizer)
+
+opt_state = Flux.setup(Adam(1e-3), model)
+loss_history = Float64[]
+for epoch in 1:50
+    val, grads = Flux.withgradient(model) do m
+        sum(loss(m(x), y) for (x, y) in zip(X_train, Y_train)) / length(train_dataset)
+    end
+    Flux.update!(opt_state, model, grads[1])
+    push!(loss_history, val)
+end
+
+plot(loss_history; xlabel="Epoch", ylabel="Loss", title="Training loss")
+
+#
+
+final_gap = compute_gap(b, test_dataset, model, maximizer)

docs/src/interface.md renamed to docs/src/api/interface.md

@@ -42,84 +42,84 @@ function create_dataset(decompressed_path::String, nb_samples::Int=10000)
     return InferOptDataset(; features=X, solutions=Y, costs=WG)
 end
 
-"""
-$TYPEDSIGNATURES
+# """
+# $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
+# 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
+# """
+# $TYPEDSIGNATURES
 
-Convert `image` to the proper data format to enable plots in Julia.
-"""
-function convert_image_for_plot(image::Array{Float32,3})::Array{RGB{N0f8},2}
-    new_img = Array{RGB{N0f8},2}(undef, size(image)[1], size(image)[2])
-    for i in 1:size(image)[1]
-        for j in 1:size(image)[2]
-            new_img[i, j] = RGB{N0f8}(image[i, j, 1], image[i, j, 2], image[i, j, 3])
-        end
-    end
-    return new_img
-end
+# Convert `image` to the proper data format to enable plots in Julia.
+# """
+# function convert_image_for_plot(image::Array{Float32,3})::Array{RGB{N0f8},2}
+#     new_img = Array{RGB{N0f8},2}(undef, size(image)[1], size(image)[2])
+#     for i in 1:size(image)[1]
+#         for j in 1:size(image)[2]
+#             new_img[i, j] = RGB{N0f8}(image[i, j, 1], image[i, j, 2], image[i, j, 3])
+#         end
+#     end
+#     return new_img
+# end
 
-"""
-$TYPEDSIGNATURES
+# """
+# $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
+# 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
+# """
+# $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
+# 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

docs/src/warcraft.md renamed to docs/src/api/warcraft.md

@@ -17,38 +17,3 @@ end
     using Documenter
     Documenter.doctest(InferOptBenchmarks)
 end
-
-# @testset verbose = true "InferOptBenchmarks" begin
-#     @testset verbose = true "Formalities" begin
-#         @testset "Aqua" begin
-#             Aqua.test_all(
-#                 InferOptBenchmarks; ambiguities=false, deps_compat=(check_extras = false)
-#             )
-#         end
-#         @testset "JET" begin
-#             JET.test_package(InferOptBenchmarks; target_defined_modules=true)
-#         end
-#         @testset "JuliaFormatter" begin
-#             @test JuliaFormatter.format(InferOptBenchmarks; verbose=false, overwrite=false)
-#         end
-#         @testset "Documenter" begin
-#             Documenter.doctest(InferOptBenchmarks)
-#         end
-#     end
-
-#     @testset "Warcraft" begin
-#         include("WarcraftTest/WarcraftTest.jl")
-#     end
-
-#     @testset "Shortest paths" begin
-#         include("FixedSizeShortestPathTest/FixedSizeShortestPathTest.jl")
-#     end
-
-#     @testset "Portfolio Optimization" begin
-#         include("PortfolioOptimizationTest/PortfolioOptimizationTest.jl")
-#     end
-
-#     @testset "Subset Selection" begin
-#         include("SubsetSelectionTest/SubsetSelectionTest.jl")
-#     end
-# end

docs/src/tutorials/warcraft.jl

@@ -1,36 +1,36 @@
-# @testitem "Portfolio Optimization" begin
-#     using InferOptBenchmarks
-#     using InferOpt
-#     using Flux
-#     using Zygote
-
-#     b = PortfolioOptimizationBenchmark()
-
-#     dataset = generate_dataset(b, 100)
-#     model = generate_statistical_model(b)
-#     maximizer = generate_maximizer(b)
-
-#     train_dataset, test_dataset = dataset[1:50], dataset[50:100]
-#     X_train = train_dataset.features
-#     Y_train = train_dataset.solutions
-
-#     perturbed_maximizer = PerturbedAdditive(maximizer; ε=0.1, nb_samples=100)
-#     loss = FenchelYoungLoss(perturbed_maximizer)
-
-#     starting_gap = compute_gap(b, test_dataset, model, maximizer)
-
-#     opt_state = Flux.setup(Adam(), model)
-#     loss_history = Float64[]
-#     for epoch in 1:50
-#         val, grads = Flux.withgradient(model) do m
-#             sum(loss(m(x), y) for (x, y) in zip(X_train, Y_train)) / length(train_dataset)
-#         end
-#         Flux.update!(opt_state, model, grads[1])
-#         push!(loss_history, val)
-#     end
-
-#     final_gap = compute_gap(b, test_dataset, model, maximizer)
-
-#     @test loss_history[end] < loss_history[1]
-#     @test final_gap < starting_gap
-# end
+@testitem "Portfolio Optimization" begin
+    using InferOptBenchmarks
+    using InferOpt
+    using Flux
+    using Zygote
+
+    b = PortfolioOptimizationBenchmark()
+
+    dataset = generate_dataset(b, 100)
+    model = generate_statistical_model(b)
+    maximizer = generate_maximizer(b)
+
+    train_dataset, test_dataset = dataset[1:50], dataset[50:100]
+    X_train = train_dataset.features
+    Y_train = train_dataset.solutions
+
+    perturbed_maximizer = PerturbedAdditive(maximizer; ε=0.1, nb_samples=1)
+    loss = FenchelYoungLoss(perturbed_maximizer)
+
+    starting_gap = compute_gap(b, test_dataset, model, maximizer)
+
+    opt_state = Flux.setup(Adam(), model)
+    loss_history = Float64[]
+    for epoch in 1:50
+        val, grads = Flux.withgradient(model) do m
+            sum(loss(m(x), y) for (x, y) in zip(X_train, Y_train)) / length(train_dataset)
+        end
+        Flux.update!(opt_state, model, grads[1])
+        push!(loss_history, val)
+    end
+
+    final_gap = compute_gap(b, test_dataset, model, maximizer)
+
+    @test loss_history[end] < loss_history[1]
+    @test final_gap < starting_gap / 10
+end