refactor!: remove scenario lists from public API

Author: gdalle

DifferentiationInterface/CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- New Arxiv preprint for citation (#795)
+- New Arxiv preprint for citation ([#795])
 
 ## [0.6.54] - 2025-05-11
 

DifferentiationInterface/test/testutils.jl

@@ -1,7 +1,17 @@
 using ADTypes
+using DifferentiationInterfaceTest
 using SparseConnectivityTracer
 using SparseMatrixColorings
 
+using DifferentiationInterfaceTest:
+    default_scenarios,
+    sparse_scenarios,
+    complex_scenarios,
+    complex_sparse_scenarios,
+    static_scenarios,
+    component_scenarios,
+    gpu_scenarios
+
 function MyAutoSparse(backend::AbstractADType)
     return AutoSparse(
         backend;

DifferentiationInterfaceTest/CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Specify preparation arguments in DIT Scenario ([#786])
 
+### Removed
+
+- Remove scenario lists from public API ([#796])
+
 ## [0.9.6] - 2025-03-28
 
 ### Added
@@ -22,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [unreleased]: https://github.com/JuliaDiff/DifferentiationInterface.jl/compare/DifferentiationInterfaceTest-v0.9.6...main
 [0.9.6]: https://github.com/JuliaDiff/DifferentiationInterface.jl/compare/DifferentiationInterfaceTest-v0.9.5...DifferentiationInterfaceTest-v0.9.6
 
+[#796]: https://github.com/JuliaDiff/DifferentiationInterface.jl/pull/796
 [#786]: https://github.com/JuliaDiff/DifferentiationInterface.jl/pull/786
 [#749]: https://github.com/JuliaDiff/DifferentiationInterface.jl/pull/749
 [#748]: https://github.com/JuliaDiff/DifferentiationInterface.jl/pull/748

DifferentiationInterfaceTest/README.md

@@ -22,12 +22,11 @@ Make it easy to know, for a given function:
 
 ## Features
 
-- Predefined or custom test scenarios
+- Definition of custom test scenarios
 - Correctness tests
 - Type stability tests
 - Count calls to the function
 - Benchmark runtime and allocations
-- Scenarios with weird array types (GPU, static) in package extensions
 
 ## Installation
 

DifferentiationInterfaceTest/docs/src/api.md

@@ -15,30 +15,16 @@ DifferentiationInterfaceTest
 Scenario
 test_differentiation
 benchmark_differentiation
-FIRST_ORDER
-SECOND_ORDER
 ```
 
 ## Utilities
 
 ```@docs
+FIRST_ORDER
+SECOND_ORDER
 DifferentiationInterfaceTest.DifferentiationBenchmarkDataRow
 ```
 
-## Pre-made scenario lists
-
-The precise contents of the scenario lists are not part of the API, only their existence.
-
-```@docs
-default_scenarios
-sparse_scenarios
-component_scenarios
-gpu_scenarios
-static_scenarios
-complex_scenarios
-complex_sparse_scenarios
-```
-
 ## Internals
 
 This is not part of the public API.

DifferentiationInterfaceTest/docs/src/tutorial.md

@@ -27,13 +27,14 @@ Of course we know the true gradient mapping:
 ∇f(x::AbstractArray) = cos.(x)
 ```
 
-DifferentiationInterfaceTest.jl relies with so-called "scenarios", in which you encapsulate the information needed for your test:
+DifferentiationInterfaceTest.jl relies with so-called [`Scenario`](@ref)s, in which you encapsulate the information needed for your test:
 
-- the operator category (`:gradient`)
+- the operator category (here `:gradient`)
 - the behavior of the operator (either `:in` or `:out` of place)
 - the function `f`
-- the input `x` of the function `f`
-- the reference first-order result `res1` of the operator
+- the input `x` of the function `f` (and possible tangents or contexts)
+- the reference first-order result `res1` (and possible second-order result `res2`) of the operator
+- the arguments `prep_args` passed during preparation
 
 ```@example tuto
 xv = rand(Float32, 3)
@@ -69,4 +70,4 @@ This is made easy by the [`benchmark_differentiation`](@ref) function, whose syn
 df = benchmark_differentiation(backends, scenarios);
 ```
 
-The resulting object is a `DataFrame` from [DataFrames.jl](https://github.com/JuliaData/DataFrames.jl), whose columns correspond to the fields of [`DifferentiationBenchmarkDataRow`](@ref):
+The resulting object is a `DataFrame` from [DataFrames.jl](https://github.com/JuliaData/DataFrames.jl), whose columns correspond to the fields of [`DifferentiationBenchmarkDataRow`](@ref).

DifferentiationInterfaceTest/src/DifferentiationInterfaceTest.jl

@@ -136,13 +136,7 @@ include("test_differentiation.jl")
 
 export FIRST_ORDER, SECOND_ORDER
 export Scenario
-export default_scenarios, sparse_scenarios
-export complex_scenarios, complex_sparse_scenarios
 export test_differentiation, benchmark_differentiation
 export DifferentiationBenchmarkDataRow
-# extensions
-export static_scenarios
-export component_scenarios
-export gpu_scenarios
 
 end

DifferentiationInterfaceTest/src/scenarios/scenario.jl

@@ -13,8 +13,21 @@ This generic type should never be used directly: use the specific constructor co
 
 # Constructors
 
-    Scenario{op,pl_op}(f, x, [t], contexts...; res1, res2, name)
-    Scenario{op,pl_op}(f!, y, x, [t,] contexts...; res1, res2, name)
+    Scenario{op,pl_op}(
+        f, x, [t], contexts...;
+        prep_args, res1, res2, name
+    )
+
+    Scenario{op,pl_op}(
+        f!, y, x, [t,] contexts...;
+        prep_args, res1, res2, name
+    )
+
+Default values:
+
+- `prep_args = ` the result of `zero` applied to each execution argument
+- `res1 = res2 = nothing`
+- `name = nothing`
 
 # Fields
 

DifferentiationInterfaceTest/test/runtests.jl

@@ -5,6 +5,15 @@ using Pkg
 using SparseConnectivityTracer
 using Test
 
+using DifferentiationInterfaceTest:
+    default_scenarios,
+    sparse_scenarios,
+    complex_scenarios,
+    complex_sparse_scenarios,
+    static_scenarios,
+    component_scenarios,
+    gpu_scenarios
+
 GROUP = get(ENV, "JULIA_DIT_TEST_GROUP", "All")
 
 ## Main tests