bugfix + cleanup docstrings

Author: BatyLeo

docs/src/custom_benchmarks.md

@@ -9,9 +9,10 @@ problems to the benchmark suite or integrate their own domains.
 ## Type hierarchy
 
 ```
-AbstractStaticBenchmark
-└── AbstractStochasticBenchmark{exogenous}
-    └── AbstractDynamicBenchmark{exogenous}
+AbstractBenchmark
+├── AbstractStaticBenchmark
+├── AbstractStochasticBenchmark{exogenous}
+└── AbstractDynamicBenchmark{exogenous}
 ```
 
 | Type | Use case |
@@ -70,7 +71,7 @@ generate_maximizer(bench::MyBenchmark)
 
 ```julia
 generate_baseline_policies(bench::MyBenchmark) -> collection of callables
-is_minimization_problem(bench::MyBenchmark) -> Bool   # default: false (maximization)
+is_minimization_problem(bench::MyBenchmark) -> Bool   # default: true (minimization)
 objective_value(bench::MyBenchmark, sample::DataSample, y) -> Real
 compute_gap(bench::MyBenchmark, dataset, model, maximizer) -> Float64
 has_visualization(bench::MyBenchmark) -> Bool                            # default: false; return true when plot methods are implemented/available
@@ -80,7 +81,7 @@ plot_solution(bench::MyBenchmark, sample::DataSample; kwargs...)
 
 ---
 
-## `AbstractStochasticBenchmark{true}`: additional methods
+## `AbstractStochasticBenchmark{true}`
 
 For stochastic benchmarks with exogenous uncertainty, implement:
 
@@ -113,7 +114,7 @@ DataSample(; x=features, y=nothing,
 
 ---
 
-## `AbstractDynamicBenchmark`: additional methods
+## `AbstractDynamicBenchmark`
 
 Dynamic benchmarks extend stochastic ones with an environment-based rollout interface.
 

docs/src/using_benchmarks.md

@@ -150,7 +150,8 @@ dataset = generate_dataset(bench, 50; rng=rng)
 gap = compute_gap(bench, dataset, model, maximizer)
 ```
 
-# Objective value for a single decision
+Objective value for a single decision:
+
 ```julia
 obj = objective_value(bench, sample, y)
 ```

src/DynamicAssortment/DynamicAssortment.jl

@@ -78,17 +78,6 @@ include("policies.jl")
 """
 $TYPEDSIGNATURES
 
-Outputs a data sample containing an [`Instance`](@ref).
-"""
-function Utils.generate_sample(
-    b::DynamicAssortmentBenchmark, rng::AbstractRNG=MersenneTwister(0)
-)
-    return DataSample(; instance=Instance(b, rng))
-end
-
-"""
-$TYPEDSIGNATURES
-
 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.
 """

src/Utils/interface/abstract_benchmark.jl

@@ -13,8 +13,8 @@ Generate a single unlabeled [`DataSample`](@ref) (with `y=nothing`) for the benc
 function generate_instance(bench::AbstractBenchmark, rng::AbstractRNG; kwargs...)
     return error(
         "`generate_instance` is not implemented for $(typeof(bench)). " *
-        "Implement `generate_instance(::$(typeof(bench)), rng; kwargs...) -> DataSample` " *
-        "or override `generate_sample` directly.",
+        "Implement `generate_instance(::$(typeof(bench)), rng; kwargs...) -> DataSample`. " *
+        "For static benchmarks, you may also override `generate_sample` directly instead.",
     )
 end
 
@@ -48,9 +48,11 @@ end
     generate_baseline_policies(::AbstractBenchmark) -> NamedTuple or Tuple
 
 Return named baseline policies for the benchmark. Each policy is a callable.
+The calling convention matches the `target_policy` signature for the benchmark category:
 
-- For static/stochastic benchmarks: signature `(sample) -> DataSample`.
-- For dynamic benchmarks: signature `(env) -> Vector{DataSample}` (full trajectory).
+- **Static:** `(sample) -> DataSample`
+- **Stochastic:** `(ctx_sample, scenarios) -> Vector{DataSample}`
+- **Dynamic:** `(env) -> Vector{DataSample}` (full trajectory rollout)
 """
 function generate_baseline_policies end
 
@@ -79,9 +81,13 @@ function plot_solution end
 """
     objective_value(bench::AbstractBenchmark, sample::DataSample, y) -> Real
 
-Compute the objective value of given solution `y` for a specific benchmark.
-Must be implemented by each concrete benchmark type. For stochastic benchmarks,
-an additional `scenario` argument is required.
+Compute the objective value of solution `y` for the benchmark instance encoded in `sample`.
+Must be implemented by each concrete [`AbstractStaticBenchmark`](@ref).
+
+For stochastic benchmarks, implement the 4-arg form instead (see
+[`ExogenousStochasticBenchmark`](@ref)):
+
+    objective_value(bench, sample, y, scenario) -> Real
 """
 function objective_value end
 

src/Utils/interface/dynamic_benchmark.jl

@@ -2,9 +2,8 @@
 $TYPEDEF
 
 Abstract type interface for multi-stage stochastic (dynamic) benchmark problems.
-
-Extends [`AbstractStochasticBenchmark`](@ref). The `{exogenous}` parameter retains its
-meaning (whether uncertainty is independent of decisions).
+The `{exogenous}` parameter has the same meaning (whether uncertainty is independent
+of decisions) as in [`AbstractStochasticBenchmark`](@ref).
 
 # Primary entry point
 - [`generate_environments`](@ref)`(bench, n; rng)`: mandatory (or implement
@@ -35,14 +34,14 @@ is_endogenous(::AbstractDynamicBenchmark{exogenous}) where {exogenous} = !exogen
 """
 $TYPEDSIGNATURES
 
