update docstrings

Author: BatyLeo

src/Argmax/Argmax.jl

@@ -62,6 +62,10 @@ end
 
 """
 $TYPEDSIGNATURES
+
+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.
 """
 function Utils.generate_sample(
     bench::ArgmaxBenchmark, rng::AbstractRNG; noise_std::Float32=0.0f0
@@ -73,28 +77,6 @@ function Utils.generate_sample(
     return DataSample(; x=features, θ_true=costs, y_true=noisy_solution)
 end
 
-# """
-# $TYPEDSIGNATURES
-
-# Generate a dataset of labeled instances for the argmax problem.
-# """
-# function Utils.generate_dataset(
-#     bench::ArgmaxBenchmark, dataset_size::Int; noise_std=0.0, kwargs...
-# )
-#     return Utils.generate_dataset(bench, dataset_size; noise_std=noise_std, kwargs...)
-#     # (; instance_dim, nb_features, encoder) = bench
-#     # rng = MersenneTwister(seed)
-#     # features = [randn(rng, Float32, nb_features, instance_dim) for _ in 1:dataset_size]
-#     # costs = encoder.(features)
-#     # noisy_solutions = [
-#     #     one_hot_argmax(θ + noise_std * randn(rng, Float32, instance_dim)) for θ in costs
-#     # ]
-#     # return [
-#     #     DataSample(; x, θ_true, y_true) for
-#     #     (x, θ_true, y_true) in zip(features, costs, noisy_solutions)
-#     # ]
-# end
-
 """
 $TYPEDSIGNATURES
 

src/FixedSizeShortestPath/FixedSizeShortestPath.jl

@@ -103,6 +103,11 @@ function Utils.generate_maximizer(bench::FixedSizeShortestPathBenchmark; use_dij
     return shortest_path_maximizer
 end
 
+"""
+$TYPEDSIGNATURES
+
+Generate a labeled sample for the fixed size shortest path benchmark.
+"""
 function Utils.generate_sample(
     bench::FixedSizeShortestPathBenchmark, rng::AbstractRNG; type::Type=Float32
 )

src/PortfolioOptimization/PortfolioOptimization.jl

@@ -82,6 +82,11 @@ function Utils.generate_maximizer(bench::PortfolioOptimizationBenchmark)
     return portfolio_maximizer
 end
 
+"""
+$TYPEDSIGNATURES
+
+Generate a labeled sample for the portfolio optimization problem.
+"""
 function Utils.generate_sample(
     bench::PortfolioOptimizationBenchmark, rng::AbstractRNG; type::Type=Float32
 )

src/StochasticVehicleScheduling/StochasticVehicleScheduling.jl

@@ -94,7 +94,7 @@ function Utils.generate_sample(
     instance = Instance(; nb_tasks, nb_scenarios, rng, store_city)
     x = get_features(instance)
     y_true = if compute_solutions
-        algorithm(instance; kwargs...).value  # TODO: modify algorithms to directly return the solution
+        algorithm(instance; kwargs...)
     else
         nothing
     end

src/StochasticVehicleScheduling/solution/algorithms/column_generation.jl

@@ -189,5 +189,5 @@ function column_generation_algorithm(
     end
 
     col_solution = solution_from_paths(sol, instance)
-    return col_solution
+    return col_solution.value
 end

src/StochasticVehicleScheduling/solution/algorithms/deterministic_mip.jl

@@ -41,5 +41,5 @@ function deterministic_mip(instance::Instance; model_builder=highs_model, silent
     solution = value.(y)
 
     sol = solution_from_JuMP_array(solution, graph)
-    return sol
+    return sol.value
 end

src/StochasticVehicleScheduling/solution/algorithms/local_search.jl

@@ -153,5 +153,5 @@ Very simple heuristic, using [`local_search`](@ref)
 function local_search(instance::Instance; num_iterations=1000)
     _, initial_solution = solve_deterministic_VSP(instance)
     sol, _, _, _ = _local_search(initial_solution, instance; nb_it=num_iterations)
-    return sol
+    return sol.value
 end

src/StochasticVehicleScheduling/solution/algorithms/mip.jl

@@ -78,7 +78,7 @@ function compact_linearized_mip(
     solution = value.(y)
 
     sol = solution_from_JuMP_array(solution, graph)
-    return sol
+    return sol.value
 end
 
 """
@@ -149,5 +149,5 @@ function compact_mip(
     solution = value.(y)
 
     sol = solution_from_JuMP_array(solution, graph)
-    return sol
+    return sol.value
 end

src/Utils/interface.jl

@@ -1,10 +1,10 @@
 """
 $TYPEDEF
 
-Abstract type interface for a benchmark problem.
+Abstract type interface for benchmark problems.
 
 The following methods are mandatory for benchmarks:
-- [`generate_dataset`](@ref)
+- [`generate_dataset`](@ref) or [`generate_sample`](@ref)
 - [`generate_statistical_model`](@ref)
 - [`generate_maximizer`](@ref)
 
@@ -17,27 +17,45 @@ abstract type AbstractBenchmark end
 
 """
 $TYPEDEF
+
+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`](@ref), with the addition of the following methods:
+TODO
 """
 abstract type AbstractStochasticBenchmark <: AbstractBenchmark end
 
 """
 $TYPEDEF
+
+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`](@ref), with the addition of the following methods:
+TODO
 """
 abstract type AbstractDynamicBenchmark <: AbstractStochasticBenchmark end
 
 """
-    generate_sample(::AbstractBenchmark, rng::AbstractRNG; kwargs...)
+    generate_sample(::AbstractBenchmark, rng::AbstractRNG; kwargs...) -> DataSample
 
-Do not always exist, interface to make [`generate_dataset`](@ref) work.
-Either implement this or generate_dataset.
+Generate a single [`DataSample`](@ref) for given benchmark.
+This is a low-level function that is used by [`generate_dataset`](@ref) 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`](@ref) to create a dataset
+without generating individual samples.
 """
 function generate_sample end
 
 """
     generate_dataset(::AbstractBenchmark, dataset_size::Int; kwargs...) -> Vector{<:DataSample}
 
-Generate a `Vector` of [`DataSample`](@ref)  of length `dataset_size` for given benchmark.
+Generate a `Vector` of [`DataSample`](@ref) of length `dataset_size` for given benchmark.
 Content of the dataset can be visualized using [`plot_data`](@ref), when it applies.
+
+By default, it uses [`generate_sample`](@ref) to create each sample in the dataset, and passes any keyword arguments to it.
 """
 function generate_dataset(
     bench::AbstractBenchmark,