-Intercepts accidental calls to `generate_sample` on dynamic benchmarks and throws a
-descriptive error pointing at the correct entry point.
+Intercepts accidental calls to the default `compute_gap` on dynamic benchmarks and throws a
+descriptive error. Dynamic benchmarks do not have a generic single-sample gap computation;
+override `compute_gap` directly on the concrete type if needed.
 """
-function generate_sample(bench::AbstractDynamicBenchmark, rng; kwargs...)
+function compute_gap(bench::AbstractDynamicBenchmark, args...; kwargs...)
     return error(
-        "`generate_sample` is not supported for dynamic benchmarks ($(typeof(bench))). " *
-        "Use `generate_environments` and " *
-        "`generate_dataset(bench, environments; target_policy=...)` instead.",
+        "`compute_gap` is not supported for dynamic benchmarks ($(typeof(bench))). " *
+        "Override `compute_gap` on the concrete type with trajectory-based evaluation logic.",
     )
 end
 
@@ -92,12 +91,11 @@ 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.
 """
 function generate_dataset(
     bench::ExogenousDynamicBenchmark, environments::AbstractVector; target_policy, kwargs...
 )
+    isempty(environments) && return DataSample[]
     return reduce(vcat, (target_policy(env) for env in environments))
 end
 
@@ -114,7 +112,7 @@ function generate_dataset(
     bench::ExogenousDynamicBenchmark, n::Int; target_policy, seed=nothing, kwargs...
 )
     environments = generate_environments(bench, n; seed)
-    return generate_dataset(bench, environments; target_policy, seed, kwargs...)
+    return generate_dataset(bench, environments; target_policy, kwargs...)
 end
 
 """

src/Utils/interface/static_benchmark.jl

@@ -21,10 +21,12 @@ Also implement:
 
 # Optional methods (defaults provided)
 - [`is_minimization_problem`](@ref): defaults to `true`
-- [`objective_value`](@ref): defaults to `dot(θ, y)`
 - [`compute_gap`](@ref): default implementation provided; override for custom evaluation
 - [`has_visualization`](@ref): defaults to `false`
 
+# Mandatory methods (no default)
+- [`objective_value`](@ref)`(bench, sample, y)`: must be implemented by every static benchmark
+
 # Optional methods (no default, require `Plots` to be loaded)
 - [`plot_instance`](@ref), [`plot_solution`](@ref)
 - [`generate_baseline_policies`](@ref)

src/Utils/interface/stochastic_benchmark.jl

@@ -71,8 +71,9 @@ function generate_scenario end
 
 Enrich `instance_sample` with observable context drawn from `rng`.
 Returns a new `DataSample` extending the instance: `.x` is the final ML feature vector
-(possibly augmented with context features) and `.extra` holds any latent context fields
-needed by [`generate_scenario`](@ref).
+(possibly augmented with context features). Any latent fields needed by
+[`generate_scenario`](@ref) must go into `.context` (they are spread as kwargs via
+`ctx.context...`), not into `.extra`.
 
 **Default**: returns `instance_sample` unchanged — no context augmentation.
 Non-contextual benchmarks (e.g. SVS) use this default.
@@ -111,6 +112,18 @@ Returns `(env; reset_env=true, kwargs...) -> Vector{DataSample}`, a full traject
 """
 function generate_anticipative_solver end
 
+"""
+    objective_value(::ExogenousStochasticBenchmark, sample::DataSample, y, scenario) -> Real
+
+Compute the objective value of solution `y` for a given `scenario`.
+Must be implemented by each concrete [`ExogenousStochasticBenchmark`](@ref).
+
+This is the primary evaluation hook for stochastic benchmarks. The 2-arg fallback
+`objective_value(bench, sample, y)` dispatches here using the scenario stored in
+`sample.extra.scenario` (or averages over `sample.extra.scenarios`).
+"""
+function objective_value end
+
 """
     generate_parametric_anticipative_solver(::ExogenousStochasticBenchmark) -> callable
 
@@ -216,6 +229,7 @@ function generate_dataset(
     rng=MersenneTwister(seed),
     kwargs...,
 )
+    nb_instances == 0 && return DataSample[]
     return reduce(
         vcat,
         (
@@ -275,7 +289,7 @@ function generate_sample(
         generate_scenario(inner, rng; ctx.context...) for _ in 1:(saa.nb_scenarios)
     ]
     if isnothing(target_policy)
-        return [DataSample(; x=ctx.x, ctx.context..., extra=(; ctx.extra..., scenarios))]
+        return [DataSample(; x=ctx.x, θ=ctx.θ, ctx.context..., extra=(; ctx.extra..., scenarios))]
     else
         return target_policy(ctx, scenarios)
     end
@@ -300,8 +314,10 @@ function generate_dataset(
     rng=MersenneTwister(seed),
     kwargs...,
 )
+    nb_instances == 0 && return DataSample[]
     return reduce(
-        vcat, (generate_sample(saa, rng; target_policy, kwargs...) for _ in 1:nb_instances)
+        vcat,
+        (generate_sample(saa, rng; target_policy, kwargs...) for _ in 1:nb_instances),
     )
 end
 

test/dynamic_assortment.jl

@@ -340,10 +340,6 @@ end
     # Test maximizer generation
     maximizer = generate_maximizer(b)
 
-    # Test integration with sample data
-    sample = generate_sample(b, MersenneTwister(42))
-    @test hasfield(typeof(sample), :context)
-
     environments = generate_environments(b, 3; seed=42)
 
     # Evaluate policy to get data samples